fl_select_genui 0.9.0
fl_select_genui: ^0.9.0 copied to clipboard
A2UI integration for fl_select: ready-made catalog components so AI agents can render fl_select selection components in chat and get selections back as structured query data.
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 #
-
You register
FlSelectCatalogItems.asCatalog()(or.all, added to the basic catalog) with your A2UIMessageProcessor. -
Your agent's system prompt includes
FlSelectCatalogItems.systemPromptFragment, which teaches it theSelectvocabulary. -
When the user needs to pick values, the agent emits a
Selectpayload — adelegate(list / grid / wrap / cascading / tabNav / sideNav / expandable) plus anentriestree authored in theSelectEntryCodecJSON format. The shape has to match the delegate: flat nodes forlist/grid/wrap, acategorytree forcascading/tabNav/sideNav/expandable. A category picks how its own children render through itslayout:list/grid/chip/counter/rangerender one level,cascadingrenders one column per level and drills into nested children.A
gridthe agent leaves unshaped —{"kind": "grid", "crossAxisCount": 2}— gets the catalog's compact tiles (3:1, 10px apart) rather thanfl_select's square, touching defaults, which are meant for icon grids;tabNavfalls back to the same shape when a category has no layout of its own, and a missing or unusablecrossAxisCountbecomes 3 columns. SetchildAspectRatio/mainAxisSpacing/crossAxisSpacingin 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 ownlayout, fortabNav/sideNav/expandable) andisScrollable(tabNav/sideNav/cascading). LeaveisScrollableout andtabNavscrolls on its own when its category names do not fit the width.Like the basic components, a
Selectalso accepts A2UI's commonweight(its share of aRow/Columnmain axis) andaccessibility(label/descriptionfor screen readers) properties. -
The user interacts with a real fl_select component; selections are written back to the surface's data model at
<id>.valueas aMap<String, List<String>>(same shape as fl_select'stoQueryMap), 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.