flutter · victoreronmosele · Nov 14, 2025 · Nov 20, 2025
diff --git a/packages/genui/lib/src/catalog/core_widgets/audio_player.dart b/packages/genui/lib/src/catalog/core_widgets/audio_player.dart
@@ -9,6 +9,12 @@ import '../../model/a2ui_schemas.dart';
 import '../../model/catalog_item.dart';
 
 final _schema = S.object(
+  description: '''
+A catalog item for an audio player.
+
+This widget displays a placeholder for an audio player, used to represent
+a component capable of playing audio from a given URL.
+''',
   properties: {
     'url': A2uiSchemas.stringReference(
       description: 'The URL of the audio to play.',

diff --git a/packages/genui/lib/src/catalog/core_widgets/button.dart b/packages/genui/lib/src/catalog/core_widgets/button.dart
@@ -15,6 +15,13 @@ import '../../primitives/logging.dart';
 import '../../primitives/simple_items.dart';
 
 final _schema = S.object(
+  description: '''
+A catalog item representing an elevated button.
+
+This widget displays an interactive button. When pressed, it dispatches
+the specified `action` event. The button's appearance can be styled as
+a primary action.
+''',
   properties: {
     'child': A2uiSchemas.componentReference(
       description:

diff --git a/packages/genui/lib/src/catalog/core_widgets/card.dart b/packages/genui/lib/src/catalog/core_widgets/card.dart
@@ -10,6 +10,9 @@ import '../../model/catalog_item.dart';
 import '../../primitives/simple_items.dart';
 
 final _schema = S.object(
+  description: '''
+A catalog item representing a card.
+''',
   properties: {'child': A2uiSchemas.componentReference()},
   required: ['child'],
 );

diff --git a/packages/genui/lib/src/catalog/core_widgets/check_box.dart b/packages/genui/lib/src/catalog/core_widgets/check_box.dart
@@ -12,6 +12,13 @@ import '../../model/data_model.dart';
 import '../../primitives/simple_items.dart';
 
 final _schema = S.object(
+  description: '''
+A catalog item representing a checkbox with a label.
+
+This widget displays a checkbox a [Text] label. The checkbox's state
+is bidirectionally bound to the data model path specified in the `value`
+parameter.
+''',
   properties: {
     'label': A2uiSchemas.stringReference(),
     'value': A2uiSchemas.booleanReference(),

diff --git a/packages/genui/lib/src/catalog/core_widgets/column.dart b/packages/genui/lib/src/catalog/core_widgets/column.dart
@@ -13,6 +13,10 @@ import '../../primitives/simple_items.dart';
 import 'widget_helpers.dart';
 
 final _schema = S.object(
+  description: '''
+A catalog item representing a layout widget that displays its children in a
+vertical array.
+''',
   properties: {
     'distribution': S.string(
       description: 'How children are aligned on the main axis. ',

diff --git a/packages/genui/lib/src/catalog/core_widgets/date_time_input.dart b/packages/genui/lib/src/catalog/core_widgets/date_time_input.dart
@@ -12,6 +12,13 @@ import '../../model/data_model.dart';
 import '../../primitives/simple_items.dart';
 
 final _schema = S.object(
+  description: '''
+A catalog item representing a date and/or time input field.
+
+This widget displays a field that, when tapped, opens the native date and/or
+time pickers. The selected value is stored as a string in the data model
+path specified by the `value` parameter.
+''',
   properties: {
     'value': A2uiSchemas.stringReference(
       description: 'The selected date and/or time.',

diff --git a/packages/genui/lib/src/catalog/core_widgets/divider.dart b/packages/genui/lib/src/catalog/core_widgets/divider.dart
@@ -9,6 +9,9 @@ import '../../model/catalog_item.dart';
 import '../../primitives/simple_items.dart';
 
 final _schema = S.object(
+  description: '''
+A catalog item representing a divider.
+''',
   properties: {
     'axis': S.string(enumValues: ['horizontal', 'vertical']),
   },

diff --git a/packages/genui/lib/src/catalog/core_widgets/icon.dart b/packages/genui/lib/src/catalog/core_widgets/icon.dart
@@ -11,6 +11,9 @@ import '../../model/data_model.dart';
 import '../../primitives/simple_items.dart';
 
 final _schema = S.object(
+  description: '''
+A catalog item for an icon.
+''',
   properties: {
     'name': A2uiSchemas.stringReference(
       description:

diff --git a/packages/genui/lib/src/catalog/core_widgets/image.dart b/packages/genui/lib/src/catalog/core_widgets/image.dart
@@ -41,7 +41,15 @@ Schema _schema({required bool enableUsageHint}) {
       ],
     );
   }
-  return S.object(properties: properties);
+  return S.object(
+    description: '''
+A catalog item representing a widget that displays an image.
+
+The image source is specified by the `url` parameter, which can be a network
+URL (e.g., `https://...`) or a local asset path (e.g., `assets/...`).
+''',
+    properties: properties,
+  );
 }
 
 extension type _ImageData.fromMap(JsonMap _json) {

diff --git a/packages/genui/lib/src/catalog/core_widgets/list.dart b/packages/genui/lib/src/catalog/core_widgets/list.dart
@@ -12,6 +12,9 @@ import '../../primitives/simple_items.dart';
 import 'widget_helpers.dart';
 
 final _schema = S.object(
+  description: '''
+A catalog item representing a scrollable list of widgets.
+''',
   properties: {
     'children': A2uiSchemas.componentArrayReference(),
     'direction': S.string(enumValues: ['vertical', 'horizontal']),

diff --git a/packages/genui/lib/src/catalog/core_widgets/modal.dart b/packages/genui/lib/src/catalog/core_widgets/modal.dart
@@ -12,6 +12,14 @@ import '../../model/catalog_item.dart';
 import '../../primitives/simple_items.dart';
 
 final _schema = S.object(
+  description: '''
+A catalog item representing a modal bottom sheet.
+
+This component doesn't render the modal content directly. Instead, it
+renders the `entryPointChild` widget. The `entryPointChild` is expected to
+trigger an action (e.g., on button press) that causes the `contentChild` to
+be displayed within a modal bottom sheet by the [GenUiSurface].
+''',
   properties: {
     'entryPointChild': A2uiSchemas.componentReference(
       description: 'The widget that opens the modal.',

diff --git a/packages/genui/lib/src/catalog/core_widgets/multiple_choice.dart b/packages/genui/lib/src/catalog/core_widgets/multiple_choice.dart
@@ -12,6 +12,13 @@ import '../../model/data_model.dart';
 import '../../primitives/simple_items.dart';
 
 final _schema = S.object(
+  description: '''
+A catalog item representing a multiple choice selection widget.
+
+This widget displays a list of options, each with a checkbox. The
+`selections` parameter, which should be a data model path, is updated to
+reflect the list of *values* of the currently selected options.
+''',
   properties: {
     'selections': A2uiSchemas.stringArrayReference(),
     'options': S.list(

diff --git a/packages/genui/lib/src/catalog/core_widgets/row.dart b/packages/genui/lib/src/catalog/core_widgets/row.dart
@@ -12,6 +12,10 @@ import '../../primitives/simple_items.dart';
 import 'widget_helpers.dart';
 
 final _schema = S.object(
+  description: '''
+A catalog item representing a layout widget that displays its children in a
+horizontal array.
+''',
   properties: {
     'children': A2uiSchemas.componentArrayReference(
       description:

diff --git a/packages/genui/lib/src/catalog/core_widgets/slider.dart b/packages/genui/lib/src/catalog/core_widgets/slider.dart
@@ -12,6 +12,12 @@ import '../../model/data_model.dart';
 import '../../primitives/simple_items.dart';
 
 final _schema = S.object(
+  description: '''
+A catalog item representing a slider.
+
+This widget allows the user to select a value from a range by sliding a
+thumb along a track. The `value` is bidirectionally bound to the data model.
+''',
   properties: {
     'value': A2uiSchemas.numberReference(),
     'minValue': S.number(),

diff --git a/packages/genui/lib/src/catalog/core_widgets/tabs.dart b/packages/genui/lib/src/catalog/core_widgets/tabs.dart
@@ -11,6 +11,13 @@ import '../../model/catalog_item.dart';
 import '../../primitives/simple_items.dart';
 
 final _schema = S.object(
+  description: '''
+A catalog item representing a tab layout.
+
+This widget displays a [TabBar] and a [TabBarView] to allow navigation
+between different child components. Each tab in `tabItems` has a title and
+a corresponding child component ID to display when selected.
+''',
   properties: {
     'tabItems': S.list(
       items: S.object(

diff --git a/packages/genui/lib/src/catalog/core_widgets/text.dart b/packages/genui/lib/src/catalog/core_widgets/text.dart
@@ -33,6 +33,13 @@ extension type _TextData.fromMap(JsonMap _json) {
 final text = CatalogItem(
   name: 'Text',
   dataSchema: S.object(
+    description: '''
+A catalog item representing a block of styled text.
+
+This widget displays a string of text. The content is taken from the `text`
+parameter, which can be a literal
+string or a data model binding.
+''',
     properties: {
       'text': A2uiSchemas.stringReference(
         description:

diff --git a/packages/genui/lib/src/catalog/core_widgets/text_field.dart b/packages/genui/lib/src/catalog/core_widgets/text_field.dart
@@ -13,6 +13,12 @@ import '../../model/ui_models.dart';
 import '../../primitives/simple_items.dart';
 
 final _schema = S.object(
+  description: '''
+A catalog item representing a text field.
+
+This widget allows the user to enter and edit text. The `text` parameter
+bidirectionally binds the field's content to the data model.
+''',
   properties: {
     'text': A2uiSchemas.stringReference(
       description: 'The initial value of the text field.',

diff --git a/packages/genui/lib/src/catalog/core_widgets/video.dart b/packages/genui/lib/src/catalog/core_widgets/video.dart
@@ -9,6 +9,12 @@ import '../../model/a2ui_schemas.dart';
 import '../../model/catalog_item.dart';
 
 final _schema = S.object(
+  description: '''
+A catalog item representing a video player.
+
+This widget currently displays a placeholder for a video player. It is
+intended to play video content from the given `url`.
+''',
   properties: {
     'url': A2uiSchemas.stringReference(
       description: 'The URL of the video to play.',