headless

type Action = html.Attrs

type AlertProps struct {
	// Tone names the kind of message: the class map turns it into colour
	// through the root's "<part>--<tone>" variant. It is passed
	// through, not interpreted; the tone word is what carries it to a
	// reader.
	Tone string
	// ToneWord is the tone in words — "Error", "Warning", "Success".
	// It is rendered for assistive tech and hidden visually, and it is
	// the reason this component satisfies WCAG 1.4.1: colour may not
	// be the only thing carrying meaning, and a red box is exactly
	// that to anyone who cannot see the red.
	//
	// Empty means the Title already says which kind it is — "Deploy
	// failed" needs no "Error:" in front of it — so the word is
	// skipped rather than duplicated.
	ToneWord string
	// Title is the headline. Required: an alert with no headline is a
	// coloured paragraph.
	Title string
	// Text is the detail, in prose.
	Text string
	// Body is the detail as markup — a list, a code sample, nested
	// content that is not an action. It renders after Text; prose
	// belongs in Text, and actions in Actions.
	Body render.HTML
	// Icon is decorative. The tone word carries the meaning.
	Icon render.HTML
	// Actions are the controls: retry, view logs, dismiss.
	Actions render.HTML
	// Live says whether this interrupts. See Live.
	Live Live
	// Focus moves focus here when the page loads.
	//
	// It is how a message that is ALREADY THERE gets announced. A live
	// region announces changes; content present when the document
	// loads is not a change, and role="alert" at load time is reported
	// inconsistently across screen readers. After a form posts and the
	// server redirects — the shape of every action in a
	// server-rendered app — the confirmation is present at load, so
	// the only reliable way to say it is to put the reader on it.
	Focus bool
	// DismissHref makes the alert dismissable with a link that keeps a
	// real href, so dismissing needs no script and survives the page
	// being reloaded. The label names what is being dismissed, because
	// "Dismiss" three times in a row tells a screen reader user
	// nothing.
	DismissHref  string
	DismissLabel string
	// Island is where the dismiss goes with script: dismissing is an
	// in-page state change, so the × carries the RPC contract beside
	// its href. Required when DismissHref is set; ignored otherwise.
	Island Island

	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs and binds on every part. Nothing here is
	// fillable — Actions already takes the page's own controls, and
	// everything else an alert draws is what a screen reader is given
	// to tell one alert from another.
	Parts Parts
	// Strings are the strings this component says. Nil means the English
	// defaults; a layer above sets them from the request's language.
	Strings *Strings
}

type BackToTopProps struct {
	// Href is where the link goes: a same-origin anchor, usually the
	// top of the page or the main content's id. Required — a jump
	// control with no destination is a button pretending to be one,
	// and the no-script page would carry a dead link.
	Href string
	// Target, when set, is the element id the module reads the scroll
	// sentinel from and scrolls to. An id, not a selector: the module
	// resolves it, and an id here cannot become a query the way a
	// selector string can.
	Target string
	// Label is the accessible name. Empty takes Strings.BackToTop;
	// the glyph alone names nothing.
	Label string
	// Icon is the glyph. The default arrow is the structure's own; a
	// caller's SVG replaces it.
	Icon render.HTML
	// Threshold is the scroll offset in CSS pixels past which the
	// module shows the link. Zero takes the module's default;
	// negative is refused.
	Threshold int
	// Smooth asks for smooth scrolling. The module downgrades to an
	// instant jump under reduced motion; the preference is honoured,
	// not overridden.
	Smooth bool

	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs and binds on the root, the icon and the label.
	// Strings are not read — the name is the caller's Label.
	Parts Parts
	// Strings are the strings this component says. Nil means the English
	// defaults; a layer above sets them from the request's language.
	Strings *Strings
}

type BadgeProps struct {
	// Label is the visible text, and the whole of what a screen reader
	// hears. Required.
	Label string
	// Icon renders before the label, and is decorative: the label is
	// the accessible name, so an icon that repeated it would be read
	// twice. Anything the icon means that the label does not say
	// belongs in the label.
	Icon render.HTML
	ID   string

	ExtraAttrs html.Attrs

	// Parts: attrs and binds on the root and the icon.
	Parts Parts
}

type BadgeTone string

type Bind struct {
	// Signal is the signal's name. Required.
	Signal string
	// Mode is "text" (the default: the part's text is the value),
	// "html" (the part's HTML is the value, the trusted path an island
	// fragment uses) or "attr" (one attribute is the value).
	Mode string
	// Attr is the attribute for mode "attr", and must be one the
	// framework lets a signal write: any aria-*, or its allow-list.
	// Empty otherwise.
	Attr string
}

type Binds map[Part]Bind

type Box struct {
	Classes Classes
	Slots   Slots
	Over    PartAttrs
	Binds   Binds
	// contains filtered or unexported fields
}

type Breadcrumb struct {
	// Text is the step's visible label. Required.
	Text string
	// Href is the step's destination. Empty on the last step (the
	// current page names itself, it does not link to itself); a value
	// on the last step links it unless Current is also set.
	Href string
	// Current marks the step as the current page whatever its Href:
	// rendered as text with aria-current="page" rather than a link,
	// for a page that appears in its own trail with a link.
	Current bool
}

type BreadcrumbsProps struct {
	// Label names the navigation landmark. Empty takes
	// Strings.BreadcrumbsLabel.
	Label string
	// Items are the steps, shallowest first. Required and non-empty:
	// a trail with no steps is a landmark that says nothing.
	Items []Breadcrumb

	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs on the root and the list. No part is fillable: the
	// trail is the contract.
	Parts   Parts
	Strings *Strings
}

type ButtonProps struct {
	// Label is the visible text. An icon-only button leaves it empty
	// and sets AriaLabel; a button with neither has no accessible name
	// and is refused.
	Label     string
	AriaLabel string
	Icon      render.HTML
	// Suffix renders after the label — a keyboard hint, a count. It is
	// the caller's markup, so whether it is announced is the caller's
	// decision: a keyboard hint hides its glyphs and supplies words, a
	// badge announces itself.
	Suffix render.HTML
	// Variant and Size are class-map vocabulary, passed through so the class map
	// can look up "<part>--<variant>". The structure does not care.
	Variant string
	Size    string
	// Disabled is a real state here. A disabled anchor is not a thing
	// in HTML, so Href + Disabled drops the href and says so with
	// aria-disabled rather than leaving a live link that looks dead.
	Disabled bool
	Type     string
	Href     string
	// External, with Href, opens the link in a new tab with
	// rel="noopener noreferrer" and owns target and rel: a caller's
	// spelling of either — folded or not — cannot clobber the noopener
	// contract.
	External bool
	// PopoverTarget names a popover this button opens. It is also what
	// gives that popover its invoker, which is how the runtime places
	// the panel beside this button.
	PopoverTarget string
	// HasPopup, when set, is the aria-haspopup value ("menu", "dialog").
	HasPopup string

	// Action is what the button DOES when the host framework's runtime
	// is on the page: the data-fui-rpc attributes of one of its
	// actions, as its Attrs() returns them, one of its local signal
	// mutations (set, increment, toggle), or one of the wiring keys a
	// page can put on any clickable — opening a widget or pane, firing
	// a toast, writing the URL, deep-linking an open, prefetching a
	// runtime module. It is a seam of its own rather than a use of
	// ExtraAttrs, because ExtraAttrs is for what a page knows and a
	// component cannot — a test id, a title — and Safe drops every
	// data-fui-* key from it so a decoration can never become a
	// request. An action is not decoration. Naming it makes it
	// reviewable: a button that fires a request says so in its props,
	// in one place, and the type refuses anything that is not a
	// request or a wiring key.
	//
	// The request family (data-fui-rpc*, data-fui-confirm, the signal
	// mutations) needs a button: an anchor carrying one is refused at
	// render, because a link navigates and a button acts. The wiring
	// keys may ride either tag.
	Action html.Attrs

	ID         string
	ExtraAttrs html.Attrs
	// Parts is the caller's reach into this component's named parts:
	// attributes on the root (a class appends, never replaces) and on
	// the icon. The root is not fillable; the icon is caller markup
	// already.
	Parts Parts
}

type CardProps struct {
	// Title renders as a heading. Empty omits it, along with the whole
	// header when Desc is empty too — an empty header is a stripe of
	// padding that looks like a mistake.
	Title string
	// TitleTag is the heading level, "h3" by default. A card does not
	// know how deep in the outline it sits, so a page that nests cards
	// under an h2 says so here rather than letting every card claim
	// the same level and leave the document with no structure to
	// navigate by.
	TitleTag string
	Desc     string
	// Href makes the whole card one focusable link — the surface is
	// the affordance. The contents render inside a single inner part,
	// so the anchor wraps exactly what the card showed as a div. A
	// href the anchor policy refuses is refused at render, naming the
	// prop, the package's posture for every configured href
	// (Alert.DismissHref, Form.Action, Table.Path): a rejected href is
	// the developer's mistake, not a link to render dead.
	Href   string
	Footer render.HTML

	ID         string
	ExtraAttrs html.Attrs

	// Parts. The header is the one fillable part, and the rule it
	// comes from is worth stating: a slot exists only where the
	// component COMPOSES something a prop cannot express. A card's
	// header is built from a title string and a description string,
	// so a header that needs a control in it has no prop to arrive
	// through. The body and the footer already take caller content, so
	// a slot there would be a second way to do one thing — which is
	// worse than none, because half the call sites will use each.
	//
	// Attrs are the opposite: they apply to every part, on every
	// component, because adding an attribute cannot break a structure.
	Parts Parts
	// Strings are the strings this component says. Nil means the English
	// defaults; a layer above sets them from the request's language.
	Strings *Strings
}

type CarouselProps struct {
	// Label names the region. Required.
	Label string
	// Slides, in order. Required, at least one.
	Slides []CarouselSlide
	// Loop makes Next on the last wrap to the first (and vice versa).
	// Default: the ends disable.
	Loop bool
	// AutoRotateMS, when > 0, advances every N ms. Negative refused.
	AutoRotateMS int
	// VisiblePerView shows N slides side-by-side (default 1; 0 or
	// negative refused — a viewport of nothing is not a viewport).
	VisiblePerView int
	// NoDots hides the dot anchors.
	NoDots bool
	// NoArrows hides the prev/next controls.
	NoArrows bool

	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs on the root, the track, the slides and the
	// controls.
	Parts   Parts
	Strings *Strings
}

type CarouselSlide struct {
	// Content is the slide body. Required.
	Content render.HTML
	// Label is the slide's accessible label. Defaults to
	// Strings.CarouselSlide ("Slide <n> of <total>") at render.
	Label string
	// ID is the slide's stable id. Empty takes "<trackID>-slide-<n>".
	ID string
}

type Case struct {
	Name string
	Why  string
	HTML render.HTML
}

type ChoiceProps struct {
	// Type is "checkbox" or "radio".
	Type string
	// Name groups the choice. For a radio it IS the group; items that
	// must act as one group share it, which is why the group helpers
	// stamp it on every item.
	Name string
	// Value is what the choice submits when checked. Required for
	// Radio: without distinct values a group cannot tell its options
	// apart. A checkbox may leave it empty and submit "on", the HTML
	// default.
	Value string
	// Label is the visible text beside the control. Required: an
	// unlabelled choice is a bug, not a variant.
	Label string
	// Hint is secondary text under the label, for the consequence of
	// the choice rather than its meaning.
	Hint     string
	Checked  bool
	Disabled bool

	ID string
	// Extra attrs land on the input, the control that submits.
	Extra html.Attrs
}

type Classes map[Part]string

type ClusterProps struct {
	Gap string
	// Align is cross-axis: "center" by default in the class map, because a
	// row of controls of different heights should line up on their
	// middles.
	Align string
	// Justify is main-axis: "start", "between", "end".
	Justify string
	// NoWrap keeps the row on one line. Use it sparingly: a row that
	// cannot wrap is a row that overflows on a phone, and horizontal
	// page scroll is the failure this whole layer exists to prevent.
	NoWrap bool
	Tag    string

	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs and binds on the root.
	Parts Parts
}

