ui

type Align string

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

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

	// ObserveSelector is the CSS selector for the container the
	// scrollspy runtime watches for in-view sections. Typically the
	// id of a wrapper around the sections (e.g. "#docs-sections"). If
	// empty, scrollspy is skipped and the rail is purely static — the
	// runtime then can't track active state.
	ObserveSelector string

	// TargetSelector overrides the default ".ui-section[id]" — set it
	// when the sections aren't ui.Section calls.
	TargetSelector string

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

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

type AnimatedCounterConfig struct {
	// To is the target value (required).
	To int
	// From is the starting value during animation. Default 0.
	From int
	// DurationMs is the animation length. Default 1200.
	DurationMs int
	// Prefix / Suffix are static strings on either side (e.g.
	// Prefix="$", Suffix="+", Suffix=" users").
	Prefix string
	Suffix string
	// ID / Class / Attrs are passed through.
	ID         string
	Class      string
	ExtraAttrs html.Attrs
}

type AspectRatio string

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

	// Class adds extra CSS classes.
	Class string

	// ID sets the element id.
	ID string
}

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

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

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

	ID    string
	Class string
}

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

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

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

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

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

	ID    string
	Class string
}

type AvatarSize string

type AvatarStatus string

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

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

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

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

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

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

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

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

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

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

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

type BackToTopOffset string

type BackToTopPosition string

type BackToTopScrollBehavior string

type BackToTopSize string

type BackToTopVariant string

type BannerConfig struct {
	// Title is the bold lead-in (required).
	Title string
	// Body is the supporting text (optional).
	Body string
	// Variant picks color + role. Defaults to BannerInfo.
	Variant BannerVariant
	// Dismissible adds an X button. When DismissID is set the runtime
	// records the dismissal in localStorage AND a same-name cookie; when
	// Ctx also carries the request (app.WithRequest — layouts and screens
	// get this automatically), Banner sees the cookie and renders nothing
	// at all on later requests — no flash of a dismissed banner before
	// the runtime's hide pass. (Richer server-side persistence is still
	// up to the app — Banner doesn't ship its own RPC.)
	Dismissible bool
	DismissID   string
	// Action is an optional inline call-to-action (a Link or Button
	// rendered to the right of the body).
	Action render.HTML
	// ID / Class / Attrs are passed through to the outer element.
	ID         string
	Class      string
	ExtraAttrs html.Attrs
	// Ctx carries the per-request context used to resolve the dismiss label.
	// When nil, English fallbacks apply.
	Ctx context.Context
}

type BannerVariant string

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

type BarChartConfig struct {
	// Bars are the entries (≥1).
	Bars []BarChartBar
	// Width / Height in CSS pixels. Default 320×200.
	Width  int
	Height int
	// ShowAxis renders a left value axis: hairline gridlines at clean
	// tick values with numeric labels down the left gutter. Default off
	// (the always-on value labels + baseline already make magnitudes
	// legible; turn this on for a denser analytical read).
	ShowAxis bool
	// ShowLabels renders the category labels under each bar. Long labels
	// wrap onto up to two lines; a single over-long word is ellipsized
	// with the full text preserved in the bar's <title>. Default off.
	ShowLabels bool
	// HideValues suppresses the per-bar value labels that ride above each
	// cap. Values are shown by default — set this to opt out (e.g. a dense
	// sparkline-style strip where the numbers would crowd).
	HideValues bool
	// LabelledBy is the id of an element naming the chart for AT.
	LabelledBy string
	ID         string
	Class      string
}

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

type BoxPad string

type ButtonConfig struct {
	Label      string        // required visible text + aria-label
	Variant    ButtonVariant // defaults to ButtonPrimary
	Size       ButtonSize    // defaults to ButtonSizeDefault
	Type       string        // "button" (default) | "submit" | "reset"
	ExtraAttrs html.Attrs
	ID         string
	Class      string
}

type ButtonSize string

type ButtonVariant string

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

	// Landmark controls whether an info/success/neutral callout renders as a
	// complementary <aside> landmark (the default, mandated by the framework's
	// own tests). Set to false for a callout embedded inline in main content
	// flow: a nested complementary landmark trips axe's
	// landmark-complementary-is-top-level rule, and an inline tip is emphasis,
	// not a tangential region. Same trade-off Sidebar already made (div, not
	// aside, to avoid nesting complementary). Danger/warning always use
	// role="alert" regardless of this flag.
	Landmark *bool
}

type CardConfig struct {
	// Heading is the optional top-of-card title. When set, a labelled
	// <section> wraps the card so screen readers pick up the heading
	// as the region name.
	//
	// The heading's id (and the section's aria-labelledby target) is
	// derived from the heading text — "ui-card-" + slug(Heading) — so
	// it is deterministic across re-renders. The trade-off, shared with
	// html.Heading: two cards with EQUAL heading text on one page
	// produce duplicate ids (the render function has no page-wide
	// context to de-dupe against). cfg.ID sets the section wrapper's own
	// anchor id, NOT the heading id, so it does not de-dupe the
	// collision; when a page repeats heading text, use Header for full
	// control over the heading element and its id.
	Heading string

	// HeadingLevel overrides the heading element level (default 3).
	// Set to 2 when the card is a top-level page section (e.g. a
	// dashboard widget directly under the page <h1>) so the heading
	// outline doesn't skip from h1 to h3.
	HeadingLevel int

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

	// Header overrides the auto-rendered Heading/Description block.
	// Use when the header needs more than a title — e.g. a row with an
	// avatar and trailing actions.
	Header render.HTML

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

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

	Variant CardVariant
	ID      string
	Class   string
}

type CardVariant string

