forms

type AutocompleteType string

type CalendarProps struct {
	utils.BaseProps
	// Year and Month define which month to display.
	Year  int
	Month time.Month
	// SelectedDate highlights the matching day.
	SelectedDate *time.Time
	// HrefBase is the URL pattern for day links. Use {year}, {month}, {day} as placeholders.
	// Example: "/calendar?year={year}&month={month}&day={day}"
	HrefBase string
	// HrefPrev/HrefNext are URLs for the prev/next month navigation links.
	HrefPrev string
	HrefNext string
	// MonthNav, when set, wires the prev/next month links for partial-page
	// updates in BOTH transport dialects (htmx hx-get or a Datastar
	// @get binding) instead of full-page navigation. The URL carries the
	// SAME {year}/{month} placeholders as HrefBase — the component clones
	// the action per direction and substitutes the target month, so one
	// action serves both arrows. A nil MonthNav keeps the href-only
	// behavior; a set HrefPrev/HrefNext alongside renders as the no-JS
	// fallback href.
	//
	//	MonthNav: &wire.Action{URL: "/api/calendar?year={year}&month={month}", Target: "#calendar"}
	MonthNav *wire.Action
	// MinDate/MaxDate disable days outside the range.
	MinDate *time.Time
	MaxDate *time.Time
}

type CheckboxProps struct {
	utils.BaseProps
	Name     string
	Value    string
	Label    string
	Checked  bool
	Required bool
	Disabled bool
	Error    string
	HelpText string
}

type ComboboxOption struct {
	Value string
	Label string
}

type ComboboxProps struct {
	utils.BaseProps
	Name        string
	Label       string
	Placeholder string
	Options     []ComboboxOption
	Value       string
	Required    bool
	Disabled    bool
	Error       string
	HelpText    string
}

type DatePickerProps struct {
	utils.BaseProps
	Name     string
	Value    string
	Label    string
	Min      string
	Max      string
	Required bool
	Disabled bool
	Error    string
	HelpText string
}

type DirtyGuardProps struct {
	utils.BaseProps
}

type EnterKeyHintType string

type FileInputProps struct {
	utils.BaseProps
	Name     string
	Label    string
	Required bool
	Disabled bool
	Error    string
	HelpText string
	Accept   string // e.g. ".jpg,.png" or "image/*"
	Multiple bool
}

type FilterBarProps struct {
	utils.BaseProps

	// Action is the list-page URL: the form's GET action (the no-JS
	// fallback), the Reset link target, and — when Wire is unset — the
	// auto-submit fetch URL. An empty Action renders an unwired form
	// (inert bar; useful for pure-CSS composition).
	Action string
	// Wire, when set with a non-empty URL, owns the auto-submit wiring in
	// both dialects. Defaults applied by the component: the change event
	// plus form encoding, so every filter field in the form serializes.
	// Target/PushURL render for htmx only; Datastar targeting is
	// response-driven — wrap the handler in wire.Handler.
	Wire *wire.Action
	// Target is the results-region selector the response swaps into
	// (htmx hx-target). Empty leaves htmx's default (the form itself).
	Target string
	// Sticky renders the top-anchored shell (sticky top-0, z-20, border,
	// solid background) — the pattern for bars above long result lists.
	Sticky bool
	// ResetText renders a ghost Reset link to the unfiltered Action URL
	// when non-empty ("Reset" via DefaultFilterBarProps).
	ResetText string
	// NoPushURL opts out of pushing the filtered URL (the zero value
	// pushes, so filtered views are shareable — the list-page convention;
	// htmx dialect only).
	NoPushURL bool
}

type FilterChip struct {
	// Label is the visible chip text.
	Label string
	// Href is the link target carrying the chip's filter state.
	Href string
	// Active marks the currently applied filter. The active chip renders
	// aria-current="true" and the filled style; keeping the link (like the
	// extraction source) is honest about the current state.
	Active bool
}

type FilterChipsProps struct {
	utils.BaseProps

	// Chips renders left to right. Provide an "All" chip (empty-value href)
	// so users can clear the filter without JavaScript.
	Chips []FilterChip
}

type FilterDropdownProps struct {
	utils.BaseProps
	Name    string
	Label   string
	Options []SelectOption
	// Value pre-selects the option whose Value matches. Use this to
	// preserve the user's last filter selection across HTMX re-renders.
	Value string
	// HxGet is the server endpoint to fetch filtered results.
	HxGet string
	// HxTarget is the CSS selector for the element to swap results into.
	HxTarget string
	// HxSwap controls how the response is swapped (default: "innerHTML").
	HxSwap string
	// HxTrigger overrides the default "change" trigger. Use e.g.
	// "change delay:500ms" for debounced filtering.
	HxTrigger string
	// HxInclude is a CSS selector or keyword (e.g. "closest form") to
	// include additional form values in the request.
	HxInclude string
	// HxIndicator is a CSS selector for the element to show while loading.
	HxIndicator string
	// HelpText shows a small caption below the select.
	HelpText string
	// Action is the no-JS fallback the wired form submits to via GET. When
	// Wire is set, the component wraps the select in a GET form with a
	// <noscript> Apply button so browsers without JavaScript still apply the
	// filter (with a full-page load). Ignored when Wire is unset.
	Action string
	// Wire, when set with a non-empty URL, owns the auto-submit wiring in
	// both dialects and the legacy HxGet/HxTarget/HxSwap/HxTrigger fields are
	// ignored (HxInclude/HxIndicator still render — they are htmx-dialect
	// extras outside the wire common subset, ADR-0036). Defaults applied by
	// the component: Event resolves to change and ContentType to form
	// encoding, so the request carries the filter fields as query parameters
	// via the wrapping form. Wire.Target renders for htmx only; Datastar
	// targeting is response-driven — wrap the handler in wire.Handler. An
	// empty Wire.URL wires nothing (plain HTMX select).
	Wire *wire.Action
}

