genui_gen library

Annotations and runtime helpers for generating genui CatalogItems from your own Flutter widgets.

Annotate a widget with GenUiWidget and run build_runner with genui_gen_builder to derive the JSON schema, the widget builder and the few-shot examples from the widget's constructor. Because everything is derived from the constructor, the catalog can never drift from the widget.

Annotate a plain data class with GenUiData to let an annotated widget take it, or a list of it, as a property.

The runtime helpers (GenUiBindings, GenUiBinding, GenUiValues, GenUiDecoder, genUiActionHandler, genUiValueWriter and genUiReportMissing) are used by the generated code and are exported here so that generated parts only need to import this library.

genUiCatalogJson and genUiCatalogJsonString go the other way: they turn the catalog the generator assembled into the A2UI catalog.json document, which is what an agent — or a client written in another language — reads to learn which components it may ask for.

S, Schema and ObjectSchema are re-exported from package:json_schema_builder, because the generated part builds its schema with them and shares this library's imports. If S collides with another one-letter name in your file (a generated localization class, say), import this library with hide S.

The same goes for the coercion helpers (genUiAsString, genUiAsNum, genUiAsBool, genUiAsStringList, genUiAsNumList, genUiAsObject, genUiAsObjectList) and the field reporters (GenUiMissingFieldReporter, genUiMissingField, genUiNestedField): generated decoders call them instead of casting, so a model that sends a number where a string was declared degrades exactly the way genui's Bound* widgets do rather than throwing inside build.

Classes

A2uiSchemas

Provides a set of pre-defined, reusable schema objects for common A2UI patterns, simplifying the creation of CatalogItem definitions.

Catalog

Represents a collection of UI components that a generative AI model can use to construct a user interface.

CatalogItem

Defines a UI layout type, its schema, and how to build its widget.

ClientFunction

GenUiAction

Marks a void Function() / VoidCallback parameter as a user action.

GenUiBinding

A typed description of how to resolve one property value.

GenUiBindings

Resolves a set of literal-or-bound values against a DataContext and calls builder once with all of them resolved.

GenUiChecked

Marks a parameter as the result of the component's validation checks.

GenUiCheckResult

What a component's validation checks say about it right now.

GenUiChecks

Evaluates a component's checks and rebuilds when the answer changes.

GenUiClientFunction

A ClientFunction whose schema and argument handling are generated.

GenUiData

Marks a plain Dart class as a data shape an annotated widget may receive.

GenUiFunction

Marks a top-level Dart function as a function of the A2UI catalog.

GenUiProp

Per-parameter overrides for a GenUiWidget constructor parameter.

GenUiValues

Typed accessors over the values resolved by GenUiBindings.

GenUiWidget

Marks a widget class as a GenUI catalog component.

GenUiWrites

Marks a void Function(T) parameter as writing the user's value back to the data model.

Enums

ClientFunctionReturnType

A function that can be invoked by the GenUI expression system.

Extension Types

ObjectSchema

A JSON Schema definition for an object with properties.

Schema

A JSON Schema object defining any kind of property.

Functions

genUiActionHandler(CatalogItemContext ctx, Object? actionData) → VoidCallback?

Builds a VoidCallback that performs an A2UI action the same way the core Button does.

genUiAsBool(Object? value) → bool?

value as a bool, or null when it cannot be read as one.

genUiAsBoolMap(Object? value) → Map<String, bool>?

value as a Map<String, bool>, or null when it is not an object.

genUiAsNum(Object? value) → num?

value as a num, or null when it cannot be read as one.

genUiAsNumList(Object? value) → List<num>?

value as a List<num>, or null when it is not a list.

genUiAsNumMap(Object? value) → Map<String, num>?

value as a Map<String, num>, or null when it is not an object.

genUiAsObject(Object? value) → Map<String, Object?>?

value as a JSON object, or null when it is not a map.

genUiAsObjectList(Object? value) → List<Map<String, Object?>>?

value as a list of JSON objects, or null when it is not a list.

genUiAsString(Object? value) → String?

value as a String, or null when it is null.

genUiAsStringList(Object? value) → List<String>?

value as a List<String>, or null when it is not a list.

genUiAsStringMap(Object? value) → Map<String, String>?

value as a Map<String, String>, or null when it is not an object.

genUiCatalogJson(Catalog catalog, {String? title, String? description}) → JsonMap

The A2UI catalog document that describes catalog.

genUiCatalogJsonString(Catalog catalog, {String? title, String? description, String indent = ' '}) → String

genUiCatalogJson, encoded as JSON indented with indent.

genUiMissingField<T>(GenUiMissingFieldReporter? onMissing, String field, T fallback) → T

Reports field through onMissing, if any, and returns fallback.

genUiNestedField(GenUiMissingFieldReporter? onMissing, String field) → GenUiMissingFieldReporter?

A reporter for the fields of the nested object held by field.

genUiReportMissing(CatalogItemContext ctx, String component, String property) → void

Reports that the required property of the component being built by ctx is missing or could not be converted, once per component instance.

genUiResetMissingReports() → void

Forgets every property reported so far, so it can be reported again.

genUiTemplateChildren(CatalogItemContext ctx, Object? reference, Object? resolved) → List<Widget>

The children reference describes.

genUiTemplatePath(Object? reference) → Object?

The path a child template reads from, in the shape a binding takes, or null when reference is a plain list of component ids.

genUiValueWriter<T>(CatalogItemContext ctx, Object? reference, String property, {Object? encode(T value)?}) → ValueChanged<T>

Builds the callback that writes a control's new value into the surface's data model, the way genui's own TextField, Slider and CheckBox do.

genUiWritePath(CatalogItemContext ctx, Object? reference, String property) → String

The data model path a control writes to for property.

genUiWriteReference(CatalogItemContext ctx, Object? raw, String property) → JsonMap

The {"path": ...} reference a writable property is read through.

Typedefs

GenUiAsyncFunctionBody = Future<Object?> Function(JsonMap args, ExecutionContext context)

The body of a catalog function that answers once, later.

GenUiDecoder<T> = T Function(Map<String, Object?> json)

Rebuilds a T from the JSON map the model produced for it.

GenUiFunctionBody = Object? Function(JsonMap args, ExecutionContext context)

The body of a synchronous catalog function.

GenUiMissingFieldReporter = void Function(String field)

Reports one field of a data object that was required but missing or unusable.

GenUiStreamFunctionBody = Stream<Object?> Function(JsonMap args, ExecutionContext context)

The body of a catalog function that keeps answering.

GenUiValuesWidgetBuilder = Widget Function(BuildContext context, GenUiValues values)

Signature of the builder invoked by GenUiBindings once every binding has been resolved.

JsonMap = Map<String, Object?>

A map of key-value pairs representing a JSON object.

S = Schema

A shortcut typedef so that Schema.object, etc. can be used as S.object.