type CarouselConfig struct {
	// Slides are the entries (≥1).
	Slides []CarouselSlide
	// Label is the accessible label for the carousel region (required,
	// becomes role=region + aria-label).
	Label string
	// ShowDots renders pagination dots under the slides (default on).
	// Set to false explicitly via NoDots if you want to hide them.
	NoDots bool
	// ShowArrows renders Prev/Next buttons (default on). Set NoArrows
	// to hide them.
	NoArrows bool
	// AutoRotateMs, when > 0, auto-advances every N ms. Paused on
	// hover, focus, and when prefers-reduced-motion is true.
	AutoRotateMs int
	// Loop, when true, makes Next-on-last wrap to first (and vice
	// versa). Default false — Prev/Next disable at the ends.
	Loop bool
	// VisiblePerView (default 1) shows N slides side-by-side; snap
	// still steps one slide at a time.
	VisiblePerView int
	// VirtualScroll, when true, server-renders only the first
	// VirtualWindow slides as visible content; the remaining slides
	// emit as same-width placeholder divs paired with a JSON manifest
	// of the deferred HTML. The runtime hydrates each placeholder via
	// IntersectionObserver as it scrolls into the viewport (plus a
	// one-window read-ahead buffer). Use for image-heavy archive views
	// (>50 slides) where rendering every slide upfront is wasteful.
	//
	// Once hydrated, slides stay hydrated for the lifetime of the
	// page — browsers manage the image cache on their own and
	// re-hydrating on scroll-back would feel laggier than the original
	// problem.
	VirtualScroll bool
	// VirtualWindow is the initial render window when VirtualScroll
	// is enabled. Default 5. Slides 0..VirtualWindow-1 ship hydrated;
	// the rest are placeholders.
	VirtualWindow int
	// VirtualPlaceholderHeight is an optional CSS length applied to
	// each unhydrated placeholder slide. Required when slides have
	// no intrinsic flex height (e.g. raw <img> with no fixed aspect)
	// — otherwise placeholders collapse to 0 and IntersectionObserver
	// fires every placeholder at once. Image-only carousels typically
	// pick "240px" or whatever matches the typical slide aspect.
	VirtualPlaceholderHeight string
	ID                       string
	Class                    string
	ExtraAttrs               html.Attrs
	// Ctx carries the per-request context used to resolve the Previous/Next,
	// Go-to-slide and pagination aria labels. When nil, English fallbacks apply.
	Ctx context.Context
}

type CarouselSlide struct {
	// Content is the slide body (required) — caller decides the shape.
	// For an image-only carousel pass an <img>; for richer slides pass
	// a Card or any composition.
	Content render.HTML
	// Label is the slide's accessible label (announced when focused
	// via Tab nav within the carousel). Defaults to "Slide N of M".
	Label string
}

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

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

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

type ClusterConfig struct {
	Gap     Gap
	Align   Align
	Justify Justify
	// NoWrap opts out of the default responsive wrapping behavior. Use it only
	// for compact chrome that is guaranteed to fit, such as two icon controls.
	NoWrap bool
	// Wrap is retained for source compatibility. Clusters wrap by default,
	// including when this zero-value field is false; use NoWrap to opt out.
	// Deprecated: wrapping is now the documented zero-value behavior.
	Wrap  bool
	ID    string
	Class string
}

type CodeBlockConfig struct {
	Code     string // raw source to render; escaped. Ignored when Lines is set.
	Language string // optional, used for aria-label only
	// Lines carries pre-rendered (e.g. syntax-highlighted) logical source
	// lines. When non-empty it takes precedence over Code; each entry is
	// wrapped as one line so LineNumbers can number it. Callers own the
	// per-token markup — pass already-escaped, trusted HTML.
	Lines []render.HTML
	// Filename, when set, renders a chrome header (status dot + filename)
	// above the body and switches the wrapper to a framed container.
	Filename string
	// ShowCopy adds a copy-to-clipboard button (the framework CopyButton)
	// in the header, targeting this block's own body. Forces a header even
	// when Filename is empty.
	ShowCopy bool
	// LineNumbers renders a left gutter numbering each line.
	LineNumbers bool
	// Scroll caps the body height (var(--ui-code-block-scroll-max,
	// 26rem)) and makes it scroll vertically — for showing a long file in
	// full without letting it dominate the page. Implies the framed
	// container.
	Scroll bool
	ID     string
	Class  string
}

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

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

type CollapsibleConfig struct {
	Summary string // required — the always-visible header
	Open    bool   // optional — start expanded (default: collapsed)
	Class   string // optional — additional CSS classes
	ID      string // optional — element id
}

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

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

	// Header is the visible column header text. Required.
	Header string

	// Sortable enables a clickable sort link in the header.
	Sortable bool

	// Align is "start" (default), "center", or "end".
	Align string
}

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

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

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

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

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

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

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

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

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

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

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

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

	Class string
}

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

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

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

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

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

	// ConfirmLabel defaults to "Confirm".
	ConfirmLabel string

	// CancelLabel defaults to "Cancel".
	CancelLabel string

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

	// RPCMethod defaults to "POST".
	RPCMethod string

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

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

type ContainerConfig struct {
	// Width picks the max-inline-size. Defaults to ContainerDefault.
	Width ContainerWidth
	// As lets the caller pick a non-<div> tag (e.g. "section", "main").
	// Defaults to "div".
	As         string
	ID         string
	Class      string
	ExtraAttrs html.Attrs
}

