fh-pydantic-form 0.3.9__py3-none-any.whl

fh_pydantic_form/list_path.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+import logging
+from typing import List, Tuple, Type, get_origin, get_args
+from pydantic import BaseModel
+from pydantic.fields import FieldInfo
+
+from fh_pydantic_form.type_helpers import _get_underlying_type_if_optional
+
+logger = logging.getLogger(__name__)
+
+
+def walk_path(
+    model: Type[BaseModel], segments: List[str]
+) -> Tuple[FieldInfo, List[str], Type]:
+    """
+    Resolve `segments` against `model`, stopping at the *list* field.
+
+    Args:
+        model: The BaseModel class to traverse
+        segments: Path segments like ["main_address", "tags"] or ["other_addresses", "1", "tags"]
+                 The final segment should always be a list field name.
+
+    Returns:
+        Tuple of:
+        - list_field_info: the FieldInfo for the target list field
+        - html_prefix_parts: segments used to build element IDs (includes indices)
+        - item_type: the concrete python type of items in the list
+
+    Raises:
+        ValueError: if the path is invalid or doesn't lead to a list field
+    """
+    if not segments:
+        raise ValueError("Empty path provided")
+
+    current_model = model
+    html_parts = []
+    i = 0
+
+    # Process all segments except the last one (which should be the list field)
+    while i < len(segments) - 1:
+        segment = segments[i]
+
+        # Check if this segment is a field name
+        if segment in current_model.model_fields:
+            field_info = current_model.model_fields[segment]
+            field_type = _get_underlying_type_if_optional(field_info.annotation)
+            html_parts.append(segment)
+
+            # Check if this is a list field (we're traversing into a list element)
+            if get_origin(field_type) is list:
+                # Next segment should be an index
+                if i + 1 >= len(segments) - 1:
+                    raise ValueError(f"Expected index after list field '{segment}'")
+
+                next_segment = segments[i + 1]
+                if not _is_index_segment(next_segment):
+                    raise ValueError(
+                        f"Expected index after list field '{segment}', got '{next_segment}'"
+                    )
+
+                # Get the item type of the list
+                list_item_type = (
+                    get_args(field_type)[0] if get_args(field_type) else None
+                )
+                if not list_item_type or not hasattr(list_item_type, "model_fields"):
+                    raise ValueError(
+                        f"List field '{segment}' does not contain BaseModel items"
+                    )
+
+                # Add the index to html_parts and update current model
+                html_parts.append(next_segment)
+                current_model = list_item_type
+
+                # Skip the next segment (the index) since we processed it
+                i += 2
+                continue
+
+            # Check if this is a BaseModel field
+            elif hasattr(field_type, "model_fields"):
+                current_model = field_type
+                i += 1
+            else:
+                raise ValueError(f"Field '{segment}' is not a BaseModel or list type")
+
+        elif _is_index_segment(segment):
+            # This should only happen if we're processing an index that wasn't handled above
+            raise ValueError(
+                f"Unexpected index segment '{segment}' without preceding list field"
+            )
+        else:
+            raise ValueError(
+                f"Field '{segment}' not found in model {current_model.__name__}"
+            )
+
+    # Process the final segment (should be a list field)
+    final_field_name = segments[-1]
+    if final_field_name not in current_model.model_fields:
+        raise ValueError(
+            f"Field '{final_field_name}' not found in model {current_model.__name__}"
+        )
+
+    list_field_info = current_model.model_fields[final_field_name]
+    list_field_type = _get_underlying_type_if_optional(list_field_info.annotation)
+
+    # Verify this is actually a list field
+    if get_origin(list_field_type) is not list:
+        raise ValueError(f"Final field '{final_field_name}' is not a list type")
+
+    # Get the item type
+    item_type_args = get_args(list_field_type)
+    if not item_type_args:
+        raise ValueError(
+            f"Cannot determine item type for list field '{final_field_name}'"
+        )
+
+    item_type = item_type_args[0]
+    html_parts.append(final_field_name)
+
+    logger.debug(
+        f"walk_path resolved: {segments} -> field_info={list_field_info}, html_parts={html_parts}, item_type={item_type}"
+    )
+
+    return list_field_info, html_parts, item_type
+
+
+def _is_index_segment(segment: str) -> bool:
+    """
+    Check if a segment represents an index (purely numeric or placeholder like 'new_1234').
+
+    Args:
+        segment: The segment to check
+
+    Returns:
+        True if the segment represents an index
+    """
+    # Pure numeric (like "0", "1", "2")
+    if segment.isdigit():
+        return True
+
+    # Placeholder format (like "new_1234567890")
+    if segment.startswith("new_") and len(segment) > 4:
+        timestamp_part = segment[4:]
+        return timestamp_part.isdigit()
+
+    return False

