feat: add SharedOptionList for centrally managed reusable option lists

New SharedOptionList model with name, slug, items (JSON), and is_active.
FormField gains a shared_option_list FK that, when set, overrides inline
choices for any choice-based field (select, radio, multiselect, checkboxes).

Choice resolution priority (both DynamicForm and ApprovalStepForm):
  1. Database prefill source (return_choices queries)
  2. SharedOptionList (centrally managed)
  3. Inline choices on the field definition

Also includes:
- Django admin with SharedOptionListAdmin
- Form builder UI integration (shared list dropdown in field properties)
- Builder API endpoints (list/save/delete shared lists)
- sync_api export/import support (by slug)
- FormFieldInline and FormFieldAdmin exposure
- Migration 0084
- 16 new tests (model + form choice resolution)

Co-authored-by: Claude Code <noreply@anthropic.com>

Author: matteius

django_forms_workflows/admin.py

@@ -39,6 +39,7 @@
     NotificationRule,
     PostSubmissionAction,
     PrefillSource,
+    SharedOptionList,
     StageApprovalGroup,
     SubWorkflowDefinition,
     SubWorkflowInstance,
@@ -166,6 +167,7 @@ class FormFieldInline(nested_admin.NestedStackedInline):
                 "classes": ("collapse",),
                 "fields": (
                     "choices",
+                    "shared_option_list",
                     "prefill_source_config",
                     "default_value",
                     "formula",
@@ -304,7 +306,7 @@ class FormFieldAdmin(admin.ModelAdmin):
         ),
         (
             "Choices (for select/radio/checkbox fields)",
-            {"fields": ("choices",), "classes": ("collapse",)},
+            {"fields": ("shared_option_list", "choices"), "classes": ("collapse",)},
         ),
         (
             "Formula (for calculated fields)",
@@ -1420,6 +1422,23 @@ def get_urls(self):
                 self.admin_site.admin_view(form_builder_views.form_builder_clone),
                 name="form_builder_api_clone",
             ),
+            path(
+                "builder/api/shared-lists/",
+                self.admin_site.admin_view(form_builder_views.shared_option_list_api),
+                name="form_builder_api_shared_lists",
+            ),
+            path(
+                "builder/api/shared-lists/save/",
+                self.admin_site.admin_view(form_builder_views.shared_option_list_save),
+                name="form_builder_api_shared_list_save",
+            ),
+            path(
+                "builder/api/shared-lists/delete/<int:list_id>/",
+                self.admin_site.admin_view(
+                    form_builder_views.shared_option_list_delete
+                ),
+                name="form_builder_api_shared_list_delete",
+            ),
             path(
                 "builder/api/doc-templates/<int:form_id>/",
                 self.admin_site.admin_view(form_builder_views.document_template_list),
@@ -2205,6 +2224,44 @@ class DocumentTemplateAdmin(admin.ModelAdmin):
     )
 
 
+# --- Shared Option List Admin ---
+
+
+@admin.register(SharedOptionList)
+class SharedOptionListAdmin(admin.ModelAdmin):
+    """Admin for centrally managed reusable option lists."""
+
+    list_display = ("name", "slug", "item_count", "is_active", "updated_at")
+    list_filter = ("is_active",)
+    search_fields = ("name", "slug")
+    prepopulated_fields = {"slug": ("name",)}
+    readonly_fields = ("created_at", "updated_at")
+
+    fieldsets = (
+        (None, {"fields": ("name", "slug", "is_active")}),
+        (
+            "Options",
+            {
+                "fields": ("items",),
+                "description": (
+                    "JSON array of options. Each item is either a string "
+                    '(e.g. "Engineering") or an object (e.g. '
+                    '{"value": "eng", "label": "Engineering"}).'
+                ),
+            },
+        ),
+        (
+            "Timestamps",
+            {"fields": ("created_at", "updated_at"), "classes": ("collapse",)},
+        ),
+    )
+
+    def item_count(self, obj):
+        return len(obj.items or [])
+
+    item_count.short_description = "Options"
+
+
 # --- File Upload Configuration Admin ---
 
 

django_forms_workflows/form_builder_views.py

@@ -21,6 +21,7 @@
     FormField,
     FormTemplate,
     PrefillSource,
+    SharedOptionList,
     StageApprovalGroup,
     SubWorkflowDefinition,
     WorkflowDefinition,
@@ -248,9 +249,15 @@ def form_builder_view(request, form_id=None):
         [{"value": ft[0], "label": ft[1]} for ft in FormField.FIELD_TYPES]
     )
 
+    # Get shared option lists for the field property panel
+    shared_option_lists = SharedOptionList.objects.filter(is_active=True).order_by(
+        "name"
+    )
+
     context = {
         "form_definition": form_definition,
         "prefill_sources": prefill_sources,
+        "shared_option_lists": shared_option_lists,
         "field_types": field_types_json,
         "is_new": form_id is None,
     }
