@domphy/ui 0.16.0 → 0.17.0

package/dist/index.d.ts

@@ -17,6 +17,25 @@ declare function abbreviation(props?: {
     accentColor?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
+/**
+ * Container patch that groups `<details>` elements into a bordered accordion.
+ * In `type: "single"` mode (default), opening one item closes all siblings.
+ *
+ * @param props.type - `"single"` (default) or `"multiple"`. Single mode auto-closes siblings.
+ * @param props.color - Theme color tone for borders and backgrounds. Defaults to `"neutral"`.
+ * @param props.accentColor - Accent color for focus outlines on summary. Defaults to `"primary"`.
+ * @example
+ * { div: [
+ *   { details: [{ summary: "Section A" }, { p: "Content A" }], $: [details()] },
+ *   { details: [{ summary: "Section B" }, { p: "Content B" }], $: [details()] },
+ * ], $: [accordion()] }
+ */
+declare function accordion(props?: {
+    type?: "single" | "multiple";
+    color?: ValueOrState<ThemeColor>;
+    accentColor?: ValueOrState<ThemeColor>;
+}): PartialElement;
+
 /**
  * A semantic alert surface block with a colored inset bar, padding, and
  * `role="alert"`. Typically applied to a `<div>` (any block container).
@@ -58,7 +77,7 @@ declare function badge(props?: {
  * shifted tone. Apply to a `<blockquote>` element.
  *
  * @hostTag blockquote
- * @param props.color - Surface/bar color tone. Optional `ValueOrState<ThemeColor>`, default "inherit".
+ * @param props.color - Surface/bar color tone. Optional `ValueOrState<ThemeColor>`, default "neutral".
  * @example { blockquote: "Design is how it works.", $: [blockquote({ color: "primary" })] }
  */
 declare function blockquote(props?: {
@@ -198,10 +217,11 @@ declare function commandSearch(props?: {
     accentColor?: ThemeColor;
 }): PartialElement;
 /**
- * Selectable item (`role="option"`) in a command palette. Subscribes to the
- * parent `command` context's query State and hides itself when its text content
- * does not match the current query. Typically applied to a `<button>` (or any
- * clickable element) used inside a `command()`.
+ * Selectable item (`role="option"`) 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()`.
  *
  * @param props.color - Base theme color tone. Defaults to "neutral".
  * @param props.accentColor - Accent color used for the focus outline. Defaults to "primary".
@@ -296,8 +316,9 @@ declare function details(props?: {
 
 /**
  * Modal dialog patch driven by an `open` State. Calls `showModal()`/`close()`,
- * fades via opacity, locks page scroll while open, focuses the first focusable
- * child, and closes on outside (backdrop) click. Apply to a `<dialog>` element.
+ * fades via opacity, locks page scroll while open, traps Tab focus within the
+ * dialog, restores focus to the previously focused element on close, sets
+ * `aria-modal`, and closes on outside (backdrop) click. Apply to a `<dialog>`.
  *
  * @hostTag dialog
  * @param props.color - Theme color tone for the dialog surface. Defaults to "neutral".
@@ -321,19 +342,30 @@ declare function divider(props?: {
     color?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
-type Placement = "left" | "right" | "top" | "bottom";
+type PhysicalPlacement = "left" | "right" | "top" | "bottom";
+type Placement = PhysicalPlacement | "start" | "end";
 /**
  * Edge-anchored modal drawer driven by an `open` State. Slides in/out from a
- * chosen edge via a transform transition, calls `showModal()`/`close()`, locks
- * page scroll while open, and closes on backdrop click. Apply to a `<dialog>`
- * element.
+ * chosen edge via a 250 ms transform transition, calls `showModal()`/`close()`,
+ * locks page scroll while open, and closes on backdrop click. A 350 ms fallback
+ * ensures `close()` is always called even when `transitionend` doesn't fire
+ * (reduced-motion, `display:none`, detached element). Apply to a `<dialog>`.
+ *
+ * Because the patch uses the native `<dialog>` `showModal()` API, the browser
+ * traps focus inside the drawer while it is open and restores focus to the
+ * previously focused element when `close()` is called. Sets `aria-modal="true"`.
+ * Escape key closes the drawer via the animated state path (not immediate close).
+ *
+ * `"start"` and `"end"` placements resolve to left/right based on the
+ * document's `dir` attribute at mount time, enabling RTL-aware drawers:
+ * `"start"` → left (LTR) / right (RTL); `"end"` → right (LTR) / left (RTL).
  *
  * @hostTag dialog
  * @param props.color - Theme color tone for the drawer surface. Defaults to "neutral".
  * @param props.open - Open state (`ValueOrState<boolean>`); set true/false to show/hide. Defaults to false.
- * @param props.placement - Edge to anchor to, "left" | "right" | "top" | "bottom". Defaults to "right".
- * @param props.size - CSS length for the drawer's width (left/right) or height (top/bottom). Defaults to themeSpacing(80) for left/right, themeSpacing(64) for top/bottom.
- * @example { dialog: [...], $: [drawer({ open, placement: "left" })] }
+ * @param props.placement - Edge to anchor to. "left" | "right" | "top" | "bottom" | "start" | "end". Defaults to "end".
+ * @param props.size - CSS length for the drawer's width (left/right/start/end) or height (top/bottom). Defaults to themeSpacing(80) for left/right, themeSpacing(64) for top/bottom.
+ * @example { dialog: [...], $: [drawer({ open, placement: "start" })] }
  */
 declare function drawer(props?: {
     color?: ThemeColor;
@@ -353,6 +385,56 @@ declare function emphasis(props?: {
     color?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
+/**
+ * Styles a container as an empty-state placeholder: centered flex column with
+ * muted coloring and comfortable padding. Provide the icon, title, and
+ * description as child elements.
+ *
+ * @param props.color - Theme color tone for the muted text/icon. Defaults to `"neutral"`.
+ * @example
+ * { div: [
+ *   { span: "📭" },
+ *   { p: "No items yet", $: [paragraph()] },
+ *   { span: "Add your first item to get started", $: [small()] },
+ * ], $: [empty()] }
+ */
+declare function empty(props?: {
+    color?: ValueOrState<ThemeColor>;
+}): PartialElement;
+
+/**
+ * Catches errors thrown inside reactive child expressions and renders a
+ * fallback element instead of crashing the whole tree. Apply to any container.
+ *
+ * Only errors in *reactive* children (functions returning element arrays) are
+ * caught. Errors during static construction propagate normally — those are
+ * programming errors, not runtime data errors.
+ *
+ * @hostTag any
+ * @param props.fallback - Fallback element or factory `(error, reset) => element`. Defaults to a plain error message div.
+ * @param props.onError - Optional callback for logging/telemetry.
+ * @example { div: (l) => renderUserContent(l), $: [errorBoundary({ fallback: { p: "Something went wrong." } })] }
+ */
+declare function errorBoundary(props?: {
+    fallback?: DomphyElement | ((error: unknown, reset: () => void) => DomphyElement);
+    onError?: (error: unknown) => void;
+}): PartialElement;
+
+/**
+ * Floating Action Button — a circular elevated button typically used for the
+ * primary action on a screen. Apply to a `<button>` element.
+ *
+ * @hostTag button
+ * @param props.color - Button color tone. Optional `ValueOrState<ThemeColor>`, defaults to `"primary"`.
+ * @param props.size - Button size preset. Optional `"small" | "medium" | "large"`, defaults to `"medium"`.
+ * @example { button: "+", $: [fab()] }
+ * @example { button: "+", $: [fab({ size: "small", color: "neutral" })] }
+ */
+declare function fab(props?: {
+    color?: ValueOrState<ThemeColor>;
+    size?: "small" | "medium" | "large";
+}): PartialElement;
+
 /**
  * Lays out a figure as a column with block-level media (img/svg/video/canvas)
  * and a themed `<figcaption>`. Apply to a `<figure>` element.
@@ -635,6 +717,42 @@ declare function link(props?: {
     accentColor?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
+/**
+ * Styles a navigation/display list container. Sets `list-style: none` and
+ * zero padding; pairs with `listItem` and `listItemButton`. Apply to `<ul>`.
+ *
+ * @hostTag ul
+ * @param props.color - Surface color tone. Optional `ThemeColor`, defaults to `"neutral"`.
+ * @example { ul: [...], $: [list()] }
+ */
+declare function list(props?: {
+    color?: ThemeColor;
+}): PartialElement;
+/**
+ * A non-interactive list row. Typically wraps an icon + text. Apply to `<li>`.
+ *
+ * @hostTag li
+ * @param props.dense - Reduce vertical padding. Optional `boolean`, defaults to `false`.
+ * @example { li: "Item", $: [listItem()] }
+ */
+declare function listItem(props?: {
+    dense?: boolean;
+}): PartialElement;
+/**
+ * An interactive (clickable) list row with hover/focus-visible states. Apply
+ * to `<button>` or `<a>` inside an `<li>`.
+ *
+ * @param props.color - Color tone. Optional `ValueOrState<ThemeColor>`, defaults to `"neutral"`.
+ * @param props.accentColor - Focus/active accent. Optional `ThemeColor`, defaults to `"primary"`.
+ * @param props.dense - Reduce vertical padding. Optional `boolean`, defaults to `false`.
+ * @example { button: "Action", $: [listItemButton()] }
+ */
+declare function listItemButton(props?: {
+    color?: ValueOrState<ThemeColor>;
+    accentColor?: ThemeColor;
+    dense?: boolean;
+}): PartialElement;
+
 /**
  * Themed highlight primitive: gives marked/highlighted inline text a tinted
  * background, rounded corners and padding. Apply to a `<mark>` element.
@@ -791,7 +909,7 @@ declare function paragraph(props?: {
  * @example { button: "Open", $: [popover({ openOn: "click", content: { div: "Hi" } })] }
  */
 declare function popover(props: {
-    openOn: "click" | "hover";
+    openOn?: "click" | "hover";
     open?: ValueOrState<boolean>;
     placement?: ValueOrState<Placement$1>;
     content: DomphyElement;
@@ -850,6 +968,54 @@ declare function progress(props?: {
     accentColor?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
+/**
+ * Interactive star rating applied to a container `<div>`. Manages its own star
+ * children: click to set, Arrow keys to adjust, hover to preview. In `readOnly`
+ * mode stars are non-interactive. Apply to a `<div>` element.
+ *
+ * @hostTag div
+ * @param props.value - Current rating (0 – max). `ValueOrState<number>`, defaults to `0`.
+ * @param props.max - Total number of stars. Optional `number`, defaults to `5`.
+ * @param props.onChange - Called with the new value when the user picks a star.
+ * @param props.readOnly - Disable interaction. Optional `boolean`, defaults to `false`.
+ * @param props.color - Star color tone. Optional `ThemeColor`, defaults to `"warning"`.
+ * @example { div: null, $: [rating({ value: ratingState, onChange: (v) => ratingState.set(v) })] }
+ */
+declare function rating(props?: {
+    value?: ValueOrState<number>;
+    max?: number;
+    onChange?: (value: number) => void;
+    readOnly?: boolean;
+    color?: ThemeColor;
+}): PartialElement;
+
+/**
+ * Container patch that establishes a `segmented` context for single-select navigation.
+ * Style: inline pill-shaped control with muted background. Use with `segmentedItem` patches on child `<button>` elements.
+ *
+ * @param props.value - Initially selected item key. Accepts a value or state. Defaults to `""`.
+ * @param props.color - Theme color for the control background. Defaults to `"neutral"`.
+ * @example { div: null, $: [segmented({ value: "month" })] }
+ */
+declare function segmented(props?: {
+    value?: ValueOrState<string>;
+    color?: ThemeColor;
+}): PartialElement;
+
+/**
+ * Styles and wires a single option inside a `segmented` control on the host `<button>`.
+ * Sets `aria-checked` and handles click-to-select against the parent `segmented` context.
+ *
+ * @hostTag button
+ * @param props.color - Theme color for resting state. Defaults to `"neutral"`.
+ * @param props.accentColor - Theme color for selected state. Defaults to `"primary"`.
+ * @example { button: "Month", $: [segmentedItem()] }
+ */
+declare function segmentedItem(props?: {
+    color?: ValueOrState<ThemeColor>;
+    accentColor?: ValueOrState<ThemeColor>;
+}): PartialElement;
+
 /**
  * Styles a native `<select>` control: removes the default appearance, applies themed
  * colors, outline, density-scaled padding/radius, a custom chevron background icon, and
@@ -1004,13 +1170,41 @@ declare function splitter(props?: {
 declare function splitterPanel(): PartialElement;
 /**
  * The draggable divider inside a `splitter`. Reads the `splitter` context, shows the
- * appropriate resize cursor, and on mouse drag updates the context `size` state (clamped to
- * `min`/`max`). Warns if used outside a `splitter`. Takes no props.
+ * 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.
  *
  * @example { div: null, $: [splitterHandle()] }
  */
 declare function splitterHandle(): PartialElement;
 
+/**
+ * Styles a single step inside a `steps` container. Sets `data-status`
+ * (`"pending"` | `"active"` | `"done"`) and `aria-current="step"` on the host element
+ * based on the parent `steps` context. The element's content is the step label.
+ *
+ * @example { li: "Shipping", $: [stepItem()] }
+ */
+declare function stepItem(): PartialElement;
+
+/**
+ * Container patch for a step-progress indicator. Establishes `steps` context
+ * with a reactive `current` index. Use with `stepItem` patches on child elements.
+ *
+ * @param props.current - Zero-based index of the active step. Accepts a value or state. Defaults to `0`.
+ * @param props.direction - `"horizontal"` (default) or `"vertical"` layout.
+ * @param props.color - Theme color for pending/track elements. Defaults to `"neutral"`.
+ * @param props.accentColor - Theme color for active/completed elements. Defaults to `"primary"`.
+ * @example { ol: null, $: [steps({ current: 1 })] }
+ */
+declare function steps(props?: {
+    current?: ValueOrState<number>;
+    direction?: "horizontal" | "vertical";
+    color?: ThemeColor;
+    accentColor?: ThemeColor;
+}): PartialElement;
+
 /**
  * Styles strongly emphasized (bold) text: inherited font size, `font-weight: 700`, and a
  * themed foreground color.
@@ -1127,6 +1321,30 @@ declare function textarea(props?: {
     autoResize?: boolean;
 }): PartialElement;
 
+/**
+ * Container for a vertical timeline. Sets list reset styles. Apply to `<ol>` or `<ul>`.
+ *
+ * @example { ol: [...], $: [timeline()] }
+ */
+declare function timeline(): PartialElement;
+/**
+ * A single event row in a `timeline`. Uses a 2-column grid: the left column holds
+ * a dot (`::before`) and optional connector line (`::after`); the right column holds
+ * the user's content. Apply to `<li>`.
+ *
+ * @param props.active - Full-opacity dot (accent color). `ValueOrState<boolean>`, defaults to `false`.
+ * @param props.last - Suppress the vertical connector below this item. `boolean`, defaults to `false`.
+ * @param props.color - Dot/connector color tone. `ThemeColor`, defaults to `"neutral"`.
+ * @param props.accentColor - Active dot color tone. `ThemeColor`, defaults to `"primary"`.
+ * @example { li: [{ b: "2024" }, { p: "Event" }], $: [timelineItem({ active: true })] }
+ */
+declare function timelineItem(props?: {
+    active?: ValueOrState<boolean>;
+    last?: boolean;
+    color?: ThemeColor;
+    accentColor?: ThemeColor;
+}): PartialElement;
+
 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
@@ -1175,6 +1393,25 @@ declare function toggleGroup(props?: {
     color?: ThemeColor;
 }): PartialElement;
 
+/**
+ * A horizontal flex row with vertically centered items. Useful for headers,
+ * toolbars, navigation bars, and action strips.
+ *
+ * @param props.gap - Spacing multiplier for gap between items (default 4 = 1em).
+ * @example { header: [...], $: [toolbar()] }
+ * @example { nav: [...], $: [toolbar({ gap: 3 })] }
+ */
+declare function toolbar(props?: {
+    gap?: number;
+}): PartialElement;
+/**
+ * A flex spacer that expands to fill available space in a toolbar, pushing
+ * subsequent items to the far end.
+ *
+ * @example { header: [logo, toolbarSpacer(), nav, actions], $: [toolbar()] }
+ */
+declare function toolbarSpacer(): DomphyElement;
+
 /**
  * Attaches a floating tooltip to the host element, shown on hover/focus and
  * hidden on leave/blur/Escape. Returns the anchor (trigger) partial; the tooltip
@@ -1218,4 +1455,4 @@ declare function unorderedList(props?: {
     color?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
-export { type DatePickerProps, type DatePickerValue, type MotionKeyframe, type MotionProps, abbreviation, alert, avatar, badge, blockquote, breadcrumb, breadcrumbEllipsis, button, buttonSwitch, card, code, combobox, command, commandItem, commandSearch, datePicker, descriptionList, details, dialog, divider, drawer, emphasis, figure, formGroup, heading, horizontalRule, icon, image, inputCheckbox, inputColor, inputDateTime, inputFile, inputNumber, inputOTP, inputRadio, inputRange, inputSearch, inputSwitch, inputText, keyboard, label, link, mark, menu, menuItem, motion, orderedList, pagination, paragraph, popover, popoverArrow, preformated, progress, select, selectBox, selectItem, selectList, skeleton, small, spinner, splitter, splitterHandle, splitterPanel, strong, subscript, superscript, tab, tabPanel, table, tabs, tag, textarea, toast, toggle, toggleGroup, tooltip, transitionGroup, unorderedList };
+export { type DatePickerProps, type DatePickerValue, type MotionKeyframe, type MotionProps, abbreviation, accordion, alert, avatar, badge, blockquote, breadcrumb, breadcrumbEllipsis, button, buttonSwitch, card, code, combobox, command, commandItem, commandSearch, datePicker, descriptionList, details, dialog, divider, drawer, emphasis, empty, errorBoundary, fab, figure, formGroup, heading, horizontalRule, icon, image, inputCheckbox, inputColor, inputDateTime, inputFile, inputNumber, inputOTP, inputRadio, inputRange, inputSearch, inputSwitch, inputText, keyboard, label, link, list, listItem, listItemButton, mark, menu, menuItem, motion, orderedList, pagination, paragraph, popover, popoverArrow, preformated, progress, rating, segmented, segmentedItem, select, selectBox, selectItem, selectList, skeleton, small, spinner, splitter, splitterHandle, splitterPanel, stepItem, steps, strong, subscript, superscript, tab, tabPanel, table, tabs, tag, textarea, timeline, timelineItem, toast, toggle, toggleGroup, toolbar, toolbarSpacer, tooltip, transitionGroup, unorderedList };