display

type AccordionItem struct {
	ID      string
	Title   string
	Content templ.Component
	Open    bool
}

type AccordionProps struct {
	utils.BaseProps
	Items []AccordionItem
	// Exclusive, when true, renders every <details> with the same name
	// attribute — the platform's native exclusive disclosure group (Modern
	// Web Guidance: search-hidden-content, "mutually exclusive
	// disclosures"): opening one item closes the others, zero JS. The group
	// name derives from ID (or a generated one), so two accordions on the
	// same page never share a group. Engines without named details (older
	// Firefox) degrade to independent items — every item stays operable.
	Exclusive bool
}

type AreaChartProps struct {
	utils.BaseProps

	// Series is the data to plot.
	Series []LineChartSeries

	// XAxisLabels are category labels along the X-axis.
	XAxisLabels []string

	// Width is the SVG canvas width in pixels. Default: 600.
	Width int

	// Height is the SVG canvas height in pixels. Default: 300.
	Height int

	// Padding controls the inset around the plot area.
	Padding ChartPadding

	// Min overrides the auto-computed Y-axis minimum.
	Min *float64

	// Max overrides the auto-computed Y-axis maximum.
	Max *float64

	// MaxTicks is the tick budget for the Y axis: ComputeNiceTicks aims for
	// at most this many ticks. 0 or negative keeps the default of 8. The
	// final count is approximate — ticks snap to human-readable steps, so
	// the actual count can land slightly above or below the budget.
	MaxTicks int

	// ShowGrid renders dashed horizontal gridlines at each Y tick. Default: true.
	ShowGrid bool

	// ShowDots renders a circle at each data point. Default: false (cleaner area look).
	ShowDots bool

	// ShowLegend renders a color-swatch legend above the chart when 2+ series.
	ShowLegend bool

	// Style controls whether lines are straight (Linear) or curved (Smooth).
	Style LineChartStyle

	// FillOpacity controls the transparency of the area fill (0.0–1.0).
	// Default: 0.2.
	FillOpacity float64

	// ValueFormat formats Y-axis tick labels.
	ValueFormat func(float64) string

	// EmptyMessage is shown when Series is empty.
	EmptyMessage string
}

type AvatarProps struct {
	utils.BaseProps
	Src      string
	Alt      string
	Initials string
	Size     AvatarSize
	Shape    AvatarShape
	Status   AvatarStatus
}

type AvatarShape string

type AvatarSize string

type AvatarStatus string

type BadgeProps struct {
	utils.BaseProps
	Text string
	Type BadgeType
	Size BadgeSize
	Pill bool
	Dot  bool
	Href string
}

type BadgeSize string

type BadgeType string

type BarChartBar struct {
	// Label is the bar's category name (e.g. "general", "Alice").
	Label string

	// Value is the bar's magnitude.
	Value float64

	// Color overrides the default bar color — a complete light+dark bg-*
	// literal (e.g. "bg-emerald-600 dark:bg-emerald-500"). Empty = use default.
	Color tone.ColorClass

	// Href makes the bar label a clickable link.
	Href string

	// Tooltip sets a per-bar title attribute (native browser tooltip).
	// Useful for dense charts where per-bar labels are hidden.
	Tooltip string

	// ValueLabel overrides the auto-formatted value display. When set,
	// this string is shown instead of ValueFormat(Value). Useful for
	// composite labels like "123 (45%)" or "1.2 GB".
	ValueLabel string
}

type BarChartProps struct {
	utils.BaseProps

	// Bars are the data points to render.
	Bars []BarChartBar

	// Orient is the bar orientation. Default: BarHorizontal.
	Orient BarOrient

	// Max overrides the auto-computed maximum (0 = auto from data).
	Max float64

	// BarColor is the default bg-* literal for bars without a per-bar Color
	// override. Default: "bg-blue-600 dark:bg-blue-500".
	BarColor tone.ColorClass

	// LabelWidth is the label column width for horizontal charts (Tailwind
	// width class, e.g. "w-32"). Default: "w-32".
	LabelWidth string

	// ShowValues renders the numeric value next to each bar.
	ShowValues bool

	// ValueFormat formats the value for display. Default: fmt.Sprintf("%.0f", v).
	ValueFormat func(float64) string

	// EmptyMessage is shown when Bars is empty. Default: "No data".
	EmptyMessage string

	// MinBarWidth sets the minimum width for vertical bars (Tailwind
	// width class, e.g. "min-w-1" for dense time-series). Default: "min-w-12".
	MinBarWidth string

	// Gap controls the spacing between bars (Tailwind gap class,
	// e.g. "gap-px" for dense charts). Default: "gap-2" (vertical),
	// "" (horizontal, uses space-y-2).
	Gap string

	// Height sets the chart container height (CSS value, e.g. "8rem").
	// Essential for vertical charts — percentage bar heights need a
	// definite parent height. No effect on horizontal.
	Height string
}

type BarOrient string

type ButtonHTMLType string

