@kb.ui/react 0.10.3 → 0.11.0

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 layouts need enough room for labels and content; applications can choose horizontal orientation at narrow widths.
+
+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 line height is 1.6; block content is bounded to 65ch by `--kb-text-measure`. Text has no margin. Inline spans keep natural flow. Use native `strong` and `em` for meaningful emphasis. Do not nest paragraphs or place block children inside 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.
+
+Use `Grid as="ul"` with `li` children for a gallery in reading order. A named Dialog trigger in the caption supports enlarged inspection, Escape dismissal and focus return through Dialog. The gallery recipe provides no carousel, arrow-key selection, image editor or upload. See [media recipes](../../../../docs/guides/media-and-identity.md) 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): Keep a portaled hint within its intended 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.3",
+  "version": "0.11.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -9,7 +9,8 @@
     "directory": "packages/react"
   },
   "files": [
-    "dist"
+    "dist",
+    "docs"
   ],
   "sideEffects": [
     "*.css"