type ContainerWidth string

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

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

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

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

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

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

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

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

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

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

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

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

	ID    string
	Class string
}

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

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

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

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

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

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

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

	// SortBy is the active sort column's Key (optional).
	SortBy string

	// SortDir is the active sort direction (asc/desc).
	SortDir SortDir

	// SortHrefPattern is a Sprintf pattern with two %s placeholders
	// for column key and direction, e.g. "?sort=%s&dir=%s". Required
	// if any column is Sortable.
	SortHrefPattern string

	// Pagination is an optional pagination.Config. When set, the
	// pagination nav renders below the table.
	Pagination *pagination.Config

	// Empty is the EmptyState shown when len(Rows) == 0. If zero,
	// a default empty state is rendered.
	Empty EmptyStateConfig

	// IslandSignal turns this DataTable into an island. When non-empty,
	// sort headers render as `data-fui-rpc` buttons that fire RPCs at
	// IslandEndpoint instead of plain `<a href>` links. The Pagination
	// config inherits the same island settings automatically (so a single
	// IslandSignal+IslandEndpoint pair drives both sort and page).
	//
	// The signal-bound wrapper is the caller's responsibility — wrap
	// the DataTable's rendered HTML in:
	//   <div data-fui-signal="<IslandSignal>" data-fui-signal-mode="html">
	//     {DataTable(...)}
	//   </div>
	IslandSignal string

	// IslandEndpoint is the URL the sort/page RPCs target. Sort links
	// hit "<endpoint>?sort=…&dir=…&p=…"; pagination links hit
	// "<endpoint>?sort=…&dir=…&p=N". The handler is expected to return
	// the full new DataTable HTML.
	IslandEndpoint string

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

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

	ID    string
	Class string
}

type DetailItem struct {
	Label string
	Value render.HTML
}

type DetailListConfig struct {
	Items []DetailItem
	Class string
}

type DiffMode string

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

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

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

	ID    string
	Class string
}

type DividerOrientation string

type DocCrumb struct {
	Label string
	Href  string
}

type DocLayoutConfig struct {
	// Nav is the left rail (use DocNav). Empty → single-column narrow doc.
	Nav render.HTML
	// Crumbs renders a breadcrumb trail above the article body.
	Crumbs []DocCrumb
	// CrumbsLabel overrides the breadcrumb nav's aria-label ("Breadcrumb").
	CrumbsLabel string
	// Toc is the optional right rail (in-page table of contents).
	Toc render.HTML
	// Pager, when set, renders a prev/next footer after the body.
	Pager *DocPager
	Class string
	ID    string
}

type DocPager struct {
	PrevHref, PrevLabel string
	NextHref, NextLabel string
}

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

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

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

type FacetKind string

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

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

type FactStyle string

type FieldErrors map[string]string

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

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

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

	// Label is the visible label. Required.
	Label string

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

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

	// Multiple allows selecting multiple files.
	Multiple bool

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

	// Disabled disables interaction.
	Disabled bool

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

	// Help renders supporting text under the drop zone.
	Help string

	// Error overrides Help and switches the field to error state.
	Error string

	Class string

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

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

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

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

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

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

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

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

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

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

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

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

	ID    string
	Class string
}

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

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

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

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

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

	// ApplyLabel overrides the submit button text. Default "Apply".
	ApplyLabel string
	// ResetLabel overrides the reset link text. Default "Reset".
	ResetLabel string
	// HideReset suppresses the Reset link (e.g. when the caller renders
	// an active-filter chip bar with its own "Clear all").
	HideReset bool

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

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

	ID         string
	Class      string
	ExtraAttrs html.Attrs
}

type FormConfig struct {
	// Action is the form's action URL. Required.
	Action string

	// Method is "POST" (default) or "GET".
	Method string

	// Errors is an optional set of field-level errors. They are
	// applied to FormFieldFor() calls so re-rendering after a failed
	// submit re-applies error styling automatically.
	Errors FieldErrors

	// Summary is an optional Callout displayed above the fields when
	// the form has errors. If empty and Errors is non-empty, a default
	// "Please fix the highlighted fields and try again." is rendered.
	Summary string

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

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

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

	ID    string
	Class string
	// ExtraAttrs are passed through to the <form> element — e.g. the
	// data-fui-rpc-* attributes that turn the form into an island that
	// submits JSON to a CRUD endpoint.
	ExtraAttrs html.Attrs
}

type FormFieldConfig struct {
	Label    string // required → <label>
	For      string // required → <label for=…> matches the input ID
	Help     string // optional helper text under the field
	Error    string // optional error message; non-empty switches to error styling
	Required bool   // adds a visible "required" hint and aria-required
	Input    render.HTML
	Class    string
}

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

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

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

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

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

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

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

type FormSectionConfig struct {
	Heading     string // optional
	Description string // optional
	Class       string
}

type GalleryCaptionMode string

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

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

type GalleryVariant string

type Gap string

type GlobalSearchConfig struct {
	// ID is the input element id (the runtime listbox uses
	// <ID>-listbox). Required, page-unique.
	ID string
	// Name is the form-submit name on the input. Required.
	Name string
	// Label is the visible label text (required, used as <label for=…>).
	Label string
	// RPCPath is the search endpoint. Required. POSTed with the
	// query in `<Name>=<value>`.
	RPCPath string
	// SignalName is the rpc-signal value used to swap the listbox
	// HTML after each search response. Required.
	SignalName string
	// Placeholder for the input. Default "Search…".
	Placeholder string
	// Shortcut, when set, opts the input into runtime focus-on-key:
	// `data-fui-shortcut-focus="<chord>"` (default "/"). Pass an
	// explicit empty string to disable.
	Shortcut string
	// ShowHint renders a small "Press <chord>" hint chip on the right
	// of the input. Default true when Shortcut is set.
	ShowHint *bool
	// DebounceMs is the input debounce window (passed to combobox).
	// Default 200.
	DebounceMs int
	// Sticky toggles position: sticky on the wrapper. Default true.
	Sticky bool
	Class  string
	// Ctx carries the per-request context used to resolve i18n labels
	// (placeholder). When nil, English fallbacks apply.
	Ctx context.Context
}

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

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

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

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

type HeroSplitRatio string

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

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

	ID    string
	Class string
}