type ButtonProps struct {
	utils.BaseProps

	Text     string
	Type     ButtonHTMLType // button, submit, reset (default: button; ignored when Href is set)
	Href     string         // if set, renders as <a> instead of <button>
	Variant  ButtonType     // default: Primary
	Size     ButtonSize     // default: MD
	Disabled bool
	Icon     templ.Component
	// Children, when set, replaces the default content (Icon + Text) inside
	// the element. Use it to compose rich button content — a spinner plus a
	// loading label, an icon-text stack, a badge — while keeping the
	// library's classes, variants, and Wire/HTMX attributes. Consumer-owned:
	// a11y of the inner markup is the consumer's responsibility (the element
	// still carries AriaLabel when set).
	Children templ.Component
	External bool // adds target="_blank" and rel="noopener noreferrer" for links
	// Wire is the optional transport-agnostic wiring (see the wire package).
	// When set, the action's attributes are rendered on the element in the
	// configured transport's dialect (htmx by default, Datastar opt-in) so
	// the same props work under either runtime. Composes with Attrs.
	Wire *wire.Action
}

type ButtonSize string

type ButtonType string

type CardPadding string

type CardProps struct {
	utils.BaseProps
	Title        string
	Subtitle     string
	Footer       templ.Component
	HeaderAction templ.Component
	// Header, when set, replaces the entire default header section (title,
	// subtitle, header action). Use this for custom header layouts that the
	// Title/Subtitle/HeaderAction fields can't express. When nil, the default
	// header renders if Title or HeaderAction is set.
	Header templ.Component
	// Body, when set, overrides children for the card's main content area.
	// Use this for struct-based composition; pass children for templ-block
	// composition. If both are set, Body takes precedence.
	Body    templ.Component
	Padding CardPadding
	// TitleTag overrides the heading element for the card title.
	// Defaults to h3 (HeadingTagH3) when empty. Set to HeadingTagH2 when the
	// card is the first heading level after a page <h1> to maintain correct
	// heading order for screen-reader navigation.
	TitleTag HeadingTagType
	// TitleClass, when set, overrides the default <h3> title classes. Consumer
	// classes are merged LAST so they win via tailwind-merge.
	TitleClass string
	// HeaderClass, when set, overrides the default header wrapper classes.
	// Consumer classes are merged LAST so they win via tailwind-merge.
	HeaderClass string
	// ContainerAware, when true, wraps the card in a @container div and swaps
	// sm: breakpoint classes for @sm: so padding adapts to container width,
	// not the viewport. Default false (viewport breakpoints). The @container
	// wrapper applies container-type: inline-size containment, which
	// suppresses the card's intrinsic width: inside shrink-to-fit parents
	// (flex rows, inline-block, auto-sized grid columns) a container-aware
	// card collapses to zero width unless the parent provides a definite
	// width. That is why Card is opt-in. See ADR-0018.
	ContainerAware bool
}

type CarouselProps struct {
	utils.BaseProps
	Slides         []CarouselSlide
	ShowIndicators bool
	ShowArrows     bool
}

type CarouselSlide struct {
	Content templ.Component
}

type ChartLegendItem struct {
	Name  string
	Color string
	X     int
}

type ChartPadding struct {
	Top    int
	Right  int
	Bottom int
	Left   int
}

type ChartRenderData struct {
	Width       int
	Height      int
	Padding     ChartPadding
	PlotW       int
	PlotH       int
	MinVal      float64
	MaxVal      float64
	RangeVal    float64
	Ticks       []float64
	HasData     bool
	LabelCount  int
	XAxisLabels []string
	ShowGrid    bool
	ValueFormat func(float64) string
	LegendItems []ChartLegendItem
	EmptyMsg    string
	Class       string
	AriaLabel   string
	ID          string
	Attrs       templ.Attributes
}

type CodeBlockProps struct {
	utils.BaseProps

	// Code is the text to display and copy. Rendered HTML-escaped by templ.
	Code string
	// Language optionally labels the block's language in the header
	// ("bash", "go"). It is a label only — CodeBlock does not syntax-highlight.
	Language string
	// Label optionally overrides the header label. Defaults to Language
	// when Language is set and Label is empty; both empty renders no header
	// label (a copy-only header when copying is enabled).
	Label string
	// NoCopy hides the copy button. The zero value shows it — both extraction
	// demand shapes (copyable command rows, ID rows) always carry copy.
	NoCopy bool
	// Variant selects block (zero value) or compact-id rendering.
	Variant CodeBlockVariant
}

type CodeBlockVariant string

type CollapsibleSectionProps struct {
	utils.BaseProps

	// Title is the section heading text.
	Title string

	// TitleTag is the heading element (h1–h6). Default: HeadingTagH3.
	TitleTag HeadingTagType

	// Collapsed controls whether the section starts collapsed on initial
	// render. Default: false (section is expanded).
	Collapsed bool

	// StorageKey, when non-empty, persists the open/closed state to
	// localStorage under this key. A consumer-side script reads the
	// data-collapsible attribute and toggles accordingly.
	StorageKey string

	// PersistState, when true, ships the persistence script with the
	// component: a CSP-safe, nonce'd singleton that restores the saved
	// open/closed state for every details[data-collapsible] on the page
	// and writes back on toggle (capture phase — toggle does not bubble).
	// Requires StorageKey AND BaseProps.Nonce; without a nonce the script
	// is skipped so strict-CSP pages never receive un-nonced inline JS.
	// Consumers who bring their own persistence script leave this false
	// (the default) and keep reading data-collapsible themselves.
	PersistState bool

	// Icon overrides the default chevron. Default: icons.ChevronDown.
	Icon icons.Name
}

type CommandGroup struct {
	Label string
	Items []CommandItem
}

type CommandItem struct {
	Label string
	Hint  string // secondary text rendered under or beside the label
	Href  string // link selection
	Wire  *wire.Action
}

