feat(a2ui_flutter): add the gallery app

dart/a2ui_flutter/README.md

@@ -291,6 +291,12 @@ registered catalog, whatever its protocol version. Once surfaces of both
 versions send their data model, `getRendererDataModel()` needs a version,
 so a v1.0 agent reads it with `version: A2uiProtocolVersion.v1_0`.
 
+## Gallery
+
+[a2ui_explorer](a2ui_explorer) is the gallery app. It renders the v0.9 and
+v1.0 basic catalog examples and steps through their messages, next to each
+surface's data model and a log of actions and errors.
+
 ## Tests
 
 `test/catalog/basic/examples_test.dart` renders every

dart/a2ui_flutter/a2ui_explorer/.gitignore

@@ -0,0 +1,48 @@
+# Miscellaneous
+*.class
+*.log
+*.pyc
+*.swp
+.DS_Store
+.atom/
+.build/
+.buildlog/
+.history
+.svn/
+.swiftpm/
+migrate_working_dir/
+
+# IntelliJ related
+*.iml
+*.ipr
+*.iws
+.idea/
+
+# The .vscode folder contains launch configuration and tasks you configure in
+# VS Code which you may wish to be included in version control, so this line
+# is commented out by default.
+#.vscode/
+
+# Flutter/Dart/Pub related
+**/doc/api/
+**/ios/Flutter/.last_build_id
+.dart_tool/
+.flutter-plugins-dependencies
+.pub-cache/
+.pub/
+/build/
+/coverage/
+
+# Symbolication related
+app.*.symbols
+
+# Obfuscation related
+app.*.map.json
+
+# Android Studio will place build artifacts here
+/android/app/debug
+/android/app/profile
+/android/app/release
+
+# Widget Preview related
+.widget_preview/

dart/a2ui_flutter/a2ui_explorer/.metadata

@@ -0,0 +1,33 @@
+# This file tracks properties of this Flutter project.
+# Used by Flutter tool to assess capabilities and perform upgrades etc.
+#
+# This file should be version controlled and should not be manually edited.
+
+version:
+  revision: "d3b14c876900e553bc736ca19295fc09e3853e8e"
+  channel: "stable"
+
+project_type: app
+
+# Tracks metadata for the flutter migrate command
+migration:
+  platforms:
+    - platform: root
+      create_revision: d3b14c876900e553bc736ca19295fc09e3853e8e
+      base_revision: d3b14c876900e553bc736ca19295fc09e3853e8e
+    - platform: macos
+      create_revision: d3b14c876900e553bc736ca19295fc09e3853e8e
+      base_revision: d3b14c876900e553bc736ca19295fc09e3853e8e
+    - platform: web
+      create_revision: d3b14c876900e553bc736ca19295fc09e3853e8e
+      base_revision: d3b14c876900e553bc736ca19295fc09e3853e8e
+
+  # User provided section
+
+  # List of Local paths (relative to this file) that should be
+  # ignored by the migrate tool.
+  #
+  # Files that are not part of the templates will be ignored by default.
+  unmanaged_files:
+    - 'lib/main.dart'
+    - 'ios/Runner.xcodeproj/project.pbxproj'

dart/a2ui_flutter/a2ui_explorer/README.md

@@ -0,0 +1,39 @@
+# A2UI Flutter Explorer
+
+The gallery app of the Flutter renderer for protocols v0.9 and v1.0,
+following the
+[framework adapter blueprint](../../../blueprints/modules/a2ui_framework_adapter.blueprint.md).
+The left column lists the basic catalog examples of the selected version:
+[v0.9](../../../specification/v0_9/catalogs/basic/examples) or
+[v1.0](../../../catalogs/basic/v1/examples). The center column shows the
+selected example's surfaces above its messages, each message marked
+processed or pending. The right column shows each surface's data model as it
+changes, above a log of the actions the surfaces send and the errors the
+surfaces and the message processor report.
+
+## Running
+
+From this directory:
+
+```bash
+flutter run -d macos
+flutter run -d chrome
+```
+
+Selecting an example processes all of its messages. Reset starts it over with
+none processed, Advance processes the next one, and Run all processes the
+rest. Selecting the other version opens the example of the same file name in
+it, or its first example.
+
+## Tests
+
+```bash
+flutter test
+```
+
+## Examples
+
+`assets/examples/v0_9` and `assets/examples/v1_0` link to each version's
+examples, so the app bundles them as they are. On Windows, the links need a
+clone made with `git clone -c core.symlinks=true` and Developer Mode turned
+on.

dart/a2ui_flutter/a2ui_explorer/assets/examples/v0_9

@@ -0,0 +1 @@
+../../../../../specification/v0_9/catalogs/basic/examples

dart/a2ui_flutter/a2ui_explorer/assets/examples/v1_0

@@ -0,0 +1 @@
+../../../../../catalogs/basic/v1/examples

dart/a2ui_flutter/a2ui_explorer/lib/main.dart

