ui

type Align string

type AnchoredRailConfig struct {
	// Label is the visible heading above the rail (e.g. "Categories",
	// "By intent", "The path"). Required: also doubles as the
	// aria-label on the underlying <aside>.
	Label string

	// Items in display order. Required.
	Items []RailItem

	// ObserveSelector is the CSS selector for the container the
	// headless-rail module watches for in-view sections. Typically the
	// id of a wrapper around the sections (e.g. "#docs-sections"). If
	// empty, the rail is purely static: the links work and nothing is
	// marked.
	ObserveSelector string

	// TargetSelector overrides the module's default heading targets.
	// Set it when the sections aren't headings (e.g. ".intent[id]").
	TargetSelector string

	// Class is appended to the <aside>'s class list.
	Class string

	// ID optionally tags the <aside>.
	ID string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the rail's root <aside>.
	// Keys the component owns are dropped: class and id (use Class /
	// ID), data-hui-* (the rail wiring), and aria-label (use Label).
	ExtraAttrs html.Attrs
}

type AnimatedCounterConfig struct {
	// To is the target value (required).
	To int
	// From is the starting value during animation. Default 0.
	From int
	// DurationMs is the animation length. Default 1200.
	DurationMs int
	// Prefix / Suffix are static strings on either side (e.g.
	// Prefix="$", Suffix="+", Suffix=" users").
	Prefix string
	Suffix string
	// ID / Class are passed through.
	ID    string
	Class string
	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the counter's root.
	// Keys the component owns are dropped: class and id (use Class /
	// ID), data-fui-*, and every data-hui-* hook.
	ExtraAttrs html.Attrs
}

type AspectRatio string

type AspectRatioConfig struct {
	// Ratio is the aspect-ratio bucket (required). Use one of the
	// AspectRatio* constants.
	Ratio AspectRatio

	// Class adds extra CSS classes.
	Class string

	// ID sets the element id.
	ID string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the wrapper's root <div>.
	// Keys the component owns are dropped: class and id (use Class /
	// ID), style and data-fui-*.
	ExtraAttrs html.Attrs
}

type AuthCardConfig struct {
	// Title is the card heading (e.g. "Sign in to Acme").
	Title string
	// Alert is an optional message shown above the body, typically a
	// failed-login notice. Empty renders nothing.
	Alert render.HTML
	// Body is the card contents, typically a ui.Form.
	Body render.HTML
	// Footer is an optional row below the body, e.g. a "Create an
	// account" link.
	Footer render.HTML
	Class  string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the card's root element.
	// Keys the component owns are dropped: class (use Class), id, and
	// data-fui-*.
	ExtraAttrs html.Attrs
}

type AvatarConfig struct {
	// Name is required; used for alt text and to derive initials when
	// no image source is set.
	Name string
	Src  string     // optional image URL; falls back to initials when empty
	Size AvatarSize // sm | "" (default md) | lg | xl

	// Status draws a presence dot in the lower corner (online / away /
	// busy / offline). Empty renders no dot.
	Status AvatarStatus
	// StatusLabel overrides the dot's accessible name. Defaults to the
	// status value (e.g. "online"). Ignored when Status is empty.
	StatusLabel string

	ID    string
	Class string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the avatar's root <span>.
	// Keys the component owns are dropped: class and id (use Class /
	// ID) and data-fui-*.
	ExtraAttrs html.Attrs
}

type AvatarGroupConfig struct {
	// Avatars is the source list: at least one. Order matters: the
	// first element renders on top.
	Avatars []AvatarConfig

	// Max caps how many avatars render before the "+N" indicator
	// replaces the remainder. Default 5.
	Max int

	// Size propagates to each child Avatar unless the child has its
	// own Size set explicitly. Default AvatarMd.
	Size AvatarSize

	// Label is the aria-label on the group element. Default "Avatars".
	Label string

	// ShowNames wraps each Avatar in a Tooltip so hover / keyboard
	// focus reveals the avatar's Name. Useful for team-roster stacks
	// where the SR-only initials aren't enough for sighted users.
	ShowNames bool

	ID    string
	Class string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the group's root element.
	// Keys the component owns are dropped: class and id (use Class /
	// ID), data-fui-*, role, and aria-label (use Label).
	ExtraAttrs html.Attrs
}

type AvatarSize string

type AvatarStatus string

type BackToTopConfig struct {
	// Position selects which corner the button anchors to.
	// Defaults to BackToTopBottomRight when empty.
	Position BackToTopPosition

	// Icon overrides the button content. Pass any render.HTML
	// (SVG markup, text, an icon component, etc).
	// Defaults to a chevron-up arrow SVG.
	Icon render.HTML

	// ThresholdPx is the scroll distance in pixels before the
	// button becomes visible. Defaults to 400 when 0.
	ThresholdPx int

	// Smooth controls scroll-to-top behavior.
	// Defaults to smooth scrolling (BackToTopSmooth).
	// Set to BackToTopInstant for no animation.
	Smooth BackToTopScrollBehavior

	// Size controls the button diameter.
	// Defaults to BackToTopMD (2.75rem).
	Size BackToTopSize

	// Variant controls the color scheme.
	// Defaults to BackToTopPrimary (solid primary color).
	Variant BackToTopVariant

	// Offset controls the distance from the viewport edge.
	// Defaults to BackToTopOffsetMD.
	Offset BackToTopOffset

	// Label overrides the aria-label. Defaults to "Back to top".
	Label string

	// ScrollTarget overrides the scroll-to selector.
	// Defaults to scrolling to y=0. Set to a CSS selector
	// (e.g. "#main-content") to scroll a specific element
	// into view instead.
	ScrollTarget string

	// ID is an optional id for the root element.
	ID string

	// Class is an optional extra CSS class.
	Class string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the root <button>. Keys
	// the component owns are dropped: class and id (use Class / ID),
	// data-fui-*, type, aria-label (use Label), and inert (the
	// runtime's initial-hidden wiring).
	ExtraAttrs html.Attrs
}

type BackToTopOffset string

type BackToTopPosition string

type BackToTopScrollBehavior string

type BackToTopSize string

type BackToTopVariant string

type BannerConfig struct {
	// Title is the bold lead-in (required).
	Title string
	// Body is the supporting text (optional).
	Body string
	// Variant picks color + role. Defaults to BannerInfo.
	Variant BannerVariant
	// Strip renders a full-width announcement with square edges and inline copy.
	Strip bool
	// Dismissible adds an X button. When DismissID is set the runtime
	// records the dismissal in localStorage AND a same-name cookie; when
	// Ctx also carries the request (app.WithRequest, layouts and screens
	// get this automatically), Banner sees the cookie and renders nothing
	// at all on later requests, no flash of a dismissed banner before
	// the runtime's hide pass. (Richer server-side persistence is still
	// up to the app. Banner doesn't ship its own RPC.)
	Dismissible bool
	DismissID   string
	// Action is an optional inline call-to-action (a Link or Button
	// rendered to the right of the body).
	Action render.HTML
	// ID / Class are passed through to the outer element.
	ID    string
	Class string
	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the banner's root <div>.
	// Keys the component owns are dropped: class and id (use Class /
	// ID), data-fui-*, and the severity contract (role, aria-live,
	// derived from Variant).
	ExtraAttrs html.Attrs
	// Ctx carries the per-request context used to resolve the dismiss label.
	// When nil, English fallbacks apply.
	Ctx context.Context
}

type BannerVariant string

type BarChartBar struct {
	// Label is the x-axis category label + AT <title>.
	Label string
	// Value is the bar height (≥0).
	Value float64
	// Color overrides the default theme primary. Accepted forms:
	//   - a palette token: "primary", "info", "success", "warning",
	//     "danger" (rendered via a theme class, so it re-skins in dark
	//     mode);
	//   - a registered status variant name (ui.RegisterStatusVariant),
	//     resolved to its accent color;
	//   - a CSS color written as hex (#rgb/#rgba/#rrggbb/#rrggbbaa),
	//     or a rgb()/rgba()/hsl()/hsla()/oklch()/color() function, or
	//     var(--…), emitted verbatim as the SVG fill.
	//
	// CSS named colors ("tomato") must be written as hex or var(). An
	// unrecognized value falls back to the theme primary instead of
	// rendering an invalid (black) fill.
	Color string
}

type BarChartConfig struct {
	// Bars are the entries (≥1).
	Bars []BarChartBar
	// Width / Height in CSS pixels. Default 320×200.
	Width  int
	Height int
	// ShowAxis renders a left value axis: hairline gridlines at clean
	// tick values with numeric labels down the left gutter. Default off
	// (the always-on value labels + baseline already make magnitudes
	// legible; turn this on for a denser analytical read).
	ShowAxis bool
	// ShowLabels renders the category labels under each bar. Long labels
	// wrap onto up to two lines; a single over-long word is ellipsized
	// with the full text preserved in the bar's <title>. Default off.
	ShowLabels bool
	// HideValues suppresses the per-bar value labels that ride above each
	// cap. Values are shown by default. Set this to opt out (e.g. a dense
	// sparkline-style strip where the numbers would crowd).
	HideValues bool
	// FitHeight sizes the SVG to hug the tallest bar instead of a
	// fixed Height: the plot area is chosen so the tallest bar lands
	// at 96px and the SVG height becomes the value/label gutters plus
	// exactly that, so no empty band pads the space above the caps.
	// The y-scale still rounds up to a clean maximum (the headroom
	// rule), so bar RATIOS are identical to the fixed-height chart —
	// only the blank pixels above the tallest bar are gone. Ignored
	// when Height is set explicitly.
	FitHeight bool
	// LabelledBy is the id of an element naming the chart for AT.
	LabelledBy string
	ID         string
	Class      string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the root <svg>. Keys the
	// component owns are dropped: class and id (use Class / ID),
	// data-fui-*, width, height, viewBox, xmlns, role,
	// aria-labelledby (use LabelledBy), and aria-hidden. With no Bars
	// the extras land on the shared zero-data placeholder instead.
	ExtraAttrs html.Attrs
}

type BoxConfig struct {
	Pad      BoxPad // padding (none | sm | md | lg | xl)
	Surface  bool   // when true, applies the surface background + border-radius
	Outlined bool   // when true, applies a 1px border (pairs well with Surface=false)
	ID       string
	Class    string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the box's root <div>.
	// Keys the component owns are dropped: class and id (use Class /
	// ID), style and data-fui-*.
	ExtraAttrs html.Attrs
}

type BoxPad string

type BreadcrumbsConfig struct {
	// Items are the steps, shallowest first.
	Items []Crumb

	// Label is the nav landmark's accessible name. Defaults to
	// "Breadcrumb", resolved per request through StringsFor when a
	// translator is on the context.
	Label string
	// CompactMobile shows only the final two steps below md, without
	// a leading separator. The full trail remains on wide screens.
	CompactMobile bool

	ID    string
	Class string
	// ExtraAttrs forwards additional attributes to the <nav> root.
	// Keys the component owns are dropped: class and id (use Class /
	// ID) and aria-label (use Label).
	ExtraAttrs html.Attrs

	// Ctx resolves the Strings table through the request's translator.
	Ctx context.Context
}

type ButtonConfig struct {
	Label string // required visible text + aria-label
	// AriaLabel overrides the accessible name when it must differ from
	// the visible Label: a row of buttons all reading "Revoke" that
	// each need a distinct accessible name ("Revoke admin from Alice").
	// Empty ⇒ the accessible name is Label. This is the supported way
	// to set it — an aria-label in ExtraAttrs is dropped (owned key).
	AriaLabel string
	// Variant defaults to ButtonPrimary.
	Variant ButtonVariant
	// Size defaults to ButtonSizeDefault.
	Size ButtonSize
	// Type is the button type: "button" (default), "submit", or "reset".
	Type string
	// Disabled renders the disabled state. This is the supported way to
	// set it — a disabled key in ExtraAttrs panics pointing here.
	Disabled bool
	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the rendered <button>.
	// Every data-fui-* key is runtime wiring and goes through the
	// typed Action seam (attach interactive wiring with
	// interactive.Action.Attrs(), interactive.OpenOnClick and friends —
	// headless.ButtonProps.Action admits exactly that vocabulary and
	// panics on any data-fui-* key outside it, where the old carrier
	// contract rendered it as a dead attribute). Keys the component
	// owns are dropped: class and id (use Class / ID), type (use
	// Type), disabled (use Disabled) and aria-label (use AriaLabel).
	ExtraAttrs html.Attrs
	ID         string
	Class      string
}

