genui library
The generative UI framework (GenUI) for Flutter and Dart.
This library provides the necessary components to build generative user interfaces in Flutter applications. It implements the A2UI protocol (https://a2ui.org), and includes an object model for UI components, data handling, and provides transport for communicating with generative AI services (agents and LLMs).
Classes
- A2UiClientCapabilities
- Describes the client's UI rendering capabilities to the server.
- A2uiMessage
- A sealed class representing a message in the A2UI stream.
- A2uiMessageEvent
- An event containing a parsed A2uiMessage.
- A2uiMessageSink
- An interface for a message sink that accepts A2uiMessages.
- A2uiParserTransformer
- Transforms a stream of text chunks into a stream of logical GenerationEvents.
- A2uiSchemas
- Provides a set of pre-defined, reusable schema objects for common A2UI patterns, simplifying the creation of CatalogItem definitions.
- A2uiTransportAdapter
- The primary high-level API for typical Flutter application development.
- ActionDelegate
- A delegate for handling UI actions in Surface.
- AndFunction
- Checks if all values in a list are truthy.
- BasicCatalogItems
- A collection of basic catalog items that can be used to build simple interactive UIs.
- BasicFunctions
- A collection of basic client-side functions.
- BoundBool
- Binds to a bool value.
- BoundList
- Binds to a List of objects.
- BoundNumber
- Binds to a num value.
- BoundObject
- Binds to any Object value.
- BoundString
- Binds to a String value.
-
BoundValue<
T> - A widget that binds to a value in the DataContext and rebuilds when it changes.
-
BoundValueState<
T, W extends BoundValue< T> > - State class for BoundValue.
- CancellationSignal
- A signal that can be used to cancel an operation.
- 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.
- CatalogItemContext
- Context provided to a CatalogItem's widget builder.
- ChatMessage
- A chat message.
- ChatMessageView
- A widget to display a chat message.
- ClientFunction
- Component
- A component in the UI.
- ComponentChildrenBuilder
- A helper widget to build widgets from component data that contains a list of children.
- ComponentsUpdated
- Fired when an existing surface is modified.
- Conversation
- Facade for managing a GenUI conversation.
- ConversationComponentsUpdated
- Fired when components are updated on a surface.
- ConversationContentReceived
- Fired when new content (text) is received from the LLM.
- ConversationError
- Fired when an error occurs during the conversation.
- ConversationEvent
- Events emitted by Conversation to notify listeners of changes.
- ConversationState
- State of the conversation.
- ConversationSurfaceAdded
- Fired when a new surface is added.
- ConversationSurfaceRemoved
- Fired when a surface is removed.
- ConversationWaiting
- Fired when a request is sent to the LLM and the conversation is waiting for an AI response.
- CreateSurface
- An A2UI message that signals the client to create and show a new surface.
- DataContext
- A contextual view of the main DataModel, used by widgets to resolve relative and absolute paths.
- DataModel
- Manages the application's data model and provides a subscription-based mechanism for reactive UI updates.
- DataModelStore
- Manages the data models for surfaces.
- DataPart
- A data part containing binary data (e.g., images).
- DataPath
- Represents a path in the data model, either absolute or relative.
- DebugCatalogView
- A widget that displays a catalog of GenUI components.
- DefaultActionDelegate
- The default action delegate that handles standard actions like 'showModal'.
- DeleteSurface
- An A2UI message that deletes a surface.
- EmailFunction
- Checks if a string is a valid email.
- ExecutionContext
- An execution context for client functions, providing access to data and other functions.
- ExpressionParser
-
Parses and evaluates expressions in the A2UI
${expression}format. - FallbackWidget
- A widget that displays a fallback UI for error or loading states.
- FormatCurrencyFunction
- Formats a currency value.
- FormatDateFunction
- Formats a date.
- FormatNumberFunction
- Formats a number.
- FormatStringFunction
- Formats a value as a string.
- GenerationEvent
- A base class for events related to the GenUI generation process.
- InMemoryDataModel
- Standard in-memory implementation of DataModel.
- InternalMessageView
- A widget to display an internal message in the chat.
- JsonBlockParser
- Utilities for parsing JSON blocks from text, commonly used when extracting structured data from LLM text responses.
- LengthFunction
- Returns the length of a string, list, or map.
- LinkPart
- A link part referencing external content.
- NotFunction
- Negates a boolean value.
- NumericFunction
- Checks if a value is numeric and optionally within a range.
- OpenUrlFunction
- Opens a URL.
-
OptionalValueBuilder<
T> -
A builder widget that simplifies handling of nullable
ValueListenables. - OrFunction
- Checks if any value in a list is truthy.
- Part
- Base class for message content parts.
-
PartConverter<
T extends Part> - A converter that converts a JSON map to a Part.
- Parts
- A collection of parts.
- PluralizeFunction
- Pluralizes a word based on a count.
- PromptBuilder
- A builder for a prompt to generate UI.
- PromptFragments
- Common fragments for prompts, to explain agent behavior.
- RegexFunction
- Checks if a string matches a regex pattern.
- RegistryEvent
- Events emitted by the SurfaceRegistry.
- RequiredFunction
- Checks if a value is present and not empty.
- StandardPart
- Base class for parts that became de-facto standard for AI messages.
- Surface
- A widget that renders a dynamic UI surface generated by the AI.
- SurfaceAdded
- Fired when a new surface is created.
- SurfaceContext
- An interface for a specific UI surface context.
- SurfaceController
- The runtime controller for the GenUI system.
- SurfaceDefinition
- A data object that represents the entire UI definition.
- SurfaceHost
- An interface for a host that manages UI surfaces.
- SurfaceOperations
- Pieces of prompt that defines allowed surface operations.
- SurfaceRegistry
- Manages the lifecycle and storage of SurfaceDefinitions.
- SurfaceRemoved
- Fired when a surface is deleted.
- SurfaceUpdate
- A sealed class representing an update to the UI managed by the system.
- SurfaceUpdated
- An event indicating that a surface has been updated.
- SynchronousClientFunction
- A base class for synchronous client functions.
- TechnicalPossibilities
- TextEvent
- An event containing a text chunk from the LLM.
- TextPart
- A text part of a message.
- ThinkingPart
- A "thinking" part of a message, used by some models to show reasoning.
-
ToolDefinition<
TInput extends Object> - A tool that can be called by the LLM.
- ToolPart
- A tool interaction part of a message.
- Transport
- An interface for transporting messages between GenUI and an AI service.
- UiInteractionPart
- A view over a DataPart representing a UI interaction.
- UiPart
- A view over a DataPart representing a UI definition.
- UiPartConstants
- Constants for UI related parts.
- UpdateComponents
- An A2UI message that updates a surface with new components.
- UpdateDataModel
- An A2UI message that updates the data model.
- ValidationError
- A validation error with a message.
- ValidationHelper
- A helper class for handling reactive validation logic.
Enums
- AvailableIcons
- ChatMessageRole
- The role of a message author.
- ClientFunctionReturnType
- A function that can be invoked by the GenUI expression system.
- InlineCatalogHandling
- Defines how catalogs should be handled when generating client capabilities.
- ProtocolMessages
- ToolPartKind
- The kind of tool interaction.
Extension Types
- UiEvent
- A data object that represents a user interaction event in the UI.
- UserActionEvent
- A UI event that represents a user action.
Extensions
- ChatMessageFactories on ChatMessage
-
Extension to help with
UserMessageusages if needed, or just helper factories. -
CombineLatestAll
on Iterable<
Stream< T> > - Extensions for Iterable of Streams.
- UiPartExtension on StandardPart
- Helper extension to interact with UI parts.
-
UiPartListExtension
on Iterable<
StandardPart>
Constants
- basicCatalogId → const String
- The catalog ID for the basic catalog.
-
defaultPartConverterRegistry
→ const Map<
String, JsonToPartConverter< Part> > - Converter registry for parts in this package.
- surfaceIdKey → const String
- Key used in schema definition to specify the component ID.
Properties
- audioPlayer → CatalogItem
-
A simple audio player.
final
-
A Material Design elevated button.
final
- card → CatalogItem
-
A Material Design card.
final
- checkBox → CatalogItem
-
A Material Design checkbox with a label.
final
- choicePicker → CatalogItem
-
A component that allows selecting one or more options from a list.
final
- column → CatalogItem
-
A layout widget that arranges its children in a vertical sequence.
final
- dateTimeInput → CatalogItem
-
A widget for selecting a date and/or time.
final
- divider → CatalogItem
-
A thin horizontal or vertical line used to separate content.
final
- genUiLogger → Logger
-
The logger for the GenUI package.
final
- icon → CatalogItem
-
A standard icon.
final
- image → CatalogItem
-
A UI element for displaying image data from a URL or other source.
The image source is specified by the
urlparameter, which can be a network URL (e.g.,https://...) or a local asset path (e.g.,assets/...).final - list → CatalogItem
-
A scrollable list of child widgets.
final
- modal → CatalogItem
-
A modal overlay that slides up from the bottom of the screen.
final
- row → CatalogItem
-
A layout widget that arranges its children in a horizontal sequence.
final
- slider → CatalogItem
-
A Material Design slider.
final
- tabs → CatalogItem
-
A Material Design tab layout.
final
- text → CatalogItem
-
A block of styled text.
final
- textField → CatalogItem
-
A Material Design text field.
final
Functions
-
buildWeightedChild(
{required String componentId, required DataContext dataContext, required ChildBuilderCallback buildChild, required int? weight, Key? key, FlexFit flexFit = FlexFit.loose}) → Widget - Builds a child widget, wrapping it in a Flexible if a weight is provided in the component.
-
checksToExpression(
List< JsonMap> ? checks) → Object? - Converts a list of validation checks into a single expression that evaluates to true if all checks pass.
-
configureLogging(
{Level level = Level.INFO, void logCallback(Level, String)?, bool enableHierarchicalLogging = true}) → Logger - Configures the logging for the GenUI package.
-
formatDuration(
Duration d) → String -
Formats a Duration as
mm:ssorh:mm:ssif longer than an hour. -
generateId(
) → String - Generates a unique ID (UUID v4).
-
resolveContext(
DataContext dataContext, JsonMap? contextDefinition) → Future< JsonMap> - Resolves a context map definition against a DataContext.
Typedefs
- CatalogWidgetBuilder = Widget Function(CatalogItemContext itemContext)
- A callback that builds a widget for a catalog item.
- ChildBuilderCallback = Widget Function(String id, [DataContext? dataContext])
- A callback that builds a child widget for a catalog item.
- DispatchEventCallback = void Function(UiEvent event)
- A callback that is called when an event is dispatched.
- ExampleBuilderCallback = String Function()
- A callback that builds an example of a catalog item.
-
ExplicitListWidgetBuilder
= Widget Function(List<
String> childIds, ChildBuilderCallback buildChild, GetComponentCallback getComponent, DataContext dataContext) -
Builder function for creating a parent widget given a list of pre-built
childIds. - GetComponentCallback = Component? Function(String componentId)
- A callback to get a component definition by its ID.
-
JsonMap
= Map<
String, Object?> - A map of key-value pairs representing a JSON object.
-
JsonToPartConverter<
T extends Part> = Converter< Map< String, Object?> , T> -
ManualSendCallback
= Future<
void> Function(ChatMessage message) - A manual sender callback.
-
SendEventsCallback
= void Function(String surfaceId, List<
UiEvent> events) - A callback that is called when events are sent.
- TemplateListWidgetBuilder = Widget Function(BuildContext context, Object? data, String componentId, String path)
- Builder function for creating a widget from a template and a list of data.
- UiEventCallback = void Function(UiEvent event)
- A callback for when a user interacts with a widget.
Exceptions / Errors
- A2uiValidationException
- Exception thrown when validation fails.
- CancellationException
- An exception thrown when an operation is cancelled.
- CatalogItemNotFoundException
- An exception thrown when a requested item is not found in the Catalog.
- DataModelTypeException
- Exception thrown when a value in the DataModel is not of the expected type.
- RecursionExpectedException
- Exception thrown when the maximum recursion depth is exceeded.