@domphy/ui 0.21.3 → 0.21.5

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { ValueOrState, PartialElement, DomphyElement, State, Listener } from '@domphy/core';
-import { ThemeColor } from '@domphy/theme';
+import { ThemeColor, ElementSize } from '@domphy/theme';
 import { Placement as Placement$1 } from '@domphy/floating';
 export { Placement } from '@domphy/floating';
 
@@ -213,7 +213,8 @@ declare function code(props?: {
  * @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.open - Whether the popover is open. Optional `ValueOrState<boolean>` (including `Computed`/`ReadableState`), default false. When the source is read-only, pass `onDismiss` so dismiss can close.
+ * @param props.onDismiss - Called when the popover requests close. Optional. Required to close when `open` is a read-only `Computed`/`ReadableState`.
  * @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 } })] }
  */
@@ -228,6 +229,7 @@ declare function combobox(props: {
     content: DomphyElement;
     color?: ThemeColor;
     open?: ValueOrState<boolean>;
+    onDismiss?: () => void;
     input?: DomphyElement;
 }): PartialElement;
 
@@ -368,7 +370,8 @@ declare function details(props?: {
  *
  * @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.
+ * @param props.open - Open state (`ValueOrState<boolean>`), including `Computed`/`ReadableState`. When the source is read-only, pass `onDismiss` so Escape/backdrop can close. Defaults to false.
+ * @param props.onDismiss - Called when Escape/backdrop/`requestClose` request close. Optional. Required to close when `open` is a read-only `Computed`/`ReadableState`.
  * @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" })] }
@@ -376,6 +379,7 @@ declare function details(props?: {
 declare function dialog(props?: {
     color?: ThemeColor;
     open?: ValueOrState<boolean>;
+    onDismiss?: () => void;
     labelledBy?: string;
     describedBy?: string;
 }): PartialElement;
@@ -412,7 +416,8 @@ type Placement = PhysicalPlacement | "start" | "end";
  *
  * @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.open - Open state (`ValueOrState<boolean>`), including `Computed`/`ReadableState`. When the source is read-only, pass `onDismiss` so Escape/backdrop can close. Defaults to false.
+ * @param props.onDismiss - Called when Escape/backdrop/`requestClose` request close. Optional. Required to close when `open` is a read-only `Computed`/`ReadableState`.
  * @param props.placement - Edge to anchor to. "left" | "right" | "top" | "bottom" | "start" | "end". Defaults to "end".
  * @param props.size - CSS length for the drawer's width (left/right/start/end) or height (top/bottom). Defaults to themeSpacing(80) for left/right, themeSpacing(64) for top/bottom.
  * @example { dialog: [...], $: [drawer({ open, placement: "start" })] }
@@ -420,6 +425,7 @@ type Placement = PhysicalPlacement | "start" | "end";
 declare function drawer(props?: {
     color?: ThemeColor;
     open?: ValueOrState<boolean>;
+    onDismiss?: () => void;
     placement?: Placement;
     size?: string;
 }): PartialElement;
@@ -517,20 +523,32 @@ declare function formGroup(props?: {
 }): PartialElement;
 
 type FlexAlign = "flex-start" | "center" | "flex-end" | "stretch" | "baseline";
+type FlexJustify = "flex-start" | "center" | "flex-end" | "space-between" | "space-around" | "space-evenly";
 /**
  * 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.gap - Spacing multiplier for gap between children (default 3).
+ *   Bounded-control mode (`density: true`, default): `themeSpacing(themeDensity(l) * gap)`
+ *   — at default density 1.5, gap 3 = 1.125em.
+ *   Structural/page-column mode (`density: false`): bare `themeSpacing(gap)` with no
+ *   density multiply — gap 3 = 0.75em, matching AGENTS.md "bare themeSpacing(n)".
  * @param props.align - Cross-axis alignment (`alignItems`). Unset by default (flex default, stretch).
+ * @param props.justify - Main-axis distribution (`justifyContent`). Unset by default (flex-start).
+ * @param props.density - When true (default), gap is multiplied by theme density
+ *   (bounded controls). When false, gap is structural `themeSpacing(n)` — use this
+ *   for page/form columns.
  * @example { div: [{ h3: "Title" }, { p: "Body" }], $: [stack()] }
  * @example { div: [...], $: [stack({ gap: 2, align: "center" })] }
+ * @example { div: [...], $: [stack({ gap: 3, density: false, justify: "space-between" })] }
  */
 declare function stack(props?: {
     gap?: number;
     align?: FlexAlign;
+    justify?: FlexJustify;
+    density?: boolean;
 }): PartialElement;
 
 /**
@@ -559,10 +577,13 @@ declare function grid(props?: {
  *
  * @hostTag h1
  * @param props.color - Theme color tone (`ValueOrState<ThemeColor>`) for the heading text. Defaults to "neutral".
+ * @param props.size - Optional `ElementSize` (`"inherit"` | `"increase-N"` | `"decrease-N"`, N ≤ 7). When set, font size is `themeSize(listener, size)` including `"inherit"` (no tag bump). When omitted, follows the host tag (`h1` increase-4 … `h6` decrease-1).
  * @example { h2: "Section title", $: [heading()] }
+ * @example { h3: "Panel title", $: [heading({ size: "inherit" })] }
  */
 declare function heading(props?: {
     color?: ValueOrState<ThemeColor>;
+    size?: ElementSize;
 }): PartialElement;
 
 /**
@@ -1051,7 +1072,8 @@ declare function paragraph(props?: {
  *
  * @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.open - Open state (`ValueOrState<boolean>`), including `Computed`/`ReadableState`. When the source is read-only, pass `onDismiss` so Escape/outside click can close. Defaults to `false`.
+ * @param props.onDismiss - Called when the panel requests close. Optional. Required to close when `open` is a read-only `Computed`/`ReadableState`.
  * @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" } })] }
@@ -1059,6 +1081,7 @@ declare function paragraph(props?: {
 declare function popover(props: {
     openOn?: "click" | "hover";
     open?: ValueOrState<boolean>;
+    onDismiss?: () => void;
     placement?: ValueOrState<Placement$1>;
     content: DomphyElement;
 }): PartialElement;
@@ -1164,7 +1187,6 @@ declare function ringProgress(props?: {
     thickness?: number;
 }): 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
  * default. The general-purpose primitive for icon+label rows, field rows,
@@ -1172,18 +1194,27 @@ type FlexJustify = "flex-start" | "center" | "flex-end" | "space-between" | "spa
  * center; gap: ...`. `toolbar()` is a semantic alias of this same shape for
  * headers/nav bars. Styles the host only; apply to any block element.
  *
- * @param props.gap - Spacing multiplier for gap between items (default 4 = 1em at density 1).
+ * @param props.gap - Spacing multiplier for gap between items (default 4).
+ *   Bounded-control mode (`density: true`, default): `themeSpacing(themeDensity(l) * gap)`
+ *   — at default density 1.5, gap 4 = 1.5em.
+ *   Structural/page-column mode (`density: false`): bare `themeSpacing(gap)` with no
+ *   density multiply — gap 4 = 1em, matching AGENTS.md "bare themeSpacing(n)".
  * @param props.align - Cross-axis alignment (`alignItems`). Defaults to `"center"`.
  * @param props.justify - Main-axis distribution (`justifyContent`). Unset by default (flex-start).
  * @param props.wrap - Allow items to wrap onto multiple lines. Defaults to `false`.
+ * @param props.density - When true (default), gap is multiplied by theme density
+ *   (bounded controls). When false, gap is structural `themeSpacing(n)` — use this
+ *   for page/form columns.
  * @example { div: [{ span: "Icon" }, { span: "Label" }], $: [row()] }
  * @example { div: [...], $: [row({ justify: "space-between", wrap: true })] }
+ * @example { div: [...], $: [row({ gap: 4, density: false })] }
  */
 declare function row(props?: {
     gap?: number;
     align?: FlexAlign;
     justify?: FlexJustify;
     wrap?: boolean;
+    density?: boolean;
 }): PartialElement;
 
 /**
@@ -1263,7 +1294,8 @@ declare function select(props?: {
  *   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`.
+ * @param props.open - Whether the popover is open. Accepts a value or reactive state (`ValueOrState<boolean>`, including `Computed`/`ReadableState`). Defaults to `false`. When the source is read-only, pass `onDismiss` so dismiss can close.
+ * @param props.onDismiss - Called when the popover requests close. Optional. Required to close when `open` is a read-only `Computed`/`ReadableState`.
  * @example { div: null, $: [selectBox({ content: { div: [...] }, options: [{ label: "A", value: "a" }] })] }
  */
 declare function selectBox(props: {
@@ -1277,6 +1309,7 @@ declare function selectBox(props: {
     content: DomphyElement;
     color?: ThemeColor;
     open?: ValueOrState<boolean>;
+    onDismiss?: () => void;
 }): PartialElement;
 
 /**
@@ -1523,7 +1556,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 and when `value` updates. Optional. Defaults to `false`.
+ * @param props.autoResize - When true, grows the textarea height to fit its content on input and when `value` updates, and remeasures when the host becomes visible (IntersectionObserver) and when its box size changes (ResizeObserver). Optional. Defaults to `false`.
  * @example { textarea: null, $: [textarea({ autoResize: true })] }
  */
 declare function textarea(props?: {
@@ -1603,16 +1636,28 @@ declare function toggleGroup(props?: {
 
 /**
  * A horizontal flex row with vertically centered items. Useful for headers,
- * toolbars, navigation bars, and action strips. A semantic alias of `row()`
- * at its default alignment — reach for `row()` directly for `justify`/`wrap`/
- * `align` beyond this shape.
+ * toolbars, navigation bars, and action strips. A semantic alias of `row()`;
+ * wrap/justify/align/density are forwarded so callers do not drop down to
+ * hand-rolled flex.
  *
- * @param props.gap - Spacing multiplier for gap between items (default 4 = 1em).
+ * @param props.gap - Spacing multiplier for gap between items (default 4).
+ *   Bounded-control mode (`density: true`, default): `themeSpacing(themeDensity(l) * gap)`.
+ *   Structural mode (`density: false`): bare `themeSpacing(gap)`.
+ * @param props.wrap - Allow items to wrap onto multiple lines. Defaults to `false`.
+ * @param props.justify - Main-axis distribution (`justifyContent`). Unset by default.
+ * @param props.align - Cross-axis alignment (`alignItems`). Defaults to `"center"` (row default).
+ * @param props.density - When true (default), gap is multiplied by theme density.
+ *   When false, gap is structural `themeSpacing(n)`.
  * @example { header: [...], $: [toolbar()] }
  * @example { nav: [...], $: [toolbar({ gap: 3 })] }
+ * @example { header: [...], $: [toolbar({ wrap: true, justify: "space-between" })] }
  */
 declare function toolbar(props?: {
     gap?: number;
+    wrap?: boolean;
+    justify?: FlexJustify;
+    align?: FlexAlign;
+    density?: boolean;
 }): PartialElement;
 /**
  * A flex spacer that expands to fill available space in a toolbar, pushing
@@ -1628,13 +1673,15 @@ declare function toolbarSpacer(): DomphyElement;
  * 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.open - Controlled open state (`ValueOrState<boolean>`), including `Computed`/`ReadableState`. When the source is read-only, pass `onDismiss` so leave/blur/Escape can close. Optional. Defaults to `false`.
+ * @param props.onDismiss - Called when the tooltip requests close. Optional. Required to close when `open` is a read-only `Computed`/`ReadableState`.
  * @param props.placement - Floating placement relative to the trigger. Optional, accepts a value or state (`Placement`). Defaults to `"top"`.
  * @param props.content - Tooltip text content. Optional, accepts a value or state (string only). Defaults to `"Tooltip Content"`.
  * @example { button: "Hover me", $: [tooltip({ content: "Help text" })] }
  */
 declare function tooltip(props?: {
     open?: ValueOrState<boolean>;
+    onDismiss?: () => void;
     placement?: ValueOrState<Placement$1>;
     content?: ValueOrState<string>;
 }): PartialElement;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { ValueOrState, PartialElement, DomphyElement, State, Listener } from '@domphy/core';
-import { ThemeColor } from '@domphy/theme';
+import { ThemeColor, ElementSize } from '@domphy/theme';
 import { Placement as Placement$1 } from '@domphy/floating';
 export { Placement } from '@domphy/floating';
 
@@ -213,7 +213,8 @@ declare function code(props?: {
  * @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.open - Whether the popover is open. Optional `ValueOrState<boolean>` (including `Computed`/`ReadableState`), default false. When the source is read-only, pass `onDismiss` so dismiss can close.
+ * @param props.onDismiss - Called when the popover requests close. Optional. Required to close when `open` is a read-only `Computed`/`ReadableState`.
  * @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 } })] }
  */
@@ -228,6 +229,7 @@ declare function combobox(props: {
     content: DomphyElement;
     color?: ThemeColor;
     open?: ValueOrState<boolean>;
+    onDismiss?: () => void;
     input?: DomphyElement;
 }): PartialElement;
 
@@ -368,7 +370,8 @@ declare function details(props?: {
  *
  * @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.
+ * @param props.open - Open state (`ValueOrState<boolean>`), including `Computed`/`ReadableState`. When the source is read-only, pass `onDismiss` so Escape/backdrop can close. Defaults to false.
+ * @param props.onDismiss - Called when Escape/backdrop/`requestClose` request close. Optional. Required to close when `open` is a read-only `Computed`/`ReadableState`.
  * @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" })] }
@@ -376,6 +379,7 @@ declare function details(props?: {
 declare function dialog(props?: {
     color?: ThemeColor;
     open?: ValueOrState<boolean>;
+    onDismiss?: () => void;
     labelledBy?: string;
     describedBy?: string;
 }): PartialElement;
@@ -412,7 +416,8 @@ type Placement = PhysicalPlacement | "start" | "end";
  *
  * @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.open - Open state (`ValueOrState<boolean>`), including `Computed`/`ReadableState`. When the source is read-only, pass `onDismiss` so Escape/backdrop can close. Defaults to false.
+ * @param props.onDismiss - Called when Escape/backdrop/`requestClose` request close. Optional. Required to close when `open` is a read-only `Computed`/`ReadableState`.
  * @param props.placement - Edge to anchor to. "left" | "right" | "top" | "bottom" | "start" | "end". Defaults to "end".
  * @param props.size - CSS length for the drawer's width (left/right/start/end) or height (top/bottom). Defaults to themeSpacing(80) for left/right, themeSpacing(64) for top/bottom.
  * @example { dialog: [...], $: [drawer({ open, placement: "start" })] }
@@ -420,6 +425,7 @@ type Placement = PhysicalPlacement | "start" | "end";
 declare function drawer(props?: {
     color?: ThemeColor;
     open?: ValueOrState<boolean>;
+    onDismiss?: () => void;
     placement?: Placement;
     size?: string;
 }): PartialElement;
@@ -517,20 +523,32 @@ declare function formGroup(props?: {
 }): PartialElement;
 
 type FlexAlign = "flex-start" | "center" | "flex-end" | "stretch" | "baseline";
+type FlexJustify = "flex-start" | "center" | "flex-end" | "space-between" | "space-around" | "space-evenly";
 /**
  * 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.gap - Spacing multiplier for gap between children (default 3).
+ *   Bounded-control mode (`density: true`, default): `themeSpacing(themeDensity(l) * gap)`
+ *   — at default density 1.5, gap 3 = 1.125em.
+ *   Structural/page-column mode (`density: false`): bare `themeSpacing(gap)` with no
+ *   density multiply — gap 3 = 0.75em, matching AGENTS.md "bare themeSpacing(n)".
  * @param props.align - Cross-axis alignment (`alignItems`). Unset by default (flex default, stretch).
+ * @param props.justify - Main-axis distribution (`justifyContent`). Unset by default (flex-start).
+ * @param props.density - When true (default), gap is multiplied by theme density
+ *   (bounded controls). When false, gap is structural `themeSpacing(n)` — use this
+ *   for page/form columns.
  * @example { div: [{ h3: "Title" }, { p: "Body" }], $: [stack()] }
  * @example { div: [...], $: [stack({ gap: 2, align: "center" })] }
+ * @example { div: [...], $: [stack({ gap: 3, density: false, justify: "space-between" })] }
  */
 declare function stack(props?: {
     gap?: number;
     align?: FlexAlign;
+    justify?: FlexJustify;
+    density?: boolean;
 }): PartialElement;
 
 /**
@@ -559,10 +577,13 @@ declare function grid(props?: {
  *
  * @hostTag h1
  * @param props.color - Theme color tone (`ValueOrState<ThemeColor>`) for the heading text. Defaults to "neutral".
+ * @param props.size - Optional `ElementSize` (`"inherit"` | `"increase-N"` | `"decrease-N"`, N ≤ 7). When set, font size is `themeSize(listener, size)` including `"inherit"` (no tag bump). When omitted, follows the host tag (`h1` increase-4 … `h6` decrease-1).
  * @example { h2: "Section title", $: [heading()] }
+ * @example { h3: "Panel title", $: [heading({ size: "inherit" })] }
  */
 declare function heading(props?: {
     color?: ValueOrState<ThemeColor>;
+    size?: ElementSize;
 }): PartialElement;
 
 /**
@@ -1051,7 +1072,8 @@ declare function paragraph(props?: {
  *
  * @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.open - Open state (`ValueOrState<boolean>`), including `Computed`/`ReadableState`. When the source is read-only, pass `onDismiss` so Escape/outside click can close. Defaults to `false`.
+ * @param props.onDismiss - Called when the panel requests close. Optional. Required to close when `open` is a read-only `Computed`/`ReadableState`.
  * @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" } })] }
@@ -1059,6 +1081,7 @@ declare function paragraph(props?: {
 declare function popover(props: {
     openOn?: "click" | "hover";
     open?: ValueOrState<boolean>;
+    onDismiss?: () => void;
     placement?: ValueOrState<Placement$1>;
     content: DomphyElement;
 }): PartialElement;
@@ -1164,7 +1187,6 @@ declare function ringProgress(props?: {
     thickness?: number;
 }): 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
  * default. The general-purpose primitive for icon+label rows, field rows,
@@ -1172,18 +1194,27 @@ type FlexJustify = "flex-start" | "center" | "flex-end" | "space-between" | "spa
  * center; gap: ...`. `toolbar()` is a semantic alias of this same shape for
  * headers/nav bars. Styles the host only; apply to any block element.
  *
- * @param props.gap - Spacing multiplier for gap between items (default 4 = 1em at density 1).
+ * @param props.gap - Spacing multiplier for gap between items (default 4).
+ *   Bounded-control mode (`density: true`, default): `themeSpacing(themeDensity(l) * gap)`
+ *   — at default density 1.5, gap 4 = 1.5em.
+ *   Structural/page-column mode (`density: false`): bare `themeSpacing(gap)` with no
+ *   density multiply — gap 4 = 1em, matching AGENTS.md "bare themeSpacing(n)".
  * @param props.align - Cross-axis alignment (`alignItems`). Defaults to `"center"`.
  * @param props.justify - Main-axis distribution (`justifyContent`). Unset by default (flex-start).
  * @param props.wrap - Allow items to wrap onto multiple lines. Defaults to `false`.
+ * @param props.density - When true (default), gap is multiplied by theme density
+ *   (bounded controls). When false, gap is structural `themeSpacing(n)` — use this
+ *   for page/form columns.
  * @example { div: [{ span: "Icon" }, { span: "Label" }], $: [row()] }
  * @example { div: [...], $: [row({ justify: "space-between", wrap: true })] }
+ * @example { div: [...], $: [row({ gap: 4, density: false })] }
  */
 declare function row(props?: {
     gap?: number;
     align?: FlexAlign;
     justify?: FlexJustify;
     wrap?: boolean;
+    density?: boolean;
 }): PartialElement;
 
 /**
@@ -1263,7 +1294,8 @@ declare function select(props?: {
  *   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`.
+ * @param props.open - Whether the popover is open. Accepts a value or reactive state (`ValueOrState<boolean>`, including `Computed`/`ReadableState`). Defaults to `false`. When the source is read-only, pass `onDismiss` so dismiss can close.
+ * @param props.onDismiss - Called when the popover requests close. Optional. Required to close when `open` is a read-only `Computed`/`ReadableState`.
  * @example { div: null, $: [selectBox({ content: { div: [...] }, options: [{ label: "A", value: "a" }] })] }
  */
 declare function selectBox(props: {
@@ -1277,6 +1309,7 @@ declare function selectBox(props: {
     content: DomphyElement;
     color?: ThemeColor;
     open?: ValueOrState<boolean>;
+    onDismiss?: () => void;
 }): PartialElement;
 
 /**
@@ -1523,7 +1556,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 and when `value` updates. Optional. Defaults to `false`.
+ * @param props.autoResize - When true, grows the textarea height to fit its content on input and when `value` updates, and remeasures when the host becomes visible (IntersectionObserver) and when its box size changes (ResizeObserver). Optional. Defaults to `false`.
  * @example { textarea: null, $: [textarea({ autoResize: true })] }
  */
 declare function textarea(props?: {
@@ -1603,16 +1636,28 @@ declare function toggleGroup(props?: {
 
 /**
  * A horizontal flex row with vertically centered items. Useful for headers,
- * toolbars, navigation bars, and action strips. A semantic alias of `row()`
- * at its default alignment — reach for `row()` directly for `justify`/`wrap`/
- * `align` beyond this shape.
+ * toolbars, navigation bars, and action strips. A semantic alias of `row()`;
+ * wrap/justify/align/density are forwarded so callers do not drop down to
+ * hand-rolled flex.
  *
- * @param props.gap - Spacing multiplier for gap between items (default 4 = 1em).
+ * @param props.gap - Spacing multiplier for gap between items (default 4).
+ *   Bounded-control mode (`density: true`, default): `themeSpacing(themeDensity(l) * gap)`.
+ *   Structural mode (`density: false`): bare `themeSpacing(gap)`.
+ * @param props.wrap - Allow items to wrap onto multiple lines. Defaults to `false`.
+ * @param props.justify - Main-axis distribution (`justifyContent`). Unset by default.
+ * @param props.align - Cross-axis alignment (`alignItems`). Defaults to `"center"` (row default).
+ * @param props.density - When true (default), gap is multiplied by theme density.
+ *   When false, gap is structural `themeSpacing(n)`.
  * @example { header: [...], $: [toolbar()] }
  * @example { nav: [...], $: [toolbar({ gap: 3 })] }
+ * @example { header: [...], $: [toolbar({ wrap: true, justify: "space-between" })] }
  */
 declare function toolbar(props?: {
     gap?: number;
+    wrap?: boolean;
+    justify?: FlexJustify;
+    align?: FlexAlign;
+    density?: boolean;
 }): PartialElement;
 /**
  * A flex spacer that expands to fill available space in a toolbar, pushing
@@ -1628,13 +1673,15 @@ declare function toolbarSpacer(): DomphyElement;
  * 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.open - Controlled open state (`ValueOrState<boolean>`), including `Computed`/`ReadableState`. When the source is read-only, pass `onDismiss` so leave/blur/Escape can close. Optional. Defaults to `false`.
+ * @param props.onDismiss - Called when the tooltip requests close. Optional. Required to close when `open` is a read-only `Computed`/`ReadableState`.
  * @param props.placement - Floating placement relative to the trigger. Optional, accepts a value or state (`Placement`). Defaults to `"top"`.
  * @param props.content - Tooltip text content. Optional, accepts a value or state (string only). Defaults to `"Tooltip Content"`.
  * @example { button: "Hover me", $: [tooltip({ content: "Help text" })] }
  */
 declare function tooltip(props?: {
     open?: ValueOrState<boolean>;
+    onDismiss?: () => void;
     placement?: ValueOrState<Placement$1>;
     content?: ValueOrState<string>;
 }): PartialElement;