type ImageAspect string

type ImageFit string

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

type InputGroupConfig struct {
	// Prepend is optional content rendered before the input (text, icon, etc.).
	Prepend render.HTML
	// Input is the actual input element (required).
	Input render.HTML
	// Append is optional content rendered after the input.
	Append render.HTML
	// Class adds extra CSS classes to the wrapper.
	Class string
}

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

type Justify string

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

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

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

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

type LinkButtonConfig struct {
	Label   string        // required visible text
	Href    string        // required navigation target
	Variant ButtonVariant // defaults to ButtonPrimary
	Size    ButtonSize    // defaults to ButtonSizeDefault
	// External, when true, opens the link in a new tab with
	// rel="noopener noreferrer". Use for off-site links (docs to
	// GitHub, pkg.go.dev, etc.). The runtime's SPA-nav interceptor
	// naturally skips http(s):// hrefs (they're not "internal"), so
	// External does not also need to "suppress SPA nav" — the
	// underlying SPA router already does the right thing.
	External bool
	// Icon, when set, renders the named registered icon (see
	// RegisterIcon / Icon) before the label. The button's inline-flex
	// gap handles spacing. Unknown names render the label alone.
	Icon       string
	ID         string
	Class      string
	ExtraAttrs html.Attrs
}

type LinkConfig struct {
	Href       string // required
	Text       string // required visible text
	Variant    LinkVariant
	Class      string
	ID         string
	ExtraAttrs html.Attrs
}

type LinkVariant string

type MarkdownConfig struct {
	// Source is the raw markdown text (required).
	Source string
	// Compact tightens spacing — useful for inline previews where
	// hero-page paragraph rhythm would feel wrong.
	Compact    bool
	ID         string
	Class      string
	ExtraAttrs html.Attrs
}

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

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

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

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

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

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

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

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

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

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

	// Variant tints destructive items (red) — purely a visual hint;
	// the actual confirm step belongs on the RPC via data-fui-confirm.
	Danger bool

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

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

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

	// Attrs sprinkles extra attributes onto the rendered element.
	ExtraAttrs map[string]string
}

type MenuPosition string

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

type MetricBandItem struct {
	Label string
	Value string
	Hint  string
}

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

	// FailureThreshold is the number of consecutive RPC failures that
	// trip the banner. Default 3. Zero disables the failure-count
	// trigger (banner only shows on explicit reportFailure threshold
	// hits never reached).
	FailureThreshold int

	// SSESilenceMs triggers the banner if no SSE event arrives for
	// this many milliseconds. Default 0 (disabled — opt-in). When set,
	// the runtime polls window.__gofastr.sseStatus.lastEventAt (kept
	// current by the SSE module on every frame) and shows the banner
	// after this much silence; on SSE reconnect a gofastr:sse-status
	// event re-probes the health endpoint so the banner can dismiss.
	SSESilenceMs int

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

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

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

	ID    string
	Class string
}

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

	ID         string
	Class      string
	ExtraAttrs html.Attrs
}

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

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

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

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

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

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

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

	ID    string
	Class string
}

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

type NotificationPosition string

type NumberInputConfig struct {
	// Name is the form-field name (required).
	Name string
	// Label is the accessible label (required, used as <label for=…>).
	Label string
	// Min / Max bound the value. When both 0, no client-side bound is
	// applied (server is still authoritative).
	Min int
	Max int
	// Step is the +/- button granularity. Default 1.
	Step int
	// Value is the initial value.
	Value int
	// Disabled disables interaction.
	Disabled bool
	// Required marks the field required.
	Required bool
	// Help renders supporting text under the field.
	Help string
	// Error overrides Help with an error message.
	Error      string
	ID         string
	Class      string
	ExtraAttrs html.Attrs
	// Ctx carries the per-request context used to resolve the Decrement and
	// Increment aria labels. When nil, English fallbacks apply.
	Ctx context.Context
}

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

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

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

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

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

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

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

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

	ID    string
	Class string
}

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

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

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

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

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

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

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

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

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

	// Placeholder, when non-empty, renders a low-fidelity background
	// (typically a 1x1 base64-encoded pixel) that shows under the
	// image while loading.
	Placeholder string

	ID    string
	Class string
}

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

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

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

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

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

	ID    string
	Class string
}

type PasswordInputConfig struct {
	// Name is the form-field name (required).
	Name string
	// ID is the input element's id (required).
	ID string
	// Placeholder renders the native placeholder.
	Placeholder string
	// Required marks the field required.
	Required bool
	// Autocomplete sets the autocomplete attribute (e.g. "current-password", "new-password").
	Autocomplete string
	// Error overrides with an error message + aria-invalid.
	Error string
	// Class adds extra CSS classes to the wrapper.
	Class string
	// Attrs lets callers attach additional attributes.
	ExtraAttrs map[string]string

	// Ctx carries the per-request context used to resolve i18n strings
	// (show/hide toggle aria-label). When nil, context.Background() is
	// used and English fallbacks are returned — preserving today's behaviour.
	Ctx context.Context
}

type PieChartConfig struct {
	// Slices are the entries (≥1 with non-zero Value).
	Slices []PieSlice
	// Size is the SVG square side in CSS pixels. Default 160.
	Size int
	// InnerRadius (0–1, fraction of outer radius) cuts the center
	// out, turning it into a donut. Default 0 (pie).
	InnerRadius float64
	// CenterLabel renders a label in the middle of the donut hole.
	// Ignored when InnerRadius=0.
	CenterLabel string
	// CenterSubtext renders smaller text under the CenterLabel.
	CenterSubtext string
	// LabelledBy is the id of an element naming the chart for AT.
	// Without it the chart is aria-hidden.
	LabelledBy string
	ID         string
	Class      string
}

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

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

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

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

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

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

	// Placeholder accepts either a data: URL (LQIP) or a BlurHash
	// string. The component sets data-placeholder for data: URLs and
	// data-blurhash for anything else. Consumers wire those attributes
	// to a CSS background or a JS hydrator as they see fit.
	Placeholder string

	Eager        bool
	HighPriority bool
	Fit          ImageFit
	Aspect       ImageAspect
	Rounded      bool

	ID, Class string
}

