@domphy/ui 0.21.0 → 0.21.2

package/dist/index.d.cts

@@ -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;
 
 /**
@@ -449,6 +458,10 @@ declare function empty(props?: {
  * caught. Errors during static construction propagate normally — those are
  * programming errors, not runtime data errors.
  *
+ * `reset()` restores the original children (including a reactive children
+ * function) so the next evaluation runs again — it does not leave the host
+ * empty.
+ *
  * @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.
@@ -604,7 +617,7 @@ declare function inputCheckbox(props?: {
 /**
  * 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"`).
+ * default is `type: "color"`; a native `type` wins).
  *
  * @hostTag input
  * @param props.color - Optional theme color tone used for the disabled state (`ValueOrState<ThemeColor>`). Defaults to `"neutral"`.
@@ -620,7 +633,7 @@ 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`).
+ * an `<input>` element (the patch default `type` is the chosen `mode`; a native `type` wins).
  *
  * @hostTag input
  * @param props.mode - Input mode selecting the host `type`: `"date" | "time" | "week" | "month" | "datetime-local"`. Defaults to `"datetime-local"`.
@@ -637,7 +650,7 @@ declare function inputDateTime(props?: {
 /**
  * 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"`).
+ * default is `type: "file"`; a native `type` wins).
  *
  * @hostTag input
  * @param props.color - Optional theme color tone for text/border and the upload button (`ValueOrState<ThemeColor>`). Defaults to `"neutral"`.
@@ -652,7 +665,7 @@ declare function inputFile(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"`).
+ * type `number` (the patch default is `type: "number"`; a native `type` wins).
  *
  * @hostTag input
  * @param props.color - Optional theme color tone for text/border (`ValueOrState<ThemeColor>`). Defaults to `"neutral"`.
@@ -678,16 +691,32 @@ declare function inputOTP(): PartialElement;
 /**
  * Password input wrapper: a styled `<div>` that inserts an `<input type="password">`
  * and a show/hide toggle button. The outer div carries the focus-ring outline via
- * `:focus-within`. Apply to an empty `<div>`.
+ * `:focus-within`. Apply to an empty `<div>`. Host `value`/`name`/`onInput`/
+ * `disabled`/`required` are forwarded onto the real input so the field
+ * participates in FormData.
  *
  * @hostTag div
  * @param props.color - Base color tone for border/background/text. Defaults to `"neutral"`.
  * @param props.accentColor - Accent outline color on focus-within. Defaults to `"primary"`.
- * @example { div: null, $: [inputPassword()] }
+ * @param props.value - Forwarded onto the inner input. Optional.
+ * @param props.name - Forwarded onto the inner input (FormData key). Optional.
+ * @param props.onInput - Forwarded onto the inner input. Optional.
+ * @param props.disabled - Forwarded onto the inner input. Optional.
+ * @param props.required - Forwarded onto the inner input. Optional.
+ * @param props.autocomplete - Native autocomplete token. Defaults to `"current-password"`.
+ * @param props.ariaLabel - Accessible name for the inner input. Defaults to `"Password"`.
+ * @example { div: null, name: "password", $: [inputPassword()] }
  */
 declare function inputPassword(props?: {
     color?: ValueOrState<ThemeColor>;
     accentColor?: ValueOrState<ThemeColor>;
+    value?: ValueOrState<string>;
+    name?: string;
+    onInput?: (event: Event) => void;
+    disabled?: ValueOrState<boolean>;
+    required?: boolean;
+    autocomplete?: string;
+    ariaLabel?: string;
 }): PartialElement;
 
 /**
@@ -723,7 +752,7 @@ declare function inputRange(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"`).
+ * element of type `search` (the patch default is `type: "search"`; a native `type` wins).
  *
  * @hostTag input
  * @param props.color - Optional theme color tone for text/border/placeholder (`ValueOrState<ThemeColor>`). Defaults to `"neutral"`.
@@ -836,7 +865,7 @@ declare function linkButton(props?: {
  * @param props.color - Surface color tone. Optional `ThemeColor`, defaults to `"neutral"`.
  * @example { ul: [...], $: [list()] }
  */
