docs: add annotation catalog for serialization and validation annotations and some smaller changes

helightdev · helightdev · commit 1a9092df4f46 · 2025-09-07T16:58:49.000+02:00
diff --git a/docs/advanced/operation_modes.md b/docs/advanced/operation_modes.md
@@ -17,52 +17,22 @@ Map<Type, OperationMode<DateTime> Function()> get modes => {
 ```
 
 ## Mode Registry
-Operation modes are always resolved through the `OperationModeRegistry`. This registry serves
+Operation modes are always resolved through the engine's `OperationModeRegistry`. This registry serves
 as a central cache and mapping from converters and types to operation mode entries. Child engines
 will always have their independent operation mode registry.
 
-!!! success "Modes do not need to be registered!"
-    The registration is handled on the fly by the `OperationModeRegistry`. If a mode is not found
-    in the registry, the registry will try to infer the operation mode using the `OperationModeFactory`
-
-## Operation Mode Factories
-If an operation mode is not found in the registry, the registry will try infer the operation mode
-using the `OperationModeFactory` list of its engine. Those factories can provide operation modes
-for converters that do not define the required operation modes themselves. Using this mechanism,
-packages can provide operation modes for converters that are not under their control. This feature
-is used by the `dogs_forms` package to provide operation modes for the `AutoFormFieldFactory`.
-
-The `OperationModeFactory` class defines several static functions that can be used to create
-and combine factories for specific converter or structure types.
-```dart title="Default factory composition for dogs_forms"
-final defaultFormFactories = OperationModeFactory.compose<AutoFormFieldFactory>([
-  OperationModeFactory.converterSingleton<NativeRetentionConverter<String>,
-      AutoFormFieldFactory>(const TextFieldFormFieldFactory()),
-  // [...]
-  ListFieldOperationModeFactory<String>(const TextFieldFormFieldFactory()),
-  ListFieldOperationModeFactory<int>(const IntTextFieldFormFieldFactory()),
-  // [...]
-  EnumOpmodeFactory(),
-  StructureOpmodeFactory(),
-]);
-
-```
+Operation modes are always first looked up in the registry. For misses, the registry will first try to resolve
+the operation mode through the converter itself. If the converter does not provide the requested
+operation mode, the registry will try to infer the operation mode using the `OperationModeFactory`s registered in
+the current engine instance.
 
 ## Examples
 ### NativeSerializerMode
 The native operation mode is the most basic operation mode. It is used to serialize and deserialize
-objects to and from dart maps that can be directly serialized to json. Most of the dogs library
+objects to and from dart maps that can be directly serialized to JSON. Most of the dogs library
 is built around this operation mode.
 
-!!! tip "Not only for serialization!"
-    The operation modes are not only used to serialize and deserialize objects,
-    but can also to provide additional functionality like validation and introspection.
-
 ### ValidationMode
 The validation operation mode is used to validate objects. It is used by the `@validate` annotation
 and can be used to validate objects before they are serialized, or to validate objects that have
-been deserialized.
-
-### AutoFormFieldFactory
-While the name may be a bit misleading, the auto form field factory is also an operation mode that
-is used to derive flutter form fields from structures.
+been deserialized.
diff --git a/docs/advanced/schema.md b/docs/advanced/schema.md
@@ -1,4 +1,4 @@
-# Schemas ![Static Badge](https://img.shields.io/badge/experimental-orange)
+# Schemas ![](https://img.shields.io/badge/experimental-orange)
 
 The library can **generate schema definitions** for all converters that support it and can **also regenerate**
 'materialize' **structures** from those **schema definitions**. The schema definition format is JSON-based and a
diff --git a/docs/annotation_catalog.md b/docs/annotation_catalog.md
@@ -0,0 +1,119 @@
+---
+icon: octicons/book-16
+---
+
+# Annotation Catalog
+## Serialization Annotations
+<div class="grid cards" markdown>
+
+-   ![](https://img.shields.io/badge/class-seagreen){ .lg .middle }
+    ![](https://img.shields.io/badge/enum-orange){ .lg .middle }
+    __Structure__
+
+    ---
+    Generates a structure for the target. `serialName` can be specified to change the identifier used.
+    `serializable: false` can be used to only generate structures.
+
+-   ![](https://img.shields.io/badge/class-seagreen){ .lg .middle }
+    ![](https://img.shields.io/badge/enum-orange){ .lg .middle }
+    __Serializable / serializable__
+
+    ---
+    Aliases for serializable `Structures`. `serialName` can be specified to change the identifier used.
+
+-   ![](https://img.shields.io/badge/enum--constant-orange){ .lg .middle }
+    __EnumProperty__
+
+    ---
+    The name of the enum constant can be overridden using the `name` parameter. Additionally,
+    a single constant can be marked as `fallback` to handle invalid enum values.
+
+-   ![](https://img.shields.io/badge/property-blue){ .lg .middle }
+    __polymorphic__
+
+    ---
+    Marks a field as polymorphic so that the actual runtime type is used for serialization.
+
+-   ![](https://img.shields.io/badge/property-blue){ .lg .middle }
+    __PropertySerializer__
+
+    ---
+    Specifies the type of custom converter to be used for this fields' serialization.
+
+-   ![](https://img.shields.io/badge/property-blue){ .lg .middle }
+    __PropertyName__
+
+    ---
+    Changes the name of the property used in serialization.
+
+-   ![](https://img.shields.io/badge/property-blue){ .lg .middle }
+    __DefaultValue__
+
+    ---
+    Sets a default value for the field. If `keep` is `false`, the field will be omitted in serialization if it has the default value.
+
+-   ![](https://img.shields.io/badge/class-seagreen){ .lg .middle }
+    ![](https://img.shields.io/badge/property-blue){ .lg .middle }
+    __excludeNull__
+
+    ---
+    If applied to a member, direct null values will be excluded from serialization.
+
+-   ![](https://img.shields.io/badge/class-seagreen){ .lg .middle }
+    __LightweightMigration__
+
+    ---
+    Applies a list of functions on deserialization to migrate data from older versions.
+
+-   ![](https://img.shields.io/badge/class-seagreen){ .lg .middle }
+    __RevisionMigration__
+
+    ---
+    Applies migrations based on the revision number added to the map output.
+
+</div>
+
+## Validation Annotations
+<div class="grid cards" markdown>
+
+-   ![](https://img.shields.io/badge/string-seagreen){ .lg .middle }
+    ![](https://img.shields.io/badge/or-many-slategray){ .lg .middle }
+    __LengthRange__
+-   ![](https://img.shields.io/badge/string-seagreen){ .lg .middle }
+    ![](https://img.shields.io/badge/or-many-slategray){ .lg .middle }
+    __Regex__
+-   ![](https://img.shields.io/badge/string-seagreen){ .lg .middle }
+    ![](https://img.shields.io/badge/or-many-slategray){ .lg .middle }
+    __email__
+-   ![](https://img.shields.io/badge/string-seagreen){ .lg .middle }
+    ![](https://img.shields.io/badge/or-many-slategray){ .lg .middle }
+    __notBlank__
+
+-   ![](https://img.shields.io/badge/num-blue){ .lg .middle }
+    ![](https://img.shields.io/badge/or-many-slategray){ .lg .middle }
+    __Range__
+-   ![](https://img.shields.io/badge/num-blue){ .lg .middle }
+    ![](https://img.shields.io/badge/or-many-slategray){ .lg .middle }
+    __Minimum__
+-   ![](https://img.shields.io/badge/num-blue){ .lg .middle }
+    ![](https://img.shields.io/badge/or-many-slategray){ .lg .middle }
+    __Maximum__
+-   ![](https://img.shields.io/badge/num-blue){ .lg .middle }
+    ![](https://img.shields.io/badge/or-many-slategray){ .lg .middle }
+    __positive__
+-   ![](https://img.shields.io/badge/num-blue){ .lg .middle }
+    ![](https://img.shields.io/badge/or-many-slategray){ .lg .middle }
+    __positiveOrZero__
+-   ![](https://img.shields.io/badge/num-blue){ .lg .middle }
+    ![](https://img.shields.io/badge/or-many-slategray){ .lg .middle }
+    __negative__
+-   ![](https://img.shields.io/badge/num-blue){ .lg .middle }
+    ![](https://img.shields.io/badge/or-many-slategray){ .lg .middle }
+    __negativeOrZero__
+-   ![](https://img.shields.io/badge/iterable-slategray){ .lg .middle }
+    __SizeRange__
+-   ![](https://img.shields.io/badge/any-red){ .lg .middle }
+    ![](https://img.shields.io/badge/or-many-slategray){ .lg .middle }
+    __validated__
+
+</div>
diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -1,5 +1,5 @@
 ---
-icon: octicons/book-16
+icon: octicons/zap-16
 ---
 
 ``` { .dart .focus hl_lines="3 6-9" }
@@ -59,6 +59,4 @@ IconButton(
 ```
 
 We then add a button to share the entry as JSON. The `dogs.toJson` method is used to convert the entry to a JSON string,
-that is then display in a dialog.
-
-
+that is then display in a dialog.
diff --git a/docs/stylesheets/theme-tweaks.css b/docs/stylesheets/theme-tweaks.css
@@ -207,4 +207,17 @@ iframe {
     overflow: hidden !important;
     padding: 0;
     background-color: black;
+}
+
+div.cards li {
+    border-radius: var(--md-border-radius) !important;
+}
+
+div.cards hr {
+    margin-top: 0.5em !important;
+    margin-bottom: 0.5em !important;
+}
+
+div.cards strong:first-of-type {
+    margin-left: 4px;
 }
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -28,6 +28,7 @@ nav:
     - index.md
     - installation.md
     - quickstart.md
+    - annotation_catalog.md
     - "Basics":
       - basics/serializables.md
       - basics/serialization.md

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Schemas ![Static Badge](https://img.shields.io/badge/experimental-orange)`
	`1`	`+# Schemas ![](https://img.shields.io/badge/experimental-orange)`
`2`	`2`
`3`	`3`	`The library can generate schema definitions for all converters that support it and can also regenerate`
`4`	`4`	`'materialize' structures from those schema definitions. The schema definition format is JSON-based and a`