@kb.ui/react 0.11.0 → 0.12.1

package/README.md

@@ -27,6 +27,9 @@ The React adapter provides the components, styles and CSS variables together. In
 
 ## Start here
 
+- [Components and recipes](https://github.com/KhallilB/kbui/blob/main/docs/guides/components-and-recipes.md): importing package APIs and copying application-owned source.
+- [Browse recipes](https://kbui.kcb.pro/recipes/): live compositions and complete source files.
+
 - [Install and configure kbui](https://github.com/KhallilB/kbui/blob/main/docs/guides/using-kbui.md): package setup, themes, and troubleshooting.
 - [Browse live components](https://kbui.kcb.pro/components/): interactive states, code, and API tables.
 - [Accessibility implementation and verification](https://github.com/KhallilB/kbui/blob/main/docs/guides/accessibility.md): requirements, caller responsibilities, manual checks, and evidence limits.
@@ -37,18 +40,18 @@ The React adapter provides the components, styles and CSS variables together. In
 
 | Task | Start here |
 |---|---|
-| Run an action or navigate | [Button](docs/components/Button.md) for actions; [Link](docs/components/Link.md) for destinations |
-| Collect choices | [Checkbox](docs/components/Checkbox.md) for independent choices; [RadioGroup](docs/components/RadioGroup.md) for one visible choice; [Select](docs/components/Select.md) for a dropdown; [Switch](docs/components/Switch.md) for an immediate setting |
-| Collect text, quantities, or files | [Input](docs/components/Input.md), [Textarea](docs/components/Textarea.md), [NumberField](docs/components/NumberField.md), or [FileInput](docs/components/FileInput.md) |
-| Reveal details or supporting controls | [Disclosure](docs/components/Disclosure.md), [Accordion](docs/components/Accordion.md), or [Popover](docs/components/Popover.md); [drawer and confirmation patterns](https://github.com/KhallilB/kbui/blob/main/docs/guides/forms-and-overlays.md#drawer-pattern) compose Dialog |
-| Arrange a responsive page | [Container](docs/components/Container.md) for the page boundary; [Inline](docs/components/Inline.md) for rows; [Grid](docs/components/Grid.md) for collections; [Split](docs/components/Split.md) for two columns |
-| Explain state, waiting, or completion | [Spinner](docs/components/Spinner.md) for indeterminate waits; [Skeleton](docs/components/Skeleton.md) for loading placeholders; [Progress](docs/components/Progress.md) for completion; [EmptyState](docs/components/EmptyState.md) for missing content; [Status](docs/components/Status.md) for changing state; [Toast](docs/components/Toast.md) for transient notifications; [Badge](docs/components/Badge.md) for metadata; [Callout](docs/components/Callout.md) for a fuller message |
-| Compare records or scan details | [Table](docs/components/Table.md), [DescriptionList](docs/components/DescriptionList.md), [CollectionList](docs/components/CollectionList.md) and [CollectionRow](docs/components/CollectionRow.md) |
-| Build readable content | [Heading](docs/components/Heading.md) and [Text](docs/components/Text.md) |
+| Run an action or navigate | [`Button`](docs/components/Button.md) for actions; [`ConfirmAction`](docs/components/ConfirmAction.md) for destructive actions; [`Link`](docs/components/Link.md) for destinations |
+| Collect choices | [`Checkbox`](docs/components/Checkbox.md) for independent choices; [`RadioGroup`](docs/components/RadioGroup.md) for one visible choice; [`Select`](docs/components/Select.md) for a dropdown; [`Switch`](docs/components/Switch.md) for an immediate setting |
+| Collect text, quantities, or files | [`Input`](docs/components/Input.md), [`Textarea`](docs/components/Textarea.md), [`NumberField`](docs/components/NumberField.md), or [`FileInput`](docs/components/FileInput.md) |
+| Reveal details or supporting controls | [`Disclosure`](docs/components/Disclosure.md), [`Accordion`](docs/components/Accordion.md), or [`Popover`](docs/components/Popover.md); [drawer and confirmation patterns](https://github.com/KhallilB/kbui/blob/main/docs/guides/forms-and-overlays.md#drawer-pattern) compose `Dialog` |
+| Arrange a responsive page | [`Container`](docs/components/Container.md) for the page boundary; [`PageHeader`](docs/components/PageHeader.md) for the title and page actions; [`StatsRow`](docs/components/StatsRow.md) for a row of key metrics; [`Dashboard`](docs/components/Dashboard.md) for an overview page with metrics and panels; [`Inline`](docs/components/Inline.md) for rows; [`Stack`](docs/components/Stack.md) for vertical flow; [`Grid`](docs/components/Grid.md) for collections; [`Split`](docs/components/Split.md) for two columns; [`SupportingPane`](docs/components/SupportingPane.md) for a main task with an aside such as an order summary |
+| Explain state, waiting, or completion | [`Spinner`](docs/components/Spinner.md) for indeterminate waits; [`Skeleton`](docs/components/Skeleton.md) for loading placeholders; [`Progress`](docs/components/Progress.md) for completion; [`EmptyState`](docs/components/EmptyState.md) for missing content; [`Status`](docs/components/Status.md) for changing state; [`Toast`](docs/components/Toast.md) for transient notifications; [`Badge`](docs/components/Badge.md) for metadata; [`Callout`](docs/components/Callout.md) for a fuller message |
+| Compare records or scan details | [`Table`](docs/components/Table.md), [`DescriptionList`](docs/components/DescriptionList.md), [`CollectionList`](docs/components/CollectionList.md) and [`CollectionRow`](docs/components/CollectionRow.md) |
+| Build readable content | [`Heading`](docs/components/Heading.md) and [`Text`](docs/components/Text.md) |
 
 Start with the complete Usage example on a component page. Its More examples section links to focused, working Storybook states; Related components explains nearby alternatives. Use the live Docs page for component-specific keyboard, focus, and labeling guidance. Check those contracts with your app’s actual content and flows.
 
-For searchable choices, compare [Combobox](docs/components/Combobox.md) and [MultiSelect](docs/components/MultiSelect.md). For complete forms, start with [Fieldset](docs/components/Fieldset.md), [FormActions](docs/components/FormActions.md), and [ErrorSummary](docs/components/ErrorSummary.md).
+For searchable choices, compare [`Combobox`](docs/components/Combobox.md) and [`MultiSelect`](docs/components/MultiSelect.md). For complete forms, start with [`Form`](docs/components/Form.md) or [`Settings`](docs/components/Settings.md), group fields with [`FormSection`](docs/components/FormSection.md), and recover with [`ErrorSummary`](docs/components/ErrorSummary.md).
 
 ## Components
 
@@ -58,100 +61,110 @@ Choose by task. Each page contains a complete usage example, canonical API detai
 
 | Component | Use for |
 |---|---|
-| <a id="avatar"></a>[Avatar](docs/components/Avatar.md) | Recognizable people and organizations with photo/initials fallback. |
-| <a id="image"></a>[Image](docs/components/Image.md) | Stable image sizing, crops, containment and failure states. |
-| <a id="thumbnail"></a>[Thumbnail](docs/components/Thumbnail.md) | Captioned products, attachments and gallery previews. |
+| <a id="avatar"></a>[`Avatar`](docs/components/Avatar.md) | Recognizable people and organizations with photo/initials fallback. |
+| <a id="image"></a>[`Image`](docs/components/Image.md) | Stable image sizing, crops, containment and failure states. |
+| <a id="thumbnail"></a>[`Thumbnail`](docs/components/Thumbnail.md) | Captioned products, attachments and gallery previews. |
 
-See [Media and identity](../../docs/guides/media-and-identity.md) for responsive sources, retry and gallery recipes. These components are implemented locally and unreleased.
+See [Media and identity](../../docs/guides/media-and-identity.md) for responsive sources and retry, and [`Gallery`](docs/components/Gallery.md) for catalog pages.
 ### Collections
 
 | Component | Use for |
 |---|---|
-| [Collection](docs/components/Collection.md) | Sort, filter, select and paginate records; includes useCollection, Collection.Pagination and Collection.BulkActions. |
+| [`Collection`](docs/components/Collection.md) | Sort, filter, select and paginate records; includes `useCollection`, `Collection.Pagination` and `Collection.BulkActions`. |
 
 ### Navigation
 
 | Component | Use it to |
 | --- | --- |
-| <a id="tabs"></a>[Tabs](docs/components/Tabs.md) | Switch between peer panels with keyboard navigation. |
+| <a id="tabs"></a>[`Tabs`](docs/components/Tabs.md) | Switch between peer panels with keyboard navigation. |
 
 ### Actions
 
 | Component | Use for |
 |---|---|
-| <a id="copyabletext"></a>[CopyableText](docs/components/CopyableText.md) | Copy identifiers and references with feedback and recovery. |
-| <a id="button"></a>[Button](docs/components/Button.md) | Trigger an action or link to another page. |
-| <a id="popover"></a>[Popover](docs/components/Popover.md) | Reveal supporting controls in an anchored popup. |
-| <a id="dialog"></a>[Dialog](docs/components/Dialog.md) | Keep a focused task in a dialog while the page waits behind it. |
-| <a id="menu"></a>[Menu](docs/components/Menu.md) | Keep related actions in a compact popup menu. |
-| <a id="toolbar"></a>[Toolbar](docs/components/Toolbar.md) | Group related actions with arrow-key navigation. |
+| <a id="copyabletext"></a>[`CopyableText`](docs/components/CopyableText.md) | Copy identifiers and references with feedback and recovery. |
+| <a id="button"></a>[`Button`](docs/components/Button.md) | Trigger an action or link to another page. |
+| <a id="popover"></a>[`Popover`](docs/components/Popover.md) | Reveal supporting controls in an anchored popup. |
+| <a id="dialog"></a>[`Dialog`](docs/components/Dialog.md) | Keep a focused task in a dialog while the page waits behind it. |
+| <a id="confirmaction"></a>[`ConfirmAction`](docs/components/ConfirmAction.md) | Put a destructive action behind one confirmation that closes only after success. |
+| <a id="menu"></a>[`Menu`](docs/components/Menu.md) | Keep related actions in a compact popup menu. |
+| <a id="toolbar"></a>[`Toolbar`](docs/components/Toolbar.md) | Group related actions with arrow-key navigation. |
 
 ### Forms
 
 | Component | Use for |
 |---|---|
-| <a id="checkbox"></a>[Checkbox](docs/components/Checkbox.md) | Let people select options independently, including a mixed selection. |
-| <a id="combobox"></a>[Combobox](docs/components/Combobox.md) | Search and choose one or multiple options from a longer list. |
-| <a id="errorsummary"></a>[ErrorSummary](docs/components/ErrorSummary.md) | Summarize form validation errors with links that focus each field. |
-| <a id="fieldset"></a>[Fieldset](docs/components/Fieldset.md) | Group related fields with a native fieldset, legend, and section help. |
-| <a id="fileinput"></a>[FileInput](docs/components/FileInput.md) | Choose files, review the list, and remove individual items. |
-| <a id="formactions"></a>[FormActions](docs/components/FormActions.md) | Align submit, reset, and secondary actions at the end of a form. |
-| <a id="input"></a>[Input](docs/components/Input.md) | Collect text with a clear label, help text, and error feedback. |
-| <a id="multiselect"></a>[MultiSelect](docs/components/MultiSelect.md) | Search a list and keep multiple selections visible as removable chips. |
-| <a id="numberfield"></a>[NumberField](docs/components/NumberField.md) | Enter a number by typing or using step buttons. |
-| <a id="radiogroup"></a>[RadioGroup](docs/components/RadioGroup.md) | Choose one option from a visible group. |
-| <a id="select"></a>[Select](docs/components/Select.md) | Choose one option from a dropdown list. |
-| <a id="switch"></a>[Switch](docs/components/Switch.md) | Turn an immediate preference on or off. |
-| <a id="textarea"></a>[Textarea](docs/components/Textarea.md) | Collect multiline text with a label, help text, and error feedback. |
+| <a id="checkbox"></a>[`Checkbox`](docs/components/Checkbox.md) | Let people select options independently, including a mixed selection. |
+| <a id="combobox"></a>[`Combobox`](docs/components/Combobox.md) | Search and choose one or multiple options from a longer list. |
+| <a id="errorsummary"></a>[`ErrorSummary`](docs/components/ErrorSummary.md) | Summarize form validation errors with links that focus each field. |
+| <a id="fieldset"></a>[`Fieldset`](docs/components/Fieldset.md) | Group related fields with a native `fieldset`, legend, and section help. |
+| <a id="fileinput"></a>[`FileInput`](docs/components/FileInput.md) | Choose files, review the list, and remove individual items. |
+| <a id="formactions"></a>[`FormActions`](docs/components/FormActions.md) | Align submit, reset, and secondary actions at the end of a form. |
+| <a id="formsection"></a>[`FormSection`](docs/components/FormSection.md) | A headed group of related fields with its error and actions. |
+| <a id="input"></a>[`Input`](docs/components/Input.md) | Collect text with a clear label, help text, and error feedback. |
+| <a id="multiselect"></a>[`MultiSelect`](docs/components/MultiSelect.md) | Search a list and keep multiple selections visible as removable chips. |
+| <a id="numberfield"></a>[`NumberField`](docs/components/NumberField.md) | Enter a number by typing or using step buttons. |
+| <a id="radiogroup"></a>[`RadioGroup`](docs/components/RadioGroup.md) | Choose one option from a visible group. |
+| <a id="select"></a>[`Select`](docs/components/Select.md) | Choose one option from a dropdown list. |
+| <a id="switch"></a>[`Switch`](docs/components/Switch.md) | Turn an immediate preference on or off. |
+| <a id="textarea"></a>[`Textarea`](docs/components/Textarea.md) | Collect multiline text with a label, help text, and error feedback. |
 
 ### Feedback
 
 | Component | Use for |
 |---|---|
-| <a id="badge"></a>[Badge](docs/components/Badge.md) | Add a short label, category, or piece of metadata. |
-| <a id="toast"></a>[Toast](docs/components/Toast.md) | Queue temporary messages with announcements, actions and timed dismissal. |
-| <a id="callout"></a>[Callout](docs/components/Callout.md) | Highlight a message and offer a useful next step. |
-| <a id="emptystate"></a>[EmptyState](docs/components/EmptyState.md) | Explain why a collection or section is empty and offer the next action. |
-| <a id="progress"></a>[Progress](docs/components/Progress.md) | Show how much of a task is complete. |
-| <a id="skeleton"></a>[Skeleton](docs/components/Skeleton.md) | Reserve incoming content geometry while a section loads. |
-| <a id="spinner"></a>[Spinner](docs/components/Spinner.md) | Indicate an indeterminate wait or busy control. |
-| <a id="stat"></a>[Stat](docs/components/Stat.md) | Show a number alongside the label that explains it. |
-| <a id="status"></a>[Status](docs/components/Status.md) | Describe a current state with text and an optional icon. |
-| <a id="tooltip"></a>[Tooltip](docs/components/Tooltip.md) | Add brief context on hover or keyboard focus. |
+| <a id="badge"></a>[`Badge`](docs/components/Badge.md) | Add a short label, category, or piece of metadata. |
+| <a id="toast"></a>[`Toast`](docs/components/Toast.md) | Queue temporary messages with announcements, actions and timed dismissal. |
+| <a id="callout"></a>[`Callout`](docs/components/Callout.md) | Highlight a message and offer a useful next step. |
+| <a id="emptystate"></a>[`EmptyState`](docs/components/EmptyState.md) | Explain why a collection or section is empty and offer the next action. |
+| <a id="progress"></a>[`Progress`](docs/components/Progress.md) | Show how much of a task is complete. |
+| <a id="skeleton"></a>[`Skeleton`](docs/components/Skeleton.md) | Reserve incoming content geometry while a section loads. |
+| <a id="spinner"></a>[`Spinner`](docs/components/Spinner.md) | Indicate an indeterminate wait or busy control. |
+| <a id="stat"></a>[`Stat`](docs/components/Stat.md) | Show a number alongside the label that explains it. |
+| <a id="status"></a>[`Status`](docs/components/Status.md) | Describe a current state with text and an optional icon. |
+| <a id="tooltip"></a>[`Tooltip`](docs/components/Tooltip.md) | Add brief context on hover or keyboard focus. |
 
 ### Layout
 
 | Component | Use for |
 |---|---|
-| <a id="accordion"></a>[Accordion](docs/components/Accordion.md) | Group related disclosures under headings. |
-| <a id="disclosure"></a>[Disclosure](docs/components/Disclosure.md) | Reveal optional details and controls inline. |
-| <a id="card"></a>[Card](docs/components/Card.md) | Group related content, with room for links and actions. |
-| <a id="container"></a>[Container](docs/components/Container.md) | Shared page widths and responsive gutters. |
-| <a id="grid"></a>[Grid](docs/components/Grid.md) | Arrange content in responsive columns or a single stack. |
-| <a id="inline"></a>[Inline](docs/components/Inline.md) | Wrapping rows with shared spacing and alignment. |
-| <a id="panel"></a>[Panel](docs/components/Panel.md) | Organize a section with a header, content, and actions. |
-| <a id="scrollarea"></a>[ScrollArea](docs/components/ScrollArea.md) | Keep longer content in a scrollable, keyboard-accessible region. |
-| <a id="separator"></a>[Separator](docs/components/Separator.md) | Semantic or decorative horizontal and vertical rules. |
-| <a id="split"></a>[Split](docs/components/Split.md) | Two columns that stack when their parent narrows. |
+| <a id="accordion"></a>[`Accordion`](docs/components/Accordion.md) | Group related disclosures under headings. |
+| <a id="dashboard"></a>[`Dashboard`](docs/components/Dashboard.md) | An overview page: header, metrics, then primary and secondary panels. |
+| <a id="disclosure"></a>[`Disclosure`](docs/components/Disclosure.md) | Reveal optional details and controls inline. |
+| <a id="card"></a>[`Card`](docs/components/Card.md) | Group related content, with room for links and actions. |
+| <a id="container"></a>[`Container`](docs/components/Container.md) | Shared page widths and responsive gutters. |
+| <a id="form"></a>[`Form`](docs/components/Form.md) | One task with grouped fields, then its one submit action. |
+| <a id="gallery"></a>[`Gallery`](docs/components/Gallery.md) | A page of image-led items, such as a product catalog, in one to four columns. |
+| <a id="grid"></a>[`Grid`](docs/components/Grid.md) | Arrange content in responsive columns or a single stack. |
+| <a id="inline"></a>[`Inline`](docs/components/Inline.md) | Wrapping rows with shared spacing and alignment. |
+| <a id="pageheader"></a>[`PageHeader`](docs/components/PageHeader.md) | Open a screen with its title, context, state badges and page-level actions. |
+| <a id="panel"></a>[`Panel`](docs/components/Panel.md) | Organize a section with a header, content, and actions. |
+| <a id="scrollarea"></a>[`ScrollArea`](docs/components/ScrollArea.md) | Keep longer content in a scrollable, keyboard-accessible region. |
+| <a id="separator"></a>[`Separator`](docs/components/Separator.md) | Semantic or decorative horizontal and vertical rules. |
+| <a id="settings"></a>[`Settings`](docs/components/Settings.md) | Sections of fields and managed lists, each saved on its own. |
+| <a id="split"></a>[`Split`](docs/components/Split.md) | Two columns that stack when their parent narrows. |
+| <a id="stack"></a>[`Stack`](docs/components/Stack.md) | Vertical flow with shared spacing and alignment. |
+| <a id="statsrow"></a>[`StatsRow`](docs/components/StatsRow.md) | Show comparable metrics in a row that fills its region and wraps when narrow. |
+| <a id="supportingpane"></a>[`SupportingPane`](docs/components/SupportingPane.md) | A main column with a named aside that moves below it when narrow. |
 
 ### Structured data
 
 | Component | Use for |
 |---|---|
-| <a id="table"></a>[Table](docs/components/Table.md) | Compare fields across records with sorting, selection, actions and sticky layouts. |
-| <a id="descriptionlist"></a>[DescriptionList](docs/components/DescriptionList.md) | Scan labeled facts with aligned, responsive key/value presentation. |
-| <a id="collectionlist"></a>[CollectionList](docs/components/CollectionList.md) | Group unordered or ordered records with shared alignment and spacing. |
-| <a id="collectionrow"></a>[CollectionRow](docs/components/CollectionRow.md) | Summarize a record with details, metadata, selection and independent actions. |
+| <a id="table"></a>[`Table`](docs/components/Table.md) | Compare fields across records with sorting, selection, actions and sticky layouts. |
+| <a id="descriptionlist"></a>[`DescriptionList`](docs/components/DescriptionList.md) | Scan labeled facts with aligned, responsive key/value presentation. |
+| <a id="collectionlist"></a>[`CollectionList`](docs/components/CollectionList.md) | Group unordered or ordered records with shared alignment and spacing. |
+| <a id="collectionrow"></a>[`CollectionRow`](docs/components/CollectionRow.md) | Summarize a record with details, metadata, selection and independent actions. |
 
 ### Typography
 
 | Component | Use for |
 |---|---|
-| <a id="codeblock"></a>[CodeBlock](docs/components/CodeBlock.md) | Explicit source listings with highlighting, line numbers and copy feedback. |
-| <a id="code"></a>[Code](docs/components/Code.md) | Literal inline code and syntax-highlighted multiline code blocks. |
-| <a id="heading"></a>[Heading](docs/components/Heading.md) | Native heading hierarchy with independent visual sizing. |
-| <a id="link"></a>[Link](docs/components/Link.md) | Recognizable navigation with visible keyboard focus. |
-| <a id="text"></a>[Text](docs/components/Text.md) | Readable paragraphs, inline text and supporting content. |
+| <a id="codeblock"></a>[`CodeBlock`](docs/components/CodeBlock.md) | Explicit source listings with highlighting, line numbers and copy feedback. |
+| <a id="code"></a>[`Code`](docs/components/Code.md) | Literal inline code and syntax-highlighted multiline code blocks. |
+| <a id="heading"></a>[`Heading`](docs/components/Heading.md) | Native heading hierarchy with independent visual sizing. |
+| <a id="link"></a>[`Link`](docs/components/Link.md) | Recognizable navigation with visible keyboard focus. |
+| <a id="text"></a>[`Text`](docs/components/Text.md) | Readable paragraphs, inline text and supporting content. |
 
 ## Composition guides
 
@@ -169,15 +182,15 @@ Use these when a task spans several components:
 
 ## Search composition
 
-Use the [Input search recipe](docs/components/Input.md#search-composition) for a labeled search field with a clear action and focus recovery.
+Use the [`Input` search recipe](docs/components/Input.md#search-composition) for a labeled search field with a clear action and focus recovery.
 
 ## Resizable panels
 
-Use the [Panel.Handle reference](docs/components/Panel.md#resizable-panels) for resizable panel groups and their pointer and keyboard behavior.
+Use the [`Panel.Handle` reference](docs/components/Panel.md#resizable-panels) for resizable panel groups and their pointer and keyboard behavior.
 
 ## Styling
 
-Every component takes `className` and `style`. Components with inner parts, such as Input, Select and Checkbox, also take `classNames` keyed by part; the props type lists each part. kbui's CSS sits in the `kbui` cascade layer, so your classes win. See [Restyling kbui](https://github.com/KhallilB/kbui/blob/main/docs/guides/restyling.md).
+Every component takes `className` and `style`. Components with inner parts, such as `Input`, `Select` and `Checkbox`, also take `classNames` keyed by part; the props type lists each part. kbui's CSS sits in the `kbui` cascade layer, so your classes win. See [Restyling kbui](https://github.com/KhallilB/kbui/blob/main/docs/guides/restyling.md).
 
 ```tsx
 <Input label="Email" className="w-full" classNames={{ control: "rounded-none" }} />

package/dist/components/ConfirmAction/ConfirmAction.d.ts

@@ -0,0 +1,42 @@
+import { type ReactNode } from "react";
+import { type ClassNames } from "../../utils/kb";
+import { type DialogContentProps, type DialogTriggerProps } from "../Dialog/Dialog";
+export type ConfirmActionSlot = "popup" | "backdrop" | "details" | "error";
+/** Destructive action behind a modal confirmation; the trigger only opens it. */
+export type ConfirmActionProps = Omit<DialogTriggerProps, "className" | "title" | "children" | "handle" | "payload"> & {
+    /** Trigger text; also the confirm button text unless confirmLabel is set. */
+    children: ReactNode;
+    /** Plain class string for the trigger. */
+    className?: string | undefined;
+    /** Dialog heading and accessible name; ask the question the action settles. */
+    title: ReactNode;
+    /** Consequence of confirming; the dialog's accessible description. */
+    description?: ReactNode | undefined;
+    /** Further consequence detail, such as what else is removed. */
+    details?: ReactNode | undefined;
+    /** Runs the action. Throw or reject to keep the dialog open with an error. */
+    onConfirm: () => unknown;
+    /** Runs once after success, after the dialog has closed; remove the trigger here. */
+    onConfirmed?: (() => void) | undefined;
+    /** Confirm button text; defaults to the trigger's children. */
+    confirmLabel?: ReactNode | undefined;
+    /** Confirm button text while the action runs; defaults to confirmLabel. */
+    pendingLabel?: ReactNode | undefined;
+    /** Cancel button text. */
+    cancelLabel?: ReactNode | undefined;
+    /** Alert shown after a failure; a function receives the thrown reason. */
+    errorMessage?: ReactNode | ((error: unknown) => ReactNode) | undefined;
+    /** Controlled visibility. */
+    open?: boolean | undefined;
+    /** Initial visibility when uncontrolled. */
+    defaultOpen?: boolean | undefined;
+    /** Receives each requested visibility change, including the close after success. */
+    onOpenChange?: ((open: boolean) => void) | undefined;
+    /** Focus target after closing; set it when success removes the trigger. */
+    finalFocus?: DialogContentProps["finalFocus"] | undefined;
+    /** Portal target; defaults to document.body. */
+    container?: DialogContentProps["container"] | undefined;
+    /** Classes for inner parts, keyed by part. */
+    classNames?: ClassNames<ConfirmActionSlot> | undefined;
+};
+export declare function ConfirmAction({ title, description, details, onConfirm, onConfirmed, confirmLabel, pendingLabel, cancelLabel, errorMessage, open, defaultOpen, onOpenChange, finalFocus, container, classNames, className, children, render, ...props }: ConfirmActionProps): import("react").JSX.Element;

package/dist/components/Dashboard/Dashboard.d.ts

@@ -0,0 +1,17 @@
+import type { ComponentProps, ReactNode } from "react";
+import { type ClassNames } from "../../utils/kb";
+export type DashboardPart = "header" | "metrics" | "panels" | "primary" | "secondary";
+export interface DashboardProps extends Omit<ComponentProps<"div">, "children"> {
+    /** Page title, freshness and page actions; usually a PageHeader. */
+    header?: ReactNode | undefined;
+    /** Row of headline metrics below the header. */
+    metrics?: ReactNode | undefined;
+    /** Main panels; take two thirds beside secondary on wide pages. */
+    primary?: ReactNode | undefined;
+    /** Supporting panels; move below primary on narrow pages. */
+    secondary?: ReactNode | undefined;
+    /** Classes for inner regions, keyed by region. */
+    classNames?: ClassNames<DashboardPart> | undefined;
+}
+/** Layout intent for an overview page: header, metrics, then primary and secondary panels. */
+export declare const Dashboard: ({ ref, header, metrics, primary, secondary, className, classNames, ...props }: DashboardProps) => import("react").JSX.Element;

package/dist/components/Form/Form.d.ts

@@ -0,0 +1,19 @@
+import type { ComponentProps, ReactNode } from "react";
+import { type ClassNames } from "../../utils/kb";
+import { type FormActionsAlign } from "../FormActions/FormActions";
+export type FormWidth = "sm" | "md" | "full";
+export type FormPart = "header" | "body" | "actions";
+export interface FormProps extends ComponentProps<"form"> {
+    /** Title and intro above the fields, such as a heading or PageHeader. */
+    header?: ReactNode | undefined;
+    /** The task's submit button first, then secondary actions. */
+    actions?: ReactNode | undefined;
+    /** Alignment of the actions row above the compact width. */
+    actionsAlign?: FormActionsAlign | undefined;
+    /** Maximum inline size: sm 32rem, md 40rem or full. */
+    width?: FormWidth | undefined;
+    /** Classes for inner regions, keyed by region. */
+    classNames?: ClassNames<FormPart> | undefined;
+}
+/** Layout intent for one task: header, grouped fields, then its actions. */
+export declare const Form: ({ ref, header, actions, actionsAlign, width, className, classNames, children, ...props }: FormProps) => import("react").JSX.Element;

package/dist/components/FormSection/FormSection.d.ts

@@ -0,0 +1,26 @@
+import { type ComponentProps, type ReactNode } from "react";
+import { type ClassNames } from "../../utils/kb";
+import { type FormActionsAlign } from "../FormActions/FormActions";
+export type FormSectionLayout = "stack" | "split";
+export type FormSectionHeadingLevel = 2 | 3 | 4 | 5 | 6;
+export type FormSectionPart = "header" | "title" | "description" | "body" | "fields" | "error" | "actions";
+export interface FormSectionProps extends Omit<ComponentProps<"fieldset">, "title"> {
+    /** Section heading; also names the group. */
+    title: ReactNode;
+    /** Heading rank; follow the page hierarchy. */
+    headingLevel?: FormSectionHeadingLevel | undefined;
+    /** Supporting context for the grouped fields. */
+    description?: ReactNode | undefined;
+    /** Section-level validation error. */
+    error?: ReactNode | undefined;
+    /** Buttons for this section, after the fields in Tab order. */
+    actions?: ReactNode | undefined;
+    /** Alignment of the actions row. */
+    actionsAlign?: FormActionsAlign | undefined;
+    /** Heading beside or above fields; unset follows the enclosing intent. */
+    layout?: FormSectionLayout | undefined;
+    /** Classes for inner parts, keyed by part. */
+    classNames?: ClassNames<FormSectionPart> | undefined;
+}
+/** Named group of related fields with its heading, error and actions. */
+export declare const FormSection: ({ ref, title, headingLevel, description, error, actions, actionsAlign, layout, disabled, className, classNames, children, "aria-describedby": ariaDescribedBy, "aria-invalid": callerAriaInvalid, ...props }: FormSectionProps) => import("react").JSX.Element;

package/dist/components/Gallery/Gallery.d.ts

@@ -0,0 +1,26 @@
+import { type ComponentProps, type ReactNode } from "react";
+import { type ClassNames } from "../../utils/kb";
+export type GalleryPart = "header" | "filters" | "items" | "empty";
+export interface GalleryProps extends ComponentProps<"div"> {
+    /** Page title, intro and page actions, usually a PageHeader. */
+    header?: ReactNode | undefined;
+    /** Search, filter and sort controls; they share a row and wrap. */
+    filters?: ReactNode | undefined;
+    /** Accessible name for the item list. */
+    itemsLabel?: string | undefined;
+    /** Shown in place of the list when there are no items. */
+    empty?: ReactNode | undefined;
+    /** Classes for inner regions, keyed by region. */
+    classNames?: ClassNames<GalleryPart> | undefined;
+}
+export interface GalleryItemProps extends ComponentProps<"li"> {
+    /** Spans two columns once the list has two; keep featured items first. */
+    featured?: boolean | undefined;
+}
+declare function GalleryRoot({ ref, header, filters, itemsLabel, empty, className, classNames, children, ...props }: GalleryProps): import("react").JSX.Element;
+declare function GalleryItem({ featured, className, ...props }: GalleryItemProps): import("react").JSX.Element;
+/** Layout intent for a grid of image-led items, such as a product catalog. */
+export declare const Gallery: typeof GalleryRoot & {
+    Item: typeof GalleryItem;
+};
+export {};

package/dist/components/PageHeader/PageHeader.d.ts

@@ -0,0 +1,27 @@
+import type { ComponentProps, ReactNode } from "react";
+import { type ClassNames } from "../../utils/kb";
+export type PageHeaderSize = "sm" | "md" | "lg";
+export type PageHeaderHeadingLevel = 1 | 2 | 3;
+export type PageHeaderProps = Omit<ComponentProps<"div">, "title"> & {
+    /** Page title; renders as the screen's main heading. */
+    title: ReactNode;
+    /** One or two sentences of context below the title. */
+    description?: ReactNode | undefined;
+    /** Short section or object-type label above the title. */
+    eyebrow?: ReactNode | undefined;
+    /** Back link or breadcrumb trail above the heading. */
+    navigation?: ReactNode | undefined;
+    /** Status badges or metadata beside the title, outside its accessible name. */
+    meta?: ReactNode | undefined;
+    /** Page-level actions; end-aligned, wrapping below the heading when narrow. */
+    actions?: ReactNode | undefined;
+    /** Document outline rank for the title (`1`–`3`); keep `1` for a screen's own header. */
+    headingLevel?: PageHeaderHeadingLevel | undefined;
+    /** Title scale: `sm` for dense app shells, `lg` for landing screens. */
+    size?: PageHeaderSize | undefined;
+    /** Draws a rule below the header to separate it from page content. */
+    divider?: boolean | undefined;
+    classNames?: ClassNames<"navigation" | "main" | "heading" | "eyebrow" | "headline" | "title" | "meta" | "description" | "actions" | "body"> | undefined;
+};
+/** Opening region of a screen: title, context, status and page-level actions. */
+export declare function PageHeader({ title, description, eyebrow, navigation, meta, actions, headingLevel, size, divider, className, classNames, children, ...rest }: PageHeaderProps): import("react").JSX.Element;

package/dist/components/Panel/Panel.d.ts

@@ -12,6 +12,8 @@ export type PanelProps = ComponentProps<"section"> & {
     rail?: PanelRail;
     /** Padding scale. */
     density?: PanelDensity;
+    /** Solid fill with no theme backdrop filter; for content that redraws often. */
+    opaque?: boolean;
     /** Makes Panel.Body collapse and expand from Panel.Toggle. */
     collapsible?: boolean;
     /** Controlled open state; collapsible only. */
@@ -53,7 +55,7 @@ export type PanelHandleProps = Omit<ComponentProps<"div">, "children" | "role">
 } | {
     "aria-labelledby": string;
 });
-declare function PanelRoot({ tone, rail, density, collapsible, open, defaultOpen, onOpenChange, className, children, ref, ...props }: PanelProps): import("react").JSX.Element;
+declare function PanelRoot({ tone, rail, density, opaque, collapsible, open, defaultOpen, onOpenChange, className, children, ref, ...props }: PanelProps): import("react").JSX.Element;
 declare function PanelHeader({ className, ...props }: PanelHeaderProps): import("react").JSX.Element;
 declare function PanelToolbar({ className, ...props }: PanelToolbarProps): import("react").JSX.Element;
 declare function PanelBody({ className, ...props }: PanelBodyProps): import("react").JSX.Element;

package/dist/components/Settings/Settings.d.ts

@@ -0,0 +1,11 @@
+import type { ComponentProps, ReactNode } from "react";
+import { type ClassNames } from "../../utils/kb";
+export type SettingsPart = "header" | "sections";
+export interface SettingsProps extends ComponentProps<"div"> {
+    /** Page title and intro above the sections. */
+    header?: ReactNode | undefined;
+    /** Classes for inner regions, keyed by region. */
+    classNames?: ClassNames<SettingsPart> | undefined;
+}
+/** Layout intent for sections of fields and managed lists, each saved on its own. */
+export declare const Settings: ({ ref, header, className, classNames, children, ...props }: SettingsProps) => import("react").JSX.Element;

package/dist/components/Skeleton/Skeleton.d.ts

@@ -1,12 +1,12 @@
 import { type ComponentPropsWithoutRef, type ReactNode } from "react";
 import { type ClassNames } from "../../utils/kb";
-export type SkeletonVariant = "text" | "rect" | "circle" | "pill";
+export type SkeletonVariant = "text" | "rect" | "circle" | "pill" | "auto";
 export type SkeletonSize = "sm" | "md" | "lg";
 export type SkeletonAnimation = "shimmer" | "pulse" | "wave" | "none";
 export type SkeletonTone = "default" | "subtle" | "accent";
-export type SkeletonPart = "root" | "line" | "content";
+export type SkeletonPart = "root" | "line" | "content" | "status";
 export interface SkeletonProps extends ComponentPropsWithoutRef<"div"> {
-    /** Shape preset for the placeholder geometry. */
+    /** Shape preset; `auto` shapes placeholders from kbui children, falling back to `text` without them. */
     variant?: SkeletonVariant | undefined;
     /** Size preset controlling line height or avatar diameter. */
     size?: SkeletonSize | undefined;
@@ -14,17 +14,19 @@ export interface SkeletonProps extends ComponentPropsWithoutRef<"div"> {
     lines?: number | undefined;
     /** Enable motion on placeholder shapes; set `false` for static placeholders. */
     animated?: boolean | undefined;
-    /** Motion choreography (`shimmer` diagonal sweep, `pulse` breathing opacity, `wave` staggered cascade, or `none`). */
+    /** Motion: `shimmer` sweep, `pulse` fade, `wave` staggered fade, or `none`. */
     animation?: SkeletonAnimation | undefined;
-    /** Surface color treatment (`default` surface, `subtle` recessed tint, or `accent` warm synthesis tint). */
+    /** Surface color: `default`, `subtle` recessed, or `accent` tinted. */
     tone?: SkeletonTone | undefined;
     /** Whether content is still loading; when `false`, renders `children` inside `.kb-skeleton-content`. */
     loading?: boolean | undefined;
+    /** Loading status announced by `variant="auto"`. */
+    label?: string | undefined;
     /** Optional explicit inline size (`px` number or CSS length string). */
     width?: number | string | undefined;
     /** Optional explicit block size (`px` number or CSS length string). */
     height?: number | string | undefined;
-    /** Loaded content revealed when `loading` is `false`. */
+    /** Loaded content; `variant="auto"` also renders it inert as the placeholder layout. */
     children?: ReactNode | undefined;
     /** Custom class names for internal component slots. */
     classNames?: ClassNames<SkeletonPart> | undefined;

package/dist/components/Stack/Stack.d.ts

@@ -0,0 +1,15 @@
+import type { LayoutElementProps, LayoutGap } from "../../utils/layout";
+export type StackElement = "div" | "section" | "article" | "aside" | "ul" | "ol" | "nav" | "form";
+export type StackAlign = "start" | "center" | "end" | "stretch";
+export type StackJustify = "start" | "center" | "end" | "between";
+export type StackProps<T extends StackElement = "div"> = LayoutElementProps<T> & {
+    /** Space between stacked items. */
+    gap?: LayoutGap;
+    /** Inline-axis alignment; stretch fills the stack width. */
+    align?: StackAlign;
+    /** Block-axis distribution when the stack is taller than its content. */
+    justify?: StackJustify;
+};
+export declare function Stack<T extends StackElement = "div">({ as, gap, align, justify, className, ...props }: StackProps<T>): import("react").DetailedReactHTMLElement<Omit<StackProps<T>, "align" | "as" | "className" | "gap" | "justify"> & {
+    className: string;
+} & Record<`data-${string}`, string>, HTMLElement>;

package/dist/components/StatsRow/StatsRow.d.ts

@@ -0,0 +1,33 @@
+import type { ComponentProps, ReactNode } from "react";
+import { type ClassNames } from "../../utils/kb";
+export type StatsRowAppearance = "plain" | "outlined";
+export type StatsRowTrend = "up" | "down" | "flat";
+export type StatsRowTone = "positive" | "negative" | "neutral";
+export type StatsRowProps = ComponentProps<"ul"> & {
+    /** Plain metrics on the page, or each metric on an outlined card surface. */
+    appearance?: StatsRowAppearance | undefined;
+};
+/** A list of comparable metrics that fills its region and wraps when narrow. */
+declare function StatsRowRoot({ appearance, className, ...rest }: StatsRowProps): import("react").JSX.Element;
+export type StatsRowItemProps = Omit<ComponentProps<"li">, "children"> & {
+    /** What the value measures, including its period when that changes the meaning. */
+    label: ReactNode;
+    /** The figure with its unit; figures are tabular. */
+    value: ReactNode;
+    /** Change since the comparison period; its text must state the direction, such as `+12.8%`. */
+    change?: ReactNode | undefined;
+    /** Direction glyph beside `change`; decorative, so the change text carries the meaning. */
+    trend?: StatsRowTrend | undefined;
+    /** Colors `change` by whether it is good or bad news; color alone, so state it in text too. */
+    tone?: StatsRowTone | undefined;
+    /** Comparison period or freshness, such as `vs. previous month`. */
+    context?: ReactNode | undefined;
+    /** Optional link to the detail behind the metric. */
+    link?: ReactNode | undefined;
+    classNames?: ClassNames<"stat" | "label" | "value" | "trend" | "change" | "glyph" | "context" | "link"> | undefined;
+};
+declare function StatsRowItem({ label, value, change, trend, tone, context, link, className, classNames, ...rest }: StatsRowItemProps): import("react").JSX.Element;
+export declare const StatsRow: typeof StatsRowRoot & {
+    Item: typeof StatsRowItem;
+};
+export {};

package/dist/components/SupportingPane/SupportingPane.d.ts

@@ -0,0 +1,15 @@
+import type { ComponentProps, ReactNode } from "react";
+import { type ClassNames } from "../../utils/kb";
+export type SupportingPanePart = "main" | "aside";
+export interface SupportingPaneProps extends ComponentProps<"div"> {
+    /** Supporting content, such as an order summary; moves below main at compact size. */
+    aside?: ReactNode | undefined;
+    /** Accessible name for the aside landmark. */
+    asideLabel?: string | undefined;
+    /** Id of a visible heading that names the aside; preferred over `asideLabel`. */
+    asideLabelledBy?: string | undefined;
+    /** Classes for inner regions, keyed by region. */
+    classNames?: ClassNames<SupportingPanePart> | undefined;
+}
+/** Layout intent for a main column with a complementary aside beside it, or below it when narrow. */
+export declare const SupportingPane: ({ ref, aside, asideLabel, asideLabelledBy, className, classNames, children, ...props }: SupportingPaneProps) => import("react").JSX.Element;