type CommandPaletteProps struct {
	utils.BaseProps

	Placeholder  string
	Groups       []CommandGroup
	TriggerLabel string // renders an opener button when non-empty
	Hotkey       bool   // register Cmd/Ctrl+K to open
	EmptyMessage string
	Size         CommandPaletteSize
}

type CommandPaletteSize string

type ContextMenuItem struct {
	Text     string
	Href     string // when set, renders an <a>
	Disabled bool
}

type ContextMenuProps struct {
	utils.BaseProps
	Items []ContextMenuItem
}

type CopyButtonProps struct {
	utils.BaseProps
	// Text is the string to copy to the clipboard.
	Text string
	// Label is the button text in the idle state. Defaults to "Copy".
	Label string
	// CopiedLabel is the button text shown briefly after a successful copy.
	// Defaults to "Copied!".
	CopiedLabel string
	// Icon optionally renders a leading clipboard icon.
	Icon bool
	// Href, when set, renders an <a> instead of a <button>. The link still
	// copies text to the clipboard on click. Use for copy-as-link patterns.
	Href string
	// LabelClass, when set, replaces the label span's default color classes
	// (text-gray-700 dark:text-gray-200). Use for themes that re-color the
	// button's ancestors (re-colored tables, tinted cards) where the fixed
	// palette fights the surroundings — e.g. "text-emerald-700
	// dark:text-emerald-300" or a var(--…)-based pair of your own. The
	// [data-tc-copy-text] attribute stays as the CSS escape hatch for full
	// restyling.
	LabelClass string
}

type CountBadgeProps struct {
	utils.BaseProps
	// Count is the number to display in the badge.
	Count int
	// Max is the overflow threshold. When Count > Max, the badge shows
	// "Max+" instead of the raw number (e.g. Max=99, Count=150 → "99+").
	// Defaults to 99. Set to 0 to disable overflow.
	Max int
}

type DataStateProps struct {
	utils.BaseProps

	// State selects the rung. DataStateContent (the zero value) renders
	// Children; every other state renders the placeholder.
	State DataStateState
	// Title and Description carry the chosen state's copy — per-state truth,
	// so they sit on the props, not in the component.
	Title       string
	Description string
	// TitleTag overrides the placeholder's heading element (defaults to h3,
	// like EmptyState).
	TitleTag HeadingTagType
	// Icon overrides the state's default icon (empty: inbox, unavailable:
	// exclamation-triangle, disabled: no-symbol).
	Icon icons.Name
}

type DataStateState string

type DataTableColumn struct {
	Label    string
	Sortable bool
	// SortKey is the query-param value representing this column when sorting
	// (e.g. "created_at"). When empty, defaults to the lowercase Label.
	SortKey string
}

type DataTableProps struct {
	utils.BaseProps
	Columns []DataTableColumn
	Rows    []TableRow
	// ActiveSortColumn is the Label of the currently sorted column.
	ActiveSortColumn string
	// ActiveSortDir is the current sort direction of the active column.
	ActiveSortDir SortDirection
	// SortBaseURL is the base URL for sort links (e.g. "/users").
	// Query params for sort/dir are appended automatically.
	SortBaseURL string
	// SortParam is the query-parameter name for the sort column (default: "sort").
	SortParam string
	// DirParam is the query-parameter name for the sort direction (default: "dir").
	DirParam string
	// Pagination, when set, renders below the table. Pass a
	// navigation.Pagination component or any custom pager.
	Pagination templ.Component
	// EmptyState, when set and Rows is empty, replaces the table entirely.
	EmptyState templ.Component
	// Striped, Hover, Bordered — table appearance options (passed to Table).
	Striped  bool
	Hover    bool
	Bordered bool
	// Flush suppresses the table wrapper border — use when nesting inside
	// a Card(CardPaddingNone) to avoid double borders.
	Flush bool
	// CellPadding controls vertical density (passed to Table).
	CellPadding TableCellPadding
	// Caption is an accessibility-only table caption (visually hidden).
	Caption string
}

type DateFormat string

type DateRangeProps struct {
	utils.BaseProps
	Start *time.Time
	End   *time.Time
	// Layout overrides the date format. Defaults to "January 2006".
	Layout DateFormat
	// PresentText overrides the text shown when End is nil. Defaults to "Present".
	PresentText string
	// Separator overrides the range separator. Defaults to "–" (en dash).
	Separator string
}

type DefinitionGridProps struct {
	utils.BaseProps
	// Items are the term-detail pairs to render.
	Items []DefinitionItem
	// Cols controls the responsive column count. Defaults to GridCols3 when
	// empty or unknown.
	Cols GridCols
	// ContainerAware, when true, wraps the grid in a @container div and uses
	// container-query variants (@sm:, @lg:) instead of viewport breakpoints.
	// Default false (viewport breakpoints).
	ContainerAware bool
}

type DefinitionItem struct {
	Term   string
	Detail string
	// DetailComponent overrides Detail when set — use for badges, links, or
	// any rich content instead of plain text.
	DetailComponent templ.Component
}

type DefinitionListProps struct {
	utils.BaseProps
	Items []DefinitionItem
}

type DrawerProps struct {
	utils.BaseProps

	Title string
	Open  bool
	Side  DrawerSide
	Size  DrawerSize
}

type DrawerSide string

type DrawerSize string

type DropdownItem struct {
	Text     string
	Href     string
	Icon     icons.Name
	Kind     DropdownItemKind
	External bool
	Disabled bool
	Attrs    templ.Attributes
}