type ButtonSize string

type ButtonVariant string

type CalloutConfig struct {
	Title   string
	Variant StatusVariant // info | success | warning | danger | neutral
	ID      string
	Class   string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers) to the callout's root element. Keys the
	// component owns are dropped: class and id (use Class / ID),
	// data-fui-* and role.
	ExtraAttrs html.Attrs
}

type CardConfig struct {
	// Heading is the optional top-of-card title, rendered as a
	// heading inside the card's header. The heading level defaults to
	// 3; a card does not know how deep in the outline it sits, so a
	// page that nests cards under an h2 says HeadingLevel: 2.
	Heading string

	// HeadingLevel overrides the heading element level (default 3).
	HeadingLevel int

	// Description is optional supporting text rendered beneath the
	// heading.
	Description string

	// Header replaces the auto-rendered Heading/Description block
	// through the primitive's fillable header part. Use when the
	// header needs more than a title, e.g. a row with an avatar and
	// trailing actions.
	Header render.HTML

	// Footer renders below the body, separated by a hairline border.
	// Common usage: button row, last-updated timestamp, status pill.
	Footer render.HTML

	// Interactive flips the surface to a focusable, hover-able link
	// shell. When set, the card renders as an <a> wrapping one inner
	// part so the entire surface activates on click.
	Href string

	Variant CardVariant
	ID      string
	Class   string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the card's root element,
	// whichever shape it takes (<a> or <div>). Keys the component
	// owns are dropped: class and id (use Class / ID), style,
	// data-fui-* and href (use Href).
	ExtraAttrs html.Attrs
}

type CardVariant string

type CarouselConfig struct {
	// Slides are the entries (≥1).
	Slides []CarouselSlide
	// Label is the accessible label for the carousel region (required,
	// becomes role=region + aria-label).
	Label string
	// NoDots hides the pagination dots.
	NoDots bool
	// NoArrows hides the Prev/Next buttons.
	NoArrows bool
	// AutoRotateMs, when > 0, auto-advances every N ms. Paused on
	// hover, focus, hidden tab and prefers-reduced-motion.
	AutoRotateMs int
	// Loop makes Next-on-last wrap to first (and vice versa). Default
	// false: Prev/Next refuse at the ends.
	Loop bool
	// VisiblePerView (default 1) shows N slides side-by-side.
	VisiblePerView int
	ID             string
	Class          string
	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the carousel's root.
	// Keys the component owns are dropped: class and id, the data-hui-*
	// wiring, and the region contract (role, aria-roledescription,
	// aria-label).
	ExtraAttrs html.Attrs
	// Ctx carries the per-request context used to resolve the
	// carousel's sentences. When nil, English fallbacks apply.
	Ctx context.Context
}

type CarouselSlide struct {
	// Content is the slide body (required). Caller decides the shape.
	Content render.HTML
	// Label is the slide's accessible label. Defaults to the
	// Strings.CarouselSlide sentence ("Slide {n} of {total}").
	Label string
}

type CenterConfig struct {
	// MinHeight maps to a class: "viewport" (100vh), "screen" (100dvh
	// where supported), or "" (auto). Used for empty-state landing /
	// onboarding panels.
	MinHeight string
	ID        string
	Class     string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the region's root <div>.
	// Keys the component owns are dropped: class and id (use Class /
	// ID), style and data-fui-*.
	ExtraAttrs html.Attrs
}

type CheckboxGroupConfig struct {
	// Name is the shared form-field name for all checkboxes (required).
	Name string
	// Legend is the group label rendered as <legend> (required).
	Legend string
	// Options is the list of checkbox options (required, at least one).
	Options []CheckboxGroupOption
	// Help renders supporting text under the group.
	Help string
	// Error replaces Help with an error message.
	Error string
	// Required marks every leaf required.
	Required bool
	ID       string
	Class    string

	// ExtraAttrs forwards additional attributes to the group's root
	// <fieldset> element, with the same owned-key drops as
	// RadioGroup's.
	ExtraAttrs html.Attrs
}

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

type ClusterConfig struct {
	Gap     Gap
	Align   Align
	Justify Justify
	// NoWrap opts out of the default responsive wrapping behavior. Use it only
	// for compact chrome that is guaranteed to fit, such as two icon controls.
	NoWrap bool
	ID     string
	Class  string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the cluster's root <div>.
	// Keys the component owns are dropped: class and id (use Class /
	// ID), style, data-fui-* and the data-hui-* hooks.
	ExtraAttrs html.Attrs
}

type CodeBlockConfig struct {
	Code     string // raw source to render; escaped. Ignored when Lines is set.
	Language string // optional, used for aria-label only
	// Lines carries pre-rendered (e.g. syntax-highlighted) logical source
	// lines. When non-empty it takes precedence over Code; each entry is
	// wrapped as one line so LineNumbers can number it. Callers own the
	// per-token markup: pass already-escaped, trusted HTML.
	Lines []render.HTML
	// Filename, when set, renders a chrome header (status dot + filename)
	// above the body and switches the wrapper to a framed container.
	Filename string
	// ShowCopy adds a copy-to-clipboard button (the framework CopyButton)
	// in the header, targeting this block's own body. Forces a header even
	// when Filename is empty.
	ShowCopy bool
	// LineNumbers renders a left gutter numbering each line.
	LineNumbers bool
	// Scroll caps the body height (var(--ui-code-block-scroll-max,
	// 26rem)) and makes it scroll vertically, for showing a long file in
	// full without letting it dominate the page. Implies the framed
	// container.
	Scroll bool
	// HighlightLines marks the given 1-based source lines with
	// fui-code-block__line--highlight, a background band that reaches the
	// block's edge. Ranges past the last line match nothing.
	HighlightLines []LineRange
	// Diff classifies lines by their first character: '+' (including the
	// '+++' file-header form) gets fui-code-block__line--added, '-' (and
	// '---') gets --removed. The marker stays in the text: a diff's
	// content IS the diff. On the Lines path a leading token span is
	// skipped, so the marker behind it still classifies.
	Diff bool
	// HighlightWords wraps literal (not regex) matches inside a line in
	// <mark class="fui-code-block__mark">. Matching runs on the source
	// text of each line's text nodes: a word never matches across a tag
	// boundary, and marked text is escaped like the rest of the line.
	HighlightWords []string
	// Wrap soft-wraps long lines (white-space: pre-wrap) instead of the
	// default horizontal scroll. The zero value keeps today's behaviour:
	// code blocks scroll, they do not wrap.
	Wrap  bool
	ID    string
	Class string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers) to the block's root element, whichever shape
	// it takes (a bare <pre> or a framed <div>). Keys the component
	// owns are dropped: class and id (use Class / ID), data-fui-*, and
	// the scroll contract (tabindex, aria-label) that lives on the
	// <pre> body.
	ExtraAttrs html.Attrs
}

type CodeSample struct {
	// Label is the visible tab text ("Go", "TypeScript", "curl"). Required.
	Label string
	// Language is the HighlightLines language key (go, js, ts, sql, json,
	// yaml, shell, …). Unknown values fall back to plain escaped text.
	Language string
	// Code is the raw source; it is escaped/tokenized, never trusted HTML.
	// Required.
	Code string
	// Filename, when set, renders the CodeBlock's framed chrome header.
	Filename string
}

type CodeTabsConfig struct {
	// Name groups the tabs as one exclusive set (native <details name=>
	// exclusivity). Required and must be unique within the page.
	Name string
	// Label is an optional aria-label for the group.
	Label string
	// LineNumbers turns on the CodeBlock line-number gutter for every tab.
	LineNumbers bool
	ID          string
	Class       string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the tab group's root
	// element. Keys the component owns are dropped: class (use
	// Class), id (ID tags the inner tabset, not the root), and
	// data-fui-*.
	ExtraAttrs html.Attrs
}

type CollapsibleConfig struct {
	Summary string // required:  the always-visible header
	Open    bool   // optional:  start expanded (default: collapsed)
	Class   string // optional:  additional CSS classes
	ID      string // optional:  element id
	// Name groups sections into an exclusive set: sections sharing a
	// Name are the native <details name> group, so opening one closes
	// the others with no script. Empty leaves each section independent.
	Name string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the root <details>. Keys
	// the component owns are dropped: class and id (use Class / ID),
	// the data-hui-* wiring, and open (use Open).
	ExtraAttrs html.Attrs
}

type ColorFieldConfig struct {
	// Name is the hex text input's form-field name (required): the
	// text input is the control that submits.
	Name string
	// Value is the authoritative value, placed in the text input
	// verbatim. When it is not #rgb or #rrggbb the swatch falls back
	// to black and the shell is marked data-invalid.
	Value string
	// TextID is the id of the text input, for a label's `for`.
	// A Field's id wins over it when both are set.
	TextID string
	// SwatchLabel is required. The swatch's own accessible name comes
	// from the component's PickColor word plus Name; SwatchLabel
	// names the TEXT input when TextLabel is empty — the input that
	// carries the value is the worse of the two to leave unnamed,
	// and the easy one to miss, because a caller that wraps this in
	// its own <label for=…> sees a labelled control while a caller
	// that does not ships an unnamed critical control.
	SwatchLabel string
	// TextLabel is the accessible name for the text input. Defaults
	// to SwatchLabel. Set aria-label or aria-labelledby in TextAttrs
	// to take over.
	TextLabel string
	// SwatchAttrs and TextAttrs add attributes to the respective
	// inputs, for the data-* attributes a caller's own JS binds to.
	// Keys the component owns are dropped: the swatch's aria-label,
	// type, value and tabindex; the text input's name, value and the
	// field wiring; and every data-fui-* / data-hui-* key.
	SwatchAttrs html.Attrs
	TextAttrs   html.Attrs

	Class string

	// ExtraAttrs forwards additional attributes to the shell's root
	// element. Keys the component owns are dropped: class (use
	// Class), id, and every data-fui-* / data-hui-* key. Per-input
	// attributes belong in SwatchAttrs / TextAttrs.
	ExtraAttrs html.Attrs

	// Ctx carries the per-request context used to resolve the swatch's
	// word (ui.StringsFor: PickColor). When nil, the English default
	// is used.
	Ctx context.Context

	// Field is the wiring an enclosing FormField handed its builder:
	// applied to the text input (id, described-by chain, invalid
	// state), and it wins over TextID. Zero value means standalone.
	Field headless.FieldControl
}

type ColorPickerConfig struct {
	// Name is the form field name for the color input (required).
	Name string
	// Label is the accessible label (required).
	Label string
	// Value is the initial color (hex, e.g. "#4F46E5"). Defaults to
	// the browser's native default (black) when empty.
	Value string
	// Disabled disables the input.
	Disabled bool
	ID       string
	Class    string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the picker's root element
	// (the wrapper div, not the <input>). Keys the component owns
	// are dropped: class, id (the wrapper id derives from ID / Name),
	// and data-fui-*.
	ExtraAttrs html.Attrs
}

type Column struct {
	// Key is the column identifier used for sort state and matching
	// against Row.Cells. Required.
	Key string

	// Header is the visible column header text. May be empty: an
	// actions or icon column. A sortable column with no header gets
	// its sort anchor named from the column Key.
	Header string

	// Sortable makes the header a sort control: an anchor that
	// re-submits the screen's query with this column's Key and the
	// next direction.
	Sortable bool

	// Align is "start" (default), "center", or "end". It reaches the
	// markup as the column's variant, so the class map names the
	// alignment class for the header and the cell.
	Align string
}

type ComboboxConfig struct {
	// ID is the input element id (the listbox takes <ID>-listbox).
	// Required, page-unique.
	ID string
	// Name is the form-submit name on the input. Required.
	Name string
	// Label is the visible label text. Required.
	Label string
	// LabelHidden folds the label into the visually-hidden recipe (the
	// placeholder or surrounding chrome already names the field).
	LabelHidden bool
	// Placeholder for the input.
	Placeholder string

	// Options is a static list the module filters client-side. Takes
	// precedence over Island.
	Options []headless.ComboboxOption

	// Island is the typed in-page results contract: the endpoint that
	// re-renders the listbox and the signal the region is bound to.
	Island *headless.Island
	// NoScriptAction is the form's action URL, the no-script
	// destination: same-origin, a GET that submits the query. Required
	// when Island is set; refused when it is "#".
	NoScriptAction string

	// DebounceMs bounds the input debounce. Default 250.
	DebounceMs int

	// Class rides the wrapper beside the component's own class.
	Class string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the combobox's root.
	// Keys the component owns are dropped, as everywhere.
	ExtraAttrs html.Attrs

	// Ctx carries the per-request context used to resolve the
	// combobox's sentences. When nil, English fallbacks apply.
	Ctx context.Context
}