type FilterInputProps struct {
	utils.BaseProps
	// Name is the field name submitted with the request (e.g. "q").
	Name string
	// Label shows a visible caption above the input. When empty, set
	// AriaLabel so screen readers can still announce the field.
	Label string
	// Value pre-fills the input. Use this to preserve the query across
	// server re-renders of the filter bar.
	Value string
	// Placeholder shows hint text inside the empty input.
	Placeholder string
	// HelpText shows a small caption below the input, linked via
	// aria-describedby.
	HelpText string
	// Action is the no-JS fallback the form submits to via GET. When empty,
	// the form has no action attribute (submits to the current URL).
	Action string
	// DebounceMS delays the wired request until typing pauses for this many
	// milliseconds. Default 300 via DefaultFilterInputProps; 0 disables the
	// debounce (a request fires on every keystroke). htmx renders it as the
	// `input changed delay:<n>ms` trigger; Datastar as the
	// `__debounce.<n>ms` event modifier (spelling decoded from the pinned
	// v1.0.3 bundle — see docs/datastar-runtime-facts.md).
	DebounceMS int
	// Wire, when set with a non-empty URL, submits the input via the
	// configured transport instead of a full page load (see the wire
	// package, ADR-0036). Defaults applied by the component: Event resolves
	// to input and ContentType to form encoding, so the request carries
	// `?<Name>=<Value>` as a query parameter. Wire.Target renders for htmx
	// only (hx-target); Datastar targeting is response-driven — wrap the
	// handler in wire.Handler. An empty Wire.URL wires nothing.
	Wire *wire.Action
}

type FormEnctype string

type FormFieldProps struct {
	ID       string
	Label    string
	Required bool
	Error    string
	HelpText string
}

type FormLayout string

type FormMethod string

type FormProps struct {
	utils.BaseProps
	Action string
	Method FormMethod
	// Enctype selects the encoding of a POST body. Zero value (and unknown
	// values) resolve to the HTML default, urlencoded; set
	// FormEnctypeMultipart for file uploads. Under both transports the
	// runtime honors it: htmx serializes natively, the pinned Datastar
	// bundle sends a FormData body exactly when enctype is multipart.
	Enctype       FormEnctype
	CSRFToken     string
	CSRFTokenName string // Hidden input name attribute; defaults to "csrf_token"
	// Layout selects the visual layout: Stack (default), Inline (horizontal
	// flex-wrap), or Grid (aligned label/value columns).
	Layout FormLayout
	// Validate, when true, adds hx-validate="true" for HTML5 constraint
	// validation before HTMX submit.
	Validate bool
	// DirtyGuard opts this form into the unsaved-changes guard: render
	// forms.DirtyGuard once on the page and the browser warns before
	// leaving with unsaved changes in this form (see DirtyGuardProps).
	DirtyGuard bool
	// NoValidate renders the HTML novalidate attribute, disabling the
	// browser's native constraint validation on submit. Symmetric across
	// transports: under htmx it suppresses the built-in reportValidity UI;
	// under Datastar it lifts the pinned bundle's form-encoding validation
	// gate (the runtime only calls checkValidity when the form lacks
	// novalidate), letting server-side validation own the error UX — see
	// docs/recipes/server-side-validation.md. Pair with Validate
	// (hx-validate="true") to keep htmx's pre-submit check while dropping
	// the native tooltips.
	NoValidate bool
	// ContainerAware, when true, wraps the form in a @container div and swaps
	// sm: breakpoint classes for @sm: so the Grid layout responds to the
	// parent container's width, not the viewport. Useful when a form is placed
	// inside a modal, drawer, sidebar, or other constrained layout. Default
	// false (viewport breakpoints). See ADR-0018.
	ContainerAware bool
	// Wire, when set, submits the form via the configured transport instead
	// of a full page load (see the wire package, ADR-0036). The form's fields
	// serialize in both dialects: htmx natively (hx-post + hx-trigger
	// "submit"), Datastar via {contentType: 'form'} on data-on:submit — a
	// runtime capability verified against the pinned v1.0.3 bundle (HTML5
	// validation gates the request, the submitter button's name/value is
	// appended, enctype selects multipart for file uploads, GET carries the
	// fields as query parameters).
	//
	// Field defaults: an unspecified Event resolves to submit, an unspecified
	// ContentType resolves to form encoding (set ContentTypeJSON explicitly to
	// submit Datastar signals instead — then no form fields travel). Method
	// follows wire's zero-value contract (GET) — set MethodPost for mutating
	// submissions, mirroring DefaultFormProps's native Method. Wire.URL
	// replaces Action for the wired request; Action/Method stay as the no-JS
	// fallback. Wire.Target renders only for htmx (hx-target); Datastar
	// targeting is response-driven — wrap the handler in wire.Handler.
	// An empty Wire.URL wires nothing (the form stays a plain HTML form).
	Wire *wire.Action
}

