fh-pydantic-form 0.1.3__py3-none-any.whl → 0.2.1__py3-none-any.whl

fh_pydantic_form/field_renderers.py

@@ -1,7 +1,9 @@
 import logging
 from datetime import date, time
+from enum import Enum
 from typing import (
     Any,
+    List,
     Optional,
     get_args,
     get_origin,
@@ -15,13 +17,30 @@ from pydantic.fields import FieldInfo
 
 from fh_pydantic_form.registry import FieldRendererRegistry
 from fh_pydantic_form.type_helpers import (
+    _UNSET,
     _get_underlying_type_if_optional,
     _is_optional_type,
+    get_default,
+)
+from fh_pydantic_form.ui_style import (
+    SpacingTheme,
+    SpacingValue,
+    _normalize_spacing,
+    spacing,
 )
 
 logger = logging.getLogger(__name__)
 
 
+def _merge_cls(base: str, extra: str) -> str:
+    """Return base plus extra class(es) separated by a single space (handles blanks)."""
+    if extra:
+        combined = f"{base} {extra}".strip()
+        # Remove duplicate whitespace
+        return " ".join(combined.split())
+    return base
+
+
 class BaseFieldRenderer:
     """
     Base class for field renderers
@@ -42,6 +61,9 @@ class BaseFieldRenderer:
         prefix: str = "",
         disabled: bool = False,
         label_color: Optional[str] = None,
+        spacing: SpacingValue = SpacingTheme.NORMAL,
+        field_path: Optional[List[str]] = None,
+        form_name: Optional[str] = None,
     ):
         """
         Initialize the field renderer
@@ -53,15 +75,61 @@ class BaseFieldRenderer:
             prefix: Optional prefix for the field name (used for nested fields)
             disabled: Whether the field should be rendered as disabled
             label_color: Optional CSS color value for the field label
+            spacing: Spacing theme to use for layout ("normal", "compact", or SpacingTheme enum)
+            field_path: Path segments from root to this field (for nested list support)
+            form_name: Explicit form name (used for nested list URLs)
         """
         self.field_name = f"{prefix}{field_name}" if prefix else field_name
         self.original_field_name = field_name
         self.field_info = field_info
         self.value = value
         self.prefix = prefix
+        self.field_path: List[str] = field_path or []
+        self.explicit_form_name: Optional[str] = form_name
         self.is_optional = _is_optional_type(field_info.annotation)
         self.disabled = disabled
         self.label_color = label_color
+        self.spacing = _normalize_spacing(spacing)
+
+    def _is_inline_color(self, color: str) -> bool:
+        """
+        Determine if a color should be applied as an inline style or CSS class.
+
+        Args:
+            color: The color value to check
+
+        Returns:
+            True if the color should be applied as inline style, False if as CSS class
+        """
+        # Check if it's a hex color value (starts with #) or basic HTML color name
+        return color.startswith("#") or color in [
+            "red",
+            "blue",
+            "green",
+            "yellow",
+            "orange",
+            "purple",
+            "pink",
+            "cyan",
+            "magenta",
+            "brown",
+            "black",
+            "white",
+            "gray",
+            "grey",
+        ]
+
+    def _get_color_class(self, color: str) -> str:
+        """
+        Get the appropriate CSS class for a color.
+
+        Args:
+            color: The color name
+
+        Returns:
+            The CSS class string for the color
+        """
+        return f"text-{color}-600"
 
     def render_label(self) -> FT:
         """
@@ -79,7 +147,8 @@ class BaseFieldRenderer:
         # Create span attributes with tooltip if description is available
         span_attrs = {}
         if description:
-            span_attrs["uk_tooltip"] = description
+            span_attrs["uk-tooltip"] = description  # UIkit tooltip
+            span_attrs["title"] = description  # Standard HTML tooltip
             # Removed cursor-help class while preserving tooltip functionality
 
         # Create the span with the label text and tooltip
@@ -88,15 +157,26 @@ class BaseFieldRenderer:
         # Prepare label attributes
         label_attrs = {"For": self.field_name}
 
+        # Build label classes with tokenized gap
+        label_gap_class = spacing("label_gap", self.spacing)
+        base_classes = f"block text-sm font-medium text-gray-700 {label_gap_class}"
+
+        cls_attr = base_classes
+
         # Apply color styling if specified
         if self.label_color:
-            label_attrs["style"] = f"color: {self.label_color};"
+            if self._is_inline_color(self.label_color):
+                # Treat as color value
+                label_attrs["style"] = f"color: {self.label_color};"
+            else:
+                # Treat as CSS class (includes Tailwind colors like emerald, amber, rose, teal, indigo, lime, violet, etc.)
+                cls_attr = f"block text-sm font-medium {self._get_color_class(self.label_color)} {label_gap_class}".strip()
 
         # Create and return the label - using standard fh.Label with appropriate styling
         return fh.Label(
             label_text_span,
             **label_attrs,
-            cls="block text-sm font-medium text-gray-700 mb-1",
+            cls=cls_attr,
         )
 
     def render_input(self) -> FT:
@@ -113,46 +193,38 @@ class BaseFieldRenderer:
 
     def render(self) -> FT:
         """
-        Render the complete field (label + input) with spacing in a collapsible accordion
+        Render the complete field (label + input) with spacing
+
+        For compact spacing: renders label and input side-by-side
+        For normal spacing: renders label above input (traditional)
 
         Returns:
-            A FastHTML component (mui.Accordion) containing the complete field
+            A FastHTML component containing the complete field
         """
-        # 1. Get the full label component (fh.Label)
+        # 1. Get the label component
         label_component = self.render_label()
 
-        # Apply color styling directly to the Label component if needed
-        if self.label_color and isinstance(label_component, fh.FT):
-            if "style" in label_component.attrs:
-                label_component.attrs["style"] += f" color: {self.label_color};"
-            else:
-                label_component.attrs["style"] = f"color: {self.label_color};"
-
-        # 2. Render the input field that will be the accordion content
+        # 2. Render the input field
         input_component = self.render_input()
 
-        # 3. Define unique IDs for potential targeting
-        item_id = f"{self.field_name}_item"
-        accordion_id = f"{self.field_name}_accordion"
-
-        # 4. Create the AccordionItem with the full label component as title
-        accordion_item = mui.AccordionItem(
-            label_component,  # Use the entire label component including the "for" attribute
-            input_component,  # Content component (the input field)
-            open=True,  # Open by default
-            li_kwargs={"id": item_id},  # Pass the specific ID for the <li>
-            cls="mb-2",  # Add spacing between accordion items
-        )
-
-        # 5. Wrap the single AccordionItem in an Accordion container
-        accordion_container = mui.Accordion(
-            accordion_item,  # The single item to include
-            id=accordion_id,  # ID for the accordion container (ul)
-            multiple=True,  # Allow multiple open (though only one exists)
-            collapsible=True,  # Allow toggling
-        )
-
-        return accordion_container
+        # 3. Choose layout based on spacing theme
+        if self.spacing == SpacingTheme.COMPACT:
+            # Horizontal layout for compact mode
+            return fh.Div(
+                fh.Div(
+                    label_component,
+                    input_component,
+                    cls=f"flex {spacing('horizontal_gap', self.spacing)} {spacing('label_align', self.spacing)}",
+                ),
+                cls=spacing("outer_margin", self.spacing),
+            )
+        else:
+            # Vertical layout for normal mode (existing behavior)
+            return fh.Div(
+                label_component,
+                input_component,
+                cls=spacing("outer_margin", self.spacing),
+            )
 
 
 # ---- Specific Field Renderers ----
@@ -168,11 +240,13 @@ class StringFieldRenderer(BaseFieldRenderer):
         Returns:
             A TextInput component appropriate for string values
         """
-        is_field_required = (
-            not self.is_optional
-            and self.field_info.default is None
-            and getattr(self.field_info, "default_factory", None) is None
-        )
+        # is_field_required = (
+        #     not self.is_optional
+        #     and self.field_info.default is None
+        #     and getattr(self.field_info, "default_factory", None) is None
+        # )
+        has_default = get_default(self.field_info) is not _UNSET
+        is_field_required = not self.is_optional and not has_default
 
         placeholder_text = f"Enter {self.original_field_name.replace('_', ' ')}"
         if self.is_optional:
@@ -185,7 +259,10 @@ class StringFieldRenderer(BaseFieldRenderer):
             "type": "text",
             "placeholder": placeholder_text,
             "required": is_field_required,
-            "cls": "w-full",
+            "cls": _merge_cls(
+                "w-full",
+                f"{spacing('input_size', self.spacing)} {spacing('input_padding', self.spacing)}".strip(),
+            ),
         }
 
         # Only add the disabled attribute if the field should actually be disabled
@@ -205,11 +282,9 @@ class NumberFieldRenderer(BaseFieldRenderer):
         Returns:
             A NumberInput component appropriate for numeric values
         """
-        is_field_required = (
-            not self.is_optional
-            and self.field_info.default is None
-            and getattr(self.field_info, "default_factory", None) is None
-        )
+        # Determine if field is required
+        has_default = get_default(self.field_info) is not _UNSET
+        is_field_required = not self.is_optional and not has_default
 
         placeholder_text = f"Enter {self.original_field_name.replace('_', ' ')}"
         if self.is_optional:
@@ -222,7 +297,10 @@ class NumberFieldRenderer(BaseFieldRenderer):
             "type": "number",
             "placeholder": placeholder_text,
             "required": is_field_required,
-            "cls": "w-full",
+            "cls": _merge_cls(
+                "w-full",
+                f"{spacing('input_size', self.spacing)} {spacing('input_padding', self.spacing)}".strip(),
+            ),
             "step": "any"
             if self.field_info.annotation is float
             or get_origin(self.field_info.annotation) is float
@@ -258,6 +336,29 @@ class BooleanFieldRenderer(BaseFieldRenderer):
 
         return mui.CheckboxX(**checkbox_attrs)
 
+    def render(self) -> FT:
+        """
+        Render the complete field (label + input) with spacing, placing the checkbox next to the label.
+
+        Returns:
+            A FastHTML component containing the complete field
+        """
+        # Get the label component
+        label_component = self.render_label()
+
+        # Get the checkbox component
+        checkbox_component = self.render_input()
+
+        # Create a flex container to place label and checkbox side by side
+        return fh.Div(
+            fh.Div(
+                label_component,
+                checkbox_component,
+                cls="flex items-center gap-2",  # Use flexbox to align items horizontally with a small gap
+            ),
+            cls=spacing("outer_margin", self.spacing),
+        )
+
 
 class DateFieldRenderer(BaseFieldRenderer):
     """Renderer for date fields"""
@@ -278,11 +379,8 @@ class DateFieldRenderer(BaseFieldRenderer):
         elif isinstance(self.value, date):
             formatted_value = self.value.isoformat()  # YYYY-MM-DD
 
-        is_field_required = (
-            not self.is_optional
-            and self.field_info.default is None
-            and getattr(self.field_info, "default_factory", None) is None
-        )
+        has_default = get_default(self.field_info) is not _UNSET
+        is_field_required = not self.is_optional and not has_default
 
         placeholder_text = f"Select {self.original_field_name.replace('_', ' ')}"
         if self.is_optional:
@@ -295,7 +393,10 @@ class DateFieldRenderer(BaseFieldRenderer):
             "type": "date",
             "placeholder": placeholder_text,
             "required": is_field_required,
-            "cls": "w-full",
+            "cls": _merge_cls(
+                "w-full",
+                f"{spacing('input_size', self.spacing)} {spacing('input_padding', self.spacing)}".strip(),
+            ),
         }
 
         # Only add the disabled attribute if the field should actually be disabled
