@kb.ui/react 0.11.0 → 0.12.0

package/docs/components/CopyableText.md

@@ -23,7 +23,7 @@ export function Example() {
 
 `value` is the clipboard source. Case, whitespace, Unicode and trailing newlines are preserved. `children` can format the collapsed display independently; expanding or a copy failure reveals the exact value for inspection and manual copying. Do not use this component to conceal secrets.
 
-The native button retains focus while a write is pending. Repeated activation during that write does nothing. Success appears only after the Clipboard API resolves; its callback receives the copied value. If value changes, the component is disabled, or it unmounts, outstanding writes cannot update feedback or fire callbacks. A write already sent to the operating system cannot be cancelled.
+The native `button` retains focus while a write is pending. Repeated activation during that write does nothing. Success appears only after the Clipboard API resolves; its callback receives the copied value. If value changes, the component is disabled, or it unmounts, outstanding writes cannot update feedback or fire callbacks. A write already sent to the operating system cannot be cancelled.
 
 A visible failure message remains until retry or content change. Users can select the full value and copy manually. Clipboard writes require a secure context such as HTTPS or localhost; browser permission, user activation, iframe policy or host restrictions can still reject them. No legacy clipboard fallback is attempted.
 
@@ -33,11 +33,11 @@ Set `tone` to color the value and softly tint field appearance. Neutral is the d
 
 Set `highlight` to a string or array of literal, case-sensitive terms. Matches use semantic `mark` elements with bold emphasis; the longest match wins when terms overlap at the same position. Matching never interprets HTML or regular expressions and never changes copied content.
 
-Automatic `format="auto"` recognizes HTTP(S) and `www.` URLs, qualified ASCII email addresses, backtick-delimited inline code, fenced code, valid JSON objects/arrays, and conservative JavaScript/TypeScript, CSS, HTML and common package-manager/Git/curl command patterns. Code receives the existing syntax colors and suppresses navigation inside source. Delimiters, whitespace and clipboard bytes remain literal.
+Automatic `format="auto"` recognizes HTTP(S) and `www.` URLs, qualified ASCII email addresses, backtick-delimited inline code, fenced code, valid JSON objects/arrays, and conservative JavaScript/TypeScript, CSS, HTML and common package-manager/Git/curl command patterns. `Code` receives the existing syntax colors and suppresses navigation inside source. Delimiters, whitespace and clipboard bytes remain literal.
 
-Use `format="text"` for identifiers or prose that resemble code, or `format="code"` with `language` for explicit source. A language hint forces code in automatic mode. Detection is intentionally conservative; it does not validate email deliverability or infer every programming language. Unknown fenced languages render as plain code. For large listings, prefer CodeBlock.
+Use `format="text"` for identifiers or prose that resemble code, or `format="code"` with `language` for explicit source. A language hint forces code in automatic mode. Detection is intentionally conservative; it does not validate email deliverability or infer every programming language. Unknown fenced languages render as plain code. For large listings, prefer `CodeBlock`.
 
-Detected links reuse Link styling and Link.Provider. Emails use mailto destinations with an encoded address; web links remain underlined native anchors. Sentence punctuation and unmatched closing brackets stay outside anchors. Set `linkify={false}` to disable detected links, or `linkify` with `format="text"` to opt back into links without code detection. Authored children retain caller-owned Link, strong, em or Code composition; automatic formatting applies to displayed raw source.
+Detected links reuse `Link` styling and `Link.Provider`. Emails use mailto destinations with an encoded address; web links remain underlined native anchors. Sentence punctuation and unmatched closing brackets stay outside anchors. Set `linkify={false}` to disable detected links, or `linkify` with `format="text"` to opt back into links without code detection. Authored children retain caller-owned `Link`, strong, em or `Code` composition; automatic formatting applies to displayed raw source.
 
 In truncated previews, detected links become interactive only after expansion. This keeps clipped links out of Tab order. After expanding, Shift+Tab reaches links above the disclosure; Tab continues to Copy. Copying remains a separate action. Errors expand the same formatted raw source for manual selection. `mono={false}` gives prose the proportional font and body line spacing.
 
@@ -65,8 +65,8 @@ In truncated previews, detected links become interactive only after expansion. T
 | `mono` | `boolean` | `true` | Monospace value display |
 | `tone` | `CopyableTextTone` | `"neutral"` | `neutral`, `accent`, `info`, `success`, `warning` or `danger`; independent of copy state |
 | `truncate` | `boolean` | `false` | Single-line preview with explicit full-value disclosure |
-| `expandLabel` | `string` | `"Show full value"` | Disclosure text when collapsed |
-| `collapseLabel` | `string` | `"Show less"` | Disclosure text when expanded |
+| `expandLabel` | `string` | `"Show full value"` | `Disclosure` text when collapsed |
+| `collapseLabel` | `string` | `"Show less"` | `Disclosure` text when expanded |
 | `disabled` | `boolean` | `false` | Disables copying, retains selectable value |
 | `copyLabel` | `string` | `"Copy"` | Visible action and accessible name; use specific purpose |
 | `copyingLabel` | `string` | `"Copying…"` | Pending label and polite announcement |
@@ -79,15 +79,15 @@ In truncated previews, detected links become interactive only after expansion. T
 | `onCopyError` | `(error: unknown) => void` | unset | Current write failed, including unavailable API |
 | `highlight` | `string \| readonly string[]` | unset | Literal case-sensitive terms; empty terms ignored, longest overlapping match wins |
 | `format` | `CopyableTextFormat` | `"auto"` | `auto`, `text`, or `code`; conservative recognition with explicit overrides |
-| `language` | `CodeLanguage` | unset | Code hint; forces code in auto mode; text mode remains literal |
+| `language` | `CodeLanguage` | unset | `Code` hint; forces code in auto mode; text mode remains literal |
 | `linkify` | `boolean` | automatic | Override detected web/email links; false disables links; code ranges never become links |
 | `classNames` | `Partial<Record<CopyableTextPart, string>>` | unset | `label`, `value`, `actions`, `toggle`, `copy`, `feedback`, `link`, `highlight`, `code` slots |
 | `className`, `ref`, other props | Native `span` props | unset | Root element; native `onCopy` replaced by success callback |
 
 The root exposes `data-copy-state="idle|pending|copied|failed"`, appearance, size, tone, mono, expandable, expanded, truncate and disabled attributes. Pending sets `aria-disabled` on the button while preserving focus. The status region exists before interaction and is empty initially. Failure is both visible and announced; success has a visible button label and polite announcement.
 
-Use `--kb-copyabletext-highlight-background` for marked text and Link tokens for navigation styling. Standalone CSS users also load `link.css` and `code.css` for detected links and syntax styling. Use `--kb-copyabletext-*` tokens for gap, padding, radius, border, background, neutral value color, target size and minimum copy width. `className` styles the root; `classNames` styles individual parts. Verify contrast and target sizes after overrides. Automated tests cover component behavior, browser keyboard activation and accessibility scans; screen-reader announcement quality remains a human verification task.
+Use `--kb-copyabletext-highlight-background` for marked text and `Link` tokens for navigation styling. Standalone CSS users also load `link.css` and `code.css` for detected links and syntax styling. Use `--kb-copyabletext-*` tokens for gap, padding, radius, border, background, neutral value color, target size and minimum copy width. `className` styles the root; `classNames` styles individual parts. Verify contrast and target sizes after overrides. Automated tests cover component behavior, browser keyboard activation and accessibility scans; screen-reader announcement quality remains a human verification task.
 
 ## Related components
 
-Use [CodeBlock](CodeBlock.md) for highlighted source and multiline commands, [Code](Code.md) for inline literals, and [Link](Link.md) for navigation. [Copyable content guidance](https://github.com/KhallilB/kbui/blob/main/docs/guides/copyable-content.md) covers shared recovery and localization.
+Use [`CodeBlock`](CodeBlock.md) for highlighted source and multiline commands, [`Code`](Code.md) for inline literals, and [`Link`](Link.md) for navigation. [Copyable content guidance](https://github.com/KhallilB/kbui/blob/main/docs/guides/copyable-content.md) covers shared recovery and localization.

package/docs/components/Dashboard.md

@@ -0,0 +1,81 @@
+# Dashboard
+
+Use `Dashboard` for an overview page: a header, a row of headline metrics, then primary and secondary panels. Primary and secondary sit side by side, two thirds and one third, once the panels region is 60rem wide, and stack with primary first below that. `Dashboard` is also the page frame: it fills the width up to 80rem with 1, 1.5 or 2rem gutters, so it does not need a [`Container`](Container.md). For a main column with one supporting aside, such as an order summary, use [`Split`](Split.md).
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/layout-dashboard--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Card, Dashboard, Grid, PageHeader, Panel, Progress, Stat, Status } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <main>
+      <Dashboard
+        header={
+          <PageHeader
+            title="Sales dashboard"
+            description="Performance overview for your online store."
+            meta={<Status tone="success">Updated 5 minutes ago</Status>}
+          />
+        }
+        metrics={
+          <Grid as="ul" aria-label="Key metrics" minItemWidth="sm" gap="md">
+            <Card as="li">
+              <Stat label="Total revenue" value="$128,450" />
+            </Card>
+            <Card as="li">
+              <Stat label="Orders" value="2,184" />
+            </Card>
+          </Grid>
+        }
+        primary={
+          <Panel aria-labelledby="channels-title">
+            <Panel.Header>
+              <h2 id="channels-title">Revenue by channel</h2>
+            </Panel.Header>
+            <Panel.Body>Organic search brought in 36% of revenue.</Panel.Body>
+          </Panel>
+        }
+        secondary={
+          <Panel aria-labelledby="goals-title">
+            <Panel.Header>
+              <h2 id="goals-title">Monthly goals</h2>
+            </Panel.Header>
+            <Panel.Body>
+              <Progress label="Revenue" value={86} valueText="$128k of $150k" />
+            </Panel.Body>
+          </Panel>
+        }
+      />
+    </main>
+  );
+}
+```
+
+## More examples
+
+- [Sales overview](https://kbui.kcb.pro/storybook/?path=/story/layout-dashboard--sales-overview): A store dashboard with a date range, four metrics, channel revenue and top products beside monthly goals.
+- [Metrics and primary](https://kbui.kcb.pro/storybook/?path=/story/layout-dashboard--metrics-and-primary): Without secondary panels, the primary region fills the page.
+
+## Reference
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `header` | `ReactNode` | unset | Page title, freshness and page actions; usually a `PageHeader` |
+| `metrics` | `ReactNode` | unset | Row of headline metrics below the header |
+| `primary` | `ReactNode` | unset | Main panels; two thirds of the row on wide pages |
+| `secondary` | `ReactNode` | unset | Supporting panels; one third on wide pages, below primary on narrow ones |
+| `classNames` | `{ header?, metrics?, panels?, primary?, secondary? }` | unset | Classes for the regions |
+
+Other native `div` props and `ref` pass through. Regions render in the order above and only when they have content; with only one of primary or secondary, it fills the row. Each panel region stacks its children with the dashboard gap.
+
+Gutters follow the width of the dashboard's parent: 1rem below 48rem, 1.5rem from 48rem and 2rem from 64rem. As a direct flex item, such as beside a sidebar, the parent is the whole row, so wrap `Dashboard` in its own block, such as `main`. Tokens: `--kb-dashboard-gap`, `--kb-dashboard-max-width`, `--kb-dashboard-gutter-sm`, `-md`, `-lg`, `--kb-dashboard-gutter-md-from`, `--kb-dashboard-gutter-lg-from` and `--kb-dashboard-collapse`.
+
+Give the page one `h1`, usually `PageHeader`'s title, and name each panel with its `h2`. Label the metrics list, and show when the data was last updated, or that it is partial, as text in the header. Your app owns data loading, date ranges and refresh.
+
+## Related components
+
+Use [`PageHeader`](PageHeader.md) for the header, [`Stat`](Stat.md) in a [`Grid`](Grid.md) for metrics and [`Panel`](Panel.md) for each panel.

package/docs/components/DescriptionList.md

@@ -1,6 +1,6 @@
 # DescriptionList
 
-Present named facts about one record with native description-list relationships. Use Table when readers need to compare the same fields across records.
+Present named facts about one record with native description-list relationships. Use `Table` when readers need to compare the same fields across records.
 
 [All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-descriptionlist--docs)
 
@@ -52,10 +52,10 @@ export function Example() {
 
 Every part accepts its native attributes, `className`, `style` and ref. Types are `DescriptionListProps`, `DescriptionListItemProps`, `DescriptionListTermProps` and `DescriptionListDetailProps`. Use a real `dt` before its `dd` values; the description list does not become a table or listbox. Group alternate names inside one Term when they share values. Native IDs and `aria-labelledby` remain available for richer relationships.
 
-Values align to the same column across Items. Long labels, identifiers and composed Status text wrap, including chips with decorative icons; native links and controls retain their keyboard behavior. Use a deliberate stacked layout for narrow details, or override `--kb-descriptionlist-term-width` when the default 12rem label cap does not fit your labels. Other tokens control column/row gaps and comfortable/dense block padding. Nested lists keep their own layout and density.
+Values align to the same column across Items. Long labels, identifiers and composed `Status` text wrap, including chips with decorative icons; native links and controls retain their keyboard behavior. Use a deliberate stacked layout for narrow details, or override `--kb-descriptionlist-term-width` when the default 12rem label cap does not fit your labels. Other tokens control column/row gaps and comfortable/dense block padding. Nested lists keep their own layout and density.
 
 Keep zero values visible. Write a meaningful unavailable value such as Not scheduled rather than silently omitting a required fact. Your app owns formatting, units, timezone, localization, loading, errors and announcements. Do not use term text as an input label; controls still need their own labels and relationships. A description list supplies native relationships, not interactive field validation.
 
 ## Related components
 
-Use [Table](Table.md) for comparing fields across records, [CollectionRow](CollectionRow.md) for summarizing records with actions, and [Status](Status.md) for an explicit state. See [Structured data](../../../../docs/guides/structured-data.md) for choosing and composing these patterns.
+Use [`Table`](Table.md) for comparing fields across records, [`CollectionRow`](CollectionRow.md) for summarizing records with actions, and [`Status`](Status.md) for an explicit state. See [Structured data](../../../../docs/guides/structured-data.md) for choosing and composing these patterns.

package/docs/components/Dialog.md

@@ -49,11 +49,11 @@ export function Example() {
 
 | Prop on root or Content  | Type             | Default       | Notes                                                                         |
 | ------------------------ | ---------------- | ------------- | ----------------------------------------------------------------------------- |
-| `open` on Dialog         | `boolean`        | uncontrolled  | Current visibility when your app controls the dialog                          |
-| `defaultOpen` on Dialog  | `boolean`        | `false`       | Initial visibility; avoid starting open in a reading surface                  |
-| `onOpenChange` on Dialog | Base UI callback | unset         | Receives the next visibility and change details                               |
-| `title` on Content       | `ReactNode`      | unset         | Visible title and accessible name; use Dialog.Title for custom markup instead |
-| `description` on Content | `ReactNode`      | unset         | Supporting description; use Dialog.Description for custom markup instead      |
+| `open` on `Dialog`         | `boolean`        | uncontrolled  | Current visibility when your app controls the dialog                          |
+| `defaultOpen` on `Dialog`  | `boolean`        | `false`       | Initial visibility; avoid starting open in a reading surface                  |
+| `onOpenChange` on `Dialog` | Base UI callback | unset         | Receives the next visibility and change details                               |
+| `title` on Content       | `ReactNode`      | unset         | Visible title and accessible name; use `Dialog.Title` for custom markup instead |
+| `description` on Content | `ReactNode`      | unset         | Supporting description; use `Dialog.Description` for custom markup instead      |
 | `container` on Content   | portal container | document body | Themed host for a nested dialog                                               |
 
 ```tsx