type DropdownItemKind string

type DropdownPosition string

type DropdownProps struct {
	utils.BaseProps
	Label string
	// Trigger, when set, replaces the default styled button CONTENT: the
	// component renders inside a functionally-wired <button> (popovertarget,
	// aria-haspopup, data-dropdown-trigger) with NO default visual classes,
	// so the custom component owns the trigger's entire appearance (e.g. an
	// avatar + email identity cluster). Leave nil for the default label +
	// chevron button.
	Trigger  templ.Component
	Items    []DropdownItem
	Position DropdownPosition
}

type EmptyStateProps struct {
	utils.BaseProps
	Title string
	// TitleTag overrides the heading element for the title.
	// Defaults to h3 (HeadingTagH3) when empty. Set to HeadingTagH2 when the
	// empty state is the first heading level after a page <h1>.
	TitleTag    HeadingTagType
	Description string
	Icon        icons.Name
	ActionText  string
	ActionHref  string
	ActionAttrs templ.Attributes
}

type ExternalLinkProps struct {
	utils.BaseProps

	// Href is the target URL. Passed as a plain string (NOT templ.SafeURL)
	// so that templ's built-in URL sanitizer runs — it blocks javascript:,
	// data:, vbscript: and other dangerous schemes by rewriting them.
	Href string

	// Text is the visible link text. When empty, children are rendered instead.
	Text string

	// ShowIcon controls whether the external-arrow icon (↗) is rendered.
	// Default: true.
	ShowIcon bool
}

type EyebrowProps struct {
	utils.BaseProps
	Text string
}

type GridCols string

type GridGap string

type GridProps struct {
	utils.BaseProps
	// Cols controls the responsive column count. Defaults to GridCols3 when
	// empty or unknown.
	Cols GridCols
	// Gap controls the spacing between grid items. Defaults to GridGapMD (gap-4).
	Gap GridGap
	// ContainerAware, when true, renders the grid inside an @container
	// wrapper so column counts respond to the container's width instead of
	// the browser viewport. Opt-in: the struct-literal zero value is
	// viewport-based; DefaultGridProps() sets it true. Set it explicitly
	// (true or false) whenever a bare GridProps{...} literal is used.
	ContainerAware bool
	// MinColWidth sets the minimum column width for auto-fit grids. Used only
	// when Cols is GridColsAutoFit. Generates a CSS auto-fit/minmax template
	// that responds to container width. Example: "190px" produces
	// grid-template-columns: repeat(auto-fit, minmax(190px, 1fr)).
	// Ignored for fixed column counts. When Cols is GridColsAutoFit,
	// ContainerAware is ignored (auto-fit already responds to container
	// width via CSS minmax).
	MinColWidth string
}

type HeadingLevel string

type HeadingTagType string

type HeatmapCell struct {
	// Value is the cell's magnitude.
	Value float64

	// Label is the tooltip text for the cell.
	Label string

	// Href makes the cell a clickable link.
	Href string
}

type HeatmapProps struct {
	utils.BaseProps

	// Rows are the data rows. Each row's Cells slice should have the same
	// length as ColumnLabels.
	Rows []HeatmapRow

	// ColumnLabels are the labels for each column (e.g. hour labels).
	ColumnLabels []string

	// Max overrides the auto-computed maximum value (0 = auto from data).
	Max float64

	// ColorVar is the CSS custom property used for cell background color.
	// Default: "--ds-brand".
	ColorVar string

	// CellSize is the Tailwind height class for each cell.
	// Default: "h-5".
	CellSize string

	// ShowValues renders the numeric value inside each cell.
	ShowValues bool

	// ValueFormat formats the value for display. Default: fmt.Sprintf("%.0f", v).
	ValueFormat func(float64) string

	// EmptyMessage is shown when Rows is empty. Default: "No data".
	EmptyMessage string

	// HighlightPeak adds a ring to the cell with the highest value.
	HighlightPeak bool
}

type HeatmapRow struct {
	// Label is the row heading (e.g. "Mon", "general").
	Label string

	// Cells are the per-column values for this row.
	Cells []HeatmapCell
}

type HoverCardPosition = Position

type HoverCardProps struct {
	utils.BaseProps
	Content  templ.Component
	Position HoverCardPosition
}

type ImageProps struct {
	utils.BaseProps
	// Src is the primary image URL.
	Src string
	// Alt text for accessibility. Required for non-decorative images.
	Alt string
	// SrcSet defines multiple image sources for responsive delivery.
	// Example: "photo-1x.jpg 1x, photo-2x.jpg 2x" or
	// "photo-480w.jpg 480w, photo-800w.jpg 800w".
	SrcSet string
	// Sizes defines the intended display width at different breakpoints.
	// Example: "(max-width: 600px) 480px, 800px".
	// Pair with a width-descriptor srcset for responsive images.
	Sizes string
	// Width in CSS pixels. When set, the img tag includes a width attribute
	// and helps prevent layout shift (CLS).
	Width int
	// Height in CSS pixels. When set, the img tag includes a height attribute.
	Height int
	// FallbackSrc, when non-empty, is used if Src fails to load. Handled via
	// a CSP-safe event-delegation script — no inline onerror handler.
	FallbackSrc string
	// Lazy controls the loading attribute AND the fetch priority. When true
	// (default) the img gets loading="lazy" and NO fetchpriority attribute;
	// set it to false for the above-the-fold LCP image, which then gets
	// loading="eager" plus fetchpriority="high".
	//
	// fetchpriority="low" is deliberately never emitted: pairing it with
	// loading="lazy" is a documented anti-pattern (Modern Web Guidance
	// "optimize-image-priority" makes it MANDATORY not to) — lazy images
	// already load at normal priority when they enter the viewport, and an
	// explicit low priority delays them further.
	Lazy bool
	// Rounded, when true, adds rounded-full for circular images (avatars, icons).
	// Defaults to false (rounded-md).
	Rounded bool
	// Placeholder, when non-empty, is a tiny image URL (a 10-30px thumbhash
	// or thumbnail) rendered blurred BEHIND the main image — the zero-JS
	// blur-up pattern. The placeholder fills the box while Src loads and is
	// covered the moment the full image paints (no JavaScript, no animation
	// timing to race). Consumer generates the tiny image; the library adds
	// only CSS.
	Placeholder string
}