@@ -0,0 +1,24 @@
+// Copyright 2024 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import 'package:flutter/services.dart';
+import 'package:flutter/widgets.dart';
+
+import 'src/example.dart';
+import 'src/explorer_app.dart';
+
+Future<void> main() async {
+  WidgetsFlutterBinding.ensureInitialized();
+  runApp(ExplorerApp(examples: await loadExamples(rootBundle)));
+}

dart/a2ui_flutter/a2ui_explorer/lib/src/demo_catalog.dart

@@ -0,0 +1,141 @@
+// Copyright 2024 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import 'dart:async';
+import 'dart:math' as math;
+
+import 'package:a2ui_core/a2ui_core.dart';
+import 'package:a2ui_flutter/a2ui_flutter.dart';
+import 'package:a2ui_flutter/v0_9/basic_catalog.dart';
+// ignore: deprecated_member_use, see https://github.com/a2ui-project/a2ui/issues/3235
+import 'package:flutter/material.dart';
+import 'package:json_schema_builder/json_schema_builder.dart';
+
+/// The basic catalog under its own id, with the custom components the
+/// examples name: `CustomGrid` and `CustomSlider`.
+final CatalogImplementation demoCatalog = basicCatalog().copyWith(
+  components: [...BasicComponents.all, customGrid, customSlider],
+);
+
+final Schema _dynamicNumber = Schema.fromMap({
+  r'$ref':
+      'https://a2ui.org/specification/v0_9/common_types.json#/\$defs/DynamicNumber',
+});
+
+/// A `CustomGrid`: its `title` and `description` over its `children` in two
+/// columns, as wide as the screen when the incoming width is unbounded.
+final ComponentImplementation customGrid = ComponentImplementation(
+  name: 'CustomGrid',
+  schema: Schema.object(
+    properties: {
+      'title': CommonSchemas.dynamicString,
+      'description': CommonSchemas.dynamicString,
+      'children': CommonSchemas.childList,
+    },
+  ),
+  builder: (context, node, props, buildChild) {
+    final TextTheme text = Theme.of(context).textTheme;
+    final List<ComponentNode<ComponentImplementation>> children = props
+        .children('children');
+    Widget cell(int index) => index < children.length
+        ? Expanded(
+            key: NodeKey(children[index].instanceId),
+            child: Card.outlined(
+              child: Padding(
+                padding: const EdgeInsets.all(8),
+                child: buildChild(children[index]),
+              ),
+            ),
+          )
+        : const Spacer();
+    return LimitedBox(
+      maxWidth: MediaQuery.sizeOf(context).width,
+      child: Column(
+        crossAxisAlignment: CrossAxisAlignment.stretch,
+        children: [
+          if (props.string('title') case final String title)
+            Text(title, style: text.titleMedium),
+          if (props.string('description') case final String description)
+            Text(description, style: text.bodySmall),
+          for (var row = 0; row < children.length; row += 2)
+            Row(
+              crossAxisAlignment: CrossAxisAlignment.start,
+              children: [cell(row), cell(row + 1)],
+            ),
+        ],
+      ),
+    );
+  },
+);
+
+/// A `CustomSlider`: its `label` and `value` over a [Slider] from `min` to
+/// `max` that writes each move to the path `value` is bound to, as a whole
+/// number of steps of 1 from `min` that stays within `max`.
+final ComponentImplementation customSlider = ComponentImplementation(
+  name: 'CustomSlider',
+  schema: Schema.object(
+    properties: {
+      'label': CommonSchemas.dynamicString,
+      'value': _dynamicNumber,
+      'min': _dynamicNumber,
+      'max': _dynamicNumber,
+    },
+  ),
+  builder: (context, node, props, buildChild) {
+    final double min = props.number('min') ?? 0;
+    final double max = math.max(min, props.number('max') ?? 100);
+    final double value = (props.number('value') ?? min).clamp(min, max);
+    final WritableBinding<Object?>? binding = props.writable('value');
+    final SurfaceModel<ComponentImplementation> surface = A2uiSurface.of(
+      context,
+    );
+    return Column(
+      crossAxisAlignment: CrossAxisAlignment.start,
+      children: [
+        Text(
+          '${props.string('label') ?? 'Value'}: '
+          '${ComponentProps.asString(value)}',
+        ),
+        Slider(
+          value: value,
+          min: min,
+          max: max,
+          onChanged: binding == null
+              ? null
+              : (moved) {
+                  final int steps = math.min(
+                    (moved - min).round(),
+                    (max - min).floor(),
+                  );
+                  final double next = min + steps;
+                  try {
+                    binding.set(next % 1 == 0 ? next.toInt() : next);
+                  } on A2uiDataError catch (error) {
+                    unawaited(
+                      surface.dispatchError(
+                        A2uiRendererError(
+                          code: error.code,
+                          surfaceId: surface.id,
+                          message: error.message,
+                          path: error.path,
+                        ),
+                      ),
+                    );
+                  }
+                },
+        ),
+      ],
+    );
+  },
+);