@@ -324,11 +425,9 @@ class TimeFieldRenderer(BaseFieldRenderer):
         elif isinstance(self.value, time):
             formatted_value = self.value.strftime("%H:%M")  # HH:MM
 
-        is_field_required = (
-            not self.is_optional
-            and self.field_info.default is None
-            and getattr(self.field_info, "default_factory", None) is None
-        )
+        # Determine if field is required
+        has_default = get_default(self.field_info) is not _UNSET
+        is_field_required = not self.is_optional and not has_default
 
         placeholder_text = f"Select {self.original_field_name.replace('_', ' ')}"
         if self.is_optional:
@@ -341,7 +440,10 @@ class TimeFieldRenderer(BaseFieldRenderer):
             "type": "time",
             "placeholder": placeholder_text,
             "required": is_field_required,
-            "cls": "w-full",
+            "cls": _merge_cls(
+                "w-full",
+                f"{spacing('input_size', self.spacing)} {spacing('input_padding', self.spacing)}".strip(),
+            ),
         }
 
         # Only add the disabled attribute if the field should actually be disabled
@@ -371,11 +473,8 @@ class LiteralFieldRenderer(BaseFieldRenderer):
             )
 
         # Determine if field is required
-        is_field_required = (
-            not self.is_optional
-            and self.field_info.default is None
-            and getattr(self.field_info, "default_factory", None) is None
-        )
+        has_default = get_default(self.field_info) is not _UNSET
+        is_field_required = not self.is_optional and not has_default
 
         # Create options for each literal value
         options = []
