Skip to main content

fl_select_genui 0.9.0 copy "fl_select_genui: ^0.9.0" to clipboard
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.

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.

1
likes
160
points
1.06k
downloads

Documentation

API reference

Publisher

verified publisherzeaon.dev

Weekly Downloads

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.

Repository (GitHub)
View/report issues
Contributing

Topics

#genui #select #multiselect #dropdown #a2ui

License

MIT (license)

Dependencies

a2ui_core, a2ui_flutter, fl_select, flutter, json_schema_builder, material_ui

More

Packages that depend on fl_select_genui