feat: add enumeration support and corresponding Flutter bindings

helightdev · helightdev · commit ab00eab04c4b · 2025-06-03T23:32:15.000+02:00
diff --git a/packages/dogs/lib/dogs_schema.dart b/packages/dogs/lib/dogs_schema.dart
@@ -28,6 +28,11 @@ SchemaType map(SchemaType itemType) {
   return SchemaType.map(itemType);
 }
 
+SchemaType enumeration(List<String> values) {
+  return SchemaType.string.property(SchemaProperties.$enum, values);
+}
+
+
 extension SchemaTypeExtension on SchemaType {
   SchemaType array() => SchemaType.array(this);
 
diff --git a/packages/dogs/lib/src/converters/enum.dart b/packages/dogs/lib/src/converters/enum.dart
@@ -58,7 +58,7 @@ abstract class GeneratedEnumDogConverter<T extends Enum> extends DogConverter<T>
 /// Mixin that exposes a public api surface for enum converters.
 /// Primarily intended to be used by opmode factories for converter tree
 /// introspection.
-mixin EnumConverter<T extends Enum> on DogConverter<T> {
+mixin EnumConverter<T> on DogConverter<T> {
   /// All possible enum values.
   List<String> get values;
 
@@ -68,3 +68,49 @@ mixin EnumConverter<T extends Enum> on DogConverter<T> {
   /// Converts a enum value to a string.
   String valueToString(T? value);
 }
+
+
+class RuntimeEnumConverter extends SimpleDogConverter<String> with EnumConverter<String> {
+  @override
+  final List<String> values;
+
+  RuntimeEnumConverter(this.values, String serialName) : super(serialName: serialName);
+
+  @override
+  String deserialize(value, DogEngine engine) {
+    if (!values.contains(value)) {
+      throw DogSerializerException(
+        message: "Value '$value' is not a valid enum value. Valid values are: $values",
+        converter: this
+      );
+    }
+    return value as String;
+  }
+
+  @override
+  serialize(String value, DogEngine engine) {
+    return value;
+  }
+
+  @override
+  String? valueFromString(String value) {
+    if (value == "null") return null;
+    if (values.contains(value)) {
+      return value;
+    }
+    throw ArgumentError("Value '$value' is not a valid enum value. Valid values are: $values");
+  }
+
+  @override
+  String valueToString(String? value) {
+    if (value == null) return "null";
+    return value;
+  }
+
+  @override
+  SchemaType describeOutput(DogEngine engine, SchemaConfig config) {
+    final type = SchemaType.string;
+    type[SchemaProperties.$enum] = values;
+    return type;
+  }
+}
diff --git a/packages/dogs/lib/src/schema/materialize.dart b/packages/dogs/lib/src/schema/materialize.dart
@@ -174,13 +174,25 @@ class DogsMaterializer {
       isPolymorphic = true;
       return QualifiedTypeTree.terminal<dynamic>();
     });
+    final annotations = <StructureMetadata>[];
+    if (isPolymorphic) {
+      annotations.add(polymorphic);
+    }
+
+    final enumProperty = field.type[SchemaProperties.$enum] as List<String>?;
+    if (enumProperty != null) {
+      annotations.add(UseConverterInstance(
+        RuntimeEnumConverter(enumProperty, "${field.name}Enum")
+      ));
+    }
+
     final structureField = DogStructureField(
       materializedTypeTree,
       null,
       field.name,
       field.type.nullable,
       true,
-      isPolymorphic ? [polymorphic] : [],
+      annotations
     );
     return structureField;
   }
diff --git a/packages/dogs/test/dogs_schema.dart b/packages/dogs/test/dogs_schema.dart
@@ -63,6 +63,36 @@ void main() {
     });
   });
 
+  test("Enum Properties", () {
+    final base = z.object({
+      "first": z.enumeration(["A", "B", "C"]),
+    });
+    expect(base, doesReserialize);
+    final case0 = {
+      "first": "A",
+    };
+    final case1 = {
+      "first": "B",
+    };
+    final case2 = {
+      "first": "C",
+    };
+    final case3 = {
+      "first": "D", // Invalid case
+    };
+
+    final serializer = DogEngine().materialize(base);
+    final encoded0 = serializer.toJson(case0);
+    final decoded0 = serializer.fromJson(encoded0);
+    expect(decoded0, unorderedDeepEquals(case0));
+    final encoded1 = serializer.toJson(case1);
+    final decoded1 = serializer.fromJson(encoded1);
+    expect(decoded1, unorderedDeepEquals(case1));
+    final decoded2 = serializer.fromNative(case2);
+    expect(decoded2, unorderedDeepEquals(case2));
+    expect(() => serializer.fromNative(case3), throwsA(isA<DogException>()));
+  });
+
   test("Unroll Nested Schema", () {
     final base = z.object({
       "name": z.string(),
diff --git a/packages/dogs_flutter/example/lib/main.dart b/packages/dogs_flutter/example/lib/main.dart
@@ -61,11 +61,11 @@ class _TestFormState extends State<TestForm> {
         "subfield1": z.string(),
         "subfield2": z.integer()
       }),
-      "array": z.string().array().min(3).max(5),
-      "objectArray": z.object({
-        "name": z.string(),
-        "value": z.integer().positive(),
-      }).array()
+      "enum": z.enumeration([
+        "option1",
+        "option2",
+        "option3",
+      ])
     }),
   );
 