type CommandPaletteConfig struct {
	// Name uniquely identifies the modal widget. Default
	// "command-palette".
	Name string

	// RPCPath is the search endpoint. The handler receives the
	// query string and returns `<li role="option">…</li>` fragments
	// to swap into the listbox. Required unless Commands is set.
	RPCPath string

	// Placeholder is the input placeholder. Default
	// "Type a command or search…".
	Placeholder string

	// Shortcut is the chord that opens the palette. Default "Meta+K"
	// (Cmd+K on Mac, Ctrl+K elsewhere: the runtime treats either as
	// Mod when matching).
	Shortcut string

	// DebounceMs is the search debounce window. Default 150 (snappier
	// than a generic combobox since results render eagerly).
	DebounceMs int

	// TriggerLabel is the SR-only trigger button text: what AT
	// users hear if they tab to it. Default "Open command palette".
	TriggerLabel string

	// EmptyHTML is the listbox HTML at first paint. Empty (default)
	// renders a placeholder hint.
	EmptyHTML string

	// Commands, when non-empty, renders a static, client-side-filtered
	// command list, no search endpoint needed. Use for a small fixed
	// set (docs/nav links) so the palette works on a serverless export
	// where no RPC handler exists. Takes precedence over RPCPath.
	Commands []PaletteCommand

	// FallbackHref is the ordinary same-origin destination the trigger
	// navigates to without script: a modal trigger with no navigation
	// path is a button a scriptless reader cannot use. Required; "#"
	// and cross-origin values are refused at render.
	FallbackHref string

	// Ctx carries the per-request context used to resolve i18n labels
	// (placeholder, trigger + dialog titles, hint chips). When nil,
	// English fallbacks apply.
	Ctx context.Context

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) onto the palette's own root
	// (the ui-cmd-palette panel inside the modal; the modal chrome is
	// widget machinery). Keys the component owns are dropped:
	// class, id, and data-fui-*.
	ExtraAttrs html.Attrs
}

type ConditionalFieldConfig struct {
	// WhenName is the form field name to watch. Required.
	WhenName string

	// WhenValue is the value that triggers showing the children.
	// For checkboxes/radios, this matches the value attribute. Required.
	WhenValue string

	// Children is the content to show when the condition is met.
	Children []render.HTML

	Class string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the region's root
	// element. Keys the component owns are dropped: class (use
	// Class), id, data-fui-*, data-hui-* (the region's hooks are the
	// runtime's contract, not a caller's to forge), hidden and
	// aria-hidden (the module owns the region's visibility).
	ExtraAttrs html.Attrs
}

type ConfirmActionConfig struct {
	// Name uniquely identifies the modal widget. Required.
	// Usually qualified per row, e.g. "delete-user-42".
	Name string

	// TriggerLabel is the visible text on the destructive button.
	// Required.
	TriggerLabel string

	// TriggerVariant maps to one of the framework button variants.
	// Defaults to "danger". The trigger always renders as
	// .fui-btn--<TriggerVariant>.
	TriggerVariant string

	// Title is the alertdialog title (h2). Required.
	Title string

	// Body is the alertdialog body paragraph. Required: the body
	// gives the user the information they need to confirm safely.
	Body string

	// ConfirmLabel defaults to "Confirm".
	ConfirmLabel string

	// CancelLabel defaults to "Cancel".
	CancelLabel string

	// RPCPath is the endpoint the Confirm button posts to. Required.
	RPCPath string

	// RPCMethod defaults to "POST".
	RPCMethod string

	// SuccessSignal, when set, emits data-fui-rpc-signal="<name>" on
	// the Confirm button. On a 2xx response the runtime broadcasts
	// the response body (typically the fresh authoritative list HTML)
	// into the named signal: pair it with a
	// data-fui-signal="<name>" data-fui-signal-mode="html" region to
	// swap in that HTML (e.g. the shorter list after a delete). On a
	// non-2xx response html-mode regions are left unchanged (the
	// optimistic-UI invariant: a failed delete leaves the row/list
	// intact), while text-mode regions render a human-readable
	// "Error: …" string. Empty (the default) leaves the response
	// unused, which is correct for fire-and-forget confirms.
	//
	// The name MUST match ^[A-Za-z0-9_-]+$: ConfirmAction panics
	// otherwise. The runtime interpolates the value into a CSS
	// attribute selector (querySelectorAll '[data-fui-signal="…"]'),
	// so any other shape is either an invalid selector (silently
	// drops the broadcast) or a selector-injection footgun.
	SuccessSignal string

	// AutofocusConfirm flips the initial focus from Cancel (the
	// default, safer choice for destructive flows where accidental
	// Enter must not fire the action) to Confirm. Set to true for
	// non-destructive confirmations ("Apply changes?", "Continue?").
	AutofocusConfirm bool
	// Ctx carries the per-request context used to resolve the
	// Confirm/Cancel button labels. When nil, English fallbacks apply.
	Ctx context.Context

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) onto the dialog's own root
	// (the ui-confirm-action panel; the modal chrome is widget
	// machinery, and the trigger is a plain ui.Button — render a
	// Button yourself for trigger-level extras). Keys the component
	// owns are dropped: class, id, and data-fui-*.
	ExtraAttrs html.Attrs
}

type ContainerConfig struct {
	// Width picks the max-inline-size. Defaults to ContainerDefault.
	Width ContainerWidth
	// Pad picks the block padding. Defaults to ContainerPadNone.
	Pad ContainerPad
	// As lets the caller pick a non-<div> tag (e.g. "section", "main").
	// Defaults to "div".
	As    string
	ID    string
	Class string
	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the wrapper element.
	// Keys the component owns are dropped: class and id (use Class /
	// ID), style and data-fui-*.
	ExtraAttrs html.Attrs
}

type ContainerPad string

type ContainerWidth string

type ContentRowConfig struct {
	// Sidebar is the start column. Give it a ui.Sidebar; the column
	// takes its width from the sidebar's content, sits on the surface
	// color and draws the inline-end rule. Below the breakpoint the
	// sidebar's own drawer serves navigation and the column stacks
	// above main with a block-end rule instead.
	Sidebar render.HTML
	// NavLabel labels the start column's navigation landmark — the
	// landmark that wraps the sidebar's title, links and footer (the
	// sidebar's own inner nav names only the links list). Defaults to
	// "Sidebar".
	NavLabel string
	// Toolbar is an optional row above main, beside the sidebar —
	// the workspace the shell's Toolbar slot renders. Compose a
	// ui.Toolbar (or any row) here; the row owns only its placement
	// and its block-end rule.
	Toolbar render.HTML
	// Aside is the optional end column after main: a context aside.
	// It stacks below main under the breakpoint, and it releases its
	// width when it holds only an empty outlet, so an unfilled
	// context column takes no space.
	Aside render.HTML
	// AsideLabel labels the aside landmark. Defaults to "Context".
	AsideLabel string
	// Breakpoint picks the viewport width below which the row stacks:
	// below md (48rem, the default) or below lg (64rem). Match it to
	// SidebarConfig.DrawerBreakpoint so the sidebar becomes a drawer
	// at the same width the row collapses.
	Breakpoint StackBreakpoint
	// Viewport confines desktop scrolling to main, the nav column and
	// the aside: at and above the breakpoint the row fills the rest of
	// the viewport below the page header and each column scrolls on
	// its own; below it the page scrolls normally. The row cannot
	// style its parent, so it reads the header's height from the
	// --size-header-height token (56px default) — the same token
	// the app-shell header band fixes its own height with — and
	// assumes the page column above it is at least one screen tall.
	// A recipe arranges both: ui.Stack{Screen: true} above, a header
	// carrying the fixed band. The row assumes no footer band below it
	// in this mode; give viewport pages their footer inside main.
	Viewport bool
	// PhoneNavFlush drops the stacked nav column's block-end rule
	// below the breakpoint. Set it when the sidebar's phone navigation
	// lives outside the column (a NativeMobile sidebar whose drawer
	// trigger the page header hosts): the stacked column renders empty
	// on phones and an empty band must not draw a line.
	PhoneNavFlush bool
	// Class appends to the row root's class list.
	Class string
	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the row root. Keys the
	// component owns are dropped: class (use Class), and data-fui-*.
	ExtraAttrs html.Attrs
}

type ControlConfig struct {
	// Field is the wiring the enclosing FormField handed the builder
	// (the FieldControl its Input closure received). Required: a
	// control built without it is exactly the defect the builder
	// exists to prevent — an id the label does not point at, a
	// description that never arrives, an invalid state the control
	// does not carry. It supplies the id, the aria-describedby, the
	// invalid state and the required flag; those four never come from
	// anywhere else, because two sources for one fact is how they
	// drift.
	Field headless.FieldControl
	// Type is the input type: text (the default), email, password,
	// datetime-local, file, tel, url, search, hidden — any type the
	// browser knows.
	Type string
	// Name is the form-field name (required).
	Name string
	// Value, Placeholder and AutoComplete render their attributes.
	Value, Placeholder, AutoComplete string
	// Disabled disables the control.
	Disabled bool
	// Min, Max and Step are the numeric and date bounds, through
	// headless's Owned seam (which admits exactly those three keys).
	Min, Max, Step string
	// MinLength and MaxLength are the length constraints.
	MinLength, MaxLength int
	// Class appends to the control's own class.
	Class string
	// ExtraAttrs forwards additional attributes (data-* test hooks, a
	// relation's data-rel-entity, pattern and title) onto the input.
	// Keys the control owns are dropped: class and id, type, name,
	// value, placeholder, autocomplete, minlength, maxlength, min,
	// max, step, required, disabled, aria-invalid and
	// aria-describedby.
	ExtraAttrs html.Attrs
}

