feat: add loading and error widget support for StacNetworkWidget

[Potatomonsta]

Description

This PR adds support for custom loading and error widgets in the StacNetworkWidget. Users can now provide optional loadingWidget and errorWidget properties that will be displayed during the network request lifecycle.

Changes:

• Added loadingWidget and errorWidget as optional StacWidget? fields to StacNetworkWidget
• Updated StacNetworkWidgetParser to parse these widgets and pass them to Stac.fromNetwork as builder functions
• Updated documentation with Dart and JSON examples showing how to use the new features
• Generated JSON serialization code for the new fields

Example Usage:

StacNetworkWidget(
  request: StacNetworkRequest(
    url: 'https://example.com/data',
    method: 'get',
  ),
  loadingWidget: StacCenter(
    child: StacCircularProgressIndicator(),
  ),
  errorWidget: StacCenter(
    child: StacText(data: 'Failed to load'),
  ),
)

{
  "type": "networkWidget",
  "request": {
    "actionType": "networkRequest",
    "url": "https://example.com/data",
    "method": "get"
  },
  "loadingWidget": {
    "type": "center",
    "child": {
      "type": "circularProgressIndicator"
    }
  },
  "errorWidget": {
    "type": "center",
    "child": {
      "type": "text",
      "data": "Failed to load"
    }
  }
}

Related Issues

Closes #243

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
  • Network requests now support optional custom loading and error widgets. You can supply custom UI for loading and error states (or rely on sensible defaults), and configure them via the widget JSON. Documentation and examples for these optional widgets have been added.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Adds optional loadingWidget and errorWidget to StacNetworkWidget, updates JSON (de)serialization, and changes the parser to pass parsed loading/error widgets into Stac.fromNetwork (with fallbacks).

Changes

Cohort / File(s)	Summary
Widget model & serialization packages/stac_core/lib/widgets/network_widget/stac_network_widget.dart, packages/stac_core/lib/widgets/network_widget/stac_network_widget.g.dart	Added nullable loadingWidget and errorWidget fields and constructor params to StacNetworkWidget. Updated generated JSON fromJson/toJson to parse/serialize these fields (null-aware). Documentation examples extended.
Parser delegation packages/stac/lib/src/parsers/widgets/stac_network_widget/stac_network_widget_parser.dart	StacNetworkWidgetParser.parse now parses model.loadingWidget and model.errorWidget (if present) and delegates to Stac.fromNetwork with loadingWidget and errorWidget arguments; uses fallbacks (e.g., centered CircularProgressIndicator, SizedBox) when parse results are absent.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Review areas to focus on:
  • Correct null-safety and JSON (de)serialization for the new fields in the generated file.
  • Parser behavior: ensure parse(context) and parse(context, error) are invoked with correct signatures and fallbacks are appropriate.
  • Public API change: constructor signature and new public fields — check callers and docs/examples for consistency.

Suggested reviewers

• divyanshub024

Poem

🐰 I nibble code in quiet light,
Loading spins until it's right.
Errors caught with gentle cheer,
Widgets snug and messages clear.
Hop, parse, render — all in sight!

Pre-merge checks and finishing touches

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The pull request title accurately summarizes the main change: adding loading and error widget support to StacNetworkWidget, which aligns with the changeset's core modifications.
Linked Issues check	✅ Passed	The PR successfully implements all coding objectives from issue #243: adds loadingWidget and errorWidget optional fields to StacNetworkWidget [#243], updates StacNetworkWidgetParser to parse and pass these widgets to Stac.fromNetwork [#243], and includes JSON/Dart serialization and documentation [#243].
Out of Scope Changes check	✅ Passed	All changes are directly scoped to implementing the requested feature: StacNetworkWidget field additions, parser updates, serialization logic, and documentation. No unrelated modifications detected.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch mn/network-widget-loader

---

📜 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 0dc0d38 and 08ad477.

📒 Files selected for processing (1)

• packages/stac/lib/src/parsers/widgets/stac_network_widget/stac_network_widget_parser.dart (2 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/stac/lib/src/parsers/widgets/stac_network_widget/stac_network_widget_parser.dart

---

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.}