diff --git a/docs/concepts/stac_registry.mdx b/docs/concepts/stac_registry.mdx new file mode 100644 index 000000000..fc480d639 --- /dev/null +++ b/docs/concepts/stac_registry.mdx @@ -0,0 +1,90 @@ +--- +title: "Stac Registry" +description: "Understand the central hub for widget parsers, action parsers, and global state in the Stac ecosystem" +--- + +The **Stac Registry** is the "brain" of the Stac framework. It acts as a centralized, in-memory repository that manages how the engine translates static JSON data into live Flutter widgets and functional actions. + +## 1. What is Stac Registry? + +The Stac Registry is a singleton service that serves as a lookup table for the rendering engine. It manages three primary areas: +- **Widget Parsers**: Mapping of JSON `type` strings (e.g., `"text"`) to their respective `StacParser`. +- **Action Parsers**: Mapping of logic triggers (e.g., `"navigate"`) to their `StacActionParser`. +- **Global Variables**: A key-value store for placeholder resolution (e.g., `{{userName}}`). + +## 2. Why and when it should be used? + +The Registry is used whenever you need to: +- **Extend Stac**: Register custom widget or action parsers that are not included in the core library. +- **Manage Dynamic Data**: Inject application state (like user info or theme settings) into your SDUI screens without re-fetching JSON. +- **Custom Logic**: Trigger specific application logic directly from a server-side payload. + +## 3. How it fits into Stac Architecture + +The Registry acts as the bridge between **Server JSON** and **Native Flutter execution**. + +### Architecture Flow + +```mermaid +graph TD + A[Server JSON] --> B(Variable Resolver) + B --> C{Stac Registry} + C -->|Lookup Parser| D[Widget Parser] + C -->|Lookup Action| E[Action Parser] + D --> F[Native Flutter Widget] + E --> G[Logic Execution] +``` + +### Data Flow Steps +1. **Placeholder Resolution**: The `Variable Resolver` swaps any `{{variable}}` placeholders in the JSON with real values from the Registry. +2. **Parser Discovery**: The Stac engine queries the Registry for the parser matching the JSON's `type` field. +3. **Execution**: The found parser converts the JSON data into a Flutter widget or executes the requested action. + +## 4. Basic Usage Example + +### Registering a Custom Parser +You typically register your custom parsers during the application's initialization phase. + +```dart +void main() async { + await Stac.initialize( + parsers: [ + const MyCustomWidgetParser(), + ], + ); + + runApp(const MyApp()); +} +``` + +### Using Global Variables +Store a value in the Registry and reference it in your SDUI screens. + +```dart +// Set a global variable +StacRegistry.instance.setValue('userName', 'Alex Smith'); +``` + +**JSON Usage:** +```json +{ + "type": "text", + "data": "Welcome back, {{userName}}!" +} +``` + +> [!TIP] +> **Variable Resolution is Recursive.** If you store a complex Map in the Registry, you can access nested properties in your JSON using dot notation (e.g., `{{user.profile.name}}`). + +### 5. Overriding Core Behavior (Global Styling) +If you want to change how a standard widget like `StacText` behaves globally (e.g., to force all text to be uppercase or add a custom logging interceptor), you can override the default parser. + +```dart +StacRegistry.instance.register( + const MyBrandedTextParser(), + true, // This replaces the core "text" parser +); +``` + +> [!WARNING] +> **Memory Management.** Since the Registry is a Singleton, registrations and values persist for the entire lifecycle of the application. Always use `removeValue()` to clear sensitive user data when they log out to avoid memory leaks or data exposure. diff --git a/docs/docs.json b/docs/docs.json index a63c419a2..db3e65ab4 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -41,6 +41,7 @@ "icon": "book", "pages": [ "concepts/rendering_stac_widgets", + "concepts/stac_registry", "concepts/navigation_in_stac", "concepts/caching", "concepts/custom_widgets", diff --git a/examples/counter_example/pubspec.lock b/examples/counter_example/pubspec.lock index 5062314b0..24d756a89 100644 --- a/examples/counter_example/pubspec.lock +++ b/examples/counter_example/pubspec.lock @@ -784,30 +784,34 @@ packages: stac: dependency: "direct main" description: - path: "../../packages/stac" - relative: true - source: path + name: stac + sha256: f1a53751157e7882d7218765b6e13016aa345007f2c6b48520c6edb32b4d02d3 + url: "https://pub.dev" + source: hosted version: "1.4.0" stac_core: - dependency: "direct overridden" + dependency: transitive description: - path: "../../packages/stac_core" - relative: true - source: path + name: stac_core + sha256: fd7e618b62b8ea136ec56837a466ab3f639a124e371d18f9d75af8631f4e2980 + url: "https://pub.dev" + source: hosted version: "1.4.0" stac_framework: - dependency: "direct overridden" + dependency: transitive description: - path: "../../packages/stac_framework" - relative: true - source: path + name: stac_framework + sha256: e75d1a1b2fd46c65acbc6ce174c7272aef4eb4020722f09c35fce2b3dadf858e + url: "https://pub.dev" + source: hosted version: "1.0.0" stac_logger: - dependency: "direct overridden" + dependency: transitive description: - path: "../../packages/stac_logger" - relative: true - source: path + name: stac_logger + sha256: bc3c1cc486d59d2378c1e18bfd9bfa078be564b58d4ae2b3898633c05a02df26 + url: "https://pub.dev" + source: hosted version: "1.1.0" stack_trace: dependency: transitive @@ -986,5 +990,5 @@ packages: source: hosted version: "3.1.3" sdks: - dart: ">=3.9.0 <4.0.0" + dart: ">=3.9.2 <4.0.0" flutter: ">=3.35.0" diff --git a/examples/movie_app/pubspec.lock b/examples/movie_app/pubspec.lock index 7ed7c023e..48b37aed9 100644 --- a/examples/movie_app/pubspec.lock +++ b/examples/movie_app/pubspec.lock @@ -712,30 +712,34 @@ packages: stac: dependency: "direct main" description: - path: "../../packages/stac" - relative: true - source: path + name: stac + sha256: f1a53751157e7882d7218765b6e13016aa345007f2c6b48520c6edb32b4d02d3 + url: "https://pub.dev" + source: hosted version: "1.4.0" stac_core: - dependency: "direct overridden" + dependency: transitive description: - path: "../../packages/stac_core" - relative: true - source: path + name: stac_core + sha256: fd7e618b62b8ea136ec56837a466ab3f639a124e371d18f9d75af8631f4e2980 + url: "https://pub.dev" + source: hosted version: "1.4.0" stac_framework: - dependency: "direct overridden" + dependency: transitive description: - path: "../../packages/stac_framework" - relative: true - source: path + name: stac_framework + sha256: e75d1a1b2fd46c65acbc6ce174c7272aef4eb4020722f09c35fce2b3dadf858e + url: "https://pub.dev" + source: hosted version: "1.0.0" stac_logger: - dependency: "direct overridden" + dependency: transitive description: - path: "../../packages/stac_logger" - relative: true - source: path + name: stac_logger + sha256: bc3c1cc486d59d2378c1e18bfd9bfa078be564b58d4ae2b3898633c05a02df26 + url: "https://pub.dev" + source: hosted version: "1.1.0" stack_trace: dependency: transitive @@ -906,5 +910,5 @@ packages: source: hosted version: "3.1.3" sdks: - dart: ">=3.9.0 <4.0.0" + dart: ">=3.9.2 <4.0.0" flutter: ">=3.35.0" diff --git a/examples/stac_gallery/pubspec.lock b/examples/stac_gallery/pubspec.lock index ff6d69155..820e330ef 100644 --- a/examples/stac_gallery/pubspec.lock +++ b/examples/stac_gallery/pubspec.lock @@ -776,37 +776,42 @@ packages: stac: dependency: "direct main" description: - path: "../../packages/stac" - relative: true - source: path + name: stac + sha256: f1a53751157e7882d7218765b6e13016aa345007f2c6b48520c6edb32b4d02d3 + url: "https://pub.dev" + source: hosted version: "1.4.0" stac_core: - dependency: "direct overridden" + dependency: transitive description: - path: "../../packages/stac_core" - relative: true - source: path + name: stac_core + sha256: fd7e618b62b8ea136ec56837a466ab3f639a124e371d18f9d75af8631f4e2980 + url: "https://pub.dev" + source: hosted version: "1.4.0" stac_framework: - dependency: "direct overridden" + dependency: transitive description: - path: "../../packages/stac_framework" - relative: true - source: path + name: stac_framework + sha256: e75d1a1b2fd46c65acbc6ce174c7272aef4eb4020722f09c35fce2b3dadf858e + url: "https://pub.dev" + source: hosted version: "1.0.0" stac_logger: - dependency: "direct overridden" + dependency: transitive description: - path: "../../packages/stac_logger" - relative: true - source: path + name: stac_logger + sha256: bc3c1cc486d59d2378c1e18bfd9bfa078be564b58d4ae2b3898633c05a02df26 + url: "https://pub.dev" + source: hosted version: "1.1.0" stac_webview: dependency: "direct main" description: - path: "../../packages/stac_webview" - relative: true - source: path + name: stac_webview + sha256: "6cf9a59a8b7b9aea85e599777a57618365b45f544d0a66916995a9dd4b2ee379" + url: "https://pub.dev" + source: hosted version: "1.0.0" stack_trace: dependency: transitive @@ -1017,5 +1022,5 @@ packages: source: hosted version: "3.1.3" sdks: - dart: ">=3.9.0 <4.0.0" + dart: ">=3.9.2 <4.0.0" flutter: ">=3.35.0" diff --git a/packages/stac_cli/pubspec.lock b/packages/stac_cli/pubspec.lock index ea1f4bd3b..20428a541 100644 --- a/packages/stac_cli/pubspec.lock +++ b/packages/stac_cli/pubspec.lock @@ -241,6 +241,11 @@ packages: url: "https://pub.dev" source: hosted version: "1.1.1" + flutter: + dependency: transitive + description: flutter + source: sdk + version: "0.0.0" frontend_server_client: dependency: transitive description: @@ -353,6 +358,14 @@ packages: url: "https://pub.dev" source: hosted version: "0.12.19" + material_color_utilities: + dependency: transitive + description: + name: material_color_utilities + sha256: "9c337007e82b1889149c82ed242ed1cb24a66044e30979c44912381e9be4c48b" + url: "https://pub.dev" + source: hosted + version: "0.13.0" meta: dependency: transitive description: @@ -449,6 +462,11 @@ packages: url: "https://pub.dev" source: hosted version: "3.0.0" + sky_engine: + dependency: transitive + description: flutter + source: sdk + version: "0.0.0" source_gen: dependency: transitive description: @@ -492,16 +510,18 @@ packages: stac_core: dependency: "direct main" description: - path: "../stac_core" - relative: true - source: path + name: stac_core + sha256: fd7e618b62b8ea136ec56837a466ab3f639a124e371d18f9d75af8631f4e2980 + url: "https://pub.dev" + source: hosted version: "1.4.0" stac_logger: - dependency: "direct overridden" + dependency: transitive description: - path: "../stac_logger" - relative: true - source: path + name: stac_logger + sha256: bc3c1cc486d59d2378c1e18bfd9bfa078be564b58d4ae2b3898633c05a02df26 + url: "https://pub.dev" + source: hosted version: "1.1.0" stack_trace: dependency: transitive @@ -583,6 +603,14 @@ packages: url: "https://pub.dev" source: hosted version: "1.4.0" + vector_math: + dependency: transitive + description: + name: vector_math + sha256: d530bd74fea330e6e364cda7a85019c434070188383e1cd8d9777ee586914c5b + url: "https://pub.dev" + source: hosted + version: "2.2.0" vm_service: dependency: transitive description: @@ -649,3 +677,4 @@ packages: version: "3.1.3" sdks: dart: ">=3.10.0 <4.0.0" + flutter: ">=1.17.0"