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 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
	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 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 so the same banner doesn't
	// re-appear on the next page load. (Server-side persistence is 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
}

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. Optional CSS color
	// or one of: "primary", "info", "success", "warning", "danger".
	Color string
}

type BarChartConfig struct {
	// Bars are the entries (≥1).
	Bars []BarChartBar
	// Width / Height in CSS pixels. Default 320×180.
	Width  int
	Height int
	// ShowAxis renders thin x/y axis lines + min/max value labels on
	// the left. Default off (compact mode).
	ShowAxis bool
	// ShowLabels renders the bar labels under the chart. Default on.
	ShowLabels 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
}

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.
	Heading string

	// 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
}

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
	Wrap    bool // when true (default), children wrap onto multiple lines
	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
	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.
	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
}

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

	// 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
}

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

	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
}

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

	ID    string
	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
}

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
}

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
}

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

	ID    string
	Class string
}

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
}

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
}

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 number of columns. Default 3.
	// Masonry mode: uses this as the 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
}

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 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
}

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
	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 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 until the
	// SSE module exposes lastEventAt).
	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
	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

	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
}

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)
	Class    string
	ID       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
}

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
}

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
	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 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
}

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
}

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
}

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 MountSidebarDrawer themselves).
	SuppressDrawerTrigger bool
}

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

	// 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 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
	// + optional status pill. No constraint on shape.
	Brand 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
	// Class is appended to the ui-site-header wrapper.
	Class 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 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
}

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
}

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 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
}

type StepWizardStep struct {
	// Heading is the step heading. Required.
	Heading string
	// Description is optional supporting text below the heading.
	Description string
	// Fields are the form fields rendered for this step.
	Fields []render.HTML
}

type StickyConfig struct {
	// Edge selects which edge to stick to.
	// Defaults to StickyTop when empty.
	Edge StickyEdge

	// Offset selects the distance preset from the edge.
	// Defaults to StickyOffsetNone when empty.
	Offset StickyOffset

	// ZIndexTier selects the z-index tier from the theme token
	// system. Defaults to "sticky" when empty.
	// Common values: "sticky", "dropdown", "overlay", "modal".
	ZIndexTier string

	ID    string
	Class string
}

type StickyEdge string

type StickyOffset string

type TOCConfig struct {
	// Target is the CSS selector of the content region whose headings
	// the runtime should scan. Required (e.g. "main", "article").
	Target string
	// Label is the accessible nav-label (defaults to "On this page").
	Label string
	// Levels picks which heading levels to harvest. Bit flags:
	// 2 = h2 only, 3 = h3 only, 0 / 5 = h2 + h3. Default 0.
	// We keep the API minimal — most sites want h2 + h3.
	Levels int
	// Sticky toggles the position: sticky behaviour. Default true.
	// When false the nav scrolls with the content.
	Sticky     bool
	ID         string
	Class      string
	ExtraAttrs html.Attrs
}

type TabItem struct {
	Label   string
	Content render.HTML
}

type TabsConfig struct {
	SignalName string            // required unless Slice is set
	Slice      *store.Slice[int] // optional; supplies the signal name + initial active index, takes precedence
	Tabs       []TabItem         // required, at least 1
	Class      string            // optional extra CSS class
}

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

	// Variant maps to the same StatusVariant set as StatusBadge so
	// status-coded tags compose with the rest of the system. Default
	// neutral.
	Variant StatusVariant

	// Href makes the entire tag an anchor (e.g. a filter link).
	Href string

	// Dismiss, when non-empty, renders a × button that fires an RPC
	// to this path on click. Pair with data-fui-rpc-signal in DismissAttrs
	// or simply rely on the runtime's default RPC behavior.
	Dismiss string

	// DismissLabel is the assistive-text label on the × button.
	// Defaults to "Remove <Label>".
	DismissLabel string

	// DismissAttrs lets callers attach extra data-fui-* attributes to
	// the × button (e.g. data-fui-rpc-signal).
	DismissAttrs html.Attrs

	ID    string
	Class string
}

type TagInputConfig struct {
	// Name is the form-field name (required). Each tag is submitted
	// under this name (repeated key).
	Name string
	// Label is the accessible label (required).
	Label string
	// Values are the initial tags.
	Values []string
	// Placeholder for the text input.
	Placeholder string
	// MaxLength caps individual tag length (chars). 0 = no cap.
	MaxLength int
	// Help renders supporting text under the field.
	Help string
	// Disabled disables all interaction.
	Disabled bool
	ID       string
	Class    string
}

type TerminalBlockConfig struct {
	Label string // required header text, e.g. "$ install"
	Class string
	ID    string
}

type TextAreaConfig struct {
	// Name is the form-field name (required).
	Name string
	// Label is the accessible label (required).
	Label string
	// Value is the initial value.
	Value string
	// Placeholder renders the native placeholder.
	Placeholder string
	// Rows is the initial visible row count. Defaults to 3.
	Rows int
	// Autogrow opts the textarea into runtime auto-resize: every
	// input event resets the height to scrollHeight so the field
	// always shows all content without an internal scrollbar.
	Autogrow bool
	// 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
	// MaxLength applies the native maxlength attribute.
	MaxLength  int
	ID         string
	Class      string
	ExtraAttrs html.Attrs
}