type CopyButtonConfig struct {
	// Target is a CSS selector that identifies the element whose
	// textContent will be copied. Required.
	Target string

	// Label is the visible button text before copying. Default "Copy".
	Label string

	// CopiedLabel is the visible text shown briefly after success.
	// Default "Copied".
	CopiedLabel string

	// IconOnly hides the visible label but keeps the SR-only label
	// (via AriaLabel or default). Use when the button is icon-only.
	IconOnly bool

	// AriaLabel overrides the screen-reader name. When IconOnly is
	// true and AriaLabel is empty, defaults to "Copy to clipboard".
	AriaLabel string

	// AnnounceText is the message written into the role=status span
	// on copy success. Default "Copied".
	AnnounceText string

	// ToastOnCopy, when true, fires a toast on copy success. The toast
	// is dispatched via window.__gofastr.toast({...}) so it stacks in
	// the page's existing ToastStack (or auto-created one), no extra
	// wiring required. Use ToastTitle / ToastBody / ToastVariant to
	// configure the message; sensible defaults if left blank.
	ToastOnCopy bool

	// ToastTitle is the toast title when ToastOnCopy=true. Default "Copied".
	ToastTitle string

	// ToastBody is the toast body when ToastOnCopy=true. Default empty.
	ToastBody string

	// ToastVariant maps to the toast's variant: "success" (default),
	// "info", "warning", "danger".
	ToastVariant string

	// ToastTTLms is the toast auto-dismiss timeout in milliseconds.
	// Default 3000.
	ToastTTLms int

	// Ctx carries the per-request context used to resolve the
	// Copy/Copied/clipboard labels. When nil, English fallbacks apply.
	Ctx context.Context

	ID    string
	Class string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the root wrapper (the
	// span carrying data-fui-comp). Keys the component owns are
	// dropped: class, id (ID lands on the button, not the wrapper),
	// and data-fui-*.
	ExtraAttrs html.Attrs
}

type CounterConfig struct {
	// SignalName is the signal that holds the count value. Required
	// unless Slice is set.
	SignalName string

	// Slice, when set, supplies both the signal name and the initial
	// value from one typed source (and auto-seeds it). Takes precedence
	// over SignalName.
	Slice *store.Slice[int]

	// Step is the increment/decrement size. Defaults to 1.
	Step int

	// Class is an optional extra CSS class on the wrapper.
	Class string
	// Ctx carries the per-request context used to resolve the Decrement,
	// Increment and Counter group aria labels. When nil, English fallbacks apply.
	Ctx context.Context

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the root element. Keys
	// the component owns are dropped: class (use Class), id, and
	// data-fui-*, plus role=group and the aria-label it derives.
	ExtraAttrs html.Attrs
}

type Crumb struct {
	// Text is the step's visible label. Required.
	Text string
	// Href is the step's destination; empty on the last step.
	Href string
	// Current marks the step as the current page whatever its Href.
	Current bool
}

type DataTableConfig struct {
	// Columns is the column definitions. Required.
	Columns []Column

	// Rows is the rendered rows for the current page.
	Rows []Row

	// Caption is an accessible table caption (optional).
	Caption string

	// CaptionHidden keeps the caption out of sight: the caption still
	// names the table and its scroll region for assistive technology
	// (the region's aria-labelledby resolves to it) but renders
	// visually hidden, for a table that sits under a visible heading
	// saying the same thing. Requires Caption.
	CaptionHidden bool

	// SortBy is the active sort column's Key (optional). Empty means
	// no column is sorted.
	SortBy string

	// SortDir is the active sort direction (asc/desc).
	SortDir SortDir
	// Summary is a sentence about the result window the caller owns,
	// e.g. "Showing 8 of 10". Appended to the sort sentence the
	// table's announcement carries after a sort swap: the table knows
	// the sort, and only the caller knows the window.
	Summary string

	// Path is the screen's own path: each sort href is it plus the
	// carried query, the sort parameters replaced. Empty means the
	// current document — a relative "?query" href.
	Path string

	// Query is the request state sort anchors carry unchanged: the
	// search, the filters, anything a sort must not drop. The
	// primitive replaces SortParam and DirParam in it rather than
	// appending duplicate pairs.
	Query url.Values

	// SortParam and DirParam name the sort key and direction query
	// parameters. Empty defaults to "sort" and "dir".
	SortParam string
	DirParam  string

	// Island is optional. A zero value keeps plain sort anchors; a
	// set value puts the GET RPC contract on those same anchors —
	// the href is still the page without script, the region update
	// with it. The Pagination config inherits the same endpoint and
	// signal automatically.
	//
	// The signal-bound wrapper is the caller's responsibility: wrap
	// the DataTable's rendered HTML in:
	//   <div data-fui-signal="<Signal>" data-fui-signal-mode="html">
	//     {DataTable(...)}
	//   </div>
	Island headless.Island
	// Pagination is an optional *PaginationConfig. When set, the
	// pagination nav renders below the table, outside the scroll
	// region. A table with an Island shares it with the pager, so
	// sort and page hit the same handler and swap the same region.
	Pagination *PaginationConfig

	// Empty is the EmptyState shown when len(Rows) == 0, under the
	// table's head: an empty result still has named columns and
	// usable sort controls. If zero, a default empty state renders.
	Empty EmptyStateConfig

	// Responsive selects how the table behaves when its container is
	// narrow. Default keeps horizontal scroll; ResponsiveCards
	// collapses rows into labeled cards via container queries.
	Responsive ResponsiveMode

	// Ctx carries the per-request context used to resolve i18n
	// strings (empty-state labels, sort aria-labels, pagination
	// labels). When nil, English fallbacks are returned.
	Ctx context.Context

	ID    string
	Class string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the list's root element.
	// Keys the component owns are dropped: class and id (use Class /
	// ID), style, data-fui-* and the data-hui-* hooks.
	ExtraAttrs html.Attrs
}

type DateFieldConfig struct {
	Name        string
	Label       string
	ID          string
	Value       string
	Placeholder string
	Help        string
	Error       string
	Class       string
	Required    bool
	Disabled    bool
	Min         string
	Max         string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers) onto the field's <input>. Keys the input owns
	// are dropped: class and id (use ID), data-fui-*, type, name,
	// value, placeholder, min, max, required, disabled,
	// aria-invalid, and aria-describedby.
	ExtraAttrs html.Attrs
}

type DetailItem struct {
	Label string
	Value render.HTML
}

type DetailListConfig struct {
	Items []DetailItem
	Class string
	// Inline keeps short label/value pairs on one line in narrow panes.
	// Long values wrap within their column instead of moving below the label.
	Inline bool

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the root <dl>. Keys the
	// component owns are dropped: class (use Class), id, style and
	// data-fui-*.
	ExtraAttrs html.Attrs
}

type DiffMode string

type DiffViewerConfig struct {
	// Patch is the raw unified-diff body (required). Lines prefixed
	// "+" are additions, "-" are removals, " " (space) are context,
	// "@@" lines are hunk headers, "---" / "+++" headers are
	// rendered as a filename row.
	Patch string
	// Mode picks unified (default) or split layout.
	Mode DiffMode
	// LeftLabel / RightLabel show above split columns (defaults
	// "Old" / "New").
	LeftLabel  string
	RightLabel string
	ID         string
	Class      string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the root element. Keys
	// the component owns are dropped: class and id (use Class / ID),
	// and data-fui-*.
	ExtraAttrs html.Attrs
}

type DividerConfig struct {
	// Label optionally renders a centered inline label. Common
	// usage: "OR" between two auth options, "Pinned" above the rest
	// of a list. When set, the divider switches from a plain <hr>
	// to a labelled <div role="separator">.
	Label string

	// Orientation selects horizontal (default) or vertical.
	Orientation DividerOrientation

	ID    string
	Class string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the root element (<hr>,
	// or the role=separator div for vertical / labelled shapes).
	// Keys the component owns are dropped: class and id (use Class /
	// ID), style, data-fui-*, role and aria-orientation (use
	// Orientation).
	ExtraAttrs html.Attrs
}

type DividerOrientation string

type EmptyStateConfig struct {
	Title       string      // required
	Description string      // optional supporting text
	Action      render.HTML // optional CTA (e.g. a button or link)
	ID          string
	Class       string

	// HeadingLevel overrides the title's heading level (1–6). Zero defaults
	// to 3 (h3), preserving the gallery/demo behaviour where the empty state
	// nests inside a section. A real page that mounts the empty state as the
	// only content under the page <h1> (e.g. an admin list with zero rows)
	// passes 2 so the outline doesn't skip h1 → h3.
	HeadingLevel int

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the empty state's root.
	// Keys the component owns are dropped: class and id (use
	// Class / ID), style, data-fui-*, role, aria-label and
	// aria-labelledby.
	ExtraAttrs html.Attrs
}

type Facet struct {
	// Name is the form field name: it becomes the URL query key. Required.
	Name string
	// Label is the group's accessible name (the <select> label or the
	// pill <fieldset> legend). Required.
	Label string
	// Options are the choices. Required, at least one.
	Options []FacetOption
	// Value is the currently-active Option.Value (from the URL). Empty
	// selects the "all" choice.
	Value string
	// Kind picks the render mode. FacetSelect (default) or FacetPills.
	Kind FacetKind
	// AllLabel overrides the auto-prepended "all / no filter" choice
	// (value ""). Defaults to "All <Label>" for selects and "All" for
	// pills. Ignored when an Option already declares Value "".
	AllLabel string
}

type FacetKind string

type FacetOption struct {
	// Label is the visible option text. Required.
	Label string
	// Value is the submitted value and the option's stable identifier.
	// A Value of "" is the "no filter / all" choice.
	Value string
}

type FactBoxConfig struct {
	Label string // required short label
	Value string // visible value; mutually exclusive with ValueHTML
	// ValueHTML lets the value contain inline markup (code, links).
	// If non-empty, takes precedence over Value.
	ValueHTML render.HTML
	// Style picks the visual hierarchy. Default FactStyleLabelFirst.
	Style FactStyle
	// FullWidth, when true, marks the box to span the full grid row
	// (the consuming grid still controls the column template).
	FullWidth bool
	ID        string
	Class     string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the fact's root div.
	// Keys the component owns are dropped: class and id (use Class /
	// ID) and data-fui-*.
	ExtraAttrs html.Attrs
}

type FactStyle string

type FieldErrors map[string]string

type FileDropzoneConfig struct {
	// Name is the form-field name (required).
	Name string
	// Label is the accessible label (required, used as the input's
	// aria-label and the visible heading inside the dropzone).
	Label string
	// Prompt overrides the default "Drop files here or click to
	// browse" call-to-action text.
	Prompt string
	// Accept is the MIME-type filter (e.g. "image/*", ".csv").
	Accept string
	// Multiple allows selecting multiple files.
	Multiple bool
	// Required marks the input required.
	Required bool
	// Disabled disables interaction.
	Disabled bool
	// ShowPreview opts into a thumbnail strip rendered below the
	// dropzone after change. Only works for image MIME types: the
	// filedropzone runtime module FileReader-reads each file and
	// emits <img>.
	ShowPreview bool
	// MaxSizeMB is announced in the help text. Server is still
	// authoritative.
	MaxSizeMB int
	// Help renders supporting text under the dropzone.
	Help string
	// Error overrides Help and switches to error state.
	Error string
	ID    string
	Class string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the dropzone's root div.
	// Keys the component owns are dropped: class and id (use Class /
	// ID), data-fui-*, and every data-hui-* key — the drop hooks are
	// the runtime's contract, not a caller's to forge. A retargeted
	// data-hui-drop-input would send every drop on this zone to
	// another input.
	ExtraAttrs html.Attrs

	// Ctx carries the per-request context used to resolve the prompt,
	// the max-size help label and the announcement sentences. When
	// nil, English fallbacks apply.
	Ctx context.Context
}

type FileUploadConfig struct {
	// Name is the form-field name. Required.
	Name string

	// Label is the visible label inside the drop zone. Required.
	Label string

	// ID is the input element's id. Defaults to Name.
	ID string

	// Accept is the MIME-type filter passed to the native input.
	// Example: "image/*", ".pdf,.docx"
	Accept string

	// Multiple allows selecting multiple files.
	Multiple bool

	// Required marks the field as required in form submission.
	Required bool

	// Disabled disables interaction.
	Disabled bool

	// MaxSizeMB, when > 0, is announced in the hint so users
	// understand the constraint. The native input doesn't enforce
	// it; server-side validation must.
	MaxSizeMB int

	// Help renders supporting text inside the drop zone (beside the
	// size hint, joined with " · ").
	Help string

	// Error overrides Help's described-by slot and switches the field
	// to error state: the input is marked aria-invalid and the
	// message renders below the zone as a role="alert" paragraph the
	// input's aria-describedby names.
	Error string

	Class string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the component's root
	// element. Keys the component owns are dropped: class (use
	// Class), id, and data-fui-*.
	ExtraAttrs html.Attrs

	// Ctx carries the per-request context used to resolve the zone's
	// drop sentence and the announcement sentences. When nil, English
	// fallbacks apply.
	Ctx context.Context
}

type FilterChip struct {
	// Label is the visible chip text. Required.
	Label string

	// DismissPath is the POST endpoint that removes this filter on
	// click of the × button. Required.
	DismissPath string

	// DismissBody is an optional static JSON body sent with the
	// dismiss request (data-fui-rpc-body). When empty, the server
	// is expected to deduce the filter from DismissPath alone.
	DismissBody string

	// Variant maps to StatusVariant: defaults to neutral. Use to
	// surface filter kind (info chips for tags, success for "active"
	// status filters, etc).
	Variant StatusVariant
}

type FilterChipBarConfig struct {
	// Filters is the active filter set. Empty renders an empty
	// (but valid) toolbar.
	Filters []FilterChip

	// ClearAllPath, when non-empty, renders a trailing "Clear all"
	// button that POSTs here.
	ClearAllPath string

	// ClearAllLabel overrides the trailing button's text.
	// Default "Clear all".
	ClearAllLabel string

	// Label is the aria-label on the toolbar.
	// Default "Active filters".
	Label string

	// RPCSignal, when set, is broadcast on every chip dismiss AND
	// on Clear all, so the bar swaps itself with the server's
	// re-rendered HTML.
	RPCSignal string

	// SignalName, when set, is also placed on the wrapper as
	// data-fui-signal so the runtime can swap the entire bar from
	// the RPC response. Pair with data-fui-signal-mode="html" on
	// the parent container.
	SignalName string

	// Ctx carries the per-request context used to resolve i18n labels
	// (Clear all / "Remove filter <label>"). When nil, English fallbacks.
	Ctx context.Context

	ID    string
	Class string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the toolbar's root div.
	// Keys the component owns are dropped: class and id (use Class /
	// ID), data-fui-*, role, and aria-label (use Label).
	ExtraAttrs html.Attrs
}

type FilterSearch struct {
	// Name is the form field name (the URL query key). Required.
	Name string
	// Value is the current query text (from the URL).
	Value string
	// Placeholder overrides the default "Search…".
	Placeholder string
	// Label overrides the accessible name (default "Search").
	Label string
}

type FilterToolbarConfig struct {
	// Action is the list route the form GETs to. Required.
	Action string

	// Facets are the filter dimensions, rendered left-to-right and
	// wrapping as width shrinks.
	Facets []Facet

	// Search, when non-nil, renders a search field.
	Search *FilterSearch

	// Sort, when non-empty, renders a labelled sort <select>.
	Sort []SortOption
	// SortName is the sort field's form name. Default "sort".
	SortName string
	// SortValue is the currently-selected sort Value (from the URL).
	SortValue string
	// SortLabel overrides the sort control's label. Default "Sort by".
	SortLabel string

	// ApplyLabel overrides the submit button text. Default "Apply".
	ApplyLabel string
	// ResetLabel overrides the reset link text. Default "Reset".
	ResetLabel string
	// HideReset suppresses the Reset link (e.g. when the caller renders
	// an active-filter chip bar with its own "Clear all").
	HideReset bool
	// Compact keeps search and actions on one row in narrow record lists.
	// Below 18rem the controls still stack so none are clipped.
	Compact bool

	// Label is the toolbar's accessible name (search landmark
	// aria-label). Default "Filters".
	Label string

	// Ctx carries the per-request context used to resolve i18n labels
	// (Filters / Apply / Reset / Sort by / "All <label>" / Search…).
	// When nil, English fallbacks are returned.
	Ctx context.Context

	ID    string
	Class string
	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the toolbar's root <form>.
	// Keys the component owns are dropped: class and id (use Class /
	// ID), data-fui-*, and the form contract (method, action, role,
	// aria-label) — the sanitized Action is never overridable.
	ExtraAttrs html.Attrs
}

type FormConfig struct {
	// Action is the form's action URL. Required. An action the anchor
	// policy refuses is a panic at render, not a silent "#" — a form
	// pointed at a dangerous URL is worse than a no-op, and a dead
	// one is found where it was made.
	Action string

	// Method is "POST" (default) or "GET". This is the NATIVE method,
	// what a scriptless browser submits; the request seam's method
	// (see ExtraAttrs) is independent of it.
	Method string

	// Errors is an optional set of field-level errors. When non-empty
	// the form renders a ValidationSummary above its fields, marked so
	// the headless behaviour module moves focus to the summary after a
	// failed submit — which requires ID (the summary's id is derived
	// from it), and the per-field wiring reaches FormFieldFor'd fields
	// automatically.
	Errors FieldErrors

	// Summary is a sentence that belongs to no one field (a general
	// failure, a credentials mismatch). It renders as a text row in
	// the validation summary, after the field errors. Empty means
	// nothing when Errors is empty, and the framework default
	// ("Please fix the highlighted fields and try again.") when
	// Errors is not.
	Summary string

	// FieldLabels, FieldIDs and FieldOrder are passed to the
	// ValidationSummary: FieldIDs maps a field name to its control's
	// id (a link to #email misses a control whose id is f_email —
	// an error whose field has no known id renders as text, not as an
	// anchor to nothing), FieldLabels supplies each link's label, and
	// FieldOrder fixes the row order.
	FieldLabels map[string]string
	FieldIDs    map[string]string
	FieldOrder  []string

	// SubmitLabel is the visible submit button label. Defaults to "Save".
	SubmitLabel string

	// HideSubmit omits the submit button entirely when true.
	// Use when the caller renders its own submit button.
	HideSubmit bool

	// SubmitFullWidth stacks the actions row into a single full-width
	// column and stretches the submit button to the form's width. Use
	// for mobile-first auth and wizard forms where the primary action
	// should be a thumb target spanning the card.
	SubmitFullWidth bool

	// NoValidate turns off the browser's own validation bubbles, for a
	// form that validates on the server and reports through Errors.
	NoValidate bool

	// Ctx, when non-nil, lets Form auto-stamp the hidden CSRF input
	// (the framework's "_csrf" field) on unsafe-method submits. It
	// reads middleware.TokenFromContext(Ctx), i.e. the token the CSRF
	// middleware stashes on every request, so callers do not have to
	// remember `render.HTML(csrfInput(ctx))` as the first child of
	// every form. Nil-safe: a form rendered without Ctx omits the
	// hidden input (matches pre-v3 behavior so existing tests and
	// non-CSRF flows like Method:"GET" stay correct).
	Ctx context.Context

	ID    string
	Class string
	// ExtraAttrs forwards additional attributes to the <form>
	// element. Every data-fui-* and data-action-* key is runtime
	// wiring and goes through the typed request seam (attach island
	// wiring with interactive.Post(...).OnSuccess(...).Attrs() —
	// headless.FormProps.Request admits exactly that vocabulary and
	// panics on any wiring key outside it, where the old carrier
	// contract silently rendered a plain form that posts natively).
	// Everything else is decoration and passes through.
	ExtraAttrs html.Attrs
}

type FormFieldConfig struct {
	Label    string // required → <label>
	For      string // required → <label for=…> matches the control ID
	Help     string // optional helper text under the field
	Error    string // optional error message; non-empty marks the control invalid
	Required bool   // marks the label and the control

	// Input BUILDS the control from the wiring the field hands it:
	// the id the label points at, the described-by chain, the invalid
	// state and the required flag. It is a builder rather than a
	// pre-built value because the wiring has to reach the control, and
	// a pre-built control is how a hint ends up rendered, given an id,
	// and never referenced — visible on screen and absent to a screen
	// reader. Build the control with ui.Control (any input type), a
	// typed field, ui.PasswordInput (its Field field), or headless
	// directly; a closure that ignores its FieldControl compiles and
	// loses the wiring, which is the one way left to get this wrong.
	Input func(headless.FieldControl) render.HTML

	// ReserveError keeps an empty error paragraph rendered — wired
	// into the control's aria-describedby and found by the id that
	// rides it — for a script that fills it without
	// re-rendering (see headless.FieldProps.ReserveError). The caller
	// that fills it must also set aria-invalid on the control; the
	// server-rendered path should pass Error instead.
	ReserveError bool
	Class        string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers) to the field row's root <div>. Keys the
	// component owns are dropped: class and id (use Class) and
	// data-fui-*.
	ExtraAttrs html.Attrs
}