@@ -71,7 +71,7 @@ export function Example() {
 
 ## Related components
 
-Use [Menu](Menu.md) for a short action list and [Callout](Callout.md) for a message that belongs in the page.
+Use [`ConfirmAction`](ConfirmAction.md) for a destructive action behind a confirmation, [`Menu`](Menu.md) for a short action list and [`Callout`](Callout.md) for a message that belongs in the page.
 
 
 ## Drawer and confirmation patterns
@@ -81,4 +81,4 @@ The [overlay guide](../../../../docs/guides/forms-and-overlays.md#drawer-pattern
 - [Drawer](https://kbui.kcb.pro/storybook/?path=/story/components-dialog--drawer)
 - [Failure and retry](https://kbui.kcb.pro/storybook/?path=/story/components-dialog--confirmation-recovery)
 
-Use [Popover](Popover.md) for non-modal anchored controls and [Disclosure](Disclosure.md) for supporting details inline.
+Use [`Popover`](Popover.md) for non-modal anchored controls and [`Disclosure`](Disclosure.md) for supporting details inline.

package/docs/components/Disclosure.md

@@ -39,15 +39,15 @@ export function AdvancedSettings() {
 | `Disclosure.Trigger` | Base UI Collapsible trigger props | `button` | Native Enter/Space activation and expanded/controls relationships. |
 | `Disclosure.Panel` | Base UI Collapsible panel props | `div` | Contains optional details and controls. |
 | `Panel.keepMounted` | `boolean` | `false` | Retains DOM and uncontrolled draft state while closed. |
-| `Panel.hiddenUntilFound` | `boolean` | `false` | Uses browser find-in-page reveal where supported; overrides keepMounted. |
+| `Panel.hiddenUntilFound` | `boolean` | `false` | Uses browser find-in-page reveal where supported; overrides `keepMounted`. |
 | `className` / `render` / `ref` | Part-specific native props | — | Style, compose and reference each DOM part. Class names accept strings. |
 
-Tab reaches the trigger; Enter and Space toggle it without moving focus into the panel. Collapsed controls leave the accessibility tree and Tab order. No arrow-key navigation or modal behavior is added. Put essential instructions and errors where they remain discoverable. Unmounted content loses uncontrolled state; use keepMounted or store values outside the panel. Browser find-in-page reveal depends on engine support and the caller accepting controlled state changes.
+Tab reaches the trigger; Enter and Space toggle it without moving focus into the panel. Collapsed controls leave the accessibility tree and Tab order. No arrow-key navigation or modal behavior is added. Put essential instructions and errors where they remain discoverable. Unmounted content loses uncontrolled state; use `keepMounted` or store values outside the panel. Browser find-in-page reveal depends on engine support and the caller accepting controlled state changes.
 
 Style `--kb-disclosure-padding`, `-radius`, `-background`, `-color`, `-border` and `-trigger-height`. Preserve visible focus, hidden semantics and disabled state when overriding styles.
 
-Panels expand and collapse through measured height transitions; reversing mid-transition follows the latest toggle. Content grows naturally once expanded. `--kb-disclosure-motion-duration` and `-motion-easing` control panel and caret motion; reduced motion disables transitions. `.kb-disclosure-panel-content` owns inner padding, keeping the outer Panel measurable without clipping collapsed padding. Panel props, className, render and ref still target the outer node.
+Panels expand and collapse through measured height transitions; reversing mid-transition follows the latest toggle. Content grows naturally once expanded. `--kb-disclosure-motion-duration` and `-motion-easing` control panel and caret motion; reduced motion disables transitions. `.kb-disclosure-panel-content` owns inner padding, keeping the outer `Panel` measurable without clipping collapsed padding. `Panel` props, `className`, render and ref still target the outer node.
 
 ## Related components
 
-Use [Accordion](Accordion.md) for related sections with headings, [Panel](Panel.md) for a structured work surface, or [Popover](Popover.md) for anchored supporting controls. [Overlay guidance](../../../../docs/guides/forms-and-overlays.md) covers choosing disclosure, popovers and modal patterns.
+Use [`Accordion`](Accordion.md) for related sections with headings, [`Panel`](Panel.md) for a structured work surface, or [`Popover`](Popover.md) for anchored supporting controls. [Overlay guidance](../../../../docs/guides/forms-and-overlays.md) covers choosing disclosure, popovers and modal patterns.

package/docs/components/EmptyState.md

@@ -47,4 +47,4 @@ export function Example() {
 
 ## Related components
 
-Use [Skeleton](Skeleton.md) while the collection is still loading, [Callout](Callout.md) for inline notices beside populated content, and [Toast](Toast.md) for transient action feedback.
+Use [`Skeleton`](Skeleton.md) while the collection is still loading, [`Callout`](Callout.md) for inline notices beside populated content, and [`Toast`](Toast.md) for transient action feedback.

package/docs/components/ErrorSummary.md

@@ -1,6 +1,6 @@
 # ErrorSummary
 
-Place ErrorSummary at the top of a form when submission fails so people can see what went wrong and jump directly to each invalid field. When `items` is empty, nothing is rendered.
+Place `ErrorSummary` at the top of a form when submission fails so people can see what went wrong and jump directly to each invalid field. When `items` is empty, nothing is rendered.
 
 [All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-errorsummary--docs)
 
@@ -39,8 +39,10 @@ This example shows a failed-submission state. The Form recovery story below demo
 | `onItemSelect` | `(href: string, event: MouseEvent<HTMLAnchorElement>) => void`       | unset                  | Called when a recovery link is clicked                           |
 | `classNames`   | `ClassNames<"title" \| "description" \| "list" \| "item" \| "link">` | unset                  | Classes for inner parts                                          |
 
-ErrorSummary renders an alert region with `tabIndex={-1}` so your submit handler can focus it when validation fails. Clicking an `#id` link focuses the matching control or the first enabled control inside a referenced group. Pair ErrorSummary with inline `error` props on each invalid field.
+`ErrorSummary` renders an alert region with `tabIndex={-1}` so your submit handler can focus it when validation fails. Clicking an `#id` link focuses the matching control or the first enabled control inside a referenced group. Pair `ErrorSummary` with inline `error` props on each invalid field.
+
+Error links keep their list markers. The list's `gap` controls spacing between items without added prose margins.
 
 ## Related components
 
-Keep inline errors on [Input](Input.md), [Textarea](Textarea.md), and other fields. Use [FormActions](FormActions.md) for the submit controls.
+Keep inline errors on [`Input`](Input.md), [`Textarea`](Textarea.md), and other fields. Use [`FormActions`](FormActions.md) for the submit controls.

package/docs/components/Fieldset.md

@@ -1,6 +1,6 @@
 # Fieldset
 
-Use Fieldset to group related controls into a named form section using native `fieldset` and `legend` semantics. Setting `disabled` disables descendant form controls natively.
+Use `Fieldset` to group related controls into a named form section using native `fieldset` and `legend` semantics. Setting `disabled` disables descendant form controls natively.
 
 [All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-fieldset--docs)
 
@@ -28,15 +28,15 @@ export function Example() {
 
 | Prop             | Type                                                           | Default  | Notes                                                  |
 | ---------------- | -------------------------------------------------------------- | -------- | ------------------------------------------------------ |
-| `legend`         | `ReactNode`                                                    | required | Section heading rendered inside the native legend      |
+| `legend`         | `ReactNode`                                                    | required | Section heading rendered inside the native `legend`      |
 | `visuallyHidden` | `boolean`                                                      | `false`  | Hides the legend visually while keeping the group name |
-| `description`    | `ReactNode`                                                    | unset    | Section help text linked through aria-describedby      |
-| `error`          | `ReactNode`                                                    | unset    | Group-level error linked through aria-describedby      |
+| `description`    | `ReactNode`                                                    | unset    | Section help text linked through `aria-describedby`      |
+| `error`          | `ReactNode`                                                    | unset    | Group-level error linked through `aria-describedby`      |
 | `disabled`       | `boolean`                                                      | `false`  | Disables all descendant controls in the fieldset       |
 | `classNames`     | `ClassNames<"legend" \| "description" \| "fields" \| "error">` | unset    | Classes for inner parts                                |
 
-Other native fieldset props and `ref` pass through to the `<fieldset>` element. Use `--kb-fieldset-gap`, `--kb-fieldset-fields-gap`, and `--kb-fieldset-legend-size` to tune spacing and legend typography.
+Other native `fieldset` props and `ref` pass through to the `<fieldset>` element. Use `--kb-fieldset-gap`, `--kb-fieldset-fields-gap`, and `--kb-fieldset-legend-size` to tune spacing and legend typography.
 
 ## Related components
 
-Use [Textarea](Textarea.md) and [Input](Input.md) for answers, [ErrorSummary](ErrorSummary.md) for submission recovery, and [FormActions](FormActions.md) for the action row.
+Use [`Textarea`](Textarea.md) and [`Input`](Input.md) for answers, [`ErrorSummary`](ErrorSummary.md) for submission recovery, and [`FormActions`](FormActions.md) for the action row.

package/docs/components/FileInput.md

@@ -1,6 +1,6 @@
 # FileInput
 
-Use FileInput to choose files, review the selected list, and remove items. Your app decides which files to accept, keeps the File objects, and handles uploads. See [Retained file selection](https://github.com/KhallilB/kbui/blob/main/docs/guides/file-inputs.md) for examples, keyboard behavior, and styling. Available since v0.6.0.
+Use `FileInput` to choose files, review the selected list, and remove items. Your app decides which files to accept, keeps the `File` objects, and handles uploads. See [Retained file selection](https://github.com/KhallilB/kbui/blob/main/docs/guides/file-inputs.md) for examples, keyboard behavior, and styling. Available since v0.6.0.
 
 [All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-fileinput--docs)
 
@@ -54,7 +54,7 @@ The example retains each original `File` alongside its display metadata. Your ap
 | `onFiles`                                            | `(files: File[]) => void`            | required                | Check the selection and update retained files in your app            |
 | `onRemove`                                           | `(id: string) => void`               | required                | Request removal; update items to confirm it                          |
 | `accept`                                             | `string`                             | unset                   | Native picker hint, such as image/*; does not validate files         |
-| `multiple`                                           | `boolean`                            | `true`                  | Allow multiple selection; use a singular chooseLabel for single mode |
+| `multiple`                                           | `boolean`                            | `true`                  | Allow multiple selection; use a singular `chooseLabel` for single mode |
 | `disabled`, `readOnly`                               | `boolean`                            | `false`                 | Prevent edits while keeping the retained list visible                |
 | `description`, `error`                               | `string`                             | unset                   | Help or actionable rejection text associated with the field          |
 | `visuallyHidden`                                     | `boolean`                            | `false`                 | Hide the visual label while preserving its accessible name           |
@@ -64,11 +64,11 @@ The example retains each original `File` alongside its display metadata. Your ap
 | `removedMessage`                                     | `(item: FileInputItem) => string`    | filename + removed.     | Announcement after removal is confirmed                              |
 | `selectionMessage`                                   | `(count: number) => string`          | count + files selected. | Announcement after native selection                                  |
 | `renderItem`                                         | `(item: FileInputItem) => ReactNode` | name + description      | Custom item content; keep visible file identity                      |
-| `inputRef`, `triggerRef`                             | element refs                         | unset                   | Hidden native input and visible picker access                        |
+| `inputRef`, `triggerRef`                             | element refs                         | unset                   | Hidden native `input` and visible picker access                        |
 | `triggerClassName`, `listClassName`, `itemClassName` | `string`                             | unset                   | Classes for picker, retained list, and items                         |
 
-Root native div props/ref and className pass through. Root aria-describedby merges after helper/error. Item button refs remain internal to preserve focus; use public item/content classes and renderItem for presentation. Use these props and classes rather than reaching into individual item buttons. The `×` mark is decorative; removal has a full accessible filename label.
+Native `<div>` props, `ref` and `className` apply to the root. Root `aria-describedby` IDs follow the help and error IDs. Item button refs stay internal so removal can restore focus. Customize items through the item/content classes and `renderItem`; avoid changing individual item buttons. The `×` is decorative, and each removal button is named with the full filename.
 
 ## Related components
 
-Use [Progress](Progress.md) to present caller-owned upload progress. File selection and uploading are separate steps.
+Use [`Progress`](Progress.md) to show upload progress supplied by your app. File selection and uploading are separate steps.

package/docs/components/Form.md

@@ -0,0 +1,67 @@
+# Form
+
+Use `Form` for one task with one submit action, such as checkout, booking or sign-up. It renders a native `form` with three regions in reading order: an optional header, the fields, and an actions row. Fill the regions and the arrangement comes with them: a readable maximum width, even spacing between sections, and actions that fill the row on narrow screens. For pages of independently saved sections, use [`Settings`](Settings.md).
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/layout-form--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Button, Form, FormSection, Heading, Input } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <Form
+      aria-labelledby="booking-title"
+      onSubmit={(event) => event.preventDefault()}
+      header={
+        <Heading level={1} id="booking-title">
+          Book a room
+        </Heading>
+      }
+      actions={
+        <>
+          <Button type="submit">Confirm booking</Button>
+          <Button type="button" variant="ghost">
+            Back to rooms
+          </Button>
+        </>
+      }
+    >
+      <FormSection title="Dates">
+        <Input label="Check-in" type="date" name="checkIn" />
+        <Input label="Check-out" type="date" name="checkOut" />
+      </FormSection>
+      <FormSection title="Guest">
+        <Input label="Full name" name="name" autoComplete="name" />
+      </FormSection>
+    </Form>
+  );
+}
+```
+
+## More examples
+
+- [Hotel booking](https://kbui.kcb.pro/storybook/?path=/story/layout-form--hotel-booking): Dates, room type and extras in three sections, then one confirm action.
+- [Sign up](https://kbui.kcb.pro/storybook/?path=/story/layout-form--sign-up): A short form at the narrow width, with plain fields and no sections.
+
+## Reference
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `header` | `ReactNode` | unset | Title and intro above the fields |
+| `actions` | `ReactNode` | unset | Rendered in [`FormActions`](FormActions.md) with a divider; put the submit button first |
+| `actionsAlign` | `"end" \| "start" \| "between"` | `"end"` | Alignment of the actions row at 30rem and wider |
+| `width` | `"sm" \| "md" \| "full"` | `"md"` | Maximum inline size: 32rem, 40rem or none |
+| `classNames` | `{ header?, body?, actions? }` | unset | Classes for the regions |
+
+Other native form props and `ref` pass through. Children fill the body: [`FormSection`](FormSection.md) groups for longer tasks, or plain fields for short ones.
+
+Below 30rem of row width, each button or link in the actions fills its own row in source order, so the submit button sits on top and every button is a full-width target. Tokens: `--kb-form-gap`, `--kb-form-width-sm` and `--kb-form-width-md`.
+
+A form is a landmark only when it has a name; add `aria-label` or `aria-labelledby` when people should find it from the landmark list. Your app owns validation, [`ErrorSummary`](ErrorSummary.md) focus after a failed submit, pending state and success feedback.
+
+## Related components
+
+Use [`Settings`](Settings.md) for independently saved sections, [`FormSection`](FormSection.md) to group fields and [`Container`](Container.md) for the page boundary around the form.

package/docs/components/FormActions.md

@@ -1,6 +1,6 @@
 # FormActions
 
-Use FormActions at the bottom of a form or section to align submit, reset, and secondary buttons with consistent wrapping and spacing. Buttons stay in natural Tab order without toolbar arrow-key navigation.
+Use `FormActions` at the bottom of a form or section to align submit, reset, and secondary buttons with consistent wrapping and spacing. Buttons stay in natural Tab order without toolbar arrow-key navigation.
 
 [All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-formactions--docs)
 
@@ -38,8 +38,8 @@ export function Example() {
 | `divider`  | `boolean`                       | `false` | Adds a top border and spacing above the action row |
 | `children` | `ReactNode`                     | unset   | Form buttons in reading and Tab order              |
 
-Other native div props and `ref` pass through. Use `--kb-formactions-gap` and `--kb-formactions-padding-top` to adjust spacing.
+Other native `div` props and `ref` pass through. Use `--kb-formactions-gap` and `--kb-formactions-padding-top` to adjust spacing.
 
 ## Related components
 
-Use [Fieldset](Fieldset.md) for named groups and [ErrorSummary](ErrorSummary.md) for failed submission recovery. Use [Toolbar](Toolbar.md) when controls need arrow-key navigation.
+Use [`Fieldset`](Fieldset.md) for named groups and [`ErrorSummary`](ErrorSummary.md) for failed submission recovery. Use [`Toolbar`](Toolbar.md) when controls need arrow-key navigation.

package/docs/components/FormSection.md

@@ -0,0 +1,57 @@
+# FormSection
+
+Use `FormSection` to group related fields under a section heading, with optional help, a section error and the section's own actions. It renders a native `fieldset` named by its heading, so screen reader users can browse sections by heading and hear the group name on entry. Use [`Form`](Form.md) or [`Settings`](Settings.md) to arrange several sections.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-formsection--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Button, FormSection, Input } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <form onSubmit={(event) => event.preventDefault()}>
+      <FormSection
+        title="Profile"
+        description="Shown to everyone in your workspace."
+        actions={<Button type="submit">Save profile</Button>}
+      >
+        <Input label="Display name" name="name" />
+        <Input label="Job title" name="title" />
+      </FormSection>
+    </form>
+  );
+}
+```
+
+## More examples
+
+- [Heading beside fields](https://kbui.kcb.pro/storybook/?path=/story/components-formsection--split-layout): `Split` layout, which stacks below 40rem of section width.
+- [Section error](https://kbui.kcb.pro/storybook/?path=/story/components-formsection--section-error): A group-level error alongside a field error.
+- [Pending save](https://kbui.kcb.pro/storybook/?path=/story/components-formsection--pending-save): Lock every field and action while a save is in flight.
+
+## Reference
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `title` | `ReactNode` | required | Section heading; also names the group |
+| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | `2` | Heading rank; follow the page outline |
+| `description` | `ReactNode` | unset | Help text; added to the group's `aria-describedby` |
+| `error` | `ReactNode` | unset | Section error; sets `data-invalid` and `aria-invalid` and describes the group |
+| `actions` | `ReactNode` | unset | Buttons rendered in [`FormActions`](FormActions.md) after the fields |
+| `actionsAlign` | `"start" \| "end" \| "between"` | `"end"` | Alignment of the actions row |
+| `layout` | `"stack" \| "split"` | unset | Heading above or beside the fields; unset stacks, or splits inside `Settings` |
+| `disabled` | `boolean` | `false` | Native fieldset disabling for every field and action |
+| `classNames` | `{ header?, title?, description?, body?, fields?, error?, actions? }` | unset | Classes for inner parts |
+
+Other native `fieldset` props and `ref` pass through. A caller `aria-describedby` follows the description and error ids, and a caller `aria-invalid` token such as `"spelling"` is kept. The section heading names the group with `aria-labelledby`, unless you pass `aria-label`: a native `legend` cannot sit in the split layout's first column.
+
+`Split` layout puts the header in one third and the fields in two thirds when the section is at least `--kb-formsection-collapse` (40rem) wide, and stacks them below that. Actions sit last in the section body, end-aligned. Below 30rem of row width, each button or link in the actions fills its own row so targets stay wide on phones; other content, such as a spinner, keeps its size. Tokens: `--kb-formsection-gap`, `--kb-formsection-header-gap`, `--kb-formsection-fields-gap` and `--kb-formsection-collapse`.
+
+Your app owns validation, saving and the announcement of saved or failed sections. While saving, pass `disabled` and `aria-busy`. Native disabling takes focus away from the pressed Save button, so move focus to a status message outside the section (`role="status"`, `tabIndex={-1}`) and report the result there.
+
+## Related components
+
+Use [`Fieldset`](Fieldset.md) for a question-style group with a legend inside a section, [`FormActions`](FormActions.md) for a form-wide action row and [`ErrorSummary`](ErrorSummary.md) for recovery after a failed submit.

package/docs/components/Gallery.md

@@ -0,0 +1,84 @@
+# Gallery
+
+Use `Gallery` for a page of image-led items, such as a product catalog, a portfolio or a media library. It is the page frame, up to 80rem wide, with a header region, an optional filters region and the items as a list, with one to four columns as the gallery widens. For records you scan by text, use [`CollectionList`](CollectionList.md) or [`Table`](Table.md); for a handful of metrics or links, use [`Grid`](Grid.md).
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/layout-gallery--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Button, Card, Gallery, Grid, Heading, Image, Input, PageHeader, Text } from "@kb.ui/react";
+import { useState } from "react";
+
+const products = [
+  { id: "classic", name: "The Schu Classic", price: 89, src: "/schu-classic.jpg", alt: "Sage knit sneaker with a white sole" },
+  { id: "trail", name: "The Schu Trail", price: 99, src: "/schu-trail.jpg", alt: "Charcoal knit sneaker with an amber sole" },
+];
+
+export function Example() {
+  const [query, setQuery] = useState("");
+  const visible = products.filter((product) => product.name.toLowerCase().includes(query.toLowerCase()));
+  return (
+    <main>
+      <Gallery
+        header={<PageHeader title="Sneakers" description="Our own model beside the brands you love." />}
+        filters={
+          <>
+            <Input label="Search" type="search" value={query} onChange={(event) => setQuery(event.currentTarget.value)} />
+            <Text role="status" size="sm" tone="muted">
+              {visible.length === 1 ? "1 sneaker" : `${visible.length} sneakers`}
+            </Text>
+          </>
+        }
+        itemsLabel="Sneakers"
+        empty={<Text>No sneakers match your search.</Text>}
+      >
+        {visible.map((product, index) => (
+          <Gallery.Item key={product.id} featured={index === 0}>
+            <Card aria-labelledby={`${product.id}-name`}>
+              <Grid layout="stack" gap="sm">
+                <Image src={product.src} alt={product.alt} ratio={index === 0 ? "wide" : "landscape"} loading="lazy" />
+                <Heading level={2} size="sm" id={`${product.id}-name`}>
+                  {product.name}
+                </Heading>
+                <Text>${product.price}</Text>
+                <Button variant="secondary">
+                  Add to cart<span className="kb-sr-only">, {product.name}</span>
+                </Button>
+              </Grid>
+            </Card>
+          </Gallery.Item>
+        ))}
+      </Gallery>
+    </main>
+  );
+}
+```
+
+## More examples
+
+- [Product catalog](https://kbui.kcb.pro/storybook/?path=/story/layout-gallery--product-catalog): A sneaker shop that features its own model, with search, brand and sort filters.
+- [No results](https://kbui.kcb.pro/storybook/?path=/story/layout-gallery--no-results): The empty region replaces the list until the filters are cleared.
+- [Inspection](https://kbui.kcb.pro/storybook/?path=/story/layout-gallery--inspection): Square thumbnails that open a full, uncropped preview in a `Dialog`.
+
+## Reference
+
+| Part / prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `header` | `ReactNode` | unset | Page title, intro and actions; usually a `PageHeader` |
+| `filters` | `ReactNode` | unset | Search, filter and sort controls and a result count |
+| `itemsLabel` | `string` | unset | Accessible name for the item list |
+| `empty` | `ReactNode` | unset | Shown in place of the list when there are no items |
+| `classNames` | `{ header?, filters?, items?, empty? }` | unset | Classes for the regions |
+| `Gallery.Item` | native `li` props | `li` | One item; `featured` spans two columns once the list has two |
+
+Other native `div` props and `ref` pass through to the root; `Gallery.Item` forwards its own. The items region is a [`Grid`](Grid.md) rendered as `ul`, so wrap every item in `Gallery.Item`.
+
+Placement is fixed in the stylesheet and measured on the gallery's own width, not the viewport: one column below 30rem, two from 30rem, three from 48rem and four from 64rem. Filters share a row, each at least 12rem wide, and wrap below it. Item content stretches to the row height; spacing inside an item belongs to its content, such as a stacked `Grid`. Pass items directly or inside fragments: a component that renders no items still counts as one, so `empty` cannot replace the list. Put featured items first: the list keeps DOM order and does not backfill gaps. `Gallery` is also the page frame: it fills its parent up to 80rem, centred, with gutters of 1rem, then 1.5rem from 48rem and 2rem from 64rem of viewport width, so do not wrap it in a [`Container`](Container.md). Tokens: `--kb-gallery-max-width`, `--kb-gallery-gutter-sm`, `--kb-gallery-gutter-md`, `--kb-gallery-gutter-lg`, `--kb-gallery-gap`, `--kb-gallery-filters-gap` and `--kb-gallery-filter-min-width`.
+
+Give every meaningful image an `alt` that says what differs between items, such as colour or material; repeat nothing the item heading already says. Name each item with its heading and include that name in item actions. Announce result counts after filtering with a status message, and when a recovery action such as "Clear filters" removes the empty region, move focus to the control it reset. Your app owns data, filtering, pagination and cart state.
+
+## Related components
+
+Frame media with [`Image`](Image.md) or [`Thumbnail`](Thumbnail.md), open the page with [`PageHeader`](PageHeader.md), show an empty result with [`EmptyState`](EmptyState.md) and inspect an item in a [`Dialog`](Dialog.md).

package/docs/components/Grid.md

@@ -1,6 +1,6 @@
 # Grid
 
-Arrange cards or other content in responsive columns, fixed column counts, or a single vertical stack. Grid uses ordinary CSS layout, without an ARIA grid role or special keyboard navigation, and resets native list markers and margins when rendered as `ul` or `ol`.
+Arrange cards or other content in responsive columns, fixed column counts, or a single vertical stack. `Grid` uses ordinary CSS layout, without an ARIA grid role or special keyboard navigation, and resets native list markers and margins when rendered as `ul` or `ol`.
 
 [All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/layout-grid--docs)
 
@@ -35,16 +35,16 @@ export function Example() {
 
 ## Reference
 
-| Prop                        | Type                                                | Default                | Notes                                                                                          |
-| --------------------------- | --------------------------------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------- |
-| `as`                        | `div` / `ul` / `ol`                                 | `div`                  | Use ul or ol for a collection; children must then be list items                                |
-| `layout`                    | `auto` / `stack`                                    | `auto`                 | Auto fits equal columns to available width; stack uses one column                              |
-| `columns`                   | `auto` / `1` / `2` / `3` / `4`                      | `auto`                 | Explicit equal column count (collapsing to 1 on narrow mobile viewports) or automatic wrapping |
-| `minItemWidth`              | `sm` / `md` / `lg`                                  | `md`                   | Minimum width (`14rem`, `18.75rem`, `24rem`) before automatic columns wrap                     |
-| `gap`                       | `none` / `sm` / `md` / `lg`                         | `lg` (`--kb-grid-gap`) | Space between columns and stacked rows                                                         |
-| `align`                     | `start` / `center` / `end` / `baseline` / `stretch` | `stretch`              | Cross-axis alignment within each grid row                                                      |
-| `children`                  | `ReactNode`                                         | unset                  | Content in document and keyboard order                                                         |
-| `className`, `style`, `ref` | native element props                                | unset                  | Style and reference the chosen container                                                       |
+| Prop                        | Type                                                | Default                | Notes                                                                                                    |
+| --------------------------- | --------------------------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------- |
+| `as`                        | `div` / `ul` / `ol`                                 | `div`                  | Use ul or ol for a collection; children must then be list items                                          |
+| `layout`                    | `auto` / `stack`                                    | `auto`                 | Auto fits equal columns to available width; stack uses one column                                        |
+| `columns`                   | `auto` / `1` / `2` / `3` / `4`                      | `auto`                 | Explicit equal column count (collapsing to 1 when the grid is narrower than 30rem) or automatic wrapping |
+| `minItemWidth`              | `sm` / `md` / `lg`                                  | `md`                   | Minimum width (`14rem`, `18.75rem`, `24rem`) before automatic columns wrap                               |
+| `gap`                       | `none` / `sm` / `md` / `lg`                         | `lg` (`--kb-grid-gap`) | Space between columns and stacked rows                                                                   |
+| `align`                     | `start` / `center` / `end` / `baseline` / `stretch` | `stretch`              | Cross-axis alignment within each grid row                                                                |
+| `children`                  | `ReactNode`                                         | unset                  | Content in document and keyboard order                                                                   |
+| `className`, `style`, `ref` | native element props                                | unset                  | Style and reference the chosen container                                                                 |
 
 ```tsx
 <Grid as="ul" role="list" layout="stack" gap="md" aria-label="Projects">
@@ -59,8 +59,8 @@ export function Example() {
 
 Use `minItemWidth`, `columns`, `gap`, and `align` for common layouts, or override `--kb-grid-gap` and `--kb-grid-min-item-width` (`-sm`, `-md`, `-lg`) on a subtree. Keep the visual order the same as the reading order.
 
-Grid removes list markers. Include `role="list"` on list renderings to retain list exposure in Safari when `list-style: none` is applied; see [MDN’s list-style accessibility guidance](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/list-style#accessibility). Confirm list/item announcement with your supported browser and screen reader.
+`Grid` removes list markers. Include `role="list"` on list renderings to retain list exposure in Safari when `list-style: none` is applied; see [MDN’s list-style accessibility guidance](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/list-style#accessibility). Confirm list/item announcement with your supported browser and screen reader.
 
 ## Related components
 
-Use [Split](Split.md) for exactly two weighted columns and [Inline](Inline.md) for a wrapping row of independent items.
+Use [`Split`](Split.md) for exactly two weighted columns, [`Inline`](Inline.md) for a wrapping row of independent items, and [`Stack`](Stack.md) for vertical flow that never forms columns.