formkit-ninja 2.2__tar.gz → 2.3__tar.gz

{formkit_ninja-2.2 → formkit_ninja-2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: formkit-ninja
-Version: 2.2
+Version: 2.3
 Summary: A Django-Ninja backend to specify FormKit schemas
 Author-email: Josh Brooks <josh@catalpa.io>
 Requires-Python: <3.15,>=3.10
@@ -213,10 +213,10 @@ Tests and submission queryset annotations (e.g. `with_unresolved_flags()`, `with
 
 ```bash
 # Using Podman (recommended)
-podman run --replace -d --name formkit-postgres -p 5434:5432 -e POSTGRES_HOST_AUTH_METHOD=trust docker.io/library/postgres:14-alpine
+podman run --replace -d --name formkit-postgres -p 5435:5432 -e POSTGRES_HOST_AUTH_METHOD=trust docker.io/library/postgres:14-alpine
 
 # OR using Docker
-docker run -d --name formkit-postgres -p 5434:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres:14-alpine
+docker run -d --name formkit-postgres -p 5435:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres:14-alpine
 ```
 
 Then run tests:

{formkit_ninja-2.2 → formkit_ninja-2.3}/README.md

@@ -199,10 +199,10 @@ Tests and submission queryset annotations (e.g. `with_unresolved_flags()`, `with
 
 ```bash
 # Using Podman (recommended)
-podman run --replace -d --name formkit-postgres -p 5434:5432 -e POSTGRES_HOST_AUTH_METHOD=trust docker.io/library/postgres:14-alpine
+podman run --replace -d --name formkit-postgres -p 5435:5432 -e POSTGRES_HOST_AUTH_METHOD=trust docker.io/library/postgres:14-alpine
 
 # OR using Docker
-docker run -d --name formkit-postgres -p 5434:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres:14-alpine
+docker run -d --name formkit-postgres -p 5435:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres:14-alpine
 ```
 
 Then run tests:

formkit_ninja-2.3/docs/ADMIN_DESIGN_EVALUATION.md

@@ -0,0 +1,164 @@
+# FormKitSchemaNode Admin: Design Pattern Evaluation
+
+This document evaluates the current admin/form design for `FormKitSchemaNode` and suggests refactors that could improve maintainability, reduce duplication, and clarify the dual storage model.
+
+**Status:** Refactors 1–4 below have been applied (shared field constants, centralised code-gen fieldset, consistency test, Repeater unified to model field names; model syncs promoted columns back to `node` on save).
+
+---
+
+## Current Architecture (Summary)
+
+```mermaid
+flowchart TB
+    subgraph forms [Admin Forms]
+        Base[FormKitBaseForm]
+        NodeForm[FormKitNodeForm]
+        GroupForm[FormKitNodeGroupForm]
+        RepeaterForm[FormKitNodeRepeaterForm]
+        ElementForm[FormKitElementForm]
+        TextForm[FormKitTextNode]
+        ConditionForm[FormKitConditionForm]
+        ComponentForm[FormKitComponentForm]
+        Base --> NodeForm
+        Base --> GroupForm
+        Base --> ElementForm
+        Base --> TextForm
+        Base --> ConditionForm
+        Base --> ComponentForm
+        NodeForm --> RepeaterForm
+    end
+    subgraph config [NODE_CONFIG]
+        Registry["pydantic type -> form + fieldsets"]
+    end
+    subgraph model [FormKitSchemaNode]
+        NodeJSON[node JSONField]
+        ModelCols[Promoted columns: icon, title, readonly, etc.]
+    end
+    forms --> config
+    forms --> model
+    NodeJSON -->|promote on save| ModelCols
+    ModelCols -->|get_node_values| NodeJSON
+```
+
+- **Type-specific forms**: `get_form()` picks a form class from `NODE_CONFIG` based on `obj.get_node()` (pydantic type).
+- **Dual storage**: Many props live both in `node` (JSON) and as model columns (e.g. `icon`, `title`, `readonly`). Model `save()` promotes from `node`/`additional_props` into those columns; `get_node_values()` writes them back into the emitted schema.
+- **JSONMappingMixin**: Forms that edit `node` use flat form fields plus `_json_fields` to read/write the JSON; the mixin also preserves unrecognized keys in `additional_props`.
+
+---
+
+## What Works Well
+
+1. **NODE_CONFIG registry**  
+   Central mapping from pydantic node type to form and optional fieldsets keeps the “which form for which node” logic in one place. Adding a new node type (e.g. a new formkit widget) is a single registry entry.
+
+2. **Form inheritance**  
+   `FormKitBaseForm` holds shared fields (label, description, code-gen, common props). Subclasses add only what’s different (e.g. `_json_fields`, node-specific form fields). That’s a clear split.
+
+3. **Fieldset grouping**  
+   `get_fieldsets()` builds a default fieldset from “all form fields not already in a named fieldset” plus code-gen at the end. NODE_CONFIG can add extra fieldsets (e.g. “Display & behaviour”, “Repeater field properties”). That keeps the UI organized without hardcoding every field.
+
+4. **Promotion in model**  
+   Having the model own the promotion logic (JSON → columns on save) and re-export (columns → schema in `get_node_values()`) keeps a single source of truth for the list of promoted fields and their naming (camelCase vs snake_case).
+
+---
+
+## Pain Points and Risks
+
+### 1. Duplicated `Meta.fields` across forms
+
+**Issue:** `FormKitBaseForm`, `FormKitNodeForm`, and `FormKitNodeGroupForm` each declare a long `Meta.fields` tuple. Shared fields (e.g. `icon`, `title`, `readonly`, `sections_schema`, code-gen, `created_by`, `updated_by`) are repeated. Adding a new shared field requires updating multiple form classes.
+
+**Risk:** Forgetting one form leads to inconsistent admin UX (e.g. “title” missing until we added it everywhere).
+
+**Refactor option:** Define a single constant (or base tuple) for “common” and “code-gen” fields, and compose in each form:
+
+```python
+# e.g. in admin.py
+COMMON_NODE_FIELDS = (
+    "label", "description", "icon", "title", "readonly", "sections_schema",
+    "is_active", "protected",
+)
+CODE_GEN_FIELDS = (
+    "django_field_type", "django_field_args", "django_field_positional_args",
+    "pydantic_field_type", "extra_imports", "validators", "list_filter",
+)
+AUDIT_FIELDS = ("created_by", "updated_by")
+
+class FormKitBaseForm(JSONMappingMixin, forms.ModelForm):
+    class Meta:
+        model = models.FormKitSchemaNode
+        fields = COMMON_NODE_FIELDS + CODE_GEN_FIELDS + AUDIT_FIELDS
+```
+
+Then `FormKitNodeForm` could be `COMMON_NODE_FIELDS + ("additional_props", "option_group", "add_label", "up_control", "down_control") + CODE_GEN_FIELDS + AUDIT_FIELDS`, and `FormKitNodeGroupForm` could add only `"additional_props", "option_group"`. New shared fields get added in one place.
+
+---
+
+### 2. Two sources of truth for “node” props (form vs model)
+
+**Issue:** Some props are edited via:
+- **Model fields only** (e.g. `title`, `icon`, `readonly`, `sections_schema`): form shows them, they’re saved to model columns, and `get_node_values()` pushes them into the output.
+- **Form fields that write into `node`** (e.g. `addLabel`, `upControl`, `downControl` in RepeaterForm): the form writes to `node`; on save the model promotes from `node` into `add_label`, `up_control`, `down_control`.
+
+So the same logical prop can be reached either as a model field or via `_json_fields` + promotion. For Repeater, the form uses `addLabel`/`upControl`/`downControl` (camelCase, node) rather than `add_label`/`up_control`/`down_control` (model). The mixin’s fallback in `_populate_form_fields` maps camelCase → model for initial values. It works but is easy to get wrong when adding new props.
+
+**Risk:** New “common” props might be added to the model and to `get_node_values()` but forgotten in the form’s `Meta.fields` (as happened with `title`), or the other way around (in form but not in promotion/get_node_values).
+
+**Refactor option (medium effort):**  
+- Prefer **model columns as the single source** for all promoted props. Forms only expose the model fields (e.g. `add_label`, `up_control`, `down_control`); do not duplicate them as node-only form fields.  
+- In `save()`, after `super().save()`, have the model (or a small helper) write from those columns back into `node` for the known keys (e.g. `addLabel`, `upControl`, `downControl`) so the stored `node` JSON stays in sync. That way the form doesn’t need to know camelCase and the promotion logic lives in one place (the model).  
+- Then `_json_fields` is only for props that are **not** promoted (e.g. `name`, `$formkit`, `placeholder`, `help`). That clarifies “what comes from node only” vs “what is promoted and edited as model”.
+
+**Lighter option:** At least document the rule (“promoted props = model fields only in forms; node-only form fields only for non-promoted keys”) and add a test or assertion that the set of promoted keys in the model matches the set of form model fields used for those props.
+
+---
+
+### 3. JSONMappingMixin responsibilities and fallback mapping
+
+**Issue:** The mixin (a) populates form from `node` (and optionally model fallback), (b) writes form data back into `node`, (c) preserves unrecognized keys into `additional_props`, and (d) validates `name` for Django-safe identifiers. The fallback mapping in `_populate_form_fields` is partial (e.g. `addLabel` → `add_label`, `sectionsSchema` → `sections_schema`); we didn’t add `title`/`icon`/`readonly` because those are now model-only in the form. If someone later adds node-backed form fields for them, they’d need to extend the mapping.
+
+**Risk:** The mixin is doing a lot; small changes (e.g. new key or new form field) can require touching both the form and the mixin.
+
+**Refactor option:**  
+- Keep the mixin focused on “read/write JSON field from/to flat form fields” and “preserve unknown keys”.  
+- Move “initial from model when not in node” into a single place: either a shared mapping (e.g. `JSON_KEY_TO_MODEL_ATTR`) used by the mixin, or a small helper on the model (e.g. `get_node_related_initial()`) that the form calls.  
+- Document that for “promoted” props, forms should use model fields only and not add them to `_json_fields`; then the mixin’s fallback is only for legacy or node-only form fields.
+
+---
+
+### 4. Fieldset definitions split across NODE_CONFIG and get_fieldsets()
+
+**Issue:**  
+- NODE_CONFIG holds type-specific fieldsets (e.g. “Repeater field properties”, “Display & behaviour”).  
+- The “Code Generation (Source of Truth)” fieldset and the set of `code_gen_fields` used to exclude from the default fieldset are hardcoded in `get_fieldsets()`.  
+- So “which fields are code-gen” is duplicated (form `Meta.fields` + `get_fieldsets()` + possibly NODE_CONFIG if we ever put code-gen there).
+
+**Risk:** Adding a new code-gen field could require updating both the form and `get_fieldsets()`.
+
+**Refactor option:** Define `CODE_GEN_FIELDS` (and optionally a single “Code Generation” fieldset spec) in one place (e.g. at module level or on the admin class), and have `get_fieldsets()` and, if needed, base form `Meta.fields` reference it. Then new code-gen fields are added once.
+
+---
+
+### 5. Repeater: form uses camelCase node keys, others use model names
+
+**Issue:** Repeater form fields are `addLabel`, `upControl`, `downControl` (and in fieldset the same names). Other forms use model names `add_label`, `up_control`, `down_control`. So the admin shows different naming by node type, and Repeater relies on the mixin’s fallback to fill from model.
+
+**Refactor option:** If we move to “model columns as source of truth” (above), RepeaterForm would use `add_label`, `up_control`, `down_control` in both `Meta.fields` and fieldset, and drop the camelCase form fields and their `_json_fields` entries for those three. The model would still write `addLabel`/`upControl`/`downControl` into `node` in `get_node_values()` (and optionally on save). That would make all forms consistent and avoid the mixin fallback for these.
+
+---
+
+## Recommended Order of Refactors
+
+| Priority | Refactor | Effort | Impact |
+|----------|----------|--------|--------|
+| 1 | Introduce `COMMON_NODE_FIELDS` / `CODE_GEN_FIELDS` (and optionally `AUDIT_FIELDS`) and compose form `Meta.fields` from them | Low | Removes duplication and prevents “missing field” regressions when adding shared fields. |
+| 2 | Centralise code-gen fieldset and `code_gen_fields` in one constant or admin attribute | Low | Single place to add new code-gen fields. |
+| 3 | Document the rule “promoted props = model fields in forms; node form fields only for non-promoted” and add a test or consistency check | Low | Reduces risk of drift between model and forms. |
+| 4 | (Optional) Unify Repeater to use model field names in the form and let the model sync to `node`; simplify mixin fallback | Medium | Clearer mental model and consistent UX. |
+| 5 | (Optional) Move “initial from model” fallback into a shared mapping or model helper | Medium | Clearer mixin responsibility and easier to extend. |
+
+---
+
+## Conclusion
+
+The current design is workable and the registry + inheritance structure is sound. The main improvements are: **reducing duplication** (shared field tuples, code-gen fieldset), **clarifying the dual storage model** (document and optionally enforce “promoted = model only in forms”), and **optionally unifying Repeater and the mixin** so that all promoted props are edited only via model fields and the model is the single place that syncs to `node`. Implementing the low-effort refactors (1–3) would already improve maintainability and make it less likely that a future “title”-like field is missed in the admin.

{formkit_ninja-2.2 → formkit_ninja-2.3}/formkit_ninja/admin.py

@@ -32,6 +32,40 @@ logger = logging.getLogger(__name__)
 # The key of the dict provided is a JSON field on the model
 JsonFieldDefn = dict[str, tuple[str | tuple[str, str], ...]]
 
+# Composable field sets for FormKitSchemaNode admin forms.
+# Rule: promoted props (icon, title, readonly, etc.) are model fields only in forms;
+# _json_fields is for node-only keys (e.g. name, $formkit, placeholder). The model
+# syncs promoted columns to/from node on save and in get_node_values().
+COMMON_NODE_FIELDS = (
+    "label",
+    "description",
+    "icon",
+    "title",
+    "readonly",
+    "sections_schema",
+    "is_active",
+    "protected",
+)
+CODE_GEN_FIELDS = (
+    "django_field_type",
+    "django_field_args",
+    "django_field_positional_args",
+    "pydantic_field_type",
+    "extra_imports",
+    "validators",
+    "list_filter",
+)
+AUDIT_FIELDS = ("created_by", "updated_by")
+
+# Code generation fieldset shown at bottom of change form; also used to exclude from default fieldset
+CODE_GEN_FIELDSET_TITLE = "Code Generation (Source of Truth)"
+CODE_GEN_FIELDSET_FIELDS = CODE_GEN_FIELDS + (
+    "django_code_preview",
+    "pydantic_code_preview",
+    "formkit_node_preview",
+)
+CODE_GEN_GROUPED_FIELDS = frozenset(CODE_GEN_FIELDSET_FIELDS)
+
 
 class ItemAdmin(admin.ModelAdmin):
     list_display = ("name",)
@@ -163,19 +197,7 @@ class FormKitBaseForm(JSONMappingMixin, forms.ModelForm):
 
     class Meta:
         model = models.FormKitSchemaNode
-        fields = (
-            "label",
-            "description",
-            "is_active",
-            "protected",
-            "django_field_type",
-            "django_field_args",
-            "django_field_positional_args",
-            "pydantic_field_type",
-            "extra_imports",
-            "validators",
-            "list_filter",
-        )
+        fields = COMMON_NODE_FIELDS + CODE_GEN_FIELDS + AUDIT_FIELDS
 
     # Code Generation Overrides
     django_field_type = forms.CharField(required=False)
@@ -231,20 +253,7 @@ class FormKitSchemaComponentInline(admin.TabularInline):
 class FormKitNodeGroupForm(FormKitBaseForm):
     class Meta:
         model = models.FormKitSchemaNode
-        fields = (
-            "label",
-            "description",
-            "additional_props",
-            "is_active",
-            "protected",
-            "django_field_type",
-            "django_field_args",
-            "django_field_positional_args",
-            "pydantic_field_type",
-            "extra_imports",
-            "validators",
-            "list_filter",
-        )
+        fields = COMMON_NODE_FIELDS + ("additional_props", "option_group") + CODE_GEN_FIELDS + AUDIT_FIELDS
 
     _json_fields = {
         "node": ("name", ("formkit", "$formkit"), "if_condition", ("html_id", "id")),
@@ -258,21 +267,7 @@ class FormKitNodeGroupForm(FormKitBaseForm):
 class FormKitNodeForm(FormKitBaseForm):
     class Meta:
         model = models.FormKitSchemaNode
-        fields = (
-            "label",
-            "description",
-            "additional_props",
-            "option_group",
-            "is_active",
-            "protected",
-            "django_field_type",
-            "django_field_args",
-            "django_field_positional_args",
-            "pydantic_field_type",
-            "extra_imports",
-            "validators",
-            "list_filter",
-        )
+        fields = COMMON_NODE_FIELDS + ("additional_props", "option_group", "add_label", "up_control", "down_control") + CODE_GEN_FIELDS + AUDIT_FIELDS
 
     _json_fields = {
         "node": (
@@ -325,21 +320,18 @@ class FormKitNodeForm(FormKitBaseForm):
 
 
 class FormKitNodeRepeaterForm(FormKitNodeForm):
+    """Repeater node form. add_label, up_control, down_control are model fields (parent);
+    itemsClass/itemClass are node-only and mapped here."""
+
     def get_json_fields(self) -> JsonFieldDefn:
         return {
             "node": (
-                *(super()._json_fields["node"]),
-                "addLabel",
-                "upControl",
-                "downControl",
+                *(super().get_json_fields()["node"]),
                 "itemsClass",
                 "itemClass",
             )
         }
 
-    addLabel = forms.CharField(required=False)
-    upControl = forms.BooleanField(required=False)
-    downControl = forms.BooleanField(required=False)
     itemsClass = forms.CharField(required=False)
     itemClass = forms.CharField(required=False)
     max = forms.IntegerField(required=False)
@@ -441,14 +433,22 @@ NODE_CONFIG: dict[type | str, dict[str, Any]] = {
         "fieldsets": [
             (
                 "Repeater field properties",
-                {"fields": ("addLabel", "upControl", "downControl", "itemsClass", "itemClass")},
+                {"fields": ("add_label", "up_control", "down_control", "itemsClass", "itemClass")},
             )
         ],
     },
     formkit_schema.FormKitSchemaDOMNode: {"form": FormKitElementForm},
     formkit_schema.FormKitSchemaComponent: {"form": FormKitComponentForm},
     formkit_schema.FormKitSchemaCondition: {"form": FormKitConditionForm},
-    formkit_schema.FormKitSchemaProps: {"form": FormKitNodeForm},
+    formkit_schema.FormKitSchemaProps: {
+        "form": FormKitNodeForm,
+        "fieldsets": [
+            (
+                "Display & behaviour",
+                {"fields": ("icon", "title", "readonly", "sections_schema")},
+            ),
+        ],
+    },
 }
 
 # Admin site registration continues below...
@@ -458,6 +458,7 @@ NODE_CONFIG: dict[type | str, dict[str, Any]] = {
 class FormKitSchemaNodeAdmin(admin.ModelAdmin):
     list_display = (
         "label",
+        "title",
         "is_active",
         "short_id",
         "node_type",
@@ -468,7 +469,15 @@ class FormKitSchemaNodeAdmin(admin.ModelAdmin):
         "protected",
         "created",
     )
-    readonly_fields = ("django_code_preview", "pydantic_code_preview", "formkit_node_preview", "created", "updated")
+    readonly_fields = (
+        "django_code_preview",
+        "pydantic_code_preview",
+        "formkit_node_preview",
+        "created",
+        "updated",
+        "created_by",
+        "updated_by",
+    )
     search_fields = ["label", "description", "id"]
     list_filter = ("is_active", "node_type", "protected", "option_group", "created", "updated")
     list_select_related = ("option_group",)
@@ -518,40 +527,15 @@ class FormKitSchemaNodeAdmin(admin.ModelAdmin):
                 break
 
         grouped_fields: set[str] = reduce(operator.or_, (set(opts["fields"]) for _, opts in fieldsets), set())
-        # Also include code generation fields to avoid them being duplicated in the default fieldset
-        code_gen_fields = {
-            "django_field_type",
-            "django_field_args",
-            "django_field_positional_args",
-            "pydantic_field_type",
-            "extra_imports",
-            "validators",
-            "list_filter",
-            "django_code_preview",
-            "pydantic_code_preview",
-            "formkit_node_preview",
-        }
-        grouped_fields.update(code_gen_fields)
+        grouped_fields.update(CODE_GEN_GROUPED_FIELDS)
         fieldsets.insert(0, (None, {"fields": [f for f in self.get_fields(request, obj) if f not in grouped_fields]}))
 
-        # Add Code Generation Source of Truth fieldset
         fieldsets.append(
             (
-                "Code Generation (Source of Truth)",
+                CODE_GEN_FIELDSET_TITLE,
                 {
-                    "fields": (
-                        "django_field_type",
-                        "django_field_args",
-                        "django_field_positional_args",
-                        "pydantic_field_type",
-                        "extra_imports",
-                        "validators",
-                        "list_filter",
-                        "django_code_preview",
-                        "pydantic_code_preview",
-                        "formkit_node_preview",
-                    ),
-                    "description": ("These values are the source of truth for code generation. If empty, they are auto-resolved on save from global configs."),
+                    "fields": CODE_GEN_FIELDSET_FIELDS,
+                    "description": "These values are the source of truth for code generation. If empty, they are auto-resolved on save from global configs.",
                 },
             )
         )

formkit_ninja-2.3/formkit_ninja/migrations/0042_formkitschemanode_list_filter.py

@@ -0,0 +1,61 @@
+# Generated by Django 4.2.27 on 2026-03-03 09:19
+
+import pgtrigger.compiler
+import pgtrigger.migrations
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("formkit_ninja", "0041_flag"),
+    ]
+
+    operations = [
+        pgtrigger.migrations.RemoveTrigger(
+            model_name="formkitschemanode",
+            name="insert_insert",
+        ),
+        pgtrigger.migrations.RemoveTrigger(
+            model_name="formkitschemanode",
+            name="update_update",
+        ),
+        migrations.AddField(
+            model_name="formkitschemanode",
+            name="list_filter",
+            field=models.BooleanField(default=False, help_text="Include this field in generated ModelAdmin.list_filter."),
+        ),
+        migrations.AddField(
+            model_name="formkitschemanodeevent",
+            name="list_filter",
+            field=models.BooleanField(default=False, help_text="Include this field in generated ModelAdmin.list_filter."),
+        ),
+        pgtrigger.migrations.AddTrigger(
+            model_name="formkitschemanode",
+            trigger=pgtrigger.compiler.Trigger(
+                name="insert_insert",
+                sql=pgtrigger.compiler.UpsertTriggerSql(
+                    func='INSERT INTO "formkit_ninja_formkitschemanodeevent" ("add_label", "additional_props", "created", "created_by_id", "description", "django_field_args", "django_field_positional_args", "django_field_type", "down_control", "extra_imports", "icon", "id", "is_active", "label", "list_filter", "max", "min", "node", "node_type", "option_group_id", "pgh_context_id", "pgh_created_at", "pgh_label", "pgh_obj_id", "protected", "pydantic_field_type", "readonly", "sections_schema", "step", "text_content", "title", "track_change", "up_control", "updated", "updated_by_id", "validators") VALUES (NEW."add_label", NEW."additional_props", NEW."created", NEW."created_by_id", NEW."description", NEW."django_field_args", NEW."django_field_positional_args", NEW."django_field_type", NEW."down_control", NEW."extra_imports", NEW."icon", NEW."id", NEW."is_active", NEW."label", NEW."list_filter", NEW."max", NEW."min", NEW."node", NEW."node_type", NEW."option_group_id", _pgh_attach_context(), NOW(), \'insert\', NEW."id", NEW."protected", NEW."pydantic_field_type", NEW."readonly", NEW."sections_schema", NEW."step", NEW."text_content", NEW."title", NEW."track_change", NEW."up_control", NEW."updated", NEW."updated_by_id", NEW."validators"); RETURN NULL;',
+                    hash="ca97f0a9bb68ffec610387b7dbb092bb006f4522",
+                    operation="INSERT",
+                    pgid="pgtrigger_insert_insert_72c4c",
+                    table="formkit_ninja_formkitschemanode",
+                    when="AFTER",
+                ),
+            ),
+        ),
+        pgtrigger.migrations.AddTrigger(
+            model_name="formkitschemanode",
+            trigger=pgtrigger.compiler.Trigger(
+                name="update_update",
+                sql=pgtrigger.compiler.UpsertTriggerSql(
+                    condition="WHEN (OLD.* IS DISTINCT FROM NEW.*)",
+                    func='INSERT INTO "formkit_ninja_formkitschemanodeevent" ("add_label", "additional_props", "created", "created_by_id", "description", "django_field_args", "django_field_positional_args", "django_field_type", "down_control", "extra_imports", "icon", "id", "is_active", "label", "list_filter", "max", "min", "node", "node_type", "option_group_id", "pgh_context_id", "pgh_created_at", "pgh_label", "pgh_obj_id", "protected", "pydantic_field_type", "readonly", "sections_schema", "step", "text_content", "title", "track_change", "up_control", "updated", "updated_by_id", "validators") VALUES (NEW."add_label", NEW."additional_props", NEW."created", NEW."created_by_id", NEW."description", NEW."django_field_args", NEW."django_field_positional_args", NEW."django_field_type", NEW."down_control", NEW."extra_imports", NEW."icon", NEW."id", NEW."is_active", NEW."label", NEW."list_filter", NEW."max", NEW."min", NEW."node", NEW."node_type", NEW."option_group_id", _pgh_attach_context(), NOW(), \'update\', NEW."id", NEW."protected", NEW."pydantic_field_type", NEW."readonly", NEW."sections_schema", NEW."step", NEW."text_content", NEW."title", NEW."track_change", NEW."up_control", NEW."updated", NEW."updated_by_id", NEW."validators"); RETURN NULL;',
+                    hash="2e35d6535c17e41582d263abff78490ad83436e1",
+                    operation="UPDATE",
+                    pgid="pgtrigger_update_update_d7c99",
+                    table="formkit_ninja_formkitschemanode",
+                    when="AFTER",
+                ),
+            ),
+        ),
+    ]

{formkit_ninja-2.2 → formkit_ninja-2.3}/formkit_ninja/models.py

@@ -489,6 +489,36 @@ class FormKitSchemaNode(UuidIdModel):
                         val = str(val)
                     setattr(self, target_field, val)
 
+        # Sync promoted columns back into node so stored JSON stays in sync when
+        # admin edits model fields (e.g. add_label, up_control) rather than node.
+        # Only write non-default values (or when key already in node) to avoid
+        # adding keys that weren't in the original schema (round-trip fidelity).
+        if isinstance(self.node, dict):
+            _promoted_to_node = (
+                ("icon", "icon", None),
+                ("title", "title", None),
+                ("readonly", "readonly", False),
+                ("sections_schema", "sectionsSchema", None),
+                ("min", "min", None),
+                ("max", "max", None),
+                ("step", "step", None),
+                ("add_label", "addLabel", None),
+                ("up_control", "upControl", True),
+                ("down_control", "downControl", True),
+            )
+            for attr, key, default in _promoted_to_node:
+                val = getattr(self, attr, None)
+                already_in_node = key in self.node
+                if isinstance(val, bool):
+                    if already_in_node or val != default:
+                        self.node[key] = val
+                    elif key in self.node:
+                        self.node.pop(key, None)
+                elif val not in (None, ""):
+                    self.node[key] = val
+                elif already_in_node:
+                    self.node.pop(key, None)
+
         # Resolve code generation defaults if not set
         self.resolve_code_generation_defaults()