@@ -286,6 +293,7 @@ def form_builder_load(request, form_id):
             "choices": field.choices or "",
             "default_value": field.default_value or "",
             "prefill_source_id": field.prefill_source_config_id,
+            "shared_option_list_id": field.shared_option_list_id,
             "validation": {
                 "min_value": field.min_value,
                 "max_value": field.max_value,
@@ -453,6 +461,8 @@ def form_builder_save(request):
                     "choices": field_data.get("choices", ""),
                     "default_value": field_data.get("default_value", ""),
                     "prefill_source_config_id": field_data.get("prefill_source_id"),
+                    "shared_option_list_id": field_data.get("shared_option_list_id")
+                    or None,
                 }
 
                 # Add validation properties
@@ -785,3 +795,81 @@ def document_template_delete(request, form_id, template_id):
     )
     tpl.delete()
     return JsonResponse({"success": True, "message": "Template deleted"})
+
+
+# ---------------------------------------------------------------------------
+# Shared Option List API endpoints
+# ---------------------------------------------------------------------------
+
+
+@staff_member_required
+@require_GET
+def shared_option_list_api(request):
+    """List all shared option lists (for form builder dropdowns)."""
+    lists = SharedOptionList.objects.filter(is_active=True).order_by("name")
+    return JsonResponse(
+        {
+            "success": True,
+            "lists": [
+                {
+                    "id": ol.id,
+                    "name": ol.name,
+                    "slug": ol.slug,
+                    "item_count": len(ol.items or []),
+                }
+                for ol in lists
+            ],
+        }
+    )
+
+
+@staff_member_required
+@require_POST
+def shared_option_list_save(request):
+    """Create or update a shared option list."""
+    try:
+        data = json.loads(request.body)
+        list_id = data.get("id")
+        name = data.get("name", "").strip()
+        slug = data.get("slug", "").strip()
+        items = data.get("items", [])
+        is_active = data.get("is_active", True)
+
+        if not name:
+            return JsonResponse(
+                {"success": False, "error": "Name is required"}, status=400
+            )
+        if not slug:
+            slug = name.lower().replace(" ", "-")
+
+        if list_id:
+            ol = get_object_or_404(SharedOptionList, id=list_id)
+            ol.name = name
+            ol.slug = slug
+            ol.items = items
+            ol.is_active = is_active
+            ol.save()
+        else:
+            ol = SharedOptionList.objects.create(
+                name=name, slug=slug, items=items, is_active=is_active
+            )
+
+        return JsonResponse(
+            {"success": True, "id": ol.id, "message": "List saved successfully"}
+        )
+    except json.JSONDecodeError:
+        return JsonResponse({"success": False, "error": "Invalid JSON"}, status=400)
+    except Exception:
+        logger.exception("Error saving shared option list")
+        return JsonResponse(
+            {"success": False, "error": "An internal error occurred."}, status=500
+        )
+
+
+@staff_member_required
+@require_POST
+def shared_option_list_delete(request, list_id):
+    """Delete a shared option list."""
+    ol = get_object_or_404(SharedOptionList, id=list_id)
+    ol.delete()
+    return JsonResponse({"success": True, "message": "List deleted"})

django_forms_workflows/forms.py

@@ -384,6 +384,27 @@ def _parse_choices(self, choices):
 
         return []
 