type PipelineSource struct {
	URL   string // image URL — required
	Width int    // intrinsic pixel width — required
	Type  string // MIME type — required (e.g. "image/webp", "image/jpeg")
}

type PollingIndicatorConfig struct {
	// Label is the text rendered next to the pulsing dot.
	// Defaults to "Live".
	Label string
	// Paused freezes the pulse animation and dims the dot — use when
	// the upstream polling has been paused or completed.
	Paused bool
	ID     string
	Class  string
	// Ctx carries the per-request context used to resolve the live label.
	// When nil, English fallbacks apply.
	Ctx context.Context
}

type PricingCardConfig struct {
	Name        string   // plan name, e.g. "Pro"
	Price       string   // headline price, e.g. "$99"
	Period      string   // optional period suffix, e.g. "/mo"
	Description string   // optional one-line pitch under the name
	Features    []string // checked feature list
	CTALabel    string   // CTA button label (defaults to "Choose " + Name)
	CTAHref     string   // CTA target
	Featured    bool     // highlight as the recommended plan
	ID          string
	// HeadingLevel overrides the plan-name heading level (default 3).
	// Set to 2 when cards sit directly under the page <h1> (no
	// intervening section <h2>) so axe's heading-order rule passes.
	HeadingLevel int
	Class        string
}

type ProgressStep struct {
	// Label is the step name (required, e.g. "Account").
	Label string
	// Hint is the optional supporting line below the label.
	Hint string
	// Status picks the visual state. Defaults to ProgressStepUpcoming.
	Status ProgressStepStatus
	// Href, when set on a complete step, makes the step a link the
	// user can click to navigate back. Upcoming steps ignore Href.
	Href string
}

type ProgressStepStatus string

type ProgressStepsConfig struct {
	// Steps are the entries in order. Required (≥1).
	Steps []ProgressStep
	// Orientation defaults to horizontal.
	Orientation ProgressStepsOrientation
	// Label is the optional aria-label for the wrapping nav. Defaults
	// to "Progress".
	Label string
	// Ctx carries the per-request context used to resolve the
	// aria-label. When nil, English fallbacks apply.
	Ctx context.Context

	ID         string
	Class      string
	ExtraAttrs html.Attrs
}

type ProgressStepsOrientation string

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

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

type RailItem struct {
	Anchor  string // required, e.g. "modeling" → href="#modeling"
	Text    string // required, link label
	Eyebrow string // optional leading chip
	Count   int    // optional trailing chip (0 = hidden)
}

type RangeSliderConfig struct {
	// Name is the form-field base name (required). Two inputs ship —
	// Name+"-min" and Name+"-max".
	Name string
	// Label is the accessible group name (required, used as the
	// fieldset legend / radiogroup aria-label).
	Label string
	// Min / Max bound the range. Defaults: 0 / 100.
	Min int
	Max int
	// Step is the step granularity. Default 1.
	Step int
	// ValueLow / ValueHigh are the initial low and high values.
	// Defaults: Min / Max.
	ValueLow  int
	ValueHigh int
	// ShowValue renders a live "lo – hi" text alongside the label.
	ShowValue bool
	// Disabled disables both thumbs.
	Disabled   bool
	ID         string
	Class      string
	ExtraAttrs html.Attrs
}

type RatingConfig struct {
	// Name is the form-field name (required).
	Name string
	// Label is the accessible label (required, used as fieldset
	// legend / radiogroup aria-label).
	Label string
	// Max is the rating ceiling (1..N). Defaults to 5.
	Max int
	// Value is the initial selection (0..Max). 0 = no rating chosen.
	Value int
	// Shape picks one of the bundled glyphs (star/heart/thumb/fire/
	// diamond/circle/square). Ignored when Icon is set.
	Shape RatingShape
	// Icon is a caller-supplied monochrome SVG (or any render.HTML)
	// used in place of the bundled Shape glyph. The fill / stroke
	// inside should use currentColor so the selected-state highlight
	// works. Cloned into every star.
	Icon render.HTML
	// Size picks the icon glyph size. Default=24px, Small=16px,
	// Large=32px. Tap target stays at the WCAG floor regardless.
	Size RatingSize
	// Gap picks the visual spacing between stars. Default keeps the
	// AAA 44×44 tap target per star (glyphs ~22px apart). Tight
	// shrinks the inline tap zone to glyph+8px so adjacent glyphs
	// nearly touch (~8px gap) — relaxes AAA to AA (24px floor) for
	// dense inline ratings. Loose / Wide widen the gap without
	// touching the tap zone. Independent of Size.
	Gap RatingGap
	// Disabled disables all radios.
	Disabled bool
	ID       string
	Class    string
}

type RatingGap string

type RatingShape string

type RatingSize string

type RecordSummaryConfig struct {
	Title        string
	Eyebrow      string
	Description  string
	Status       render.HTML
	Highlight    render.HTML
	Metrics      render.HTML
	Aside        render.HTML
	Footer       render.HTML
	Actions      render.HTML
	Tone         RecordSummaryTone
	HeadingLevel int
	ID           string
	Class        string
}

type RecordSummaryTone string

type RepeaterConfig struct {
	Name        string
	Label       string
	ID          string
	MinItems    int
	MaxItems    int
	AddLabel    string
	RemoveLabel string
	Template    func(index int) render.HTML
	Items       []render.HTML
	RPCPath     string

	// Ctx carries the per-request context used to resolve i18n strings
	// (AddLabel, RemoveLabel defaults). When nil, context.Background() is
	// used and English fallbacks are returned — preserving today's behaviour.
	Ctx context.Context
}

