@domphy/ui 0.18.14 → 0.18.16

package/dist/index.d.cts

@@ -808,39 +808,39 @@ declare function mark(props?: {
     accentColor?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
-/**
- * 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`.
+/** One item inside a menu. */
+type MenuItem = {
+    /** Button label — plain string (auto-wrapped) or any DomphyElement (e.g. icon + text). */
+    label: string | DomphyElement;
+    /** Stable key. Defaults to the item's zero-based index. */
+    key?: string | number;
+    /** Called when the item is clicked. */
+    onClick?: () => void;
+};
+/**
+ * All-in-one vertical menu. Generates `<button>` `[role=menuitem]` elements
+ * from the `items` array with keyboard navigation (Arrow/Home/End/Enter/Space).
+ * Apply to any wrapper element (`div`, `ul`, …).
+ *
+ * @param props.items - Item definitions `{ label, key?, onClick? }`. Pass `[]`
+ * to keep the wrapper's own children (escape hatch for fully custom rows —
+ * only the menu container styling and `role="menu"` semantics apply then).
+ * @param props.activeKey - Currently selected key (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 })] }
+ * @param props.accentColor - Accent color for the active/focus item. Defaults to `"primary"`.
+ * @example
+ * { div: null, $: [menu({ items: [
+ *   { label: "Profile",  key: "profile",  onClick: () => navigate("/profile")  },
+ *   { label: "Settings", key: "settings", onClick: () => navigate("/settings") },
+ * ] })] }
  */
 declare function menu(props?: {
-    activeKey?: ValueOrState<number | string>;
+    items: MenuItem[];
+    activeKey?: ValueOrState<number | string | null>;
     selectable?: boolean;
     color?: ThemeColor;
-}): PartialElement;
-
-/**
- * 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;
 
 /**
@@ -1067,31 +1067,33 @@ declare function scrollArea(props?: {
     color?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
+/** One item inside a segmented control. */
+type SegmentedItem = {
+    /** Button label — plain string (auto-wrapped) or any DomphyElement. */
+    label: string | DomphyElement;
+    /** Stable key. Defaults to the item's zero-based index as a string. */
+    key?: string;
+};
 /**
- * Container patch that establishes a `segmented` context for single-select navigation.
- * Style: inline pill-shaped control with muted background. Use with `segmentedItem` patches on child `<button>` elements.
+ * All-in-one single-select segmented control. Generates `<button>` option
+ * elements from the `items` array. Apply to any wrapper element.
  *
- * @param props.value - Initially selected item key. Accepts a value or state. Defaults to `""`.
+ * @param props.items - Item definitions `{ label, key? }`.
+ * @param props.value - Initially selected key (value or State). Defaults to the first item's key.
  * @param props.color - Theme color for the control background. Defaults to `"neutral"`.
- * @example { div: null, $: [segmented({ value: "month" })] }
+ * @param props.accentColor - Theme color for the selected item. Defaults to `"primary"`.
+ * @example
+ * { div: null, $: [segmented({ items: [
+ *   { label: "Day",   key: "day"   },
+ *   { label: "Month", key: "month" },
+ *   { label: "Year",  key: "year"  },
+ * ] })] }
  */
 declare function segmented(props?: {
+    items: SegmentedItem[];
     value?: ValueOrState<string>;
     color?: ThemeColor;
-}): PartialElement;
-
-/**
- * Styles and wires a single option inside a `segmented` control on the host `<button>`.
- * Sets `aria-checked` and handles click-to-select against the parent `segmented` context.
- *
- * @hostTag button
- * @param props.color - Theme color for resting state. Defaults to `"neutral"`.
- * @param props.accentColor - Theme color for selected state. Defaults to `"primary"`.
- * @example { button: "Month", $: [segmentedItem()] }
- */
-declare function segmentedItem(props?: {
-    color?: ValueOrState<ThemeColor>;
-    accentColor?: ValueOrState<ThemeColor>;
+    accentColor?: ThemeColor;
 }): PartialElement;
 
 /**
@@ -1241,7 +1243,11 @@ declare function splitter(props?: {
 /**
  * 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.
+ * 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()] }
  */
@@ -1257,26 +1263,31 @@ declare function splitterPanel(): PartialElement;
  */
 declare function splitterHandle(): PartialElement;
 
+/** One step entry. */
+type StepItem = {
+    /** Step label — plain string (auto-wrapped) or any DomphyElement. */
+    label: string | DomphyElement;
+    /** Stable key. Defaults to the item's zero-based index. */
+    key?: string | number;
+};
 /**
- * Styles a single step inside a `steps` container. Sets `data-status`
- * (`"pending"` | `"active"` | `"done"`) and `aria-current="step"` on the host element
- * based on the parent `steps` context. The element's content is the step label.
- *
- * @example { li: "Shipping", $: [stepItem()] }
- */
-declare function stepItem(): PartialElement;
-
-/**
- * Container patch for a step-progress indicator. Establishes `steps` context
- * with a reactive `current` index. Use with `stepItem` patches on child elements.
+ * All-in-one step-progress indicator. Generates `<li>` step elements from the
+ * `items` array. Apply to an `<ol>` or `<ul>` element.
  *
- * @param props.current - Zero-based index of the active step. Accepts a value or state. Defaults to `0`.
+ * @param props.items - Step definitions `{ label, key? }`.
+ * @param props.current - Zero-based index of the active step (value or State). Defaults to `0`.
  * @param props.direction - `"horizontal"` (default) or `"vertical"` layout.
  * @param props.color - Theme color for pending/track elements. Defaults to `"neutral"`.
  * @param props.accentColor - Theme color for active/completed elements. Defaults to `"primary"`.
- * @example { ol: null, $: [steps({ current: 1 })] }
+ * @example
+ * { ol: null, $: [steps({ current: 1, items: [
+ *   { label: "Cart" },
+ *   { label: "Shipping" },
+ *   { label: "Payment" },
+ * ] })] }
  */
 declare function steps(props?: {
+    items: StepItem[];
     current?: ValueOrState<number>;
     direction?: "horizontal" | "vertical";
     color?: ThemeColor;
@@ -1318,22 +1329,6 @@ declare function superscript(props?: {
     color?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
-/**
- * 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;
-
 /**
  * Styles a data table (header/body/footer cells, caption, row hover, borders)
  * on the host `<table>` element.
@@ -1346,26 +1341,38 @@ declare function table(props?: {
     color?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
+/** One tab entry: a trigger label and its panel content. */
+type TabItem = {
+    /** Tab button label — a plain string (auto-wrapped in span) or any DomphyElement. */
+    label: string | DomphyElement;
+    /** Panel content rendered when this tab is active. */
+    content: DomphyElement;
+    /** Stable identity key. Defaults to the item's zero-based index. */
+    key?: string | number;
+};
 /**
- * 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.
+ * All-in-one tabs patch. Generates a `[role=tablist]` button row and
+ * `[role=tabpanel]` panels from the `items` array. Apply to any wrapper
+ * element (`div`, `section`, …). No companion `tab()` / `tabPanel()` needed.
  *
- * @hostTag div
- * @example { div: "Panel content", $: [tabPanel()] }
- */
-declare function tabPanel(): PartialElement;
-
-/**
- * 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.
+ * To control the active tab programmatically, pass an external `State` as
+ * `activeKey` and call `.set()` on it from outside.
  *
- * @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 })] }
+ * @param props.items - Tab definitions `{ label, content, key? }`.
+ * @param props.activeKey - Initially active key (value or State). Defaults to the first item's key.
+ * @param props.accentColor - Theme color for the active underline indicator. Defaults to `"primary"`.
+ * @param props.color - Theme color for the resting underline. Defaults to `"neutral"`.
+ * @example
+ * { div: null, $: [tabs({ items: [
+ *   { label: "Overview", content: { p: "Overview content" } },
+ *   { label: "API",      content: { p: "API content"      } },
+ * ] })] }
  */
 declare function tabs(props?: {
-    activeKey?: ValueOrState<number | string>;
+    items: TabItem[];
+    activeKey?: ValueOrState<string | number>;
+    accentColor?: ThemeColor;
+    color?: ThemeColor;
 }): PartialElement;
 
 /**
@@ -1438,37 +1445,34 @@ declare function toast(props?: {
     color?: ThemeColor;
 }): PartialElement;
 
+/** One item inside a toggle group. */
+type ToggleItem = {
+    /** Button label — plain string (auto-wrapped) or any DomphyElement. */
+    label: string | DomphyElement;
+    /** Stable key. Defaults to the item's zero-based index as a string. */
+    key?: string;
+};
 /**
- * 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.
+ * All-in-one toggle group — single or multi-select button group. Generates
+ * `<button>` toggle elements from the `items` array. Apply to any wrapper element.
  *
- * @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;
-
-/**
- * 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 })] }
+ * @param props.items - Item definitions `{ label, key? }`.
+ * @param props.value - Selected key(s) (value or State). Defaults to `[]` (multiple) or `""` (single).
+ * @param props.multiple - Allow multiple items selected at once. Defaults to `false`.
+ * @param props.color - Theme color for the group background/border. Defaults to `"neutral"`.
+ * @param props.accentColor - Theme color for the pressed state. Defaults to `"primary"`.
+ * @example
+ * { div: null, $: [toggleGroup({ multiple: true, items: [
+ *   { label: "Bold",   key: "bold"   },
+ *   { label: "Italic", key: "italic" },
+ * ] })] }
  */
 declare function toggleGroup(props?: {
+    items: ToggleItem[];
     value?: ValueOrState<string | string[]>;
     multiple?: boolean;
     color?: ThemeColor;
+    accentColor?: ThemeColor;
 }): PartialElement;
 
 /**
@@ -1533,4 +1537,4 @@ declare function unorderedList(props?: {
     color?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
-export { type DatePickerProps, type DatePickerValue, type MotionKeyframe, type MotionProps, 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, menuItem, motion, orderedList, pagination, paragraph, popover, popoverArrow, preformated, progress, rating, ringProgress, scrollArea, segmented, segmentedItem, select, selectBox, selectItem, selectList, skeleton, small, spinner, splitter, splitterHandle, splitterPanel, stepItem, steps, strong, subscript, superscript, tab, tabPanel, table, tabs, tag, textarea, timeline, timelineItem, toast, toggle, toggleGroup, toolbar, toolbarSpacer, tooltip, transitionGroup, unorderedList };
+export { type DatePickerProps, type DatePickerValue, 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, paragraph, popover, popoverArrow, preformated, progress, rating, ringProgress, scrollArea, segmented, select, selectBox, selectItem, selectList, skeleton, small, spinner, splitter, splitterHandle, splitterPanel, steps, strong, subscript, superscript, table, tabs, tag, textarea, timeline, timelineItem, toast, toggleGroup, toolbar, toolbarSpacer, tooltip, transitionGroup, unorderedList };

package/dist/index.d.ts

@@ -808,39 +808,39 @@ declare function mark(props?: {
     accentColor?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
-/**
- * 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`.
+/** One item inside a menu. */
+type MenuItem = {
+    /** Button label — plain string (auto-wrapped) or any DomphyElement (e.g. icon + text). */
+    label: string | DomphyElement;
+    /** Stable key. Defaults to the item's zero-based index. */
+    key?: string | number;
+    /** Called when the item is clicked. */
+    onClick?: () => void;
+};
+/**
+ * All-in-one vertical menu. Generates `<button>` `[role=menuitem]` elements
+ * from the `items` array with keyboard navigation (Arrow/Home/End/Enter/Space).
+ * Apply to any wrapper element (`div`, `ul`, …).
+ *
+ * @param props.items - Item definitions `{ label, key?, onClick? }`. Pass `[]`
+ * to keep the wrapper's own children (escape hatch for fully custom rows —
+ * only the menu container styling and `role="menu"` semantics apply then).
+ * @param props.activeKey - Currently selected key (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 })] }
+ * @param props.accentColor - Accent color for the active/focus item. Defaults to `"primary"`.
+ * @example
+ * { div: null, $: [menu({ items: [
+ *   { label: "Profile",  key: "profile",  onClick: () => navigate("/profile")  },
+ *   { label: "Settings", key: "settings", onClick: () => navigate("/settings") },
+ * ] })] }
  */
 declare function menu(props?: {
-    activeKey?: ValueOrState<number | string>;
+    items: MenuItem[];
+    activeKey?: ValueOrState<number | string | null>;
     selectable?: boolean;
     color?: ThemeColor;
-}): PartialElement;
-
-/**
- * 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;
 
 /**
@@ -1067,31 +1067,33 @@ declare function scrollArea(props?: {
     color?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
+/** One item inside a segmented control. */
+type SegmentedItem = {
+    /** Button label — plain string (auto-wrapped) or any DomphyElement. */
+    label: string | DomphyElement;
+    /** Stable key. Defaults to the item's zero-based index as a string. */
+    key?: string;
+};
 /**
- * Container patch that establishes a `segmented` context for single-select navigation.
- * Style: inline pill-shaped control with muted background. Use with `segmentedItem` patches on child `<button>` elements.
+ * All-in-one single-select segmented control. Generates `<button>` option
+ * elements from the `items` array. Apply to any wrapper element.
  *
- * @param props.value - Initially selected item key. Accepts a value or state. Defaults to `""`.
+ * @param props.items - Item definitions `{ label, key? }`.
+ * @param props.value - Initially selected key (value or State). Defaults to the first item's key.
  * @param props.color - Theme color for the control background. Defaults to `"neutral"`.
- * @example { div: null, $: [segmented({ value: "month" })] }
+ * @param props.accentColor - Theme color for the selected item. Defaults to `"primary"`.
+ * @example
+ * { div: null, $: [segmented({ items: [
+ *   { label: "Day",   key: "day"   },
+ *   { label: "Month", key: "month" },
+ *   { label: "Year",  key: "year"  },
+ * ] })] }
  */
 declare function segmented(props?: {
+    items: SegmentedItem[];
     value?: ValueOrState<string>;
     color?: ThemeColor;
-}): PartialElement;
-
-/**
- * Styles and wires a single option inside a `segmented` control on the host `<button>`.
- * Sets `aria-checked` and handles click-to-select against the parent `segmented` context.
- *
- * @hostTag button
- * @param props.color - Theme color for resting state. Defaults to `"neutral"`.
- * @param props.accentColor - Theme color for selected state. Defaults to `"primary"`.
- * @example { button: "Month", $: [segmentedItem()] }
- */
-declare function segmentedItem(props?: {
-    color?: ValueOrState<ThemeColor>;
-    accentColor?: ValueOrState<ThemeColor>;
+    accentColor?: ThemeColor;
 }): PartialElement;
 
 /**
@@ -1241,7 +1243,11 @@ declare function splitter(props?: {
 /**
  * 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.
+ * 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()] }
  */
@@ -1257,26 +1263,31 @@ declare function splitterPanel(): PartialElement;
  */
 declare function splitterHandle(): PartialElement;
 
+/** One step entry. */
+type StepItem = {
+    /** Step label — plain string (auto-wrapped) or any DomphyElement. */
+    label: string | DomphyElement;
+    /** Stable key. Defaults to the item's zero-based index. */
+    key?: string | number;
+};
 /**
- * Styles a single step inside a `steps` container. Sets `data-status`
- * (`"pending"` | `"active"` | `"done"`) and `aria-current="step"` on the host element
- * based on the parent `steps` context. The element's content is the step label.
- *
- * @example { li: "Shipping", $: [stepItem()] }
- */
-declare function stepItem(): PartialElement;
-
-/**
- * Container patch for a step-progress indicator. Establishes `steps` context
- * with a reactive `current` index. Use with `stepItem` patches on child elements.
+ * All-in-one step-progress indicator. Generates `<li>` step elements from the
+ * `items` array. Apply to an `<ol>` or `<ul>` element.
  *
- * @param props.current - Zero-based index of the active step. Accepts a value or state. Defaults to `0`.
+ * @param props.items - Step definitions `{ label, key? }`.
+ * @param props.current - Zero-based index of the active step (value or State). Defaults to `0`.
  * @param props.direction - `"horizontal"` (default) or `"vertical"` layout.
  * @param props.color - Theme color for pending/track elements. Defaults to `"neutral"`.
  * @param props.accentColor - Theme color for active/completed elements. Defaults to `"primary"`.
- * @example { ol: null, $: [steps({ current: 1 })] }
+ * @example
+ * { ol: null, $: [steps({ current: 1, items: [
+ *   { label: "Cart" },
+ *   { label: "Shipping" },
+ *   { label: "Payment" },
+ * ] })] }
  */
 declare function steps(props?: {
+    items: StepItem[];
     current?: ValueOrState<number>;
     direction?: "horizontal" | "vertical";
     color?: ThemeColor;
@@ -1318,22 +1329,6 @@ declare function superscript(props?: {
     color?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
-/**
- * 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;
-
 /**
  * Styles a data table (header/body/footer cells, caption, row hover, borders)
  * on the host `<table>` element.
@@ -1346,26 +1341,38 @@ declare function table(props?: {
     color?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
+/** One tab entry: a trigger label and its panel content. */
+type TabItem = {
+    /** Tab button label — a plain string (auto-wrapped in span) or any DomphyElement. */
+    label: string | DomphyElement;
+    /** Panel content rendered when this tab is active. */
+    content: DomphyElement;
+    /** Stable identity key. Defaults to the item's zero-based index. */
+    key?: string | number;
+};
 /**
- * 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.
+ * All-in-one tabs patch. Generates a `[role=tablist]` button row and
+ * `[role=tabpanel]` panels from the `items` array. Apply to any wrapper
+ * element (`div`, `section`, …). No companion `tab()` / `tabPanel()` needed.
  *
- * @hostTag div
- * @example { div: "Panel content", $: [tabPanel()] }
- */
-declare function tabPanel(): PartialElement;
-
-/**
- * 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.
+ * To control the active tab programmatically, pass an external `State` as
+ * `activeKey` and call `.set()` on it from outside.
  *
- * @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 })] }
+ * @param props.items - Tab definitions `{ label, content, key? }`.
+ * @param props.activeKey - Initially active key (value or State). Defaults to the first item's key.
+ * @param props.accentColor - Theme color for the active underline indicator. Defaults to `"primary"`.
+ * @param props.color - Theme color for the resting underline. Defaults to `"neutral"`.
+ * @example
+ * { div: null, $: [tabs({ items: [
+ *   { label: "Overview", content: { p: "Overview content" } },
+ *   { label: "API",      content: { p: "API content"      } },
+ * ] })] }
  */
 declare function tabs(props?: {
-    activeKey?: ValueOrState<number | string>;
+    items: TabItem[];
+    activeKey?: ValueOrState<string | number>;
+    accentColor?: ThemeColor;
+    color?: ThemeColor;
 }): PartialElement;
 
 /**
@@ -1438,37 +1445,34 @@ declare function toast(props?: {
     color?: ThemeColor;
 }): PartialElement;
 
+/** One item inside a toggle group. */
+type ToggleItem = {
+    /** Button label — plain string (auto-wrapped) or any DomphyElement. */
+    label: string | DomphyElement;
+    /** Stable key. Defaults to the item's zero-based index as a string. */
+    key?: string;
+};
 /**
- * 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.
+ * All-in-one toggle group — single or multi-select button group. Generates
+ * `<button>` toggle elements from the `items` array. Apply to any wrapper element.
  *
- * @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;
-
-/**
- * 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 })] }
+ * @param props.items - Item definitions `{ label, key? }`.
+ * @param props.value - Selected key(s) (value or State). Defaults to `[]` (multiple) or `""` (single).
+ * @param props.multiple - Allow multiple items selected at once. Defaults to `false`.
+ * @param props.color - Theme color for the group background/border. Defaults to `"neutral"`.
+ * @param props.accentColor - Theme color for the pressed state. Defaults to `"primary"`.
+ * @example
+ * { div: null, $: [toggleGroup({ multiple: true, items: [
+ *   { label: "Bold",   key: "bold"   },
+ *   { label: "Italic", key: "italic" },
+ * ] })] }
  */
 declare function toggleGroup(props?: {
+    items: ToggleItem[];
     value?: ValueOrState<string | string[]>;
     multiple?: boolean;
     color?: ThemeColor;
+    accentColor?: ThemeColor;
 }): PartialElement;
 
 /**
@@ -1533,4 +1537,4 @@ declare function unorderedList(props?: {
     color?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
-export { type DatePickerProps, type DatePickerValue, type MotionKeyframe, type MotionProps, 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, menuItem, motion, orderedList, pagination, paragraph, popover, popoverArrow, preformated, progress, rating, ringProgress, scrollArea, segmented, segmentedItem, select, selectBox, selectItem, selectList, skeleton, small, spinner, splitter, splitterHandle, splitterPanel, stepItem, steps, strong, subscript, superscript, tab, tabPanel, table, tabs, tag, textarea, timeline, timelineItem, toast, toggle, toggleGroup, toolbar, toolbarSpacer, tooltip, transitionGroup, unorderedList };
+export { type DatePickerProps, type DatePickerValue, 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, paragraph, popover, popoverArrow, preformated, progress, rating, ringProgress, scrollArea, segmented, select, selectBox, selectItem, selectList, skeleton, small, spinner, splitter, splitterHandle, splitterPanel, steps, strong, subscript, superscript, table, tabs, tag, textarea, timeline, timelineItem, toast, toggleGroup, toolbar, toolbarSpacer, tooltip, transitionGroup, unorderedList };