@domphy/ui 0.20.12 → 0.21.1

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { ValueOrState, PartialElement, DomphyElement, State } from '@domphy/core';
+import { ValueOrState, PartialElement, DomphyElement, State, Listener } from '@domphy/core';
 import { ThemeColor } from '@domphy/theme';
 import { Placement as Placement$1 } from '@domphy/floating';
 export { Placement } from '@domphy/floating';
@@ -359,14 +359,23 @@ declare function details(props?: {
  * dialog, restores focus to the previously focused element on close, sets
  * `aria-modal`, and closes on outside (backdrop) click. Apply to a `<dialog>`.
  *
+ * Accessible name/description: pass `labelledBy`/`describedBy` the `id` of a
+ * heading/paragraph inside the dialog (Radix Title/Description parity). The
+ * native `ariaLabelledby`/`ariaDescribedby` attributes on the host element
+ * remain an equivalent escape hatch (the native element always wins).
+ *
  * @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 })] }
+ * @param props.labelledBy - `id` of the element labeling the dialog (wired to `aria-labelledby`). Optional.
+ * @param props.describedBy - `id` of the element describing the dialog (wired to `aria-describedby`). Optional.
+ * @example { dialog: [{ h2: "Confirm", id: "dlg-title" }], $: [dialog({ open, labelledBy: "dlg-title" })] }
  */
 declare function dialog(props?: {
     color?: ThemeColor;
     open?: ValueOrState<boolean>;
+    labelledBy?: string;
+    describedBy?: string;
 }): PartialElement;
 
 /**
@@ -501,6 +510,43 @@ declare function formGroup(props?: {
     layout?: "horizontal" | "vertical";
 }): PartialElement;
 
+type FlexAlign = "flex-start" | "center" | "flex-end" | "stretch" | "baseline";
+/**
+ * A vertical flex column with spacing between children. The general-purpose
+ * primitive for stacking blocks — form sections, panel content, card bodies —
+ * instead of hand-rolling `display: flex; flexDirection: column; gap: ...`.
+ * Styles the host only; apply to any block element.
+ *
+ * @param props.gap - Spacing multiplier for gap between children (default 3 = 0.75em at density 1).
+ * @param props.align - Cross-axis alignment (`alignItems`). Unset by default (flex default, stretch).
+ * @example { div: [{ h3: "Title" }, { p: "Body" }], $: [stack()] }
+ * @example { div: [...], $: [stack({ gap: 2, align: "center" })] }
+ */
+declare function stack(props?: {
+    gap?: number;
+    align?: FlexAlign;
+}): PartialElement;
+
+/**
+ * A CSS grid with a column template and spacing between cells — the
+ * general-purpose primitive for card/property/stat grids instead of
+ * hand-rolling `display: "grid"; gridTemplateColumns: ...; gap: ...`.
+ * Mirrors `row()`'s contract. Styles the host only; apply to any block
+ * element.
+ *
+ * @param props.columns - Column count (expanded to `repeat(N, minmax(0, 1fr))`)
+ *   or a raw `grid-template-columns` value. Defaults to `1`.
+ * @param props.gap - Spacing multiplier for gap between cells (default 4 = 1em at density 1).
+ * @param props.align - Block-axis alignment of items (`alignItems`). Unset by default.
+ * @example { div: [{ div: "A" }, { div: "B" }], $: [grid({ columns: 2 })] }
+ * @example { div: [...], $: [grid({ columns: "repeat(auto-fill, minmax(12em, 1fr))", gap: 6 })] }
+ */
+declare function grid(props?: {
+    columns?: number | string;
+    gap?: number;
+    align?: FlexAlign;
+}): 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>`.
@@ -712,17 +758,19 @@ declare function inputSwitch(props?: {
 }): 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.
+ * Themed single-line text input primitive. Sets `type` (default `"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.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()] }
  */
 declare function inputText(props?: {
+    type?: string;
     color?: ValueOrState<ThemeColor>;
     accentColor?: ValueOrState<ThemeColor>;
 }): PartialElement;
@@ -1089,23 +1137,6 @@ declare function ringProgress(props?: {
     thickness?: number;
 }): PartialElement;
 