type ResponsiveConfig struct {
	// Breakpoint in pixels — viewport >= Breakpoint renders the
	// desktop variant; < Breakpoint renders the mobile variant.
	// Defaults to 1024 when zero.
	Breakpoint int

	// Class is appended to the wrapping <div>'s class list.
	Class string
}

type ResponsiveMode string

type Row struct {
	// Cells is a map from column Key to the rendered cell HTML.
	// Missing cells render as empty strings.
	Cells map[string]render.HTML

	// ID optionally identifies the row for ARIA / interaction. Empty
	// is fine; it just won't get an `id=` attribute.
	ID string
}

type SearchInputConfig struct {
	// Name is the form-field name (required).
	Name string
	// ID is the input element's id (required).
	ID string
	// Placeholder renders the native placeholder. Defaults to "Search...".
	Placeholder string
	// Action is an optional form action URL. When set, wraps in <form role="search">.
	Action string
	// Method is the form method. Defaults to "GET".
	Method string
	// Class adds extra CSS classes to the wrapper.
	Class string
	// Attrs lets callers attach additional attributes.
	ExtraAttrs map[string]string
	// Ctx carries the per-request context used to resolve i18n labels
	// (placeholder, aria-labels). When nil, English fallbacks apply.
	Ctx context.Context
}

type SectionConfig struct {
	// Eyebrow is an optional short decorative kicker rendered above/around
	// the heading — e.g. a section number ("01 / what it generates"). It is
	// marked aria-hidden because it duplicates the heading for SR users.
	Eyebrow     string
	Heading     string // optional <h2> heading
	Description string // optional supporting text under the heading
	// DescriptionHTML lets the supporting text carry inline markup (code,
	// links). When non-empty it takes precedence over Description.
	DescriptionHTML render.HTML
	// Label sets the section's accessible name when there is no Heading.
	// Without a Heading or Label the section falls back to a generic
	// "Section" aria-label.
	Label string
	Class string
	ID    string
	// Ctx carries the per-request context used to resolve the default
	// Section aria-label. When nil, English fallback applies.
	Ctx context.Context
}

type SegmentedControlConfig struct {
	// Name is the form-submit name shared by all radios. Required.
	Name string

	// Options must contain at least two segments. Required.
	Options []SegmentedOption

	// Selected is the initially selected Value. When empty or not
	// matching any option, defaults to Options[0].Value.
	Selected string

	// Label is the aria-label on the radiogroup wrapper. Required
	// when the surrounding context doesn't already label it (e.g.
	// the SegmentedControl is not inside a <label> or FormField).
	Label string

	// RPCPath, when set, attaches data-fui-rpc to each radio so a
	// change submits to the server. Method is POST.
	RPCPath string

	// RPCSignal, when set, broadcasts the response as the given
	// signal name (data-fui-rpc-signal).
	RPCSignal string

	ID    string
	Class string
}

type SegmentedOption struct {
	// Label is the visible text. Required.
	Label string
	// Value is the submit value and the option's stable identifier.
	// Required and unique within the control.
	Value string
	// Disabled marks the segment as non-selectable.
	Disabled bool
}

type SelectConfig struct {
	// Name is the form-field name (required).
	Name string
	// Label is the accessible label (required).
	Label string
	// Options is the list of <option> elements (required, at least one).
	Options []SelectOption
	// Placeholder adds a disabled, selected-first option with empty value
	// that acts as a placeholder hint (e.g. "Choose a country…").
	Placeholder string
	// Required marks the field required.
	Required bool
	// Disabled disables interaction.
	Disabled bool
	// Help renders supporting text under the field.
	Help string
	// Error overrides Help with an error message + aria-invalid.
	Error      string
	ID         string
	Class      string
	ExtraAttrs html.Attrs
}

type SelectOption struct {
	Value    string
	Text     string
	Selected bool
}

type ShortcutHintConfig struct {
	// Chord is the human-readable chord string accepted by the
	// runtime's parseCombo: "Mod+K", "Ctrl+/", "Shift+Tab", "/",
	// "Esc", "Enter". Required.
	Chord string

	// BindTarget is an optional CSS selector. When set, the chord is
	// installed as a global shortcut that clicks the matched element.
	// (The runtime hook lives on the TARGET, not the hint.)
	// NOTE: This component renders only the hint; the caller must
	// place data-fui-shortcut-click="<Chord>" on the actual target,
	// or use ShortcutHintBind which returns both.
	BindTarget string

	// SROnlyLabel overrides the screen-reader announcement.
	// Default: humanized chord (e.g. "Command-K", "Slash", "Escape").
	SROnlyLabel string

	ID    string
	Class string
}

type SidebarConfig struct {
	// Title is rendered as the sidebar's top heading. Empty omits it.
	Title string

	// Items is the navigation tree.
	Items []SidebarItem

	// CurrentPath is the screen's current path, used for active-state
	// highlighting. When empty, falls back to JS: the runtime stamps
	// aria-current on any matching <a> after hydration.
	CurrentPath string

	// Variant defaults to SidebarPersistent.
	Variant SidebarVariant

	// Footer is optional content rendered at the bottom (signed-in
	// user pill, settings link, etc.).
	Footer render.HTML

	// DrawerName overrides the widget name used for the < md drawer.
	// Defaults to "ui-sidebar-drawer". Apps that host multiple
	// sidebars per page must override to avoid collisions.
	DrawerName string

	// SuppressDrawerTrigger hides the hamburger button rendered by
	// Sidebar (some apps put their hamburger in the page header
	// instead and call MountSidebar themselves).
	SuppressDrawerTrigger bool
}