type FormRepeaterConfig struct {
	// Name is the repeater group name (used as prefix for field
	// indexing). Required.
	Name string

	// Items is the current list of rendered item groups.
	// Each item is a slice of render.HTML representing one row's fields.
	Items [][]render.HTML

	// MinItems prevents removal below this count. Default 0.
	MinItems int

	// MaxItems prevents addition above this count. Default 0 = unlimited.
	MaxItems int

	// AddLabel is the "Add" button text. Default "Add item".
	AddLabel string

	// RemoveLabel is the "Remove" button text. Default "Remove".
	RemoveLabel string

	Class string

	// ExtraAttrs forwards additional attributes to the repeater's
	// root div. Keys the component owns are dropped: class and id
	// (use Class), data-fui-*, aria-label, and aria-live.
	ExtraAttrs html.Attrs

	// Ctx carries the per-request context used to resolve i18n labels
	// (Add / Remove). When nil, English fallbacks apply.
	Ctx context.Context
}

type FormSectionConfig struct {
	Heading     string // optional
	Description string // optional
	Class       string
	// ID names the group and roots the description's id (<ID>-desc).
	// Without one the id is derived from Heading, so two sections
	// with one heading and a description on a page would share it:
	// give the second an ID.
	ID string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers) to the group's root element, whichever shape
	// it takes (<div> without a Heading, <fieldset> with one). Keys
	// the component owns are dropped: class and id (use Class) and
	// data-fui-*.
	ExtraAttrs html.Attrs
}

type GalleryCaptionMode string

type GalleryConfig struct {
	// Variant picks the surface layout.
	Variant GalleryVariant
	// Items are the entries (≥1).
	Items []GalleryItem
	// Label is the accessible label for the gallery list. Defaults
	// to "Image gallery".
	Label string
	// Columns (Grid mode): the MAXIMUM number of columns. Default 3.
	// The grid is responsive: tracks never shrink below --ui-gallery-min
	// (default 9.5rem, overridable per instance via a Class), so narrow
	// viewports automatically get fewer columns without media queries.
	// Masonry mode: uses this as the maximum column count too.
	Columns int
	// Gap between thumbs. Default GapMD.
	Gap Gap
	// Lightbox, when non-empty, is the Name of a paired
	// framework/ui.Lightbox. Each item becomes a trigger for that
	// lightbox via data-fui-open + data-fui-deeplink.
	Lightbox string
	// HrefFn, when set, returns a per-item destination URL. Ignored
	// when Lightbox is set.
	HrefFn func(i int, it GalleryItem) string
	// CaptionMode controls caption rendering. Default Below.
	CaptionMode GalleryCaptionMode
	// ID / Class are passed through to the wrapper.
	ID    string
	Class string
	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the gallery's root <ul>.
	// Keys the component owns are dropped: class and id (use Class /
	// ID), data-fui-*, and aria-label (use Label).
	ExtraAttrs html.Attrs
}

type GalleryItem struct {
	// Src is the full-resolution image URL (required).
	Src string
	// Thumb is the thumbnail URL. Defaults to Src.
	Thumb string
	// Alt is the accessible image description (required: empty Alt
	// is rejected at render time to surface omissions).
	Alt string
	// Caption is optional descriptive text shown per CaptionMode.
	Caption string
	// Width / Height for the thumbnail (CLS-safe). Default 200×150.
	Width  int
	Height int
}

type GalleryVariant string

type Gap string

type GlobalSearchConfig struct {
	// ID is the input element id (the listbox takes <ID>-listbox).
	// Required, page-unique.
	ID string
	// Name is the form-submit name on the input. Required.
	Name string
	// Label is the visible label text (required, used as <label for=…>;
	// visually hidden by the bar's shape).
	Label string
	// RPCPath is the search endpoint. Required. POSTed with the query
	// in `<Name>=<value>`; the listbox re-renders through the signal.
	RPCPath string
	// SignalName is the rpc-signal value used to swap the listbox HTML
	// after each search response. Required.
	SignalName string
	// NoScriptAction is the same-origin GET destination the wrapping
	// form submits to without script. Required: a reader without
	// script must still reach the results page. `#` is refused.
	NoScriptAction string
	// Placeholder for the input. Default "Search…".
	Placeholder string
	// Shortcut, when set, opts the input into runtime focus-on-key:
	// `data-hui-shortcut-focus="<chord>"` (default "/"). Pass an
	// explicit empty string to disable.
	Shortcut string
	// ShowHint renders a small "Press <chord>" hint chip on the right
	// of the input. Default true when Shortcut is set.
	ShowHint *bool
	// DebounceMs is the input debounce window. Default 200.
	DebounceMs int
	// Sticky toggles position: sticky on the wrapper. Default true.
	Sticky bool
	Class  string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the search bar's root
	// wrapper. Keys the component owns are dropped: class, the
	// data-hui-* wiring, and the shortcut chords.
	ExtraAttrs html.Attrs

	// Ctx carries the per-request context used to resolve i18n labels
	// (placeholder, the combobox's sentences). When nil, English
	// fallbacks apply.
	Ctx context.Context
}

type GridConfig struct {
	// Min is the minimum column width (e.g. "20rem"). The grid uses
	// `repeat(auto-fit, minmax(<Min>, 1fr))` so columns wrap at the
	// breakpoint implied by the minimum. Defaults to "16rem".
	Min   string
	Gap   Gap
	ID    string
	Class string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the grid's root <div>.
	// Keys the component owns are dropped: class and id (use Class /
	// ID), style, data-fui-*, data-hui-* and data-min (use Min).
	ExtraAttrs html.Attrs
}

type HeaderInfo struct {
	Name   string
	Width  int
	Height int
	MIME   string
}

