@kb.ui/react 0.10.4 → 0.12.0

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

@@ -0,0 +1,61 @@
+# DescriptionList
+
+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)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { DescriptionList, Link, Status } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <DescriptionList aria-label="Project details">
+      <DescriptionList.Item>
+        <DescriptionList.Term>Owner</DescriptionList.Term>
+        <DescriptionList.Detail><Link href="/people/ada">Ada Chen</Link></DescriptionList.Detail>
+      </DescriptionList.Item>
+      <DescriptionList.Item>
+        <DescriptionList.Term>Status</DescriptionList.Term>
+        <DescriptionList.Detail><Status tone="success">Ready for review</Status></DescriptionList.Detail>
+      </DescriptionList.Item>
+      <DescriptionList.Item>
+        <DescriptionList.Term>Open tasks</DescriptionList.Term>
+        <DescriptionList.Detail>{0}</DescriptionList.Detail>
+      </DescriptionList.Item>
+    </DescriptionList>
+  );
+}
+```
+
+## More examples
+
+- [Responsive](https://kbui.kcb.pro/storybook/?path=/story/components-descriptionlist--responsive): Stacks according to its parent width.
+- [Nested details](https://kbui.kcb.pro/storybook/?path=/story/components-descriptionlist--nested): Independent density and layout inside another detail value.
+
+## Reference
+
+| Part | Native element | Purpose |
+|---|---|---|
+| `DescriptionList` | `dl` | Root description list; native naming attributes, children, styles and ref pass through |
+| `DescriptionList.Item` | `div` | Groups one Term with one or more Detail elements |
+| `DescriptionList.Term` | `dt` | Meaningful label in reading order before its values |
+| `DescriptionList.Detail` | `dd` | Text, numbers, links, status or richer content; repeated Details support multiple values |
+
+| Prop | Default | Behavior |
+|---|---|---|
+| `layout` | `responsive` | `responsive` uses label/value columns, stacking below 32rem of available width; `horizontal` keeps columns; `stacked` always puts values below labels |
+| `density` | `comfortable` | `comfortable` or `dense`; changes immediate Item spacing |
+| `dividers` | true | Rules between immediate groups |
+
+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.
+
+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.

package/docs/components/Dialog.md

@@ -0,0 +1,84 @@
+# Dialog
+
+`Dialog` is composed from parts. Base UI handles focus trapping, closing on Escape and scroll locking.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-dialog--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Button, Dialog } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <Dialog>
+      <Dialog.Trigger render={<Button />}>View details</Dialog.Trigger>
+      <Dialog.Content
+        title="Project details"
+        description="Current project status."
+      >
+        <p>Three tasks remain.</p>
+        <Dialog.Actions>
+          <Dialog.Close render={<Button />}>Done</Dialog.Close>
+        </Dialog.Actions>
+      </Dialog.Content>
+    </Dialog>
+  );
+}
+```
+
+## More examples
+
+- [A confirmation task](https://kbui.kcb.pro/storybook/?path=/story/components-dialog--confirm): Open and close a modal from its trigger.
+- [Structured content](https://kbui.kcb.pro/storybook/?path=/story/components-dialog--sections): Inspect header, body, footer, and actions; opens a modal.
+- [A custom layout](https://kbui.kcb.pro/storybook/?path=/story/components-dialog--custom-layout): Inspect composed titles and descriptions; opens a modal.
+
+## Reference
+
+| Part                                            | Purpose                                                                                                                       |
+| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `Dialog`                                        | Root. Accepts `open`, `defaultOpen` and `onOpenChange` for controlled use.                                                    |
+| `Dialog.Trigger`                                | Opens the dialog. Use `render={<Button />}` to style it as a button.                                                          |
+| `Dialog.Content`                                | The dialog. `title` and `description` set its accessible name and description; `container` changes where it mounts.           |
+| `Content.layout` | `"center"` (default) or `"drawer"`; drawer slides from inline end, uses `--kb-dialog-width` and scrolls direct Body independently. |
+| `Dialog.Title`, `Dialog.Description`            | For custom layouts. Use these or the `Dialog.Content` props in a given dialog, not both, or it gets two titles.               |
+| `Dialog.Header`, `Dialog.Body`, `Dialog.Footer` | Optional structured sections; accept native `div` props and refs. Centered padding follows `--kb-dialog-{header,body,footer}-padding`; drawer sections use `--kb-dialog-padding`. |
+| `Dialog.Actions`                                | Aligns buttons along the bottom right.                                                                                        |
+| `Dialog.Close`                                  | Closes the dialog.                                                                                                            |
+
+| 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      |
+| `container` on Content   | portal container | document body | Themed host for a nested dialog                                               |
+
+```tsx
+<Dialog>
+  <Dialog.Trigger render={<Button />}>Open</Dialog.Trigger>
+  <Dialog.Content title="Rename file">
+    <Input label="Name" />
+    <Dialog.Actions>
+      <Dialog.Close render={<Button variant="ghost" />}>Cancel</Dialog.Close>
+      <Button>Save</Button>
+    </Dialog.Actions>
+  </Dialog.Content>
+</Dialog>
+```
+
+## Related components
+
+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
+
+The [overlay guide](../../../../docs/guides/forms-and-overlays.md#drawer-pattern) supplies complete drawer and asynchronous confirmation modules. Drawers use `Content layout="drawer"` with direct Header, Body and Footer sections. Header/actions remain visible while Body scrolls; the drawer follows logical direction and dynamic viewport height. Content title/description props automatically form a drawer Header. Focus a composed title initially for long content. Confirmations focus Cancel first, reject duplicate/pending dismissal, retain errors for retry and close only after success.
+
+- [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.

package/docs/components/Disclosure.md

@@ -0,0 +1,53 @@
+# Disclosure
+
+Reveal optional details or advanced controls inline. Base UI Collapsible owns the open state, trigger relationship and hidden panel behavior.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-disclosure--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Disclosure, Input } from "@kb.ui/react";
+
+export function AdvancedSettings() {
+  return (
+    <Disclosure>
+      <Disclosure.Trigger>Advanced settings</Disclosure.Trigger>
+      <Disclosure.Panel keepMounted>
+        <Input label="Reply-to address" defaultValue="team@example.com" />
+      </Disclosure.Panel>
+    </Disclosure>
+  );
+}
+```
+
+## More examples
+
+- [Retained draft](https://kbui.kcb.pro/storybook/?path=/story/components-disclosure--retained-draft): preserve an uncontrolled field through collapse.
+- [Controlled](https://kbui.kcb.pro/storybook/?path=/story/components-disclosure--controlled): caller-owned open state.
+- [Disabled](https://kbui.kcb.pro/storybook/?path=/story/components-disclosure--disabled): unavailable details.
+
+## Reference
+
+| Part / prop | Type | Default | Purpose |
+|---|---|---|---|
+| `Disclosure` | Base UI Collapsible root props | `div` | Groups trigger and panel; accepts native props and ref. |
+| `open` / `defaultOpen` | `boolean` | `false` | Controlled or initial expansion. |
+| `onOpenChange` | `(open, details) => void` | — | Requests a state change; `details.cancel()` rejects it. |
+| `disabled` | `boolean` | `false` | Prevents user toggling. |
+| `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`. |
+| `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.
+
+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.
+
+## 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.

package/docs/components/EmptyState.md

@@ -0,0 +1,50 @@
+# EmptyState
+
+Explain why a collection, search result, or section has no content to show, and provide the direct action that populates or recovers it.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-emptystate--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Button, EmptyState } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <EmptyState
+      eyebrow="Pipelines"
+      title="No release pipelines configured"
+      description="Create a pipeline to validate builds and publish signed packages."
+      actions={<Button size="sm">Create pipeline</Button>}
+    />
+  );
+}
+```
+
+## More examples
+
+- [Filtered zero results](https://kbui.kcb.pro/storybook/?path=/story/components-emptystate--filtered-zero-results): Give people a one-click way to clear active filters or widen their query.
+- [Recoverable section failure](https://kbui.kcb.pro/storybook/?path=/story/components-emptystate--recoverable-failure): Explain when a section failed to load and pair the explanation with a retry action.
+- [Surface variants](https://kbui.kcb.pro/storybook/?path=/story/components-emptystate--variants-and-sizes): Choose `surface`, `subtle`, or `plain` containers to match surrounding hierarchy.
+
+## Reference
+
+| Prop           | Type                                         | Default   | Notes                                                                                  |
+| -------------- | -------------------------------------------- | --------- | -------------------------------------------------------------------------------------- |
+| `title`        | `ReactNode`                                  | required  | Heading text naming what is missing or unavailable                                     |
+| `description`  | `ReactNode`                                  | unset     | Supporting guidance explaining how to populate or recover the view                     |
+| `eyebrow`      | `ReactNode`                                  | unset     | Short uppercase label above the title                                                  |
+| `icon`         | `ReactNode`                                  | unset     | Decorative emblem above the header; hidden from assistive technology                   |
+| `actions`      | `ReactNode`                                  | unset     | Primary and secondary buttons or links that resolve the empty state                    |
+| `footer`       | `ReactNode`                                  | unset     | Quiet footnote, error code, or secondary hint below actions                            |
+| `headingLevel` | `2` / `3` / `4`                              | `3`       | Semantic heading tag (`h2`–`h4`) matching the surrounding document outline             |
+| `variant`      | `surface` / `subtle` / `plain`               | `surface` | Raised bordered card, dashed recessed well, or borderless inline block                 |
+| `size`         | `sm` / `md` / `lg`                           | `md`      | Scales padding, icon badge, and heading typography                                     |
+| `tone`         | `neutral` / `info` / `warning` / `danger`    | `neutral` | Accentuates the icon badge and border for informational or failure states              |
+| `live`         | `boolean`                                    | `false`   | Adds `role="status"` when revealed dynamically after filtering or an async load error  |
+| `classNames`   | keyed classes                                | unset     | Style `icon`, `header`, `eyebrow`, `title`, `description`, `body`, `actions`, `footer` |
+
+## 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.

package/docs/components/ErrorSummary.md

@@ -0,0 +1,48 @@
+# 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.
+
+[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)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { ErrorSummary, Input } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <form noValidate>
+      <ErrorSummary
+        items={[{ href: "#email", label: "Enter an email address." }]}
+      />
+      <Input id="email" label="Email" error="Enter an email address." />
+    </form>
+  );
+}
+```
+
+This example shows a failed-submission state. The Form recovery story below demonstrates validation and moving focus to the summary after submission.
+
+## More examples
+
+- [Recover after submission](https://kbui.kcb.pro/storybook/?path=/story/components-errorsummary--form-recovery): Run validation, focus the summary, and jump to invalid fields.
+
+## Reference
+
+| Prop           | Type                                                                 | Default                | Notes                                                            |
+| -------------- | -------------------------------------------------------------------- | ---------------------- | ---------------------------------------------------------------- |
+| `items`        | `readonly ErrorSummaryItem[]`                                        | required               | Ordered `{ id?, href, label }` entries linking to invalid fields |
+| `title`        | `ReactNode`                                                          | `"There is a problem"` | Heading text naming the alert region                             |
+| `description`  | `ReactNode`                                                          | unset                  | Optional recovery guidance above the error list                  |
+| `headingLevel` | `2 \| 3 \| 4`                                                        | `2`                    | Heading rank for the summary title                               |
+| `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.
+
+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.

package/docs/components/Fieldset.md

@@ -0,0 +1,42 @@
+# 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.
+
+[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)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Fieldset, Input } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <Fieldset legend="Contact details" description="How we can reach you.">
+      <Input label="Email" type="email" name="email" />
+    </Fieldset>
+  );
+}
+```
+
+## More examples
+
+- [A group-level error](https://kbui.kcb.pro/storybook/?path=/story/components-fieldset--with-error): Explain a correction for a named group.
+- [An unavailable group](https://kbui.kcb.pro/storybook/?path=/story/components-fieldset--disabled): Inspect disabled descendant controls.
+
+## Reference
+
+| Prop             | Type                                                           | Default  | Notes                                                  |
+| ---------------- | -------------------------------------------------------------- | -------- | ------------------------------------------------------ |
+| `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`      |
+| `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.
+
+## 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.

package/docs/components/FileInput.md

@@ -0,0 +1,74 @@
+# 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.
+
+[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)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { FileInput, type FileInputItem } from "@kb.ui/react";
+import { useState } from "react";
+
+type Attachment = FileInputItem & { file: File };
+
+export function Example() {
+  const [items, setItems] = useState<Attachment[]>([]);
+  return (
+    <FileInput
+      label="Attachments"
+      items={items}
+      onFiles={(files) =>
+        setItems((current) => [
+          ...current,
+          ...files.map((file) => ({
+            id: crypto.randomUUID(),
+            name: file.name,
+            file,
+          })),
+        ])
+      }
+      onRemove={(id) =>
+        setItems((current) => current.filter((item) => item.id !== id))
+      }
+    />
+  );
+}
+```
+
+The example retains each original `File` alongside its display metadata. Your app chooses acceptance rules and builds `FormData` for uploads; see [retained file selection](https://github.com/KhallilB/kbui/blob/main/docs/guides/file-inputs.md#choosing-and-removing-files).
+
+## More examples
+
+- [Rejected selection feedback](https://kbui.kcb.pro/storybook/?path=/story/components-fileinput--rejected): Keep accepted items visible while explaining a rejection.
+- [Image-picker hints](https://kbui.kcb.pro/storybook/?path=/story/components-fileinput--evidence): Compare image acceptance hints and helper text.
+- [Item metadata](https://kbui.kcb.pro/storybook/?path=/story/components-fileinput--custom-content): Customize retained-file content without losing its identity.
+
+## Reference
+
+| Prop                                                 | Type                                 | Default                 | Notes                                                                |
+| ---------------------------------------------------- | ------------------------------------ | ----------------------- | -------------------------------------------------------------------- |
+| `label`                                              | `string`                             | required                | Visible field name and accessible picker context                     |
+| `items`                                              | `readonly FileInputItem[]`           | required                | Retained files with stable ids, names, and optional descriptions     |
+| `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 |
+| `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           |
+| `chooseLabel`                                        | `string`                             | Choose files            | Localized visible picker action                                      |
+| `emptyMessage`                                       | `string`                             | No files added.         | Localized empty-state text                                           |
+| `removeLabel`                                        | `(item: FileInputItem) => string`    | Remove + filename       | Accessible remove action; keep the filename in the name              |
+| `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                        |
+| `triggerClassName`, `listClassName`, `itemClassName` | `string`                             | unset                   | Classes for picker, retained list, and items                         |
+
+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 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

@@ -0,0 +1,45 @@
+# 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.
+
+[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)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Button, FormActions, Input } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <form onSubmit={(event) => event.preventDefault()}>
+      <Input label="Project name" name="project" />
+      <FormActions divider>
+        <Button type="submit">Save changes</Button>
+        <Button type="reset" variant="ghost">
+          Reset
+        </Button>
+      </FormActions>
+    </form>
+  );
+}
+```
+
+## More examples
+
+- [Separate the action row](https://kbui.kcb.pro/storybook/?path=/story/components-formactions--with-divider): Keep a boundary above the actions.
+- [Primary and secondary groups](https://kbui.kcb.pro/storybook/?path=/story/components-formactions--split-alignment): Compare actions at opposite ends of the row.
+
+## Reference
+
+| Prop       | Type                            | Default | Notes                                              |
+| ---------- | ------------------------------- | ------- | -------------------------------------------------- |
+| `align`    | `"end" \| "start" \| "between"` | `"end"` | Horizontal button alignment                        |
+| `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.
+
+## 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.