Stac Server-Driven UI Framework

Stac is a Server-Driven UI (SDUI) framework for Flutter. It allows you to build, update, and deliver dynamic user interfaces by defining your UI as Stac Widgets that render at runtime from JSON. This eliminates the need to redeploy the Flutter app for UI changes.

Key Benefits

• Instant Updates: Update StacWidgets and push them to Stac Cloud to ship changes immediately.
• Feature Experimentation: Perform A/B testing and personalization without new app releases.
• Cross-Platform Consistency: Use a unified schema to maintain UI consistency across different platforms.
• Non-Developer Empowerment: Enable designers and PMs to manage layouts and content directly.

The stac_core package is a pure Dart package that provides the foundational core functionalities and common interfaces for the Stac ecosystem. It defines the core models and interfaces that the main stac package depends on to build server-driven UIs.

If you are looking for a functional implementation of server-driven UI, refer to the main Stac package.

The Movie App example serves as a reference implementation for several core Stac capabilities:

• Complex dynamic layouts: Using Stac components to build sophisticated UIs driven by the server.
• Network data fetching: Combining real-time data retrieval with Server-Driven UI patterns.
• Navigation: Moving between different screens that are themselves defined by the server.
• Global theming: Implementing consistent visual styles across the application using the Stac theme system.

The Image widget allows you to display images in your Flutter app via JSON. It supports three primary source types: asset, network, and file. You can customize the display using properties like width, height, fit, alignment, and color.

{
  "type": "image",
  "src": "assets/logo.png",
  "imageType": "asset",
  "width": 200,
  "height": 100,
  "fit": "cover"
}

The Stac Registry is a centralized, in-memory singleton service that acts as the 'brain' of the Stac framework. It serves as a lookup table for the rendering engine to bridge the gap between Server JSON and Native Flutter execution.

The Registry manages three primary responsibilities:

1. Widget Parsers: Maps JSON type strings (e.g., "text") to their corresponding StacParser.
2. Action Parsers: Maps logic triggers (e.g., "navigate") to their StacActionParser.
3. Global Variables: A key-value store used for placeholder resolution (e.g., {{userName}}).

Server-Driven UI (SDUI) is an architectural approach where the server determines the layout and behavior of a screen, and the mobile app acts as a renderer. Instead of hardcoding UI in the client, the app fetches a description (typically a JSON schema) from the server that specifies which components to display, their arrangement, and their actions.

The SDUI Workflow:

1. Server Definition: The server defines the UI structure in a lightweight format (usually JSON).
2. Client Fetching: The app receives this UI schema.
3. Dynamic Rendering: The app renders the schema dynamically.

To update the UI, you only need to change the configuration on the server; the app reflects these changes instantly without requiring a new app store submission.

A custom StacWidget is a Dart class used to extend Stac's functionality. It allows you to wrap third-party Flutter packages, create reusable app-specific UI components, or build domain-specific widgets. To work within the Stac ecosystem, a custom widget must:

• Extend the StacWidget base class.
• Support JSON serialization and deserialization.
• Be paired with a corresponding StacParser to render the Flutter widget.
• Be usable within your /stac folder and deployable to Stac Cloud.

A StacAction is a Dart class used to define behaviors that can be triggered from widgets via JSON definitions. While Stac provides built-in actions (navigation, dialogs, network requests), custom actions allow you to integrate third-party services, implement business-specific logic, or extend existing functionality.

To be a valid custom action, a class must:

• Extend the StacAction base class.
• Be serializable to and from JSON.
• Be compatible with Stac's action parser system.
• Provide a unique actionType string used for identification in JSON.

The StacNavigationBar is used to build a Material 3 Flutter NavigationBar via JSON. To function correctly, it should be placed in the bottomNavigationBar slot of a StacScaffold.

For state management, it pairs with a StacDefaultNavigationController (which defines the number of destinations via length) and a StacNavigationView as the body. The controller drives the selection state, switching between the children provided in the StacNavigationView as the user interacts with the bar.

StacDefaultNavigationController(
  length: 3,
  child: StacScaffold(
    body: StacNavigationView(
      children: [ /* views for each destination */ ],
    ),
    bottomNavigationBar: StacNavigationBar(
      destinations: [ /* navigation destinations */ ],
    ),
  ),
)

The StacStack widget allows you to layer multiple children on top of each other using JSON or Dart. It is the Stac implementation of the Flutter Stack widget. You can define how children are aligned, how they are sized, and how content is clipped within the stack.

StacStack(
  alignment: StacAlignment.center,
  clipBehavior: StacClip.antiAlias,
  fit: StacStackFit.expand,
  textDirection: StacTextDirection.ltr,
  children: [
    StacText(data: 'Hello, World!'),
    StacContainer(width: 100, height: 100, color: StacColors.red),
  ],
)

To insert data from an API response into a dynamicView template, use double curly braces {{placeholder}}.

• Nested data: Use dot notation, e.g., {{user.address.city}}.
• Array elements: Use index notation, e.g., {{users[0].name}} or {{items.0.title}}.
• Nested arrays/objects: Combine notation, e.g., {{data.users[2].profile.name}}.

StacText(data: 'Hello, {{name}}!')