fh-pydantic-form 0.2.4__py3-none-any.whl → 0.3.0__py3-none-any.whl

fh_pydantic_form/form_parser.py

@@ -7,6 +7,8 @@ from typing import (
     Optional,
     Tuple,
     Union,
+    get_origin,
+    get_args,
 )
 
 from fh_pydantic_form.type_helpers import (
@@ -33,17 +35,16 @@ def _identify_list_fields(model_class) -> Dict[str, Dict[str, Any]]:
     list_fields = {}
     for field_name, field_info in model_class.model_fields.items():
         annotation = getattr(field_info, "annotation", None)
-        if (
-            annotation is not None
-            and hasattr(annotation, "__origin__")
-            and annotation.__origin__ is list
-        ):
-            item_type = annotation.__args__[0]
-            list_fields[field_name] = {
-                "item_type": item_type,
-                "is_model_type": hasattr(item_type, "model_fields"),
-                "field_info": field_info,  # Store for later use if needed
-            }
+        if annotation is not None:
+            # Handle Optional[List[...]] by unwrapping the Optional
+            base_ann = _get_underlying_type_if_optional(annotation)
+            if get_origin(base_ann) is list:
+                item_type = get_args(base_ann)[0]
+                list_fields[field_name] = {
+                    "item_type": item_type,
+                    "is_model_type": hasattr(item_type, "model_fields"),
+                    "field_info": field_info,  # Store for later use if needed
+                }
     return list_fields
 
 
@@ -128,9 +129,14 @@ def _parse_non_list_fields(
             # Get the nested model class (unwrap Optional if needed)
             nested_model_class = _get_underlying_type_if_optional(annotation)
 
-            # Parse the nested model - pass the base_prefix
+            # Parse the nested model - pass the base_prefix and exclude_fields
             nested_value = _parse_nested_model_field(
-                field_name, form_data, nested_model_class, field_info, base_prefix
+                field_name,
+                form_data,
+                nested_model_class,
+                field_info,
+                base_prefix,
+                exclude_fields,
             )
 
             # Only assign if we got a non-None value or the field is not optional
@@ -270,6 +276,7 @@ def _parse_nested_model_field(
     nested_model_class,
     field_info,
     parent_prefix: str = "",
+    exclude_fields: Optional[List[str]] = None,
 ) -> Optional[Dict[str, Any]]:
     """
     Parse a nested Pydantic model field from form data.
@@ -351,6 +358,7 @@ def _parse_nested_model_field(
                 form_data,
                 nested_list_defs,
                 current_prefix,  # ← prefix for this nested model
+                exclude_fields,  # Pass through exclude_fields
             )
             # Merge without clobbering keys already set in step 1
             for lf_name, lf_val in list_results.items():
@@ -432,6 +440,7 @@ def _parse_list_fields(
     form_data: Dict[str, Any],
     list_field_defs: Dict[str, Dict[str, Any]],
     base_prefix: str = "",
+    exclude_fields: Optional[List[str]] = None,
 ) -> Dict[str, List[Any]]:
     """
     Parse list fields from form data by analyzing keys and reconstructing ordered lists.
@@ -440,10 +449,13 @@ def _parse_list_fields(
         form_data: Dictionary containing form field data
         list_field_defs: Dictionary of list field definitions
         base_prefix: Prefix to use when looking up field names in form_data
+        exclude_fields: Optional list of field names to exclude from parsing
 
     Returns:
         Dictionary with parsed list fields
     """
+    exclude_fields = exclude_fields or []
+
     # Skip if no list fields defined
     if not list_field_defs:
         return {}
@@ -525,9 +537,18 @@ def _parse_list_fields(
         if items:  # Only add if items were found
             final_lists[field_name] = items
 
-    # DON'T set defaults for missing list fields here - let _inject_missing_defaults handle all defaults
-    # This allows the proper default injection mechanism to work for missing list fields
-    # Only keep this section for excluded fields if needed, but don't inject defaults for all missing fields
+    # Ensure every rendered list field appears in final_lists
+    for field_name, field_def in list_field_defs.items():
+        # Skip list fields the UI never showed (those in exclude_fields)
+        if field_name in exclude_fields:
+            continue
+
+        # When user supplied ≥1 item we already captured it
+        if field_name in final_lists:
+            continue
+
+        # User submitted form with zero items → honour intent with empty list
+        final_lists[field_name] = []
 
     return final_lists
 
@@ -560,7 +581,9 @@ def _parse_model_list_item(
     )
     # 2. Parse inner lists
     result.update(
-        _parse_list_fields(form_data, nested_list_defs, base_prefix=item_prefix)
+        _parse_list_fields(
+            form_data, nested_list_defs, base_prefix=item_prefix, exclude_fields=[]
+        )
     )
     return result
 

fh_pydantic_form/form_renderer.py

@@ -31,7 +31,10 @@ from fh_pydantic_form.form_parser import (
 )
 from fh_pydantic_form.list_path import walk_path
 from fh_pydantic_form.registry import FieldRendererRegistry
-from fh_pydantic_form.type_helpers import _is_skip_json_schema_field, get_default
+from fh_pydantic_form.type_helpers import (
+    _is_skip_json_schema_field,
+    get_default,
+)
 from fh_pydantic_form.ui_style import (
     SpacingTheme,
     SpacingValue,
@@ -211,46 +214,6 @@ class PydanticForm(Generic[ModelType]):
 
     # --- module-level flag (add near top of file) ---
 
-    def _compact_wrapper(self, inner: FT) -> FT:
-        """
-        Wrap inner markup in a wrapper div.
-        """
-        wrapper_cls = "fhpf-wrapper w-full flex-1"
-        return fh.Div(inner, cls=wrapper_cls)
-
-    def _clone_with_values(self, values: Dict[str, Any]) -> "PydanticForm":
-        """
-        Create a copy of this renderer with the same configuration but different values.
-
-        This preserves all constructor arguments (label_colors, custom_renderers, etc.)
-        to avoid configuration drift during refresh operations.
-
-        Args:
-            values: New values dictionary to use in the cloned renderer
-
-        Returns:
-            A new PydanticForm instance with identical configuration but updated values
-        """
-        # Get custom renderers if they were registered (not stored directly on instance)
-        # We'll rely on global registry state being preserved
-
-        clone = PydanticForm(
-            form_name=self.name,
-            model_class=self.model_class,
-            initial_values=None,  # Will be set via values_dict below
-            custom_renderers=None,  # Registry is global, no need to re-register
-            disabled=self.disabled,
-            disabled_fields=self.disabled_fields,
-            label_colors=self.label_colors,
-            exclude_fields=self.exclude_fields,
-            spacing=self.spacing,
-        )
-
-        # Set the values directly
-        clone.values_dict = values
-
-        return clone
-
     def __init__(
         self,
         form_name: str,
@@ -262,6 +225,7 @@ class PydanticForm(Generic[ModelType]):
         label_colors: Optional[Dict[str, str]] = None,
         exclude_fields: Optional[List[str]] = None,
         spacing: SpacingValue = SpacingTheme.NORMAL,
+        metrics_dict: Optional[Dict[str, Any]] = None,
     ):
         """
         Initialize the form renderer
@@ -278,6 +242,7 @@ class PydanticForm(Generic[ModelType]):
             label_colors: Optional dictionary mapping field names to label colors (CSS color values)
             exclude_fields: Optional list of top-level field names to exclude from the form
             spacing: Spacing theme to use for form layout ("normal", "compact", or SpacingTheme enum)
+            metrics_dict: Optional metrics dictionary for field-level visual feedback
         """
         self.name = form_name
         self.model_class = model_class
@@ -319,6 +284,7 @@ class PydanticForm(Generic[ModelType]):
         self.label_colors = label_colors or {}  # Store label colors mapping
         self.exclude_fields = exclude_fields or []  # Store excluded fields list
         self.spacing = _normalize_spacing(spacing)  # Store normalized spacing
+        self.metrics_dict = metrics_dict or {}  # Store metrics dictionary
 
         # Register custom renderers with the global registry if provided
         if custom_renderers:
@@ -326,6 +292,54 @@ class PydanticForm(Generic[ModelType]):
             for field_type, renderer_cls in custom_renderers:
                 registry.register_type_renderer(field_type, renderer_cls)
 
+    def _compact_wrapper(self, inner: FT) -> FT:
+        """
+        Wrap inner markup in a wrapper div.
+        """
+        wrapper_cls = "fhpf-wrapper w-full flex-1"
+        return fh.Div(inner, cls=wrapper_cls)
+
+    def reset_state(self) -> None:
+        """
+        Restore the live state of the form to its immutable baseline.
+        Call this *before* rendering if you truly want a factory-fresh view.
+        """
+        self.values_dict = self.initial_values_dict.copy()
+
+    def _clone_with_values(self, values: Dict[str, Any]) -> "PydanticForm":
+        """
+        Create a copy of this renderer with the same configuration but different values.
+
+        This preserves all constructor arguments (label_colors, custom_renderers, etc.)
+        to avoid configuration drift during refresh operations.
+
+        Args:
+            values: New values dictionary to use in the cloned renderer
+
+        Returns:
+            A new PydanticForm instance with identical configuration but updated values
+        """
+        # Get custom renderers if they were registered (not stored directly on instance)
+        # We'll rely on global registry state being preserved
+
+        clone = PydanticForm(
+            form_name=self.name,
+            model_class=self.model_class,
+            initial_values=None,  # Will be set via values_dict below
+            custom_renderers=None,  # Registry is global, no need to re-register
+            disabled=self.disabled,
+            disabled_fields=self.disabled_fields,
+            label_colors=self.label_colors,
+            exclude_fields=self.exclude_fields,
+            spacing=self.spacing,
+            metrics_dict=self.metrics_dict,
+        )
+
+        # Set the values directly
+        clone.values_dict = values
+
+        return clone
+
     def render_inputs(self) -> FT:
         """
         Render just the form inputs based on the model class (no form tag)
@@ -431,6 +445,8 @@ class PydanticForm(Generic[ModelType]):
                 label_color=label_color,  # Pass the label color if specified
                 spacing=self.spacing,  # Pass the spacing
                 field_path=[field_name],  # Set top-level field path
+                form_name=self.name,  # Pass form name
+                metrics_dict=self.metrics_dict,  # Pass the metrics dict
             )
 
             rendered_field = renderer.render()
@@ -453,6 +469,34 @@ class PydanticForm(Generic[ModelType]):
 
         return wrapped
 
+    def _filter_by_prefix(self, data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Filter form data to include only keys that start with this form's base_prefix.
+
+        This prevents cross-contamination when multiple forms share the same HTML form element.
+
+        Args:
+            data: Raw form data dictionary
+
+        Returns:
+            Filtered dictionary containing only keys with matching prefix
+        """
+        if not self.base_prefix:
+            return data  # No prefix = no filtering needed
+
+        filtered = {
+            key: value
+            for key, value in data.items()
+            if key.startswith(self.base_prefix)
+        }
+
+        logger.debug(
+            f"Filtered form data for '{self.name}': "
+            f"{len(data)} keys -> {len(filtered)} keys"
+        )
+
+        return filtered
+
     # ---- Form Renderer Methods (continued) ----
 
     async def handle_refresh_request(self, req):
@@ -467,6 +511,10 @@ class PydanticForm(Generic[ModelType]):
         """
         form_data = await req.form()
         form_dict = dict(form_data)
+
+        # Filter to only this form's fields
+        form_dict = self._filter_by_prefix(form_dict)
+
         logger.info(f"Refresh request for form '{self.name}'")
 
         parsed_data = {}
@@ -481,15 +529,27 @@ class PydanticForm(Generic[ModelType]):
                 f"Error parsing form data for refresh on form '{self.name}': {e}",
                 exc_info=True,
             )
-            # Fallback: Use original initial values dict if available, otherwise empty dict
-            parsed_data = (
-                self.initial_values_dict.copy() if self.initial_values_dict else {}
-            )
+
+            # Merge strategy - preserve existing values for unparseable fields
+            # Start with current values
+            parsed_data = self.values_dict.copy() if self.values_dict else {}
+
+            # Try to extract any simple fields that don't require complex parsing
+            for key, value in form_dict.items():
+                if key.startswith(self.base_prefix):
+                    field_name = key[len(self.base_prefix) :]
+                    # Only update simple fields to avoid corruption
+                    if "_" not in field_name:  # Not a nested field
+                        parsed_data[field_name] = value
+
             alert_ft = mui.Alert(
-                f"Warning: Could not fully process current form values for refresh. Display might not be fully updated. Error: {str(e)}",
+                f"Warning: Some fields could not be refreshed. Preserved previous values. Error: {str(e)}",
                 cls=mui.AlertT.warning + " mb-4",  # Add margin bottom
             )
 
+        # Parsed successfully (or merged best effort) – make it the new truth
+        self.values_dict = parsed_data.copy()
+
         # Create temporary renderer with same configuration but updated values
         temp_renderer = self._clone_with_values(parsed_data)
 
@@ -519,6 +579,9 @@ class PydanticForm(Generic[ModelType]):
         Returns:
             HTML response with reset form inputs
         """
+        # Rewind internal state to the immutable baseline
+        self.reset_state()
+
         logger.info(f"Resetting form '{self.name}' to initial values")
 
         # Create temporary renderer with original initial dict
@@ -532,6 +595,7 @@ class PydanticForm(Generic[ModelType]):
             label_colors=self.label_colors,
             exclude_fields=self.exclude_fields,
             spacing=self.spacing,
+            metrics_dict=self.metrics_dict,
         )
 
         reset_inputs_component = temp_renderer.render_inputs()
@@ -739,6 +803,7 @@ class PydanticForm(Generic[ModelType]):
                 disabled=self.disabled,
                 field_path=segments,  # Pass the full path segments
                 form_name=self.name,  # Pass the explicit form name
+                metrics_dict=self.metrics_dict,  # Pass the metrics dict
             )
 
             # Generate a unique placeholder index

fh_pydantic_form/type_helpers.py

@@ -5,19 +5,39 @@ __all__ = [
     "_is_literal_type",
     "_is_enum_type",
     "_is_skip_json_schema_field",
-    "default_for_annotation",
+    "MetricEntry",
+    "MetricsDict",
+    "DecorationScope",
 ]
 
+
 import logging
 from enum import Enum
 from types import UnionType
-from typing import Annotated, Any, Literal, Union, get_args, get_origin
+from typing import (
+    Annotated,
+    Any,
+    Dict,
+    Literal,
+    TypedDict,
+    Union,
+    get_args,
+    get_origin,
+)
 
 from fh_pydantic_form.constants import _UNSET
 
 logger = logging.getLogger(__name__)
 
 
+class DecorationScope(str, Enum):
+    """Controls which metric decorations are applied to an element"""
+
+    BORDER = "border"
+    BULLET = "bullet"
+    BOTH = "both"
+
+
 def _is_skip_json_schema_field(annotation_or_field_info: Any) -> bool:
     """
     Check if a field annotation or field_info indicates it should be skipped in JSON schema.
@@ -85,6 +105,21 @@ def _is_skip_json_schema_field(annotation_or_field_info: Any) -> bool:
     return "SkipJsonSchema" in repr(annotation)
 
 
+# Metrics types for field-level annotations
+class MetricEntry(TypedDict, total=False):
+    """Metrics for annotating field values with scores, colors, and comments"""
+
+    metric: float | int | str  # Metric value (0-1 score, count, or label)
+    color: str  # CSS-compatible color string
+    comment: str  # Free-form text for tooltips/hover
+
+
+# Type alias for metrics mapping
+MetricsDict = Dict[
+    str, MetricEntry
+]  # Keys are dot-paths like "address.street" or "tags[0]"
+
+
 def _is_optional_type(annotation: Any) -> bool:
     """
     Check if an annotation is Optional[T] (Union[T, None]).
@@ -209,7 +244,3 @@ def _is_pydantic_undefined(value: Any) -> bool:
         pass
 
     return False
-
-
-# Local import placed after _UNSET is defined to avoid circular-import problems
-from .defaults import default_for_annotation  # noqa: E402

fh_pydantic_form/ui_style.py

@@ -44,6 +44,7 @@ SPACING_MAP: Dict[SpacingTheme, Dict[str, str]] = {
         "card_border": "border",
         "card_border_thin": "",
         "section_divider": "border-t border-gray-200",
+        "metric_badge_gap": "ml-2",
         "accordion_divider": "uk-accordion-divider",
         "accordion_title_pad": "",
         "accordion_content_pad": "",
@@ -70,6 +71,7 @@ SPACING_MAP: Dict[SpacingTheme, Dict[str, str]] = {
         "card_border": "",
         "card_border_thin": "",
         "section_divider": "",
+        "metric_badge_gap": "ml-1",
         "accordion_divider": "",
         "accordion_title_pad": "py-1",
         "accordion_content_pad": "py-1",