@@ -409,7 +508,95 @@ class LiteralFieldRenderer(BaseFieldRenderer):
             "name": self.field_name,
             "required": is_field_required,
             "placeholder": placeholder_text,
-            "cls": "w-full",
+            "cls": _merge_cls(
+                "w-full",
+                f"{spacing('input_size', self.spacing)} {spacing('input_padding', self.spacing)}".strip(),
+            ),
+        }
+
+        # Only add the disabled attribute if the field should actually be disabled
+        if self.disabled:
+            select_attrs["disabled"] = True
+
+        # Render the select element with options and attributes
+        return mui.Select(*options, **select_attrs)
+
+
+class EnumFieldRenderer(BaseFieldRenderer):
+    """Renderer for Enum fields as dropdown selects"""
+
+    def render_input(self) -> FT:
+        """
+        Render input element for the field as a select dropdown
+
+        Returns:
+            A Select component with options based on the Enum values
+        """
+        # Get the Enum class from annotation
+        annotation = _get_underlying_type_if_optional(self.field_info.annotation)
+        enum_class = annotation
+
+        if not (isinstance(enum_class, type) and issubclass(enum_class, Enum)):
+            return mui.Alert(
+                f"No enum class found for {self.field_name}", cls=mui.AlertT.warning
+            )
+
+        # Get all enum members
+        enum_members = list(enum_class)
+
+        if not enum_members:
+            return mui.Alert(
+                f"No enum values found for {self.field_name}", cls=mui.AlertT.warning
+            )
+
+        # Determine if field is required
+        has_default = get_default(self.field_info) is not _UNSET
+        is_field_required = not self.is_optional and not has_default
+
+        # Create options for each enum value
+        options = []
+        current_value_str = None
+
+        # Convert current value to string for comparison
+        if self.value is not None:
+            if isinstance(self.value, Enum):
+                current_value_str = str(self.value.value)
+            else:
+                current_value_str = str(self.value)
+
+        # Add empty option for optional fields
+        if self.is_optional:
+            options.append(
+                fh.Option("-- None --", value="", selected=(self.value is None))
+            )
+
+        # Add options for each enum member
+        for member in enum_members:
+            member_value_str = str(member.value)
+            display_name = member.name.replace("_", " ").title()
+            is_selected = current_value_str == member_value_str
+            options.append(
+                fh.Option(
+                    display_name,  # Display text
+                    value=member_value_str,  # Value attribute
+                    selected=is_selected,
+                )
+            )
+
+        placeholder_text = f"Select {self.original_field_name.replace('_', ' ')}"
+        if self.is_optional:
+            placeholder_text += " (Optional)"
+
+        # Prepare attributes dictionary
+        select_attrs = {
+            "id": self.field_name,
+            "name": self.field_name,
+            "required": is_field_required,
+            "placeholder": placeholder_text,
+            "cls": _merge_cls(
+                "w-full",
+                f"{spacing('input_size', self.spacing)} {spacing('input_padding', self.spacing)}".strip(),
+            ),
         }
 
         # Only add the disabled attribute if the field should actually be disabled
