Migrate UI events to use new format.

[gspencergoog]

Description

Convert user events to use userAction.

Summary of Changes

This pull request significantly refactors the way user interactions are handled within the flutter_genui framework. By introducing a dedicated UserActionEvent with explicit action names and a flexible, data-bound context, it standardizes and enriches the information passed from the UI to the AI. This change improves the clarity and robustness of event processing, with corresponding updates across examples, core widgets, and documentation to ensure a seamless transition to the new event format.

Highlights

• Event Model Refactor: The core UI event handling mechanism has been refactored, replacing the generic UiActionEvent with a more structured UserActionEvent. This new event type now explicitly includes actionName, sourceComponentId, and a flexible context map for data binding.
• Data-Bound Context: The UserActionEvent's context now supports data binding, allowing values to be resolved from the DataContext using paths, or provided as literal strings, numbers, or booleans. A new resolveContext utility function has been introduced to facilitate this.
• GenUiManager Integration: The GenUiManager's handleUiEvent method has been updated to correctly process the new UserActionEvent format. It now constructs a UserMessage with a JSON payload that includes the detailed user action and the current state of the UI surface.
• Widget and Example Updates: Numerous core widgets (ElevatedButton, TextField) and example applications (catalog_gallery, simple_chat, travel_app) have been migrated to utilize the new UserActionEvent and its associated action schema, ensuring consistency across the framework.
• Documentation Alignment: Documentation files (IMPLEMENTATION.md, README.md) have been updated to reflect the changes in the event handling architecture and the updated component catalog descriptions.

Changelog

• examples/catalog_gallery/lib/main.dart
  • Converted CatalogGalleryApp to a StatefulWidget to manage state.
  • Added an onSubmit callback to DebugCatalogView to display user actions as snackbar messages.
• examples/simple_chat/lib/main.dart
  • Modified _sendMessage to return void and used unawaited for _uiAgent.sendRequest to handle asynchronous operations without awaiting.
• examples/travel_app/IMPLEMENTATION.md
  • Updated the list of custom UI components, adding DateInputChip, ListingsBooker, PaddedBodyText, SectionHeader, and TabbedSections.
  • Revised the data flow diagram description to accurately reflect the new event dispatch mechanism.
• examples/travel_app/README.md
  • Updated references to component catalog examples and the location of the system prompt.
• examples/travel_app/lib/src/catalog/input_group.dart
  • Introduced an action property to the _InputGroupData schema and factory.
  • Updated the ElevatedButton's onPressed handler to dispatch a UserActionEvent with a resolved context.
• examples/travel_app/lib/src/catalog/itinerary_entry.dart
  • Added a choiceRequiredAction property to the _ItineraryEntryData schema and factory.
  • Modified the FilledButton's onPressed to dispatch a UserActionEvent with a resolved context.
  • Adjusted vertical and horizontal padding for the itinerary entry.
• examples/travel_app/lib/src/catalog/itinerary_with_details.dart
  • Minor formatting adjustment for borderRadius in ClipRRect.
• examples/travel_app/lib/src/catalog/listings_booker.dart
  • Added a modifyAction property to the _ListingsBookerData schema and factory.
  • Updated the TextButton's onPressed to dispatch a UserActionEvent with a resolved context, including the listingSelectionId.
• examples/travel_app/lib/src/catalog/trailhead.dart
  • Added an action property to the _TrailheadData schema and factory.
  • Modified the InputChip's onPressed to dispatch a UserActionEvent with a resolved context, including the selected topic.
• examples/travel_app/lib/src/catalog/travel_carousel.dart
  • Added an action property to the _TravelCarouselItemSchemaData schema and factory.
  • Updated the InkWell's onTap to dispatch a UserActionEvent with a resolved context, including description and listingSelectionId.
  • Updated example data to include the new action field.
• examples/travel_app/test/input_group_test.dart
  • Updated test data to include the new action field.
  • Changed assertions from UiActionEvent to UserActionEvent and verified actionName and sourceComponentId.
• examples/travel_app/test/trailhead_test.dart
  • Updated test data to include the new action field.
  • Changed assertions from UiActionEvent to UserActionEvent and verified actionName and context.
• examples/travel_app/test/travel_carousel_test.dart
  • Updated test data to include the new action field.
  • Changed assertions from UiActionEvent to UserActionEvent and verified actionName and context.
• packages/flutter_genui/IMPLEMENTATION.md
  • Updated the ChatMessage description to include UserUiInteractionMessage.
  • Clarified the UiAgent initialization and event dispatch steps in the data flow.
• packages/flutter_genui/README.md
  • Removed the onEvent callback from the GenUiSurface example, as event handling is now managed differently.
• packages/flutter_genui/lib/src/catalog/core_widgets/column.dart
  • Updated the example Column widget definition to use the new action format for ElevatedButton.
• packages/flutter_genui/lib/src/catalog/core_widgets/elevated_button.dart
  • Changed the action property in the schema from a simple string to GulfSchemas.action for structured event data.
  • Updated the ElevatedButton's onPressed handler to dispatch a UserActionEvent with a resolved context.
  • Added exampleData for better demonstration and testing.
• packages/flutter_genui/lib/src/catalog/core_widgets/text_field.dart
  • Added an onSubmittedAction property to the _TextFieldData schema and factory.
  • Updated the onSubmitted callback to dispatch a UserActionEvent with a resolved context.
• packages/flutter_genui/lib/src/core/genui_manager.dart
  • Modified handleUiEvent to specifically process UserActionEvent instances.
  • Constructs a UserMessage with a JSON payload containing detailed user action information and the current UI state.
• packages/flutter_genui/lib/src/core/genui_surface.dart
  • Modified _dispatchEvent to correctly cast UserActionEvent when re-creating the event with the surfaceId.
• packages/flutter_genui/lib/src/core/widget_utilities.dart
  • Added a new resolveContext utility function to resolve data-bound context definitions from a DataContext.
• packages/flutter_genui/lib/src/model/gulf_schemas.dart
  • Refactored the action schema to use actionName (string) and context (object with data-bound properties) instead of a single action string and a list of key-value pairs.
• packages/flutter_genui/lib/src/model/ui_models.dart
  • Renamed UiActionEvent to UserActionEvent.
  • Changed event properties from widgetId, eventType, and value to actionName, sourceComponentId, and context.
• packages/flutter_genui/test/catalog/core_widgets_test.dart
  • Updated test data for ElevatedButton and TextField to include action and onSubmittedAction respectively.
• packages/flutter_genui/test/core/genui_manager_test.dart
  • Added a new test case for handleUiEvent to verify the correct processing of UserActionEvent and the creation of UserMessage.
• packages/flutter_genui/test/genui_surface_test.dart
  • Updated test data for ElevatedButton to include the new action field.
• packages/flutter_genui/test/model/ui_models_test.dart
  • Renamed the test group from UiEvent to UserActionEvent.
  • Updated tests to reflect the new properties of UserActionEvent (actionName, sourceComponentId, context).

Related Issues

• Fixes [A2UI] Update UI event format to conform to A2UI ClientEvent schema #356

[andrewkolos]

LGTM