type InputGroupProps struct {
	utils.BaseProps
	LeftAddon  templ.Component
	RightAddon templ.Component
}

type InputProps struct {
	utils.BaseProps
	Type         InputType
	Name         string
	Value        string
	Placeholder  string
	Label        string
	Required     bool
	Disabled     bool
	ReadOnly     bool
	AutoFocus    bool
	MaxLength    int
	EnterKeyHint EnterKeyHintType
	Autocomplete AutocompleteType
	Error        string
	HelpText     string
}

type InputType string

type RadioGroupProps struct {
	utils.BaseProps

	Name     string
	Label    string // renders as <legend>
	Options  []RadioOption
	Inline   bool   // horizontal layout
	Error    string // group-level error
	HelpText string
	Required bool
}

type RadioOption struct {
	Value    string
	Label    string
	Checked  bool
	Disabled bool
}

type RadioProps struct {
	utils.BaseProps

	Name     string
	Value    string
	Label    string
	Checked  bool
	Required bool
	Disabled bool
}

type RatingProps struct {
	utils.BaseProps
	Name     string
	Value    int // current rating (0 = unrated)
	Max      int // maximum stars (default: 5)
	Size     RatingSize
	ReadOnly bool // display-only mode (no inputs)
	Required bool
	Label    string
	HelpText string
}

type RatingSize string

type SegmentedControlItem struct {
	// Label is the visible text.
	Label string
	// Value is the option's submitted value (radio mode).
	Value string
	// Href, when set on ANY item, switches the whole control to link mode —
	// every item should carry one (a mixed control is a consumer bug;
	// items without an Href render inert links in link mode).
	Href string
}

type SegmentedControlProps struct {
	utils.BaseProps

	// Name is the radio group's field name (radio mode). Ignored in link
	// mode.
	Name string
	// Items render in FORWARD DOM order (first item first) so radiogroup
	// arrow keys move down the value order (the Rating rule).
	Items []SegmentedControlItem
	// ActiveValue marks the selected item: the checked radio (radio mode)
	// or aria-current link (link mode).
	ActiveValue string
}

type SelectGroup struct {
	Label   string
	Options []SelectOption
}

type SelectOption struct {
	Value    string
	Label    string
	Disabled bool
	Selected bool
}

type SelectProps struct {
	utils.BaseProps
	Name    string
	Label   string
	Options []SelectOption
	// Groups, when non-empty, renders <optgroup> elements instead of a flat
	// Options list. Each group has its own label. Options is ignored when
	// Groups is set.
	Groups   []SelectGroup
	Required bool
	Disabled bool
	// Stylable, when true, opts into the modern customizable <select> API
	// (appearance: base-select). Emits a <button><selectedcontent> structure
	// inside the select for CSS styling. Non-supporting browsers ignore
	// these elements — progressive enhancement, no breaking changes.
	// Requires the .tc-select CSS from templates/app.css.
	Stylable bool
	Error    string
	HelpText string
}

type SliderProps struct {
	utils.BaseProps
	Name     string
	Label    string
	Min      float64
	Max      float64
	Value    float64
	Step     float64
	Required bool
	Disabled bool
	HelpText string
	Error    string
	// ShowValue displays the current value next to the label.
	ShowValue bool
}

type TagsInputProps struct {
	utils.BaseProps
	Name           string
	Label          string
	Values         []string
	Placeholder    string
	MaxTags        int  // 0 = unlimited
	AllowDuplicate bool // false by default
	Required       bool
	Disabled       bool
	Error          string
	HelpText       string
}

type TextareaProps struct {
	utils.BaseProps
	Name         string
	Value        string
	Placeholder  string
	Label        string
	Rows         int
	Required     bool
	Disabled     bool
	ReadOnly     bool
	MaxLength    int
	AutoGrow     bool
	EnterKeyHint EnterKeyHintType
	Error        string
	HelpText     string
}

type ToggleProps struct {
	utils.BaseProps
	Name     string
	Label    string
	Checked  bool
	Disabled bool
	Required bool
	Error    string
	HelpText string
	Size     ToggleSize
}

type ToggleSize string

type ValidationError struct {
	Field   string // HTML element ID (e.g. "email", "user_name") — used as the anchor href target
	Message string
}

type ValidationSummaryProps struct {
	utils.BaseProps
	Errors []ValidationError
}