feat: add stacOffstage widget, parser, example, and documentation

[akhil-ge0rge]

Description

This PR introduces support for stacOffstage by adding a new widget model and its corresponding parser.

Related Issues

Closes #433

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

  • Introduced Offstage widget support, allowing developers to conditionally hide/show content while preserving widget state. The widget is removed from layout calculations but remains in the widget tree.

• Documentation

  • Added dedicated documentation page explaining Offstage behavior and use cases.
  • Added interactive gallery example demonstrating Offstage widget in action.

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

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds Offstage widget support to the Stac framework by introducing a new StacOffstage model, StacOffstageParser, JSON serialization, parser registration, enum type addition, documentation, and gallery examples demonstrating the widget's functionality.

Changes

Cohort / File(s)	Summary
Core Widget Model packages/stac_core/lib/widgets/offstage/stac_offstage.dart, packages/stac_core/lib/widgets/offstage/stac_offstage.g.dart	Introduces StacOffstage widget model extending StacWidget with offstage (bool?) and child (StacWidget?) properties, including JSON serialization/deserialization via generated code.
Parser Implementation packages/stac/lib/src/parsers/widgets/stac_offstage/stac_offstage_parser.dart, packages/stac/lib/src/parsers/widgets/widgets.dart	Adds StacOffstageParser to convert JSON into Flutter Offstage widgets and exports the parser from the widgets module.
Framework Integration packages/stac_core/lib/foundation/specifications/widget_type.dart, packages/stac/lib/src/framework/stac_service.dart, packages/stac_core/lib/widgets/widgets.dart	Registers offstage in WidgetType enum, initializes StacOffstageParser in StacService, and exports StacOffstage from widgets module.
Documentation & Examples docs/widgets/offstage.mdx, docs/docs.json, examples/stac_gallery/assets/json/home_screen.json, examples/stac_gallery/assets/json/offstage_example.json	Adds comprehensive documentation explaining Offstage behavior, updates navigation index, and provides gallery example with JSON asset demonstrating usage.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• feat: Introduce stacTooltip widget and parser with example JSON #397 — Adds new widget type support with same registration pattern in StacService and WidgetType enum.
• Stac Framework Enhancements: Navigation, Borders, Colors & Architecture Improvements #361 — Also extends WidgetType enumeration and registers new parsers following identical integration approach.

Suggested labels

feature

Suggested reviewers

• divyanshub024
• Potatomonsta

Poem

🐰 A hidden widget hops into place,
Offstage it stands, preserved with grace,
The Stac framework now knows its name,
State preserved, but out of frame!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title accurately describes the main changes: adding a stacOffstage widget with parser, example, and documentation.
Linked Issues check	✅ Passed	The PR successfully implements the StacOffstage widget model required by issue #433, with full parser, documentation, and example support.
Out of Scope Changes check	✅ Passed	All changes are directly related to the Offstage widget implementation objective: model, parser registration, documentation, and gallery example.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

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]

Thanks a lot for the PR and the effort put into this 🙌

At the moment, this widget is not something we need right now, so we will skip merging it for now. That said, it’s a solid addition and we would be happy to revisit it in the future if the requirement comes up 🚀

Really appreciate you taking the time to contribute :)