⚡ bloc_signals_genui_jaspr

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

Jaspr web component bindings, HTML DOM catalog adapters, and 0ms reactive two-way data bindings for bloc_signals_genui and Google's A2UI (Agent-to-User Interface) protocol.

bloc_signals_genui_jaspr connects the pure-Dart A2uiSurfaceBloc state machine to Jaspr's web component hierarchy via A2uiSurfaceView, A2uiJasprCatalog, A2uiComponentContext, and standard DOM catalog components.

🌐 Ecosystem Packages

The BlocSignal monorepo consists of 14 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
`bloc_signals_genui_jaspr`		Declarative Jaspr web components & DOM catalog adapters for A2UI

⚡ Key Features

🎨 A2uiSurfaceView: Reactive Jaspr web component handling the complete A2uiSurfaceState lifecycle (SurfaceInitial, SurfaceStreaming, SurfaceReady, SurfaceSubmitting, and SurfaceError) with customizable builders and per-component error boundaries.
🧱 A2uiJasprCatalog: Extensible component registry pre-populated with standard DOM components covering core A2UI primitives (Text, Row, Column, Card, Divider, Button, and TextField) alongside immutable composition helpers (copyWith, copyWithout, registerAll).
✅ Reactive CheckRule Validation UI: Automatically surfaces GenericBinder validation state (isValid, validationErrors, validationResults) across form inputs and disables button submissions when validation rules fail.
⚡ Granular Signal Bindings & Two-Way Sync: Each rendered component subscribes to its own resolved properties and writes two-way input mutations via A2uiComponentContext.updateBoundValue, updating leaf DOM elements and A2uiSurfaceBloc form data in 0ms on data changes without tearing down 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 DOM tree from malformed or stringified LLM JSON properties.

📦 Installation

Add bloc_signals_genui_jaspr to your Jaspr project:

dart pub add bloc_signals_genui_jaspr

Or declare it in your pubspec.yaml:

dependencies:
  jaspr: ^0.23.1
  bloc_signals: ^1.7.0
  bloc_signals_jaspr: ^1.3.0
  bloc_signals_genui: ^1.0.0
  bloc_signals_genui_jaspr: ^1.0.0
  a2ui_core: ^0.3.0

🚀 Quick Start

Rendering an Interactive A2UI Surface

import 'package:bloc_signals_genui/bloc_signals_genui.dart';
import 'package:bloc_signals_genui_jaspr/bloc_signals_genui_jaspr.dart';
import 'package:bloc_signals_jaspr/bloc_signals_jaspr.dart';
import 'package:jaspr/dom.dart';
import 'package:jaspr/jaspr.dart';

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

  final A2uiSurfaceBloc surfaceBloc;

  @override
  Component build(BuildContext context) {
    return section(classes: 'agent-surface-page', [
      const h1([Component.text('Generative UI Surface')]),
      A2uiSurfaceView(
        bloc: surfaceBloc,
        catalog: A2uiJasprCatalog.standard(),
      ),
    ]);
  }
}

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

  @override
  Component build(BuildContext context) {
    return section(classes: 'agent-surface-page', [
      const h1([Component.text('Generative UI Surface')]),
      A2uiSurfaceView(
        bloc: surfaceBloc,
        catalog: A2uiJasprCatalog.standard(),
      ),
    ]);
  }
}

Registering Custom Catalog Components

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

final customCatalog = A2uiJasprCatalog.standard().copyWith({
  'MetricBadge': (context, A2uiComponentContext componentContext) {
    final label = componentContext.props['label'] as String? ?? 'Metric';
    final value = componentContext.props['value']?.toString() ?? '0';

    return button(
      classes: 'metric-badge-btn',
      onClick: () => componentContext.dispatchAction('inspect_metric'),
      [Component.text('$label: $value')],
    );
  },
});

🛡️ License

MIT License. See LICENSE for details.