@@ -430,26 +617,36 @@ class BaseModelFieldRenderer(BaseFieldRenderer):
         Returns:
             A FastHTML component (mui.Accordion) containing the accordion structure.
         """
-        # 1. Get the label content (the inner Span with text/tooltip)
-        label_component = self.render_label()
-        if isinstance(label_component, fh.FT) and label_component.children:
-            label_content = label_component.children[0]
-            # Extract label style if present
-            label_style = label_component.attrs.get("style", "")
-            # Apply label style directly to the span if needed
-            if label_style:
-                # Check if label_content is already a Span, otherwise wrap it
-                if isinstance(label_content, fh.Span):
-                    label_content.attrs["style"] = label_style
-                else:
-                    # This case is less likely if render_label returns Label(Span(...))
-                    label_content = fh.Span(label_content, style=label_style)
+
+        # Extract the label text and apply color styling
+        label_text = self.original_field_name.replace("_", " ").title()
+
+        # Create the title component with proper color styling
+        if self.label_color:
+            if self._is_inline_color(self.label_color):
+                # Color value - apply as inline style
+                title_component = fh.Span(
+                    label_text,
+                    style=f"color: {self.label_color};",
+                    cls="text-sm font-medium",
+                )
+            else:
+                # CSS class - apply as Tailwind class (includes emerald, amber, rose, teal, indigo, lime, violet, etc.)
+                title_component = fh.Span(
+                    label_text,
+                    cls=f"text-sm font-medium {self._get_color_class(self.label_color)}",
+                )
         else:
-            # Fallback if structure is different (should not happen ideally)
-            label_content = self.original_field_name.replace("_", " ").title()
-            label_style = f"color: {self.label_color};" if self.label_color else ""
-            if label_style:
-                label_content = fh.Span(label_content, style=label_style)
+            # No color specified - use default styling
+            title_component = fh.Span(
+                label_text, cls="text-sm font-medium text-gray-700"
+            )
+
+        # Add tooltip if description is available
+        description = getattr(self.field_info, "description", None)
+        if description:
+            title_component.attrs["uk-tooltip"] = description
+            title_component.attrs["title"] = description
 
         # 2. Render the nested input fields that will be the accordion content
         input_component = self.render_input()
@@ -459,34 +656,30 @@ class BaseModelFieldRenderer(BaseFieldRenderer):
         accordion_id = f"{self.field_name}_accordion"
 
         # 4. Create the AccordionItem using the MonsterUI component
-        #    - Pass label_content as the title.
-        #    - Pass input_component as the content.
-        #    - Set 'open=True' to be expanded by default.
-        #    - Pass item_id via li_kwargs.
-        #    - Add 'mb-4' class for bottom margin spacing.
         accordion_item = mui.AccordionItem(
-            label_content,  # Title component (already potentially styled Span)
+            title_component,  # Title component with proper color styling
             input_component,  # Content component (the Card with nested fields)
             open=True,  # Open by default
             li_kwargs={"id": item_id},  # Pass the specific ID for the <li>
-            cls="mb-4",  # Add bottom margin to the <li> element
+            cls=spacing(
+                "outer_margin", self.spacing
+            ),  # Add bottom margin to the <li> element
         )
 
         # 5. Wrap the single AccordionItem in an Accordion container
-        #    - Set multiple=True (harmless for single item)
-        #    - Set collapsible=True
         accordion_container = mui.Accordion(
             accordion_item,  # The single item to include
             id=accordion_id,  # ID for the accordion container (ul)
             multiple=True,  # Allow multiple open (though only one exists)
             collapsible=True,  # Allow toggling
+            cls=f"{spacing('accordion_divider', self.spacing)} {spacing('accordion_content', self.spacing)}".strip(),
         )
 
         return accordion_container
 
     def render_input(self) -> FT:
         """
-        Render input elements for nested model fields
+        Render input elements for nested model fields with robust schema drift handling
 
         Returns:
             A Card component containing nested form fields
@@ -504,75 +697,151 @@ class BaseModelFieldRenderer(BaseFieldRenderer):
                 cls=mui.AlertT.error,
             )
 
-        # Prepare values dict
-        values_dict = (
-            self.value.model_dump()
-            if hasattr(self.value, "model_dump")
-            else self.value
-            if isinstance(self.value, dict)
-            else {}
-        )
+        # Robust value preparation
+        if isinstance(self.value, dict):
+            values_dict = self.value.copy()
+        elif hasattr(self.value, "model_dump"):
+            values_dict = self.value.model_dump()
+        else:
+            values_dict = {}
 
-        # Create nested field inputs directly instead of using FormRenderer
+        # Create nested field inputs with error handling
         nested_inputs = []
+        skipped_fields = []
 