type ColorProps struct {
	Name string
	// Value is the colour as text, usually but not always #rrggbb.
	Value    string
	Disabled bool
	Invalid  bool

	// ID and extra attrs land on the hex text input, the control that
	// submits.
	ID          string
	Extra       html.Attrs
	DescribedBy string

	// Parts: attrs and binds on the shell, the hex input and the
	// swatch. Strings carry the swatch's name.
	Parts Parts
	// Strings are the strings this component says. Nil means the English
	// defaults; a layer above sets them from the request's language.
	Strings *Strings
}

type Column struct {
	// Key identifies the column: the value under SortParam in the
	// sort href, and the key a Row's Cells are matched by. Required.
	// Anything a query can encode is a legal Key — that is the point
	// of building the href through net/url.
	Key string
	// Header is the visible column header text. May be empty: an
	// actions or icon column. A header-less column that cannot be
	// sorted is hidden from assistive tech; one that can is named
	// from Strings.TableSortBy, because an anchor with no text is a
	// control with no name.
	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
	// HeaderAttrs and CellAttrs add attributes to this column's <th>
	// and to every <td> under it, through the same sanitiser as
	// ExtraAttrs (Safe): data-fui-* keys, style, id and class are
	// dropped, names are stored folded, and one attribute under two
	// spellings is refused.
	HeaderAttrs html.Attrs
	CellAttrs   html.Attrs

	// Variant is class-map vocabulary for the whole column: looked
	// up as "<part>--<variant>" on this column's <th> (PartHeader)
	// and each of its <td> (PartCell), so a class map can align a
	// column's text or shade its column without the structure
	// caring. Empty means none.
	Variant string
}

type ComboboxOption struct {
	// ID is the option's stable id. Empty takes "<listboxID>-opt-<n>".
	ID string
	// Value is what a pick writes into the input. Empty takes Label.
	Value string
	// Label is the option's visible text. Required.
	Label string
	// Meta is secondary text beside the label (a path, a kind).
	Meta string
	// Href turns the option into an anchor: picking it navigates.
	// Unsafe schemes drop the navigation affordance entirely (the
	// pick still fills the input).
	Href string
	// Disabled removes the option from keyboard navigation.
	Disabled bool
}

