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.jsondefinitions. - 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()/VoidCallbackparameter 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? -
valueas abool, ornullwhen it cannot be read as one. -
genUiAsBoolMap(
Object? value) → Map< String, bool> ? -
valueas aMap<String, bool>, ornullwhen it is not an object. -
genUiAsNum(
Object? value) → num? -
valueas anum, ornullwhen it cannot be read as one. -
genUiAsNumList(
Object? value) → List< num> ? -
valueas aList<num>, ornullwhen it is not a list. -
genUiAsNumMap(
Object? value) → Map< String, num> ? -
valueas aMap<String, num>, ornullwhen it is not an object. -
genUiAsObject(
Object? value) → Map< String, Object?> ? -
valueas a JSON object, ornullwhen it is not a map. -
genUiAsObjectList(
Object? value) → List< Map< ?String, Object?> > -
valueas a list of JSON objects, ornullwhen it is not a list. -
genUiAsString(
Object? value) → String? -
valueas aString, ornullwhen it isnull. -
genUiAsStringList(
Object? value) → List< String> ? -
valueas aList<String>, ornullwhen it is not a list. -
genUiAsStringMap(
Object? value) → Map< String, String> ? -
valueas aMap<String, String>, ornullwhen 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
componentsthat has one, ornullwhen none has. -
genUiMissingField<
T> (GenUiMissingFieldReporter? onMissing, String field, T fallback) → T -
Reports
fieldthroughonMissing, if any, and returnsfallback. -
genUiMissingIn(
BuildContext context, ComponentNode< ComponentImplementation> node, String property) → GenUiMissingFieldReporter -
The reporter a generated builder hands the decoder of a
@GenUiDatapropertyofnode. -
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
@GenUiWritesparameter receives: one that writes the user's value to the data pathpropertyis 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 asS.object.