{{- /* SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Commercial */ -}}
{{- /* SPDX-FileCopyrightText: 2025-2026 Christian Galo */ -}}

{{/* Page anatomy: one form field, every control in the closed set (spec
     form-library "The form part owns the container", "Constraint
     attributes derive from the declaration"; spec form-conventions "Every
     control has a label, and its hint and error are described"; design
     D2, D8, D11, D12, D21, D22). Pipeline: forms.FieldView, built by
     forms.Render from the field's declaration. Rendered by the form part,
     never called directly by a page.

     Three defines, so every family shares one control and one label and
     they cannot drift apart. A Rows body's cells call formField through
     FormView.RowField, which is why a row's control is the same control
     a stacked form would render, under a name and a wrapper id carrying
     its row:

       formField        the wrapper a stacked or dense form renders: label,
                        control, and the one line under it.
       formFieldLabel   the <label for>, its "(optional)" marker and its
                        help icon, for a family that places the label
                        itself (the table's first column).
       formFieldControl the control element alone, for a family that places
                        the control itself (the table's last column, the
                        bar's input group).

     Every control carries a <label for>; in a dense row or a bar with no
     room the label is visually hidden, never absent, and an aria-label
     never substitutes for it (finding FA-51). The help icon follows the
     label as its sibling, never inside it: a button inside a <label>
     toggles the labelled control on every click that opens the popover
     (findings FA-37, FA-50). The hint carries an id the control's
     aria-describedby names, and survives an error; the error carries its
     own id, also named, with aria-invalid on the control (findings FA-48,
     FA-49). The error renders here, under its control, in every family:
     a dense row aligns its columns to the top under one label line, so a
     refused column grows alone and the commit stays level (design D16 of
     staged-rule-changes, which retired D22's error block below the row).
     A dense checkbox has no label line of its own, so its wrapper carries
     app-form-unlabeled and sits on the control line.

     The .Attrs blob is every attribute the declaration decides: required,
     maxlength, min, max, pattern, inputmode, autocomplete, the
     described-by wiring, autofocus on the first errored control, and the
     data-* and hx-* escape hatch. It is built in Go (forms.fieldAttrs) so
     the browser's constraints and the server's rules cannot differ and no
     template can write one by hand.

     Parsed into every template set by web.ParseUIPartials. */}}
{{ define "formField" }}
{{- if eq .Control "hidden" -}}
<input type="hidden" name="{{ .Name }}" value="{{ .Value }}" {{ .Attrs }}>
{{- else -}}
<div id="{{ .WrapperID }}" class="{{ if .ColClass }}{{ .ColClass }}{{ if eq .Control "checkbox" }} app-form-unlabeled{{ end }}{{ else }}mb-3{{ end }} app-form-field">
    {{ if eq .Control "checkbox" }}
    {{/* A checkbox declares a boolean whose absence is false; the library
         refuses a required checkbox, because "required" on one would mean
         "must be ticked" and the console has no such field (lesson
         L§21). */}}
    <div class="form-check">
        {{ template "formFieldControl" . }}
        <label class="form-check-label{{ if .LabelHidden }} visually-hidden{{ end }}{{ if .LabelNarrowOnly }} d-lg-none{{ end }}" for="{{ .ControlID }}">{{ .Label }}{{ if .Optional }} <span class="text-muted">(optional)</span>{{ end }}</label>{{ if .Help.Set }} {{ template "helpIcon" .Help }}{{ end }}
    </div>
    {{ else }}
    {{ template "formFieldLabel" . }}
    {{ template "formFieldControl" . }}
    {{ end }}
    {{ if .SlotID }}<div id="{{ .SlotID }}">{{ .SlotHTML }}</div>{{ end }}
    {{/* One visible line under a control, and only one: its hint, or, for
         the rare field whose one-sidedness would surprise a person, its
         notice. A one-sided field's declared reason is not copy and never
         renders (maintainer, 2026-09-03). */}}
    {{ if .Hint }}<div id="{{ .HintID }}" class="form-text">{{ .Hint }}</div>{{ end }}
    {{ if .Notice }}<div id="{{ .NoticeID }}" class="form-text">{{ .Notice }}</div>{{ end }}
    {{ if .Error }}<div id="{{ .ErrorID }}" class="invalid-feedback d-block">{{ .Error }}</div>{{ end }}
</div>
{{- end -}}
{{ end }}

{{ define "formFieldLabel" }}
<label class="form-label{{ if .Small }} form-label-sm{{ end }}{{ if .LabelHidden }} visually-hidden{{ end }}{{ if .LabelNarrowOnly }} d-lg-none{{ end }}" for="{{ .ControlID }}">{{ .Label }}{{ if .Optional }} <span class="text-muted">(optional)</span>{{ end }}</label>{{ if .Help.Set }} {{ template "helpIcon" .Help }}{{ end }}
{{ end }}

{{ define "formFieldControl" }}
{{- if eq .Control "static" -}}
{{/* A static row states a fact where a control would be: no name, nothing
     submitted, never parsed (design D21). It is how a table holds a key an
     operator cannot set on this page at all. */}}
<span class="text-muted small">{{ .Value }}</span>
{{- else if eq .Control "checkbox" -}}
<input class="form-check-input{{ if .Error }} is-invalid{{ end }}" type="checkbox" id="{{ .ControlID }}" name="{{ .Name }}" value="{{ .CheckboxValue }}"{{ if .Checked }} checked{{ end }} {{ .Attrs }}>
{{- else if eq .Control "select" -}}
<select class="form-select{{ if .Small }} form-select-sm{{ end }}{{ if .Error }} is-invalid{{ end }}" id="{{ .ControlID }}" name="{{ .Name }}" {{ .Attrs }}>
    {{ range .Options }}<option value="{{ .Value }}"{{ if .Disabled }} disabled{{ end }}{{ if .Selected }} selected{{ end }}>{{ .Label }}</option>
    {{ end }}
</select>
{{- else if eq .Control "textarea" -}}
<textarea class="form-control{{ if .Small }} form-control-sm{{ end }}{{ if .Error }} is-invalid{{ end }}" id="{{ .ControlID }}" name="{{ .Name }}" rows="{{ .Rows }}"{{ if .Placeholder }} placeholder="{{ .Placeholder }}"{{ end }} {{ .Attrs }}>{{ .Value }}</textarea>
{{- else if eq .Control "radio" -}}
{{ range .Radios }}
<div class="form-check">
    <input class="form-check-input{{ if $.Error }} is-invalid{{ end }}" type="radio" id="{{ .ID }}" name="{{ $.Name }}" value="{{ .Value }}"{{ if .Checked }} checked{{ end }} {{ $.Attrs }}>
    <label class="form-check-label" for="{{ .ID }}">{{ .Label }}</label>
</div>
{{ end }}
{{- else -}}
<input type="{{ .InputType }}" class="form-control{{ if .Small }} form-control-sm{{ end }}{{ if .Error }} is-invalid{{ end }}" id="{{ .ControlID }}" name="{{ .Name }}" value="{{ .Value }}"{{ if .Placeholder }} placeholder="{{ .Placeholder }}"{{ end }} {{ .Attrs }}>
{{- end -}}
{{ end }}