fh_pydantic_form/registry.py

@@ -0,0 +1,142 @@
+from logging import getLogger
+from typing import (
+    Any,
+    ClassVar,
+    Dict,
+    List,
+    Optional,
+    Tuple,
+    Type,
+)
+
+from pydantic.fields import FieldInfo
+
+from fh_pydantic_form.type_helpers import _get_underlying_type_if_optional
+
+logger = getLogger(__name__)
+
+
+class FieldRendererRegistry:
+    """
+    Registry for field renderers with support for type and predicate-based registration
+
+    This registry manages:
+    - Type-specific renderers (e.g., for str, int, bool)
+    - Type-name-specific renderers (by class name)
+    - Predicate-based renderers (e.g., for Literal fields)
+    - List item renderers for specialized list item rendering
+
+    It uses a singleton pattern to ensure consistent registration across the app.
+    """
+
+    _instance = None  # Add class attribute to hold the single instance
+
+    # Use ClassVar for all registry storage
+    _type_renderers: ClassVar[Dict[Type, Any]] = {}
+    _type_name_renderers: ClassVar[Dict[str, Any]] = {}
+    _predicate_renderers: ClassVar[List[Tuple[Any, Any]]] = []
+    _list_item_renderers: ClassVar[Dict[Type, Any]] = {}
+
+    def __new__(cls, *args, **kwargs):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    @classmethod
+    def register_type_renderer(cls, field_type: Type, renderer_cls: Any) -> None:
+        """Register a renderer for a field type"""
+        cls._type_renderers[field_type] = renderer_cls
+
+    @classmethod
+    def register_type_name_renderer(
+        cls, field_type_name: str, renderer_cls: Any
+    ) -> None:
+        """Register a renderer for a specific field type name"""
+        cls._type_name_renderers[field_type_name] = renderer_cls
+
+    @classmethod
+    def register_type_renderer_with_predicate(cls, predicate_func, renderer_cls):
+        """
+        Register a renderer with a predicate function
+
+        The predicate function should accept a field_info parameter and return
+        True if the renderer should be used for that field.
+        """
+        cls._predicate_renderers.append((predicate_func, renderer_cls))
+
+    @classmethod
+    def register_list_item_renderer(cls, item_type: Type, renderer_cls: Any) -> None:
+        """Register a renderer for list items of a specific type"""
+        cls._list_item_renderers[item_type] = renderer_cls
+
+    @classmethod
+    def get_renderer(cls, field_name: str, field_info: FieldInfo) -> Any:
+        """
+        Get the appropriate renderer for a field
+
+        The selection algorithm:
+        1. Check exact type matches
+        2. Check predicate renderers (for special cases like Literal fields)
+        3. Check for subclass relationships
+        4. Fall back to string renderer
+
+        Args:
+            field_name: The name of the field being rendered
+            field_info: The FieldInfo for the field
+
+        Returns:
+            A renderer class appropriate for the field
+        """
+        # Get the field type (unwrap Optional if present)
+        original_annotation = field_info.annotation
+        field_type = _get_underlying_type_if_optional(original_annotation)
+
+        # 1. Check exact type matches first
+        if field_type in cls._type_renderers:
+            return cls._type_renderers[field_type]
+
+        # 2. Check predicates second
+        for predicate, renderer in cls._predicate_renderers:
+            if predicate(field_info):
+                return renderer
+
+        # 3. Check for subclass relationships
+        if isinstance(field_type, type):
+            for typ, renderer in cls._type_renderers.items():
+                try:
+                    if isinstance(typ, type) and issubclass(field_type, typ):
+                        return renderer
+                except TypeError:
+                    # Handle non-class types
+                    continue
+
+        # 4. Fall back to string renderer
+        from_imports = globals()
+        return from_imports.get("StringFieldRenderer", None)
+
+    @classmethod
+    def get_list_item_renderer(cls, item_type: Type) -> Optional[Any]:
+        """
+        Get renderer for summarizing list items of a given type
+
+        Args:
+            item_type: The type of the list items
+
+        Returns:
+            A renderer class for list items, or None if none is registered
+        """
+        # Check for exact type match
+        if item_type in cls._list_item_renderers:
+            return cls._list_item_renderers[item_type]
+
+        # Check for subclass matches
+        for registered_type, renderer in cls._list_item_renderers.items():
+            try:
+                if isinstance(registered_type, type) and issubclass(
+                    item_type, registered_type
+                ):
+                    return renderer
+            except TypeError:
+                continue
+
+        return None

