@domphy/ui 0.21.5 → 0.22.0

package/dist/index.d.cts

@@ -86,13 +86,23 @@ declare function blockquote(props?: {
 
 /**
  * A horizontal breadcrumb navigation that lays out its children with a
- * separator between items and highlights the `[aria-current=page]` item.
- * Apply to a `<nav>` element.
+ * separator between items and marks the `[aria-current=page]` item
+ * non-interactive. Apply to a `<nav>` element.
+ *
+ * Does not paint `color` on any crumb — each composed child (`link()` for
+ * non-current items, `strong()` for the current one, or any other patch) owns
+ * its own color; wrap the current crumb in `strong()` for the usual "reads
+ * stronger" emphasis rather than relying on breadcrumb to repaint it.
  *
  * @hostTag nav
- * @param props.color - Color tone for links/separators. Optional `ValueOrState<ThemeColor>`, default "neutral".
+ * @param props.color - Color tone for the nav's own background/inherited text
+ *   color and the separator glyphs. Optional `ValueOrState<ThemeColor>`, default "neutral".
  * @param props.separator - String inserted between items via `::after`. Optional `string`, default "/".
- * @example { nav: null, $: [breadcrumb({ separator: "›" })] }
+ * @example
+ * { nav: [
+ *   { a: "Home", href: "#", $: [link()] },
+ *   { strong: "Settings", ariaCurrent: "page", $: [strong()] },
+ * ], $: [breadcrumb({ separator: "›" })] }
  */
 declare function breadcrumb(props?: {
     color?: ValueOrState<ThemeColor>;
@@ -153,7 +163,7 @@ declare function button(props?: {
  * @param props.color - Text color tone. Optional `ValueOrState<ThemeColor>`, defaults to `"neutral"`.
  * @param props.size - Button size preset. Optional `"small" | "medium" | "large"`, defaults to `"medium"`.
  * @example { button: "×", $: [buttonGhost()] }
- * @example { button: { span: null, $: [icon({ name: "trash" })] }, $: [buttonGhost({ color: "error" })] }
+ * @example { button: [{ span: "🗑", $: [icon()] }], $: [buttonGhost({ color: "error" })] }
  */
 declare function buttonGhost(props?: {
     color?: ValueOrState<ThemeColor>;
@@ -168,7 +178,7 @@ declare function buttonGhost(props?: {
  * @param props.checked - Toggle state. Optional `ValueOrState<boolean>`, default false.
  * @param props.accentColor - Color tone when checked (on). Optional `ValueOrState<ThemeColor>`, default "primary".
  * @param props.color - Color tone when unchecked (off track). Optional `ValueOrState<ThemeColor>`, default "neutral".
- * @example { button: { span: null }, $: [buttonSwitch({ checked: true })] }
+ * @example { button: [{ span: null }], $: [buttonSwitch({ checked: true })] }
  */
 declare function buttonSwitch(props?: {
     checked?: ValueOrState<boolean>;
@@ -183,15 +193,15 @@ declare function buttonSwitch(props?: {
  * `<div>` (any block container).
  *
  * @param props.color - Surface/border color tone. Optional `ValueOrState<ThemeColor>`, default "neutral".
- * @example { div: { h3: "Title", p: "Body" }, $: [card({ color: "neutral" })] }
+ * @example { div: [{ h3: "Title", $: [heading()] }, { p: "Body", $: [paragraph()] }], $: [card({ color: "neutral" })] }
  */
 declare function card(props?: {
     color?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
 /**
- * Styles an inline code snippet with a subtle surface background, rounded corners,
- * and shifted tone. Apply to a `<code>` element.
+ * Styles an inline code snippet in the theme's monospace stack, with a subtle
+ * surface background, rounded corners, and shifted tone. Apply to a `<code>` element.
  *
  * @hostTag code
  * @param props.color - Surface/text color tone. Optional `ValueOrState<ThemeColor>`, default "neutral".
@@ -249,7 +259,7 @@ declare function command(): PartialElement;
  * @hostTag input
  * @param props.color - Base theme color tone. Defaults to "neutral".
  * @param props.accentColor - Accent color used for the focus border. Defaults to "primary".
- * @example { input: "", $: [commandSearch({ accentColor: "primary" })] }
+ * @example { input: null, $: [commandSearch({ accentColor: "primary" })] }
  */
 declare function commandSearch(props?: {
     color?: ThemeColor;
@@ -259,10 +269,11 @@ declare function commandSearch(props?: {
  * Selectable item in a command palette. On mount, immediately hides itself if
  * the current query doesn't match its text content, and subscribes to future
  * query changes — so items added dynamically after a search is typed are
- * correctly filtered. Typically applied to a `<button>` (or any clickable
- * element) used inside a `command()`. Uses native button semantics (not
- * `role=option`) so the search input may sit as a sibling without a listbox
- * parent requirement.
+ * correctly filtered. Apply to a `<button>` inside a `command()`. Uses native
+ * button semantics (not `role=option`) so the search input may sit as a
+ * sibling without a listbox parent requirement. A non-focusable host (a bare
+ * `<div>`) still filters, but the container's arrow-key walk calls `focus()`
+ * on it and that is a no-op — give such a host a `tabindex` of its own.
  *
  * @param props.color - Base theme color tone. Defaults to "neutral".
  * @param props.accentColor - Accent color used for the focus ring. Defaults to "primary".
@@ -321,7 +332,7 @@ interface DatePickerProps {
  * @param props.onChange - Called with the new value whenever the selection changes, `(value: DatePickerValue) => void`.
  * @param props.accentColor - Accent color (`ValueOrState<ThemeColor>`) for selected/active days. Defaults to "primary".
  * @param props.placement - Popover placement (`ValueOrState<Placement>`) relative to the input. Defaults to "bottom-start".
- * @example { input: "", $: [inputText(), datePicker({ mode: "range" })] }
+ * @example { input: null, $: [inputText(), datePicker({ mode: "range" })] }
  */
 declare function datePicker(props?: DatePickerProps): PartialElement;
 
@@ -501,7 +512,7 @@ declare function fab(props?: {
  *
  * @hostTag figure
  * @param props.color - Theme color tone (`ValueOrState<ThemeColor>`) for the figure/caption text. Defaults to "neutral".
- * @example { figure: [{ img: "", src }, { figcaption: "A caption" }], $: [figure()] }
+ * @example { figure: [{ img: null, src: "chart.png", alt: "Quarterly revenue" }, { figcaption: "A caption" }], $: [figure()] }
  */
 declare function figure(props?: {
     color?: ValueOrState<ThemeColor>;
@@ -515,7 +526,7 @@ declare function figure(props?: {
  * @hostTag fieldset
  * @param props.color - Theme color tone (`ValueOrState<ThemeColor>`) for legend/text/surface. Defaults to "neutral".
  * @param props.layout - Field arrangement, "horizontal" (label beside control) | "vertical" (label above). Defaults to "horizontal".
- * @example { fieldset: [{ legend: "Profile" }, { label: "Name" }, { input: "" }], $: [formGroup({ layout: "vertical" })] }
+ * @example { fieldset: [{ legend: "Profile" }, { label: "Name" }, { input: null }], $: [formGroup({ layout: "vertical" })] }
  */
 declare function formGroup(props?: {
     color?: ValueOrState<ThemeColor>;
@@ -575,7 +586,7 @@ declare function grid(props?: {
  * Styles a heading, scaling its font size by level (h1 largest … h6 smallest)
  * relative to the theme base size. Apply to a heading element `<h1>`–`<h6>`.
  *
- * @hostTag h1
+ * @hostTag h1-h6
  * @param props.color - Theme color tone (`ValueOrState<ThemeColor>`) for the heading text. Defaults to "neutral".
  * @param props.size - Optional `ElementSize` (`"inherit"` | `"increase-N"` | `"decrease-N"`, N ≤ 7). When set, font size is `themeSize(listener, size)` including `"inherit"` (no tag bump). When omitted, follows the host tag (`h1` increase-4 … `h6` decrease-1).
  * @example { h2: "Section title", $: [heading()] }
@@ -592,7 +603,7 @@ declare function heading(props?: {
  *
  * @hostTag hr
  * @param props.color - Theme color tone (`ValueOrState<ThemeColor>`) for the rule. Defaults to "neutral".
- * @example { hr: "", $: [horizontalRule()] }
+ * @example { hr: null, $: [horizontalRule()] }
  */
 declare function horizontalRule(props?: {
     color?: ValueOrState<ThemeColor>;
@@ -610,17 +621,34 @@ declare function icon(props?: {
     color?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
+type ImageProps = {
+    color?: ValueOrState<ThemeColor>;
+} & ({
+    alt: string;
+    decorative?: false;
+} | {
+    decorative: true;
+    alt?: undefined;
+});
 /**
  * Styles a responsive image: full-width, cover-fit, rounded corners with a
  * themed placeholder background. Apply to an `<img>` element.
  *
+ * `alt` is a required prop (WCAG 1.1.1) forwarded onto the host as the native
+ * `alt` attribute, not left for the call site to declare separately — a
+ * native `alt` on the host element still wins over this if both are given
+ * (Domphy's usual native-over-patch merge), but every call site must now
+ * make an explicit choice. Pass `decorative: true` for `alt=""` (purely
+ * decorative images the caller does not want announced).
+ *
  * @hostTag img
+ * @param props.alt - Accessible text alternative. Required unless `decorative: true`.
+ * @param props.decorative - Marks the image as pure decoration — renders `alt=""` so assistive tech skips it. Optional.
  * @param props.color - Optional theme color tone for the placeholder background (`ValueOrState<ThemeColor>`). Defaults to `"neutral"`.
- * @example { img: null, src: "photo.jpg", alt: "Photo", $: [image()] }
+ * @example { img: null, src: "photo.jpg", $: [image({ alt: "A scenic mountain photo" })] }
+ * @example { img: null, src: "divider.svg", $: [image({ decorative: true })] }
  */
-declare function image(props?: {
-    color?: ValueOrState<ThemeColor>;
-}): PartialElement;
+declare function image(props: ImageProps): PartialElement;
 
 /**
  * Styles a custom checkbox with themed box, check mark, indeterminate state,
@@ -707,7 +735,7 @@ declare function inputNumber(props?: {
  * (e.g. `<div>`) whose direct children are the OTP `<input>` boxes. Takes no
  * props.
  *
- * @example { div: null, $: [inputOTP()], children: [{ input: null }, { input: null }] }
+ * @example { div: [{ input: null }, { input: null }], $: [inputOTP()] }
  */
 declare function inputOTP(): PartialElement;
 
@@ -810,7 +838,7 @@ declare function inputSwitch(props?: {
  * @param props.type - The input's `type` attribute (e.g. `"email"`, `"url"`, `"tel"`). Defaults to `"text"`.
  * @param props.color - Base color tone for text/border/background. Defaults to `"neutral"`.
  * @param props.accentColor - Accent color tone for the hover/focus outline. Defaults to `"primary"`.
- * @example { input: "", type: "text", placeholder: "Name", $: [inputText()] }
+ * @example { input: null, type: "text", placeholder: "Name", $: [inputText()] }
  */
 declare function inputText(props?: {
     type?: string;
@@ -819,8 +847,8 @@ declare function inputText(props?: {
 }): PartialElement;
 
 /**
- * Renders keyboard-key styling (themed background, border and padding) for a
- * keystroke hint. Apply to a `<kbd>` element.
+ * Renders keyboard-key styling (the theme's monospace stack, themed background,
+ * border and padding) for a keystroke hint. Apply to a `<kbd>` element.
  *
  * @hostTag kbd
  * @param props - Optional configuration.
@@ -992,6 +1020,27 @@ interface MotionProps {
         iterations?: number;
     };
 }
+/**
+ * Animation primitive driven by the Web Animations API. Runs an enter
+ * animation on mount (`initial` -> `animate`), re-animates whenever `animate`
+ * is a `State` that changes, and plays the `exit` keyframe before removal.
+ * Has no host-tag restriction; apply to any element you want to animate.
+ *
+ * Later generations route a fresh `animate`/`exit`/`transition` into the same
+ * `behavior()` instance via `update()`, so a reused node is not stuck on
+ * generation-1 keyframes.
+ *
+ * @param props - Optional configuration (see {@link MotionProps}).
+ * @param props.initial - Starting keyframe applied before the enter animation.
+ * @param props.animate - Target keyframe, or a `State` to re-animate on change.
+ * @param props.exit - Keyframe animated to before the element is removed.
+ * @param props.transition - Timing options.
+ * @param props.transition.duration - Duration in ms. Defaults to `300`.
+ * @param props.transition.delay - Delay in ms. Defaults to `0`.
+ * @param props.transition.easing - CSS easing. Defaults to `"ease"`.
+ * @param props.transition.iterations - Number of iterations. Defaults to `1`.
+ * @example { div: "Hello", $: [motion({ initial: { opacity: 0 }, animate: { opacity: 1 } })] }
+ */
 declare function motion(props?: MotionProps): PartialElement;
 
 /**
@@ -1001,7 +1050,7 @@ declare function motion(props?: MotionProps): PartialElement;
  * @hostTag ol
  * @param props - Optional configuration.
  * @param props.color - Color tone for the list text. Defaults to `"neutral"`.
- * @example { ol: "", $: [orderedList()], children: [{ li: "First" }] }
+ * @example { ol: [{ li: "First" }, { li: "Second" }], $: [orderedList()] }
  */
 declare function orderedList(props?: {
     color?: ValueOrState<ThemeColor>;
@@ -1018,7 +1067,7 @@ declare function orderedList(props?: {
  * @param props.value - Current page, accepts a value or `State`. Defaults to `1`.
  * @param props.color - Base color tone for the page buttons. Defaults to `"neutral"`.
  * @param props.accentColor - Accent color tone for the active page. Defaults to `"primary"`.
- * @example { div: "", $: [pagination({ total: 10, value: 1 })] }
+ * @example { div: null, $: [pagination({ total: 10, value: 1 })] }
  */
 declare function pagination(props: {
     value?: ValueOrState<number>;
@@ -1111,7 +1160,8 @@ declare function popoverArrow(props?: {
 }): PartialElement;
 
 /**
- * Styles a preformatted text block: inherited font size, themed foreground/background,
+ * Styles a preformatted text block: inherited font size, the theme's monospace
+ * stack, themed foreground/background,
  * no border, density-scaled padding and rounded corners.
  *
  * @hostTag pre
@@ -1223,12 +1273,27 @@ declare function row(props?: {
  * and Firefox via `scrollbar-width`/`scrollbar-color`. Sets `overflow: auto`.
  * No host-tag check; apply to any block element.
  *
+ * Pass `label` when the scrollable content is NOT itself keyboard-reachable —
+ * a wide table, a code block, a diagram. Such a region can only be scrolled
+ * with a pointer, which fails WCAG 2.1.1 (axe `scrollable-region-focusable`),
+ * so `label` makes the host a named, tabbable region: `role="region"` +
+ * `aria-label` + `tabindex="0"`, the wrapper pattern GOV.UK and shadcn use
+ * around overflowing tables. Leave it off when the content already holds
+ * focusable elements (a nav list, a form) — those are reachable by Tab
+ * already, and a region tab stop in front of them is one keystroke of noise
+ * per list.
+ *
  * @param props.color - Theme color for the scrollbar thumb. Accepts a value or
  *   reactive state. Defaults to `"neutral"`.
+ * @param props.label - Accessible name for the scroll region. Setting it makes
+ *   the host a tabbable `role="region"`. Optional; a host-declared
+ *   `role`/`ariaLabel`/`tabIndex` still wins (native over patch).
  * @example { div: [...], style: { maxHeight: "300px" }, $: [scrollArea()] }
+ * @example { div: [wideTable], $: [scrollArea({ label: "Quarterly revenue" })] }
  */
 declare function scrollArea(props?: {
     color?: ValueOrState<ThemeColor>;
+    label?: string;
 }): PartialElement;
 
 /** One item inside a segmented control. */
@@ -1279,8 +1344,9 @@ declare function select(props?: {
  * A clickable select trigger box that renders the currently selected option(s) as removable
  * tags and toggles a floating popover (the dropdown content) anchored to itself. Selected
  * labels are derived from `options` matching the bound `value`; removing a tag updates the value.
- * Keyboard: Enter/Space toggle, ArrowDown opens, Escape closes, and printable characters
- * typeahead-search options (closed: selects the match; open: focuses the matching
+ * Keyboard: Enter/Space toggle, ArrowDown/ArrowUp/Home/End open the listbox and move focus to
+ * the first/last option (and move between options while open), Escape closes, and printable
+ * characters typeahead-search options (closed: selects the match; open: focuses the matching
  * `[role=option]` in the panel; a repeated character cycles matches).
  *
  * @hostTag div
@@ -1370,6 +1436,26 @@ declare function skeleton(props?: {
  * Styles small/secondary text: one step smaller font size (`data-size="decrease-1"`) with a
  * themed foreground color.
  *
+ * The tone is `shift-10`, one step ABOVE the `"text"` floor, because this text renders below
+ * the WCAG large-text threshold and so must always clear 4.5:1. Measured in Chromium on the
+ * built bundle: 6.01–7.73:1 (light) and 6.33–7.73:1 (dark) on every edge-anchored surface.
+ * Three things at the CALL SITE forfeit that guarantee, all measured in Chromium:
+ * 1. A host-declared `style.color` wins over the patch (native beats patch) — `"text"` /
+ *    `shift-9` on a `shift-1` surface is 4.23:1. Pass `color` for a different family
+ *    instead of restyling.
+ * 2. An ancestor's scoped `"& small": { color: … }` also wins: that descendant selector is
+ *    specificity (0,1,1) and this patch's own generated class is only (0,1,0). Measured
+ *    inside a correctly tone-anchored `dataTone: "shift-1"` card, with no inline style on
+ *    the `<small>` at all: `& small { color: themeColor(l, "shift-8") }` resolves to
+ *    `var(--neutral-9)` = #707070 on the card's #ededed = 4.23:1 (6.27:1 once the `color`
+ *    line is dropped). The specificity is deliberately NOT escalated here — a patch that
+ *    outranked descendant rules would leave an author no way to restyle short of
+ *    `!important`. Scope layout there (`display: block`) and leave the colour to the patch.
+ * 3. A surface tinted with a fixed `themeColor(l, "shift-N")` background and no `dataTone`:
+ *    every child still resolves against the page root, and even `shift-10` drops to 4.34:1
+ *    (shift-2 tint) and 3.67:1 (shift-3). Shift the surface with `dataTone` + `"inherit"`
+ *    instead — `@domphy/doctor`'s `tone-background-inherit` rule flags exactly this.
+ *
  * @hostTag small
  * @param props.color - Theme color tone for the text. Accepts a value or reactive state.
  *   Defaults to `"neutral"`.
@@ -1416,11 +1502,18 @@ declare function splitterPanel(): PartialElement;
  * appropriate resize cursor, and updates the context `size` state (clamped to `min`/`max`)
  * via mouse drag or keyboard: Arrow keys move by 1%, Home/End jump to min/max, hold Shift
  * for 10× step. Sets `role="separator"`, `tabindex="0"`, and `aria-value*` attributes.
- * Warns if used outside a `splitter`. Takes no props.
+ * Warns if used outside a `splitter`. Drag works with mouse, pen and touch
+ * (Pointer Events).
  *
+ * @param props.label - Accessible name for the separator (WCAG 4.1.2 — a
+ *   focusable `role="separator"` with `aria-value*` is a widget and needs a
+ *   name). Defaults to `"Resize"`. A native `ariaLabel`/`ariaLabelledby` on
+ *   the host element wins.
  * @example { div: null, $: [splitterHandle()] }
  */
-declare function splitterHandle(): PartialElement;
+declare function splitterHandle(props?: {
+    label?: string;
+}): PartialElement;
 
 /** One step entry. */
 type StepItem = {
@@ -1454,7 +1547,7 @@ declare function steps(props?: {
 }): PartialElement;
 
 /**
- * Styles strongly emphasized (bold) text: inherited font size, `font-weight: 700`, and a
+ * Styles strongly emphasized (bold) text: inherited font size, the theme's `bold` weight, and a
  * themed foreground color.
  *
  * @hostTag strong
@@ -1592,16 +1685,21 @@ declare function timelineItem(props?: {
 type ToastPosition = "top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right";
 /**
  * Renders a transient notification surface as a fixed-position overlay (portaled
- * into a corner stack), animating in on mount and out before removal. No host
+ * into a corner stack), animating in on mount and out before removal. Auto-dismisses
+ * after `duration` (Radix/Sonner semantics), paused while hovered or focused. No host
  * tag check; typically applied to a `<div>`.
  *
  * @param props.position - Corner of the screen for the toast stack. Optional, one of `"top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right"`. Defaults to `"top-center"`.
  * @param props.color - Theme color for the toast surface. Optional. Defaults to `"neutral"`.
+ * @param props.duration - Milliseconds before the toast dismisses itself (calls `onDismiss` then removes itself). Pass `Infinity` or `0` to disable. Optional. Defaults to `5000`.
+ * @param props.onDismiss - Called once, right before the toast removes itself, when `duration` elapses without the pointer/focus inside it. Optional — a caller tracking its own toast list should use this to drop the entry from state.
  * @example { div: "Saved!", $: [toast({ position: "top-right" })] }
  */
 declare function toast(props?: {
     position?: ToastPosition;
     color?: ThemeColor;
+    duration?: number;
+    onDismiss?: () => void;
 }): PartialElement;
 
 /** One item inside a toggle group. */
@@ -1677,6 +1775,8 @@ declare function toolbarSpacer(): DomphyElement;
  * @param props.onDismiss - Called when the tooltip requests close. Optional. Required to close when `open` is a read-only `Computed`/`ReadableState`.
  * @param props.placement - Floating placement relative to the trigger. Optional, accepts a value or state (`Placement`). Defaults to `"top"`.
  * @param props.content - Tooltip text content. Optional, accepts a value or state (string only). Defaults to `"Tooltip Content"`.
+ * @param props.openDelay - Hover/focus-intent delay before showing, in ms (Radix `delayDuration` parity). Optional. Defaults to 100.
+ * @param props.closeDelay - Delay before hiding after leave/blur, in ms. Optional. Defaults to 100.
  * @example { button: "Hover me", $: [tooltip({ content: "Help text" })] }
  */
 declare function tooltip(props?: {
@@ -1684,6 +1784,8 @@ declare function tooltip(props?: {
     onDismiss?: () => void;
     placement?: ValueOrState<Placement$1>;
     content?: ValueOrState<string>;
+    openDelay?: number;
+    closeDelay?: number;
 }): PartialElement;
 
 /**