type SidebarItem struct {
	Label    string
	Href     string
	Icon     render.HTML
	Children []SidebarItem

	// Roles, when non-empty, restricts the item to users holding at least
	// one of the named roles. Empty = visible to everyone. Filtering happens
	// at render time via the roles extractor (SetRolesExtractor); when no
	// extractor is registered, items render unfiltered (opt-in feature).
	Roles []string

	// Active forces the item into the active state regardless of the
	// caller's MatchPath. Useful for pages that don't map 1:1 to a URL.
	Active bool

	// MatchPath, when set, overrides the default "current URL equals
	// Href" check used to mark the item as active. Pass a literal
	// prefix ("/customers") to highlight on sub-paths, or use
	// CurrentPath in your screen and set Active manually.
	MatchPath string
}

type SidebarVariant string

type SignOutConfig struct {
	// Action is the POST target; defaults to "/auth/logout".
	Action string
	// Label is the button text; defaults to "Sign out".
	Label string
	// Next is an optional post-logout redirect, sent as a hidden field.
	Next string
	// Variant styles the button; defaults to ButtonGhost.
	Variant ButtonVariant
	Class   string
	// Ctx carries the per-request context used to resolve the sign-out label.
	// When nil, English fallbacks apply.
	Ctx context.Context
}

type SignalToggleConfig struct {
	SignalName string             // required unless Slice is set
	Slice      *store.Slice[bool] // optional; supplies the signal name + initial value, takes precedence
	Label      string             // optional — aria-label (falls back to the signal name)
	Class      string             // optional — extra CSS classes
}

type SiteFooterColumn struct {
	Title string
	Links []SiteFooterLink
}

type SiteFooterConfig struct {
	// Lead is the optional left-most slot (brand mark + tagline).
	// If empty, the grid is just columns.
	Lead render.HTML
	// Columns are the labelled link lists rendered after Lead.
	Columns []SiteFooterColumn
	// Bottom is the optional small-text strip below the grid (e.g.,
	// copyright + colophon). Children render in a horizontal cluster.
	Bottom []render.HTML
	// Class is appended to the ui-site-footer wrapper.
	Class string
}

type SiteFooterLink struct {
	Label    string
	Href     string
	External bool
}

type SiteHeaderConfig struct {
	// Brand is the left-most slot. Usually a link with logo + wordmark.
	// The consumer owns its visual identity: the framework ships only
	// zero-specificity typography defaults for a linked brand, so any
	// consumer CSS rule overrides them. Keep operational status in page
	// content rather than overloading a long identity lockup.
	Brand render.HTML
	// MobileBrand, when set, replaces Brand at widths up to 720px. Use a
	// concise mark or short product name so status and navigation never push
	// the identity off-screen. The framework owns the responsive swap.
	MobileBrand render.HTML
	// NavItems renders both the desktop nav and the mobile drawer list.
	NavItems []SiteHeaderLink
	// Actions is the right-cluster slot for search, theme toggle,
	// icon links, etc. Rendered before the mobile drawer trigger so
	// the trigram glyph sits at the far right.
	Actions render.HTML
	// MobileExtraLinks are appended only to the mobile drawer list
	// (e.g., "Home", "GitHub ↗"). Lets the consumer surface secondary
	// destinations on phones without cluttering the desktop bar.
	MobileExtraLinks []SiteHeaderLink
	// MobileNavAriaLabel labels the mobile <nav>. Defaults to
	// "Mobile primary".
	MobileNavAriaLabel string
	// PrimaryNavAriaLabel labels the desktop <nav>. Defaults to
	// "Primary".
	PrimaryNavAriaLabel string
	// NavUnderline opts the desktop nav links into an animated
	// underline-reveal on hover / focus / active, instead of the default
	// flat colour-only treatment. The underline colour is themeable via
	// --ui-site-header-nav-underline-color (defaults to the primary colour).
	NavUnderline bool
	// Drawer selects the mobile nav shape. The default is a compact
	// trigger-anchored popover; SiteHeaderDrawerSheet renders a full-height
	// slide-in side drawer with a backdrop scrim — the component owns the
	// layout, so consumers don't hand-roll drawer CSS.
	Drawer SiteHeaderDrawerVariant
	// Class is appended to the ui-site-header wrapper.
	Class string
	// Ctx carries the per-request context used to resolve the nav
	// aria-labels (primary, mobile, toggle). When nil, English fallbacks apply.
	Ctx context.Context
}

type SiteHeaderDrawerVariant string

type SiteHeaderLink struct {
	// Label is the visible text.
	Label string
	// Href is the navigation target.
	Href string
	// MatchPrefix, when true, lights the link active on any URL that
	// shares the Href as a prefix (e.g. /docs/foo matches /docs/).
	// Wires the data-fui-match-prefix runtime attribute.
	MatchPrefix bool
	// External, when true, opens in a new tab. Only honored in the
	// mobile drawer (the desktop nav stays internal-only by design).
	External bool
}

type SkeletonAvatarConfig struct {
	// Size overrides the circle diameter (CSS length, e.g. "3rem").
	// Defaults to the skeleton primitive's 2.5rem when empty.
	Size string
	// HideSubline collapses the two stacked lines into one.
	HideSubline bool
	ID          string
	Class       string
}

type SkeletonCardConfig struct {
	// BodyLines is the number of skeleton lines rendered in the body.
	// Defaults to 2 when zero.
	BodyLines int
	// ShowFooter renders a hairline-divided skeleton footer line.
	ShowFooter bool
	ID         string
	Class      string
}

type SkeletonRowConfig struct {
	// HideChevron drops the trailing chevron skeleton — use for plain
	// label/value rows that aren't drill-down navigable.
	HideChevron bool
	ID          string
	Class       string
}