+    def _resolve_choices(self, field_def):
+        """Resolve choices for a field from all sources in priority order.
+
+        1. Database prefill source (return_choices query)
+        2. SharedOptionList (centrally managed reusable list)
+        3. Inline choices on the field definition
+
+        Returns a list of (value, label) tuples.
+        """
+        db_choices = self._get_choices_from_prefill_source(field_def)
+        if db_choices is not None:
+            return db_choices
+
+        if field_def.shared_option_list_id:
+            try:
+                return field_def.shared_option_list.get_choices()
+            except Exception:
+                pass
+
+        return self._parse_choices(field_def.choices)
+
     def _get_choices_from_prefill_source(self, field_def):
         """
         Return a list of (value, label) tuples from a database choices query when the
@@ -531,47 +552,27 @@ def add_field(self, field_def, initial_data):
             self.fields[field_def.field_name] = forms.URLField(**field_args)
 
         elif field_def.field_type == "select":
-            _db_choices = self._get_choices_from_prefill_source(field_def)
-            choices = [("", "-- Select --")] + (
-                _db_choices
-                if _db_choices is not None
-                else self._parse_choices(field_def.choices)
-            )
+            choices = [("", "-- Select --")] + self._resolve_choices(field_def)
             self.fields[field_def.field_name] = forms.ChoiceField(
                 choices=choices, **field_args
             )
 
         elif field_def.field_type == "multiselect":
-            _db_choices = self._get_choices_from_prefill_source(field_def)
-            choices = (
-                _db_choices
-                if _db_choices is not None
-                else self._parse_choices(field_def.choices)
-            )
+            choices = self._resolve_choices(field_def)
             self.fields[field_def.field_name] = forms.MultipleChoiceField(
                 choices=choices, widget=forms.CheckboxSelectMultiple, **field_args
             )
 
         elif field_def.field_type == "multiselect_list":
-            _db_choices = self._get_choices_from_prefill_source(field_def)
-            choices = (
-                _db_choices
-                if _db_choices is not None
-                else self._parse_choices(field_def.choices)
-            )
+            choices = self._resolve_choices(field_def)
             self.fields[field_def.field_name] = forms.MultipleChoiceField(
                 choices=choices,
                 widget=forms.SelectMultiple(attrs={"class": "form-select"}),
                 **field_args,
             )
 
         elif field_def.field_type == "radio":
-            _db_choices = self._get_choices_from_prefill_source(field_def)
-            choices = (
-                _db_choices
-                if _db_choices is not None
-                else self._parse_choices(field_def.choices)
-            )
+            choices = self._resolve_choices(field_def)
             self.fields[field_def.field_name] = forms.ChoiceField(
                 choices=choices, widget=forms.RadioSelect, **field_args
             )
@@ -585,12 +586,7 @@ def add_field(self, field_def, initial_data):
             )
 
         elif field_def.field_type == "checkboxes":
-            _db_choices = self._get_choices_from_prefill_source(field_def)
-            choices = (
-                _db_choices
-                if _db_choices is not None
-                else self._parse_choices(field_def.choices)
-            )
+            choices = self._resolve_choices(field_def)
             self.fields[field_def.field_name] = forms.MultipleChoiceField(
                 choices=choices,
                 widget=forms.CheckboxSelectMultiple,
@@ -1505,51 +1501,31 @@ def _create_field(self, field_def, field_args, widget_attrs, is_editable):
             self.fields[field_def.field_name] = forms.EmailField(**field_args)
 
         elif field_def.field_type == "select":
-            _db_choices = self._get_choices_from_prefill_source(field_def)
-            choices = [("", "-- Select --")] + (
-                _db_choices
-                if _db_choices is not None
-                else self._parse_choices(field_def.choices)
-            )
+            choices = [("", "-- Select --")] + self._resolve_choices(field_def)
             if widget_attrs:
                 field_args["widget"] = forms.Select(attrs=widget_attrs)
             self.fields[field_def.field_name] = forms.ChoiceField(
                 choices=choices, **field_args
             )
 
         elif field_def.field_type == "multiselect":
-            _db_choices = self._get_choices_from_prefill_source(field_def)
-            choices = (
-                _db_choices
-                if _db_choices is not None
-                else self._parse_choices(field_def.choices)
-            )
+            choices = self._resolve_choices(field_def)
             self.fields[field_def.field_name] = forms.MultipleChoiceField(
                 choices=choices,
                 widget=forms.CheckboxSelectMultiple,
                 **field_args,
             )
 
         elif field_def.field_type == "multiselect_list":
-            _db_choices = self._get_choices_from_prefill_source(field_def)
-            choices = (
-                _db_choices
-                if _db_choices is not None
-                else self._parse_choices(field_def.choices)
-            )
+            choices = self._resolve_choices(field_def)
             self.fields[field_def.field_name] = forms.MultipleChoiceField(
                 choices=choices,
                 widget=forms.SelectMultiple(attrs={"class": "form-select"}),
                 **field_args,
             )
 
         elif field_def.field_type == "radio":
-            _db_choices = self._get_choices_from_prefill_source(field_def)
-            choices = (
-                _db_choices
-                if _db_choices is not None
-                else self._parse_choices(field_def.choices)
-            )
+            choices = self._resolve_choices(field_def)
             self.fields[field_def.field_name] = forms.ChoiceField(
                 choices=choices,
                 widget=forms.RadioSelect(attrs=widget_attrs),
@@ -1675,6 +1651,18 @@ def _parse_choices(self, choices):
             return [(c.strip(), c.strip()) for c in choices.split(",") if c.strip()]
         return []
 
+    def _resolve_choices(self, field_def):
+        """Resolve choices from all sources (DB prefill > shared list > inline)."""
+        db_choices = self._get_choices_from_prefill_source(field_def)
+        if db_choices is not None:
+            return db_choices
+        if field_def.shared_option_list_id:
+            try:
+                return field_def.shared_option_list.get_choices()
+            except Exception:
+                pass
+        return self._parse_choices(field_def.choices)
+
     def _get_choices_from_prefill_source(self, field_def):
         """
         Return (value, label) tuples from a database choices query when the field's