type HeroConfig struct {
	// Eyebrow is an optional short kicker rendered as an accent pill above
	// the title (e.g. "Billing & revenue").
	Eyebrow string
	// Title is the display headline (rendered as the page <h1>).
	Title string
	// Subtitle is the supporting lede under the title.
	Subtitle string
	// Actions are the call-to-action elements (usually ui.LinkButton),
	// laid out in a wrapping row beneath the lede.
	Actions []render.HTML
	// Media is an optional visual rendered beside the copy. When set, the
	// hero becomes a two-column split; when empty it's a single column.
	Media render.HTML
	// AriaLabel names the hero <section>. Defaults to the Title.
	AriaLabel string
	// Class is appended to the ui-hero wrapper.
	Class string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the hero's root <section>.
	// Keys the component owns are dropped: class and id (use Class),
	// data-fui-*, and aria-label (use AriaLabel).
	ExtraAttrs html.Attrs
}

type HeroSplitConfig struct {
	// Copy is the left column body (title, lede, CTAs).
	Copy render.HTML
	// Media is the right column body (code, image, stats).
	Media render.HTML
	// Ratio picks the column split. Defaults to HeroSplitEqual.
	Ratio HeroSplitRatio
	// AriaLabel labels the <section> for screen readers (the hero is
	// almost always the page-opening landmark). Required unless an
	// h1 inside Copy provides the accessible name.
	AriaLabel string
	// Class is appended to the ui-hero-split wrapper.
	Class string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the hero's root <section>.
	// Keys the component owns are dropped: class and id (use Class),
	// data-fui-*, and aria-label (use AriaLabel).
	ExtraAttrs html.Attrs
}

type HeroSplitRatio string

type IconConfig struct {
	// Size sets the rendered width/height. Accepts any CSS length
	// (e.g. "20", "1.25rem"). Default: "20".
	Size string

	// AriaLabel makes the icon meaningful to assistive tech. When set,
	// the SVG renders with role="img" and aria-label="<AriaLabel>";
	// without it, the icon is aria-hidden="true" (decorative).
	AriaLabel string

	ID    string
	Class string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the icon's root <svg>
	// element. Keys the component owns are dropped: class and id
	// (use Class / ID), data-fui-*, and the drawing / accessibility
	// keys the component derives (xmlns, width, height, viewBox,
	// fill, stroke*, role, aria-label, aria-hidden).
	ExtraAttrs html.Attrs
}

type ImageAspect string

type ImageFit string

type ImageSource struct {
	URL   string // image URL: required
	Width int    // intrinsic pixel width: required (becomes "<url> <width>w")
}

type InputGroupConfig struct {
	// Prepend is optional content rendered before the input (text, icon, etc.).
	Prepend render.HTML
	// Input is the actual input element (required). Inside a
	// FormField builder, build it from the wiring the field handed
	// the closure — ui.Control, a typed control, or headless directly
	// — so the id and the description chain arrive with it.
	Input render.HTML
	// Append is optional content rendered after the input.
	Append render.HTML
	// Class adds extra CSS classes to the wrapper.
	Class string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the group's root wrapper
	// div. Keys the component owns are dropped: class and id (use
	// Class) and data-fui-*.
	ExtraAttrs html.Attrs
}

type JSONViewerConfig struct {
	// Value is the data to render (required).
	Value any
	// OpenDepth is the recursion depth that renders open by default.
	// 0 means just the root is open; -1 means everything is open.
	OpenDepth int
	// MaxStringLen truncates long strings with "…". 0 = no limit.
	MaxStringLen int
	ID           string
	Class        string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the viewer's root <div>.
	// Keys the component owns are dropped: class and id (use Class /
	// ID) and data-fui-*.
	ExtraAttrs html.Attrs
}

type Justify string

type LightboxConfig struct {
	// Name is the unique widget name (required) used as the
	// preset.Modal name. Page-unique. Any element with
	// data-fui-open="<this Name>" opens the overlay.
	Name string
	// Label is the accessible name for the open modal. Defaults to
	// "Image viewer" (i18nui.KeyLightboxLabel through the strings
	// bridge).
	Label string
	// NavArrows renders Prev/Next buttons inside the modal AND wires
	// ArrowLeft/Right keyboard nav over siblings sharing the same
	// data-fui-lightbox-group attribute.
	NavArrows bool
	// ShowCaption adds a <figcaption> bound to the "caption" signal.
	// Triggers pass caption=<text> in their data-fui-deeplink.
	ShowCaption bool
	// AllowDownload renders a visible "Download" anchor inside the
	// modal whose href is bound to the current src signal.
	AllowDownload bool
	// Pages, when non-empty, scopes the modal mount to those routes.
	Pages []string

	// Ctx carries the per-request context used to resolve i18n strings
	// (the viewer label, Prev/Next nav and Download aria-labels) through
	// the strings bridge. When nil, context.Background() is used and
	// English fallbacks are returned, preserving today's behaviour.
	Ctx context.Context

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) onto the lightbox's own root
	// (the fui-lightbox viewer panel; the modal chrome is widget
	// machinery, and triggers are caller-owned elements). Keys the
	// component owns are dropped: class, id, data-fui-* (the viewer and
	// nav wiring) and data-hui-* (the headless anatomy's hooks).
	ExtraAttrs html.Attrs
}

type LineChartConfig struct {
	// Series are the lines (≥1, each with ≥2 Values).
	Series []LineSeries
	// Labels are optional x-axis tick labels. When non-empty, must
	// match the length of the longest series.
	Labels []string
	// Width / Height in CSS pixels. Default 360×200.
	Width  int
	Height int
	// ShowLegend renders a small legend strip below the chart.
	ShowLegend bool
	// LabelledBy is the id of an element naming the chart for AT.
	LabelledBy string
	ID         string
	Class      string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the chart's root <svg>
	// element, or to the shared zero-data placeholder when there is
	// nothing to draw. Keys the component owns are dropped: class and id
	// (use Class / ID), data-fui-*, and the geometry / accessibility
	// keys the chart derives (width, height, viewBox, xmlns, role,
	// aria-labelledby, aria-hidden).
	ExtraAttrs html.Attrs
}

type LineRange struct {
	From int
	To   int
}

type LineSeries struct {
	// Name is the legend label (required).
	Name string
	// Values are the y-values in order.
	Values []float64
	// Color overrides the default palette pick. Optional palette key
	// or raw CSS color.
	Color string
	// Area, when true, fills under the line.
	Area bool
}

type LinkButtonConfig struct {
	Label   string        // required visible text
	Href    string        // required navigation target
	Variant ButtonVariant // defaults to ButtonPrimary
	Size    ButtonSize    // defaults to ButtonSizeDefault
	// External, when true, opens the link in a new tab with
	// rel="noopener noreferrer". Use for off-site links (docs to
	// GitHub, pkg.go.dev, etc.). The runtime's SPA-nav interceptor
	// naturally skips http(s):// hrefs (they're not "internal"), so
	// External does not also need to "suppress SPA nav": the
	// underlying SPA router already does the right thing.
	External bool
	// Icon, when set, renders the named registered icon (see
	// RegisterIcon / Icon) before the label. The button's inline-flex
	// gap handles spacing. Unknown names render the label alone.
	Icon  string
	ID    string
	Class string
	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the rendered <a>. The
	// four data-fui-* keys that make sense on a link (push-state,
	// prefetch, open, deeplink) go through the typed Action seam;
	// every other data-fui-* key is refused, as it always was — a
	// link navigates, a button acts. Keys the component owns are
	// dropped: class and id (use Class / ID) and href (use Href).
	// With External, target and rel are owned too; without it a caller
	// may still set them.
	ExtraAttrs html.Attrs
}

type LinkConfig struct {
	Href    string // required
	Text    string // required visible text
	Variant LinkVariant
	Class   string
	ID      string
	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the rendered <a>. Link is
	// a wiring carrier: data-fui-* passes through, which is how a
	// progressive-enhancement link ships an href fallback plus a
	// data-fui-rpc upgrade (uinoderender's ActionRef links). Keys the
	// component owns are dropped: class and id (use Class / ID) and
	// href (use Href). on* event handlers and values with control
	// bytes are also scrubbed (see scrubAttrs).
	ExtraAttrs html.Attrs
}

type LinkVariant string

type ListDetailConfig struct {
	// List is kept chrome in a group layout, not a per-route outlet.
	List render.HTML
	// ListLabel labels the independently scrolling list. Required.
	ListLabel string
	// Detail is the group's primary slot, replaced on detail navigation.
	Detail render.HTML
	// MobileSinglePane shows either list or detail on phones instead of
	// stacking them. Render ListDetailPlaceholder for the index screen.
	MobileSinglePane bool
	// BackHref adds a link back to the list at the top of the detail
	// pane. It shows only while the detail pane is alone: a phone, with
	// a selected detail (not ListDetailPlaceholder). It sits outside
	// Detail, so it survives detail navigation. Requires MobileSinglePane.
	BackHref string
	// BackLabel is the back link's text. Default "Back".
	BackLabel string
	// ExtraAttrs forwards safe data-* and ARIA attributes to the root.
	// LayoutTree.VTRegion's two transition attributes are also accepted.
	ExtraAttrs html.Attrs
}

type MarkdownConfig struct {
	// Source is the raw markdown text (required).
	Source string
	// Compact tightens spacing, useful for inline previews where
	// hero-page paragraph rhythm would feel wrong.
	Compact bool
	// Measure caps the line length at a reading width
	// (--ui-markdown-measure, 72ch) for long-form pages: about, terms,
	// an explanatory paragraph in a wide page column.
	Measure bool
	ID      string
	Class   string
	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the prose container's
	// root <div>. Keys the component owns are dropped: class and id
	// (use Class / ID) and data-fui-*.
	ExtraAttrs html.Attrs
}

type MenuAction struct {
	// Path is the form's action URL.
	Path string

	// Method defaults to POST. GET is allowed for completeness but
	// defeats the point; prefer Href for navigations.
	Method string

	// Fields are the hidden inputs, first use: the CSRF token.
	Fields map[string]string

	// Unsafe acknowledges the no-Fields case deliberately.
	Unsafe bool
}

type MenuConfig struct {
	// ID becomes the dropdown's stable identifier. Used to pair the
	// trigger with the panel for aria-controls + analytics. Optional
	// auto-generated when empty.
	ID string

	// Label is the trigger's visible text. Mutually exclusive with
	// TriggerHTML.
	Label string

	// TriggerHTML overrides Label with custom inline HTML. Use for
	// avatar buttons, icon-only triggers, etc.
	TriggerHTML render.HTML

	// TriggerElement replaces the framework-rendered summary with a
	// caller-owned interactive element: inline HTML for a real <button>
	// (or <a>). The menu renders a summary-less disclosure holding the
	// panel, with the element in a presentation wrapper beside it, and
	// the runtime makes the element the disclosure controller: click,
	// Enter, and Space toggle the panel; aria-haspopup /
	// aria-controls / aria-expanded are wired onto the element at
	// hydration (attributes cannot be injected into raw caller HTML
	// server-side); focus lands on the first menuitem on open; Escape
	// closes one level at a time and returns focus to the element; Tab
	// closes the chain. Use for host-styled triggers whose markup and
	// classes the page owns: routing such an element through
	// TriggerHTML nests an interactive control inside the summary
	// control, which axe reports as nested-interactive (SERIOUS).
	// Activation is preventDefaulted — the element opens the menu, it
	// does not navigate or submit; put navigation on menu items.
	// Overrides Label and TriggerHTML. Auto-generated IDs fold the
	// markup in, but two structurally identical trigger menus on one
	// page still need distinct IDs.
	TriggerElement render.HTML

	// Items is the menu's contents. Required (empty menus panic at
	// render time. They signal a bug, not a runtime state).
	Items []MenuItem

	// Position anchors the panel relative to the trigger.
	Position MenuPosition

	// LazyPanel keeps the panel's rows out of the document tree until
	// the menu is first opened: SSR wraps them in an inert
	// <template data-hui-menu-lazy> as the panel's only child, and the
	// menu module moves them into the panel on first open (the panel
	// <div> itself always renders, so aria-controls still resolves
	// while closed). Use it when page-scoped consumers must not see
	// closed-menu rows in the live DOM: host test contracts that pin
	// getByText('Theme') to a visible element or getByLabel to exactly
	// one. The rows are still in the HTML source, so this hides
	// nothing from a crawler that parses the response. The cost: rows
	// are not in the DOM until first open, so host JS that binds rows
	// by id at page load must use delegated listeners instead, and
	// with JavaScript disabled the menu opens empty (only the module
	// mounts the rows). The zero value (false) renders rows inline
	// exactly as before. Applies to the summary path and
	// TriggerElement alike; nested submenus live inside the template
	// and mount with the rest.
	LazyPanel bool

	// TriggerClass / PanelClass append to the rendered element class
	// lists (rare).
	TriggerClass string
	PanelClass   string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the menu's root element
	// (the <details> on the summary path, the wrapper <div> when
	// TriggerElement is set). Keys the component owns are dropped:
	// class, id, and the disclosure/menu wiring.
	ExtraAttrs html.Attrs
}

