feat: Introduce StacError and StacErrorWidget for enhanced error handling

[divyanshub024]

Description

• Add StacError class to encapsulate details about parsing and runtime errors, including type, original JSON, and stack trace.
• Implement StacErrorWidget to display structured error information, providing context and troubleshooting tips for developers.
• Update StacService to utilize StacError for error reporting and display custom error widgets when parsing fails.
• Enhance error handling in JSON parsing and action execution with detailed logging and optional error widgets.

Related Issues

Closes #

Type of Change

• New feature (non-breaking change which adds functionality)
• Bug fix (non-breaking change which fixes an issue)
• Breaking change (fix or feature that would cause existing functionality to change)
• Code refactor
• Build configuration change
• Documentation
• Chore

Summary by CodeRabbit

• New Features

  • Configurable error handling: toggle visible error panels, enable/disable stack-trace logging, and supply a custom error widget.
  • Built-in error panel UI for parsing/runtime issues with expandable details and troubleshooting tips (shown in debug).
  • Improved validation and clearer error reporting across parsing, actions, and loading.

• Refactor

  • Centralized error logging and rendering for a more consistent experience.

• Revert

  • Removed the custom outline input border component; use standard alternatives or provide your own.

[coderabbitai]

Walkthrough

Adds configurable error handling and UI: introduces StacError model and StacErrorWidget, a StacErrorWidgetBuilder typedef, and new initialization flags (showErrorWidgets, logStackTraces, errorWidgetBuilder) propagated from Stac to StacService; centralizes error logging/building. Removes StacOutlineInputBorder implementation.

Changes

Cohort / File(s)	Summary of changes
Framework API & initialization packages/stac/lib/src/framework/stac.dart, packages/stac/lib/src/framework/stac_service.dart	Adds StacErrorWidgetBuilder typedef; extends Stac constructor and initialize with showErrorWidgets, logStackTraces, errorWidgetBuilder; wires options to StacService.initialize. StacService stores options, adds _logError and _buildErrorWidget, and uses them across parsing, action, and load flows.
Error model & UI packages/stac/lib/src/framework/stac_error.dart	Adds public StacError data class and StacErrorWidget (expandable, styled error panel with JSON view and heuristic troubleshooting tips).
UI component removal packages/stac/lib/src/framework/ui/stac_outline_input_border.dart	Removes the StacOutlineInputBorder class and its custom painting/path logic (file deleted).

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor App
  participant Stac
  participant StacService
  participant Logger as _logError
  participant Builder as _buildErrorWidget

  App->>Stac: initialize(showErrorWidgets, logStackTraces, errorWidgetBuilder)
  Stac->>StacService: initialize(..., showErrorWidgets, logStackTraces, errorWidgetBuilder)

  rect rgba(200,230,255,0.25)
    note over StacService: parsing / action / loading flows
    App->>StacService: fromJson / fromStacWidget / load(...)
    alt success
      StacService-->>App: widget/result
    else error
      StacService->>Logger: _logError(details[, stackTrace])
      alt showErrorWidgets AND debug
        StacService->>Builder: _buildErrorWidget(details)
        Builder-->>StacService: StacErrorWidget (custom or default)
        StacService-->>App: Error widget
      else
        StacService-->>App: null / fallback
      end
    end
  end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• refactor: Remove unused files #356 — Removes parser/types referencing StacOutlineInputBorder, directly related to this PR’s deletion of that border implementation.

Suggested reviewers

• Potatomonsta

Poem

I nibble at the stack and trace,
A tidy widget finds its place.
Expand the hints where errors dwell,
Old borders gone — the UI’s well.
Hops of code, a quieter race. 🐇

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title concisely and specifically highlights the main change by introducing the StacError class and StacErrorWidget for enhanced error handling, making the purpose of the PR clear.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch dv/error-handling

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 30daaa9 and 3a18dd1.

📒 Files selected for processing (3)

