@kb.ui/react 0.10.4 → 0.12.0

package/docs/components/Table.md

@@ -0,0 +1,105 @@
+# Table
+
+Present related records with native table semantics, optional controlled sorting and selection, and independent row actions. Your app owns records, stable IDs, ordering, selection and requests.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-table--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Table, type TableSortDirection } from "@kb.ui/react";
+import { useState } from "react";
+
+const records = [{ id: "ada", name: "Ada Chen" }, { id: "lin", name: "Lin Patel" }];
+
+export function Example() {
+  const [direction, setDirection] = useState<TableSortDirection>("ascending");
+  const [selected, setSelected] = useState<string[]>([]);
+  const ordered = [...records].sort((a, b) => a.name.localeCompare(b.name) * (direction === "descending" ? -1 : 1));
+  const selectedCount = records.filter((record) => selected.includes(record.id)).length;
+  return (
+    <>
+      <p role="status">{selectedCount} people selected</p>
+      <Table.ScrollContainer label="People scroll area" maxHeight="20rem">
+        <Table density="dense" stickyHeader>
+          <Table.Caption>People</Table.Caption>
+          <Table.Head><Table.Row>
+            <Table.ColumnHeader>
+              <Table.SelectionCheckbox visuallyHidden label="Select all people" checked={selectedCount === records.length} indeterminate={selectedCount > 0 && selectedCount < records.length} onCheckedChange={(checked) => setSelected(checked ? records.map((record) => record.id) : [])} />
+            </Table.ColumnHeader>
+            <Table.ColumnHeader sortDirection={direction} onSortChange={setDirection}>Name</Table.ColumnHeader>
+            <Table.ColumnHeader align="end">Actions</Table.ColumnHeader>
+          </Table.Row></Table.Head>
+          <Table.Body>{ordered.map((record) => (
+            <Table.Row key={record.id} selected={selected.includes(record.id)}>
+              <Table.Cell><Table.SelectionCheckbox visuallyHidden label={`Select ${record.name}`} checked={selected.includes(record.id)} onCheckedChange={(checked) => setSelected(checked ? [...selected, record.id] : selected.filter((id) => id !== record.id))} /></Table.Cell>
+              <Table.RowHeader>{record.name}</Table.RowHeader>
+              <Table.Cell><Table.RowActions><a href={`/people/${record.id}`}>View {record.name}</a></Table.RowActions></Table.Cell>
+            </Table.Row>
+          ))}</Table.Body>
+        </Table>
+      </Table.ScrollContainer>
+    </>
+  );
+}
+```
+
+## More examples
+
+- [Sorting and selection](https://kbui.kcb.pro/storybook/?path=/story/components-table--sorting-and-selection): Numeric and text ordering, stable selected IDs, mixed selection and excluded rows.
+- [Row actions](https://kbui.kcb.pro/storybook/?path=/story/components-table--sorting-and-selection): Named Buttons and `Menu` composition with focus return.
+- [Dense and sticky](https://kbui.kcb.pro/storybook/?path=/story/components-table--dense-sticky): Bounded scrolling, sticky headers and a pinned first column.
+
+## Reference
+
+| Part | Native element | Purpose |
+|---|---|---|
+| `Table` | `table` | Named data table; forwards table attributes, children and ref |
+| `Table.ScrollContainer` | `section` | Named focusable scroll region; `label` required, `maxHeight` optional CSS length |
+| `Table.Caption` | `caption` | Visible table name; use a caption or native `aria-label`/`aria-labelledby` |
+| `Table.Head`, `Table.Body`, `Table.Foot` | `thead`, `tbody`, `tfoot` | Native row groups; `aria-busy` may mark pending rows |
+| `Table.Row` | `tr` | `selected` projects visual selection; checkbox communicates checked state |
+| `Table.ColumnHeader` | `th`, optional `button` | Defaults `scope="col"`; controlled sorting and logical alignment |
+| `Table.RowHeader` | `th` | Defaults `scope="row"`; supports grouped header scope override |
+| `Table.Cell` | `td` | Native data cell; supports `colSpan`, `rowSpan`, children and ref |
+| `Table.SelectionCheckbox` | `Checkbox` | Same required `label`, `checked`, `onCheckedChange`, optional `indeterminate`, `disabled`, `readOnly`, ref and slots as `Checkbox` |
+| `Table.RowActions` | `div` | Wrapping, end-aligned actions; compose named Buttons, links or `Menu` |
+
+| Prop | Applies to | Default | Behavior |
+|---|---|---|---|
+| `density` | `Table` | `comfortable` | `comfortable` or `dense`; controls cell spacing, preserves control targets |
+| `layout` | `Table` | `auto` | `auto` or `fixed`; with fixed layout supply widths through native `colgroup`/`col` or styles |
+| `stickyHeader` | `Table` | false | Pins the complete head, including grouped header rows, to the scroll boundary |
+| `align` | Cell, ColumnHeader, RowHeader | `start` | Logical `start`, `center`, `end`; works with `dir="rtl"` |
+| `sticky` | Cell, ColumnHeader, RowHeader | unset | Pins one `start` or `end` edge cell; match the same edge across rows |
+| `sortDirection` | ColumnHeader | `none` | `none`, `ascending`, `descending`; explicit direction owns `aria-sort`, otherwise native `aria-sort` passes through |
+| `onSortChange` | ColumnHeader | unset | Enables sort button; requests ascending from none, then toggles ascending/descending |
+| `sortDisabled` | ColumnHeader | false | Disables sort button, preserves announced order |
+| `classNames` | ColumnHeader | unset | Adds `sortButton`, `sortIcon` slot classes; root uses `className` |
+
+Every part accepts its native element attributes, `style`, `className` and ref. The checkbox forwards its ref to the input. Public prop types follow `Table<Part>Props`; root uses `TableProps`, sorting uses `TableSortDirection`, shared cell options use `TableCellOptions`. The sort button is `type="button"`; sorting inside forms does not submit them. Put text and decorative content in sortable headers; nested interactive children would create invalid nested controls.
+
+### Sorting and selection ownership
+
+Sortable headings use the full cell as the button target. Unsorted headings show paired arrows; the applied order uses one arrow with stronger ink. Keep headings readable with native column widths and a bounded scroll container. Fixed-layout sortable headings wrap within their assigned columns. Reserve a compact checkbox column, align numeric headings with their values, and keep row action labels short while supplying record-specific accessible names. The sorting example places its title, instructions and selection count outside scrolling data, with visible text explaining unavailable selection.
+
+Sort a copy of your data or request server ordering. Keep the column and direction together; reset other headers to `none` so only one header announces an active sort. For server requests, handle stale responses in your app, keep applied order authoritative, set `sortDisabled` while pending, and announce progress through a status message outside an `aria-busy` body. `Table` does not mutate or fetch records. It does not implement multiple simultaneous sort keys.
+
+Keep selection by stable ID rather than visible row index. Define whether select-all covers the current page, filtered results or all records; label that scope explicitly. Compute mixed/all state from eligible rows only, exclude disabled rows, and disable select-all when no rows are eligible. Decide how removed records and page changes affect selection. `Table.Row selected` provides styling; selection controls own the accessible state. Row actions have their own names and normal Tab order, and do not toggle selection implicitly.
+
+### Layout and feedback
+
+Place the table inside `Table.ScrollContainer` for horizontal overflow or a bounded vertical viewport. Its region is keyboard focusable; `maxHeight` limits height. On focus, the React container reveals controls hidden beneath sticky headers or pinned edges without moving keyboard focus. Keep enough free viewport space for the action; a pinned column wider than the viewport cannot expose adjacent cells. In auto layout, headings and cells keep whole words, so a table narrower than its longest words scrolls instead of breaking them; supply a minimum table width with `style` when columns need more room. Fixed layout breaks long words within its assigned columns. A table can also render directly when page scrolling is sufficient. To keep the table title fixed on both scroll axes, render a `Heading` outside `ScrollContainer` and name the table through `aria-labelledby`, as in Dense and sticky. Native `Table.Caption` remains part of the scrollable table. Column headings stay fixed vertically with `stickyHeader` and scroll horizontally with their data columns.
+
+Sticky edges support one cell on each edge. For several pinned columns, calculate non-overlapping offsets in your own styles; `Table` does not assign column offsets. Keep sufficient viewport space for unpinned cells. Header/body column widths must match. Set `dir="rtl"` on the application or ScrollContainer as well as the table when the scroll direction should follow RTL; the stories expose a direction control. Nested tables keep their own density and section surfaces. Native `colSpan`, `rowSpan`, `scope="colgroup"` and explicit `id`/`headers` relationships support grouped headers. Sticky and selected cell backgrounds stay opaque in both themes; restyled background tokens must remain opaque.
+
+Render empty or error feedback in a row containing a `Table.Cell colSpan={columnCount}`; supply retry as a named `Button` if appropriate. Use a separate status for asynchronous updates. `Table` preserves semantic HTML and ordinary Tab navigation; arrow-key cell navigation, pagination, filtering, virtualization and record management remain app-owned. For very large sets, paginate in your app rather than assuming all rows are virtualized.
+
+Adjust `--kb-table-cell-padding-block`, `--kb-table-cell-padding-inline`, `--kb-table-dense-padding-block`, `--kb-table-background`, `--kb-table-header-background`, `--kb-table-selected-background`, `--kb-table-border`, `--kb-table-radius` and `--kb-table-sort-target` through normal CSS. Keep focus visible and dense action targets usable. See [accessibility verification](../../../../docs/guides/accessibility.md) for manual keyboard, screen-reader, zoom, spacing and contrast checks. Automated stories do not establish screen-reader interoperability or page conformance.
+
+## Related components
+
+Use [`DescriptionList`](DescriptionList.md) for labeled facts about one record and [`CollectionList`](CollectionList.md) with [`CollectionRow`](CollectionRow.md) for records with variable details. The [Structured data guide](../../../../docs/guides/structured-data.md) compares these choices.
+
+Use [`Checkbox`](Checkbox.md) for independent selection, [`Menu`](Menu.md) for overflow actions, [`Button`](Button.md) for immediate actions, and [`Status`](Status.md) for meaningful asynchronous feedback. Use [`Grid`](Grid.md) for visual page layout rather than tabular relationships.

package/docs/components/Tabs.md

@@ -0,0 +1,89 @@
+# Tabs
+
+Switch between peer panels within one page. Use links for navigation to another URL and `RadioGroup` for a single form choice.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-tabs--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Tabs } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <Tabs defaultValue="summary">
+      <Tabs.List aria-label="Project sections">
+        <Tabs.Tab value="summary">Summary</Tabs.Tab>
+        <Tabs.Tab value="activity" badge="3">Activity</Tabs.Tab>
+      </Tabs.List>
+      <Tabs.Panel value="summary">Project summary</Tabs.Panel>
+      <Tabs.Panel value="activity">Recent activity</Tabs.Panel>
+    </Tabs>
+  );
+}
+```
+
+## More examples
+
+- [Section headers](https://kbui.kcb.pro/storybook/?path=/story/components-tabs--default): Select a release panel with arrow keys or a pointer.
+- [Compact time windows](https://kbui.kcb.pro/storybook/?path=/story/components-tabs--pill): Small pill tabs with a disabled option.
+- [Vertical settings](https://kbui.kcb.pro/storybook/?path=/story/components-tabs--vertical): Up/Down navigation beside settings content.
+- [Retained settings draft](https://kbui.kcb.pro/storybook/?path=/story/components-tabs--retained-draft): Manual activation retains an input while its panel is hidden.
+
+- [Nested panels](https://kbui.kcb.pro/storybook/?path=/story/components-tabs--nested): Each `Tabs` root owns its orientation, density and variant.
+
+## Reference
+
+| Part | Responsibility |
+| --- | --- |
+| `Tabs` | Selection owner, orientation, appearance and shared class names |
+| `Tabs.List` | Named tab list with roving keyboard focus; inserts an indicator by default |
+| `Tabs.Tab` | Named trigger with a unique value matching its panel |
+| `Tabs.Indicator` | Optional explicit active indicator inside the list |
+| `Tabs.Panel` | Content associated with a matching trigger |
+
+| `Tabs` prop | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `value` | `string \| number \| null` | — | Controlled selection; null selects no panel |
+| `defaultValue` | `string \| number \| null` | First enabled tab | Initial uncontrolled selection; null selects none |
+| `onValueChange` | `(value, details) => void` | — | Selection request with Base UI reason, event and cancel method |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Layout and keyboard axis |
+| `variant` | `"line" \| "pill"` | `"line"` | Underline or raised active surface |
+| `size` | `"sm" \| "md"` | `"md"` | Trigger density |
+| `className` | `string` | — | Root class |
+| `classNames` | `ClassNames<TabsClassKey>` | — | root, list, tab, `tabIcon`, `tabLabel`, `tabBadge`, indicator, panel |
+
+| Part prop | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `Tabs.List.activateOnFocus` | `boolean` | `true` | Select with arrow-key focus; false requires Enter/Space |
+| `Tabs.List.loopFocus` | `boolean` | `true` | Wrap focus at list ends |
+| `Tabs.List.showIndicator` | `boolean` | `true` | Insert automatic indicator; false leaves authored indicators intact |
+| `Tabs.Tab.value` | `string \| number` | Required | Stable unique selection key |
+| `Tabs.Tab.disabled` | `boolean` | `false` | Prevent selection; remain discoverable with arrow keys |
+| `Tabs.Tab.icon` | `ReactNode` | — | Decorative leading icon |
+| `Tabs.Tab.badge` | `ReactNode` | — | Trailing count/status included in accessible name |
+| `Tabs.Panel.value` | `string \| number` | Required | Matching trigger value |
+| `Tabs.Panel.keepMounted` | `boolean` | `false` | Retain hidden DOM and local draft state |
+
+All parts forward refs, native element props and Base UI composition props; `className` accepts a string. Keep triggers and panels inside their `Tabs` root. Put an explicit indicator directly inside `Tabs.List`, or set `showIndicator` to false when supplying a custom composition. Use unique values within each root and avoid interactive elements inside tab labels or badges.
+
+## Selection and focus
+
+Base UI owns selection, tab/panel relationships and roving focus. Tab enters the selected trigger; Left/Right moves horizontal focus, Up/Down moves vertical focus, and Home/End reaches the first/last trigger. Disabled tabs can receive arrow-key focus but cannot be selected. Automatic activation selects enabled tabs while moving; manual activation requires Enter or Space. Controlled values change only when the parent updates them. A null value selects no tab.
+
+Uncontrolled roots recover to an enabled tab when the selected tab is removed or disabled, reporting the reason through `onValueChange`. Controlled recovery belongs to the parent. User selection can be cancelled through details.cancel(); automatic fallback cannot. Applications own fetching, loading feedback and content availability. Prefer manual activation for panels that require loading.
+
+Inactive panels unmount by default. `keepMounted` preserves their DOM and draft state while hiding them from reading and keyboard navigation; hidden components can still run effects. Default values must match a tab when selecting a particular initial panel.
+
+## Styling and accessibility
+
+Each part receives its nearest root’s `data-variant`, `data-size` and `data-orientation`, so nested roots retain independent styling. Use the documented classes and component tokens: `--kb-tabs-radius`, `--kb-tabs-list-padding`, `--kb-tabs-tab-height-sm`, `--kb-tabs-tab-height-md`, `--kb-tabs-indicator-thickness` and `--kb-tabs-panel-padding`. The tab list scrolls horizontally when labels exceed available width. Vertical tabs place the list beside the panel from 48rem of their own width; at narrower widths, the panel moves beneath the list.
+
+For right-to-left interfaces, combine HTML `dir="rtl"` with Base UI `DirectionProvider direction="rtl"` so keyboard direction matches layout.
+
+Name `Tabs.List` with `aria-label` or `aria-labelledby`. Keep tab labels descriptive and use associated panels for peer views. Verify selected versus focused states, hidden panel controls, long labels, both themes, forced colors and enlarged text. Browser automation covers tested keyboard and accessibility fixtures; manual screen-reader and browser-zoom checks remain pending. See [shared verification](../../../../docs/guides/accessibility.md) and the informative [WAI-ARIA tabs pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/).
+
+## Related components
+
+Use [`RadioGroup`](RadioGroup.md) for a form choice and [`Toolbar`](Toolbar.md) for grouped actions.

package/docs/components/Text.md

@@ -0,0 +1,36 @@
+# Text
+
+Body paragraphs, inline text and block grouping.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-text--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Text } from "@kb.ui/react";
+
+export function Example() {
+  return <Text>Review the project details before saving changes.</Text>;
+}
+```
+
+## More examples
+
+- [Body and supporting copy](https://kbui.kcb.pro/storybook/?path=/story/components-text--sizes-and-tones): Compare text emphasis and measure.
+- [Inline text](https://kbui.kcb.pro/storybook/?path=/story/components-text--inline): Preserve surrounding document structure.
+
+## Reference
+
+| Prop               | Type                   | Default   | Notes                                                 |
+| ------------------ | ---------------------- | --------- | ----------------------------------------------------- |
+| `as`               | `p` \| `span` \| `div` | `p`       | Use span inside paragraphs; div for block children    |
+| `size`             | `sm` \| `md` \| `lg`   | `md`      | Existing small/body roles (13px, 15px), then 1.125rem |
+| `tone`             | `default` \| `muted`   | `default` | Primary ink or readable secondary ink                 |
+| `className`, `ref` | Native element props   | unset     | Ref type follows chosen element                       |
+
+Body text has a line height of 1.6 and a 65ch line-length limit set by `--kb-text-measure`. `Text` adds no margin. Inline spans stay in the flow of the sentence. Use native `<strong>` and `<em>` for emphasis. Keep paragraphs and other block elements outside the default paragraph.
+
+## Related components
+
+Use [`Heading`](Heading.md) for hierarchy, [`Link`](Link.md) for navigation, and [`Code`](Code.md) for literal code.

package/docs/components/Textarea.md

@@ -0,0 +1,47 @@
+# Textarea
+
+Use `Textarea` for multiline notes, summaries, or configuration payloads. It pairs a native `textarea` with a persistent label, optional help text, and validation feedback.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-textarea--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Textarea } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <Textarea
+      label="Review notes"
+      name="notes"
+      rows={5}
+      description="Explain what needs attention."
+    />
+  );
+}
+```
+
+## More examples
+
+- [Validation feedback](https://kbui.kcb.pro/storybook/?path=/story/components-textarea--with-error): Associate an error with multiline input.
+- [User resizing](https://kbui.kcb.pro/storybook/?path=/story/components-textarea--resize-modes): Compare allowed resize directions.
+
+## Reference
+
+| Prop             | Type                                                           | Default      | Notes                                                      |
+| ---------------- | -------------------------------------------------------------- | ------------ | ---------------------------------------------------------- |
+| `label`          | `string`                                                       | required     | Visible field label and accessible name                    |
+| `visuallyHidden` | `boolean`                                                      | `false`      | Hides the label visually while keeping its accessible name |
+| `description`    | `string`                                                       | unset        | Supporting help text below the control                     |
+| `error`          | `string`                                                       | unset        | Validation message; marks the control invalid              |
+| `rows`           | `number`                                                       | `4`          | Initial visible line count on the native `textarea`          |
+| `resize`         | `"vertical" \| "none" \| "both"`                               | `"vertical"` | Controls user drag-resizing axis                           |
+| `onValueChange`  | `(value: string) => void`                                      | unset        | Called with the next string value on change                |
+| `classNames`     | `ClassNames<"label" \| "control" \| "description" \| "error">` | unset        | Classes for inner parts                                    |
+
+Other native `textarea` props (`value`, `defaultValue`, `onChange`, `placeholder`, `disabled`, `readOnly`, `required`, `name`, `form`, `ref`) pass through to the `<textarea>` element. Adjust minimum height and padding with `--kb-textarea-min-height`, `--kb-textarea-padding-block`, and `--kb-textarea-padding-inline`.
+
+## Related components
+
+Use [`Input`](Input.md) for a single-line value and [`Fieldset`](Fieldset.md) to group related answers.

package/docs/components/Thumbnail.md

@@ -0,0 +1,66 @@
+# Thumbnail
+
+Pair stable image frames with visible titles and metadata for products, studies and attachments. Compose figures into responsive collections with `Grid`.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-thumbnail--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Grid, Link, Thumbnail } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <Grid as="ul" minItemWidth="sm" gap="lg">
+      <li>
+        <Thumbnail
+          src="/products/studio-coat.jpg"
+          alt="Sand wool coat with broad lapels"
+          ratio="portrait"
+          fit="contain"
+          caption={<Link href="/products/studio-coat">The studio coat</Link>}
+          description="Sand · Wool blend"
+          imageProps={{ loading: "lazy", width: 900, height: 1200 }}
+        />
+      </li>
+      <li>
+        <Thumbnail
+          alt=""
+          ratio="portrait"
+          fallback="PDF"
+          caption={<Link href="/brand-guide.pdf">Brand guide.pdf</Link>}
+          description="PDF · 2.4 MB"
+        />
+      </li>
+    </Grid>
+  );
+}
+```
+
+## More examples
+
+- [Products](https://kbui.kcb.pro/storybook/?path=/story/components-thumbnail--products): Responsive product cards and absent photography.
+- [Attachments](https://kbui.kcb.pro/storybook/?path=/story/components-thumbnail--attachments): Persistent filenames, formats and file sizes.
+- [Gallery](https://kbui.kcb.pro/storybook/?path=/story/components-thumbnail--gallery): Keyboard-operable `Dialog` inspection and focus return.
+
+## Reference
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `alt` | `string` | required | Meaningful visual alternative; empty when decorative |
+| `src` | `string` | unset | Preview source |
+| `ratio`, `fit`, `position`, `fallback` | `Image` props | `Image` defaults | Framing and non-interactive fallback |
+| `caption` | `ReactNode` | unset | Visible figure title; may contain `Link`, `Button` or `Dialog.Trigger` |
+| `description` | `ReactNode` | unset | Persistent supporting text such as format and size |
+| `imageProps` | remaining `Image` props | unset | Responsive source/loading attributes, callbacks, frame ref, style and `Image` slots |
+| `classNames` | keyed classes | unset | `root`, `media`, `caption`, `title`, `description` |
+| `ref` | `Ref<HTMLElement>` | unset | Native figure; remaining figure props apply here |
+
+A caption names the figure through `aria-labelledby`; caller naming attributes take precedence. Description is visible metadata within `figcaption`. Without either, no caption element is rendered. Figure and image remain non-interactive; caption actions own their native keyboard behavior. The component never infers file type, size or download policy from the URL.
+
+For a page of previews, put each `Thumbnail` in a [`Gallery`](Gallery.md) item. A named `Dialog` trigger in the caption supports enlarged inspection, Escape dismissal and focus return through `Dialog`. `Gallery` provides no carousel, arrow-key selection, image editor or upload. See [media recipes](../../../../docs/guides/media-and-identity.md#build-a-gallery-in-reading-order) for a complete implementation.
+
+## Related components
+
+Use [`Image`](Image.md) for an image alone, [`Avatar`](Avatar.md) for people, [`Grid`](Grid.md) for layout, and [`Dialog`](Dialog.md) for focused media inspection.

package/docs/components/Toast.md

@@ -0,0 +1,130 @@
+# Toast
+
+Use `Toast` for temporary feedback about background work. One provider owns the message list, timers and focus. Keep essential results available in the page or a notification history.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-toast--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Button, Toast, useToastManager } from "@kb.ui/react";
+
+function SaveButton() {
+  const { add } = useToastManager();
+  return (
+    <Button onClick={() => add({ title: "Changes saved", description: "Your project is up to date.", type: "success" })}>
+      Save changes
+    </Button>
+  );
+}
+
+export function Example() {
+  return (
+    <Toast.Provider timeout={5000} limit={3}>
+      <SaveButton />
+      <Toast.Viewport aria-label="Notifications" />
+    </Toast.Provider>
+  );
+}
+```
+
+Mount one `Toast.Viewport` inside each provider. Fixed placements portal to `document.body`; `placement="inline"` renders in normal layout without a portal. Choose a logical corner with `top-start`, `top-end`, `bottom-start` or `bottom-end`. For a nested theme, pass a mounted themed element or ref through `container`; otherwise the document theme applies. The provider and hook are scoped, so nested providers maintain independent messages.
+
+## Queue and timing
+
+Messages display newest first. `limit` defaults to `3`; older overflow messages remain mounted, hidden and inert. Dismissing a newer message reveals an older message if it has not expired. Timers continue for overflow messages. This is a temporary notification stack, not a FIFO delivery queue or durable history.
+
+`timeout` defaults to `5000` milliseconds; a per-message timeout overrides the provider. Set `timeout: 0` to keep a message until dismissed. Hover, keyboard focus in the viewport and window blur pause timers; leaving resumes the remaining duration. New messages added while paused also wait. Unmounting the provider clears its timers and subscriptions.
+
+Use `timeout: 0` for essential information or time-sensitive actions. Supply an application preference to disable or adjust time limits where the task requires it; hover/focus pause alone does not meet every requirement of [WCAG 2.2.1 Timing Adjustable, Level A](https://www.w3.org/WAI/WCAG22/Understanding/timing-adjustable.html).
+
+F6 moves focus into the viewport without notifications interrupting the current task. Tab reaches messages and actions. Escape dismisses the focused message. Dismissal keeps focus within remaining messages or returns it to the previous working control when the last message closes. Close buttons provide a pointer and keyboard alternative to swipe dismissal.
+
+## More examples
+
+- [Overflow and dismissal](https://kbui.kcb.pro/storybook/?path=/story/components-toast--queue): Hide older messages and reveal persistent messages as capacity returns.
+- [Undo action](https://kbui.kcb.pro/storybook/?path=/story/components-toast--with-action): Update an existing notification after an action.
+- [Timed dismissal](https://kbui.kcb.pro/storybook/?path=/story/components-toast--timed): Enter notifications with F6, dismiss with Escape and return to work.
+- [Promise states](https://kbui.kcb.pro/storybook/?path=/story/components-toast--promise-state): Keep message identity through loading and success.
+- [Custom composition](https://kbui.kcb.pro/storybook/?path=/story/components-toast--custom-composition): Render typed message data and a real navigation link.
+- [Positioned urgent message](https://kbui.kcb.pro/storybook/?path=/story/components-toast--positioned): Use a portaled corner viewport and a high-priority announcement.
+- [Long content](https://kbui.kcb.pro/storybook/?path=/story/components-toast--long-content): Check wrapping, actions and dismissal at narrow widths.
+
+## Reference
+
+### Toast.Provider
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | unset | Application content and one viewport |
+| `timeout` | `number` | `5000` | Milliseconds before dismissal; `0` disables automatic dismissal |
+| `limit` | `number` | `3` | Maximum visible active messages; use a positive integer |
+| `toastManager` | `ToastManager` | unset | Optional external manager created once per application or request |
+
+### Toast.Viewport
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `placement` | `ToastPlacement` | `bottom-end` | Four logical corners or `inline` |
+| `container` | `HTMLElement` or ref | `document.body` | Portal host for fixed placements; unused for inline |
+| `aria-label` | `string` | `Notifications` | Localize and distinguish the notification region |
+| `renderToast` | `(toast: ToastObject<Data>) => ReactNode` | complete `Toast` | Custom renderer; give each returned root `key={toast.id}` |
+| `children` | `ReactNode` | managed messages | Explicit children replace automatic rendering |
+| `className`, `ref`, DOM props | native `div` props | unset | Reach the viewport; Base UI `render` composition is supported |
+
+### Toast and parts
+
+| Prop or part | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `toast` | `ToastObject<Data>` | required | Message from the matching provider |
+| `tone` | `neutral`, `info`, `success`, `warning`, `danger` | from type | `error` maps to danger; loading maps to info; other types fall back to neutral |
+| `closeLabel` | `string` | `Dismiss notification` | Localized name for default close control |
+| `classNames` | content, title, description, action, close | unset | Extra classes for default slots |
+| `children` | `ReactNode` | complete message | Overrides default content and close control |
+| `swipeDirection` | Base UI swipe directions | down and right | Configure or disable with an empty array |
+| `Toast.Content` | content wrapper | div | Groups message content |
+| `Toast.Title` | heading | message title | Supplies the root accessible name |
+| `Toast.Description` | paragraph | message description | Supplies the root accessible description |
+| `Toast.Action` | button | message `actionProps` | Does not close automatically; explicitly call close or update |
+| `Toast.Close` | button | caller children | Dismisses its message; supply visible text or an accessible name |
+| `className`, `ref`, DOM props | part element props | unset | Every part supports a plain class string, ref and Base UI render composition |
+
+Custom children own their own slot classes and close control. For a link action, use `render={<a href="…" />}`, `nativeButton={false}` and `role="link"`. Default parts render title, description and action only when the message supplies them. Description-only messages, including shorthand promise text, become the title so the default dialog stays named. Give every message meaningful title text; an icon or color cannot replace it. Keep `title` and `description` on the message even when custom parts render them, because urgent announcements use the stored message content.
+
+### Managers and messages
+
+`useToastManager<Data>()` returns reactive `toasts`, `add`, `update`, `close` and `promise` from the nearest provider. `createToastManager<Data>()` supplies the same methods outside React; pass it to `toastManager`. Create a stable instance per application or server request. Calls made before provider subscription or after unmount are not buffered. Do not share a module-level manager between server requests.
+
+| Method or option | Type | Behavior |
+| --- | --- | --- |
+| `add(options)` | `ToastAddOptions<Data>` | Returns string ID; adding the same ID updates in place and refreshes its timer |
+| `update(id, options)` | `ToastUpdateOptions<Data>` or updater | Changes existing content; an explicit timeout restarts timing |
+| `close(id?)` | optional string ID | Closes one message or all messages; callbacks fire once |
+| `promise(value, options)` | promise and loading/success/error options | Persistent loading message becomes success/error using same ID; resolves or rejects with original result |
+| `title`, `description` | `ReactNode` | Stored message and announcement text |
+| `type` | `string` | Visual type; use words in content to explain status |
+| `priority` | `low` or `high` | Low is polite; high uses a separate urgent alert announcement |
+| `timeout` | `number` | Per-message duration; `0` disables automatic dismissal |
+| `id` | `string` | Optional stable key for upsert |
+| `actionProps` | native `button` props | Includes action text, handler, disabled state and accessible name |
+| `onClose`, `onRemove` | `() => void` | Close intent and final removal after exit transition |
+| `data` | caller-defined object | Typed custom data for `renderToast` |
+
+Promise options accept `loading`, `success` and `error` as text or update options; success/error also accept functions of the result/error. Handle rejected returned promises in application code. `ToastObject`, `ToastManager`, `ToastAddOptions`, `ToastUpdateOptions`, `ToastPromiseOptions`, component prop types, `ToastTone` and `ToastPlacement` are public exports.
+
+Base UI owns interaction and lifecycle semantics; see its [`Toast` reference](https://base-ui.com/react/components/toast). CSS-only consumers must implement queueing, announcements, timing and focus themselves. Component tokens use the `--kb-toast-*` namespace; importing a standalone `toast.css` also requires tokens and reset.
+
+## Motion
+
+Messages enter with a short slide and soft scale settle; dismissal fades and collapses the space before removal. `Stack` spacing opens as a new message enters, and swipe dismissal continues in the gesture direction. Reduced motion removes transitions and geometric movement.
+
+Tune `--kb-toast-motion-duration`, `--kb-toast-exit-duration`, `--kb-toast-motion-easing`, `--kb-toast-enter-offset` and `--kb-toast-enter-scale` to match the application. Keep exits brief so notifications do not obstruct work.
+
+## Accessibility evidence and limits
+
+Component tests cover lifecycle, announcements in the DOM, provider isolation, callbacks and portal composition. Browser stories exercise keyboard/focus, live-region structure, queue visibility, actions and real timing in both themes and motion preferences. These checks do not prove spoken delivery. Test relevant initial/update/urgent messages with supported screen readers and confirm no duplicate announcements. Manual screen-reader interoperability remains unverified; follow the [shared accessibility procedure](../../../../docs/guides/accessibility.md).
+
+## Related components
+
+Use [`Status`](Status.md) for state beside its content, [`Callout`](Callout.md) for an inline message with fuller context, and [`Dialog`](Dialog.md) when a decision must interrupt work.

package/docs/components/Toolbar.md

@@ -0,0 +1,39 @@
+# Toolbar
+
+Group related actions, such as editing or filtering controls. Give the row an accessible name so people know what its controls affect.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-toolbar--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Toolbar } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <Toolbar aria-label="Document actions">
+      <Toolbar.Button onClick={() => window.print()}>Print</Toolbar.Button>
+    </Toolbar>
+  );
+}
+```
+
+## More examples
+
+- [Coordinated actions](https://kbui.kcb.pro/storybook/?path=/story/components-toolbar--default): Try the toolbar’s single Tab entry and arrow-key navigation.
+
+## Reference
+
+| Part                | Props and responsibility                                                        |
+| ------------------- | ------------------------------------------------------------------------------- |
+| `Toolbar`           | Root; name with `aria-label`; Base UI orientation controls the keyboard direction |
+| `Toolbar.Group`     | Groups related controls inside the toolbar                                      |
+| `Toolbar.Button`    | Action; variant accepts `Button` variants and defaults to ghost                   |
+| `Toolbar.Separator` | Visual division between groups                                                  |
+
+Tab enters the toolbar once; arrow keys move between its controls. Give icon-only actions their own accessible names. Use `Checkbox` or `RadioGroup` when a control represents a persistent choice rather than an action.
+
+## Related components
+
+Use [`Inline`](Inline.md) for independent controls that should each retain their normal Tab stop, and [`Menu`](Menu.md) for a compact action list.

package/docs/components/Tooltip.md

@@ -0,0 +1,42 @@
+# Tooltip
+
+Add a brief, optional hint to an already named control. Put essential instructions in visible text or a field description instead.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-tooltip--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Button, Tooltip } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <Tooltip content="Print using your browser’s print dialog.">
+      <Button onClick={() => window.print()}>Print page</Button>
+    </Tooltip>
+  );
+}
+```
+
+## More examples
+
+- [An optional description](https://kbui.kcb.pro/storybook/?path=/story/components-tooltip--on-hover): Try pointer and keyboard access to a named trigger.
+- [A themed hint](https://kbui.kcb.pro/storybook/?path=/story/components-tooltip--nested-theme): Check that the hint uses its parent theme.
+
+## Reference
+
+| Prop        | Type             | Default       | Notes                                                      |
+| ----------- | ---------------- | ------------- | ---------------------------------------------------------- |
+| `children`  | `ReactElement`   | required      | Focusable trigger that accepts Base UI props and a ref     |
+| `content`   | `ReactNode`      | required      | Short, non-interactive hint shown on hover or focus        |
+| `side`      | positioner side  | `top`         | Preferred side; placement can adjust near viewport edges   |
+| `delay`     | `number`         | `400`         | Hover delay in milliseconds                                |
+| `container` | portal container | document body | Use a themed host when the popup belongs to a nested theme |
+| `className` | `string`         | unset         | Class on the popup                                         |
+
+Give icon-only triggers their own `aria-label`. The tooltip is a description, not a replacement for the control's name. Do not put links, buttons, or required instructions in the popup.
+
+## Related components
+
+Use [`Input`](Input.md) descriptions for essential field instructions and [`Callout`](Callout.md) for a persistent message.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kb.ui/react",
-  "version": "0.10.4",
+  "version": "0.12.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -9,7 +9,8 @@
     "directory": "packages/react"
   },
   "files": [
-    "dist"
+    "dist",
+    "docs"
   ],
   "sideEffects": [
     "*.css"