genui_gen library

Annotations and runtime helpers for generating a2ui_flutter components from your own Flutter widgets.

Annotate a widget with GenUiWidget and run build_runner with genui_gen_builder to derive the JSON schema and the widget builder of a ComponentImplementation 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, and a top-level function with GenUiFunction to make it a function of the catalog.

Each generated component is a GenUiComponent, which carries the examples the generator wrote for it; genUiExampleInstructions puts them where an agent reads them, in the catalog's instructions.

a2ui_core resolves every property of a component against its schema before the widget is built, so the generated builder only reads what it resolved. The helpers it needs for the rest (GenUiSchemas, genUiWriter and genUiMissingIn) 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 rather than throwing inside build.

Classes

CommonSchemas
Dart builders for the v0.9 common_types.json definitions.
ComponentImplementation
A catalog component with a Flutter implementation.
DataContext
Provides data access relative to a specific path in the DataModel.
FunctionImplementation
A function implementation that can be registered with a catalog.
GenUiAction
Marks a void Function() / VoidCallback parameter as a user action.
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.
GenUiClientFunction
A FunctionImplementation whose schema and argument handling are generated.
GenUiComponent
A ComponentImplementation generated from an annotated widget, with the examples the generator wrote for it.
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.
GenUiSchemas
The schemas generated components describe their properties with.
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

A2uiReturnType
The type of value a function returns.

Extension Types

ComponentProps
Typed, non-throwing reads of a node's resolved properties.
ObjectSchema
A JSON Schema definition for an object with properties.
Schema
A JSON Schema object defining any kind of property.

Functions

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<ComponentApi, FunctionApi> catalog, {String? title, String? description}) → Map<String, Object?>
The A2UI catalog document that describes catalog.
genUiCatalogJsonString(Catalog<ComponentApi, FunctionApi> catalog, {String? title, String? description, String indent = ' '}) → String
genUiCatalogJson, encoded as JSON indented with indent.
genUiExampleInstructions(Iterable<ComponentImplementation> components) → String?
The instructions that show an agent an example of each component in components that has one, or null when none has.
genUiMissingField<T>(GenUiMissingFieldReporter? onMissing, String field, T fallback) → T
Reports field through onMissing, if any, and returns fallback.
genUiMissingIn(BuildContext context, ComponentNode<ComponentImplementation> node, String property) → GenUiMissingFieldReporter
The reporter a generated builder hands the decoder of a @GenUiData property of node.
genUiNestedField(GenUiMissingFieldReporter? onMissing, String field) → GenUiMissingFieldReporter?
A reporter for the fields of the nested object held by field.
genUiWriter<T>(BuildContext context, ComponentProps props, String property, {Object? encode(T value)?}) → ValueChanged<T>?
Builds the callback a @GenUiWrites parameter receives: one that writes the user's value to the data path property is bound to.

Typedefs

CatalogImplementation = Catalog<ComponentImplementation, FunctionImplementation>
A catalog whose components carry Flutter implementations.
GenUiAsyncFunctionBody = Future<Object?> Function(Map<String, Object?> args, DataContext context)
The body of a catalog function that answers once, later.
GenUiFunctionBody = Object? Function(Map<String, Object?> args, DataContext 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(Map<String, Object?> args, DataContext context)
The body of a catalog function that keeps answering.
S = Schema
A shortcut typedef so that Schema.object, etc. can be used as S.object.