-declare function list(_props?: {
+declare function list(props?: {
     color?: ThemeColor;
 }): PartialElement;
 /**
@@ -1085,11 +1114,22 @@ declare function progress(props?: {
     accentColor?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
+type RatingProps = {
+    value?: ValueOrState<number>;
+    max?: number;
+    onChange?: (value: number) => void;
+    readOnly?: boolean;
+    color?: ThemeColor;
+};
 /**
  * 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.
  *
+ * Star insert runs in `_onInit` (SSR markup). `onChange`/`readOnly`/`max` and
+ * a plain-number `value` stay live via `behavior()` `update()` so a reused
+ * node picks up the latest factory props.
+ *
  * @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`.
@@ -1098,13 +1138,7 @@ declare function progress(props?: {
  * @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;
+declare function rating(props?: RatingProps): PartialElement;
 
 /**
  * Circular ring progress indicator rendered via CSS `conic-gradient` and a
@@ -1212,6 +1246,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
@@ -1338,17 +1375,6 @@ declare function splitter(props?: {
     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. Intended for exactly two panels either side of one `splitterHandle`:
- * the first `splitterPanel` mounted takes `size`%, and the second takes the complementary
- * `100 - size`% — so the pair always sums to the full width/height instead of both tracking
- * the same number (which would make them grow and shrink together instead of trading space).
- * 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
@@ -1476,11 +1502,11 @@ declare function tabs(props?: {
 /**
  * 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.
+ * a close button is inserted that removes the host node on click or Enter/Space.
  *
  * @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`.
+ * @param props.removable - When true, renders a remove (x) button that removes the tag on click or Enter/Space. Optional. Defaults to `false`.
  * @example { span: "Label", $: [tag({ removable: true })] }
  */
 declare function tag(props?: {
@@ -1495,7 +1521,7 @@ declare function tag(props?: {
  * @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`.
+ * @param props.autoResize - When true, grows the textarea height to fit its content on input and when `value` updates. Optional. Defaults to `false`.
  * @example { textarea: null, $: [textarea({ autoResize: true })] }
  */
 declare function textarea(props?: {

package/dist/index.d.ts

@@ -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;
 
 /**
@@ -449,6 +458,10 @@ declare function empty(props?: {
  * caught. Errors during static construction propagate normally — those are
  * programming errors, not runtime data errors.
  *
+ * `reset()` restores the original children (including a reactive children
+ * function) so the next evaluation runs again — it does not leave the host
+ * empty.
+ *
  * @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.
@@ -604,7 +617,7 @@ declare function inputCheckbox(props?: {
 /**
  * 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"`).
+ * default is `type: "color"`; a native `type` wins).
  *
  * @hostTag input
  * @param props.color - Optional theme color tone used for the disabled state (`ValueOrState<ThemeColor>`). Defaults to `"neutral"`.
@@ -620,7 +633,7 @@ 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`).
+ * an `<input>` element (the patch default `type` is the chosen `mode`; a native `type` wins).
  *
  * @hostTag input
  * @param props.mode - Input mode selecting the host `type`: `"date" | "time" | "week" | "month" | "datetime-local"`. Defaults to `"datetime-local"`.
@@ -637,7 +650,7 @@ declare function inputDateTime(props?: {
 /**
  * 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"`).
+ * default is `type: "file"`; a native `type` wins).
  *
  * @hostTag input
  * @param props.color - Optional theme color tone for text/border and the upload button (`ValueOrState<ThemeColor>`). Defaults to `"neutral"`.
@@ -652,7 +665,7 @@ declare function inputFile(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"`).
+ * type `number` (the patch default is `type: "number"`; a native `type` wins).
  *
  * @hostTag input
  * @param props.color - Optional theme color tone for text/border (`ValueOrState<ThemeColor>`). Defaults to `"neutral"`.
@@ -678,16 +691,32 @@ declare function inputOTP(): PartialElement;
 /**
  * Password input wrapper: a styled `<div>` that inserts an `<input type="password">`
  * and a show/hide toggle button. The outer div carries the focus-ring outline via
- * `:focus-within`. Apply to an empty `<div>`.
+ * `:focus-within`. Apply to an empty `<div>`. Host `value`/`name`/`onInput`/
+ * `disabled`/`required` are forwarded onto the real input so the field
+ * participates in FormData.
  *
  * @hostTag div
  * @param props.color - Base color tone for border/background/text. Defaults to `"neutral"`.
  * @param props.accentColor - Accent outline color on focus-within. Defaults to `"primary"`.
- * @example { div: null, $: [inputPassword()] }
+ * @param props.value - Forwarded onto the inner input. Optional.
+ * @param props.name - Forwarded onto the inner input (FormData key). Optional.
+ * @param props.onInput - Forwarded onto the inner input. Optional.
+ * @param props.disabled - Forwarded onto the inner input. Optional.
+ * @param props.required - Forwarded onto the inner input. Optional.
+ * @param props.autocomplete - Native autocomplete token. Defaults to `"current-password"`.
+ * @param props.ariaLabel - Accessible name for the inner input. Defaults to `"Password"`.
+ * @example { div: null, name: "password", $: [inputPassword()] }
  */
 declare function inputPassword(props?: {
     color?: ValueOrState<ThemeColor>;
     accentColor?: ValueOrState<ThemeColor>;
+    value?: ValueOrState<string>;
+    name?: string;
+    onInput?: (event: Event) => void;
+    disabled?: ValueOrState<boolean>;
+    required?: boolean;
+    autocomplete?: string;
+    ariaLabel?: string;
 }): PartialElement;
 
 /**
@@ -723,7 +752,7 @@ declare function inputRange(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"`).
+ * element of type `search` (the patch default is `type: "search"`; a native `type` wins).
  *
  * @hostTag input
  * @param props.color - Optional theme color tone for text/border/placeholder (`ValueOrState<ThemeColor>`). Defaults to `"neutral"`.
@@ -836,7 +865,7 @@ declare function linkButton(props?: {
  * @param props.color - Surface color tone. Optional `ThemeColor`, defaults to `"neutral"`.
  * @example { ul: [...], $: [list()] }
  */
-declare function list(_props?: {
+declare function list(props?: {
     color?: ThemeColor;
 }): PartialElement;
 /**
@@ -1085,11 +1114,22 @@ declare function progress(props?: {
     accentColor?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
+type RatingProps = {
+    value?: ValueOrState<number>;
+    max?: number;
+    onChange?: (value: number) => void;
+    readOnly?: boolean;
+    color?: ThemeColor;
+};
 /**
  * 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.
  *
+ * Star insert runs in `_onInit` (SSR markup). `onChange`/`readOnly`/`max` and
+ * a plain-number `value` stay live via `behavior()` `update()` so a reused
+ * node picks up the latest factory props.
+ *
  * @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`.
@@ -1098,13 +1138,7 @@ declare function progress(props?: {
  * @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;
+declare function rating(props?: RatingProps): PartialElement;
 
 /**
  * Circular ring progress indicator rendered via CSS `conic-gradient` and a
@@ -1212,6 +1246,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
@@ -1338,17 +1375,6 @@ declare function splitter(props?: {
     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. Intended for exactly two panels either side of one `splitterHandle`:
- * the first `splitterPanel` mounted takes `size`%, and the second takes the complementary
- * `100 - size`% — so the pair always sums to the full width/height instead of both tracking
- * the same number (which would make them grow and shrink together instead of trading space).
- * 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
@@ -1476,11 +1502,11 @@ declare function tabs(props?: {
 /**
  * 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.
+ * a close button is inserted that removes the host node on click or Enter/Space.
  *
  * @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`.
+ * @param props.removable - When true, renders a remove (x) button that removes the tag on click or Enter/Space. Optional. Defaults to `false`.
  * @example { span: "Label", $: [tag({ removable: true })] }
  */
 declare function tag(props?: {
@@ -1495,7 +1521,7 @@ declare function tag(props?: {
  * @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`.
+ * @param props.autoResize - When true, grows the textarea height to fit its content on input and when `value` updates. Optional. Defaults to `false`.
  * @example { textarea: null, $: [textarea({ autoResize: true })] }
  */
 declare function textarea(props?: {