⚡ bloc_signals_genui_flutter

"With the rigor of BLoC and the flex and speed of Signals"

Declarative Flutter surface views, Material 3 catalog widgets, and 0ms reactive two-way data bindings for bloc_signals_genui and Google's A2UI (Agent-to-User Interface) protocol.

bloc_signals_genui_flutter connects the pure-Dart A2uiSurfaceBloc state machine to Flutter's widget hierarchy via A2uiSurfaceView, A2uiFlutterCatalog, A2uiComponentContext, and GenUiControllerAdapter.

🌐 Ecosystem Packages

The BlocSignal monorepo consists of 13 modular packages:

Package	Version	Description
`bloc_signals`		Core pure Dart reactive state primitives bridging BLoC & Signals
`bloc_signals_flutter`		Flutter UI bindings, providers, builders, listeners & selectors
`bloc_signals_bloc`		Classic BLoC 8/9 interop adapters & bidirectional event bridges
`bloc_signals_riverpod`		Bidirectional Riverpod 2/3 interop adapters & provider extensions
`bloc_signals_jaspr`		Jaspr web component integration and state binding for BlocSignal
`bloc_signals_hydrate`		Automated synchronous local state persistence & hydration
`bloc_signals_replay`		Undo & redo state history tracking for CubitSignal and BlocSignal
`bloc_signals_otel`		OpenTelemetry tracing and span generation for state transitions
`bloc_signals_devtools`		Universal DevTools telemetry observer using `dart:developer`
`bloc_signals_test`		Declarative unit testing utilities (`blocSignalTest`)
`bloc_signals_lint`		Custom analyzer lint rules & automated IDE quick-fixes
`bloc_signals_genui`		Pure-Dart A2UI streaming state machine & Generative UI runtime adapter
`bloc_signals_genui_flutter`		Declarative Flutter surface containers & A2UI catalog widget adapters

⚡ Key Features

🎨 A2uiSurfaceView: Declarative Flutter widget handling the complete A2uiSurfaceState lifecycle (SurfaceInitial, SurfaceStreaming, SurfaceReady, SurfaceSubmitting, and SurfaceError) with customizable builders and per-component error boundaries.
🧱 A2uiFlutterCatalog (16 Standard BasicCatalog Widgets): Extensible component registry pre-populated with 16 Material 3 widgets covering A2UI BasicCatalog v0.9 and v1.0 (Text, Row, Column, List, Tabs, Modal, Card, Divider, Icon, Image, Button, TextField, CheckBox, ChoicePicker, Slider, and DateTimeInput) alongside immutable composition helpers (copyWith, copyWithout, registerAll).
✅ Reactive CheckRule Validation UI: Automatically surfaces GenericBinder validation state (isValid, validationErrors, validationResults) across form inputs (TextField, CheckBox, ChoicePicker, Slider, DateTimeInput) and disables Button submissions (onPressed: null) when check rules fail.
⚡ Granular Signal Bindings & Two-Way Sync: Each rendered component subscribes to its own GenericBinder.resolvedProps signal and writes two-way input mutations via A2uiComponentContext.updateBoundValue, updating leaf widgets and A2uiSurfaceBloc form data in 0ms on DataModel or @path mutations without rebuilding parent containers.
🧭 Multi-Surface & Split-Pane Support: Pin A2uiSurfaceView(bloc: bloc, surfaceId: '...') to a specific surface or omit surfaceId to follow bloc.activeSurfaceId reactively across tabs and split views.
🛡️ Defensive LLM Property Coercion: Built-in safe_prop_parser.dart utilities (unwrapBinding, asString, asInt, asDouble, asBool, extractChildId, extractChildIds) protect the widget tree from malformed or stringified LLM JSON properties.

📦 Installation

Add bloc_signals_genui_flutter to your Flutter project:

flutter pub add bloc_signals_genui_flutter

Or declare it in your pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  bloc_signals: ^1.7.0
  bloc_signals_flutter: ^1.3.4
  bloc_signals_genui: ^1.0.0
  bloc_signals_genui_flutter: ^1.0.0
  a2ui_core: ^0.3.0

🚀 Quick Start

Rendering an Interactive A2UI Surface

import 'package:bloc_signals_flutter/bloc_signals_flutter.dart';
import 'package:bloc_signals_genui/bloc_signals_genui.dart';
import 'package:bloc_signals_genui_flutter/bloc_signals_genui_flutter.dart';
import 'package:flutter/material.dart';

// Dart 3.5+ (Standard)
class AgentSurfaceScreen extends StatelessWidget {
  const AgentSurfaceScreen({
    required this.surfaceBloc,
    super.key,
  });

  final A2uiSurfaceBloc surfaceBloc;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Generative UI Surface')),
      body: A2uiSurfaceView(
        bloc: surfaceBloc,
        catalog: A2uiFlutterCatalog.standard(),
      ),
    );
  }
}

// Dart 3.13+ (Modern Primary Constructor)
class ModernAgentSurfaceScreen({
  required this.surfaceBloc,
  super.key,
}) extends StatelessWidget {
  final A2uiSurfaceBloc surfaceBloc;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Generative UI Surface')),
      body: A2uiSurfaceView(
        bloc: surfaceBloc,
        catalog: A2uiFlutterCatalog.standard(),
      ),
    );
  }
}

Registering Custom Catalog Widgets

Extend A2uiFlutterCatalog.standard() using copyWith (or register) to bind domain-specific A2UI components to custom Flutter widgets while reading and mutating form signals through A2uiComponentContext:

final customCatalog = A2uiFlutterCatalog.standard().copyWith({
  'RatingSlider': (context, A2uiComponentContext componentContext) {
    final path = componentContext.props['path'] as String? ?? '/rating';
    final label = componentContext.props['label'] as String? ?? 'Rating';
    final current =
        (componentContext.props['value'] as num?)?.toDouble() ?? 3.0;

    return Column(
      crossAxisAlignment: CrossAxisAlignment.start,
      children: [
        Text('$label: ${current.toStringAsFixed(1)}'),
        Slider(
          min: 1,
          max: 5,
          divisions: 4,
          value: current,
          onChanged: (next) => componentContext.updateFormField(path, next),
        ),
      ],
    );
  },
});

🛡️ License

MIT License. See LICENSE for details.