• packages/stac/lib/src/framework/stac.dart (3 hunks)
• packages/stac/lib/src/framework/stac_error.dart (1 hunks)
• packages/stac/lib/src/framework/stac_service.dart (8 hunks)

🔇 Additional comments (8)

packages/stac/lib/src/framework/stac_error.dart (2)

1-94: Well-structured error model with comprehensive documentation.

The StacError class provides a clean API with appropriate nullable fields and thorough documentation explaining when each field is null. Good use of const constructor and immutable design.

---

402-446: Effective error categorization heuristics.

The troubleshooting tips use sensible pattern matching on error messages and types to provide contextual guidance. The fallback to general tips with a documentation link is a good practice.

packages/stac/lib/src/framework/stac.dart (2)

20-37: Well-documented typedef with clear usage example.

The StacErrorWidgetBuilder typedef is clearly documented with a practical example showing how to provide custom error UI. Good API design for extensibility.

---

51-71: Clean parameter propagation to StacService.

The new error handling parameters (showErrorWidgets, logStackTraces, errorWidgetBuilder) are properly threaded through to StacService.initialize with sensible defaults.

packages/stac/lib/src/framework/stac_service.dart (4)

176-244: Robust error handling with structured validation.

The updated fromJson method demonstrates solid defensive programming:

• Validates JSON is non-null and has required type field
• Type-checks the type value before use
• Provides debug-time error widgets with full context
• Centralizes error logging via _logError

This pattern prevents cryptic errors and aids debugging.

---

453-493: Well-designed error utilities for consistency.

The _logError and _buildErrorWidget helpers provide excellent centralization:

• _logError formats errors consistently with category, type, and conditional stack traces
• _buildErrorWidget respects custom builders while providing a sensible default
• Both helpers enable consistent error handling across the codebase

---

155-174: Clean integration of error handling configuration.

The initialize method cleanly accepts and stores the new error handling parameters with sensible defaults (showErrorWidgets: true, logStackTraces: true). The configuration is properly stored in static variables for runtime access.

---

302-350: Consistent error handling for action parsing.

The onCallFromJson method applies the same validation and error handling patterns as fromJson, appropriately adapting for the action context (actions don't return widgets, so errors are logged but not rendered).

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (1)

packages/stac/lib/src/framework/stac_service.dart (1)

421-423: Minor: Avoid unnecessary toString() on already-String asset data.
Use snapshot.data! directly for jsonDecode.

-              final json = jsonDecode(snapshot.data.toString());
+              final json = jsonDecode(snapshot.data!);

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 917e724 and 30daaa9.

📒 Files selected for processing (4)

• packages/stac/lib/src/framework/stac.dart (3 hunks)
• packages/stac/lib/src/framework/stac_error.dart (1 hunks)
• packages/stac/lib/src/framework/stac_service.dart (8 hunks)
• packages/stac/lib/src/framework/ui/stac_outline_input_border.dart (0 hunks)

💤 Files with no reviewable changes (1)

• packages/stac/lib/src/framework/ui/stac_outline_input_border.dart

🔇 Additional comments (6)

packages/stac/lib/src/framework/stac.dart (2)

6-6: Import for StacError looks good.

---

49-62: Initialize wiring (showErrorWidgets/logStackTraces/errorWidgetBuilder) — LGTM.

Properly threads options down to StacService.initialize.

packages/stac/lib/src/framework/stac_service.dart (4)

5-5: Good call hiding Flutter’s ErrorWidgetBuilder.
Prevents typedef collision with the local one from stac.dart.

---

181-241: fromJson validations and debug-only error widget — LGTM.
Null/field checks, structured logging, and gated error UI are consistent.

---

453-475: Centralized logging helper — LGTM.
Compact message + optional stack trace gating is clean and consistent.

---

483-493: Custom/default error widget selection — LGTM.
Respects provided builder; otherwise falls back to StacErrorWidget. Debug-only governed upstream.