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

Release Notes

• New Features
  • Network requests now support optional custom loading and error widgets. Define what displays while content loads and how errors are presented, with full JSON configuration support.

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

[coderabbitai]

Walkthrough

The PR adds optional loadingWidget and errorWidget parameters to StacNetworkWidget. These widgets can be configured in JSON and are passed through the parser to Stac.fromNetwork. Changes include widget class definition, JSON serialization, and parser updates to handle the new optional parameters.

Changes

Cohort / File(s)	Summary
Widget model and 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 optional loadingWidget and errorWidget fields to StacNetworkWidget constructor and class definition. Updated JSON (de)serialization logic to handle null-safe parsing and serialization of both new fields. Extended documentation with examples.
Parser delegation packages/stac/lib/src/parsers/widgets/stac_network_widget/stac_network_widget_parser.dart	Updated StacNetworkWidgetParser.parse to extract and parse optional loadingWidget and errorWidget from the model, delegating to Stac.fromNetwork with parsed results or SizedBox fallbacks.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

• The changes follow a consistent, repetitive pattern across all files (adding optional parameters with null-safety).
• JSON serialization updates are straightforward null-aware handling.
• Parser updates use simple fallback logic with minimal branching.

Possibly related PRs

• #361: Both PRs modify widget/action parsers to delegate to nested model.parse(context) instead of direct Stac calls, enabling custom widget composition through configuration.

Suggested reviewers

• divyanshub024

Poem

🐰 A network widget hops with glee,
Now loading states the world can see!
With error friends to catch the fall,
Custom widgets grace them all! ✨

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 title clearly and concisely describes the main feature addition: support for loading and error widgets in StacNetworkWidget.
Linked Issues check	✅ Passed	The PR fully addresses issue #243 by adding optional loadingWidget and errorWidget fields to StacNetworkWidget with proper parser support and documentation.
Out of Scope Changes check	✅ Passed	All changes directly support the feature objective of adding loading and error widget support; no out-of-scope 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 11de03f and 0dc0d38.

📒 Files selected for processing (3)

• packages/stac/lib/src/parsers/widgets/stac_network_widget/stac_network_widget_parser.dart (2 hunks)
• packages/stac_core/lib/widgets/network_widget/stac_network_widget.dart (3 hunks)
• packages/stac_core/lib/widgets/network_widget/stac_network_widget.g.dart (1 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)

• GitHub Check: format
• GitHub Check: analyze
• GitHub Check: pub_get_check

🔇 Additional comments (4)

packages/stac_core/lib/widgets/network_widget/stac_network_widget.dart (2)

11-12: Docs and examples for loading/error widgets are clear and aligned with the API

The added prose plus Dart/JSON examples accurately reflect the new loadingWidget and errorWidget fields and how they’re intended to be used. Nothing blocking here.

Also applies to: 15-55

---

61-69: Model shape for optional loading/error widgets is consistent and non‑breaking

The constructor and new StacWidget? fields are well-typed and keep request required. This matches the generated JSON code and the parser’s usage, so the change is additive and preserves existing behavior when the new fields are omitted.

Also applies to: 72-85

packages/stac_core/lib/widgets/network_widget/stac_network_widget.g.dart (1)

14-19: JSON (de)serialization for loading/error widgets matches the model and parser

The FromJson/ToJson updates correctly mirror the new optional fields and use StacWidget.fromJson/.toJson() as expected. This keeps the wire format consistent with the public API and the parser’s expectations.

Also applies to: 25-26

packages/stac/lib/src/parsers/widgets/stac_network_widget/stac_network_widget_parser.dart (1)

3-4: Parser wiring into Stac.fromNetwork is correct and defensive

Importing stac_widget_parser.dart and passing loadingWidget/errorWidget as builders that call model.*Widget!.parse(context) ?? const SizedBox() cleanly bridges the model to runtime widgets while avoiding nulls from the builders. The change is additive and preserves previous defaults when the new fields are absent.

Also applies to: 18-29

---

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

[divyanshub024]

I think we should have some default loading widget