-type FlexAlign = "flex-start" | "center" | "flex-end" | "stretch" | "baseline";
-/**
- * A vertical flex column with spacing between children. The general-purpose
- * primitive for stacking blocks — form sections, panel content, card bodies —
- * instead of hand-rolling `display: flex; flexDirection: column; gap: ...`.
- * Styles the host only; apply to any block element.
- *
- * @param props.gap - Spacing multiplier for gap between children (default 3 = 0.75em at density 1).
- * @param props.align - Cross-axis alignment (`alignItems`). Unset by default (flex default, stretch).
- * @example { div: [{ h3: "Title" }, { p: "Body" }], $: [stack()] }
- * @example { div: [...], $: [stack({ gap: 2, align: "center" })] }
- */
-declare function stack(props?: {
-    gap?: number;
-    align?: FlexAlign;
-}): PartialElement;
-
 type FlexJustify = "flex-start" | "center" | "flex-end" | "space-between" | "space-around" | "space-evenly";
 /**
  * A horizontal flex row with spacing between children, vertically centered by
@@ -1190,6 +1221,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
+ * `[role=option]` in the panel; a repeated character cycles matches).
  *
  * @hostTag div
  * @param props.multiple - Whether multiple selection is allowed (renders removable tags and
@@ -1615,4 +1649,40 @@ declare function unorderedList(props?: {
     color?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
-export { type ButtonVariant, type DatePickerProps, type DatePickerValue, type FlexAlign, type FlexJustify, type MenuItem, type MotionKeyframe, type MotionProps, type SegmentedItem, type StepItem, type TabItem, type ToggleItem, abbreviation, accordion, alert, avatar, badge, blockquote, breadcrumb, breadcrumbEllipsis, button, buttonGhost, 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, inputPassword, inputRadio, inputRange, inputSearch, inputSwitch, inputText, keyboard, label, link, linkButton, list, listItem, listItemButton, mark, menu, motion, orderedList, pagination, panelSection, paragraph, popover, popoverArrow, preformated, progress, rating, ringProgress, row, scrollArea, segmented, select, selectBox, selectItem, selectList, skeleton, small, spinner, splitter, splitterHandle, splitterPanel, stack, steps, strong, subscript, superscript, table, tabs, tag, textarea, timeline, timelineItem, toast, toggleGroup, toolbar, toolbarSpacer, tooltip, transitionGroup, unorderedList };
+/**
+ * Visually hides an element while keeping it in the accessibility tree — the
+ * classic "sr-only" recipe for screen-reader-only labels, live-region text,
+ * and skip links (before focus). Styles the host only; apply to any element.
+ *
+ * @example { span: "Opens in a new tab", $: [visuallyHidden()] }
+ */
+declare function visuallyHidden(): PartialElement;
+
+/** Named elevation levels for floating/raised surfaces. */
+type ElevationLevel = "low" | "medium" | "high";
+/**
+ * Shared box-shadow value for a named elevation level. Used by floating/raised
+ * surface patches (popover, menu, dialog, drawer, toast, tooltip, combobox/
+ * selectBox dropdown, datePicker popup, fab) so elevation reads consistently
+ * across the library instead of each patch picking its own shadow.
+ */
+declare function elevation(level: ElevationLevel): string;
+
+/**
+ * Shared `:focus-visible` ring — ring-offset pattern used by Radix / shadcn /
+ * Vercel / Linear:
+ *
+ *   1. 2px "gap" in the surface tone (reads as space between control + ring)
+ *   2. 2px accent halo outside that gap
+ *
+ * Implemented as a layered `box-shadow` so it composes with a control's own
+ * resting outline / elevation instead of replacing them. Prefer this over a
+ * flush `0 0 0 2px` ring (looks like a thick pastel border glued to the edge)
+ * and over the browser default outline.
+ *
+ * Accent at `shift-9` stays legible on both light and dark surfaces; the
+ * washed `shift-6` flush ring is what made focus look broken in product UIs.
+ */
+declare function focusRing(listener: Listener, color?: ThemeColor): string;
+
+export { type ButtonVariant, type DatePickerProps, type DatePickerValue, type ElevationLevel, type FlexAlign, type FlexJustify, type MenuItem, type MotionKeyframe, type MotionProps, type SegmentedItem, type StepItem, type TabItem, type ToggleItem, abbreviation, accordion, alert, avatar, badge, blockquote, breadcrumb, breadcrumbEllipsis, button, buttonGhost, buttonSwitch, card, code, combobox, command, commandItem, commandSearch, datePicker, descriptionList, details, dialog, divider, drawer, elevation, emphasis, empty, errorBoundary, fab, figure, focusRing, formGroup, grid, heading, horizontalRule, icon, image, inputCheckbox, inputColor, inputDateTime, inputFile, inputNumber, inputOTP, inputPassword, inputRadio, inputRange, inputSearch, inputSwitch, inputText, keyboard, label, link, linkButton, list, listItem, listItemButton, mark, menu, motion, orderedList, pagination, panelSection, paragraph, popover, popoverArrow, preformated, progress, rating, ringProgress, row, scrollArea, segmented, select, selectBox, selectItem, selectList, skeleton, small, spinner, splitter, splitterHandle, splitterPanel, stack, steps, strong, subscript, superscript, table, tabs, tag, textarea, timeline, timelineItem, toast, toggleGroup, toolbar, toolbarSpacer, tooltip, transitionGroup, unorderedList, visuallyHidden };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ValueOrState, PartialElement, DomphyElement, State } from '@domphy/core';
+import { ValueOrState, PartialElement, DomphyElement, State, Listener } from '@domphy/core';
 import { ThemeColor } from '@domphy/theme';
 import { Placement as Placement$1 } from '@domphy/floating';
 export { Placement } from '@domphy/floating';