+        # Only process fields that exist in current model schema
         for (
             nested_field_name,
             nested_field_info,
         ) in nested_model_class.model_fields.items():
-            # Determine initial value
-            nested_field_value = (
-                values_dict.get(nested_field_name) if values_dict else None
-            )
+            try:
+                # Check if field exists in provided values
+                field_was_provided = nested_field_name in values_dict
+                nested_field_value = (
+                    values_dict.get(nested_field_name) if field_was_provided else None
+                )
 
-            # Apply default if needed
-            if nested_field_value is None:
-                if nested_field_info.default is not None:
-                    nested_field_value = nested_field_info.default
-                elif getattr(nested_field_info, "default_factory", None) is not None:
-                    try:
-                        nested_field_value = nested_field_info.default_factory()
-                    except Exception:
-                        nested_field_value = None
-
-            # Get renderer for this nested field
-            registry = FieldRendererRegistry()  # Get singleton instance
-            renderer_cls = registry.get_renderer(nested_field_name, nested_field_info)
-
-            if not renderer_cls:
-                # Fall back to StringFieldRenderer if no renderer found
-                renderer_cls = StringFieldRenderer
-
-            # The prefix for nested fields is simply the field_name of this BaseModel instance + underscore
-            # field_name already includes the form prefix, so we don't need to add self.prefix again
-            nested_prefix = f"{self.field_name}_"
-
-            # Create and render the nested field
-            renderer = renderer_cls(
-                field_name=nested_field_name,
-                field_info=nested_field_info,
-                value=nested_field_value,
-                prefix=nested_prefix,
-                disabled=self.disabled,  # Propagate disabled state to nested fields
-            )
+                # Only use defaults if field wasn't provided
+                if not field_was_provided:
+                    if nested_field_info.default is not None:
+                        nested_field_value = nested_field_info.default
+                    elif (
+                        getattr(nested_field_info, "default_factory", None) is not None
+                    ):
+                        try:
+                            nested_field_value = nested_field_info.default_factory()
+                        except Exception as e:
+                            logger.warning(
+                                f"Default factory failed for {nested_field_name}: {e}"
+                            )
+                            nested_field_value = None
+
+                # Get renderer for this nested field
+                registry = FieldRendererRegistry()  # Get singleton instance
+                renderer_cls = registry.get_renderer(
+                    nested_field_name, nested_field_info
+                )
+
+                if not renderer_cls:
+                    # Fall back to StringFieldRenderer if no renderer found
+                    renderer_cls = StringFieldRenderer
+
+                # The prefix for nested fields is simply the field_name of this BaseModel instance + underscore
+                # field_name already includes the form prefix, so we don't need to add self.prefix again
+                nested_prefix = f"{self.field_name}_"
+
+                # Create and render the nested field
+                renderer = renderer_cls(
+                    field_name=nested_field_name,
+                    field_info=nested_field_info,
+                    value=nested_field_value,
+                    prefix=nested_prefix,
+                    disabled=self.disabled,  # Propagate disabled state to nested fields
+                    spacing=self.spacing,  # Propagate spacing to nested fields
+                    field_path=self.field_path + [nested_field_name],  # Propagate path
+                    form_name=self.explicit_form_name,  # Propagate form name
+                )
+
+                nested_inputs.append(renderer.render())
+
+            except Exception as e:
+                logger.warning(
+                    f"Skipping field {nested_field_name} in nested model: {e}"
+                )
+                skipped_fields.append(nested_field_name)
+                continue
 
-            nested_inputs.append(renderer.render())
+        # Log summary if fields were skipped
+        if skipped_fields:
+            logger.info(
+                f"Skipped {len(skipped_fields)} fields in {self.field_name}: {skipped_fields}"
+            )
 
         # Create container for nested inputs
         nested_form_content = mui.DivVStacked(
-            *nested_inputs, cls="space-y-3 items-stretch"
+            *nested_inputs,
+            cls=f"{spacing('inner_gap', self.spacing)} items-stretch",
         )
 
         # Wrap in card for visual distinction
+        t = self.spacing
         return mui.Card(
             nested_form_content,
-            cls="p-3 mt-1 border rounded",
+            cls=f"{spacing('padding_sm', t)} mt-1 {spacing('card_border', t)} rounded".strip(),
         )
 
 
 class ListFieldRenderer(BaseFieldRenderer):
     """Renderer for list fields containing any type"""
 
