{#- chirp-ui: Form field macros
    Extended field macros with BEM styling. These complement (and can replace)
    Chirp's built-in form macros from "chirp/forms".

    Internal: field_wrapper provides label, hint, error display. Standard fields
    use it; checkbox/toggle/radio/range/input_group have custom layouts.
-#}

{% def form(action, method="get", enctype=none, density="", cls="", attrs="", attrs_map=none,
           hx_get=none, hx_post=none, hx_put=none, hx_patch=none, hx_delete=none,
           hx_target=none, hx_swap=none, hx_trigger=none, hx_include=none,
           hx_select=none, hx_select_oob=none, hx_disabled_elt=none, hx_sync=none,
           hx_ext=none, hx_vals=none, hx_reset_on_success=none) %}
{% provide _form_density = density %}
{#- hx_reset_on_success: when true, form resets after successful htmx response (2xx).
   Defaults to true when form has hx-post/put/patch/delete (via params or attrs_map).
   See https://htmx.org/examples/reset-user-input/
   hx_sync: pass explicitly or via attrs_map to prevent double-submit; e.g. "this:replace".
   See https://htmx.org/docs/#synchronization -#}
{% set _has_hx = hx_post or hx_put or hx_patch or hx_delete or (attrs_map or {}).get("hx-post") or (attrs_map or {}).get("hx-put") or (attrs_map or {}).get("hx-patch") or (attrs_map or {}).get("hx-delete") %}
{% set _reset = hx_reset_on_success if hx_reset_on_success is not none else _has_hx %}
{% set _sync_from_attrs = (attrs_map or {}).get("hx-sync") %}
{% set _sync = hx_sync if hx_sync is not none else _sync_from_attrs %}
{% set _select = hx_select if hx_select is not none else ("unset" if _has_hx else none) %}
{% set _disinherit = "hx-select" if _has_hx and hx_select is none else none %}
<form action="{{ action }}" method="{{ method }}"
      {% if enctype %}enctype="{{ enctype }}"{% end %}
      class="chirpui-form{{ " " ~ cls if cls else "" }}"
      {{ attrs | html_attrs }}
      {{ attrs_map | html_attrs }}
      {% if _reset %}hx-on::after-request="if(event.detail.successful) this.reset()"{% end %}
      {{ build_hx_attrs(hx_get=hx_get, hx_post=hx_post, hx_put=hx_put,
          hx_patch=hx_patch, hx_delete=hx_delete, hx_target=hx_target,
          hx_swap=hx_swap, hx_trigger=hx_trigger, hx_include=hx_include,
          hx_select=_select, hx_disinherit=_disinherit,
          hx_select_oob=hx_select_oob, hx_disabled_elt=hx_disabled_elt,
          hx_sync=_sync, hx_ext=hx_ext, hx_vals=hx_vals) | html_attrs }}>
    {% slot %}
</form>
{% end %}
{% end %}

{% def fieldset(legend=none, cls="") %}
<fieldset class="chirpui-fieldset{{ " " ~ cls if cls else "" }}">
    {% if legend %}<legend class="chirpui-fieldset__legend">{{ legend }}</legend>{% end %}
    {% slot %}
</fieldset>
{% end %}

{# Shared wrapper: label, slot (control), hint, errors. modifier adds chirpui-field--X.
   field_id: override wrapper id (default: "field-{name}"). oob: emit hx-swap-oob="true". #}
{% def field_wrapper(name, label=none, errors=none, required=false, hint=none, modifier="", field_id=none, oob=false) %}
{% set _fid = field_id if field_id else "field-" ~ name %}
{% set _eid = "errors-" ~ name %}
{% set _has_errors = errors and errors | field_errors(name) %}
{% set _density = consume("_form_density", "") %}
<div id="{{ _fid }}" class="chirpui-field{{ " chirpui-field--" ~ modifier if modifier else "" }}{{ " chirpui-field--dense" if _density else "" }}{{ " chirpui-field--error" if _has_errors else "" }}"{% if oob %} hx-swap-oob="true"{% end %}>
    {% if label %}
        <label class="chirpui-field__label" for="{{ name }}">
            {{ label }}{% if required %} <span class="chirpui-field__required" aria-hidden="true">*</span>{% end %}
        </label>
    {% end %}
    {% slot %}
    {% if hint and not _has_errors %}
        <span class="chirpui-field__hint">{{ hint }}</span>
    {% end %}
    <div id="{{ _eid }}" class="chirpui-field__errors" role="alert" aria-live="polite">
        {% if _has_errors %}
            {% for msg in errors | field_errors(name) %}
                <span class="chirpui-field__error">{{ msg }}</span>
            {% end %}
        {% end %}
    </div>
</div>
{% end %}

    Usage:
        from "chirpui/forms.html" import text_field, textarea_field, select_field

        text_field("title", value=form.title, label="Title",
                   errors=errors, required=true)
        textarea_field("description", value=form.description,
                       label="Description", rows=6)
        select_field("status", options=statuses, selected=form.status,
                     label="Status")
        checkbox_field("active", checked=form.active, label="Active")
        toggle_field("notifications", checked=true, label="Enable notifications")
        radio_field("plan", options=plans, selected=form.plan, label="Plan")
        file_field("avatar", label="Avatar", accept="image/*")
        date_field("birthday", value=form.birthday, label="Birthday")
        range_field("volume", value=50, min=0, max=100, label="Volume", show_value=true)
        hidden_field("id", value=form.id)
        phone_field("phone", value=form.phone, label="Phone")
        money_field("amount", value=form.amount, label="Amount")
        masked_field("ssn", mask="999-99-9999", label="SSN")
        masked_field("expiry", mask="99/99", label="Card expiry")

    Note: The field_errors filter is provided by Chirp. When using chirp-ui
    without Chirp, define your own field_errors filter or pass errors=none.
-#}

{# Text input with label and error display #}
{% def text_field(name, value="", label=none, errors=none, type="text",
                  required=false, placeholder="", hint=none, attrs="") %}
{% call field_wrapper(name, label, errors, required, hint) %}
<input class="chirpui-field__input"
       type="{{ type }}" id="{{ name }}" name="{{ name }}"
       value="{{ value }}"
       {% if required %}required{% end %}
       {% if placeholder %}placeholder="{{ placeholder }}"{% end %}
       {% if errors and errors | field_errors(name) %}aria-invalid="true"{% end %}
       aria-describedby="errors-{{ name }}"
       {{ attrs | safe }}>
{% end %}
{% end %}

{# Password field with secure browser autocomplete defaults #}
{% def password_field(name="password", value="", label=none, errors=none, required=true,
                     placeholder="", hint=none, autocomplete="current-password", attrs="") %}
{% call field_wrapper(name, label, errors, required, hint) %}
<input class="chirpui-field__input"
       type="password" id="{{ name }}" name="{{ name }}"
       value="{{ value }}"
       {% if required %}required{% end %}
       {% if placeholder %}placeholder="{{ placeholder }}"{% end %}
       {% if autocomplete %}autocomplete="{{ autocomplete }}"{% end %}
       {% if errors and errors | field_errors(name) %}aria-invalid="true"{% end %}
       aria-describedby="errors-{{ name }}"
       {{ attrs | safe }}>
{% end %}
{% end %}

{# Textarea with label and error display #}
{% def textarea_field(name, value="", label=none, errors=none,
                      rows=4, required=false, placeholder="", hint=none) %}
{% call field_wrapper(name, label, errors, required, hint) %}
<textarea class="chirpui-field__input"
          id="{{ name }}" name="{{ name }}" rows="{{ rows }}"
          {% if required %}required{% end %}
          {% if placeholder %}placeholder="{{ placeholder }}"{% end %}
          {% if errors and errors | field_errors(name) %}aria-invalid="true"{% end %}
          aria-describedby="errors-{{ name }}">{{ value }}</textarea>
{% end %}
{% end %}

{# Select dropdown with label and error display #}
{% def select_field(name, options, selected="", label=none, errors=none,
                    required=false, hint=none) %}
{% call field_wrapper(name, label, errors, required, hint) %}
<select class="chirpui-field__input"
        id="{{ name }}" name="{{ name }}"
        {% if required %}required{% end %}
        {% if errors and errors | field_errors(name) %}aria-invalid="true"{% end %}
        aria-describedby="errors-{{ name }}">
    {% for opt in options %}
        <option value="{{ opt.value }}"
                {% if opt.value == selected %}selected{% end %}>
            {{ opt.label }}
        </option>
    {% end %}
</select>
{% end %}
{% end %}

{# Checkbox with label #}
{% def checkbox_field(name, checked=false, label=none, errors=none) %}
{% set _has_errors = errors and errors | field_errors(name) %}
<div id="field-{{ name }}" class="chirpui-field chirpui-field--checkbox{{ " chirpui-field--error" if _has_errors else "" }}">
    <label class="chirpui-field__label chirpui-field__label--inline">
        <input class="chirpui-field__checkbox"
               type="checkbox" id="{{ name }}" name="{{ name }}"
               {% if checked %}checked{% end %}
               aria-describedby="errors-{{ name }}">
        {{ label if label else name }}
    </label>
    <div id="errors-{{ name }}" class="chirpui-field__errors" role="alert" aria-live="polite">
        {% if _has_errors %}
            {% for msg in errors | field_errors(name) %}
                <span class="chirpui-field__error">{{ msg }}</span>
            {% end %}
        {% end %}
    </div>
</div>
{% end %}

{# Toggle (switch-style checkbox) #}
{# Supports size (sm/md/lg), color variant (success/danger/accent), and label_inside for ON/OFF text #}
{% def toggle_field(name, checked=false, label=none, errors=none, size="", variant="", label_inside=false) %}
{% set size_class = " chirpui-toggle-wrap--" ~ size if size in ("sm", "lg") else "" %}
{% set variant_class = " chirpui-toggle-wrap--" ~ variant if variant in ("success", "danger", "accent") else "" %}
{% set _has_errors = errors and errors | field_errors(name) %}
<div id="field-{{ name }}" class="chirpui-field chirpui-field--toggle{{ " chirpui-field--error" if _has_errors else "" }}">
    <label class="chirpui-field__label chirpui-field__label--inline chirpui-toggle-wrap{{ size_class }}{{ variant_class }}">
        <input class="chirpui-toggle chirpui-visually-hidden"
               type="checkbox" id="{{ name }}" name="{{ name }}"
               {% if checked %}checked{% end %}
               {% if _has_errors %}aria-invalid="true"{% end %}
               aria-describedby="errors-{{ name }}">
        <span class="chirpui-toggle__track" aria-hidden="true">
            {% if label_inside %}
            <span class="chirpui-toggle__track-label chirpui-toggle__track-label--on">ON</span>
            <span class="chirpui-toggle__track-label chirpui-toggle__track-label--off">OFF</span>
            {% end %}
        </span>
        <span class="chirpui-toggle__label">{{ label if label else name }}</span>
    </label>
    <div id="errors-{{ name }}" class="chirpui-field__errors" role="alert" aria-live="polite">
        {% if _has_errors %}
            {% for msg in errors | field_errors(name) %}
                <span class="chirpui-field__error">{{ msg }}</span>
            {% end %}
        {% end %}
    </div>
</div>
{% end %}

{# Radio group with label and error display #}
{% def radio_field(name, options, selected="", label=none, errors=none,
                   required=false, hint=none, layout="vertical") %}
{% set _has_errors = errors and errors | field_errors(name) %}
<fieldset id="field-{{ name }}" class="chirpui-field chirpui-field--radio chirpui-field--radio-{{ layout }}{{ " chirpui-field--error" if _has_errors else "" }}"
          aria-describedby="errors-{{ name }}">
    {% if label %}
        <legend class="chirpui-field__label">
            {{ label }}{% if required %} <span class="chirpui-field__required" aria-hidden="true">*</span>{% end %}
        </legend>
    {% end %}
    <div class="chirpui-field__radio-group">
        {% for opt in options %}
        <label class="chirpui-field__radio-option">
            <input class="chirpui-field__input"
                   type="radio" name="{{ name }}" value="{{ opt.value }}"
                   {% if opt.value == selected %}checked{% end %}
                   {% if required %}required{% end %}
                   {% if _has_errors %}aria-invalid="true"{% end %}>
            <span class="chirpui-field__radio-label">{{ opt.label }}</span>
        </label>
        {% end %}
    </div>
    {% if hint and not _has_errors %}
        <span class="chirpui-field__hint">{{ hint }}</span>
    {% end %}
    <div id="errors-{{ name }}" class="chirpui-field__errors" role="alert" aria-live="polite">
        {% if _has_errors %}
            {% for msg in errors | field_errors(name) %}
                <span class="chirpui-field__error">{{ msg }}</span>
            {% end %}
        {% end %}
    </div>
</fieldset>
{% end %}

{# Star rating — interactive CSS-only 1-N star picker.
   Renders radio inputs in reverse DOM order with row-reverse flex so the
   CSS ~ sibling selector fills stars up to the hovered/checked one. #}
{% def star_rating(name, count=5, selected=0, label=none, errors=none,
                   required=false, hint=none, size="") %}
{% set size = size | validate_size("star-rating", "") %}
{% set _has_errors = errors and errors | field_errors(name) %}
<div id="field-{{ name }}" class="chirpui-field{{ " chirpui-field--error" if _has_errors else "" }}">
    {% if label %}
        <label class="chirpui-field__label">
            {{ label }}{% if required %} <span class="chirpui-field__required" aria-hidden="true">*</span>{% end %}
        </label>
    {% end %}
    <fieldset class="chirpui-star-rating{{ " chirpui-star-rating--" ~ size if size else "" }}"
              aria-label="{{ label or name }}" aria-describedby="errors-{{ name }}">
        {% for i in range(count, 0, -1) %}
        <input class="chirpui-star-rating__input"
               type="radio" name="{{ name }}" value="{{ i }}"
               id="{{ name }}-{{ i }}"
               {% if i == selected %}checked{% end %}
               {% if required %}required{% end %}
               {% if _has_errors %}aria-invalid="true"{% end %}>
        <label class="chirpui-star-rating__label" for="{{ name }}-{{ i }}"
               title="{{ i }} star{{ "s" if i != 1 else "" }}">&#9733;</label>
        {% end %}
    </fieldset>
    {% if hint and not _has_errors %}
        <span class="chirpui-field__hint">{{ hint }}</span>
    {% end %}
    <div id="errors-{{ name }}" class="chirpui-field__errors" role="alert" aria-live="polite">
        {% if _has_errors %}
            {% for msg in errors | field_errors(name) %}
                <span class="chirpui-field__error">{{ msg }}</span>
            {% end %}
        {% end %}
    </div>
</div>
{% end %}

{# Thumbs up/down — binary sentiment input (radio pair). #}
{% def thumbs(name, selected="", label=none, errors=none,
              required=false, hint=none, size="") %}
{% set size = size | validate_size("thumbs", "") %}
{% set _has_errors = errors and errors | field_errors(name) %}
<div id="field-{{ name }}" class="chirpui-field{{ " chirpui-field--error" if _has_errors else "" }}">
    {% if label %}
        <label class="chirpui-field__label">
            {{ label }}{% if required %} <span class="chirpui-field__required" aria-hidden="true">*</span>{% end %}
        </label>
    {% end %}
    <fieldset class="chirpui-thumbs{{ " chirpui-thumbs--" ~ size if size else "" }}"
              aria-label="{{ label or name }}" aria-describedby="errors-{{ name }}">
        <input class="chirpui-thumbs__input" type="radio" name="{{ name }}" value="up"
               id="{{ name }}-up"
               {% if selected == "up" %}checked{% end %}
               {% if required %}required{% end %}
               {% if _has_errors %}aria-invalid="true"{% end %}>
        <label class="chirpui-thumbs__label chirpui-thumbs__label--up" for="{{ name }}-up"
               title="Yes">&#x1F44D;</label>
        <input class="chirpui-thumbs__input" type="radio" name="{{ name }}" value="down"
               id="{{ name }}-down"
               {% if selected == "down" %}checked{% end %}
               {% if required %}required{% end %}
               {% if _has_errors %}aria-invalid="true"{% end %}>
        <label class="chirpui-thumbs__label chirpui-thumbs__label--down" for="{{ name }}-down"
               title="No">&#x1F44E;</label>
    </fieldset>
    {% if hint and not _has_errors %}
        <span class="chirpui-field__hint">{{ hint }}</span>
    {% end %}
    <div id="errors-{{ name }}" class="chirpui-field__errors" role="alert" aria-live="polite">
        {% if _has_errors %}
            {% for msg in errors | field_errors(name) %}
                <span class="chirpui-field__error">{{ msg }}</span>
            {% end %}
        {% end %}
    </div>
</div>
{% end %}

{# Segmented control — connected button-group radio selector. #}
{% def segmented_control(name, options, selected="", label=none, errors=none,
                         required=false, hint=none, size="") %}
{% set size = size | validate_size("segmented", "") %}
{% set _has_errors = errors and errors | field_errors(name) %}
<div id="field-{{ name }}" class="chirpui-field{{ " chirpui-field--error" if _has_errors else "" }}">
    {% if label %}
        <label class="chirpui-field__label">
            {{ label }}{% if required %} <span class="chirpui-field__required" aria-hidden="true">*</span>{% end %}
        </label>
    {% end %}
    <div class="chirpui-segmented{{ " chirpui-segmented--" ~ size if size else "" }}"
         role="radiogroup" aria-label="{{ label or name }}" aria-describedby="errors-{{ name }}">
        {% for opt in options %}
        <input class="chirpui-segmented__input" type="radio" name="{{ name }}"
               value="{{ opt.value }}" id="{{ name }}-{{ opt.value }}"
               {% if opt.value == selected %}checked{% end %}
               {% if required %}required{% end %}
               {% if _has_errors %}aria-invalid="true"{% end %}>
        <label class="chirpui-segmented__label" for="{{ name }}-{{ opt.value }}">{{ opt.label }}</label>
        {% end %}
    </div>
    {% if hint and not _has_errors %}
        <span class="chirpui-field__hint">{{ hint }}</span>
    {% end %}
    <div id="errors-{{ name }}" class="chirpui-field__errors" role="alert" aria-live="polite">
        {% if _has_errors %}
            {% for msg in errors | field_errors(name) %}
                <span class="chirpui-field__error">{{ msg }}</span>
            {% end %}
        {% end %}
    </div>
</div>
{% end %}

{# Number scale — horizontal numbered radio row (NPS-style 0-10 or 1-5). #}
{% def number_scale(name, min=0, max=10, selected=none, label=none, errors=none,
                    required=false, hint=none, low_label="", high_label="") %}
{% set _has_errors = errors and errors | field_errors(name) %}
<div id="field-{{ name }}" class="chirpui-field{{ " chirpui-field--error" if _has_errors else "" }}">
    {% if label %}
        <label class="chirpui-field__label">
            {{ label }}{% if required %} <span class="chirpui-field__required" aria-hidden="true">*</span>{% end %}
        </label>
    {% end %}
    <div class="chirpui-number-scale" role="radiogroup" aria-label="{{ label or name }}"
         aria-describedby="errors-{{ name }}">
        {% for i in range(min, max + 1) %}
        <input class="chirpui-number-scale__input" type="radio" name="{{ name }}"
               value="{{ i }}" id="{{ name }}-{{ i }}"
               {% if selected is not none and i == selected %}checked{% end %}
               {% if required %}required{% end %}
               {% if _has_errors %}aria-invalid="true"{% end %}>
        <label class="chirpui-number-scale__label" for="{{ name }}-{{ i }}">{{ i }}</label>
        {% end %}
    </div>
    {% if low_label or high_label %}
    <div class="chirpui-number-scale__labels">
        <span class="chirpui-font-xs chirpui-text-muted">{{ low_label }}</span>
        <span class="chirpui-font-xs chirpui-text-muted">{{ high_label }}</span>
    </div>
    {% end %}
    {% if hint and not _has_errors %}
        <span class="chirpui-field__hint">{{ hint }}</span>
    {% end %}
    <div id="errors-{{ name }}" class="chirpui-field__errors" role="alert" aria-live="polite">
        {% if _has_errors %}
            {% for msg in errors | field_errors(name) %}
                <span class="chirpui-field__error">{{ msg }}</span>
            {% end %}
        {% end %}
    </div>
</div>
{% end %}

{# File input with label and error display #}
{% def file_field(name, label=none, errors=none, accept="", multiple=false,
                  required=false, hint=none) %}
{% call field_wrapper(name, label, errors, required, hint, modifier="file") %}
<input class="chirpui-field__file"
       type="file" id="{{ name }}" name="{{ name }}"
       {% if accept %}accept="{{ accept }}"{% end %}
       {% if multiple %}multiple{% end %}
       {% if required %}required{% end %}
       {% if errors and errors | field_errors(name) %}aria-invalid="true"{% end %}
       aria-describedby="errors-{{ name }}">
{% end %}
{% end %}

{# Date input with label and error display #}
{% def date_field(name, value="", label=none, errors=none, required=false,
                  min=none, max=none, hint=none) %}
{% call field_wrapper(name, label, errors, required, hint) %}
<input class="chirpui-field__input"
       type="date" id="{{ name }}" name="{{ name }}" value="{{ value }}"
       {% if required %}required{% end %}
       {% if min %}min="{{ min }}"{% end %}
       {% if max %}max="{{ max }}"{% end %}
       {% if errors and errors | field_errors(name) %}aria-invalid="true"{% end %}
       aria-describedby="errors-{{ name }}">
{% end %}
{% end %}

{# Range slider with label and error display #}
{% def range_field(name, value=50, min=0, max=100, step=1, label=none,
                   errors=none, hint=none, show_value=false) %}
{% set _has_errors = errors and errors | field_errors(name) %}
<div id="field-{{ name }}" class="chirpui-field chirpui-field--range{{ " chirpui-field--error" if _has_errors else "" }}">
    {% if label or show_value %}
    <div class="chirpui-field__range-header">
        {% if label %}
            <label class="chirpui-field__label" for="{{ name }}">{{ label }}</label>
        {% end %}
        {% if show_value %}
            <output class="chirpui-field__range-value" for="{{ name }}">{{ value }}</output>
        {% end %}
    </div>
    {% end %}
    <input class="chirpui-field__range"
           type="range" id="{{ name }}" name="{{ name }}"
           value="{{ value }}" min="{{ min }}" max="{{ max }}" step="{{ step }}"
           {% if _has_errors %}aria-invalid="true"{% end %}
           aria-describedby="errors-{{ name }}">
    {% if hint and not _has_errors %}
        <span class="chirpui-field__hint">{{ hint }}</span>
    {% end %}
    <div id="errors-{{ name }}" class="chirpui-field__errors" role="alert" aria-live="polite">
        {% if _has_errors %}
            {% for msg in errors | field_errors(name) %}
                <span class="chirpui-field__error">{{ msg }}</span>
            {% end %}
        {% end %}
    </div>
</div>
{% end %}

{# Input with prefix/suffix. Use prefix/suffix params for text, or slot prefix/suffix for custom content (icons, etc). #}
{% def input_group(name, prefix=none, suffix=none, value="", label=none,
                   errors=none, type="text", required=false, placeholder="",
                   hint=none, attrs="") %}
{% set _has_errors = errors and errors | field_errors(name) %}
<div id="field-{{ name }}" class="chirpui-field chirpui-field--input-group{{ " chirpui-field--error" if _has_errors else "" }}">
    {% if label %}
        <label class="chirpui-field__label" for="{{ name }}">
            {{ label }}{% if required %} <span class="chirpui-field__required" aria-hidden="true">*</span>{% end %}
        </label>
    {% end %}
    <div class="chirpui-input-group">
        {% if prefix %}
        <span class="chirpui-input-group__prefix">{{ prefix }}</span>
        {% else %}
        <span class="chirpui-input-group__prefix">{% slot prefix %}</span>
        {% end %}
        <input class="chirpui-input-group__input"
               type="{{ type }}" id="{{ name }}" name="{{ name }}"
               value="{{ value }}"
               {% if required %}required{% end %}
               {% if placeholder %}placeholder="{{ placeholder }}"{% end %}
               {% if _has_errors %}aria-invalid="true"{% end %}
               aria-describedby="errors-{{ name }}"
               {{ attrs | safe }}>
        {% if suffix %}
        <span class="chirpui-input-group__suffix">{{ suffix }}</span>
        {% else %}
        <span class="chirpui-input-group__suffix">{% slot suffix %}</span>
        {% end %}
    </div>
    {% if hint and not _has_errors %}
        <span class="chirpui-field__hint">{{ hint }}</span>
    {% end %}
    <div id="errors-{{ name }}" class="chirpui-field__errors" role="alert" aria-live="polite">
        {% if _has_errors %}
            {% for msg in errors | field_errors(name) %}
                <span class="chirpui-field__error">{{ msg }}</span>
            {% end %}
        {% end %}
    </div>
</div>
{% end %}

{# Masked text input — uses Alpine Mask plugin. Pass mask (static) or mask_dynamic (expression).
   Requires @alpinejs/mask loaded before Alpine core. See https://alpinejs.dev/plugins/mask
   mask: static pattern, e.g. "99/99/9999", "999-99-9999"
   mask_dynamic: Alpine expression with $input, e.g. "$money($input)" or credit card logic #}
{% def masked_field(name, value="", label=none, errors=none, mask=none, mask_dynamic=none,
                   required=false, placeholder="", hint=none, attrs="") %}
{% call field_wrapper(name, label, errors, required, hint, modifier="masked") %}
<input class="chirpui-field__input"
       type="text" id="{{ name }}" name="{{ name }}"
       value="{{ value }}"
       {% if mask %}x-mask="{{ mask }}"{% end %}
       {% if mask_dynamic %}x-mask:dynamic="{{ mask_dynamic }}"{% end %}
       {% if required %}required{% end %}
       {% if placeholder %}placeholder="{{ placeholder }}"{% end %}
       {% if errors and errors | field_errors(name) %}aria-invalid="true"{% end %}
       aria-describedby="errors-{{ name }}"
       {{ attrs | safe }}>
{% end %}
{% end %}

{# Phone field — US format (999) 999-9999 by default. Use masked_field for other formats. #}
{% def phone_field(name, value="", label=none, errors=none, format="us",
                   required=false, placeholder="", hint=none, attrs="") %}
{% set _mask = "(999) 999-9999" if format == "us" else "9999 999 9999" if format == "uk" else "+9 999 999 9999" if format == "intl" else "(999) 999-9999" %}
{% call field_wrapper(name, label, errors, required, hint, modifier="phone") %}
<input class="chirpui-field__input"
       type="tel" id="{{ name }}" name="{{ name }}"
       value="{{ value }}"
       x-mask="{{ _mask }}"
       {% if required %}required{% end %}
       {% if placeholder %}placeholder="{{ placeholder }}"{% end %}
       {% if errors and errors | field_errors(name) %}aria-invalid="true"{% end %}
       aria-describedby="errors-{{ name }}"
       {{ attrs | safe }}>
{% end %}
{% end %}

{# Money/currency field — uses Alpine $money(). decimal_sep, thousands_sep, precision optional.
   $money($input, decimal, thousands, precision) — default ".", ",", 2 #}
{% def money_field(name, value="", label=none, errors=none,
                  decimal_sep=".", thousands_sep=",", precision=2,
                  required=false, placeholder="", hint=none, attrs="") %}
{% set _money_expr = "$money($input, '" ~ decimal_sep ~ "', '" ~ thousands_sep ~ "', " ~ precision ~ ")" %}
{% call field_wrapper(name, label, errors, required, hint, modifier="money") %}
<input class="chirpui-field__input"
       type="text" inputmode="decimal" id="{{ name }}" name="{{ name }}"
       value="{{ value }}"
       x-mask:dynamic="{{ _money_expr }}"
       {% if required %}required{% end %}
       {% if placeholder %}placeholder="{{ placeholder }}"{% end %}
       {% if errors and errors | field_errors(name) %}aria-invalid="true"{% end %}
       aria-describedby="errors-{{ name }}"
       {{ attrs | safe }}>
{% end %}
{% end %}

{# Multi-select dropdown with label and error display #}
{% def multi_select_field(name, options, selected=none, label=none, errors=none,
                          required=false, hint=none, size=4) %}
{% set selected = selected or [] %}
{% call field_wrapper(name, label, errors, required, hint) %}
<select class="chirpui-field__input chirpui-field__input--multi"
        id="{{ name }}" name="{{ name }}" multiple size="{{ size }}"
        {% if required %}required{% end %}
        {% if errors and errors | field_errors(name) %}aria-invalid="true"{% end %}
        aria-describedby="errors-{{ name }}">
    {% for opt in options %}
        <option value="{{ opt.value }}"
                {% if opt.value in selected %}selected{% end %}>
            {{ opt.label }}
        </option>
    {% end %}
</select>
{% end %}
{% end %}

{# Search input with optional htmx debounced search #}
{% def search_field(name, value="", label=none, search_url=none, search_target=none,
                    search_trigger="keyup changed delay:300ms", search_include=none,
                    search_sync=none, placeholder="Search...", errors=none, attrs="", attrs_map=none,
                    search_attrs_map=none, search_hx_select=none) %}
{% set _has_errors = errors and errors | field_errors(name) %}
<div id="field-{{ name }}" class="chirpui-field{{ " chirpui-field--error" if _has_errors else "" }}">
    {% if label %}
        <label class="chirpui-field__label" for="{{ name }}">{{ label }}</label>
    {% end %}
    <input class="chirpui-field__input"
           type="search" id="{{ name }}" name="{{ name }}"
           value="{{ value }}"
           placeholder="{{ placeholder }}"
           {% if _has_errors %}aria-invalid="true"{% end %}
           aria-describedby="errors-{{ name }}"
           {{ attrs | html_attrs }}
           {{ attrs_map | html_attrs }}
           {{ search_attrs_map | html_attrs }}
           {% if search_url and search_target %}hx-get="{{ search_url }}"{% end %}
           {% if search_url and search_target %}hx-trigger="{{ search_trigger }}"{% end %}
           {% if search_url and search_target %}hx-target="{{ search_target }}"{% end %}
           {% if search_url and search_target %}hx-swap="innerHTML"{% end %}
           {% if search_url and search_target and search_hx_select %}hx-select="{{ search_hx_select }}"{% end %}
           {% if search_url and search_target and search_include %}hx-include="{{ search_include }}"{% end %}
           {% set _search_sync = search_sync if search_sync is not none else ("this:replace" if (search_url and search_target) else none) %}
           {% if _search_sync %}hx-sync="{{ _search_sync }}"{% end %}>
    <div id="errors-{{ name }}" class="chirpui-field__errors" role="alert" aria-live="polite">
        {% if _has_errors %}
            {% for msg in errors | field_errors(name) %}
                <span class="chirpui-field__error">{{ msg }}</span>
            {% end %}
        {% end %}
    </div>
</div>
{% end %}

{# Search bar — composite search input with layout variants. Use inside a form.
   variant: "solo" (input only, for live search), "with-button" (input + compact submit),
   "with-icon" (input with ⌕ prefix). With with-button, input flexes; button stays compact. #}
{% def search_bar(name, value="", variant="solo", label=none, search_url=none, search_target=none,
                  search_trigger="keyup changed delay:300ms", search_include=none, search_sync=none,
                  placeholder="Search...", button_label="Search", button_icon="⌕",
                  errors=none, attrs="", attrs_map=none, search_attrs_map=none, search_hx_select=none) %}
{% set _has_errors = errors and errors | field_errors(name) %}
<div id="field-{{ name }}" class="chirpui-field chirpui-search-bar chirpui-search-bar--{{ variant }}{{ " chirpui-field--error" if _has_errors else "" }}">
    {% if label %}
        <label class="chirpui-field__label" for="{{ name }}">{{ label }}</label>
    {% end %}
    <div class="chirpui-search-bar__inner">
        {% if variant == "with-icon" %}
        <span class="chirpui-search-bar__icon" aria-hidden="true">{{ button_icon }}</span>
        {% end %}
        <input class="chirpui-search-bar__input"
               type="search" id="{{ name }}" name="{{ name }}"
               value="{{ value }}"
               placeholder="{{ placeholder }}"
               {% if _has_errors %}aria-invalid="true"{% end %}
               aria-describedby="errors-{{ name }}"
               {{ attrs | html_attrs }}
               {{ attrs_map | html_attrs }}
               {{ search_attrs_map | html_attrs }}
               {% if search_url and search_target %}hx-get="{{ search_url }}"{% end %}
               {% if search_url and search_target %}hx-trigger="{{ search_trigger }}"{% end %}
               {% if search_url and search_target %}hx-target="{{ search_target }}"{% end %}
               {% if search_url and search_target %}hx-swap="innerHTML"{% end %}
               {% if search_url and search_target and search_hx_select %}hx-select="{{ search_hx_select }}"{% end %}
               {% if search_url and search_target and search_include %}hx-include="{{ search_include }}"{% end %}
               {% set _search_sync = search_sync if search_sync is not none else ("this:replace" if (search_url and search_target) else none) %}
               {% if _search_sync %}hx-sync="{{ _search_sync }}"{% end %}>
        {% if variant == "with-button" %}
        <button type="submit" class="chirpui-btn chirpui-btn--primary chirpui-btn--sm chirpui-search-bar__btn">
            <span class="chirpui-btn__icon">{{ button_icon }}</span>
            <span class="chirpui-btn__label">{{ button_label }}</span>
        </button>
        {% end %}
    </div>
    <div id="errors-{{ name }}" class="chirpui-field__errors" role="alert" aria-live="polite">
        {% if _has_errors %}
            {% for msg in errors | field_errors(name) %}
                <span class="chirpui-field__error">{{ msg }}</span>
            {% end %}
        {% end %}
    </div>
</div>
{% end %}

{# Key-value form — inline key + value inputs + submit. For "Set config value" etc. -#}
{% def key_value_form(action, method="post", key_placeholder="", value_placeholder="",
                      submit_label="Set", key_options=none, key_name="key", value_name="value",
                      attrs="", attrs_map=none, cls="") %}
{% call form(action, method=method, attrs=attrs, attrs_map=attrs_map, cls="chirpui-key-value-form" ~ (" " ~ cls if cls else "")) %}
<div class="chirpui-key-value-form__row">
    <div class="chirpui-field chirpui-key-value-form__key">
        <label class="chirpui-field__label" for="{{ key_name }}">Key</label>
        {% if key_options %}
        <input class="chirpui-field__input" type="text" id="{{ key_name }}" name="{{ key_name }}"
               list="key-value-form-datalist-{{ key_name }}" placeholder="{{ key_placeholder }}">
        <datalist id="key-value-form-datalist-{{ key_name }}">
            {% for opt in key_options %}
            <option value="{{ opt['value'] if opt is mapping else opt }}">{{ opt['label'] if opt is mapping else opt }}</option>
            {% end %}
        </datalist>
        {% else %}
        <input class="chirpui-field__input" type="text" id="{{ key_name }}" name="{{ key_name }}"
               placeholder="{{ key_placeholder }}">
        {% end %}
    </div>
    <div class="chirpui-field chirpui-key-value-form__value">
        <label class="chirpui-field__label" for="{{ value_name }}">Value</label>
        <input class="chirpui-field__input" type="text" id="{{ value_name }}" name="{{ value_name }}"
               placeholder="{{ value_placeholder }}">
    </div>
    <div class="chirpui-key-value-form__submit">
        {% from "chirpui/button.html" import btn %}
        {{ btn(submit_label, type="submit", variant="primary") }}
    </div>
</div>
{% end %}
{% end %}

{# Hidden field #}
{% def hidden_field(name, value="") %}
<input type="hidden" name="{{ name }}" value="{{ value }}">
{% end %}

{# CSRF hidden field helper. Pass token for non-Chirp environments. #}
{% def csrf_hidden(token=none, field_name="_csrf_token") %}
{% if token is not none %}
<input type="hidden" name="{{ field_name }}" value="{{ token }}">
{% else %}
{{ csrf_token() }}
{% end %}
{% end %}

{# Form error summary — alert-style box listing all field errors with anchor links.
   Place at the top of the form. Renders nothing if no errors. oob: emit hx-swap-oob for OOB targeting. #}
{% def form_error_summary(errors, id="form-errors", oob=false) %}
{% if errors and errors is mapping %}
{% set _fields = [] %}
{% for fname, msgs in errors.items() %}
    {% if msgs %}{% set _ = _fields.append(fname) %}{% end %}
{% end %}
{% if _fields %}
<div id="{{ id }}" class="chirpui-form-error-summary" role="alert" aria-live="assertive"{% if oob %} hx-swap-oob="true"{% end %}>
    <p class="chirpui-form-error-summary__heading">Please fix {{ _fields | length }} error{{ "s" if _fields | length != 1 else "" }} below:</p>
    <ul class="chirpui-form-error-summary__list">
        {% for fname in _fields %}
        <li><a href="#field-{{ fname }}">{{ fname }}</a></li>
        {% end %}
    </ul>
</div>
{% elif not oob %}
<div id="{{ id }}" class="chirpui-form-error-summary" hidden></div>
{% else %}
<div id="{{ id }}" class="chirpui-form-error-summary" hidden hx-swap-oob="true"></div>
{% end %}
{% else %}
{% if oob %}
<div id="{{ id }}" class="chirpui-form-error-summary" hidden hx-swap-oob="true"></div>
{% end %}
{% end %}
{% end %}

{# Form actions — submit/cancel button row. Use align="end" for right-aligned. #}
{% def form_actions(align="start", cls="") %}
{% set align_class = " chirpui-form-actions--end" if align == "end" else "" %}
<div class="chirpui-form-actions{{ align_class }}{{ " " ~ cls if cls else "" }}">
    {% slot %}
</div>
{% end %}