@@ -110,11 +110,7 @@ class _TestFormState extends State<TestForm> {
                         "surname": "Doe",
                         "age": 21,
                         "subschema": {"subfield1": "value1", "subfield2": 42},
-                        "array": ["item1", "item2", "item3"],
-                        "objectArray": [
-                          {"name": "Item1", "value": 1},
-                          {"name": "Item2", "value": 2},
-                        ],
+                        "enum": "option2",
                       });
 
                       setState(() {
diff --git a/packages/dogs_flutter/lib/databinding/bindings/enum.dart b/packages/dogs_flutter/lib/databinding/bindings/enum.dart
@@ -0,0 +1,143 @@
+import 'package:dogs_flutter/dogs_flutter.dart';
+import 'package:flutter/material.dart';
+
+class EnumFlutterBinder extends FlutterWidgetBinder<String>
+    with TypeCaptureMixin<String>
+    implements StructureMetadata {
+  final EnumConverter converter;
+
+  const EnumFlutterBinder(this.converter);
+
+  @override
+  Widget buildBindingField(
+    BuildContext context,
+    FieldBindingController<String> controller,
+  ) {
+    return EnumBindingFieldWidget(
+      key: Key(controller.fieldName),
+      controller: controller as EnumBindingFieldController,
+    );
+  }
+
+  @override
+  FieldBindingController<String> createBindingController(
+    FieldBindingParent parent,
+    FieldBindingContext<String> context,
+  ) {
+    return EnumBindingFieldController(parent, this, context, converter);
+  }
+
+  @override
+  void initialise(DogEngine engine) {}
+
+  @override
+  bool operator ==(Object other) =>
+      identical(this, other) ||
+      other is EnumFlutterBinder &&
+          runtimeType == other.runtimeType &&
+          converter == other.converter;
+
+  @override
+  int get hashCode => converter.hashCode;
+}
+
+class EnumBindingFieldController extends FieldBindingController<String> {
+  final FocusNode focusNode = FocusNode();
+  String? value;
+  final EnumConverter converter;
+
+  EnumBindingFieldController(
+    super.parent,
+    super.binder,
+    super.bindingContext,
+    this.converter,
+  ) {
+    focusNode.addListener(_onFocusChanged);
+  }
+
+  @override
+  void dispose() {
+    super.dispose();
+    focusNode.dispose();
+  }
+
+  void _onFocusChanged() {
+    if (!focusNode.hasFocus) {
+      performValidation(ValidationTrigger.onUnfocus);
+    }
+  }
+
+  @override
+  String? getValue() {
+    return value;
+  }
+
+  @override
+  void setValue(String? value) {
+    this.value = value;
+    notifyListeners();
+  }
+}
+
+class EnumBindingFieldWidget extends StatelessWidget {
+  final EnumBindingFieldController controller;
+
+  const EnumBindingFieldWidget({super.key, required this.controller});
+
+  @override
+  Widget build(BuildContext context) {
+    final theme = BindingTheme.of(context);
+    return ValueListenableBuilder(
+      valueListenable: controller.errorListenable,
+      builder: (context, error, _) {
+        final outerDecoration = theme.style
+            .buildMaterialDecoration(
+              context,
+              controller,
+              includeLabel: false,
+              includeHint: false,
+              includeHelper: false,
+            )
+            .copyWith(
+              errorText: theme.toErrorText(error),
+              border: InputBorder.none,
+              isDense: true,
+            );
+        return InputDecorator(
+          decoration: outerDecoration,
+          child: ListenableBuilder(
+            listenable: controller,
+            builder:
+                (context, child) => DropdownButton<String>(
+                  value: controller.value,
+                  items:
+                      controller.converter.values
+                          .map(
+                            (e) => DropdownMenuItem(value: e, child: Text(e)),
+                          )
+                          .toList(),
+                  isExpanded: true,
+                  hint: theme.style.buildMaterialLabelText(context),
+                  onChanged: (String? value) {
+                    controller.setValue(value);
+                  },
+                ),
+          ),
+        );
+      },
+    );
+  }
+}
+
+class EnumAutoFactory extends OperationModeFactory<FlutterWidgetBinder> {
+  @override
+  FlutterWidgetBinder? forConverter(
+    DogConverter<dynamic> converter,
+    DogEngine engine,
+  ) {
+    if (converter is EnumConverter) {
+      return EnumFlutterBinder(converter);
+    }
+    return null;
+  }
+}
diff --git a/packages/dogs_flutter/lib/dogs_flutter.dart b/packages/dogs_flutter/lib/dogs_flutter.dart
@@ -1,5 +1,7 @@
 library;
 
+import 'package:dogs_flutter/databinding/bindings/enum.dart';
+
 import 'dogs_flutter.dart';
 import 'dogs.g.dart';
 
@@ -44,12 +46,13 @@ export 'schema/custom_tags.dart';
 export 'schema/binding_style_contributor.dart';
 
 final defaultFactories = OperationModeFactory.compose<FlutterWidgetBinder>([
+  ListAutoFactory(),
+  EnumAutoFactory(),
+  NestedStructureAutoFactory(),
   OperationModeFactory.typeSingleton<String, FlutterWidgetBinder>(StringFlutterBinder()),
   OperationModeFactory.typeSingleton<int, FlutterWidgetBinder>(IntFlutterBinder()),
   OperationModeFactory.typeSingleton<double, FlutterWidgetBinder>(DoubleFlutterBinder()),
   OperationModeFactory.typeSingleton<bool, FlutterWidgetBinder>(BoolFlutterBinder()),
-  ListAutoFactory(),
-  NestedStructureAutoFactory()
 ]);
 
 void configureDogsFlutter({