@@ -359,14 +359,23 @@ declare function details(props?: {
  * dialog, restores focus to the previously focused element on close, sets
  * `aria-modal`, and closes on outside (backdrop) click. Apply to a `<dialog>`.
  *
+ * Accessible name/description: pass `labelledBy`/`describedBy` the `id` of a
+ * heading/paragraph inside the dialog (Radix Title/Description parity). The
+ * native `ariaLabelledby`/`ariaDescribedby` attributes on the host element
+ * remain an equivalent escape hatch (the native element always wins).
+ *
  * @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 })] }
+ * @param props.labelledBy - `id` of the element labeling the dialog (wired to `aria-labelledby`). Optional.
+ * @param props.describedBy - `id` of the element describing the dialog (wired to `aria-describedby`). Optional.
+ * @example { dialog: [{ h2: "Confirm", id: "dlg-title" }], $: [dialog({ open, labelledBy: "dlg-title" })] }
  */
 declare function dialog(props?: {
     color?: ThemeColor;
     open?: ValueOrState<boolean>;
+    labelledBy?: string;
+    describedBy?: string;
 }): PartialElement;
 
 /**
@@ -501,6 +510,43 @@ declare function formGroup(props?: {
     layout?: "horizontal" | "vertical";
 }): PartialElement;
 
+type FlexAlign = "flex-start" | "center" | "flex-end" | "stretch" | "baseline";
+/**
+ * A vertical flex column with spacing between children. The general-purpose
+ * primitive for stacking blocks — form sections, panel content, card bodies —
+ * instead of hand-rolling `display: flex; flexDirection: column; gap: ...`.
+ * Styles the host only; apply to any block element.
+ *
+ * @param props.gap - Spacing multiplier for gap between children (default 3 = 0.75em at density 1).
+ * @param props.align - Cross-axis alignment (`alignItems`). Unset by default (flex default, stretch).
+ * @example { div: [{ h3: "Title" }, { p: "Body" }], $: [stack()] }
+ * @example { div: [...], $: [stack({ gap: 2, align: "center" })] }
+ */
+declare function stack(props?: {
+    gap?: number;
+    align?: FlexAlign;
+}): PartialElement;
+
+/**
+ * A CSS grid with a column template and spacing between cells — the
+ * general-purpose primitive for card/property/stat grids instead of
+ * hand-rolling `display: "grid"; gridTemplateColumns: ...; gap: ...`.
+ * Mirrors `row()`'s contract. Styles the host only; apply to any block
+ * element.
+ *
+ * @param props.columns - Column count (expanded to `repeat(N, minmax(0, 1fr))`)
+ *   or a raw `grid-template-columns` value. Defaults to `1`.
+ * @param props.gap - Spacing multiplier for gap between cells (default 4 = 1em at density 1).
+ * @param props.align - Block-axis alignment of items (`alignItems`). Unset by default.
+ * @example { div: [{ div: "A" }, { div: "B" }], $: [grid({ columns: 2 })] }
+ * @example { div: [...], $: [grid({ columns: "repeat(auto-fill, minmax(12em, 1fr))", gap: 6 })] }
+ */
+declare function grid(props?: {
+    columns?: number | string;
+    gap?: number;
+    align?: FlexAlign;
+}): 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>`.
@@ -712,17 +758,19 @@ declare function inputSwitch(props?: {
 }): 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.
+ * Themed single-line text input primitive. Sets `type` (default `"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.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()] }
  */
 declare function inputText(props?: {
+    type?: string;
     color?: ValueOrState<ThemeColor>;
     accentColor?: ValueOrState<ThemeColor>;
 }): PartialElement;
@@ -1089,23 +1137,6 @@ declare function ringProgress(props?: {
     thickness?: number;
 }): PartialElement;
 