type KanbanBoardProps struct {
	utils.BaseProps
	// Columns renders left to right (right to left under dir="rtl").
	Columns []KanbanColumn
	// Wire is the move exchange. nil or empty URL renders a read-only board.
	// Method defaults to POST, Event to submit, ContentType to form
	// encoding; under htmx, Target defaults to the board root with
	// hx-swap="outerHTML".
	//
	// Sorted views: the submitted index is advisory — the server owns the
	// real ordering. On a server-sorted view (by priority, created-at, …)
	// reject same-column moves in the handler; the sort re-asserts on
	// re-render and would otherwise make the drop look broken. See
	// docs/recipes/kanban-card-anatomy.md ("Moves on a sorted view").
	Wire *wire.Action
	// EmptyColumnText shows inside a column with no cards. Default "No cards".
	EmptyColumnText string
	// CSRFToken, when set, renders a hidden CSRF input (name from
	// CSRFTokenName) inside the move form so submissions pass token checks.
	CSRFToken string
	// CSRFTokenName is the hidden input's name. Default "csrf_token".
	CSRFTokenName string
}

type KanbanCard struct {
	// ID is the stable card identity submitted as the move's card field.
	// It must survive re-renders (never auto-generate it per request).
	ID string
	// Title is the card's heading text.
	Title string
	// Href, when set, links the card title to a detail page.
	Href string
	// Content renders arbitrary card body below the title (labels, avatars,
	// metadata). Compose with Badge, Avatar, RelativeTime, … — the proven
	// anatomy (identity badges, 2+N tag overflow, assignee stack, one-line
	// description preview) is docs/recipes/kanban-card-anatomy.md; the
	// compiling composition is ExampleKanbanBoard_cardAnatomy.
	Content templ.Component
	// Class overrides the card's Tailwind classes.
	Class string
}

type KanbanColumn struct {
	// ID is the stable column identity submitted as the move's column field.
	ID string
	// Title is the column heading.
	Title string
	// Cards renders in order, top to bottom.
	Cards []KanbanCard
	// Action is an optional affordance rendered in the column header after
	// the count badge — the standard "add card" spot. The consumer owns the
	// whole element: compose display.Button (its Wire field for transport
	// wiring), a plain link, or any templ markup — and owns its
	// accessibility too: whatever renders there must be keyboard-reachable
	// (a real button or link, not a hover-only div). nil omits it; boards
	// without it render byte-identical to before.
	Action templ.Component
	// Tone is an optional status color rendered as a small dot before the
	// column title (todo=blue, done=green, …). The zero value (and any
	// unknown value) renders no dot — see KanbanTone.
	Tone KanbanTone
	// Class overrides the column's Tailwind classes.
	Class string
}

type KanbanMove struct {
	Card   string `form:"card"`
	Column string `form:"column"`
	Index  int    `form:"index"`
}

type KanbanTone string

type LightboxImage struct {
	// Src is the full-size image URL.
	Src string
	// Alt is the image's alternative text (required for a11y).
	Alt string
	// Caption optionally renders under the image.
	Caption string
	// ThumbSrc optionally overrides the thumbnail source (TriggerLabel
	// button mode uses Src when empty).
	ThumbSrc string
}

type LightboxProps struct {
	utils.BaseProps

	// Images renders in order; the viewer navigates them with wrap-around.
	Images []LightboxImage
	// TriggerLabel renders one opener button with this text (Thumbnails
	// overrides it). Empty + no Thumbnails renders the dialog only —
	// open it yourself via tcOpenLightbox("<id>-dialog", index).
	TriggerLabel string
	// Thumbnails renders one opener button per image (using ThumbSrc/Src
	// as its thumbnail) instead of a single TriggerLabel button.
	Thumbnails bool
}