type MenuItem struct {
	// Label is the item's visible text. Required unless Separator.
	Label string

	// Href turns the item into an <a> link. Mutually exclusive with
	// custom action attrs; if both are supplied, Href wins.
	Href string

	// RPC + RPCMethod wire the item to a server-side handler via
	// data-fui-rpc / data-fui-rpc-method. Use for "Delete this row"
	// menu items.
	RPC, RPCMethod string

	// Confirm asks the user to confirm before the RPC fires. Maps to
	// data-fui-confirm, which the runtime honors on RPC dispatch and on
	// any form submit. A menu item is neither unless it carries RPC, so
	// on a plain link item the attribute is inert.
	Confirm string

	// Icon is rendered to the left of Label. Inline HTML; caller
	// supplies an <svg>, character, or render.Text("⚙").
	Icon render.HTML

	// Variant tints destructive items (red), purely a visual hint;
	// the actual confirm step is Confirm above.
	Danger bool

	// Disabled greys the item out and removes it from keyboard
	// navigation.
	Disabled bool

	// Separator renders a horizontal divider instead of an item.
	// Label and other fields are ignored when true.
	Separator bool

	// ID becomes the rendered row's id attribute, so page JS, test
	// suites, or aria wiring elsewhere on the page can address this
	// exact item (a Help Mode toggle a script binds to, an Imports
	// row a shortcut targets). Uniqueness is caller-owned within one
	// menu, like any HTML id: the menu refuses duplicates it can see.
	// Ignored on separators, like every other field. Empty emits no
	// id, leaving the output identical to a menu that never set it.
	ID string

	// Radio, when non-empty, renders the row as a radio option:
	// role="menuitemradio" plus aria-checked (see Checked) and
	// data-hui-menu-radio="<Radio>". Every item sharing the same Radio
	// value within one Menu forms a radio group — across submenus too:
	// a picker whose rarer options sit behind a "More" submenu is one
	// group, not two. Exactly one of them should carry Checked (like
	// ID, uniqueness is caller-owned, not enforced here). The runtime's
	// menu module arbitrates the group client-side on activation
	// (click / Enter / Space): the activated row is checked, its
	// same-group siblings — anywhere in the same menu — unchecked, so
	// pure-client menus feel like radios without a round trip; a row
	// carrying RPC or Href still fires it and the server re-render
	// stays authoritative. Mutually exclusive with Children (a radio
	// row is a leaf command, a submenu parent is a disclosure) — both
	// set panics at render time. Empty renders the plain menuitem, so
	// zero-value output is unchanged.
	Radio string

	// Checked sets aria-checked on a Radio row. Inert without Radio
	// (like Confirm without RPC): there is no checked state to render
	// on a plain menuitem.
	Checked bool

	// Action renders the row as a form submission instead of a link or
	// RPC, for hosts whose command rows hit PRG endpoints (stop
	// impersonation, sign out with server-side sessions) where a plain
	// Href would widen a state-changing endpoint to GET. Nil (the zero
	// value) renders nothing — Action is a pointer exactly so the
	// unconfigured case cannot half-render. See MenuAction for the
	// CSRF contract. Mutually exclusive with Href, RPC, Radio, and
	// Children: incoherent combos panic at render time.
	Action *MenuAction

	// Children nests a submenu behind this row: the row renders as a
	// <summary role="menuitem" aria-haspopup="menu"> whose activation
	// reveals a nested role="menu" panel, reusing the same disclosure
	// machinery the top level uses (Escape, SPA-nav close,
	// aria-expanded mirroring, focus-on-open). Keyboard: the menu
	// module opens it on ArrowRight (ArrowLeft in RTL) and enters,
	// closes it on ArrowLeft (ArrowRight in RTL) and ArrowUp-style
	// roving focus applies inside it; Escape closes one level at a
	// time. The parent row is purely a disclosure: setting Href, RPC,
	// or Radio on it panics at render time. Disabled greys the row out
	// and removes it from keyboard navigation like any other item; the
	// children still render (closed, unreachable) so a server-side
	// state change only needs to flip Disabled.
	Children []MenuItem

	// Class appends to the rendered item's class list (rare; mainly
	// for testing or one-off hooks).
	Class string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) onto the rendered item
	// element. Keys the item owns are dropped: class (use Class),
	// id (use ID), the runtime wiring (data-fui-*), and the menuitem
	// contract (type, href, tabindex, role, aria-disabled, disabled,
	// aria-checked).
	ExtraAttrs map[string]string
}

type MenuPosition string

type MetricBandConfig struct {
	Items []MetricBandItem
	Label string
	ID    string
	Class string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers) to the band's root <dl> element. Keys the
	// component owns are dropped: class and id (use Class / ID),
	// data-fui-*, and aria-label (derived from Label).
	ExtraAttrs html.Attrs
}

type MetricBandItem struct {
	Label string
	Value string
	Hint  string
}

type MultiSelectConfig struct {
	// Name is the form-field name every checkbox shares. Required.
	Name string
	// Label is the group's accessible name and the disclosure's
	// summary. Required.
	Label string
	// Placeholder is what the chips strip says when nothing is
	// picked. Defaults to "Choose…" through the Strings table.
	Placeholder string
	// Options are the choices, in order. Required.
	Options []MultiSelectOption
	// Open renders the disclosure expanded.
	Open bool

	ID    string
	Class string
	// ExtraAttrs forwards additional attributes to the wrapper. Keys
	// the component owns are dropped: class and id (use Class / ID).
	ExtraAttrs html.Attrs

	// Ctx resolves the Strings table through the request's translator.
	Ctx context.Context
}

type MultiSelectOption = headless.MultiSelectOption

type NetworkRetryBannerConfig struct {
	// HealthEndpoint is the URL the Retry button pings to test
	// connectivity. Must return 2xx when the server is healthy.
	// Required.
	HealthEndpoint string

	// Title is the banner heading. Default "Connection lost".
	Title string

	// Description is the body text. Default explains the recovery
	// action.
	Description string

	// RetryLabel is the retry button text. Default "Retry now".
	RetryLabel string

	ID    string
	Class string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the banner's root element.
	// Keys the component owns are dropped: class and id (use Class /
	// ID), data-fui-*, role, aria-live, and hidden (the runtime
	// un-hides the banner when connectivity degrades).
	ExtraAttrs html.Attrs
}

type NotificationBellConfig struct {
	// Name is the unique widget name (required) used for the paired
	// preset.Popover. Keep page-unique.
	Name string
	// Href is where the trigger goes without script: the
	// notifications page, same-origin. Required — a bell that rings
	// to nowhere is a dead link on the no-script page, and "#" is
	// not a destination.
	Href string
	// Label is the accessible label on the bell button (required,
	// e.g. "Notifications").
	Label string
	// UnreadCount renders as a badge on the bell. Hidden when 0
	// (unless SignalUnread is set, then the badge always renders
	// and the signal drives its visibility / text).
	UnreadCount int
	// Items are the entries rendered inside the popover. ≥1 recommended;
	// 0 renders the EmptyText placeholder.
	Items []NotificationItem
	// EmptyText is shown when Items is empty. Default
	// "No new notifications".
	EmptyText string
	// SignalUnread, when non-empty, binds the badge text to that
	// signal name so live updates can swap the count without a page
	// reload. The badge always renders when this is set (signal value
	// "" hides it via the empty-state CSS rule).
	SignalUnread string
	// SignalList, when non-empty, binds the popover list HTML to that
	// signal so live updates can swap the list. Items above seed the
	// SSR initial render.
	SignalList string
	// Pages, when non-empty, scopes the popover mount to those routes.
	Pages []string
	// Ctx carries the per-request context used to resolve the
	// empty-state text. When nil, English fallbacks apply.
	Ctx context.Context

	ID    string
	Class string
	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the bell's root <button>.
	// Keys the component owns are dropped: class and id (use Class /
	// ID), data-fui-* (the popover wiring), type, aria-label (use
	// Label), and aria-describedby (the unread-count announcement).
	ExtraAttrs html.Attrs
}

type NotificationConfig struct {
	// Title is the prominent first line. Required.
	Title string

	// Body is optional supporting text below the title.
	Body string

	// Variant colors the leading icon and accent rail. Defaults to Info.
	Variant StatusVariant

	// DismissHref optionally adds a × link with this href. Pair with a
	// server-side handler that removes the notification from session
	// state. Empty omits the dismiss control.
	DismissHref string

	// DismissLabel overrides the dismiss link's accessible label.
	// Defaults to "Dismiss notification".
	DismissLabel string

	// Position pins the notification to a screen corner via fixed
	// positioning. Defaults to NotificationInline (in document flow).
	Position NotificationPosition

	// Island is where the dismiss goes with script: a dismissing
	// toast changes the stack, which is an in-page state change and
	// needs the endpoint that renders the region again. Required by
	// the primitive when DismissHref is set; without script the same
	// link navigates to DismissHref.
	Island headless.Island

	// Ctx carries the per-request context used to resolve the
	// dismiss-label string. When nil, English fallbacks apply.
	Ctx context.Context

	ID    string
	Class string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the notification's root
	// element. Keys the component owns are dropped: class and id
	// (use Class / ID), data-fui-*, role, and aria-live.
	ExtraAttrs html.Attrs
}

type NotificationItem struct {
	// Title is the headline (required, e.g. "Build #4821 failed").
	Title string
	// Body is optional supporting text.
	Body string
	// Time is an optional right-aligned timestamp string ("2m ago").
	Time string
	// Href, when set, makes the entire row a link.
	Href string
	// Unread marks the row with a left-edge primary stripe.
	Unread bool
}

type NotificationPosition string

type NumberFieldConfig struct {
	Name        string
	Label       string
	ID          string
	Value       string
	Placeholder string
	Help        string
	Error       string
	Class       string
	Required    bool
	Disabled    bool
	Min         *float64
	Max         *float64
	Step        *float64

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers) onto the field's <input>. Keys the input owns
	// are dropped: class and id (use ID), data-fui-*, type, name,
	// value, placeholder, min, max, step, required, disabled,
	// aria-invalid, and aria-describedby.
	ExtraAttrs html.Attrs
}

type NumberInputConfig struct {
	// Name is the form-field name (required).
	Name string
	// Label is the accessible label (required, used as <label for=…>).
	Label string
	// Min / Max bound the value. When both 0, no client-side bound is
	// applied (server is still authoritative). When either is set, Min
	// is a real floor even at 0 (Max: 10 means 0..10); a caller that
	// allows negatives sets Min explicitly. Max is emitted only when
	// non-zero, so Min: 1 alone never fabricates an empty 1..0 range.
	Min int
	Max int
	// Step is the +/- button granularity. Default 1.
	Step int
	// Value is the initial value.
	Value int
	// Disabled disables interaction.
	Disabled bool
	// Required marks the field required.
	Required bool
	// Help renders supporting text under the field.
	Help string
	// Error overrides Help with an error message.
	Error string
	ID    string
	Class string
	// ExtraAttrs forwards additional attributes to the root element.
	// Keys the component owns are dropped: class and id (use Class /
	// ID), data-fui-*, and every data-hui-* hook.
	ExtraAttrs html.Attrs
	// Ctx carries the per-request context used to resolve the Decrement
	// and Increment aria labels. When nil, English fallbacks apply.
	Ctx context.Context
}

type OptimisticActionConfig struct {
	// Endpoint is the URL the click fires against. Required.
	Endpoint string

	// Method is "POST" (default), "DELETE", "PATCH", or "PUT".
	Method string

	// IdleLabel is the button text in the rest state. Required.
	IdleLabel string

	// SuccessLabel is shown immediately on click (the optimistic
	// flip). Required.
	SuccessLabel string

	// IdleIcon optionally renders alongside IdleLabel.
	IdleIcon render.HTML

	// SuccessIcon optionally renders alongside SuccessLabel. Common
	// usage: a small check or filled-heart SVG.
	SuccessIcon render.HTML

	// Variant maps to the standard Button variant ("primary"/""
	// default, "secondary", "danger", "ghost").
	Variant ButtonVariant

	// Size maps to the standard Button size ("" default, "small",
	// "large").
	Size ButtonSize

	ID    string
	Class string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the button's root
	// element. Keys the component owns are dropped: class and id
	// (use Class / ID), data-fui-* (endpoint and method wiring),
	// type, and data-state — the optimistic lifecycle contract.
	ExtraAttrs html.Attrs

	// FailedText is what the status span announces when the server
	// refuses. Empty takes the Strings default.
	FailedText string
	// Ctx carries the per-request context used to resolve the
	// failure sentence. When nil, English fallbacks apply.
	Ctx context.Context
}