-type FlexAlign = "flex-start" | "center" | "flex-end" | "stretch" | "baseline";
-/**
- * A vertical flex column with spacing between children. The general-purpose
- * primitive for stacking blocks — form sections, panel content, card bodies —
- * instead of hand-rolling `display: flex; flexDirection: column; gap: ...`.
- * Styles the host only; apply to any block element.
- *
- * @param props.gap - Spacing multiplier for gap between children (default 3 = 0.75em at density 1).
- * @param props.align - Cross-axis alignment (`alignItems`). Unset by default (flex default, stretch).
- * @example { div: [{ h3: "Title" }, { p: "Body" }], $: [stack()] }
- * @example { div: [...], $: [stack({ gap: 2, align: "center" })] }
- */
-declare function stack(props?: {
-    gap?: number;
-    align?: FlexAlign;
-}): PartialElement;
-
 type FlexJustify = "flex-start" | "center" | "flex-end" | "space-between" | "space-around" | "space-evenly";
 /**
  * A horizontal flex row with spacing between children, vertically centered by
@@ -1190,6 +1221,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
+ * `[role=option]` in the panel; a repeated character cycles matches).
  *
  * @hostTag div
  * @param props.multiple - Whether multiple selection is allowed (renders removable tags and
@@ -1615,4 +1649,40 @@ declare function unorderedList(props?: {
     color?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
-export { type ButtonVariant, type DatePickerProps, type DatePickerValue, type FlexAlign, type FlexJustify, type MenuItem, type MotionKeyframe, type MotionProps, type SegmentedItem, type StepItem, type TabItem, type ToggleItem, abbreviation, accordion, alert, avatar, badge, blockquote, breadcrumb, breadcrumbEllipsis, button, buttonGhost, 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, inputPassword, inputRadio, inputRange, inputSearch, inputSwitch, inputText, keyboard, label, link, linkButton, list, listItem, listItemButton, mark, menu, motion, orderedList, pagination, panelSection, paragraph, popover, popoverArrow, preformated, progress, rating, ringProgress, row, scrollArea, segmented, select, selectBox, selectItem, selectList, skeleton, small, spinner, splitter, splitterHandle, splitterPanel, stack, steps, strong, subscript, superscript, table, tabs, tag, textarea, timeline, timelineItem, toast, toggleGroup, toolbar, toolbarSpacer, tooltip, transitionGroup, unorderedList };
+/**
+ * Visually hides an element while keeping it in the accessibility tree — the
+ * classic "sr-only" recipe for screen-reader-only labels, live-region text,
+ * and skip links (before focus). Styles the host only; apply to any element.
+ *
+ * @example { span: "Opens in a new tab", $: [visuallyHidden()] }
+ */
+declare function visuallyHidden(): PartialElement;
+
+/** Named elevation levels for floating/raised surfaces. */
+type ElevationLevel = "low" | "medium" | "high";
+/**
+ * Shared box-shadow value for a named elevation level. Used by floating/raised
+ * surface patches (popover, menu, dialog, drawer, toast, tooltip, combobox/
+ * selectBox dropdown, datePicker popup, fab) so elevation reads consistently
+ * across the library instead of each patch picking its own shadow.
+ */
+declare function elevation(level: ElevationLevel): string;
+
+/**
+ * Shared `:focus-visible` ring — ring-offset pattern used by Radix / shadcn /
+ * Vercel / Linear:
+ *
+ *   1. 2px "gap" in the surface tone (reads as space between control + ring)
+ *   2. 2px accent halo outside that gap
+ *
+ * Implemented as a layered `box-shadow` so it composes with a control's own
+ * resting outline / elevation instead of replacing them. Prefer this over a
+ * flush `0 0 0 2px` ring (looks like a thick pastel border glued to the edge)
+ * and over the browser default outline.
+ *
+ * Accent at `shift-9` stays legible on both light and dark surfaces; the
+ * washed `shift-6` flush ring is what made focus look broken in product UIs.
+ */
+declare function focusRing(listener: Listener, color?: ThemeColor): string;
+
+export { type ButtonVariant, type DatePickerProps, type DatePickerValue, type ElevationLevel, type FlexAlign, type FlexJustify, type MenuItem, type MotionKeyframe, type MotionProps, type SegmentedItem, type StepItem, type TabItem, type ToggleItem, abbreviation, accordion, alert, avatar, badge, blockquote, breadcrumb, breadcrumbEllipsis, button, buttonGhost, buttonSwitch, card, code, combobox, command, commandItem, commandSearch, datePicker, descriptionList, details, dialog, divider, drawer, elevation, emphasis, empty, errorBoundary, fab, figure, focusRing, formGroup, grid, heading, horizontalRule, icon, image, inputCheckbox, inputColor, inputDateTime, inputFile, inputNumber, inputOTP, inputPassword, inputRadio, inputRange, inputSearch, inputSwitch, inputText, keyboard, label, link, linkButton, list, listItem, listItemButton, mark, menu, motion, orderedList, pagination, panelSection, paragraph, popover, popoverArrow, preformated, progress, rating, ringProgress, row, scrollArea, segmented, select, selectBox, selectItem, selectList, skeleton, small, spinner, splitter, splitterHandle, splitterPanel, stack, steps, strong, subscript, superscript, table, tabs, tag, textarea, timeline, timelineItem, toast, toggleGroup, toolbar, toolbarSpacer, tooltip, transitionGroup, unorderedList, visuallyHidden };