+    def _container_id(self) -> str:
+        """
+        Return a DOM-unique ID for the list's <ul> / <div> wrapper.
+
+        Format: <formname>_<hierarchy>_items_container
+        Example:  main_form_compact_tags_items_container
+        """
+        base = "_".join(self.field_path)  # tags  or  main_address_tags
+        if self._form_name:  # already resolved in property
+            return f"{self._form_name}_{base}_items_container"
+        return f"{base}_items_container"  # fallback (shouldn't happen)
+
+    @property
+    def _form_name(self) -> str:
+        """Get form name - prefer explicit form name if provided"""
+        if self.explicit_form_name:
+            return self.explicit_form_name
+
+        # Fallback to extracting from prefix (for backward compatibility)
+        # The prefix always starts with the form name followed by underscore
+        # e.g., "main_form_compact_" or "main_form_compact_main_address_tags_"
+        # We need to extract just "main_form_compact"
+        if self.prefix:
+            # For backward compatibility with existing non-nested lists
+            # Split by underscore and rebuild the form name by removing known field components
+            parts = self.prefix.rstrip("_").split("_")
+
+            # For a simple heuristic: form names typically have 2-3 parts (main_form_compact)
+            # Field paths are at the end, so we find where the form name ends
+            # This is imperfect but works for most cases
+            if len(parts) >= 3 and parts[1] == "form":
+                # Standard pattern: main_form_compact
+                form_name = "_".join(parts[:3])
+            elif len(parts) >= 2:
+                # Fallback: take first 2 parts
+                form_name = "_".join(parts[:2])
+            else:
+                # Single part
+                form_name = parts[0] if parts else ""
+
+            return form_name
+        return ""
+
+    @property
+    def _list_path(self) -> str:
+        """Get the hierarchical path for this list field"""
+        return "/".join(self.field_path)
+
     def render(self) -> FT:
         """
         Render the complete field (label + input) with spacing, adding a refresh icon for list fields.
@@ -582,13 +851,42 @@ class ListFieldRenderer(BaseFieldRenderer):
             A FastHTML component containing the complete field with refresh icon
         """
         # Extract form name from prefix (removing trailing underscore if present)
-        form_name = self.prefix.rstrip("_") if self.prefix else None
+        # form_name = self.prefix.rstrip("_") if self.prefix else None
+        form_name = self._form_name or None
+
+        # Create the label text with proper color styling
+        label_text = self.original_field_name.replace("_", " ").title()
 
-        # Get the original label
-        original_label = self.render_label()
+        # Create the styled label span
+        if self.label_color:
+            if self._is_inline_color(self.label_color):
+                # Color value - apply as inline style
+                label_span = fh.Span(
+                    label_text,
+                    style=f"color: {self.label_color};",
+                    cls=f"block text-sm font-medium {spacing('label_gap', self.spacing)}",
+                )
+            else:
+                # CSS class - apply as Tailwind class (includes emerald, amber, rose, teal, indigo, lime, violet, etc.)
+                label_span = fh.Span(
+                    label_text,
+                    cls=f"block text-sm font-medium {self._get_color_class(self.label_color)} {spacing('label_gap', self.spacing)}",
+                )
+        else:
+            # No color specified - use default styling
+            label_span = fh.Span(
+                label_text,
+                cls=f"block text-sm font-medium text-gray-700 {spacing('label_gap', self.spacing)}",
+            )
+
+        # Add tooltip if description is available
+        description = getattr(self.field_info, "description", None)
+        if description:
+            label_span.attrs["uk-tooltip"] = description
+            label_span.attrs["title"] = description
 
         # Construct the container ID that will be generated by render_input()
-        container_id = f"{self.prefix}{self.original_field_name}_items_container"
+        container_id = self._container_id()
 
         # Only add refresh icon if we have a form name
         if form_name:
@@ -605,28 +903,34 @@ class ListFieldRenderer(BaseFieldRenderer):
                 hx_post=f"/form/{form_name}/refresh",
                 hx_target=f"#{form_name}-inputs-wrapper",
                 hx_swap="innerHTML",
-                hx_include=f"#{form_name}-form",
+                hx_include="closest form",  # ← key change
                 uk_tooltip="Refresh form display to update list summaries",
+                # Prevent 'toggleListItems' on the parent from firing
+                onclick="event.stopPropagation();",
             )
 
             # Combine label and icon
             label_with_icon = fh.Div(
-                original_label,
+                label_span,  # Use the properly styled label span
                 refresh_icon_trigger,
                 cls="flex items-center cursor-pointer",  # Added cursor-pointer
                 onclick=f"toggleListItems('{container_id}'); return false;",  # Add click handler
             )
         else:
-            # If no form name, just use the original label but still make it clickable
+            # If no form name, just use the styled label but still make it clickable
             label_with_icon = fh.Div(
-                original_label,
+                label_span,  # Use the properly styled label span
                 cls="flex items-center cursor-pointer",  # Added cursor-pointer
                 onclick=f"toggleListItems('{container_id}'); return false;",  # Add click handler
                 uk_tooltip="Click to toggle all items open/closed",
             )
 
         # Return container with label+icon and input
