fl_select_genui 0.3.0

fl_select_genui: ^0.3.0 copied to clipboard

GenUI SDK (A2UI) integration for fl_select: exposes fl_select components as CatalogItems 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) with your GenUI SurfaceController alongside the basic catalog.
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.
4. The user interacts with a real fl_select component; selections are written back to the GenUI 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.

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:

dart run skills@ get

Usage #

import 'package:fl_select_genui/fl_select_genui.dart';
import 'package:genui/genui.dart';

final controller = SurfaceController(
  catalogs: [
    BasicCatalogItems.asCatalog().copyWith(
      newItems: FlSelectCatalogItems.all,
    ),
  ],
);

// System prompt:
FlSelectCatalogItems.systemPromptFragment;

See example/ for an end-to-end demo 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), 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.