type SkipLinkConfig struct {
	// Target is the id of the element to jump to.
	// Defaults to "main-content" when empty.
	Target string
	// Text is the visible label shown on focus.
	// Defaults to "Skip to main content" when empty.
	Text  string
	Class string
	ID    string
}

type SliderConfig struct {
	// Name is the form-field name (required).
	Name string
	// Label is the accessible label (required, used as <label for=…>).
	Label string
	// Min / Max bound the range. Defaults: 0 / 100.
	Min int
	Max int
	// Step is the step granularity. Default 1.
	Step int
	// Value is the initial value (clamped to [Min,Max]).
	Value int
	// ShowValue renders a value bubble next to the label that updates
	// via :has() / CSS custom-property tricks isn't supported across
	// browsers yet — we emit a simple <output> element instead, which
	// the browser auto-updates as the range input moves (the native
	// form-output association).
	ShowValue bool
	// ShowEdgeLabels renders the Min and Max values under the track.
	ShowEdgeLabels bool
	// Disabled disables interaction.
	Disabled   bool
	ID         string
	Class      string
	ExtraAttrs html.Attrs
}

type SortDir string

type SortOption struct {
	// Label is the visible text ("Newest", "Name A–Z"). Required.
	Label string
	// Value is the submitted sort key. Required.
	Value string
}

type SparklineConfig struct {
	// Values are the points in order (≥2).
	Values []float64
	// Width / Height in CSS pixels. Default 120×32.
	Width  int
	Height int
	// Shape picks line or area. Default line.
	Shape SparklineShape
	// Color override — defaults to var(--color-primary) via CSS.
	// Set to "danger" / "success" / "warning" / "info" to use the
	// matching theme token; any other string is passed through as a
	// raw CSS color.
	Color string
	// LabelledBy is the id of an element naming the chart (e.g. the
	// StatCard label) — used as the SVG's aria-labelledby. Without
	// it the chart is aria-hidden (decorative).
	LabelledBy string
	ID         string
	Class      string
	// Ctx carries the per-request context used to resolve the no-trend-data label.
	// When nil, English fallbacks apply.
	Ctx context.Context
}

type SparklineShape string

type SpinnerConfig struct {
	// Label is the assistive-text announced by screen readers.
	// Defaults to "Loading…" when empty.
	Label string

	// Size selects a named size (sm | md (default) | lg).
	Size SpinnerSize

	// Variant selects the visual treatment.
	Variant SpinnerVariant

	// Inline true renders inline-flex (sits next to text); false
	// renders block (centered in its own row).
	Inline bool

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

type SpinnerSize string

type SpinnerVariant string

type StackConfig struct {
	Gap     Gap     // gap between children (default md)
	Align   Align   // cross-axis (horizontal) alignment
	Justify Justify // main-axis (vertical) alignment
	ID      string
	Class   string
}

type StatCardConfig struct {
	Label string // required (e.g. "Active users")
	Value string // required (e.g. "12,483" or "98.4%")
	Trend string // optional trend label (e.g. "+12% vs. last week")

	// Direction colors the trend pill. Defaults to flat.
	Direction TrendDirection

	ID    string
	Class string
}

type StatusBadgeConfig struct {
	Label   string        // required visible text
	Variant StatusVariant // defaults to Neutral
	ID      string
	Class   string
}

type StatusPillConfig struct {
	Label string         // required visible text
	Tone  StatusPillTone // default StatusPillNeutral
	// Dot adds a leading status dot. Opt-in.
	Dot   bool
	Class string
	ID    string
}

type StatusPillTone string

type StatusVariant string

type StatusVariantCSS struct {
	// Color is the variant's accent. Required. Token references like
	// "{colors.primary}" resolve to "var(--color-primary)".
	Color string
	// Icon is the glyph Callout and Notification display for this
	// variant (a short string, typically one character). Defaults to
	// "•". Must not contain `"` or `\` — it is embedded in a CSS
	// string literal.
	Icon string
}

type StepRailConfig struct {
	// Title is the small heading at the top of the rail
	// (e.g. "The path", "On this page"). Optional.
	Title string
	// Items are the numbered steps, in order.
	Items []StepRailItem
	// ActiveIndex marks one step as the active one (visually
	// highlighted). Must be in [0, len(Items)) or -1 for "no active
	// step" — out-of-range values panic at render time so a typo
	// (or a `slices.Index` -1 result, which is the common one) is
	// caught immediately rather than silently rendering a rail with
	// no highlight.
	ActiveIndex int
	// Meta is optional small text below the list (e.g. a "stuck?
	// open the journal" pointer).
	Meta string
	// MetaHref, when non-empty, renders Meta as a link to this URL
	// instead of plain text — so a "stuck? ask here" pointer is
	// actually clickable.
	MetaHref string
	// Class is appended to the ui-step-rail wrapper.
	Class string
}

type StepRailItem struct {
	// Number is the displayed ordinal (e.g. "01", "02"). Caller picks
	// the format (zero-padded vs. plain) so the visual matches the
	// step headings.
	Number string
	// Anchor is the in-page #id this rail entry jumps to.
	Anchor string
	// Label is the visible step name.
	Label string
}

type StepWizardConfig struct {
	// Steps is the ordered list of wizard steps. Required, min 1.
	Steps []StepWizardStep

	// CurrentStep is 0-indexed. The server sets this after each POST.
	CurrentStep int

	// Action is the form action URL. Required.
	Action string

	// Method defaults to "POST".
	Method string

	// HiddenFields are hidden inputs to carry forward between steps
	// (e.g. previously entered data).
	HiddenFields []render.HTML

	Class string

	// Ctx carries the per-request context used to resolve i18n strings
	// (Back, Continue, Submit button labels). When nil, context.Background()
	// is used and English fallbacks are returned — preserving today's behaviour.
	Ctx context.Context
}