-        return fh.Div(label_with_icon, self.render_input(), cls="mb-4")
+        return fh.Div(
+            label_with_icon,
+            self.render_input(),
+            cls=spacing("outer_margin", self.spacing),
+        )
 
     def render_input(self) -> FT:
         """
@@ -679,8 +983,8 @@ class ListFieldRenderer(BaseFieldRenderer):
                     )
                 )
 
-        # Container for list items with form-specific prefix in ID
-        container_id = f"{self.prefix}{self.original_field_name}_items_container"
+        # Container for list items using hierarchical field path
+        container_id = self._container_id()
 
         # Use mui.Accordion component
         accordion = mui.Accordion(
@@ -688,19 +992,16 @@ class ListFieldRenderer(BaseFieldRenderer):
             id=container_id,
             multiple=True,  # Allow multiple items to be open at once
             collapsible=True,  # Make it collapsible
-            cls="space-y-2",  # Add space between items
+            cls=f"{spacing('inner_gap_small', self.spacing)} {spacing('accordion_content', self.spacing)}".strip(),  # Add space between items and accordion content styling
         )
 
         # Empty state message if no items
         empty_state = ""
         if not items:
-            # Extract form name from prefix if available
-            form_name = self.prefix.rstrip("_") if self.prefix else None
-
-            # Check if it's a simple type or BaseModel
+            # Use hierarchical path for URL
             add_url = (
-                f"/form/{form_name}/list/add/{self.original_field_name}"
-                if form_name
+                f"/form/{self._form_name}/list/add/{self._list_path}"
+                if self._form_name
                 else f"/list/add/{self.field_name}"
             )
 
@@ -728,10 +1029,11 @@ class ListFieldRenderer(BaseFieldRenderer):
             )
 
         # Return the complete component
+        t = self.spacing
         return fh.Div(
             accordion,
             empty_state,
-            cls="mb-4 border rounded-md p-4",
+            cls=f"{spacing('outer_margin', t)} {spacing('card_border', t)} rounded-md {spacing('padding', t)}".strip(),
         )
 
     def _render_item_card(self, item, idx, item_type, is_open=False) -> FT:
@@ -752,9 +1054,6 @@ class ListFieldRenderer(BaseFieldRenderer):
             item_id = f"{self.field_name}_{idx}"
             item_card_id = f"{item_id}_card"
 
-            # Extract form name from prefix if available
-            form_name = self.prefix.rstrip("_") if self.prefix else None
-
             # Check if it's a simple type or BaseModel
             is_model = hasattr(item_type, "model_fields")
 
@@ -767,8 +1066,8 @@ class ListFieldRenderer(BaseFieldRenderer):
                         model_for_display = item
 
                     elif isinstance(item, dict):
-                        # Item is a dict, try to create a model instance for display
-                        model_for_display = item_type.model_validate(item)
+                        # Item is a dict, use model_construct for better performance (defaults are known-good)
+                        model_for_display = item_type.model_construct(**item)
 
                     else:
                         # Handle cases where item is None or unexpected type
@@ -812,17 +1111,17 @@ class ListFieldRenderer(BaseFieldRenderer):
             item_content_elements = []
 
             if is_model:
-                # Handle BaseModel items - include the form prefix in nested items
+                # Handle BaseModel items with robust schema drift handling
                 # Form name prefix + field name + index + _
                 name_prefix = f"{self.prefix}{self.original_field_name}_{idx}_"
 
-                nested_values = (
-                    item.model_dump()
-                    if hasattr(item, "model_dump")
-                    else item
-                    if isinstance(item, dict)
-                    else {}
-                )
+                # Robust value preparation for schema drift handling
+                if isinstance(item, dict):
+                    nested_values = item.copy()
+                elif hasattr(item, "model_dump"):
+                    nested_values = item.model_dump()
+                else:
+                    nested_values = {}
 
                 # Check if there's a specific renderer registered for this item_type
                 registry = FieldRendererRegistry()
@@ -853,44 +1152,76 @@ class ListFieldRenderer(BaseFieldRenderer):
                     # Add the rendered input to content elements
                     item_content_elements.append(item_renderer.render_input())
                 else:
-                    # Fall back to original behavior: render each field individually
+                    # Fall back to original behavior: render each field individually with schema drift handling
+                    valid_fields = []
+                    skipped_fields = []
+
+                    # Only process fields that exist in current model
                     for (
                         nested_field_name,
                         nested_field_info,
                     ) in item_type.model_fields.items():
-                        nested_field_value = nested_values.get(nested_field_name)
-
-                        # Apply default if needed
-                        if (
-                            nested_field_value is None
-                            and hasattr(nested_field_info, "default")
-                            and nested_field_info.default is not None
-                        ):
-                            nested_field_value = nested_field_info.default
-                        elif (
-                            nested_field_value is None
-                            and hasattr(nested_field_info, "default_factory")
-                            and nested_field_info.default_factory is not None
-                        ):
-                            try:
-                                nested_field_value = nested_field_info.default_factory()
-                            except Exception:
-                                pass
-
-                        # Get renderer and render field
-                        renderer_cls = FieldRendererRegistry().get_renderer(
-                            nested_field_name, nested_field_info
-                        )
-                        renderer = renderer_cls(
-                            field_name=nested_field_name,
-                            field_info=nested_field_info,
-                            value=nested_field_value,
-                            prefix=name_prefix,
-                            disabled=self.disabled,  # Propagate disabled state
+                        try:
+                            field_was_provided = nested_field_name in nested_values
+                            nested_field_value = (
+                                nested_values.get(nested_field_name)
+                                if field_was_provided
+                                else None
+                            )
+
+                            # Use defaults only if field not provided
+                            if not field_was_provided:
+                                if nested_field_info.default is not None:
+                                    nested_field_value = nested_field_info.default
+                                elif (
+                                    getattr(nested_field_info, "default_factory", None)
+                                    is not None
+                                ):
+                                    try:
+                                        nested_field_value = (
+                                            nested_field_info.default_factory()
+                                        )
+                                    except Exception:
+                                        continue  # Skip fields with problematic defaults
+
+                            # Get renderer and render field with error handling
+                            renderer_cls = FieldRendererRegistry().get_renderer(
+                                nested_field_name, nested_field_info
+                            )
+                            if not renderer_cls:
+                                renderer_cls = StringFieldRenderer
+
+                            renderer = renderer_cls(
+                                field_name=nested_field_name,
+                                field_info=nested_field_info,
+                                value=nested_field_value,
+                                prefix=name_prefix,
+                                disabled=self.disabled,  # Propagate disabled state
+                                spacing=self.spacing,  # Propagate spacing
+                                field_path=self.field_path
+                                + [
+                                    str(idx),
+                                    nested_field_name,
+                                ],  # Propagate path with index
+                            )
+
+                            # Add rendered field to valid fields
+                            valid_fields.append(renderer.render())
+
+                        except Exception as e:
+                            logger.warning(
+                                f"Skipping problematic field {nested_field_name} in list item: {e}"
+                            )
+                            skipped_fields.append(nested_field_name)
+                            continue
+
+                    # Log summary if fields were skipped
+                    if skipped_fields:
+                        logger.info(
+                            f"Skipped {len(skipped_fields)} fields in list item {idx}: {skipped_fields}"
                         )
 
-                        # Add rendered field to content elements
-                        item_content_elements.append(renderer.render())
+                    item_content_elements = valid_fields
             else:
                 # Handle simple type items
                 field_info = FieldInfo(annotation=item_type)
@@ -906,21 +1237,24 @@ class ListFieldRenderer(BaseFieldRenderer):
                     value=item,
                     prefix=self.prefix,  # Correct: Provide the form prefix
                     disabled=self.disabled,  # Propagate disabled state
+                    spacing=self.spacing,  # Propagate spacing
+                    field_path=self.field_path
+                    + [str(idx)],  # Propagate path with index
                 )
                 input_element = simple_renderer.render_input()
                 item_content_elements.append(fh.Div(input_element))
 
             # --- Create action buttons with form-specific URLs ---
-            # Generate HTMX endpoints with form name if available
+            # Generate HTMX endpoints using hierarchical paths
             delete_url = (
-                f"/form/{form_name}/list/delete/{self.original_field_name}"
-                if form_name
+                f"/form/{self._form_name}/list/delete/{self._list_path}"
+                if self._form_name
                 else f"/list/delete/{self.field_name}"
             )
 
             add_url = (
-                f"/form/{form_name}/list/add/{self.original_field_name}"
-                if form_name
+                f"/form/{self._form_name}/list/add/{self._list_path}"
+                if self._form_name
                 else f"/list/add/{self.field_name}"
             )
 
@@ -986,6 +1320,7 @@ class ListFieldRenderer(BaseFieldRenderer):
             )
 
             # Assemble actions div
+            t = self.spacing
             actions = fh.Div(
                 fh.Div(  # Left side buttons
                     delete_button, add_below_button, cls="flex items-center"
@@ -993,11 +1328,15 @@ class ListFieldRenderer(BaseFieldRenderer):
                 fh.Div(  # Right side buttons
                     move_up_button, move_down_button, cls="flex items-center space-x-1"
                 ),
-                cls="flex justify-between w-full mt-3 pt-3 border-t border-gray-200",
+                cls=f"flex justify-between w-full mt-3 pt-3 {spacing('section_divider', t)}".strip(),
             )
 
             # Create a wrapper Div for the main content elements with proper padding
-            content_wrapper = fh.Div(*item_content_elements, cls="px-4 py-3 space-y-3")
+            t = self.spacing
+            content_wrapper = fh.Div(
+                *item_content_elements,
+                cls=f"{spacing('card_body_pad', t)} {spacing('inner_gap', t)}",
+            )
 
             # Return the accordion item
             title_component = fh.Span(
@@ -1005,11 +1344,16 @@ class ListFieldRenderer(BaseFieldRenderer):
             )
             li_attrs = {"id": full_card_id}
 
+            # Build card classes conditionally based on spacing theme
+            card_cls = "uk-card uk-margin-small-bottom"
+            if self.spacing == SpacingTheme.NORMAL:
+                card_cls += " uk-card-default"
+
             return mui.AccordionItem(
                 title_component,  # Title as first positional argument
                 content_wrapper,  # Use the new padded wrapper for content
                 actions,  # More content elements
-                cls="uk-card uk-card-default uk-margin-small-bottom",  # Use cls keyword arg directly
+                cls=card_cls,  # Use theme-aware card classes
                 open=is_open,
                 li_kwargs=li_attrs,  # Pass remaining li attributes without cls
             )
@@ -1023,11 +1367,17 @@ class ListFieldRenderer(BaseFieldRenderer):
             li_attrs = {"id": f"{self.field_name}_{idx}_error_card"}
 
             # Wrap error component in a div with consistent padding
-            content_wrapper = fh.Div(content_component, cls="px-4 py-3")
+            t = self.spacing
+            content_wrapper = fh.Div(content_component, cls=spacing("card_body_pad", t))
+
+            # Build card classes conditionally based on spacing theme
+            card_cls = "uk-card uk-margin-small-bottom"
+            if self.spacing == SpacingTheme.NORMAL:
+                card_cls += " uk-card-default"
 
             return mui.AccordionItem(
                 title_component,  # Title as first positional argument
                 content_wrapper,  # Wrapped content element
-                cls="mb-2",  # Use cls keyword arg directly
+                cls=card_cls,  # Use theme-aware card classes
                 li_kwargs=li_attrs,  # Pass remaining li attributes without cls
             )