API Reference¶

@lru_cache(maxsize=1)
def default_css() -> str:
    """Return the default AirForm CSS as a string."""
    css_path = Path(__file__).parent / "static" / "airform.css"
    return css_path.read_text()

def default_form_widget(
    *,
    model: type[BaseModel],
    data: dict | None = None,
    errors: list | None = None,
    excludes: set[str] | None = None,
) -> str:
    """Render form fields for a Pydantic model as HTML.

    Reads the full AirField metadata vocabulary: Widget, Label,
    Placeholder, HelpText, Choices, Autofocus, PrimaryKey, Hidden,
    ReadOnly.

    This is the default widget for AirForm.render(). Swap it by
    setting ``widget`` on your AirForm subclass.

    Args:
        model: The Pydantic model class to render.
        data: Dictionary of data to pre-populate fields.
        errors: List of Pydantic validation errors.
        excludes: Field names to skip when rendering.

    Returns:
        HTML string with all form fields.
    """
    error_dict = errors_to_dict(errors)
    field_parts: list[str] = []

    for field_name, field_info in model.model_fields.items():
        if excludes is not None and field_name in excludes:
            continue

        meta = _meta_dict(field_info)
        annotation = field_info.annotation

        # Skip fields hidden in form context
        hidden = _get_meta(meta, Hidden)
        if hidden and hidden.in_context("form"):
            continue
        readonly = _get_meta(meta, ReadOnly)
        if readonly and readonly.in_context("form"):
            continue

        input_type = pydantic_type_to_html_type(field_info)
        label_text = label_for_field(field_name, field_info)
        error = error_dict.get(field_name)
        value = data.get(field_name) if data is not None else None
        has_error = error is not None

        # Build wrapper
        wrapper_cls = "air-field" + (" air-field-error" if has_error else "")
        parts: list[str] = [f'<div class="{wrapper_cls}">']

        # Label (after input for checkboxes)
        label_html = f'  <label for="{escape(field_name)}">{escape(label_text)}</label>'
        if input_type != "checkbox":
            parts.append(label_html)

        # Build input attributes
        input_attrs: dict[str, str] = {"name": field_name, "id": field_name}

        if input_type not in ("textarea", "select"):
            input_attrs["type"] = input_type

        # Required: non-optional required fields
        if field_info.is_required() and not _is_optional(annotation):
            input_attrs["required"] = ""

        if Autofocus in meta:
            input_attrs["autofocus"] = ""

        placeholder = _get_meta(meta, Placeholder)
        if placeholder:
            input_attrs["placeholder"] = placeholder.text

        if has_error:
            input_attrs["aria-invalid"] = "true"
            input_attrs["aria-describedby"] = f"{field_name}-error"

        # Pydantic constraints -> HTML5 validation attributes
        for m in field_info.metadata:
            if isinstance(m, annotated_types.MinLen):
                input_attrs["minlength"] = str(m.min_length)
            elif isinstance(m, annotated_types.MaxLen):
                input_attrs["maxlength"] = str(m.max_length)
            elif hasattr(annotated_types, "Len") and isinstance(m, annotated_types.Len):
                if getattr(m, "min_length", None) is not None:
                    input_attrs.setdefault("minlength", str(m.min_length))
                if getattr(m, "max_length", None) is not None:
                    input_attrs.setdefault("maxlength", str(m.max_length))

        # Fallback to field_info attributes
        if hasattr(field_info, "min_length") and field_info.min_length is not None:
            input_attrs.setdefault("minlength", str(field_info.min_length))
        if hasattr(field_info, "max_length") and field_info.max_length is not None:
            input_attrs.setdefault("maxlength", str(field_info.max_length))

        # Render the input element
        if input_type == "textarea":
            val = escape(str(value)) if value is not None else ""
            parts.append(f"  <textarea{_attr_str(input_attrs)}>{val}</textarea>")

        elif input_type == "select":
            options = _get_options(annotation, meta)
            parts.append(f"  <select{_attr_str(input_attrs)}>")
            parts.append('    <option value="" disabled selected hidden>Select...</option>')
            for opt_val, opt_label in options:
                sel = " selected" if value is not None and str(value) == opt_val else ""
                parts.append(f'    <option value="{escape(opt_val)}"{sel}>{escape(opt_label)}</option>')
            parts.append("  </select>")

        else:
            val_attr = f' value="{escape(str(value))}"' if value is not None else ""
            parts.append(f"  <input{_attr_str(input_attrs)}{val_attr}>")

        if input_type == "checkbox":
            parts.append(label_html)

        # Help text
        help_text = _get_meta(meta, HelpText)
        if help_text:
            parts.append(f'  <div class="air-field-help" id="{escape(field_name)}-help">{escape(help_text.text)}</div>')

        # Error message
        if error:
            parts.append(
                f'  <div class="air-field-message" id="{escape(field_name)}-error" role="alert">'
                f"{escape(get_user_error_message(error))}</div>"
            )

        parts.append("</div>")
        field_parts.append("\n".join(parts))

    return "\n".join(field_parts)

def errors_to_dict(errors: list[dict] | None) -> dict[str, dict]:
    """Converts a pydantic error list to a dictionary for easier reference."""
    if errors is None:
        return {}
    return {error["loc"][0]: error for error in errors}

def get_user_error_message(error: dict) -> str:
    """Convert technical pydantic error to user-friendly message."""
    error_type = error.get("type", "")
    technical_msg = error.get("msg", "")

    messages = {
        "missing": "This field is required.",
        "int_parsing": "Please enter a valid number.",
        "float_parsing": "Please enter a valid number.",
        "bool_parsing": "Please select a valid option.",
        "string_too_short": "This field is required." if error.get("input") == "" else "This value is too short.",
        "string_too_long": "This value is too long.",
        "value_error": "This value is not valid.",
        "type_error": "Please enter the correct type of value.",
        "assertion_error": "This value doesn't meet the requirements.",
        "url_parsing": "Please enter a valid URL.",
        "email": "Please enter a valid email address.",
        "json_invalid": "Please enter valid JSON.",
        "enum": "Please select a valid option.",
        "greater_than": "This value must be greater than the minimum.",
        "greater_than_equal": "This value must be at least the minimum.",
        "less_than": "This value must be less than the maximum.",
        "less_than_equal": "This value must be at most the maximum.",
    }

    return messages.get(error_type, technical_msg or "Please correct this error.")

def label_for_field(field_name: str, field_info: Any) -> str:
    """Return the label for a field from AirField metadata."""
    for m in getattr(field_info, "metadata", []):
        if isinstance(m, Label):
            return m.text
    return field_name

def pydantic_type_to_html_type(field_info: Any) -> str:
    """Return HTML input type from a Pydantic field's type and metadata.

    Checks AirField metadata first (Widget, Choices), then infers
    from the Python type annotation.
    """
    meta = _meta_dict(field_info)

    widget = _get_meta(meta, Widget)
    if widget:
        return widget.kind
    if Choices in meta:
        return "select"

    annotation = field_info.annotation
    if annotation is bool:
        return "checkbox"
    if annotation is int or annotation is float:
        return "number"
    if isinstance(annotation, type) and issubclass(annotation, Enum):
        return "select"
    if get_origin(annotation) is Literal:
        return "select"

    return "text"