type ThemeToggleConfig struct {
	// Variant selects the visual style.
	// Defaults to ThemeToggleIcon when empty.
	Variant ThemeToggleVariant

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

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

	// LightLabel overrides the light-mode label for label/pill variants.
	// Defaults to "Light".
	LightLabel string

	// DarkLabel overrides the dark-mode label for label/pill variants.
	// Defaults to "Dark".
	DarkLabel string

	// AutoLabel overrides the auto-mode label for pill variant.
	// Defaults to "Auto".
	AutoLabel string
}

type ThemeToggleVariant string

type TimePickerConfig struct {
	// Name is the form field name (required).
	Name string
	// Label is the accessible label (required).
	Label string
	// Value is the initial value in HH:MM (24-hour) format. Empty
	// means no preselection.
	Value string
	// Min / Max bound the picker (e.g. "09:00", "17:00"). Empty
	// leaves them unset.
	Min  string
	Max  string
	Step int // step in seconds (default = 60). 1 → seconds visible.
	// Required marks the input required.
	Required bool
	// Disabled disables interaction.
	Disabled bool
	// Help renders supporting text under the picker.
	Help string
	// Error overrides Help with an error message + aria-invalid.
	Error string
	ID    string
	Class string
}

type TimelineConfig struct {
	Events     []TimelineEvent
	ID         string
	Class      string
	ExtraAttrs html.Attrs
}

type TimelineEvent struct {
	// Title is the event headline (required, e.g. "Deployed v3.2.1").
	Title string
	// Meta is the optional right-aligned secondary text (e.g. a time
	// or actor — "2h ago" / "by dom").
	Meta string
	// Body is the optional supporting prose / nested HTML.
	Body render.HTML
	// Variant tints the dot on the rail. Defaults to neutral.
	Variant TimelineEventVariant
}

type TimelineEventVariant string

type ToastTrigger struct {
	Variant StatusVariant `json:"variant,omitempty"` // info | success | warning | danger | neutral
	Title   string        `json:"title"`             // required
	Body    string        `json:"body,omitempty"`
	TTL     int           `json:"ttl,omitempty"` // milliseconds; 0 = persistent
	// Stack is the name of the toast stack widget to push into.
	// Defaults to the first stack mounted on the page. Set explicitly
	// when an app hosts multiple stacks (e.g. per-tenant).
	Stack string `json:"stack,omitempty"`
}

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

	// Label is the visible label text shown next to the control.
	// Required for accessibility.
	Label string

	// ID is the input element's id. When empty, defaults to Name.
	// FormField-style components key error wiring off this id.
	ID string

	// Value is the form-submit value (for checkboxes / radios sharing
	// a Name). Defaults to "on" for Checkbox/Switch, required for
	// Radio when several share a Name.
	Value string

	// Checked is the initial selected state.
	Checked bool

	// Disabled disables interaction.
	Disabled bool

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

	// Help renders supporting text under the label.
	Help string

	// Error overrides Help and switches the control to the error state
	// (aria-invalid="true", red ring, role="alert" message).
	Error string

	// Attrs lets callers attach data-fui-* attributes (e.g. for RPC).
	ExtraAttrs html.Attrs

	Class string
}

type ToolbarConfig struct {
	// Label is the accessible name for the toolbar (required —
	// becomes aria-label).
	Label string
	// Groups are rendered in order with separators between.
	Groups []ToolbarGroup
	// Align picks justify-content. Default is "start". Options:
	// "start", "center", "end", "between".
	Align      string
	ID         string
	Class      string
	ExtraAttrs html.Attrs
}

type ToolbarGroup struct {
	// Label is the accessible group name (optional). When set the
	// group renders with role="group" + aria-label.
	Label string
	// Children are the actual button/link elements. The caller
	// decides what goes in — Button, Link, IconButton, etc.
	Children []render.HTML
}

type TooltipConfig struct {
	// Text is the tooltip message. Required.
	Text string

	// Placement selects the side. Default top.
	Placement TooltipPlacement

	// ID is the tooltip's id; the trigger's aria-describedby points
	// to it. When empty, a stable id is derived from the trigger's
	// content position.
	ID string

	Class string
}

type TooltipPlacement string

type TrendDirection string

type ValidationSummaryConfig struct {
	// Errors maps field names to error messages (required).
	Errors FieldErrors
	// FieldLabels maps field names to human-readable labels.
	// Falls back to the field name when not provided.
	FieldLabels map[string]string
	// FieldIDs maps field names to actual input element IDs.
	// When set, anchor links use these IDs so they point to the
	// correct input. Falls back to the field name when not provided.
	FieldIDs map[string]string
	// FieldOrder controls the order of error rows. Entries that aren't
	// in Errors are silently skipped, so it's safe to pass the full
	// form field list. Without FieldOrder, rows fall back to
	// alphabetical-by-field-name so the rendered HTML is deterministic
	// across requests (Go map iteration is randomized).
	FieldOrder []string
	// Title overrides the default banner heading. Empty → "Please fix
	// the following errors:".
	Title string
	// Class adds extra CSS classes to the wrapper.
	Class string
}

type WidgetMounter interface {
	MountWidget(def *widget.Definition)
}