genui_button #

A GenUI-compatible button widget package, giving AI agents the ability to generate highly styled buttons connected to your app's interactions.

Features #

• Provides a GenUIButton widget defined as a GenUI CatalogItem.
• Theme Support: Seamlessly falls back to your app's Material 3 ThemeData if properties are absent!
• Deep UI Control: Supports full width layout, custom tooltips, shadowing, explicit border colors and widths.
• Typographic Control: Explicit font weight declarations and letter spacing customizations.
• Material Styles: Supports elevated, filled, outlined, and text visual button types.
• Integrates flawlessly with genui properties to accept a label string and action ID payload.
• Out-of-the-box UserActionEvent triggering when tapping.
• Handled Accessibility out-of-the-box with Semantics.

Getting started #

In your pubspec.yaml, add the dependency:

dependencies:
  flutter:
    sdk: flutter
  genui_button: ^0.0.5

Usage #

Simply register genUiButton with your GenUI catalogues:

import 'package:genui_button/genui_button.dart';
import 'package:genui/genui.dart';

final a2uiMessageProcessor = A2uiMessageProcessor(
  catalogs: [
    CoreCatalogItems.asCatalog().copyWith([genUiButton])
  ],
);

Then your FirebaseAiContentGenerator (or similar generator) system instruction can tell the agent to use GenUIButton globally.

final contentGenerator = FirebaseAiContentGenerator(
  systemInstruction: 'Use GenUIButton to provide user actions with custom styling.',
  additionalTools: a2uiMessageProcessor.getTools(),
);

Whenever the agent generates a UI containing a button, it can trigger UserActionEvent actions back to the app logic that you configure.

The AI can also deeply customize the button's look dynamically using the schema:

• type: elevated, filled, outlined, text
• backgroundColor: #FF5733
• foregroundColor: #FFFFFF
• borderColor: #000000
• borderWidth: 1.5
• shadowColor: #FF0000
• borderRadius: 8.0
• elevation: 4.0
• padding: 16.0
• fontSize: 18.0
• fontWeight: bold, normal, w700
• letterSpacing: 1.2
• fullWidth: true
• tooltip: "Click me to proceed!"
• data: {"id": 123} (Static payload parameters)
• contextMapping: {"user": "session/user_id"} (Dynamic context collection from DataContext)
• debounceMs: 500 (Debounce duration in milliseconds)
• onLongPressAction: "secondary_action" (Alternative action on long press)
• confirmation: {"title": "Warning!", "message": "Delete?"} (Confirmation dialog setup)

Realistic Action Handling #

GenUIButton supports advanced interaction patterns to build production-ready AI UIs:

Context & Data Mapping

You can now map button actions to specific keys in the GenUI DataContext. This allows the button to "collect" state from other components (like text fields or checkboxes) that have bound their values to the context.

{
  "action": "submit_form",
  "contextMapping": {
    "email": "form/email_field",
    "accept_terms": "form/terms_accepted"
  }
}

Native Confirmation Dialogs

For destructive or important actions, you can configure a native confirmation dialog without any extra logic on the app side:

{
  "action": "clear_data",
  "confirmation": {
    "isEnabled": true,
    "title": "Clear all data?",
    "message": "This action is permanent and cannot be reversed.",
    "confirmText": "Delete All",
    "cancelText": "Keep My Data",
    "onConfirmAction": "explicitly_confirmed_delete",
    "onCancelAction": "user_cancelled_delete"
  }
}

Key confirmation properties:

• isEnabled: Set to false to conditionally disable the dialog.
• onConfirmAction: Override the default action when the user confirms.
• onCancelAction: Trigger a specific event if the user cancels.

### Handling Actions (Developer Guide)

When a developer uses this package, the button triggers a `UserActionEvent`. Here is the best way to handle these actions in your Flutter app using a `GenUiSurface`:

```dart
GenUiSurface(
  message: lastAiMessage,
  onEvent: (UiEvent event) {
    if (event is UserActionEvent) {
      // 1. Identify the action triggered by the AI
      final actionName = event.name;
      
      // 2. Access the data payload (static data + context mapping)
      final payload = event.context; 

      switch (actionName) {
        case 'submit_order':
          _processOrder(payload['order_id'], payload['user_email']);
          break;
        case 'user_confirmed_delete':
          _performDeletion(payload['id']);
          break;
        case 'analytics_cancel':
          _logCancellation(payload['reason']);
          break;
      }
    }
  },
)

Advanced Confirmation Logic #

The confirmation object allows for interactive safety checks before an action is dispatched.

Conditional Confirmation Example

The AI can decide to only show a confirmation if a certain condition is met (e.g., "Are you sure you want to exit without saving?"):

{
  "action": "exit_screen",
  "confirmation": {
    "isEnabled": true,
    "title": "Unsaved Changes",
    "message": "You have unsaved work. Exit anyway?",
    "confirmText": "Exit",
    "onConfirmAction": "FORCE_EXIT_CONFIRMED",
    "onCancelAction": "STAY_ON_PAGE"
  }
}

Example Application #

See the example/ folder for a more comprehensive Flutter project demonstrating how genui_button parses styling under the hood, including its interactions with parent themes!