codecov

A2UI integration for fl_select, built on the A2UI Dart SDKs a2ui_core and a2ui_flutter: exposes fl_select components as catalog components (ComponentImplementations) so conversational AI agents can render real, interactive selection UIs inside chat surfaces — and receive the user's selections back as structured query data.

agent ──JSON payload──▶ Select (fl_select UI) ──selection──▶ Map<String, List<String>>

How it works

  1. You register FlSelectCatalogItems.asCatalog() (or .all, added to the basic catalog) with your A2UI MessageProcessor.

  2. Your agent's system prompt includes FlSelectCatalogItems.systemPromptFragment, which teaches it the Select vocabulary.

  3. When the user needs to pick values, the agent emits a Select payload — a delegate (list / grid / wrap / cascading / tabNav / sideNav / expandable) plus an entries tree authored in the SelectEntryCodec JSON format. The shape has to match the delegate: flat nodes for list / grid / wrap, a category tree for cascading / tabNav / sideNav / expandable. A category picks how its own children render through its layout: list / grid / chip / counter / range render one level, cascading renders one column per level and drills into nested children.

    A grid the agent leaves unshaped — {"kind": "grid", "crossAxisCount": 2} — gets the catalog's compact tiles (3:1, 10px apart) rather than fl_select's square, touching defaults, which are meant for icon grids; tabNav falls back to the same shape when a category has no layout of its own, and a missing or unusable crossAxisCount becomes 3 columns. Set childAspectRatio / mainAxisSpacing / crossAxisSpacing in the layout to keep a different shape.

    Optional top-level fields tune the whole panel: selectionMode (single / multiple), search (boolean), defaultLayout (a layout object used by categories without their own layout, for tabNav / sideNav / expandable) and isScrollable (tabNav / sideNav / cascading). Leave isScrollable out and tabNav scrolls on its own when its category names do not fit the width.

    Like the basic components, a Select also accepts A2UI's common weight (its share of a Row / Column main axis) and accessibility (label / description for screen readers) properties.

  4. The user interacts with a real fl_select component; selections are written back to the surface's data model at <id>.value as a Map<String, List<String>> (same shape as fl_select's toQueryMap), ready for the next agent turn or your query layer.

The MessageProcessor rejects a payload that does not match the Select schema (a wrong type, an unknown delegate token, empty entries, or a property the schema does not declare) and reports it on processor.model.onError. Other invalid agent payloads render an inline error card instead of crashing.

Agent Skills

This package ships an agent skill for the Dart Skills CLI at skills/fl-select-genui-code-generation, so AI coding agents (Claude Code, Cursor, Codex, Windsurf, GitHub Copilot, etc.) author Select payloads correctly — catalog registration, the SelectEntryCodec entry-tree format, selection write-back, and the SelectEntrySchema JSON Schema.

It is discovered automatically in any project that depends on fl_select_genui. Run this from the project root (the CLI resolves skills from that project's dependency tree):

# install every discovered skill without prompting
dart run skills@ get --all

# or pick interactively / target one package
dart run skills@ get
dart run skills@ get --package fl_select_genui

Usage

import 'package:a2ui_core/a2ui_core.dart';
import 'package:a2ui_flutter/a2ui_flutter.dart';
import 'package:a2ui_flutter/v0_9/basic_catalog.dart' as v0_9;
import 'package:fl_select_genui/fl_select_genui.dart';

final processor = MessageProcessor<ComponentImplementation>(
  catalogs: [
    v0_9.basicCatalog().copyWith(
      components: [...v0_9.BasicComponents.all, ...FlSelectCatalogItems.all],
    ),
  ],
);

// Pass the agent's A2UI messages to processor.processMessages(...) and render
// each surface it creates with A2uiSurface(surface: surface).

// System prompt:
FlSelectCatalogItems.systemPromptFragment;

See example/ for an end-to-end example of the payload → render → write-back loop.

Entry tree format

{"type": "category", "id": "price", "name": "Price", "children": [
  {"type": "any", "name": "Any"},
  {"type": "range", "id": "0-100", "name": "$0 - $100", "min": 0, "max": 100},
  {"type": "custom", "name": "Custom", "min": 0, "max": 1000}
]}

Node types: category (group, optional selectionMode / layout and header/footer chip rows with their own headerSelectionMode / footerSelectionMode), text (option or sub-branch), range (slider), any (reset sentinel), custom (user-typed range). See SelectEntrySchema for the generated JSON Schema and FlSelectCatalogItems.systemPromptFragment for the agent-facing documentation.

The top level is either all category nodes or a flat list of leaves — never both. A non-category entry beside a category is invalid (a category tree needs every top-level entry to be a category, which is how fl_select renders its navigation) and renders the error card.

Libraries

fl_select_genui
A2UI integration for fl_select.