type LineChartProps struct {
	utils.BaseProps

	// Series is the data to plot. Each series becomes one line.
	Series []LineChartSeries

	// XAxisLabels are category labels along the X-axis (e.g. month names).
	// If empty, no X-axis labels are rendered.
	XAxisLabels []string

	// Width is the SVG canvas width in pixels. Default: 600.
	Width int

	// Height is the SVG canvas height in pixels. Default: 300.
	Height int

	// Padding controls the inset around the plot area. Default: DefaultChartPadding().
	Padding ChartPadding

	// Min overrides the auto-computed Y-axis minimum (nil = auto from data).
	Min *float64

	// Max overrides the auto-computed Y-axis maximum (nil = auto from data).
	Max *float64

	// MaxTicks is the tick budget for the Y axis: ComputeNiceTicks aims for
	// at most this many ticks. 0 or negative keeps the default of 8. The
	// final count is approximate — ticks snap to human-readable steps, so
	// the actual count can land slightly above or below the budget.
	MaxTicks int

	// ShowGrid renders dashed horizontal gridlines at each Y tick. Default: true.
	ShowGrid bool

	// ShowDots renders a circle at each data point. Default: true.
	ShowDots bool

	// ShowLegend renders a color-swatch legend above the chart when there
	// are 2+ series. Default: true.
	ShowLegend bool

	// Style controls whether lines are straight (Linear) or curved (Smooth).
	// Default: LineChartStyleLinear.
	Style LineChartStyle

	// ValueFormat formats Y-axis tick labels. Default: FormatTickValue.
	ValueFormat func(float64) string

	// EmptyMessage is shown when Series is empty. Default: "No data".
	EmptyMessage string
}

type LineChartSeries struct {
	// Name is the series label shown in the legend.
	Name string

	// Values are the Y-axis data points.
	Values []float64

	// Color overrides the palette color — a complete light+dark literal
	// (prefer the ChartColor* constants; e.g. ChartColorEmerald). Empty =
	// palette by index.
	Color tone.ColorClass

	// StrokeWidth is the line thickness. Default: 2.
	StrokeWidth float64

	// Dashed renders the line with a dashed pattern.
	Dashed bool
}

type LineChartStyle string

type ListNoteProps struct {
	utils.BaseProps
	// Shown is the number of items currently rendered.
	Shown int
	// Total is the unfiltered/cap-exceeding match count. Read by the
	// truncated variant ("N of M") and by ListNoteRange (the Z in
	// "X–Y of Z"); ignored by ListNoteCount.
	Total int
	// RangeFrom is the 1-based index of the first item on the current page
	// (ListNoteRange only). Non-positive values degrade to the count message.
	RangeFrom int
	// RangeTo is the 1-based index of the last item on the current page
	// (ListNoteRange only). Non-positive values degrade to the count message.
	RangeTo int
	// Variant selects count semantics. Defaults to ListNoteTruncated.
	Variant ListNoteVariant
}

type ListNoteVariant string

type LivePillProps struct {
	utils.BaseProps

	// Tone selects the dot's semantic color.
	Tone StatusTone
	// Text is the visible label ("Live", "Reconnecting…").
	Text string
	// Pulse renders the radiating ring on the pill's dot.
	Pulse bool
}

type LoadingDialogProps struct {
	utils.BaseProps
	// Title names the dialog for assistive technology (aria-label fallback
	// after AriaLabel and Message). It is not rendered as a visible header —
	// a blocking loading state has nothing to close, so the dialog ships no
	// header bar and no close button.
	Title string
	// Message is the visible loading text (also the aria-label fallback).
	Message string
	// ShowProgress swaps the "Please wait..." hint for a determinate bar.
	ShowProgress bool
	// Progress is clamped to [0, 100] before rendering.
	Progress int
	// Open auto-shows the dialog on load (native showModal via the shared
	// overlay script). Toggle at runtime with tcOpenModal(id)/tcCloseModal(id)
	// or the dialog element's native showModal()/close().
	Open bool
}

type ModalProps struct {
	utils.BaseProps

	Title string
	Open  bool
	Size  ModalSize
}

type ModalSize string

type OverlayKind string

type PageHeaderProps struct {
	utils.BaseProps
	Title string
	// TitleComponent, when set, renders inside the <h1> instead of the Title
	// string — for code elements, badges, or copy buttons inside the header
	// title. Takes precedence over Title.
	TitleComponent templ.Component
	// Subtitle renders below the title in muted text.
	Subtitle string
	// SubtitleComponent, when set, renders inside the subtitle <p> instead
	// of the Subtitle string. Takes precedence over Subtitle.
	SubtitleComponent templ.Component
	// Breadcrumb renders above the title (optional). Pass a navigation.Breadcrumbs
	// component or any custom breadcrumb markup.
	Breadcrumb templ.Component
	// Action renders on the right side of the title row (optional). Use for
	// primary buttons, back links, or status badges.
	Action templ.Component
}

type PieChartLabelMode string

type PieChartProps struct {
	utils.BaseProps

	// Slices is the data to plot.
	Slices []PieChartSlice

	// Width is the SVG canvas width in pixels. Default: 400.
	Width int

	// Height is the SVG canvas height in pixels. Default: 300.
	Height int

	// Donut renders a donut (ring) chart with an inner hole. Default: false (full pie).
	Donut bool

	// InnerRadius controls the donut hole size as a fraction of the radius
	// (0.0–1.0). Default: 0.6.
	InnerRadius float64

	// ShowLabels renders slice labels outside the pie. Default: true.
	ShowLabels bool

	// LabelMode controls label positioning. Default: PieChartLabelExternal.
	LabelMode PieChartLabelMode

	// ShowLegend renders a color-swatch legend below the chart. Default: true.
	ShowLegend bool

	// CenterLabel is text rendered in the center of a donut chart (e.g. "128GB").
	CenterLabel string

	// EmptyMessage is shown when Slices is empty. Default: "No data".
	EmptyMessage string
}

type PieChartSlice struct {
	// Label is the slice's category name.
	Label string

	// Value is the slice's magnitude. Must be non-negative.
	Value float64

	// Color overrides the palette color with a Tailwind text-* class
	// (e.g. "text-emerald-600 dark:text-emerald-400"). Empty = palette by index.
	Color tone.ColorClass
}

