@domphy/ui 0.13.0 → 0.15.0

package/dist/index.d.cts

@@ -3,69 +3,164 @@ import { ThemeColor } from '@domphy/theme';
 import { Placement as Placement$1 } from '@domphy/floating';
 export { Placement } from '@domphy/floating';
 
+/**
+ * Styles an abbreviation/acronym with a dotted underline and a "help" cursor,
+ * shifting to the accent color on hover. Apply to an `<abbr>` element.
+ *
+ * @hostTag abbr
+ * @param props.color - Base text/decoration color tone. Optional `ValueOrState<ThemeColor>`, default "neutral".
+ * @param props.accentColor - Hover color tone. Optional `ValueOrState<ThemeColor>`, default "primary".
+ * @example { abbr: "HTML", title: "HyperText Markup Language", $: [abbreviation({ accentColor: "primary" })] }
+ */
 declare function abbreviation(props?: {
     color?: ValueOrState<ThemeColor>;
     accentColor?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
-declare function card(props?: {
+/**
+ * A semantic alert surface block with a colored inset bar, padding, and
+ * `role="alert"`. Typically applied to a `<div>` (any block container).
+ *
+ * @param props.color - Surface/accent color tone. Optional `ValueOrState<ThemeColor>`, default "primary".
+ * @example { div: "Saved successfully", $: [alert({ color: "success" })] }
+ */
+declare function alert(props?: {
     color?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
-declare function splitter(props?: {
-    direction?: "horizontal" | "vertical";
-    defaultSize?: number;
-    min?: number;
-    max?: number;
+/**
+ * A circular avatar container that centers initials/text and cover-fits any
+ * child `<img>`. Typically applied to an inline-flex container such as a `<span>`.
+ *
+ * @param props.color - Background/foreground color tone. Optional `ValueOrState<ThemeColor>`, default "primary".
+ * @example { span: "JD", $: [avatar({ color: "primary" })] }
+ */
+declare function avatar(props?: {
+    color?: ValueOrState<ThemeColor>;
 }): PartialElement;
-declare function splitterPanel(): PartialElement;
-declare function splitterHandle(): PartialElement;
 
-declare function command(): PartialElement;
-declare function commandSearch(props?: {
-    color?: ThemeColor;
-    accentColor?: ThemeColor;
-}): PartialElement;
-declare function commandItem(props?: {
-    color?: ThemeColor;
-    accentColor?: ThemeColor;
+/**
+ * Renders a small count/label bubble pinned to the top-right corner of its host
+ * (via a `::after` pseudo-element). Typically applied to an inline container such
+ * as a `<span>` wrapping an icon or element.
+ *
+ * @param props.color - Badge color tone. Optional `ValueOrState<ThemeColor>`, default "danger".
+ * @param props.label - Text/number shown in the badge. Optional `ValueOrState<string | number>`, default 999.
+ * @example { span: "🔔", $: [badge({ label: 3, color: "danger" })] }
+ */
+declare function badge(props?: {
+    color?: ValueOrState<ThemeColor>;
+    label?: ValueOrState<string | number>;
 }): PartialElement;
 
-declare function toggle(props?: {
+/**
+ * Styles a quotation block with a colored inset side bar, padded surface, and
+ * shifted tone. Apply to a `<blockquote>` element.
+ *
+ * @hostTag blockquote
+ * @param props.color - Surface/bar color tone. Optional `ValueOrState<ThemeColor>`, default "inherit".
+ * @example { blockquote: "Design is how it works.", $: [blockquote({ color: "primary" })] }
+ */
+declare function blockquote(props?: {
     color?: ValueOrState<ThemeColor>;
-    accentColor?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
-declare function toggleGroup(props?: {
-    value?: ValueOrState<string | string[]>;
-    multiple?: boolean;
-    color?: ThemeColor;
+/**
+ * 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.
+ *
+ * @hostTag nav
+ * @param props.color - Color tone for links/separators. Optional `ValueOrState<ThemeColor>`, default "neutral".
+ * @param props.separator - String inserted between items via `::after`. Optional `string`, default "/".
+ * @example { nav: null, $: [breadcrumb({ separator: "›" })] }
+ */
+declare function breadcrumb(props?: {
+    color?: ValueOrState<ThemeColor>;
+    separator?: string;
 }): PartialElement;
 
-declare function inputOTP(): PartialElement;
-
-declare function alert(props?: {
+/**
+ * An ellipsis trigger button for collapsed breadcrumb items, with hover and
+ * focus-visible states. Apply to a `<button>` element.
+ *
+ * @hostTag button
+ * @param props.color - Color tone for the trigger. Optional `ValueOrState<ThemeColor>`, default "neutral".
+ * @example { button: "…", $: [breadcrumbEllipsis({ color: "neutral" })] }
+ */
+declare function breadcrumbEllipsis(props?: {
     color?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
-declare function avatar(props?: {
+/**
+ * A themed button control with density-aware padding/radius and hover, focus-visible,
+ * `[disabled]`, and `[aria-busy=true]` states. Apply to a `<button>` element.
+ *
+ * @hostTag button
+ * @param props.color - Button color tone. Optional `ValueOrState<ThemeColor>`, default "primary".
+ * @example { button: "Save", $: [button({ color: "primary" })] }
+ */
+declare function button(props?: {
     color?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
-declare function badge(props?: {
+/**
+ * A pill-shaped toggle switch with `role="switch"`; clicking flips the bound
+ * `checked` state and slides the thumb. Apply to a `<button>` element.
+ *
+ * @hostTag button
+ * @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 })] }
+ */
+declare function buttonSwitch(props?: {
+    checked?: ValueOrState<boolean>;
+    accentColor?: ValueOrState<ThemeColor>;
     color?: ValueOrState<ThemeColor>;
-    label?: ValueOrState<string | number>;
 }): PartialElement;
 
-declare function breadcrumb(props?: {
+/**
+ * A grid-based card surface that auto-places known child elements into named
+ * regions: `<img>` (image), headings (title), `<p>` (description), `<aside>`
+ * (aside), `<div>` (content), and `<footer>` (footer). Typically applied to a
+ * `<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" })] }
+ */
+declare function card(props?: {
     color?: ValueOrState<ThemeColor>;
-    separator?: string;
 }): PartialElement;
 
-declare function breadcrumbEllipsis(props?: {
+/**
+ * Styles an inline code snippet 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".
+ * @example { code: "npm install", $: [code({ color: "neutral" })] }
+ */
+declare function code(props?: {
     color?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
+/**
+ * A combobox/multi-select control: renders selected options as removable tags
+ * plus an input, and shows a floating popover (`content`) anchored to the host.
+ * Apply to a `<div>` element.
+ *
+ * @hostTag div
+ * @param props.multiple - Allow selecting multiple values (popover stays open on click). Optional `boolean`, default false.
+ * @param props.value - Selected value(s). Optional `ValueOrState<Array<number | string | null | undefined> | number | string | null | undefined>`, no default.
+ * @param props.options - Available `{ label, value }` options used to render selected tags. Optional `Array<{ label: string; value: string }>`, default `[]`.
+ * @param props.placement - Floating popover placement. Optional `ValueOrState<Placement>`, default "bottom".
+ * @param props.content - The floating popover content element. Required `DomphyElement`.
+ * @param props.color - Color tone for the control. Optional `ThemeColor`, default "neutral".
+ * @param props.open - Whether the popover is open. Optional `ValueOrState<boolean>`, default false.
+ * @param props.input - Custom input element; when omitted a default `<input>` is created. Optional `DomphyElement`.
+ * @example { div: null, $: [combobox({ options: [{ label: "A", value: "a" }], content: { div: null } })] }
+ */
 declare function combobox(props: {
     multiple?: boolean;
     value?: ValueOrState<Array<number | string | null | undefined> | number | string | null | undefined>;
@@ -80,173 +175,715 @@ declare function combobox(props: {
     input?: DomphyElement;
 }): PartialElement;
 
-declare function popoverArrow(props?: {
-    placement?: ValueOrState<Placement$1>;
-    sideOffset?: string;
+/**
+ * Command-palette container patch. Sets up a vertical flex column and provides a
+ * shared `command` context (a query State) consumed by `commandSearch` and
+ * `commandItem` descendants to filter the list. Typically applied to a `<div>`.
+ *
+ * @example { div: [...], $: [command()] }
+ */
+declare function command(): PartialElement;
+/**
+ * Search input for a command palette. Wires the input's value into the parent
+ * `command` context's query State so descendant `commandItem`s filter live.
+ * Apply to an `<input>` element used inside a `command()`.
+ *
+ * @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" })] }
+ */
+declare function commandSearch(props?: {
     color?: ThemeColor;
-    bordered?: boolean;
-}): PartialElement;
-
-declare function blockquote(props?: {
-    color?: ValueOrState<ThemeColor>;
+    accentColor?: ThemeColor;
 }): PartialElement;
-
-declare function button(props?: {
-    color?: ValueOrState<ThemeColor>;
+/**
+ * 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()`.
+ *
+ * @param props.color - Base theme color tone. Defaults to "neutral".
+ * @param props.accentColor - Accent color used for the focus outline. Defaults to "primary".
+ * @example { button: "Open file", $: [commandItem({ color: "neutral" })] }
+ */
+declare function commandItem(props?: {
+    color?: ThemeColor;
+    accentColor?: ThemeColor;
 }): PartialElement;
 
-declare function inputCheckbox(props?: {
-    color?: ValueOrState<ThemeColor>;
+/** A single date selection, or a `[start, end]` tuple in range mode. */
+type DatePickerValue = Date | null | [Date | null, Date | null];
+interface DatePickerProps {
+    /** Controlled value: a `Date` in single mode, a `[start, end]` tuple in range mode. */
+    value?: ValueOrState<DatePickerValue>;
+    /** Selection mode. */
+    mode?: "single" | "range";
+    /** Also pick hour + minute. The chosen time applies to the selected date(s). */
+    time?: boolean;
+    /** Earliest selectable day (inclusive). */
+    min?: Date;
+    /** Latest selectable day (inclusive). */
+    max?: Date;
+    /** Disable arbitrary days. */
+    disabledDate?: (date: Date) => boolean;
+    /** BCP-47 locale for month/weekday names, first-day-of-week, and formatting. */
+    locale?: string;
+    /** Override the first day of the week (0 = Sunday … 6 = Saturday). */
+    weekStartsOn?: number;
+    /** Override the input display string. */
+    format?: (value: DatePickerValue) => string;
+    /** Called whenever the selection changes. */
+    onChange?: (value: DatePickerValue) => void;
+    /** Accent color for the selected/active days. */
     accentColor?: ValueOrState<ThemeColor>;
-}): PartialElement;
+    /** Popover placement relative to the input. */
+    placement?: ValueOrState<Placement$1>;
+}
+/**
+ * A native, themeable date picker patch for an `<input>`. Opens a calendar
+ * popover (rendered with Domphy elements, positioned via `@domphy/floating`)
+ * supporting single/range selection, optional time, min/max + disabled days,
+ * localized names, and keyboard navigation. The input is read-only and shows the
+ * formatted selection; compose with `inputText()` for the input's look.
+ *
+ * @hostTag input
+ * @param props.value - Controlled value (`ValueOrState<DatePickerValue>`): a `Date`/`null` in single mode, a `[start, end]` tuple in range mode.
+ * @param props.mode - Selection mode, "single" | "range". Defaults to "single".
+ * @param props.time - When true, also pick hour + minute (applied to the selected date(s)). Defaults to false.
+ * @param props.min - Earliest selectable day (inclusive), a `Date`.
+ * @param props.max - Latest selectable day (inclusive), a `Date`.
+ * @param props.disabledDate - Predicate `(date: Date) => boolean` to disable arbitrary days.
+ * @param props.locale - BCP-47 locale for names/first-day-of-week/formatting. Defaults to `navigator.language` (or "en-US" in non-browser).
+ * @param props.weekStartsOn - Override first day of week (0 = Sunday … 6 = Saturday). Defaults to the locale's first day.
+ * @param props.format - Override the input display string, `(value: DatePickerValue) => string`.
+ * @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" })] }
+ */
+declare function datePicker(props?: DatePickerProps): PartialElement;
 
-declare function code(props?: {
+/**
+ * Styles a description list as a two-column grid (terms in the first column,
+ * descriptions in the second), theming the nested `<dt>`/`<dd>` elements.
+ * Apply to a `<dl>` element.
+ *
+ * @hostTag dl
+ * @param props.color - Theme color tone (`ValueOrState<ThemeColor>`) for the term/description text. Defaults to "neutral".
+ * @example { dl: [{ dt: "Name" }, { dd: "Domphy" }], $: [descriptionList()] }
+ */
+declare function descriptionList(props?: {
     color?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
+/**
+ * Styles a native disclosure widget: a themed `<summary>` header with an
+ * animated rotating chevron and an expand/collapse transition on the body
+ * content. Apply to a `<details>` element.
+ *
+ * @hostTag details
+ * @param props.color - Theme color tone (`ValueOrState<ThemeColor>`) for the body/summary. Defaults to "neutral".
+ * @param props.accentColor - Accent color (`ValueOrState<ThemeColor>`) for the summary's focus outline. Defaults to "primary".
+ * @param props.duration - Open/close transition duration in milliseconds. Defaults to 240.
+ * @example { details: [{ summary: "More" }, { div: "Body" }], $: [details()] }
+ */
 declare function details(props?: {
     color?: ValueOrState<ThemeColor>;
     accentColor?: ValueOrState<ThemeColor>;
     duration?: number;
 }): PartialElement;
 
-declare function descriptionList(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.
+ *
+ * @hostTag dialog
+ * @param props.color - Theme color tone for the dialog surface. Defaults to "neutral".
+ * @param props.open - Open state (`ValueOrState<boolean>`); set it to true/false to show/hide. Defaults to false.
+ * @example { dialog: [...], $: [dialog({ open })] }
+ */
+declare function dialog(props?: {
+    color?: ThemeColor;
+    open?: ValueOrState<boolean>;
+}): PartialElement;
+
+/**
+ * A horizontal separator (`role="separator"`) with a line on each side of its
+ * content, suitable for labelled dividers ("or"). Apply to a `<div>` element.
+ *
+ * @hostTag div
+ * @param props.color - Theme color tone (`ValueOrState<ThemeColor>`) for the label text and rules. Defaults to "neutral".
+ * @example { div: "or", $: [divider()] }
+ */
+declare function divider(props?: {
     color?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
-declare function dialog(props?: {
+type Placement = "left" | "right" | "top" | "bottom";
+/**
+ * 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.
+ *
+ * @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" })] }
+ */
+declare function drawer(props?: {
     color?: ThemeColor;
     open?: ValueOrState<boolean>;
+    placement?: Placement;
+    size?: string;
 }): PartialElement;
 
+/**
+ * Italic emphasized inline text. Apply to an `<em>` element.
+ *
+ * @hostTag em
+ * @param props.color - Theme color tone (`ValueOrState<ThemeColor>`) for the text. Defaults to "neutral".
+ * @example { em: "important", $: [emphasis()] }
+ */
 declare function emphasis(props?: {
     color?: ValueOrState<ThemeColor>;
 }): 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.
+ *
+ * @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()] }
+ */
 declare function figure(props?: {
     color?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
+/**
+ * Layout patch for a group of form fields. Arranges a `<legend>`, `<label>`s,
+ * controls, and helper `<p>`s in a grid — labels beside controls (horizontal)
+ * or stacked above them (vertical). Apply to a `<fieldset>` element.
+ *
+ * @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" })] }
+ */
 declare function formGroup(props?: {
     color?: ValueOrState<ThemeColor>;
     layout?: "horizontal" | "vertical";
 }): PartialElement;
 
+/**
+ * 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
+ * @param props.color - Theme color tone (`ValueOrState<ThemeColor>`) for the heading text. Defaults to "neutral".
+ * @example { h2: "Section title", $: [heading()] }
+ */
 declare function heading(props?: {
     color?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
+/**
+ * A thematic break rendered as a thin 1px themed line with vertical margin.
+ * Apply to an `<hr>` element.
+ *
+ * @hostTag hr
+ * @param props.color - Theme color tone (`ValueOrState<ThemeColor>`) for the rule. Defaults to "neutral".
+ * @example { hr: "", $: [horizontalRule()] }
+ */
 declare function horizontalRule(props?: {
     color?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
+/**
+ * Styles an inline icon container: square box that centers its content and
+ * applies the themed icon color. Apply to a `<span>` element.
+ *
+ * @hostTag span
+ * @param props.color - Optional theme color tone for the icon (`ValueOrState<ThemeColor>`). Defaults to `"neutral"`.
+ * @example { span: null, $: [icon()] }
+ */
+declare function icon(props?: {
+    color?: ValueOrState<ThemeColor>;
+}): PartialElement;
+
+/**
+ * Styles a responsive image: full-width, cover-fit, rounded corners with a
+ * themed placeholder background. Apply to an `<img>` element.
+ *
+ * @hostTag img
+ * @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()] }
+ */
 declare function image(props?: {
     color?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
-declare function icon(props?: {
+/**
+ * Styles a custom checkbox with themed box, check mark, indeterminate state,
+ * hover, focus and disabled styling. Apply to an `<input>` element of
+ * type `checkbox` (the patch sets `type: "checkbox"`).
+ *
+ * @hostTag input
+ * @param props.color - Optional theme color tone for the box/border (`ValueOrState<ThemeColor>`). Defaults to `"neutral"`.
+ * @param props.accentColor - Optional theme color tone for the checked/indeterminate fill and focus ring (`ValueOrState<ThemeColor>`). Defaults to `"primary"`.
+ * @example { input: null, type: "checkbox", $: [inputCheckbox()] }
+ */
+declare function inputCheckbox(props?: {
     color?: ValueOrState<ThemeColor>;
+    accentColor?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
+/**
+ * Styles a native color picker swatch with themed padding, rounded swatch and
+ * disabled styling. Apply to an `<input>` element of type `color` (the patch
+ * sets `type: "color"`).
+ *
+ * @hostTag input
+ * @param props.color - Optional theme color tone used for the disabled state (`ValueOrState<ThemeColor>`). Defaults to `"neutral"`.
+ * @param props.accentColor - Optional theme color tone (`ValueOrState<ThemeColor>`). Defaults to `"primary"`.
+ * @example { input: null, type: "color", $: [inputColor()] }
+ */
 declare function inputColor(props?: {
     color?: ValueOrState<ThemeColor>;
     accentColor?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
 type InputDateTimeMode = "date" | "time" | "week" | "month" | "datetime-local";
+/**
+ * Styles a native date/time input with themed border, padding, hover, focus,
+ * invalid and disabled states. The `mode` selects the input `type`. Apply to
+ * an `<input>` element (the patch sets `type` to the chosen `mode`).
+ *
+ * @hostTag input
+ * @param props.mode - Input mode selecting the host `type`: `"date" | "time" | "week" | "month" | "datetime-local"`. Defaults to `"datetime-local"`.
+ * @param props.color - Optional theme color tone for text/border (`ValueOrState<ThemeColor>`). Defaults to `"neutral"`.
+ * @param props.accentColor - Optional theme color tone for the hover/focus ring (`ValueOrState<ThemeColor>`). Defaults to `"primary"`.
+ * @example { input: null, type: "datetime-local", $: [inputDateTime()] }
+ */
 declare function inputDateTime(props?: {
     mode?: InputDateTimeMode;
     color?: ValueOrState<ThemeColor>;
     accentColor?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
+/**
+ * Styles a native file input with a themed upload button, border, hover, focus
+ * and disabled states. Apply to an `<input>` element of type `file` (the patch
+ * sets `type: "file"`).
+ *
+ * @hostTag input
+ * @param props.color - Optional theme color tone for text/border and the upload button (`ValueOrState<ThemeColor>`). Defaults to `"neutral"`.
+ * @param props.accentColor - Optional theme color tone for the hover/focus ring (`ValueOrState<ThemeColor>`). Defaults to `"primary"`.
+ * @example { input: null, type: "file", $: [inputFile()] }
+ */
 declare function inputFile(props?: {
     color?: ValueOrState<ThemeColor>;
     accentColor?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
-declare function inputSearch(props?: {
+/**
+ * Styles a native number input with themed border, padding, visible spin
+ * buttons, hover, focus and disabled states. Apply to an `<input>` element of
+ * type `number` (the patch sets `type: "number"`).
+ *
+ * @hostTag input
+ * @param props.color - Optional theme color tone for text/border (`ValueOrState<ThemeColor>`). Defaults to `"neutral"`.
+ * @param props.accentColor - Optional theme color tone for the hover/focus ring (`ValueOrState<ThemeColor>`). Defaults to `"primary"`.
+ * @example { input: null, type: "number", $: [inputNumber()] }
+ */
+declare function inputNumber(props?: {
     color?: ValueOrState<ThemeColor>;
     accentColor?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
-declare function inputText(props?: {
+/**
+ * Lays out a one-time-password container as a horizontal row of inputs and
+ * wires keyboard navigation: auto-advance on input, backspace/arrow movement,
+ * and paste distribution across the child inputs. Apply to a container element
+ * (e.g. `<div>`) whose direct children are the OTP `<input>` boxes. Takes no
+ * props.
+ *
+ * @example { div: null, $: [inputOTP()], children: [{ input: null }, { input: null }] }
+ */
+declare function inputOTP(): PartialElement;
+
+/**
+ * Styles a custom radio button with a themed circular box, checked dot, hover,
+ * focus and disabled states. Apply to an `<input>` element of type `radio`
+ * (the patch sets `type: "radio"`).
+ *
+ * @hostTag input
+ * @param props.color - Optional theme color tone for the box/border (`ValueOrState<ThemeColor>`). Defaults to `"neutral"`.
+ * @param props.accentColor - Optional theme color tone for the checked dot and focus ring (`ValueOrState<ThemeColor>`). Defaults to `"primary"`.
+ * @example { input: null, type: "radio", $: [inputRadio()] }
+ */
+declare function inputRadio(props?: {
     color?: ValueOrState<ThemeColor>;
     accentColor?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
+/**
+ * Styles a range slider with a themed track and thumb, hover, focus and
+ * disabled states. Apply to an `<input>` element of type `range` (the patch
+ * sets `type: "range"`).
+ *
+ * @hostTag input
+ * @param props.color - Optional theme color tone for the slider track (`ValueOrState<ThemeColor>`). Defaults to `"neutral"`.
+ * @param props.accentColor - Optional theme color tone for the thumb and focus ring (`ValueOrState<ThemeColor>`). Defaults to `"primary"`.
+ * @example { input: null, type: "range", $: [inputRange()] }
+ */
 declare function inputRange(props?: {
     color?: ValueOrState<ThemeColor>;
     accentColor?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
-declare function inputNumber(props?: {
+/**
+ * Styles a search input with themed border, padding, placeholder color, native
+ * search decorations, hover, focus and disabled states. Apply to an `<input>`
+ * element of type `search` (the patch sets `type: "search"`).
+ *
+ * @hostTag input
+ * @param props.color - Optional theme color tone for text/border/placeholder (`ValueOrState<ThemeColor>`). Defaults to `"neutral"`.
+ * @param props.accentColor - Optional theme color tone for the hover/focus ring (`ValueOrState<ThemeColor>`). Defaults to `"primary"`.
+ * @example { input: null, type: "search", $: [inputSearch()] }
+ */
+declare function inputSearch(props?: {
+    color?: ValueOrState<ThemeColor>;
+    accentColor?: ValueOrState<ThemeColor>;
+}): PartialElement;
+
+/**
+ * Styles a checkbox as a toggle switch: themed track and sliding knob that
+ * animates and recolors on checked, plus a disabled state. Apply to an
+ * `<input>` element of type `checkbox` (the patch sets `type: "checkbox"`).
+ *
+ * @hostTag input
+ * @param props.accentColor - Optional theme color tone for the checked track (`ValueOrState<ThemeColor>`). Defaults to `"primary"`.
+ * @example { input: null, type: "checkbox", $: [inputSwitch()] }
+ */
+declare function inputSwitch(props?: {
+    accentColor?: ValueOrState<ThemeColor>;
+}): PartialElement;
+
+/**
+ * Themed single-line text input primitive. Sets `type="text"` and styles the
+ * field with themed border, focus ring, placeholder, disabled and validation
+ * (`data-status`) states. Apply to an `<input>` element.
+ *
+ * @hostTag input
+ * @param props - Optional configuration.
+ * @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()] }
+ */
+declare function inputText(props?: {
     color?: ValueOrState<ThemeColor>;
     accentColor?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
+/**
+ * Renders keyboard-key styling (themed background, border and padding) for a
+ * keystroke hint. Apply to a `<kbd>` element.
+ *
+ * @hostTag kbd
+ * @param props - Optional configuration.
+ * @param props.color - Color tone for text/background/border. Defaults to `"neutral"`.
+ * @example { kbd: "Ctrl", $: [keyboard()] }
+ */
 declare function keyboard(props?: {
     color?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
+/**
+ * Themed form-label primitive: inline-flex layout with gap, themed text color,
+ * focus-within highlighting and a disabled (`aria-disabled`) state. Apply to a
+ * `<label>` element.
+ *
+ * @hostTag label
+ * @param props - Optional configuration.
+ * @param props.color - Base color tone for the label text. Defaults to `"neutral"`.
+ * @param props.accentColor - Accent color tone applied on focus-within. Defaults to `"primary"`.
+ * @example { label: "Email", htmlFor: "email", $: [label()] }
+ */
 declare function label(props?: {
     color?: ValueOrState<ThemeColor>;
     accentColor?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
+/**
+ * Themed hyperlink primitive: styles text color, hover underline, visited,
+ * focus ring and a disabled state. Apply to an `<a>` element.
+ *
+ * @hostTag a
+ * @param props - Optional configuration.
+ * @param props.color - Base color tone for the link text. Defaults to `"primary"`.
+ * @param props.accentColor - Accent color tone for visited/focus states. Defaults to `"secondary"`.
+ * @example { a: "Home", href: "/", $: [link()] }
+ */
 declare function link(props?: {
     color?: ValueOrState<ThemeColor>;
     accentColor?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
+/**
+ * Themed highlight primitive: gives marked/highlighted inline text a tinted
+ * background, rounded corners and padding. Apply to a `<mark>` element.
+ *
+ * @hostTag mark
+ * @param props - Optional configuration.
+ * @param props.accentColor - Accent color tone for the highlight fill and text. Defaults to `"highlight"`.
+ * @example { mark: "important", $: [mark()] }
+ */
 declare function mark(props?: {
     accentColor?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
-declare function paragraph(props?: {
-    color?: ValueOrState<ThemeColor>;
+/**
+ * Themed menu container that provides selection context (`activeKey`,
+ * `selectable`) to child `menuItem` patches and lays them out vertically.
+ * Sets `role="menu"`. Typically applied to a container element such as a
+ * `<div>` or `<ul>`.
+ *
+ * @param props - Optional configuration.
+ * @param props.activeKey - Currently selected item key, accepts a value or `State`. Defaults to `null`.
+ * @param props.selectable - Whether items track and update the active selection. Defaults to `true`.
+ * @param props.color - Background color tone for the menu. Defaults to `"neutral"`.
+ * @example { div: "", $: [menu({ activeKey: 0 })] }
+ */
+declare function menu(props?: {
+    activeKey?: ValueOrState<number | string>;
+    selectable?: boolean;
+    color?: ThemeColor;
 }): PartialElement;
 
-declare function preformated(props?: {
-    color?: ValueOrState<ThemeColor>;
+/**
+ * Themed menu entry for use inside a `menu`. Sets `role="menuitem"`, wires
+ * click/keyboard selection (Enter/Space activate; Arrow/Home/End move focus),
+ * and reflects the active item via `aria-current`. Apply to a `<button>`
+ * element placed within a `menu`.
+ *
+ * @hostTag button
+ * @param props - Optional configuration.
+ * @param props.accentColor - Accent color tone for the active/focus indicator. Defaults to `"primary"`.
+ * @param props.color - Base color tone for the item. Defaults to `"neutral"`.
+ * @example { button: "Profile", $: [menuItem()] }
+ */
+declare function menuItem(props?: {
+    accentColor?: ThemeColor;
+    color?: ThemeColor;
 }): PartialElement;
 
-declare function progress(props?: {
-    color?: ValueOrState<ThemeColor>;
-    accentColor?: ValueOrState<ThemeColor>;
-}): PartialElement;
+/**
+ * One keyframe. Shorthands `x`/`y` (px), `scale`, `rotate` (deg) compose into a
+ * single `transform`; any other key is a raw CSS property (e.g. `opacity`,
+ * `backgroundColor`).
+ */
+type MotionKeyframe = {
+    x?: number | string;
+    y?: number | string;
+    scale?: number | string;
+    rotate?: number | string;
+} & Record<string, string | number>;
+interface MotionProps {
+    /** Starting keyframe applied before the enter animation. */
+    initial?: MotionKeyframe;
+    /** Target keyframe. Pass a `State` to re-animate whenever it changes. */
+    animate?: MotionKeyframe | State<MotionKeyframe>;
+    /** Keyframe animated to before the element is removed. */
+    exit?: MotionKeyframe;
+    transition?: {
+        /** ms, default 300. */
+        duration?: number;
+        /** ms, default 0. */
+        delay?: number;
+        /** CSS easing, default "ease". */
+        easing?: string;
+        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.
+ *
+ * @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;
 
-declare function inputRadio(props?: {
+/**
+ * Themed ordered-list primitive: decimal markers positioned outside, reset
+ * margins and themed text color. Apply to an `<ol>` element.
+ *
+ * @hostTag ol
+ * @param props - Optional configuration.
+ * @param props.color - Color tone for the list text. Defaults to `"neutral"`.
+ * @example { ol: "", $: [orderedList()], children: [{ li: "First" }] }
+ */
+declare function orderedList(props?: {
     color?: ValueOrState<ThemeColor>;
-    accentColor?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
-declare function select(props?: {
+/**
+ * Themed pagination control. Renders previous/next buttons plus truncated page
+ * numbers (with ellipses), tracks the current page in a `State`, and updates it
+ * on click. Apply to a `<div>` element.
+ *
+ * @hostTag div
+ * @param props - Configuration.
+ * @param props.total - Required. Total number of pages.
+ * @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 })] }
+ */
+declare function pagination(props: {
+    value?: ValueOrState<number>;
+    total: number;
     color?: ThemeColor;
     accentColor?: ThemeColor;
 }): PartialElement;
 
-declare function skeleton(props?: {
+/**
+ * Themed paragraph primitive: comfortable line-height, reset margins and themed
+ * text color. Apply to a `<p>` element.
+ *
+ * @hostTag p
+ * @param props - Optional configuration.
+ * @param props.color - Color tone for the paragraph text. Defaults to `"neutral"`.
+ * @example { p: "Hello world", $: [paragraph()] }
+ */
+declare function paragraph(props?: {
     color?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
-declare function spinner(props?: {
-    color?: ValueOrState<ThemeColor>;
+/**
+ * Floating popover primitive. Attaches to its host as the anchor/trigger and
+ * shows a floating `content` element (with `role="dialog"`) on click or hover,
+ * positioned via `@domphy/floating`. Returns the anchor partial, which merges
+ * trigger wiring (haspopup/expanded, focus/blur dismissal). Apply to the
+ * trigger element you want the popover anchored to.
+ *
+ * @param props - Configuration.
+ * @param props.openOn - Interaction that opens the popover: `"click"` or `"hover"`. Defaults to `"click"`.
+ * @param props.open - Open state, accepts a value or `State`. Defaults to `false`.
+ * @param props.placement - Floating placement (e.g. `"bottom"`, `"top-start"`), value or `State`. Defaults to `"bottom"`.
+ * @param props.content - The floating content element to display.
+ * @example { button: "Open", $: [popover({ openOn: "click", content: { div: "Hi" } })] }
+ */
+declare function popover(props: {
+    openOn: "click" | "hover";
+    open?: ValueOrState<boolean>;
+    placement?: ValueOrState<Placement$1>;
+    content: DomphyElement;
 }): PartialElement;
 
-declare function selectList(props?: {
-    multiple?: boolean;
-    value?: ValueOrState<Array<number | string | null> | number | string | null>;
+/**
+ * Renders a small rotated arrow (via a `::after` pseudo-element) that points from a
+ * popover/tooltip toward its anchor, positioned and oriented based on the floating placement.
+ * The arrow direction is computed by flipping the given placement. No host-tag check is
+ * performed; apply it to the popover container element.
+ *
+ * @param props.placement - Floating placement the popover sits at; the arrow is drawn on the
+ *   opposite (flipped) side. Accepts a value or reactive state. Defaults to `"bottom-end"`.
+ *   One of: `top` | `bottom` | `left` | `right` | `top-start` | `top-end` | `bottom-start` |
+ *   `bottom-end` | `left-start` | `left-end` | `right-start` | `right-end`.
+ * @param props.sideOffset - CSS length used to offset the arrow toward the start/end edge.
+ *   Defaults to `themeSpacing(6)`.
+ * @param props.color - Theme color tone for the arrow fill and border. Defaults to `"neutral"`.
+ * @param props.bordered - Whether the arrow draws a 1px border (set to `0px` when false).
+ *   Defaults to `true`.
+ * @example { div: [...], $: [popoverArrow({ placement: "top" })] }
+ */
+declare function popoverArrow(props?: {
+    placement?: ValueOrState<Placement$1>;
+    sideOffset?: string;
     color?: ThemeColor;
-    name?: string;
+    bordered?: boolean;
 }): PartialElement;
 
-declare function selectItem(props?: {
-    accentColor?: ThemeColor;
+/**
+ * Styles a preformatted text block: inherited font size, themed foreground/background,
+ * no border, density-scaled padding and rounded corners.
+ *
+ * @hostTag pre
+ * @param props.color - Theme color tone for text and background. Accepts a value or reactive
+ *   state. Defaults to `"neutral"`.
+ * @example { pre: "const x = 1", $: [preformated()] }
+ */
+declare function preformated(props?: {
+    color?: ValueOrState<ThemeColor>;
+}): PartialElement;
+
+/**
+ * Styles a native progress bar: full-width, pill-shaped track with a themed fill,
+ * including the WebKit progress-bar/value pseudo-elements and a width transition.
+ *
+ * @hostTag progress
+ * @param props.color - Theme color tone for the track/background. Accepts a value or reactive
+ *   state. Defaults to `"neutral"`.
+ * @param props.accentColor - Theme color tone for the filled value. Accepts a value or reactive
+ *   state. Defaults to `"primary"`.
+ * @example { progress: null, value: 40, max: 100, $: [progress()] }
+ */
+declare function progress(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
+ * hover/focus/disabled/optgroup/option states.
+ *
+ * @hostTag select
+ * @param props.color - Theme color tone for text, background and outline. Defaults to `"neutral"`.
+ * @param props.accentColor - Theme color tone for hover/focus outlines. Defaults to `"primary"`.
+ * @example { select: [{ option: "A" }], $: [select()] }
+ */
+declare function select(props?: {
     color?: ThemeColor;
-    value?: number | string;
+    accentColor?: ThemeColor;
 }): PartialElement;
 
+/**
+ * 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.
+ *
+ * @hostTag div
+ * @param props.multiple - Whether multiple selection is allowed (renders removable tags and
+ *   keeps the popover open on click). Defaults to `false`.
+ * @param props.value - Bound selection value(s). Accepts a value or reactive state of an array of
+ *   `number | string | null | undefined`, or a single `number | string | null | undefined`.
+ * @param props.options - List of `{ label, value }` options used to resolve selected labels.
+ *   Defaults to `[]`.
+ * @param props.placement - Floating placement of the dropdown popover. Accepts a value or
+ *   reactive state. Defaults to `"bottom"`.
+ * @param props.content - Required. The popover/dropdown content element shown when open.
+ * @param props.color - Theme color tone for the box text/background. Defaults to `"neutral"`.
+ * @param props.open - Whether the popover is open. Accepts a value or reactive state. Defaults to `false`.
+ * @example { div: null, $: [selectBox({ content: { div: [...] }, options: [{ label: "A", value: "a" }] })] }
+ */
 declare function selectBox(props: {
     multiple?: boolean;
     value?: ValueOrState<Array<number | string | null | undefined> | number | string | null | undefined>;
@@ -260,148 +897,325 @@ declare function selectBox(props: {
     open?: ValueOrState<boolean>;
 }): PartialElement;
 
-declare function inputSwitch(props?: {
-    accentColor?: ValueOrState<ThemeColor>;
+/**
+ * A single selectable option row (`role="option"`) for use inside a `selectList`. Reads the
+ * `select` context to reflect/toggle selection: it sets `aria-selected` from the bound value and
+ * toggles the value (single or multiple) on click. Styles hover/selected/focus states.
+ *
+ * @hostTag div
+ * @param props.accentColor - Theme color tone for the selected/focus state. Defaults to `"primary"`.
+ * @param props.color - Theme color tone for text/background. Defaults to `"neutral"`.
+ * @param props.value - The option value compared against and written to the select state.
+ *   Defaults to `null`.
+ * @example { div: "Option A", $: [selectItem({ value: "a" })] }
+ */
+declare function selectItem(props?: {
+    accentColor?: ThemeColor;
+    color?: ThemeColor;
+    value?: number | string;
 }): PartialElement;
 
-declare function buttonSwitch(props?: {
-    checked?: ValueOrState<boolean>;
-    accentColor?: ValueOrState<ThemeColor>;
+/**
+ * Container for a list of `selectItem`s that owns the selection state. It exposes a `select`
+ * context (`{ value, multiple }`) consumed by child items, and injects hidden `<input>`(s)
+ * carrying the selected value(s) under `name` for form submission.
+ *
+ * @hostTag div
+ * @param props.multiple - Whether multiple selection is allowed; also sets the default empty
+ *   value (`[]` vs `null`). Defaults to `false`.
+ * @param props.value - Bound selection value(s). Accepts a value or reactive state of an array of
+ *   `number | string | null`, or a single `number | string | null`. Defaults to `[]` when
+ *   `multiple`, otherwise `null`.
+ * @param props.color - Theme color tone for the background. Defaults to `"neutral"`.
+ * @param props.name - Name attribute for the hidden inputs (form field name).
+ * @example { div: [{ div: "A", $: [selectItem({ value: "a" })] }], $: [selectList({ name: "pick" })] }
+ */
+declare function selectList(props?: {
+    multiple?: boolean;
+    value?: ValueOrState<Array<number | string | null> | number | string | null>;
+    color?: ThemeColor;
+    name?: string;
+}): PartialElement;
+
+/**
+ * A loading placeholder block with a pulsing opacity animation. Marked `aria-hidden`, themed
+ * background/foreground, fixed height, slight rounding. No host-tag check; typically applied
+ * to a block-level element such as a `div` or `span`.
+ *
+ * @param props.color - Theme color tone for the placeholder. Accepts a value or reactive state.
+ *   Defaults to `"neutral"`.
+ * @example { div: null, $: [skeleton()] }
+ */
+declare function skeleton(props?: {
     color?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
+/**
+ * Styles small/secondary text: one step smaller font size (`data-size="decrease-1"`) with a
+ * themed foreground color.
+ *
+ * @hostTag small
+ * @param props.color - Theme color tone for the text. Accepts a value or reactive state.
+ *   Defaults to `"neutral"`.
+ * @example { small: "fine print", $: [small()] }
+ */
 declare function small(props?: {
     color?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
+/**
+ * A circular loading spinner: a themed ring with a contrasting top border that rotates
+ * continuously. Marked `role="status"` with `aria-label="loading"`.
+ *
+ * @hostTag span
+ * @param props.color - Theme color tone for the ring/highlight. Accepts a value or reactive
+ *   state. Defaults to `"neutral"`.
+ * @example { span: null, $: [spinner()] }
+ */
+declare function spinner(props?: {
+    color?: ValueOrState<ThemeColor>;
+}): PartialElement;
+
+/**
+ * Root of a resizable split layout. Lays out children as a flex row (horizontal) or column
+ * (vertical) and provides a `splitter` context (`{ direction, size, min, max }`) consumed by
+ * `splitterPanel` and `splitterHandle`. `size` is a reactive state holding the first panel's
+ * percentage. No host-tag check; typically applied to a `div`.
+ *
+ * @param props.direction - Split orientation, `"horizontal"` | `"vertical"`. Defaults to `"horizontal"`.
+ * @param props.defaultSize - Initial size (percentage) of the resizable panel. Defaults to `50`.
+ * @param props.min - Minimum panel size (percentage). Defaults to `10`.
+ * @param props.max - Maximum panel size (percentage). Defaults to `90`.
+ * @example { div: [...], $: [splitter({ direction: "vertical" })] }
+ */
+declare function splitter(props?: {
+    direction?: "horizontal" | "vertical";
+    defaultSize?: number;
+    min?: number;
+    max?: number;
+}): PartialElement;
+/**
+ * The resizable panel inside a `splitter`. Reads the `splitter` context and binds its
+ * width (horizontal) or height (vertical) to the context `size` state, updating reactively as
+ * the handle is dragged. Warns if used outside a `splitter`. Takes no props.
+ *
+ * @example { div: [...], $: [splitterPanel()] }
+ */
+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.
+ *
+ * @example { div: null, $: [splitterHandle()] }
+ */
+declare function splitterHandle(): PartialElement;
+
+/**
+ * Styles strongly emphasized (bold) text: inherited font size, `font-weight: 700`, and a
+ * themed foreground color.
+ *
+ * @hostTag strong
+ * @param props.color - Theme color tone for the text. Accepts a value or reactive state.
+ *   Defaults to `"neutral"`.
+ * @example { strong: "important", $: [strong()] }
+ */
 declare function strong(props?: {
     color?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
+/**
+ * Renders subscript text (shrunk, baseline-lowered) for the host `<sub>` element.
+ *
+ * @hostTag sub
+ * @param props.color - Theme color for the text. Optional, accepts a value or state. Defaults to `"neutral"`.
+ * @example { sub: "2", $: [subscript()] }
+ */
 declare function subscript(props?: {
     color?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
+/**
+ * Renders superscript text (shrunk, baseline-raised) for the host `<sup>` element.
+ *
+ * @hostTag sup
+ * @param props.color - Theme color for the text. Optional, accepts a value or state. Defaults to `"neutral"`.
+ * @example { sup: "2", $: [superscript()] }
+ */
 declare function superscript(props?: {
     color?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
-declare function table(props?: {
-    color?: ValueOrState<ThemeColor>;
+/**
+ * Styles a single tab trigger inside a `tabs` tablist on the host `<button>` element.
+ * Wires up the tab's id/aria-controls/aria-selected, click selection, and
+ * arrow/Home/End keyboard navigation via the surrounding `tabs` context.
+ * Must be used inside a `tabs` patch.
+ *
+ * @hostTag button
+ * @param props.accentColor - Theme color for the active/focus underline. Optional. Defaults to `"primary"`.
+ * @param props.color - Theme color for the resting/hover underline and text. Optional. Defaults to `"neutral"`.
+ * @example { button: "Tab 1", $: [tab()] }
+ */
+declare function tab(props?: {
+    accentColor?: ThemeColor;
+    color?: ThemeColor;
 }): PartialElement;
 
-declare function textarea(props?: {
+/**
+ * Styles a data table (header/body/footer cells, caption, row hover, borders)
+ * on the host `<table>` element.
+ *
+ * @hostTag table
+ * @param props.color - Theme color applied across cells and text. Optional, accepts a value or state. Defaults to `"neutral"`.
+ * @example { table: null, $: [table()] }
+ */
+declare function table(props?: {
     color?: ValueOrState<ThemeColor>;
-    accentColor?: ValueOrState<ThemeColor>;
-    autoResize?: boolean;
 }): PartialElement;
 
-declare function unorderedList(props?: {
-    color?: ValueOrState<ThemeColor>;
-}): PartialElement;
+/**
+ * Styles a tab panel inside a `tabs` tablist. Wires up the panel's
+ * id/aria-labelledby and toggles `hidden` based on the surrounding `tabs`
+ * context's active key. Must be used inside a `tabs` patch. Takes no props.
+ *
+ * @hostTag div
+ * @example { div: "Panel content", $: [tabPanel()] }
+ */
+declare function tabPanel(): PartialElement;
 
-declare function orderedList(props?: {
-    color?: ValueOrState<ThemeColor>;
+/**
+ * Container patch that establishes a `tabs` context (with a shared `activeKey`
+ * state) and the `tablist` role for child `tab`/`tabPanel` patches. No host tag
+ * check; typically applied to a wrapper element.
+ *
+ * @param props.activeKey - Initially active tab key. Optional, accepts a value or state of `number | string`. Defaults to `0`.
+ * @example { div: null, $: [tabs({ activeKey: 0 })] }
+ */
+declare function tabs(props?: {
+    activeKey?: ValueOrState<number | string>;
 }): PartialElement;
 
-declare function pagination(props: {
-    value?: ValueOrState<number>;
-    total: number;
-    color?: ThemeColor;
-    accentColor?: ThemeColor;
+/**
+ * Styles an inline chip/tag (rounded, bordered, optional remove button).
+ * No host tag check; typically applied to a `<span>`. When `removable` is true,
+ * a close button is inserted that removes the host node on click.
+ *
+ * @hostTag span
+ * @param props.color - Theme color for the chip background/border/text. Optional, accepts a value or state. Defaults to `"neutral"`.
+ * @param props.removable - When true, renders a remove (x) button that removes the tag on click. Optional. Defaults to `false`.
+ * @example { span: "Label", $: [tag({ removable: true })] }
+ */
+declare function tag(props?: {
+    color?: ValueOrState<ThemeColor>;
+    removable?: boolean;
 }): PartialElement;
 
-declare function divider(props?: {
+/**
+ * Styles a multi-line text input (border, focus/hover/invalid/disabled states)
+ * on the host `<textarea>` element, with optional auto-resize to content.
+ *
+ * @hostTag textarea
+ * @param props.color - Theme color for the border and text. Optional, accepts a value or state. Defaults to `"neutral"`.
+ * @param props.accentColor - Theme color for hover/focus outline. Optional, accepts a value or state. Defaults to `"primary"`.
+ * @param props.autoResize - When true, grows the textarea height to fit its content on input. Optional. Defaults to `false`.
+ * @example { textarea: null, $: [textarea({ autoResize: true })] }
+ */
+declare function textarea(props?: {
     color?: ValueOrState<ThemeColor>;
+    accentColor?: ValueOrState<ThemeColor>;
+    autoResize?: boolean;
 }): PartialElement;
 
-type Placement = "left" | "right" | "top" | "bottom";
-declare function drawer(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
+ * 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"`.
+ * @example { div: "Saved!", $: [toast({ position: "top-right" })] }
+ */
+declare function toast(props?: {
+    position?: ToastPosition;
     color?: ThemeColor;
-    open?: ValueOrState<boolean>;
-    placement?: Placement;
-    size?: string;
 }): PartialElement;
 
-declare function popover(props: {
-    openOn: "click" | "hover";
-    open?: ValueOrState<boolean>;
-    placement?: ValueOrState<Placement$1>;
-    content: DomphyElement;
+/**
+ * Styles a single toggle button inside a `toggleGroup` on the host `<button>`
+ * element. Wires up `aria-pressed` and click-to-toggle against the surrounding
+ * `toggleGroup` context (single- or multi-select). Must be used inside a
+ * `toggleGroup` patch.
+ *
+ * @hostTag button
+ * @param props.color - Theme color for the resting/hover background and text. Optional, accepts a value or state. Defaults to `"neutral"`.
+ * @param props.accentColor - Theme color for the pressed/focus state. Optional, accepts a value or state. Defaults to `"primary"`.
+ * @example { button: "Bold", $: [toggle()] }
+ */
+declare function toggle(props?: {
+    color?: ValueOrState<ThemeColor>;
+    accentColor?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
-type ToastPosition = "top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right";
-declare function toast(props?: {
-    position?: ToastPosition;
+/**
+ * Container patch that establishes a `toggleGroup` context (shared selection
+ * `value` + `multiple` flag) and `group` role for child `toggle` patches, with
+ * a bordered segmented-control style. No host tag check; typically applied to a
+ * wrapper element.
+ *
+ * @param props.value - Selected toggle key(s). Optional, accepts a value or state of `string | string[]`. Defaults to `[]` when `multiple`, otherwise `""`.
+ * @param props.multiple - When true, allows multiple toggles selected at once. Optional. Defaults to `false`.
+ * @param props.color - Theme color for the group background/border. Optional. Defaults to `"neutral"`.
+ * @example { div: null, $: [toggleGroup({ multiple: true })] }
+ */
+declare function toggleGroup(props?: {
+    value?: ValueOrState<string | string[]>;
+    multiple?: boolean;
     color?: ThemeColor;
 }): PartialElement;
 
+/**
+ * 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
+ * surface is positioned via the floating utility and linked with
+ * `aria-describedby`. No host tag check; applied to the trigger element.
+ *
+ * @param props.open - Controlled open state. Optional, accepts a value or state. Defaults to `false`.
+ * @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"`.
+ * @example { button: "Hover me", $: [tooltip({ content: "Help text" })] }
+ */
 declare function tooltip(props?: {
     open?: ValueOrState<boolean>;
     placement?: ValueOrState<Placement$1>;
     content?: ValueOrState<string>;
 }): PartialElement;
 
+/**
+ * Animates child reordering using the FLIP technique: records each child's
+ * position before an update and smoothly transitions it from its old to new
+ * position afterward. No host tag check; applied to the list container.
+ *
+ * @param props.duration - Transition duration in milliseconds. Optional. Defaults to `300`.
+ * @param props.delay - Transition delay in milliseconds. Optional. Defaults to `0`.
+ * @example { ul: null, $: [transitionGroup({ duration: 300 })] }
+ */
 declare function transitionGroup(props?: {
     duration?: number;
     delay?: number;
 }): PartialElement;
 
-declare function tabs(props?: {
-    activeKey?: ValueOrState<number | string>;
-}): PartialElement;
-
-declare function tab(props?: {
-    accentColor?: ThemeColor;
-    color?: ThemeColor;
-}): PartialElement;
-
-declare function tabPanel(): PartialElement;
-
-declare function tag(props?: {
-    color?: ValueOrState<ThemeColor>;
-    removable?: boolean;
-}): PartialElement;
-
-declare function menu(props?: {
-    activeKey?: ValueOrState<number | string>;
-    selectable?: boolean;
-    color?: ThemeColor;
-}): PartialElement;
-
-declare function menuItem(props?: {
-    accentColor?: ThemeColor;
-    color?: ThemeColor;
-}): PartialElement;
-
 /**
- * One keyframe. Shorthands `x`/`y` (px), `scale`, `rotate` (deg) compose into a
- * single `transform`; any other key is a raw CSS property (e.g. `opacity`,
- * `backgroundColor`).
+ * Styles a bulleted list (disc markers, reset margins, themed text) on the host
+ * `<ul>` element.
+ *
+ * @hostTag ul
+ * @param props.color - Theme color for the list text. Optional, accepts a value or state. Defaults to `"neutral"`.
+ * @example { ul: null, $: [unorderedList()] }
  */
-type MotionKeyframe = {
-    x?: number | string;
-    y?: number | string;
-    scale?: number | string;
-    rotate?: number | string;
-} & Record<string, string | number>;
-interface MotionProps {
-    /** Starting keyframe applied before the enter animation. */
-    initial?: MotionKeyframe;
-    /** Target keyframe. Pass a `State` to re-animate whenever it changes. */
-    animate?: MotionKeyframe | State<MotionKeyframe>;
-    /** Keyframe animated to before the element is removed. */
-    exit?: MotionKeyframe;
-    transition?: {
-        /** ms, default 300. */
-        duration?: number;
-        /** ms, default 0. */
-        delay?: number;
-        /** CSS easing, default "ease". */
-        easing?: string;
-        iterations?: number;
-    };
-}
-declare function motion(props?: MotionProps): PartialElement;
+declare function unorderedList(props?: {
+    color?: ValueOrState<ThemeColor>;
+}): PartialElement;
 
-export { type MotionKeyframe, type MotionProps, abbreviation, alert, avatar, badge, blockquote, breadcrumb, breadcrumbEllipsis, button, buttonSwitch, card, code, combobox, command, commandItem, commandSearch, 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, 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 };