fh_pydantic_form/type_helpers.py

@@ -0,0 +1,266 @@
+# Explicit exports for public API
+__all__ = [
+    "_is_optional_type",
+    "_get_underlying_type_if_optional",
+    "_is_literal_type",
+    "_is_enum_type",
+    "_is_skip_json_schema_field",
+    "normalize_path_segments",
+    "MetricEntry",
+    "MetricsDict",
+    "DecorationScope",
+]
+
+
+import logging
+from enum import Enum
+from types import UnionType
+from typing import (
+    Annotated,
+    Any,
+    Dict,
+    List,
+    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 normalize_path_segments(path_segments: List[str]) -> str:
+    """Collapse path segments into a dot path ignoring list indices and placeholders."""
+    normalized: List[str] = []
+    for segment in path_segments:
+        # Coerce to string to avoid surprises from enums or numbers
+        seg_str = str(segment)
+        if seg_str.isdigit() or seg_str.startswith("new_"):
+            continue
+        normalized.append(seg_str)
+    return ".".join(normalized)
+
+
+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.
+
+    This handles the pattern where SkipJsonSchema is used with typing.Annotated:
+    - Annotated[str, SkipJsonSchema()]
+    - SkipJsonSchema[str] (which internally uses Annotated)
+    - Field metadata containing SkipJsonSchema (Pydantic 2 behavior)
+
+    Args:
+        annotation_or_field_info: The field annotation or field_info to check
+
+    Returns:
+        True if the field should be skipped in JSON schema
+    """
+    try:
+        from pydantic.json_schema import SkipJsonSchema
+
+        skip_json_schema_cls = SkipJsonSchema
+    except ImportError:  # very old Pydantic
+        skip_json_schema_cls = None
+
+    if skip_json_schema_cls is None:
+        return False
+
+    # Check if it's a field_info object with metadata
+    if hasattr(annotation_or_field_info, "metadata"):
+        metadata = getattr(annotation_or_field_info, "metadata", [])
+        if metadata:
+            for item in metadata:
+                if (
+                    item is skip_json_schema_cls
+                    or isinstance(item, skip_json_schema_cls)
+                    or (
+                        hasattr(item, "__class__")
+                        and item.__class__.__name__ == "SkipJsonSchema"
+                    )
+                ):
+                    return True
+
+    # Fall back to checking annotation (for backward compatibility)
+    annotation = annotation_or_field_info
+    if hasattr(annotation_or_field_info, "annotation"):
+        annotation = getattr(annotation_or_field_info, "annotation")
+
+    # 1. Direct or generic alias
+    if (
+        annotation is skip_json_schema_cls
+        or getattr(annotation, "__origin__", None) is skip_json_schema_cls
+    ):
+        return True
+
+    # 2. Something like Annotated[T, SkipJsonSchema()]
+    if get_origin(annotation) is Annotated:
+        for meta in get_args(annotation)[1:]:
+            meta_class = getattr(meta, "__class__", None)
+            if (
+                meta is skip_json_schema_cls  # plain class
+                or isinstance(meta, skip_json_schema_cls)  # instance
+                or (meta_class is not None and meta_class.__name__ == "SkipJsonSchema")
+            ):
+                return True
+
+    # 3. Fallback – cheap but effective, but be more specific to avoid false positives
+    # Only match if SkipJsonSchema appears as a standalone word (not part of a class name)
+    repr_str = repr(annotation)
+    # Look for patterns like "SkipJsonSchema[" or "SkipJsonSchema(" or "SkipJsonSchema]"
+    # but not "SomeClassNameSkipJsonSchema"
+    import re
+
+    return bool(re.search(r"\bSkipJsonSchema\b", repr_str))
+
+
+# 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]).
+
+    Args:
+        annotation: The type annotation to check
+
+    Returns:
+        True if the annotation is Optional[T], False otherwise
+    """
+    origin = get_origin(annotation)
+    if origin in (Union, UnionType):
+        args = get_args(annotation)
+        # Check if NoneType is one of the args and there are exactly two args
+        return len(args) == 2 and type(None) in args
+    return False
+
+
+def _get_underlying_type_if_optional(annotation: Any) -> Any:
+    """
+    Extract the type T from Optional[T], otherwise return the original annotation.
+
+    Args:
+        annotation: The type annotation, potentially Optional[T]
+
+    Returns:
+        The underlying type if Optional, otherwise the original annotation
+    """
+    if _is_optional_type(annotation):
+        args = get_args(annotation)
+        # Return the non-None type
+        return args[0] if args[1] is type(None) else args[1]
+    return annotation
+
+
+def _is_literal_type(annotation: Any) -> bool:
+    """Check if the underlying type of an annotation is Literal."""
+    underlying_type = _get_underlying_type_if_optional(annotation)
+    return get_origin(underlying_type) is Literal
+
+
+def _is_enum_type(annotation: Any) -> bool:
+    """Check if the underlying type of an annotation is Enum."""
+    underlying_type = _get_underlying_type_if_optional(annotation)
+    return isinstance(underlying_type, type) and issubclass(underlying_type, Enum)
+
+
+def get_default(field_info: Any) -> Any:
+    """
+    Extract the default value from a Pydantic field definition.
+
+    Handles both literal defaults and default_factory functions.
+
+    Args:
+        field_info: The Pydantic FieldInfo object
+
+    Returns:
+        The default value if available, or _UNSET sentinel if no default exists
+    """
+    # Check for literal default value (including None, but not Undefined)
+    if hasattr(field_info, "default") and not _is_pydantic_undefined(
+        field_info.default
+    ):
+        return field_info.default
+
+    # Check for default_factory
+    default_factory = getattr(field_info, "default_factory", None)
+    if default_factory is not None and callable(default_factory):
+        try:
+            return default_factory()
+        except Exception as exc:
+            logger.warning(f"default_factory failed for field: {exc}")
+            # Don't raise - return sentinel to indicate no usable default
+
+    return _UNSET
+
+
+def _is_pydantic_undefined(value: Any) -> bool:
+    """
+    Check if a value is Pydantic's Undefined sentinel.
+
+    Args:
+        value: The value to check
+
+    Returns:
+        True if the value represents Pydantic's undefined default
+    """
+    # Check if value is None first (common case)
+    if value is None:
+        return False
+
+    # Check for various Pydantic undefined markers
+    if hasattr(value, "__class__"):
+        class_name = value.__class__.__name__
+        if class_name in ("Undefined", "PydanticUndefined"):
+            return True
+
+    # Check string representation as fallback
+    str_repr = str(value)
+    if str_repr in ("PydanticUndefined", "<class 'pydantic_core.PydanticUndefined'>"):
+        return True
+
+    # Check for pydantic.fields.Undefined (older versions)
+    try:
+        from pydantic import fields
+
+        if hasattr(fields, "Undefined") and value is fields.Undefined:
+            return True
+    except ImportError:
+        pass
+
+    # Check for pydantic_core.PydanticUndefined (newer versions)
+    try:
+        import pydantic_core
+
+        if (
+            hasattr(pydantic_core, "PydanticUndefined")
+            and value is pydantic_core.PydanticUndefined
+        ):
+            return True
+    except ImportError:
+        pass
+
+    return False

fh_pydantic_form/ui_style.py

@@ -0,0 +1,115 @@
+from enum import Enum, auto
+from typing import Dict, Literal, Union
+
+
+class SpacingTheme(Enum):
+    NORMAL = auto()
+    COMPACT = auto()
+
+
+# Type alias for spacing values - supports both literal strings and enum values
+SpacingValue = Union[Literal["normal", "compact"], SpacingTheme]
+
+
+def _normalize_spacing(spacing_value: SpacingValue) -> SpacingTheme:
+    """Convert literal string or enum spacing value to SpacingTheme enum."""
+    if isinstance(spacing_value, str):
+        if spacing_value == "compact":
+            return SpacingTheme.COMPACT
+        elif spacing_value == "normal":
+            return SpacingTheme.NORMAL
+        else:
+            # This case shouldn't happen with proper Literal typing, but included for runtime safety
+            raise ValueError(
+                f"Invalid spacing value: {spacing_value}. Must be 'compact', 'normal', or SpacingTheme enum"
+            )
+    elif isinstance(spacing_value, SpacingTheme):
+        return spacing_value
+    else:
+        raise TypeError(
+            f"spacing must be Literal['normal', 'compact'] or SpacingTheme, got {type(spacing_value)}"
+        )
+
+
+SPACING_MAP: Dict[SpacingTheme, Dict[str, str]] = {
+    SpacingTheme.NORMAL: {
+        "outer_margin": "mb-4",
+        "outer_margin_sm": "mb-2",
+        "inner_gap": "space-y-3",
+        "inner_gap_small": "space-y-2",
+        "stack_gap": "space-y-3",
+        "padding": "p-4",
+        "padding_sm": "p-3",
+        "padding_card": "px-4 py-3",
+        "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": "",
+        "accordion_item_margin": "uk-margin-small-bottom",
+        "label_gap": "mb-1",
+        "card_body_pad": "px-4 py-3",
+        "accordion_content": "",
+        "input_size": "",
+        "input_padding": "",
+        "input_line_height": "",
+        "input_font_size": "",
+        "horizontal_gap": "gap-3",
+        "label_align": "items-start",
+    },
+    SpacingTheme.COMPACT: {
+        "outer_margin": "mb-0",
+        "outer_margin_sm": "mb-0",
+        "inner_gap": "space-y-1",
+        "inner_gap_small": "space-y-0.5",
+        "stack_gap": "space-y-1",
+        "padding": "p-1",
+        "padding_sm": "p-0.5",
+        "padding_card": "px-2 py-1",
+        "card_border": "",
+        "card_border_thin": "",
+        "section_divider": "",
+        "metric_badge_gap": "ml-1",
+        "accordion_divider": "",
+        "accordion_title_pad": "py-1",
+        "accordion_content_pad": "py-1",
+        "accordion_item_margin": "mb-0",
+        "label_gap": "mb-0",
+        "card_body_pad": "px-2 py-0.5",
+        "accordion_content": "uk-padding-remove-vertical",
+        "input_size": "uk-form-small",
+        "input_padding": "py-0.5 px-1",
+        "input_line_height": "leading-tight",
+        "input_font_size": "text-sm",
+        "horizontal_gap": "gap-2",
+        "label_align": "items-start",
+    },
+}
+
+
+def spacing(token: str, spacing: SpacingValue) -> str:
+    """Return a Tailwind utility class for the given semantic token."""
+    theme = _normalize_spacing(spacing)
+    return SPACING_MAP[theme][token]
+
+
+def spacing_many(tokens: list[str], spacing: SpacingValue) -> str:
+    """
+    Return combined Tailwind utility classes for multiple semantic tokens.
+
+    Args:
+        tokens: List of spacing token names
+        spacing: Spacing theme to use
+
+    Returns:
+        String of space-separated CSS classes
+    """
+    theme = _normalize_spacing(spacing)
+    classes = []
+    for token in tokens:
+        class_value = SPACING_MAP[theme].get(token, "")
+        if class_value:  # Only add non-empty class values
+            classes.append(class_value)
+    return " ".join(classes)