type Point struct {
	X, Y float64
}

type PopoverPosition = Position

type PopoverProps struct {
	utils.BaseProps
	TriggerText string
	Position    PopoverPosition
}

type Position string

type ProseProps struct {
	utils.BaseProps

	// Children is the longform content (typically rendered markdown HTML).
	// When nil, Prose renders its templ trailing block instead — both call
	// styles work (the doc example uses the trailing block; programmatic Go
	// consumers set this field). Before the fallback shipped (2026-10-30),
	// trailing-block callers got an EMPTY container — the demo's own Prose
	// section shipped empty for weeks.
	Children templ.Component
	// Size sets the font scale. Zero value falls back to ProseSizeMD.
	Size ProseSize
}

type ProseSize string

type RelativeTimeProps struct {
	utils.BaseProps
	// Time is the timestamp to display relative to now.
	Time time.Time
	// Now, when non-zero, pins the reference instant the relative string is
	// computed against (defaults to time.Now at render time). Tests use it to
	// pin boundary behavior ("59s vs 60s") deterministically; production
	// callers leave it zero.
	Now time.Time
	// Title, when non-empty, overrides the default title (absolute time shown
	// on hover). Set to "" to use the formatted absolute timestamp.
	Title string
	// EmptyText, when non-empty and Time is the zero value, renders this text
	// instead of a relative string: zero timestamps mean "never" (never
	// rotated, never used), and date noise like "Jan 1, 0001" is the opposite
	// of the information the reader needs. The empty render stays inside the
	// <time> shell but omits the meaningless zero datetime, the default
	// zero-date title, and data-tc-relative (the auto-refresh script would
	// re-format the placeholder into date noise). Unset, or a non-zero Time,
	// keeps the exact prior behavior.
	EmptyText string
	// AutoRefresh defaults to true — the component injects a singleton script
	// that uses the native Intl.RelativeTimeFormat API to live-update the text
	// every 30 seconds. Also listens to htmx:afterSettle so newly-swapped
	// <time> elements are formatted immediately. This is progressive enhancement:
	// the server-rendered text is correct without JS; the script just keeps it
	// fresh. Set to false for static contexts (PDF, email, SEO-only).
	AutoRefresh bool
}

type ScrollbackLine struct {
	Timestamp string
	Tag       string
	Text      string
	Tone      ScrollbackTone
}

type ScrollbackProps struct {
	utils.BaseProps
	// Lines renders top-down in the given order. Empty slice renders nothing.
	Lines []ScrollbackLine
	// Stagger animates lines in sequentially (pure CSS, reduced-motion safe).
	// DefaultScrollbackProps enables it; the zero value renders instantly.
	Stagger bool
}

type ScrollbackTone string

type SectionHeadingProps struct {
	utils.BaseProps
	Title    string
	Level    HeadingLevel
	Align    TextAlign
	SubTitle string
}

type SegmentBarProps struct {
	utils.BaseProps

	// Segments stack in the given order. A bar with no positive-value
	// segments renders nothing (an empty proportion bar is no bar).
	Segments []SegmentBarSegment
	// NoLegend hides the dot+label+percent legend. The zero value shows it.
	NoLegend bool
}

type SegmentBarSegment struct {
	// Label names the segment in the legend and the accessible summary.
	Label string
	// Value is the segment's magnitude (relative to the sum of all values).
	// Negative values clamp to zero.
	Value float64
	// Color optionally overrides the deterministic palette — a complete
	// light+dark literal pair such as "bg-emerald-600 dark:bg-emerald-400".
	Color tone.ColorClass
}

type SimpleCardProps struct {
	utils.BaseProps
	Padding CardPadding
	// Body, when set, overrides children — same pattern as CardProps.Body.
	Body templ.Component
}

type SortDirection string

type SparklineProps struct {
	utils.BaseProps

	// Values are the data points to plot. Fewer than 2 points renders nothing.
	Values []float64

	// Width is the SVG canvas width in pixels. Default: 120.
	Width int

	// Height is the SVG canvas height in pixels. Default: sparklineDefaultHeight.
	Height int

	// StrokeWidth controls the line thickness. Default: 1.5.
	StrokeWidth float64

	// Filled renders a filled area beneath the line (default: false).
	Filled bool

	// Min overrides the auto-computed minimum value (nil = auto from data).
	Min *float64

	// Max overrides the auto-computed maximum value (nil = auto from data).
	Max *float64
}

type StatCardProps struct {
	utils.BaseProps
	Value  string
	Label  string
	Change string
	Trend  TrendDirection
	// Tone selects the semantic color of the Icon tile. Empty/unknown
	// values fall back to the blue default.
	Tone StatTone
	// Icon optionally renders a leading icon tile (e.g. icons.Users).
	Icon icons.Name
	// Href, when non-empty, wraps the whole card in an <a> so the card acts
	// as a clickable navigation/filter link. Use this for dashboard stat cards
	// that drill down into a filtered view.
	Href string
	// HxGet, when set, adds hx-get to the card for HTMX-driven updates.
	// Mutually independent of Href — Href navigates, HxGet fetches partial HTML.
	HxGet string
	// HxTarget specifies the hx-target attribute (CSS selector for the swap target).
	HxTarget string
	// HxSwap specifies the hx-swap attribute (e.g. htmx.SwapInnerHTML, htmx.SwapOuterHTML).
	HxSwap htmx.SwapStyle
	// ValueID, when non-empty, sets the id attribute on the value <dd> node.
	// Use on live-updating dashboards whose scripts address the value
	// directly instead of querying the card's internal structure — so a
	// markup refactor inside the card cannot break the script's selector.
	ValueID string
}