type ComboboxProps struct {
	// ID is the input's element id. Required; the listbox takes
	// "<ID>-listbox".
	ID string
	// Name is the form-submit name on the input. Required.
	Name string
	// Label names the input. Required.
	Label string

	// Placeholder for the input.
	Placeholder string

	// Island is the typed in-page results contract: the endpoint that
	// re-renders the listbox and the signal the region is bound to.
	// Optional — a static Options list needs no island; the no-script
	// path is the same-origin GET form below either way.
	Island *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 (a reader without script must still reach the
	// results); refused when it is "#".
	NoScriptAction string

	// Options is a static list the module filters client-side. Takes
	// precedence over the Island (no round-trip fires).
	Options []ComboboxOption

	// DebounceMS bounds the input debounce. Zero takes 250; negative
	// is refused.
	DebounceMS int

	ExtraAttrs html.Attrs

	// Parts: attrs on the root, the input and the listbox. The
	// listbox's content is the Options' — not fillable.
	Parts   Parts
	Strings *Strings
}

type ConditionalFieldProps struct {
	// When is the NAME of the watched field. Required: a region that
	// watches nothing is always shown, which is a div.
	//
	// The scope the runtime reads the name in: the region's own form
	// first — two forms can each carry a "plan" control and the region
	// follows the one it belongs to — and, when the region has no
	// form or its form holds no control of that name, the document,
	// preferring controls no form owns (a page-level switch) and
	// otherwise the first in document order.
	When string
	// Value is the watched field's value that shows the region.
	// Required: shown on every value is the same as always shown.
	// The empty string is refused, so "show when unchecked" — a
	// checkbox whose unchecked value is "" — is not expressible here;
	// watch a select or a radio pair whose values are both stated
	// instead.
	Value string

	ID         string
	ExtraAttrs html.Attrs
}

type ContainerProps struct {
	// Size names the measure — "sm", "md", "lg", "full".
	Size string
	Tag  string

	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs and binds on the root.
	Parts Parts
}

type CounterProps struct {
	// Signal is the client signal the count lives in. Required: the
	// buttons' whole contract is that they change a value the page
	// already holds, and the display's contract is that the same
	// signal writes it.
	Signal string
	// Name, when set, renders the value as a named number input the
	// surrounding form submits — the no-script path. The input's
	// value follows the signal the same way the span does, so the
	// two variants are one control.
	Name string
	// Value is the count's first value, seeded into the markup.
	Value int
	// Step is the increment size. Default 1; must be positive.
	Step int
	// Label names the group for assistive technology. Empty takes
	// Strings.CounterLabel: three controls with no group name is a
	// label, a minus, a number and a plus to nobody, so the default
	// names them.
	Label string
	// AnimateFrom, when set, is the value the count animates from on
	// arrival; Value is where it lands, and Value stays the SSR text.
	// Nil means no animation. The hooks it renders are bound by the
	// headless-controls module, which respects reduced motion and
	// never owns the number.
	AnimateFrom *int
	// DurationMS bounds the animation. Zero takes the module's
	// default; negative is refused.
	DurationMS int

	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs and binds on the root and the value. Strings
	// carry the group's name and the two buttons'.
	Parts Parts
	// Strings are the strings this component says. Nil means the English
	// defaults; a layer above sets them from the request's language.
	Strings *Strings
}

type DetailListProps struct {
	// Rows are the pairs, in reading order. At least one.
	Rows []DetailRow

	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs and binds on the list, its rows and their terms
	// and values.
	Parts Parts
}

type DetailRow struct {
	// Label is the term. Required: a value with no term is a fact
	// nobody can look up.
	Label string
	// Value is the value, and it may be markup — a status badge, a
	// link, an empty-value dash. Required: render the empty-value
	// dash for a missing value, so the absence is deliberate.
	Value render.HTML
}

type DisclosureProps struct {
	// Summary is the always-visible controller. Required and
	// non-blank: a details whose summary says nothing is a button with
	// no name.
	Summary render.HTML
	// Content is the revealed panel.
	Content render.HTML
	// Open renders the details expanded.
	Open bool
	// Trap opts the open disclosure into focus containment: Tab walks
	// inside it and comes back, the drawer posture. The containment is
	// the widget runtime's own (the kernel's focus selector), armed by
	// the module while the disclosure is open.
	Trap bool
	// Name, when set, is the details element's name attribute: the
	// browser groups disclosures that share it and opens one at a time
	// (the native accordion) — opening one closes the others with no
	// script at all. Control bytes are refused: the value is a group
	// key the browser matches verbatim.
	Name string
	// PersistKey, when set, keeps the open state across client-side
	// navigation AND restores it on arrival from the session store,
	// namespaced and component-encoded so two disclosures never share
	// one key. Empty means the ordinary dialect: closed by a
	// navigation, whatever the reader left open.
	PersistKey string

	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs on the root, the summary and the panel. The summary
	// is fillable — its content is the caller's — and so is the panel.
	Parts Parts
}

type DividerProps struct {
	// Label puts text in the break ("or"). A labelled divider is
	// always meaningful, so it is never decorative.
	Label string
	// Vertical draws it along the block axis, for a divider inside a
	// row.
	Vertical bool
	// Decorative says this line groups nothing — it is a flourish, and
	// is hidden from assistive tech. Without it a screen reader
	// announces "separator" at every line on the page.
	Decorative bool

	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs and binds on the root, the lines and the label.
	Parts Parts
}

type EmptyStateProps struct {
	// Title is the heading. Required: it is also the region's name.
	Title string
	// Level is the heading level, 3 by default. An empty state nests
	// inside a section; one mounted as the whole page under the h1
	// says 2 here.
	Level int
	// Description is the supporting line: what would be here, or what
	// to do about it.
	Description string
	// Action is the way out — "New app", "Clear the filter". A dead
	// end with no action is a page the reader can only leave with the
	// back button.
	Action render.HTML

	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs and binds on every part the state draws.
	Parts Parts
}

type Event struct {
	// Title is what happened. Required.
	Title string
	// Detail is the supporting line.
	Detail string
	// When is the human-readable time ("3 days ago", "18:22").
	When string
	// Machine is the machine-readable timestamp for <time datetime>,
	// RFC 3339. Without it "3 days ago" is a string no assistive tech,
	// translation layer or scraper can resolve to a moment.
	Machine string
	// Tone lets the class map colour the marker — "success", "danger".
	Tone string
	// Meta is the secondary line beside the title — an actor, a
	// relative time ("by dom", "2h ago") — in the header row, read
	// after the title it qualifies. When is the timestamp contract;
	// Meta is a caption with no machine form.
	Meta string
	// Body is extra markup under the detail: a log excerpt, actions.
	Body render.HTML
}

type FieldControl struct {
	// ID is the field's For: the id the label points at.
	ID string
	// DescribedBy is the error's and the hint's ids, error first, for
	// the control's aria-describedby. Empty when the field has
	// neither — unless ReserveError held an empty error node in place,
	// whose id rides here too.
	DescribedBy string
	// Invalid is true when the field has an Error, so a control never
	// has to be told twice.
	Invalid bool
	// Required mirrors the field's own flag.
	Required bool
}

type FieldError struct {
	// For is the id of the control at fault. With it the message
	// becomes a link that moves focus to the field; without it the
	// message is text, which is the right fallback and a worse
	// experience.
	For string
	// Message is what is wrong, in words the person can act on.
	// "Invalid" is not one of them.
	Message string
}

type FieldProps struct {
	// Label is required. An input without a label is not a variant, it
	// is a defect: nothing announces it and nothing clicks it into
	// focus.
	Label string
	// For is the control's id. Without it the label is decorative — it
	// neither names the control for assistive tech nor enlarges its hit
	// area — so a Field with a Label and no For is refused.
	For string
	// Hint is help text: the rule the value must obey. It stays
	// rendered — and stays in the description — when Error is set: the
	// hint is the rule, the error is the violation, and dropping the
	// rule exactly when it was broken is dropping it when the reader
	// needs it most. The error is drawn first and read first, so the
	// correction arrives before the reminder.
	//
	// The cost is paid in pixels and syllables: an errored row is
	// taller, and its description is longer, than an error-only one.
	// That is the deliberate trade of this primitive; a caller who
	// wants the hint gone on error says so by not setting it.
	Hint string
	// Error is announced and drawn before the hint.
	Error string
	// ReserveError keeps an error paragraph rendered — empty and wired
	// into the control's aria-describedby — when Error itself is
	// empty. It exists for a script that fills the node without
	// re-rendering the field (a live editor applying edits as the
	// operator types). An empty described-by target announces nothing
	// until it is filled, which is the point: the wiring ships, the
	// words arrive when they are true.
	//
	// The node's id is the contract a filling script looks it up by:
	// the control's id with "-error" appended, the same id that rides
	// aria-describedby. It carries no hook of its own — a data-hui-*
	// attribute is something this package's runtime module binds, and
	// no module has behaviour for an empty paragraph.
	//
	// A caller that fills the node must also set aria-invalid on the
	// control it describes; this component cannot know the script's
	// verdict. The server-rendered path should pass Error instead —
	// a reserved node is a scaffold, not an answer.
	ReserveError bool
	// Required marks the label and is mirrored onto the control by the
	// caller (the control owns its own required attribute).
	Required bool

	// Parts is the caller's reach into the field's named parts:
	// attributes on the root (a class appends, never replaces). No
	// part is fillable — every element a field draws is half of a
	// relationship built from the control's id, and replacement
	// content would break the half it replaced.
	Parts Parts

	ID         string
	ExtraAttrs html.Attrs
}

type FieldsetProps struct {
	// Legend is the group's name, rendered as a real <legend> inside
	// a real <fieldset>: that pair is the native group semantic,
	// naming every control inside without a single aria attribute.
	//
	// Empty renders the group as a plain div: an unlabelled fieldset
	// is a landmark that names nothing, and a group with no name to
	// give is a row of fields, not a section.
	Legend string
	// Description is the supporting line under the legend. It is
	// wired to the group by aria-describedby beside any group error,
	// read with the question it explains.
	Description string
	// Error is the error that belongs to the group as a whole — the
	// question was answered wrong somewhere in it, not in any one
	// field. It is wired to the group by aria-describedby, so the
	// fields' own errors and the group's never compete for the same
	// relationship.
	Error string

	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs and binds on the group and every part it draws.
	Parts Parts
}

type FileUploadProps struct {
	// Name is the field name. Required.
	Name string
	// ID is the input's id. Required: the zone is a <label for=…>, and
	// without the pair the biggest click target on the control does
	// nothing.
	ID string
	// Label is the instruction inside the zone. Required.
	Label string
	// CTA is the part of the instruction that reads as the action —
	// "choose a file". It is NOT a button: a button inside a label
	// swallows the label's click, so the whole zone stops opening the
	// picker. It is styled text, and the real control is the input.
	CTA string
	// Hint is the accepted types and size, tied to the input by
	// aria-describedby so it is read with the field rather than being
	// small print beside it.
	Hint string
	// Accept is the accept attribute; Multiple allows several files.
	Accept   string
	Multiple bool
	Required bool
	Disabled bool
	Invalid  bool
	// DescribedBy is an extra id to reference, from a Field.
	DescribedBy string

	// Parts: attrs and binds on the root, the zone, the input, the
	// list and the status. Strings carry the sentences the
	// runtime says when files are chosen.
	Parts Parts
	// Strings are the strings this component says. Nil means the English
	// defaults; a layer above sets them from the request's language.
	Strings *Strings

	ExtraAttrs html.Attrs
}

type FormProps struct {
	// Action and Method are the submission target. Method defaults to
	// post.
	Action string
	Method string
	// Label names the form for assistive tech when it is one of
	// several on a page. A single form on a page needs no name; two
	// unnamed ones are two identical entries in a landmark list.
	Label string
	// Errors renders above the fields. When non-empty the form asks
	// the runtime to move focus there on load, which is what makes a
	// failed submit noticed at all — see ValidationSummary.
	Errors render.HTML
	// Actions are the submit and cancel controls.
	Actions render.HTML
	// Multipart sets the encoding a file upload needs. Without it the
	// browser submits file inputs as names with no contents, which
	// looks like a server bug and is not one.
	Multipart bool
	// NoValidate turns off the browser's own validation bubbles, for a
	// form that validates on the server and reports through Errors.
	// The bubbles are not a substitute: they show one message at a
	// time, vanish on blur, and cannot be styled or read back.
	NoValidate bool

	// Island is where the form's answer is rendered again: when set,
	// the form carries the RPC contract beside its action and the
	// arrival pass focuses the summary. The HTTP convention the
	// runtime's RPC lands in the signal: a validation failure is
	// answered 200 with the region's HTML — the errors ARE the
	// answer, the island swaps them in, and the summary takes focus.
	// A non-2xx is a transport or server error, which the runtime
	// delivers as {ok:false, status, text} in the signal, never as
	// markup: an island form that answers 422 to a failed validation
	// renders nothing at all. Nil is right for a page that IS the
	// form — sign-in, the auth flow the architecture keeps native —
	// where the plain POST to the page is the whole design.
	Island Island

	// Request is what the form DOES when the host framework's runtime
	// is on the page: its data-fui-rpc contract — the endpoint the
	// submit posts to, a method that may differ from the native one
	// (a form that natively POSTs for no-script may PUT over RPC),
	// the success effects (a signal to land in, a page to navigate
	// to, a reset, a widget to open or close) — plus the mount hook a
	// generated form carries (data-action-mount, the compiled action
	// that populates its relation selects). It is a seam of its own
	// rather than a use of ExtraAttrs for the same reason Button's
	// Action is: Safe drops every data-fui-* and data-action-* key, so
	// wiring through extras would render a plain form that posts
	// natively. A key outside the request vocabulary panics at render,
	// naming the key and the seam.
	//
	// Island and Request are two ways of saying "the submit is an
	// RPC"; carrying both on one form is refused rather than resolved
	// by precedence.
	Request Action

	// Parts is the caller's reach into the form's named parts:
	// attributes on the root and on the body and actions rows (a
	// class appends, never replaces). Nothing is fillable — the
	// fields and the actions are the caller's own children.
	Parts Parts

	ID         string
	ExtraAttrs html.Attrs
}

type GalleryItem struct {
	// Src is the full-resolution image URL. Required; refused when
	// unsafe (a javascript: URL in an image is a payload, not a
	// picture) — it degrades to nothing the day the caller hands one
	// in, so the refusal is loud.
	Src string
	// Thumb is the thumbnail URL. Defaults to Src.
	Thumb string
	// Alt is the image's description. Required: an image with no
	// description is decoration lying about being content.
	Alt string
	// Caption is optional descriptive text under the image.
	Caption string
	// Width / Height for the thumbnail (CLS-safe). Default 200×150.
	Width  int
	Height int
}

type GalleryLightbox struct {
	// Name is the lightbox to open: the data-fui-open value, the Name
	// of a mounted framework/ui.Lightbox. Required when the wiring is
	// set; a zero GalleryLightbox renders plain links.
	Name string
	// Group is the data-fui-lightbox-group value: the id the lightbox's
	// prev/next nav walks across this gallery's items. Empty derives
	// "<Name>-gallery".
	Group string
}

type GalleryProps struct {
	// Items are the entries, in order. Required non-empty.
	Items []GalleryItem
	// Label names the list. Required: an unnamed image list is a
	// landmark a screen reader cannot jump to.
	Label string
	// HrefFn, when set, returns a per-item destination. Empty for an
	// item makes that item's link the full image, so every tile stays
	// a working link.
	HrefFn func(i int, it GalleryItem) string
	// ExtraAttrsPerItem adds attributes to item N's anchor (a lightbox
	// group id, a deeplink): index → attrs.
	ExtraAttrsPerItem map[int]html.Attrs
	// Lightbox, when set, wires every item's anchor to a framework
	// lightbox: the click opens the named overlay instead of
	// navigating, through the widget runtime's open contract. The
	// no-script path stays the full-image href the anchor carries.
	Lightbox GalleryLightbox

	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs on the list, items, figures, links, images,
	// captions.
	Parts Parts
}

type GridProps struct {
	// Min is the narrowest a column may get before the grid drops one,
	// as a name from the scale ("sm", "md", "lg"), not a length.
	//
	// A length is what the framework's Grid takes, and it silently did
	// nothing for every value: the component wrote a data attribute
	// and no stylesheet ever read it. A named step cannot rot that way
	// — the class map either has a rule for the name or the name is a typo
	// that shows up the first time anyone looks.
	Min string
	Gap string
	Tag string

	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs and binds on the root.
	Parts Parts
}

type GroupProps struct {
	// Legend is the group's shared label. Required: a set of choices
	// with no question above them is as broken as an unlabelled input.
	Legend string
	// Required marks the legend with data-required, the same state
	// attribute a Field puts on its label, so a class map can draw
	// the mark a sighted reader looks for. It is a cue, not a
	// constraint: what the browser and the parser enforce is the
	// required attribute on the leaves, which the caller sets there.
	Required bool

	ID    string
	Extra html.Attrs
}

type InputGroupProps struct {
	// Label names the group when it holds more than one focusable
	// thing and no single label covers them. It becomes a group role
	// with that name; without it the group is a plain div, which is
	// correct for the common case of one labelled input plus a button
	// that already says what it does.
	Label string

	ID         string
	ExtraAttrs html.Attrs
}

type InputProps struct {
	Type string
	// DescribedBy is the aria-describedby a Field hands down. It is
	// the whole reason a hint or an error reaches assistive tech: the
	// text is on screen either way, but without this attribute a
	// screen reader user hears the label and nothing else — no
	// format hint, and no reason the control is red.
	DescribedBy string
	Name        string
	Value       string
	Placeholder string
	Required    bool
	Disabled    bool
	// Invalid states aria-invalid for assistive tech; the class map
	// colours the border off the same attribute.
	Invalid bool
	// AriaLabel names the control where a visible label cannot go — a
	// search box in a toolbar, a field inside a table's own controls.
	// Everywhere else the label belongs to a Field, on screen where
	// everyone can read it. A placeholder is not a label: it goes away
	// on the first keystroke, its contrast is deliberately low, and
	// not every screen reader treats it as a name.
	AriaLabel string

	ID    string
	Extra html.Attrs
	// Owned are the type-specific attrs — min, max and step, and only
	// those — applied after the common set and after Extra so a caller
	// cannot widen a numeric input's bounds through extra attrs behind
	// the config's back. Any other key is refused: this is a seam for
	// bounds, not a second ExtraAttrs. Empty values are skipped,
	// leaving Extra's say if it has one.
	Owned html.Attrs
}

type Island struct {
	// Endpoint is the RPC path the region's next rendering comes
	// from: same-origin, starting with "/".
	Endpoint string
	// Signal is the data-fui-signal the region is bound to; the
	// response replaces it.
	Signal string
}

type JSONTreeProps struct {
	// Value is the data to render. Required non-nil; values that do
	// not marshal to JSON are refused (a channel, a func, a cycle).
	Value any
	// OpenDepth is the recursion depth that renders open by default.
	// 0 means only the root is open; -1 means everything is open.
	OpenDepth int
	// MaxStringLen truncates long strings with the truncation mark.
	// 0 means no limit.
	MaxStringLen int

	ID         string
	ExtraAttrs html.Attrs

	// Strings overrides the words (object, array, null, empty,
	// truncation). Nil takes the defaults.
	Strings *Strings

	// Parts: attrs on the root, nodes, summaries, lists, keys.
	Parts Parts
}

type Kit struct {
	// Classes is this component's own classes.
	Classes Classes
	// contains filtered or unexported fields
}

type LightboxViewerProps struct {
	// Name is the lightbox's identity (required): the value its hooks
	// carry, and the source of the title span's id (<Name>-title),
	// which the surrounding modal's aria-labelledby points at.
	Name string
	// Label is the accessible name of the open viewer. Empty means
	// Strings.LightboxViewerLabel.
	Label string
	// Nav renders the prev/next buttons.
	Nav bool
	// Caption renders a <figcaption> bound to the viewer's caption
	// signal.
	Caption bool
	// Download renders an anchor that saves the image being viewed,
	// its href bound to the viewer's src signal.
	Download bool
	// PrevIcon, NextIcon and DownloadIcon are the buttons' glyphs.
	// Decorative; the accessible names come from Strings.
	PrevIcon     render.HTML
	NextIcon     render.HTML
	DownloadIcon render.HTML
	// Wiring renders the framework module's data-fui-lightbox*
	// attributes IN PLACE OF the hooks. See LightboxWiring.
	Wiring LightboxWiring

	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs on every part. Nothing here is fillable — the
	// caption and the image are signal-bound, and the buttons are the
	// nav contract; a slot would fight the binding it replaced.
	Parts Parts
	// Strings are the strings this component says. Nil means the
	// English defaults; a layer above sets them from the request's
	// language.
	Strings *Strings
}

type LightboxWiring struct {
	// Viewer is the data-fui-lightbox value: the lightbox widget's
	// name, carried by the root and the nav buttons, and (as a bare
	// marker) by the image the module's pinch-zoom owns.
	Viewer string
	// Nav renders data-fui-lightbox-nav="true" beside the hook that
	// states the same fact: the opt-in that makes prev/next and the
	// arrow keys step the gallery group.
	Nav bool
}

type Live string

type MenuAction struct {
	// Path is the form's action URL.
	Path string
	// Method defaults to POST.
	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 MenuItem struct {
	// Label is the row's visible text. Required unless Separator.
	Label string

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

	// RPC and RPCMethod wire the row to a server-side handler via the
	// kernel's data-fui-rpc contract. Use for "Delete this row" items.
	RPC, RPCMethod string

	// Confirm asks the reader to confirm before the RPC fires; the
	// runtime honours it on RPC dispatch and on any form submit.
	Confirm string

	// Icon is rendered before the Label. Inline HTML.
	Icon render.HTML

	// Danger tints destructive rows; a visual hint only.
	Danger bool

	// Disabled removes the row from keyboard navigation and pointer
	// interaction while keeping it in the panel.
	Disabled bool

	// Separator renders a horizontal divider instead of a row.
	Separator bool

	// ID becomes the rendered row's id attribute. Uniqueness is
	// caller-owned, like any HTML id — the menu refuses the duplicates
	// it can see.
	ID string

	// Radio, when non-empty, renders the row as a radio option:
	// role="menuitemradio" plus aria-checked (see Checked) and the
	// group attr the module arbitrates client-side. Exactly one row of
	// a group should carry Checked. Mutually exclusive with Children —
	// both set is refused at render.
	Radio string

	// Checked sets aria-checked on a Radio row.
	Checked bool

	// Action renders the row as a form submission instead of a link or
	// RPC, for hosts whose command rows hit PRG endpoints. Nil (the
	// zero value) renders nothing. Mutually exclusive with Href, RPC,
	// Radio and Children: incoherent combos are refused at render.
	Action *MenuAction

	// Children nests a submenu behind this row. The row renders as a
	// disclosure summary; setting Href, RPC, Action or Radio on it is
	// refused at render.
	Children []MenuItem

	// ExtraAttrs forwards additional attributes onto the row. Keys the
	// row owns are dropped, as everywhere in this package.
	ExtraAttrs html.Attrs
}

type MenuProps struct {
	// ID pairs the trigger with the panel. Empty derives a stable id
	// from the menu's content.
	ID string
	// Label is the trigger's visible text. Mutually exclusive with
	// TriggerHTML and TriggerElement.
	Label string
	// TriggerHTML overrides Label with custom inline HTML.
	TriggerHTML render.HTML
	// TriggerElement replaces the framework summary with a
	// caller-owned interactive element: the menu renders a
	// summary-less disclosure beside it and the module makes the
	// element the controller. Use for host-styled triggers — an
	// interactive element inside a summary is axe nested-interactive.
	TriggerElement render.HTML
	// Items is the menu's contents. Required; an empty menu panics —
	// it signals a bug, not a runtime state.
	Items []MenuItem
	// Position names the panel's anchoring variant (bottom-start, …);
	// the class map resolves it. Empty takes bottom-start.
	Position string
	// LazyPanel ships the panel's rows inside an inert template the
	// module mounts on first open, for page-scoped consumers that must
	// not see closed-menu rows in the live DOM.
	LazyPanel bool

	ExtraAttrs html.Attrs

	// Parts: attrs on the root. Rows own their guarantees.
	Parts Parts
}

type MultiSelectOption struct {
	// Value is the form-submit value. Required.
	Value string
	// Label is the option's visible text. Required.
	Label string
	// Selected checks the option on first paint.
	Selected bool
	// Disabled greys the option out and keeps it unsubmitting.
	Disabled bool
}

type MultiSelectProps struct {
	// Name is the form-field name every checkbox shares; the form
	// receives the repeated key for each checked option. Required.
	Name string
	// Label is the group's accessible name and the disclosure's
	// summary. Required.
	Label string
	// Options are the choices, in order. Required and non-empty.
	Options []MultiSelectOption
	// Open renders the disclosure expanded.
	Open bool
	// Placeholder is what the chips strip says when nothing is
	// picked. Empty takes Strings.MultiSelectPlaceholder.
	Placeholder string

	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs on the root, the chips strip, the summary, the
	// panel, the group and the rows. No part is fillable: the
	// checkbox group is the contract.
	Parts   Parts
	Strings *Strings
}

type NotificationBellProps struct {
	// Href is where the link goes: 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 trigger's visible name. Required.
	Label string
	// UnreadCount is the count the badge shows and the accessible
	// name says. Negative is refused; zero hides the badge (nothing
	// unread is no news) unless a Bind raises it.
	UnreadCount int
	// UnreadBind, when set, keeps the count following a client
	// signal: the badge the server rendered at zero appears when the
	// signal changes it.
	UnreadBind *Bind
	// Opens, when set, is the widget name the anchor opens with
	// script: the same element is the no-script link (Href) and the
	// widget's trigger, rendered as the kernel's data-fui-open and a
	// bottom-anchored popover. A name carrying control bytes or
	// whitespace is refused — it is a widget key, not free text.
	Opens string
	// Icon is the glyph. The default bell is the structure's own; a
	// caller's SVG replaces it.
	Icon render.HTML

	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs and binds on the root, the icon, the badge and the
	// count. Strings carry the spoken count.
	Parts Parts
	// Strings are the strings this component says. Nil means the English
	// defaults; a layer above sets them from the request's language.
	Strings *Strings
}

type NumberInputProps struct {
	// Name is the form-field name. Required.
	Name string
	// Label is the visible label. Required: it names the control and
	// the two buttons (through NumberDecrement / NumberIncrement).
	Label string
	// Value is the initial value as text, so a decimal step's value
	// travels unchanged. Empty means no value. A value that is not a
	// number, or violates a supplied bound, is refused.
	Value string
	// Min and Max bound the value. Nil leaves the bound to the
	// server; a Min above a Max is refused.
	Min *int
	Max *int
	// Step is the stepper granularity. Default 1; positive only.
	Step int
	// Required and Disabled are the input's own states; Disabled also
	// takes the buttons out.
	Required bool
	Disabled bool
	// Help is the rule the value obeys; Error is the violation. Both
	// reach the input's description, the error first.
	Help  string
	Error string

	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs and binds on every part. Strings carry the two
	// buttons' names.
	Parts Parts
	// Strings are the strings this component says. Nil means the English
	// defaults; a layer above sets them from the request's language.
	Strings *Strings
}

type OptimisticActionProps struct {
	// Endpoint is the URL the click fires against. Required, and
	// same-origin (it must start with "/").
	Endpoint string
	// Method defaults to POST and may be PUT, PATCH or DELETE.
	Method string
	// IdleLabel is the text at rest. Required.
	IdleLabel string
	// SuccessLabel is the text painted the moment the button is
	// clicked. Required — and it must say something the idle label
	// does not, because the label flip IS the state change; colour
	// alone is never allowed to carry it.
	SuccessLabel string
	// IdleIcon and DoneIcon are decoration beside each label. Each
	// span carries its own so the flip swaps glyph and word together.
	IdleIcon render.HTML
	DoneIcon render.HTML
	// Variant and Size are class-map vocabulary, passed through so the
	// class map can look up "<part>--<variant>". The structure does not
	// care.
	Variant string
	Size    string
	// Disabled is the state at render time. The runtime manages it
	// from the first click: pending disables, settlement re-enables.
	Disabled bool
	// FailedText is what the status span announces when the server
	// refuses. Defaults to "Could not save. Try again."
	FailedText string

	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs only. Nothing is fillable — the two labels are
	// the state, and a slot that replaced one could make the button
	// say it did something it did not.
	Parts Parts
	// Strings are the strings this component says. Nil means the English
	// defaults; a layer above sets them from the request's language.
	Strings *Strings
}

type Option struct {
	// Value is what the option submits; Label is what it shows. They
	// are separate so the submitted key stays stable while the visible
	// text is edited.
	Value string
	Label string
}

type PageHeaderProps struct {
	// Title is the page's heading. Required: the header exists to
	// name the page, and a header with no heading is padding.
	Title string
	// Level is the heading level, 1 by default. The page's own header
	// is the h1; a header for a sub-page inside a page says 2 here
	// rather than leaving the outline to guess.
	Level int
	// Eyebrow is a short kicker above the title ("Customers"). It is
	// aria-hidden: it repeats what the title or the navigation
	// already says, in fewer words, and hearing both is hearing the
	// page's name twice.
	Eyebrow string
	// Subtitle is the supporting line under the title.
	Subtitle string
	// Badge is status content beside the heading, outside its accessible name.
	Badge render.HTML
	// Actions are the page-level controls — New, Import, Filter — in
	// the trailing slot. They apply to the page, not to an item in
	// it; an action about one row belongs on that row.
	Actions render.HTML

	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs and binds on every part the header draws.
	Parts Parts
}

type PaginationProps struct {
	// AriaLabel names the nav landmark for AT. Required: pagination
	// announced as "pagination" is how AT users find it at all.
	AriaLabel string
	// 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. When set it must
	// be same-origin and carry no query or fragment of its own: the
	// carry belongs in Query, where it survives the page turn, and a
	// Path query is silently replaced — a value lost with no error is
	// the defect this component exists to make structural.
	Path string
	// Query is the query the screen's URL already carries — the
	// search, the filters, the sort — and survives a page turn
	// beside the page number.
	Query url.Values
	// PageParam names the page query parameter. It 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

	// PrevLabel and NextLabel default to "Previous" and "Next".
	PrevLabel string
	NextLabel string

	// Island is where a page change goes when the pager sits inside
	// a region rather than being the page: the page anchors then
	// carry the RPC contract beside their hrefs — the page without
	// script, the region update with it, the URL written after the
	// swap. Optional, the Table posture: the URL is the truth for a
	// list, so a list screen's page anchors are plain navigations
	// the client router intercepts. An Island that looks wired and
	// is not is refused, whichever shape the pager renders.
	Island Island

	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs and binds on the root, the list and the gaps.
	// Strings carry the two end links.
	Parts Parts
	// Strings are the strings this component says. Nil means the English
	// defaults; a layer above sets them from the request's language.
	Strings *Strings
}

type PaneHostProps struct {
	// Primary is the always-visible pane. Required.
	Primary render.HTML
	// Secondary is the first optional side pane.
	Secondary render.HTML
	// Tertiary is the second optional side pane.
	Tertiary render.HTML
	// SecondaryOpen / TertiaryOpen set the SSR initial open state.
	SecondaryOpen bool
	TertiaryOpen  bool
	// SecondaryLabel / TertiaryLabel label each side pane's region.
	// Empty takes "Secondary" / "Tertiary".
	SecondaryLabel string
	TertiaryLabel  string
	// DeepLinkParam names the query parameter that carries pane state
	// for refresh/share/Back parity. Empty leaves the URL alone. A
	// non-token value (control bytes, markup, whitespace) is refused.
	DeepLinkParam string

	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs on the root and each pane.
	Parts Parts
}

type Part string

type PartAttrs map[Part]html.Attrs

type Parts struct {
	// Attrs add attributes to named parts. An attribute the component
	// owns is never beaten, and the keys refused on every way in are
	// refused here too (see refused).
	Attrs PartAttrs
	// Slots replace named parts' content. Only the parts a component
	// lists as fillable do anything; the rest are ignored rather than
	// silently half-applied.
	Slots Slots
	// Binds keep named parts in step with client signals: an
	// attribute anywhere the allow-lists allow, and text or html only
	// on a fillable part, where a Bind may replace what a Slot may.
	Binds Binds
}

type PasswordProps struct {
	Name        string
	Placeholder string
	Required    bool
	Disabled    bool
	Invalid     bool

	// ID lands on the inner input, not the shell: the shell is
	// styling, and a Field label's for= must point at the control.
	ID string
	// Extra attrs land on the inner input too (autocomplete,
	// inputmode): they are attributes of the control, and putting them
	// on the shell would swallow them.
	Extra       html.Attrs
	DescribedBy string

	// Parts: attrs and binds on the shell, the input and the
	// reveal button. Strings carry the reveal button's two
	// names).
	Parts Parts
	// Strings are the strings this component says. Nil means the English
	// defaults; a layer above sets them from the request's language.
	Strings *Strings
}

type ProgressProps struct {
	// Value is the current progress. 0 to Max renders a determinate
	// bar; a negative value renders an indeterminate one. A value
	// past Max is clamped to Max at render; NaN and the infinities
	// render indeterminate, because a number that is not a number
	// cannot label progress.
	Value float64
	// Max is the ceiling. 0 (and any non-finite or negative value)
	// takes 100.
	Max float64
	// Label names the bar for assistive tech. Required: a progress
	// bar with no name is a stripe a screen reader cannot identify.
	Label string
	// LabelVisible renders the label as text above the bar (wired to
	// the element through aria-labelledby) instead of an aria-label.
	LabelVisible bool
	// Description is an optional human sentence beside the bar ("73
	// of 100", "Uploading…"). Scrubbed, never refused: it is data a
	// request can carry.
	Description string

	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs on the root and the value. No part is fillable.
	Parts Parts
}

type RailItem struct {
	// Anchor is the fragment id of the section this entry links to,
	// without the leading #. Required: an entry that links nowhere is
	// not an entry.
	Anchor string
	// Text is the visible link label. Required.
	Text string
	// Eyebrow is the leading chip beside the label (a number, a
	// glyph); empty hides it.
	Eyebrow string
	// Count is the trailing chip (a document count); empty hides it.
	Count string
}

type RailProps struct {
	// Label names the landmark and heads the list. Required: a
	// complementary landmark with no name is a region a screen reader
	// cannot jump to by name.
	Label string
	// Items are the entries, in display order. Required and non-empty.
	Items []RailItem
	// ObserveSelector is the CSS selector of the region whose sections
	// the module watches to mark the active entry. Empty renders a
	// purely static rail: the links work, nothing is marked.
	ObserveSelector string
	// TargetSelector narrows which elements inside the observed region
	// count as sections. Empty takes the module's default (the
	// h2/h3/h4 elements that carry an id).
	TargetSelector string

	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs on the root and the entries. No part is fillable:
	// every element the rail draws carries its own guarantee.
	Parts Parts
}

type RangeSliderProps struct {
	// Name is the base form-field name. Two inputs ship, Name+"-min"
	// and Name+"-max", so the server receives the pair without
	// parsing a composite string.
	Name string
	// Label is the group's name, read by assistive technology and
	// built into each thumb's name (RangeLow / RangeHigh).
	Label string
	// Min, Max, Step as for Slider.
	Min  int
	Max  int
	Step int
	// ValueLow and ValueHigh are the thumbs' values. Both zero means
	// Min and Max. Values outside the bounds clamp to them, and a
	// crossed pair is ordered low, high — the same repair the module
	// makes of a dragged pair.
	ValueLow  int
	ValueHigh int
	// ShowValue renders the pair's one output sentence, from
	// RangeValue; the module keeps it in step using the same
	// sentence, which travels with the output.
	ShowValue bool
	// Disabled disables both thumbs.
	Disabled bool

	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs and binds on every part. Strings carry the two
	// thumbs' names and the output sentence.
	Parts Parts
	// Strings are the strings this component says. Nil means the English
	// defaults; a layer above sets them from the request's language.
	Strings *Strings
}

type RatingProps struct {
	// Name is the form-field name. Required; the group submits the
	// chosen value 1..Max under it.
	Name string
	// Label names the group for assistive technology. Required.
	Label string
	// Max is the ceiling. Default 5; below 1 is refused.
	Max int
	// Value is the current choice, 0 (none) to Max.
	Value int
	// Icon is the glyph cloned into every choice. The default is a
	// star; a caller's icon reaches every choice the same way.
	Icon render.HTML
	// Disabled disables every radio.
	Disabled bool

	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs and binds on every part. Strings carry each
	// choice's name (RatingChoice).
	Parts Parts
	// Strings are the strings this component says. Nil means the English
	// defaults; a layer above sets them from the request's language.
	Strings *Strings
}

type RepeaterItem struct {
	Fields []render.HTML
}

type RepeaterProps struct {
	// Name is the group's name. Required; the submit controls' names
	// derive from it when the caller does not give their own.
	Name string
	// Label names the group for assistive technology and names the
	// items region. Optional: a repeater beside its own heading may
	// not need one, though two unnamed repeaters on a page are two
	// identical entries in a landmarks list.
	Label string
	// Items are the rendered rows, in order.
	Items []RepeaterItem
	// MinItems is the floor below which removal is refused (the
	// remove controls render disabled). MaxItems is the ceiling above
	// which addition is refused. Zero MaxItems is unlimited.
	MinItems int
	MaxItems int
	// AddLabel and RemoveLabel override the add control's visible
	// text and the remove controls'; the remove control's accessible
	// name always carries its 1-based position.
	AddLabel    string
	RemoveLabel string
	// AddName and AddValue name the add control as a submit control
	// (a FormRepeater's "<Name>_add=1"); RemoveName names the remove
	// controls, whose value is the row's 0-based index. Empty names
	// render plain buttons the surrounding form does not carry.
	AddName    string
	AddValue   string
	RemoveName string
	// Action is the same-origin URL the add and remove operations go
	// to when the result swaps in place; it is required together with
	// Island and useless without it — a plain form repeater needs no
	// Action, because the surrounding form's own action is the
	// no-script destination and the submit controls ride it.
	Action string
	// Island is where an add or remove result lands. Required when
	// Action is set, refused half-wired like every Island.
	Island Island
	// Status is the sentence the live region carries — the server's
	// own words about the operation that just happened, re-rendered
	// with the region after an island swap.
	Status string

	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs and binds on every part. Strings carry the add
	// control's text and the remove controls' names.
	Parts Parts
	// Strings are the strings this component says. Nil means the English
	// defaults; a layer above sets them from the request's language.
	Strings *Strings
}

type Row struct {
	// ID lands on the <tr> as id=, for a keyed swap: successive
	// renders of a live table differ only on the rows that changed.
	ID string
	// Cells maps a column Key to the rendered cell HTML. A column
	// with no entry renders an empty cell; a key naming no column is
	// refused at render, because a silent drop hides a typo.
	Cells map[string]render.HTML
}

type SectionProps struct {
	// Title is the heading. It is also what makes this a landmark: a
	// section with a name is navigable, a section without one is noise
	// in the landmark list, so Section renders a plain div until it
	// has a title to be named by.
	Title string
	// Eyebrow is a short kicker above the title ("01 / Overview"). It
	// is aria-hidden: it decorates a heading the reader has already
	// heard, and reading both is hearing the section's name twice. A
	// section named by Label alone renders it too — the caller's
	// heading rides in the body, and the kicker decorates it from
	// above.
	Eyebrow string
	// Level is the heading level, 2 by default. It is a real decision
	// and not a style: heading levels are how a screen reader user
	// moves through a page, and a section under an <h1> that renders
	// an <h3> leaves a hole in the outline.
	Level int
	// Description is supporting text under the heading.
	Description string
	// DescriptionHTML is supporting text that carries markup — code,
	// links. When set it takes precedence over Description.
	DescriptionHTML render.HTML
	// Label names the region when there is no Title to name it by.
	// A named section without a heading is still a landmark; an
	// unnamed one renders as a plain div. With both set, Title wins:
	// the heading names the region and Label is not read.
	Label string
	// Actions sit opposite the heading — a button, a filter.
	Actions render.HTML
	Gap     string

	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs and binds on every part the region draws.
	Parts Parts
}

type SelectProps struct {
	Name string
	// DescribedBy is the aria-describedby a Field hands down. It is
	// the whole reason a hint or an error reaches assistive tech: the
	// text is on screen either way, but without this attribute a
	// screen reader user hears the label and nothing else — no
	// format hint, and no reason the control is red.
	DescribedBy string
	// Options is the list of choices.
	Options []Option
	// Selected marks the option whose Value it matches. Empty selects
	// the placeholder (or the first option when there is none).
	Selected string
	// Placeholder renders a disabled first option with an empty value.
	// That empty value is also what makes Required enforceable: the
	// browser reads it as unfilled.
	Placeholder string
	Required    bool
	Disabled    bool
	Invalid     bool

	ID    string
	Extra html.Attrs
}

type SidebarItem struct {
	// Label is the entry's text. Required.
	Label string
	// Href is the link's destination. Required for leaves; refused on
	// group parents (a group parent is a disclosure, not a link).
	Href string
	// Icon is optional inline HTML before the label.
	Icon render.HTML
	// Active marks the current page's link.
	Active bool
	// Open opens a group at SSR. Inert on leaves.
	Open bool
	// MatchPrefix, when non-empty, is emitted as the leaf link's
	// data-fui-match-prefix value: the runtime's active-link module
	// re-derives the item's current-state on sub-paths after a client
	// navigation, using this value (not the href) as the section
	// prefix. The caller resolves the active state for first paint;
	// this is the same rule, handed to the client.
	MatchPrefix string
	// Children make this entry a group. Mutually exclusive with Href.
	Children []SidebarItem
}

type SidebarProps struct {
	// NavLabel names the navigation landmark. Required.
	NavLabel string
	// Title is the optional heading above the list.
	Title string
	// Items, in order. Required non-empty.
	Items []SidebarItem
	// Variant names the layout posture: "persistent" (always shown),
	// "collapsible" (toggle collapses to a rail), "off-canvas"
	// (drawer-only), "auto-hide" (a rail at rest that reveals on hover
	// or focus — pure presentation, the sheet's own). Empty takes
	// persistent.
	Variant string
	// Collapse names the collapse behaviour for the collapsible
	// variant: "none" (server-owned state), "auto" (the module owns
	// and restores it). Empty takes none.
	Collapse string
	// ServerCollapsed ships the server-owned collapsed state for the
	// collapsible variant (data-collapsed on the root, aria-expanded
	// and the state-matched label on the toggle). Nil means the state
	// is not the server's to say here: with Collapse "auto" the module
	// restores it after hydration, and no data-collapsed ships.
	ServerCollapsed *bool
	// DrawerName names the widget the mobile drawer opens; empty
	// renders no drawer trigger (the caller mounts the drawer).
	DrawerName string
	// DrawerLabel names the drawer trigger button. Empty leaves the
	// trigger unnamed — a caller rendering the trigger passes the
	// words, this package says none of its own.
	DrawerLabel string
	// CollapseStorageKey names the storage the collapse state lives
	// in when Collapse is auto. Empty means server-owned: the module
	// never writes storage without it.
	CollapseStorageKey string
	// HideDrawerTrigger suppresses the drawer trigger button (a host
	// that opens the drawer from its own chrome).
	HideDrawerTrigger bool
	// CollapseLabel / ExpandLabel are the collapse toggle's two
	// accessible names, resolved by the caller. Both always ride the
	// button as data-hui-sidebar-collapse-label / -expand-label: the
	// module re-says them after a client-side toggle and carries no
	// sentence of its own. Empty falls back to NavLabel for the
	// button's initial aria-label.
	CollapseLabel string
	ExpandLabel   string
	// GroupMarkup selects the dialect for groups: "" or "details"
	// (native details + the disclosure module's persist key) or
	// "button" (aria-expanded + aria-controls + hidden, which the
	// sidebar module's group-toggle mirror owns).
	GroupMarkup string
	// GroupIDPrefix derives each group's id (the button dialect's
	// aria-controls target) and per-group persist key (the details
	// dialect), as <prefix>-g<N>. Empty takes DrawerName + "-inline",
	// or "sidebar-inline" when DrawerName is empty too.
	GroupIDPrefix string
	// Prepend / Footer are optional slots above and below the list.
	Prepend render.HTML
	Footer  render.HTML

	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs on the shell, the controls, the region's parts and
	// every item part.
	Parts Parts
}

type SkeletonProps struct {
	// Label is what is loading, announced once through a live region
	// — "Loading apps". Required for the same reason Spinner's is.
	Label string
	// Lines is how many bars to draw. Zero means one.
	Lines int
	// Shape is a class map hint: "text", "title", "block", "circle".
	Shape string

	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs and binds on the root and the bars.
	Parts Parts
}

type SliderProps struct {
	// Name is the form-field name. Required.
	Name string
	// Label is the visible label. Required.
	Label string
	// Min and Max bound the range. Both zero means 0..100; a Min
	// above or equal to a Max is refused.
	Min int
	Max int
	// Step is the granularity. Default 1; positive only.
	Step int
	// Value is the initial value. Outside the range clamps to the
	// nearest bound, the way the browser treats a dragged thumb; a
	// value between steps renders as given and snaps on first
	// interaction — the module mirrors whatever the thumb says, so
	// there is no disagreement to refuse.
	Value int
	// ShowValue renders the output beside the label and the hook the
	// module mirrors the live value through.
	ShowValue bool
	// ShowEdgeLabels renders Min and Max under the track.
	ShowEdgeLabels bool
	// Disabled disables the control.
	Disabled bool

	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs and binds on every part.
	Parts Parts
	// Strings are the strings this component says. Nil means the English
	// defaults; a layer above sets them from the request's language.
	Strings *Strings
}

type Slots map[Part]render.HTML

type SortDir string

type SortableItem struct {
	// Key is the stable identifier the server applies the new order
	// by. Required. It is data the database hands the page, not
	// configuration: a space, a quote, `#` or markup renders escaped
	// in its attribute and control bytes are scrubbed — only the
	// empty key refuses.
	Key string
	// Label is the row's visible text and the drag name. Required.
	Label string
	// Content, when set, replaces the label as the row's body. Use
	// for richer rows; the grip and the announcements still use
	// Label.
	Content render.HTML
}

type SortableListProps struct {
	// Items are the rows in initial order. May be empty: an empty
	// column renders a valid sortable <ol> with no rows and stays a
	// drop target.
	Items []SortableItem
	// Label is the list's accessible name. Required.
	Label string
	// RPCPath, when set, is POSTed after every successful reorder:
	// order=<comma-separated keys>, plus container=<id> when
	// Container is set, version=<token> when Version is set, and
	// moved=<key> on a cross-container drop. The server confirms with
	// 2xx or rejects (the DOM reverts).
	RPCPath string
	// Group is the board id shared by linked lists (kanban): lists
	// with the same non-empty Group accept cross-container drag and
	// keyboard moves between them, including into an empty one.
	Group string
	// Container is the per-column id sent as the container field so
	// the server can route the write without inferring the column
	// from the key set. Distinct from Group because a board has one
	// Group and N containers.
	Container string
	// Version is an optional optimistic-concurrency token appended to
	// every commit. When set, a 409 fires the conflict path instead
	// of a blanket rollback.
	Version string
	// ConflictRPC, alongside Version, is GET-fetched on a 409: the
	// response body (fresh rows) replaces the list's contents,
	// server-rendered reconciliation. Without it a 409 falls back to
	// rollback.
	ConflictRPC string

	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs on the root and the rows. No part is fillable:
	// the rows are the caller's data.
	Parts   Parts
	Strings *Strings
}

type SpacerProps struct {
	// Grow is how much of the row's slack this spacer takes against
	// its growing siblings. 1 through 4 — 0 is refused because a
	// spacer that cannot grow is a typo rather than a choice (the
	// typed Spacer defaults it to 1), and above 4 is refused because
	// the stylesheet wires exactly those four factors: a number the
	// sheet does not carry would be a factor that renders as 1.
	//
	// It travels as data-hui-grow rather than a style, because an
	// inline style is a rule the CSP drops and a class per factor is
	// a class the class map has to enumerate from a number it cannot see.
	Grow int
	// Min and Max bound the space, as names from the gap scale rather
	// than lengths: a spacer with a floor keeps a contents list legible
	// when the value is missing, and one with a ceiling keeps two
	// distant words from being pushed to the edges of the screen.
	Min string
	Max string
	// Leader draws a dotted line across the space — the leader between
	// a term and its value in a contents list, which is what ties the
	// two together once the row is wider than the pair.
	Leader bool
	// Rule draws a hairline rule across the space, for when the line
	// should read as a divider-in-waiting rather than a tie. A leader
	// and a rule in the same space are two answers to one question,
	// and are refused together.
	Rule bool

	ID         string
	ExtraAttrs html.Attrs
}

type Spec struct {
	// Name is the exported function's name, exactly. The coverage
	// gate matches on it.
	Name string
	// Anatomy lists the parts this component draws. A class map styles these
	// and only these; a part listed here and never rendered is a
	// class in the stylesheet with nothing to land on.
	Anatomy []Part
	// Fillable are the parts a caller may replace through Slots. The
	// empty set is the correct answer for most components: a slot is
	// offered where the component's own content carries no guarantee.
	Fillable []Part
	// Hooks are the data-hui-* attributes this component publishes for
	// the runtime. Naming them here is what lets a test prove the
	// runtime is not bound to an attribute nothing renders.
	Hooks []string
	// WithParts renders the component with a caller's Parts applied.
	// A component that offers its parts must provide it: it is how the
	// harness proves that filling a slot or adding an attribute cannot
	// break the contract, and a part nothing tests is a part that will.
	WithParts func(s Classes, parts Parts) render.HTML
	// Cases renders the component at a given Classes. A nil Classes means
	// unstyled, which is what the contract is asserted against.
	Cases func(k Kit) []Case
}

type SpinnerProps struct {
	// Label says what is being waited for — "Loading apps". Required,
	// and it is not decoration: a spinner with no label is a moving
	// shape that tells a screen reader user nothing at all, and the
	// one thing they need to know is that waiting is the correct thing
	// to be doing right now.
	Label string
	// Announce puts the label in a live region, so it is read when the
	// spinner appears. Off by default: a spinner rendered WITH the
	// page has not "happened" — the same rule Alert follows — and
	// announcing it on load talks over the page.
	//
	// Turn it on for a spinner that replaces content after an action.
	Announce bool
	// Size is a class-map hint ("sm", "lg").
	Size string
	// Variant is the animated shape, a class-map hint: "" draws a
	// bordered ring, "dots" three pulsing dots, "grid" a rippling
	// square of nine. Every shape is aria-hidden — the shape is a
	// picture of waiting and the label is what waiting is FOR.
	Variant string

	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs and binds on the root and the shape.
	Parts Parts
}

type StackProps struct {
	// Gap is a name from the scale, passed through to the class map. It is
	// not a length, because a system with arbitrary gaps has no
	// rhythm — and the one the framework ships proves the point: its
	// Grid takes a free-form Min that nothing ever read.
	Gap string
	// Align is cross-axis alignment: "start", "center", "end". Empty
	// stretches, which is what a stack of cards wants.
	Align string
	// Justify is main-axis distribution: "start", "center", "end",
	// "between". Empty packs to the start, which is what a page's
	// blocks do.
	Justify string
	// Tag overrides the element. A list of things should be a list;
	// this is how a Stack becomes one without a second component.
	Tag string

	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs and binds on the root.
	Parts Parts
}

type StatCardProps struct {
	// Label says what is counted. Required.
	Label string
	// Value is the number, formatted by the caller. Required: a stat
	// card with no value is a label in a box.
	Value string
	// Trend is the movement ("+12% vs. last week"). Optional.
	Trend string
	// Direction names which way the trend reads — "up", "down" or
	// "flat". The trend's colour is the class map's to draw from it;
	// the direction must also be in the Trend's own words for a
	// reader who cannot see the colour, which is why Direction is a
	// variant hint and never the only carrier of meaning.
	Direction string

	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs and binds on every part the card draws. The value
	// is the part a dashboard binds to a signal.
	Parts Parts
}

type Step struct {
	// Label is the step's name. Required.
	Label string
	// Hint is the supporting line under the label.
	Hint string
	// Href makes the step a link — a completed step the reader can go
	// back to. Every href goes through the anchor policy; one the
	// policy refuses is the developer's mistake, said at render like
	// every configured href in this package.
	Href string
	// Marker overrides the glyph in the marker circle — a zero-padded
	// number ("01"), a caller's check icon. It is aria-hidden either
	// way: the marker is a picture of the step's state, and the label
	// beside it is what a reader hears.
	Marker render.HTML
	// State overrides the state derived from Current: "done",
	// "current" or "todo". Empty derives. An explicit state is how a
	// rail says a later step finished while an earlier one is still
	// open.
	State string
}

type StepWizardProps struct {
	// Steps is the flow. At least one.
	Steps []WizardStep
	// Current is the 0-based step in progress. Outside the list is
	// refused.
	Current int
	// Action and Method are the form's own. Method defaults to POST;
	// anything but GET or POST is refused.
	Action string
	Method string
	// HiddenFields carry state between steps.
	HiddenFields []render.HTML
	// Errors is the rendered validation summary for a failed submit.
	// When set, ID is required and the form asks the runtime to move
	// focus to the summary on arrival.
	Errors render.HTML

	// Island, when set, makes the submit a region update: the same
	// form, the same controls, the answer swapped into the signal.
	// Partial is refused like every Island.
	Island Island

	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs and binds on every part. Strings carry the three
	// controls, the rail's name and each dot's.
	Parts Parts
	// Strings are the strings this component says. Nil means the English
	// defaults; a layer above sets them from the request's language.
	Strings *Strings
}

type StepsProps struct {
	// Steps are the entries in order. At least one.
	Steps []Step
	// Current is the 1-based step in progress: the steps before it are
	// done, it is current, the rest are todo. 0 means nothing has
	// started yet. Must not exceed len(Steps).
	Current int

	ID         string
	ExtraAttrs html.Attrs
}

type Strings struct {

	// DismissTitled names a dismiss control whose target follows it:
	// an Alert's, a SystemBanner's. The title follows the colon and a
	// space; a format taking it as %s.
	DismissTitled string
	// RemoveLabelled names a remove control by what it removes: a
	// Tag's chip. A format taking the value's name as %s.
	RemoveLabelled string

	// ActionFailed is what a failed mutation announces when the caller
	// supplied nothing better. A sentence, not a word: it says the
	// save did not happen and that trying again is allowed.
	ActionFailed string

	// PickColor names the colour swatch, which carries no visible
	// label. A format taking the field's name as %s.
	PickColor string

	// ShowPassword and HidePassword name the reveal button in each of
	// its two states. Imperative, not rendered visually; they also
	// travel as data so the runtime can swap them.
	ShowPassword string
	HidePassword string
	// RevealShow is the reveal button's visible text, and RevealHide
	// is what the runtime swaps it to. One word each; RevealHide is
	// never rendered by the server.
	RevealShow string
	RevealHide string

	// Previous and Next label the pager's ends, which are disabled
	// anchors rather than absent ones. One word each; they carry no
	// arrows, so a translation may add its own.
	Previous string
	Next     string

	// ToneInfo, ToneSuccess, ToneWarning and ToneDanger are the tone
	// said before a title — a SystemBanner's, and an Alert's when the
	// caller passes one as ToneWord — because the title says WHAT
	// happened and the
	// tone is the only thing saying how serious it is. One word each,
	// the one a reader understands rather than the stylesheet's name
	// for the colour ("Error", not "Danger"); the colon and space that
	// follow are added in the assembly.
	ToneInfo    string
	ToneSuccess string
	ToneWarning string
	ToneDanger  string

	// FileSelected says one file was chosen, with {name} where the
	// file's name goes. The runtime writes the name in when it knows
	// it; the server never renders this string with a value in it,
	// because before the reader picks there is no value to say.
	FileSelected string
	// FilesSelected says several files were chosen, with {n} for the
	// count and {names} for the joined list. Substituted by the runtime
	// like FileSelected's {name}, for the same reason: neither the
	// count nor the names exist until the reader has picked.
	FilesSelected string

	// LightboxViewerLabel is the accessible name of the open image
	// viewer: what a screen reader says when the viewer takes focus.
	// A short noun phrase; the image's own alt travels beside it.
	LightboxViewerLabel string
	// LightboxPrevious and LightboxNext name the viewer's nav buttons.
	// They name the action on this surface ("Previous image"), not the
	// pager's bare word: a reader inside a viewer needs to know what
	// stepping moves.
	LightboxPrevious string
	LightboxNext     string
	// LightboxDownload names the anchor that saves the image being
	// viewed.
	LightboxDownload string

	// TableSortBy names a sort control whose column carries no
	// visible header text: an actions or icon column that can still
	// be sorted. A format taking the column's Key as {column}; the
	// token is written in at render, when the anchor is built —
	// unlike the {n} the runtime substitutes, the key is known on
	// the server.
	TableSortBy string
	// TableSortedBy says what a changed table is now sorted by, with
	// {column} where the column's header goes and {direction} where
	// the direction word goes. Rendered into data-hui-table-announcement
	// at render and copied into the status after a swap, so a
	// translated page announces in its own language.
	TableSortedBy string
	// SortAscending and SortDescending are the direction words
	// TableSortedBy carries. One lowercase word each: they sit inside
	// a sentence, after a comma.
	SortAscending  string
	SortDescending string

	// CounterLabel names the counter group, which carries no visible
	// label of its own. One noun.
	CounterLabel string
	// CounterDecrement and CounterIncrement name the counter's two
	// buttons. One word each; the counter's value is the context.
	CounterDecrement string
	CounterIncrement string

	// BackToTop names the back-to-top anchor, whose glyph carries no
	// words. A short imperative.
	BackToTop string

	// NumberDecrement and NumberIncrement name the stepper's two
	// buttons, which need the field's name to tell them from any
	// other stepper's. Formats taking the label as %s.
	NumberDecrement string
	NumberIncrement string

	// RangeLow and RangeHigh name the two thumbs of a range pair —
	// "Minimum %s" and "Maximum %s", the label standing in for the
	// thing bounded. RangeValue is the pair's one output sentence,
	// "%s to %s", low first.
	RangeLow   string
	RangeHigh  string
	RangeValue string

	// RatingChoice names one rating radio: "%d out of %d", the chosen
	// value and the ceiling.
	RatingChoice string

	// TagInputAdd names the control that commits the draft, a format
	// taking the field's label as %s. TagInputAdded and
	// TagInputRemoved are what the status region says after a chip
	// operation, with {name} where the chip's text goes — the runtime
	// writes it when the operation has happened.
	TagInputAdd     string
	TagInputAdded   string
	TagInputRemoved string

	// RepeaterAdd names the add control. RepeaterRemove names one
	// remove control, a format taking the item's 1-based position as
	// %d, because twelve controls all called Remove tell a screen
	// reader user nothing.
	RepeaterAdd    string
	RepeaterRemove string

	// NotificationCount is the bell's accessible name, "%d unread
	// notifications" — the count the anchor carries, said in words.
	NotificationCount string

	// StepBack, StepNext and StepSubmit are the wizard's three
	// controls; Next is the one weighted action until the last step
	// makes it Submit. StepOf is the rail's name, "Step %d of %d",
	// and StepName is one dot's, "Step %d: %s" with the step's
	// heading as %s.
	StepBack   string
	StepNext   string
	StepSubmit string
	StepOf     string
	StepName   string

	// TableOfContentsLabel names the contents navigation, which is a
	// landmark a screen reader jumps to by name. A short prepositional
	// phrase naming what the list is of.
	TableOfContentsLabel string

	// ComboboxLoading is what the status region says while results
	// are being fetched. One word or a short phrase.
	ComboboxLoading string
	// ComboboxNoResults is what the status region says when a query
	// matched nothing.
	ComboboxNoResults string
	// ComboboxResultCount announces how many results a query found,
	// "{n}" where the count goes — the module writes the count in when
	// the results arrive, so the sentence travels as an attribute and
	// the placeholder is a name, not a fmt verb.
	ComboboxResultCount string
	// ComboboxResultsLabel names the listbox: "<Label> results" is
	// assembled at render, so the word here is the noun.
	ComboboxResultsLabel string

	// CarouselSlide names one slide and the total, "Slide {n} of
	// {total}" — {n} and {total} are filled at render (the module
	// re-says it into the status after each step).
	CarouselSlide string
	// CarouselGoTo names a dot control, "Go to slide {n}".
	CarouselGoTo string

	// JSONObject names an object node in a JSON tree. One word.
	JSONObject string
	// JSONArray names an array node in a JSON tree. One word.
	JSONArray string
	// JSONNull is the null literal. One word.
	JSONNull string
	// JSONTrue / JSONFalse are the boolean literals. One word each.
	JSONTrue  string
	JSONFalse string
	// JSONEmptyObject / JSONEmptyArray are what an empty collection
	// renders: the literal braces/brackets. One token each.
	JSONEmptyObject string
	JSONEmptyArray  string
	// JSONTruncated is the mark a truncated string ends with.
	JSONTruncated string

	// ThereIsAProblem heads the list a failed submit focuses. A short
	// sentence; it names the fact, the list names each field.
	ThereIsAProblem string

	// BreadcrumbsLabel names the trail's navigation landmark, which a
	// screen reader jumps to by name. One word.
	BreadcrumbsLabel string

	// SortableItemRole is the roledescription every row carries: it
	// tells a screen reader what kind of thing the row is before any
	// key is pressed. Two words.
	SortableItemRole string
	// SortableDragLabel names one row by what it offers: a format
	// taking the row's visible label as %s, applied at render.
	SortableDragLabel string
	// SortableGrabbed is said when a row is picked up, with {label}
	// where the row's name goes. Substituted by the runtime when the
	// grab happens, so the sentence travels as an attribute.
	SortableGrabbed string
	// SortablePosition says where the grabbed row now is, with
	// {position} and {list} (the list's own name) written in by the
	// runtime after each move.
	SortablePosition string
	// SortableMoved says the row changed lists, with {list} and
	// {position}: the kanban crossing, announced after it lands.
	SortableMoved string
	// SortableSaved confirms a commit the server accepted.
	SortableSaved string
	// SortableReverted says a failed commit put the rows back.
	SortableReverted string
	// SortableCancelled says Esc put the grabbed row back where it
	// started, uncommitted.
	SortableCancelled string
	// SortableConflictReverted says a 409 was reconciled by putting
	// the rows back.
	SortableConflictReverted string
	// SortableConflictRefreshed says a 409 was reconciled by
	// replacing the list with the server's own rows.
	SortableConflictRefreshed string

	// MultiSelectPlaceholder is what the chips strip says when
	// nothing is picked. A short phrase; the chips replace it the
	// moment one is.
	MultiSelectPlaceholder string
	// MultiSelectRemoveLabel names a chip's remove control, with
	// {label} where the picked option's name goes — the runtime
	// writes it in when it builds the chip.
	MultiSelectRemoveLabel string
}

type SwitchProps struct {
	// Name is the key the switch submits under when on.
	Name string
	// Value overrides what an on switch submits. Empty submits "on",
	// the HTML default, which is right for a lone "email me" toggle.
	Value string
	// Label is the visible text beside the track. Required, same rule
	// as every choice.
	Label    string
	Checked  bool
	Disabled bool

	ID string
	// Extra attrs land on the input, the control that submits.
	Extra html.Attrs
}

type SystemBannerProps struct {
	// ID is the message's identity, not just the element's: the
	// runtime remembers it so the same message is not shown twice.
	// Required.
	ID string
	// Tone is "info" (the default), "warning", "danger" or
	// "success". The class map looks it up as root--<tone>, and the word
	// a screen reader hears is derived from it, so a tone nobody
	// spelled is refused rather than silently rendered untinted.
	Tone string
	// Title is the headline. Required: "Connection lost" is the
	// message; the detail is detail.
	Title string
	// Text is the detail, in prose.
	Text string
	// Action is the one control the message offers — "Retry now",
	// "View the deploy". One, because a system banner is a bar
	// across the top of the page, not a form.
	Action render.HTML
	// Dismiss renders the dismiss button. Nil means yes: a system
	// message the reader cannot send away is furniture that outstays
	// its news, and the cases that want it gone — the offline
	// banner, whose ending is the reconnect — say so explicitly:
	// Dismiss on an Offline banner is refused at render.
	Dismiss *bool
	// DismissLabel names the dismiss control. Defaults to
	// "Dismiss: <Title>", because three banners each called
	// "Dismiss" say which nothing.
	DismissLabel string
	// Shown renders the banner visible. The default is hidden: the
	// banner ships hidden and something shows it.
	Shown bool
	// Icon is decoration beside the title, hidden from assistive
	// technology (the tone word in words carries the severity).
	Icon render.HTML
	// Offline marks this banner as the built-in connection message.
	// The root carries data-hui-system-offline for the module that
	// binds it to show when the framework reports the connection lost
	// and hide on reconnect — so it always ships hidden, and Shown on
	// an Offline banner is refused: that module owns it.
	Offline bool

	ExtraAttrs html.Attrs

	// Parts: attrs only. Nothing here is fillable — Action
	// already takes the page's own control, and everything else a
	// banner draws is what a screen reader is given to tell one
	// message from another.
	Parts Parts
	// Strings are the strings this component says. Nil means the English
	// defaults; a layer above sets them from the request's language.
	Strings *Strings
}

type TOCItem struct {
	// ID is the fragment id of the heading this entry links to,
	// without the leading #. Required.
	ID string
	// Label is the entry's visible text. Required.
	Label string
	// Level is the heading's level, 1 to 6; 0 takes 2. It names the
	// item's variant (h2, h3, …) so a class map can indent by depth.
	Level int
}

type Tab struct {
	// Label is the tab's visible text. Required.
	Label string
	// Panel is the tab's panel content.
	Panel render.HTML
	// Href overrides the fragment href (a same-origin deep link).
	Href string
	// Disabled removes the tab from the keyboard rotation.
	Disabled bool
}

type TableOfContentsProps struct {
	// Label names the landmark. Empty takes
	// Strings.TableOfContentsLabel.
	Label string
	// Items are the entries, in document order. Required and
	// non-empty: an empty contents landmark is a name with nothing
	// under it, and the no-script contract is the rendered list.
	Items []TOCItem
	// TargetSelector is the CSS selector of the content region whose
	// headings the module watches to mark the active entry. Empty
	// renders a purely static list: every link works, nothing is
	// marked.
	TargetSelector string

	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs on the root and the entries. No part is fillable:
	// the list is the contract.
	Parts   Parts
	Strings *Strings
}

type TableProps struct {
	// Columns is the column definitions. Required.
	Columns []Column
	// Rows is the rendered rows.
	Rows []Row
	// Caption is the table's caption: text, escaped. A table is named
	// by its caption and by nothing else — there is no AriaLabel —
	// and a caller who wants the table named gives one.
	Caption string

	// SortBy is the active sort column's Key. Empty means no column
	// is sorted.
	SortBy string
	// SortDir is the active sort's direction. Empty means ascending,
	// the direction an inactive column's anchor sorts by.
	SortDir SortDir

	// 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. When set it must
	// be same-origin: a sort anchor pointing off-origin is a mistake
	// refused at render.
	Path string
	// Query is the query the screen's URL already carries — the
	// search, the filters, the page — and survives a sort beside the
	// sort keys.
	Query url.Values
	// SortParam and DirParam name the sort key and direction
	// parameters. They default to "sort" and "dir".
	SortParam string
	DirParam  string

	// Island is where a sort goes when the table is embedded in a
	// region rather than being the page: the sort anchors then carry
	// the RPC contract beside their hrefs — the page without script,
	// the region update with it, the URL written after the swap.
	// Optional, the Form posture: the URL is the truth for a list,
	// and a list screen's sort anchors are plain navigations the
	// client router intercepts when script is present. An Island
	// that looks wired and is not is refused, whichever shape the
	// table renders.
	Island Island

	// Empty renders in the body's one row when there are no rows, in
	// a cell spanning every column. Nil renders an empty <tbody>;
	// the head stays either way — an empty result still has named
	// columns, and the sort controls stay usable.
	Empty render.HTML
	// Summary is a sentence about the result window the caller owns,
	// e.g. "Showing 8 of 10". Appended to the sort sentence the
	// announcement carries, with a space, when given: the primitive
	// knows the sort, and only the caller knows the window.
	Summary string
	// Footer renders after the scroll region, as its sibling inside
	// the root, never inside the table, so a pager's nav landmark
	// never nests in a table. Nil renders nothing — the scroll region
	// is the root's only child.
	Footer render.HTML

	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs on every part. Nothing here is fillable — the
	// cells are the caller's own content, and a slot that replaced a
	// header would drop the sort control inside it.
	Parts Parts
	// Strings are the strings this component says. Nil means the English
	// defaults; a layer above sets them from the request's language.
	Strings *Strings
}

type TabsProps struct {
	// Name is the signal the selection lives in. Required: the strip's
	// whole contract is that clicking a tab writes the signal and the
	// wrapper mirrors it.
	Name string
	// Tabs, in order. Required, at least one.
	Tabs []Tab
	// Active is the selected tab's index. Out-of-range takes 0.
	Active int
	// VacateHidden ships hidden panels EMPTY with their content in an
	// adjacent JSON stash the module restores on first show, so
	// page-scoped locators cannot match hidden text.
	VacateHidden bool
	// StateAttrs mirrors data-state="active"/"inactive" onto every tab
	// after client-side switches, the attribute Radix-style ports pin
	// their locators to.
	StateAttrs bool
	// ID is the prefix the tab and panel ids derive from ("<ID>-tab-<n>"
	// and "<ID>-panel-<n>"). Empty takes Name; a page with two strips
	// on one signal-distinct name can still disambiguate ids with it.
	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs on the root, the tabs and the panels.
	Parts Parts
}

type TagInputProps struct {
	// Name is the form-field name. Required: every committed value
	// submits under it, as the standard repeated-key pattern.
	Name string
	// Label is the visible label. Required.
	Label string
	// Values are the committed tags, rendered as chips and as hidden
	// inputs — the list on screen and the values in the form are the
	// same set, which is the whole point of rendering the chips at
	// all: what a reader sees remove is what a submit stops carrying.
	Values []string
	// Placeholder is the draft input's placeholder. A placeholder is
	// not a name; the label is.
	Placeholder string
	// MaxLength caps one tag's length, in characters. Zero is no cap;
	// negative is refused. The cap applies to the rendered values
	// too, so a server value longer than the cap cannot submit
	// unchanged while a typed one is refused.
	MaxLength int
	// Help is the rule the values obey.
	Help string
	// Disabled takes the chips' remove controls, the draft input and
	// the add control out.
	Disabled bool

	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs and binds on every part. Strings carry the add
	// control's name, the remove controls' names, and the two
	// sentences the status says after a chip operation.
	Parts Parts
	// Strings are the strings this component says. Nil means the English
	// defaults; a layer above sets them from the request's language.
	Strings *Strings
}

type TagProps struct {
	// Label is the visible text. Required.
	Label string
	// Icon renders before the label.
	Icon render.HTML
	// DismissHref adds the dismiss control, an × that keeps a real
	// href: removing a filter is the server's decision, and the href
	// is the dismiss that needs no script.
	DismissHref string
	// Island is where the dismiss goes with script: removing a filter
	// is an in-page state change, so the × carries the RPC contract
	// beside its href — the page without script, the region update
	// with it, and the URL written after the swap. Required when
	// DismissHref is set; ignored otherwise.
	Island Island
	// DismissAriaLabel names the × for screen readers. Defaults to
	// "Remove <Label>".
	DismissAriaLabel string
	// Href makes the whole chip an anchor — a filter link — with the
	// label and any dismiss inside it. The same anchor policy as
	// every href this package writes; one chip, one label, whatever
	// shape it renders.
	Href string

	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs and binds on the root and the dismiss control.
	// Strings carry the dismiss control's name.
	Parts Parts
	// Strings are the strings this component says. Nil means the English
	// defaults; a layer above sets them from the request's language.
	Strings *Strings
}

type TextareaProps struct {
	Name string
	// DescribedBy is the aria-describedby a Field hands down. It is
	// the whole reason a hint or an error reaches assistive tech: the
	// text is on screen either way, but without this attribute a
	// screen reader user hears the label and nothing else — no
	// format hint, and no reason the control is red.
	DescribedBy string
	Value       string
	// Placeholder is the prompt shown when empty.
	Placeholder string
	// Rows sets the rows attribute. Zero omits it and lets the
	// stylesheet size the box, so an unspecified height stays the
	// system's decision rather than the caller's guess.
	Rows     int
	Required bool
	Disabled bool
	Invalid  bool
	// Autogrow opts the control into the core runtime's auto-resize
	// (textarea.js: every input event resets the height to the
	// scrollHeight, so the field always shows all its content). It is
	// the one data-fui-* attribute a component here renders, and it
	// is a prop rather than an extra because every seam a caller can
	// reach — Safe, the part-attrs sanitiser — refuses the prefix
	// precisely so decoration cannot become a request; autogrow is a
	// behaviour of the control itself, not a decoration, and the
	// styled layer's TextArea has no other way to say it.
	Autogrow bool

	ID    string
	Extra html.Attrs
}

type TimelineProps struct {
	// Label names the list for assistive tech — "Deploy history".
	Label  string
	Events []Event

	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs and binds on the list and every part it draws.
	Parts Parts
}

type ToastProps struct {
	// Tone is one of info, success, warning, danger. The class map
	// colours the row from it; the tone word carries it to a reader.
	Tone string
	// Icon is the decorative glyph, hidden from readers: the tone
	// word is what tells them the kind of news. Empty renders no icon.
	Icon render.HTML
	// Title is the headline; Body is the detail. One of them is
	// required — a toast that says nothing is decoration.
	Title string
	Body  string
	// DismissHref makes the toast dismissable with a link that keeps
	// a real href, and requires a complete Island: dismissing an
	// in-page region is an in-page state change, never a route.
	DismissHref  string
	DismissLabel string
	// TTLMS is how long the module keeps the toast before it goes, on
	// the runtime path. Zero means it stays until dismissed. Negative
	// is refused.
	TTLMS int
	// Live is how the toast interrupts. The default is polite: a
	// toast is an arrival, and arrivals wait their turn; assertive is
	// for the failures a reader must hear before doing anything else.
	Live Live

	// Island is where the dismiss goes with script. Required when
	// DismissHref is set; ignored otherwise.
	Island Island

	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs and binds on every part. Strings carry the tone
	// word and the dismiss control's name.
	Parts Parts
	// Strings are the strings this component says. Nil means the English
	// defaults; a layer above sets them from the request's language.
	Strings *Strings
}

type ToastStackProps struct {
	// Label names the stack for assistive technology. Required: the
	// stack is a landmark a reader can jump to, and an unnamed one is
	// a hole.
	Label string
	// Toasts are the rendered rows. The runtime path inserts into the
	// stack; the server-rendered rows are already home.
	Toasts []render.HTML
	// Max is how many rows the module keeps before dropping the
	// oldest. Default 4; zero takes the default; negative is refused.
	Max int

	ID         string
	ExtraAttrs html.Attrs
	Parts      Parts
	// Strings carry the dismiss label template a runtime-inserted
	// toast names itself by ("%s" where the toast's title goes).
	Strings *Strings
}

type ToggleActionProps struct {
	// Endpoint is the URL hit when toggling idle → committed.
	// Required, and same-origin.
	Endpoint string
	// Method defaults to POST and may be PUT, PATCH or DELETE. It
	// applies to both the commit and the untoggle request.
	Method string
	// IdleLabel is the text in the un-committed state. Required.
	IdleLabel string
	// CommittedLabel is the text while committed. Required, and it
	// must differ from IdleLabel: the flip is the signal.
	CommittedLabel string
	// IdleIcon and DoneIcon are decoration beside each label.
	IdleIcon render.HTML
	DoneIcon render.HTML
	// Committed is the state the server knows: render it true when
	// the action is already active, so first paint matches server
	// state instead of flashing through the wrong label.
	Committed bool
	// Group, when set, joins this button to a client-side mutex:
	// committing any button with the same key reverts the
	// previously-committed sibling, with no second request.
	Group string
	// AllowUntoggle lets a click on a committed button revert it to
	// idle. Without it (and without UntoggleEndpoint) the button is
	// sticky once committed, like OptimisticAction.
	AllowUntoggle bool
	// UntoggleEndpoint is the URL hit when reverting committed →
	// idle. Setting it implies AllowUntoggle; when empty the revert
	// flips locally with no request.
	UntoggleEndpoint string
	// Variant and Size are class-map vocabulary.
	Variant string
	Size    string
	// Disabled is the state at render time.
	Disabled bool
	// FailedText is what the status span announces on a failure.
	FailedText string

	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs only, for the same reason as
	// OptimisticActionProps.
	Parts Parts
	// Strings are the strings this component says. Nil means the English
	// defaults; a layer above sets them from the request's language.
	Strings *Strings
}

type ToolbarProps struct {
	ID         string
	ExtraAttrs html.Attrs
}

type ToolbarSearchProps struct {
	// Island is required: a search refilters the list the toolbar
	// sits on, which is an in-page state change — never a route.
	Island Island
}

type TreeNode struct {
	// ID is unique within the tree and becomes the treeitem's element
	// id. Required, and a bare id: letters, digits, `-`, `_` — a
	// space, quote, `#` or markup refuses at render. Unlike
	// SortableItem.Key this is not data: the id pairs with
	// href="#<id>" fragments and signal names, so slugify stored
	// values before they reach the tree.
	ID string
	// Label is the row's visible text. Required.
	Label string
	// Href, when set, makes the row's label a link. A branch with
	// Href keeps its toggle; a dangerous href degrades to a plain
	// label rather than a clickable vector.
	Href string
	// Children are statically-known descendants. Empty for leaves.
	Children []TreeNode
	// LazyPath, when set and Children is empty, makes this a branch
	// whose children load on first expand: the toggle carries the
	// kernel's rpc wiring against LazyPath and the child group is
	// bound to the signal the response swaps in. Children wins when
	// both are set — the children are already there.
	LazyPath string
	// Expanded forces the branch open on first paint.
	Expanded bool
	// Selected sets aria-selected="true" on the treeitem.
	Selected bool
}

type TreeProps struct {
	// Label is the aria-label on the role="tree" wrapper. Required.
	Label string
	// Nodes are the root-level entries. Required and non-empty: a
	// tree with nothing in it is a landmark that says nothing.
	Nodes []TreeNode
	// LazySignalPrefix names the signal namespace the lazy branches
	// bind their child groups to (each lazy branch's group carries
	// data-fui-signal="<prefix>-<node-id>"). Required when any node
	// uses LazyPath, ignored otherwise.
	LazySignalPrefix string

	// ID is the tree wrapper's element id. Required.
	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs on the root and the rows. No part is fillable: the
	// tree is the contract.
	Parts Parts
}

type ValidationSummaryProps struct {
	// Title heads the summary. Defaults to "There is a problem".
	Title string
	// Level is the title's heading level, 2 by default.
	Level  int
	Errors []FieldError
	// ID names the summary's root. Required, like the control ids the
	// errors link to: the title's id is derived from it, and two
	// summaries on one page without ids would share one title id —
	// breaking both labels and both announcements.
	ID         string
	ExtraAttrs html.Attrs

	// Parts: attrs and binds on the root, the title, the list and
	// its items. Strings carry the title a failed submit
	// focuses).
	Parts Parts
	// Strings are the strings this component says. Nil means the English
	// defaults; a layer above sets them from the request's language.
	Strings *Strings
}

type WizardStep struct {
	// Heading is the step's name. Required: the rail's dots and the
	// step's own heading say it, and a step with no name is a
	// nameless place in a flow.
	Heading string
	// Description is the supporting line under the heading.
	Description string
	// Fields are the step's form fields.
	Fields []render.HTML
}