type OptimizedImageConfig struct {
	Src string // fallback / single-resolution URL (required)
	Alt string // alt text: required for non-decorative images

	// Width and Height are the intrinsic pixel dimensions of the
	// fallback Src. Setting them is mandatory to reserve layout space
	// and avoid Cumulative Layout Shift on first paint.
	Width  int
	Height int

	// Sources, when set, render alongside Src in a <picture> via
	// srcset="<url> <width>w, …". The browser picks the best size for
	// the viewport.
	Sources []ImageSource

	// Sizes is the CSS sizes attribute for the responsive source set.
	// Defaults to "100vw" when Sources is non-empty.
	Sizes string

	// Eager flips loading="lazy" → loading="eager". Use for
	// above-the-fold hero images.
	Eager bool

	// HighPriority sets fetchpriority="high" (above-the-fold critical
	// imagery). Mutually exclusive with Eager=false; setting both
	// keeps both behaviors.
	HighPriority bool

	// Fit selects the object-fit treatment (default cover).
	Fit ImageFit

	// Aspect locks the aspect ratio via a CSS class (CSP-clean,
	// no inline style). Setting Width + Height already establishes
	// the intrinsic ratio; Aspect is for forced ratios distinct from
	// the source.
	Aspect ImageAspect

	// Rounded toggles a token-driven border-radius treatment.
	Rounded bool

	// Placeholder, when set to an inline raster data: URI, renders a
	// low-fidelity image behind this one so something content-shaped is
	// visible before the real pixels arrive.
	//
	// Produce one with framework/image: BlurHashDataURL(hash, …) to render
	// a stored BlurHash, or Image.Placeholder() to build an LQIP straight
	// from the source. A bare BlurHash string is not accepted: it is not
	// an image until it is decoded.
	//
	// Values that are not usable inline images (a raw hash, a remote URL,
	// a non-raster data: URI) are dropped and the image renders without a
	// placeholder. See placeholderImage for why that degrades instead of
	// panicking.
	Placeholder string

	ID    string
	Class string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the image's root wrapper
	// (the outer <span>, in both the single-source and <picture>
	// shapes). Keys the component owns are dropped: class and id
	// (use Class / ID) and data-fui-*.
	ExtraAttrs html.Attrs
}

type PageHeaderConfig struct {
	Title    string      // required
	Subtitle string      // optional supporting text below the title
	Eyebrow  string      // optional small label above the title (e.g. "Customers")
	Actions  render.HTML // optional trailing action slot (button row, link)
	Badge    render.HTML // optional status beside the title; wraps below when needed
	// HeadingLevel overrides the title's heading level (default 1). Set to
	// 2 when the header is a sub-section of a page that already has an <h1>
	// (e.g. a related-list block on a detail page) so the outline doesn't
	// produce a second <h1> or skip levels.
	HeadingLevel int
	Class        string
	ID           string
	// Compact removes the divider and outer padding for pane and article titles.
	Compact bool

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the header's root <header>
	// element. Keys the component owns are dropped: class and id
	// (use Class / ID), style, data-fui-* and role.
	ExtraAttrs html.Attrs
}

type PaginationConfig struct {
	// Page is the current page, 1-based. Must be within 1..Pages.
	Page int
	// Pages is the total number of pages. At least 1.
	Pages int

	// Path is the screen's own path: each page href is it plus the
	// carried query, the page parameter replaced. Empty means the
	// current document — a relative "?query" href.
	Path string
	// Query is the request state the page anchors carry unchanged:
	// the search, the filters, the sort — anything a page turn must
	// not drop. The primitive replaces PageParam in it rather than
	// appending duplicate pairs.
	Query url.Values
	// PageParam names the page query parameter. Empty defaults to "p".
	PageParam string

	// Window is the number of pages shown each side of the current
	// one, the first and last always shown. Default 1; a Window large
	// enough shows every page.
	Window int
	// OmitPrevNext drops the Previous and Next anchors entirely.
	OmitPrevNext bool

	// AriaLabel names the nav landmark for AT. Empty resolves to the
	// reader's "Pagination" through the i18n keys.
	AriaLabel string
	// PrevLabel and NextLabel override the end anchors' words, which
	// otherwise resolve through the i18n keys.
	PrevLabel string
	NextLabel string

	// Island is optional. A zero value keeps plain page anchors —
	// the URL is the truth for a list, and a list screen's pager is
	// list state. A set value puts the GET RPC contract on those same
	// anchors, for a pager embedded in an island region (a
	// DataTable's footer under an island table): the href is still
	// the page without script, the region update with it.
	Island headless.Island

	// Ctx carries the per-request context used to resolve the i18n
	// strings (the nav label, the end anchors' words). When nil,
	// English fallbacks are returned.
	Ctx context.Context

	ID    string
	Class string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the nav landmark. Keys
	// the component owns are dropped: class and id (use Class / ID),
	// style, data-fui-* and the data-hui-* hooks.
	ExtraAttrs html.Attrs
}

type PaletteCommand struct {
	Label string // visible text
	Href  string // route to navigate to on pick (data-fui-push-state)
	Meta  string // optional muted secondary text (e.g. the route path)
}

type PaneHostConfig struct {
	// Primary is the always-visible main pane. Required: PaneHost
	// panics when it is empty (mirrors DataTable's required slots).
	Primary render.HTML
	// Secondary is the first optional side pane. When empty, no
	// secondary pane is rendered.
	Secondary render.HTML
	// Tertiary is the second optional side pane.
	Tertiary render.HTML

	// SecondaryOpen / TertiaryOpen set the SSR initial open state so
	// the first paint matches server state (Hard Rule 6), e.g. a
	// detail route that should render with the pane already shown. A
	// closed optional pane renders with hidden; the runtime reveals it
	// on open so there is no flash.
	SecondaryOpen bool
	TertiaryOpen  bool

	// SecondaryLabel / TertiaryLabel label each side pane's
	// role="region" via aria-label. Empty falls back to "Secondary" /
	// "Tertiary".
	SecondaryLabel string
	TertiaryLabel  string

	// DeepLinkParam opts this host into URL round-tripping, naming the
	// query parameter that carries pane state, e.g. "pane" for
	// `?pane=secondary:ticket-42`. Opening a pane whose trigger declares
	// a key writes that parameter, closing strips it, and Back moves
	// between those states. Empty (the default) leaves the URL alone.
	//
	// Pane open/close remains in-page state, not a route (Hard Rule 1):
	// the parameter records which pane is showing so a refresh or a
	// shared link reproduces it, exactly as widget deep links do for
	// modals. The server still decides first paint. Read the parameter
	// with PaneDeepLink and set SecondaryOpen/TertiaryOpen plus the
	// pane's content from it. Without that, a shared link renders the
	// URL's pane closed and the runtime opens it after hydration.
	//
	// Triggers declare their key with interactive.PaneKey; a trigger
	// with no key opens the pane without touching the URL.
	DeepLinkParam string

	ID    string
	Class string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the host's root element.
	// Keys the component owns are dropped: class and id (use Class /
	// ID) and data-fui-* (the pane-host marker and deep-link wiring).
	ExtraAttrs html.Attrs
}

type PasswordInputConfig struct {
	// Name is the form-field name (required).
	Name string
	// ID is the input element's id — the id a surrounding label's
	// for= points at. Required unless Field carries one.
	ID string
	// Placeholder renders the native placeholder.
	Placeholder string
	// Required marks the field required.
	Required bool
	// Autocomplete sets the autocomplete attribute (e.g. "current-password", "new-password").
	Autocomplete string
	// Class adds extra CSS classes to the shell.
	Class string
	// ExtraAttrs forwards additional attributes to the shell's root
	// element — the same contract every component's ExtraAttrs
	// carries (data-* test hooks, analytics markers). Keys the
	// component owns are dropped: class (use Class), id, the input's
	// type, name, placeholder, required, autocomplete, aria-invalid
	// and aria-describedby (the field's wiring owns them), plus every
	// data-fui-* and data-hui-* key — the reveal hooks are the
	// runtime's contract, not a caller's to forge. Autocomplete has
	// its own field because it belongs to the input that submits.
	ExtraAttrs map[string]string

	// Ctx carries the per-request context used to resolve the reveal
	// button's words (ui.StringsFor: ShowPassword, HidePassword,
	// RevealShow, RevealHide). When nil, the English defaults are
	// used.
	Ctx context.Context

	// Field is the wiring an enclosing FormField handed its builder
	// (the headless.FieldControl its Input closure received). Applied
	// to the inner input — the id the outer label points at, the
	// described-by chain, the invalid state and the required flag —
	// and it wins over the config's own: two sources for one fact is
	// how they drift. Zero value means standalone.
	Field headless.FieldControl
}

type PieChartConfig struct {
	// Slices are the entries (≥1 with non-zero Value).
	Slices []PieSlice
	// Size is the SVG square side in CSS pixels. Default 160.
	Size int
	// InnerRadius (0–1, fraction of outer radius) cuts the center
	// out, turning it into a donut. Default 0 (pie).
	InnerRadius float64
	// CenterLabel renders a label in the middle of the donut hole.
	// Ignored when InnerRadius=0.
	CenterLabel string
	// CenterSubtext renders smaller text under the CenterLabel.
	CenterSubtext string
	// LabelledBy is the id of an element naming the chart for AT.
	// Without it the chart is aria-hidden.
	LabelledBy string
	ID         string
	Class      string
	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the chart's <svg> root,
	// or to the shared zero-data placeholder when there is nothing to
	// draw. Keys the component owns are dropped: class and
	// id (use Class / ID), data-fui-*, and the sizing and naming
	// attributes the SVG derives from config (width, height, viewBox,
	// xmlns, role, aria-labelledby, aria-hidden).
	ExtraAttrs html.Attrs
}

type PieSlice struct {
	// Label is the accessible label for the slice (required when
	// LabelledBy is set on the chart, used as <title> for AT).
	Label string
	// Value is the slice value (≥0). Slices with Value=0 are skipped.
	Value float64
	// Color overrides the default palette pick. Optional CSS color
	// or one of: "primary", "info", "success", "warning", "danger".
	Color string
}

type PipelineImageConfig struct {
	// Fallback is the <img>'s src: required, used by browsers that
	// can't pick from Sources. Typically a mid-size JPEG / PNG.
	Fallback string

	// Alt is required for non-decorative images.
	Alt string

	// Width and Height are the intrinsic dimensions of Fallback.
	// Setting them is mandatory to avoid CLS.
	Width, Height int

	// Sources is the typed responsive set; one <source> element is
	// emitted per distinct Type, grouping every PipelineSource with
	// that type into a single srcset.
	//
	// Groups are emitted in the order their Type first appears, so
	// putting the modern format (WebP) before the legacy one makes
	// older browsers fall through to the Fallback <img>.
	Sources []PipelineSource

	// Sizes is the CSS sizes attribute. Default "100vw".
	Sizes string

	// Placeholder, when set to an inline raster data: URI, renders a
	// low-fidelity image behind this one so something content-shaped is
	// visible before the real pixels arrive.
	//
	// Produce one with framework/image: BlurHashDataURL(hash, …) to render
	// a stored BlurHash, the natural companion to VariantResult.BlurHash,
	// or pass VariantResult.Placeholder straight through for an LQIP.
	// A bare BlurHash string is not accepted; it is not an image until it
	// is decoded.
	//
	// Values that are not usable inline images are dropped and the image
	// renders without a placeholder.
	Placeholder string

	Eager        bool
	HighPriority bool
	Fit          ImageFit
	Aspect       ImageAspect
	Rounded      bool

	ID, Class string

	// ExtraAttrs forwards additional attributes (data-* test hooks,
	// analytics markers, ARIA overrides) to the image's root element
	// (the wrapping <span>, not the inner <img>). Keys the component
	// owns are dropped: class and id (use Class / ID) and data-fui-*.
	ExtraAttrs html.Attrs
}