type StatTone string

type StatusBadgeMapper func(status string) BadgeType

type StatusDotProps struct {
	utils.BaseProps

	// Tone selects the semantic color (neutral gray by default).
	Tone StatusTone
	// Pulse renders the radiating ring — live indicators. The zero value
	// is a static dot; the animation carries a motion-reduce fallback.
	Pulse bool
	// Label, when set, renders screen-reader text naming the state — a
	// colored dot that is the ONLY status indicator must be announced.
	// Without a Label the dot renders aria-hidden (decorative next to
	// visible text you provide).
	Label string
}

type StatusTone string

type Tab struct {
	ID      string
	Label   string
	Content templ.Component
}

type TableCell struct {
	Text    string
	Content templ.Component
}

type TableCellPadding string

type TableHeader struct {
	Label         string
	Sortable      bool
	SortDirection SortDirection
	Href          string // When set with Sortable=true, renders as <a> for server-side sorting
}

type TableProps struct {
	utils.BaseProps
	Caption      string
	Headers      []string
	TypedHeaders []TableHeader // When set, takes precedence over Headers for sortable column rendering
	Rows         []TableRow
	Striped      bool
	Hover        bool
	Bordered     bool
	// Flush, when true, suppresses the wrapper div's border and rounded corners.
	// Use this when the table is nested inside a Card(CardPaddingNone) to avoid
	// a double border — the card provides the outer border, and the table sits
	// flush against it. The overflow-x-auto scroll wrapper is always retained.
	Flush bool
	// StickyHeader, when true, pins the header row to the top of the table's
	// scroll container (sticky top-0 + z). Effective when the table scrolls
	// vertically — inside a height-constrained wrapper or a scrollable
	// ancestor (the built-in overflow-x-auto wrapper counts as a scroll
	// container). Harmless no-op on short tables.
	StickyHeader bool
	// CellPadding controls the vertical density of header and body cells.
	// Defaults to TableCellPaddingComfortable (px-4 py-3). Set to
	// TableCellPaddingCompact (px-4 py-2) for data-heavy dashboards and admin
	// panels where rows should feel tighter.
	CellPadding TableCellPadding
	// LazyRows, when true, applies content-visibility: auto to body rows.
	// The browser skips rendering off-screen rows, giving 2-5x faster initial
	// render for tables with 100+ rows. Uses contain-intrinsic-size so the
	// scrollbar stays accurate. Recommended for large data tables.
	LazyRows bool
	// Body, when set, overrides Rows for the <tbody> content. The component
	// should render <tr> elements directly — ideal for templ loops where each
	// row needs custom cell rendering:
	//
	//	@display.Table(display.TableProps{
	//	    Headers: headers,
	//	    Body:    messageRows(messages),
	//	})
	//	templ messageRows(messages []Message) {
	//	    for _, m := range messages {
	//	        <tr><td>{ m.Text }</td><td>{ m.Author }</td></tr>
	//	    }
	//	}
	Body templ.Component
	// BodyID, when non-empty, sets the id attribute on the <tbody> element.
	// Use on live-updating dashboards whose scripts swap rows without
	// querying the table's internal structure — so a markup refactor inside
	// the table cannot break the script's selector.
	BodyID string
}

type TableRow struct {
	Cells []TableCell
	// Href, when non-empty, makes the entire row clickable. The row gets
	// data-tc-row-href, role="link", tabindex="0", and cursor-pointer.
	Href string
	// Class, when set, is merged onto the row's <tr> (consumer classes last,
	// tailwind-merge resolves conflicts). Use it for per-row styling — e.g.
	// a hover treatment on a Body-less table without flipping Table.Hover
	// for every row, or a status tint on specific rows — without the
	// dummy-Href hack of borrowing the clickable-row styling.
	Class string
}

type TabsProps struct {
	utils.BaseProps
	Tabs        []Tab
	ActiveTabID string
	Variant     TabsVariant
	ClientSide  bool
	// Wire, when set, switches the tabs from client-side toggling to
	// SERVER-side switching: each tab link carries the wired action with the
	// URL's `{tab}` placeholder substituted by that tab's ID (the same
	// URL-template convention as the Calendar MonthNav `{year}`/`{month}`),
	// and the endpoint re-renders the WHOLE Tabs component with the new
	// ActiveTabID. Under htmx the action self-replaces the container with
	// `outerHTML settle:0s` (the Calendar re-bind-window rationale: without
	// settle, rapid tab clicks land in htmx's ~20ms processing window and
	// silently no-op); under Datastar targeting is response-driven
	// (wire.Handler) or id-matched — give the fragment root the Tabs' id.
	// An empty Wire.Target defaults to the component's own `#ID` when ID is
	// set. Wire is nil-safe inert: an empty URL wires nothing. ClientSide is
	// ignored when Wire is set (one switching model at a time); the anchors'
	// hash hrefs remain as the no-JS fallback, so the clone sets
	// PreventDefault (the Datastar runtime auto-prevents only form+submit).
	Wire *wire.Action
}

type TabsVariant string

type TextAlign string

type TooltipPosition = Position

type TooltipProps struct {
	utils.BaseProps
	Text     string
	Position TooltipPosition
}

type TrendDirection string