@domphy/ui 0.18.22 → 0.20.0

package/dist/index.d.cts

@@ -111,16 +111,36 @@ declare function breadcrumbEllipsis(props?: {
     color?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
+/**
+ * The `fontSize` step for `button()`/`buttonGhost()`'s `size` prop. Padding stays
+ * per-component (button and buttonGhost start from different base paddings) so
+ * only the part that's genuinely identical — the font-size step — lives here.
+ */
+declare const BUTTON_SIZE_FONT: {
+    readonly small: "decrease-1";
+    readonly medium: "inherit";
+    readonly large: "increase-1";
+};
+type ButtonSize = keyof typeof BUTTON_SIZE_FONT;
+
+type ButtonVariant = "solid" | "outline" | "ghost";
 /**
  * A themed button control with density-aware padding/radius and hover, focus-visible,
  * `[disabled]`, and `[aria-busy=true]` states. Apply to a `<button>` element.
  *
  * @hostTag button
  * @param props.color - Button color tone. Optional `ValueOrState<ThemeColor>`, default "primary".
+ * @param props.variant - Visual style: `"outline"` (tinted background + outline, default,
+ *   backward compatible), `"solid"` (filled background, readable contrast text), or `"ghost"`
+ *   (no background/border — delegates to `buttonGhost()` so the two stay visually identical).
+ * @param props.size - Button size preset. Optional `"small" | "medium" | "large"`, defaults to `"medium"`.
  * @example { button: "Save", $: [button({ color: "primary" })] }
+ * @example { button: "Delete", $: [button({ color: "error", variant: "solid" })] }
  */
 declare function button(props?: {
     color?: ValueOrState<ThemeColor>;
+    variant?: ButtonVariant;
+    size?: ButtonSize;
 }): PartialElement;
 
 /**
@@ -130,11 +150,13 @@ declare function button(props?: {
  *
  * @hostTag button
  * @param props.color - Text color tone. Optional `ValueOrState<ThemeColor>`, defaults to `"neutral"`.
+ * @param props.size - Button size preset. Optional `"small" | "medium" | "large"`, defaults to `"medium"`.
  * @example { button: "×", $: [buttonGhost()] }
  * @example { button: { span: null, $: [icon({ name: "trash" })] }, $: [buttonGhost({ color: "error" })] }
  */
 declare function buttonGhost(props?: {
     color?: ValueOrState<ThemeColor>;
+    size?: ButtonSize;
 }): PartialElement;
 
 /**
@@ -923,6 +945,29 @@ declare function pagination(props: {
     accentColor?: ThemeColor;
 }): PartialElement;
 
+/**
+ * A padded section for side-panel/inspector UIs — density-aware padding on
+ * all sides, with an optional bottom divider for sections stacked one after
+ * another. A thin wrapper: it does not impose flex layout on its children —
+ * pair it with `stack()` or `row()` for that. No host-tag check; apply to
+ * any block element.
+ *
+ * @param props.padding - Spacing multiplier for padding on all sides (default 4 = 1em at density 1).
+ * @param props.divider - Adds a bottom border, for sections stacked one after another. Defaults to `false`.
+ * @param props.color - Theme color tone for the divider border. Defaults to `"neutral"`.
+ * @example { div: [{ h3: "Parameters" }, { p: "..." }], $: [panelSection()] }
+ * @example
+ * { div: [
+ *   { div: "Section A", $: [panelSection({ divider: true })] },
+ *   { div: "Section B", $: [panelSection()] },
+ * ], $: [stack({ gap: 0 })] }
+ */
+declare function panelSection(props?: {
+    padding?: number;
+    divider?: boolean;
+    color?: ValueOrState<ThemeColor>;
+}): PartialElement;
+
 /**
  * Themed paragraph primitive: comfortable line-height, reset margins and themed
  * text color. Apply to a `<p>` element.
@@ -1053,6 +1098,45 @@ 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
+ * default. The general-purpose primitive for icon+label rows, field rows,
+ * and button groups — instead of hand-rolling `display: flex; alignItems:
+ * 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.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`.
+ * @example { div: [{ span: "Icon" }, { span: "Label" }], $: [row()] }
+ * @example { div: [...], $: [row({ justify: "space-between", wrap: true })] }
+ */
+declare function row(props?: {
+    gap?: number;
+    align?: FlexAlign;
+    justify?: FlexJustify;
+    wrap?: boolean;
+}): PartialElement;
+
 /**
  * Applies thin, themed overlay scrollbars to any scrollable container.
  * Covers WebKit (Chrome/Safari/Edge) via `::-webkit-scrollbar` pseudo-elements
@@ -1071,7 +1155,7 @@ declare function scrollArea(props?: {
 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. */
+    /** Stable key. Defaults to the item's zero-based index. */
     key?: string;
 };
 /**
@@ -1477,7 +1561,9 @@ declare function toggleGroup(props?: {
 
 /**
  * A horizontal flex row with vertically centered items. Useful for headers,
- * toolbars, navigation bars, and action strips.
+ * 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.
  *
  * @param props.gap - Spacing multiplier for gap between items (default 4 = 1em).
  * @example { header: [...], $: [toolbar()] }
@@ -1537,4 +1623,4 @@ declare function unorderedList(props?: {
     color?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
-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 };
+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 };

package/dist/index.d.ts

@@ -111,16 +111,36 @@ declare function breadcrumbEllipsis(props?: {
     color?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
+/**
+ * The `fontSize` step for `button()`/`buttonGhost()`'s `size` prop. Padding stays
+ * per-component (button and buttonGhost start from different base paddings) so
+ * only the part that's genuinely identical — the font-size step — lives here.
+ */
+declare const BUTTON_SIZE_FONT: {
+    readonly small: "decrease-1";
+    readonly medium: "inherit";
+    readonly large: "increase-1";
+};
+type ButtonSize = keyof typeof BUTTON_SIZE_FONT;
+
+type ButtonVariant = "solid" | "outline" | "ghost";
 /**
  * A themed button control with density-aware padding/radius and hover, focus-visible,
  * `[disabled]`, and `[aria-busy=true]` states. Apply to a `<button>` element.
  *
  * @hostTag button
  * @param props.color - Button color tone. Optional `ValueOrState<ThemeColor>`, default "primary".
+ * @param props.variant - Visual style: `"outline"` (tinted background + outline, default,
+ *   backward compatible), `"solid"` (filled background, readable contrast text), or `"ghost"`
+ *   (no background/border — delegates to `buttonGhost()` so the two stay visually identical).
+ * @param props.size - Button size preset. Optional `"small" | "medium" | "large"`, defaults to `"medium"`.
  * @example { button: "Save", $: [button({ color: "primary" })] }
+ * @example { button: "Delete", $: [button({ color: "error", variant: "solid" })] }
  */
 declare function button(props?: {
     color?: ValueOrState<ThemeColor>;
+    variant?: ButtonVariant;
+    size?: ButtonSize;
 }): PartialElement;
 
 /**
@@ -130,11 +150,13 @@ declare function button(props?: {
  *
  * @hostTag button
  * @param props.color - Text color tone. Optional `ValueOrState<ThemeColor>`, defaults to `"neutral"`.
+ * @param props.size - Button size preset. Optional `"small" | "medium" | "large"`, defaults to `"medium"`.
  * @example { button: "×", $: [buttonGhost()] }
  * @example { button: { span: null, $: [icon({ name: "trash" })] }, $: [buttonGhost({ color: "error" })] }
  */
 declare function buttonGhost(props?: {
     color?: ValueOrState<ThemeColor>;
+    size?: ButtonSize;
 }): PartialElement;
 
 /**
@@ -923,6 +945,29 @@ declare function pagination(props: {
     accentColor?: ThemeColor;
 }): PartialElement;
 
+/**
+ * A padded section for side-panel/inspector UIs — density-aware padding on
+ * all sides, with an optional bottom divider for sections stacked one after
+ * another. A thin wrapper: it does not impose flex layout on its children —
+ * pair it with `stack()` or `row()` for that. No host-tag check; apply to
+ * any block element.
+ *
+ * @param props.padding - Spacing multiplier for padding on all sides (default 4 = 1em at density 1).
+ * @param props.divider - Adds a bottom border, for sections stacked one after another. Defaults to `false`.
+ * @param props.color - Theme color tone for the divider border. Defaults to `"neutral"`.
+ * @example { div: [{ h3: "Parameters" }, { p: "..." }], $: [panelSection()] }
+ * @example
+ * { div: [
+ *   { div: "Section A", $: [panelSection({ divider: true })] },
+ *   { div: "Section B", $: [panelSection()] },
+ * ], $: [stack({ gap: 0 })] }
+ */
+declare function panelSection(props?: {
+    padding?: number;
+    divider?: boolean;
+    color?: ValueOrState<ThemeColor>;
+}): PartialElement;
+
 /**
  * Themed paragraph primitive: comfortable line-height, reset margins and themed
  * text color. Apply to a `<p>` element.
@@ -1053,6 +1098,45 @@ 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
+ * default. The general-purpose primitive for icon+label rows, field rows,
+ * and button groups — instead of hand-rolling `display: flex; alignItems:
+ * 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.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`.
+ * @example { div: [{ span: "Icon" }, { span: "Label" }], $: [row()] }
+ * @example { div: [...], $: [row({ justify: "space-between", wrap: true })] }
+ */
+declare function row(props?: {
+    gap?: number;
+    align?: FlexAlign;
+    justify?: FlexJustify;
+    wrap?: boolean;
+}): PartialElement;
+
 /**
  * Applies thin, themed overlay scrollbars to any scrollable container.
  * Covers WebKit (Chrome/Safari/Edge) via `::-webkit-scrollbar` pseudo-elements
@@ -1071,7 +1155,7 @@ declare function scrollArea(props?: {
 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. */
+    /** Stable key. Defaults to the item's zero-based index. */
     key?: string;
 };
 /**
@@ -1477,7 +1561,9 @@ declare function toggleGroup(props?: {
 
 /**
  * A horizontal flex row with vertically centered items. Useful for headers,
- * toolbars, navigation bars, and action strips.
+ * 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.
  *
  * @param props.gap - Spacing multiplier for gap between items (default 4 = 1em).
  * @example { header: [...], $: [toolbar()] }
@@ -1537,4 +1623,4 @@ declare function unorderedList(props?: {
     color?: ValueOrState<ThemeColor>;
 }): PartialElement;
 
-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 };
+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 };