@kb.ui/react 0.10.3 → 0.11.0

package/docs/components/RadioGroup.md

@@ -0,0 +1,69 @@
+# RadioGroup
+
+Use RadioGroup when people need to choose one option and see all the choices at once. Give the group a label and each item a unique string value. Arrow keys change the selection and skip disabled options.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-radiogroup--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { RadioGroup } from "@kb.ui/react";
+import { useState } from "react";
+
+export function Example() {
+  const [value, setValue] = useState<string | null>("weekly");
+  return (
+    <RadioGroup label="Frequency" value={value} onValueChange={setValue}>
+      <RadioGroup.Item value="daily">Daily</RadioGroup.Item>
+      <RadioGroup.Item value="weekly">Weekly</RadioGroup.Item>
+    </RadioGroup>
+  );
+}
+```
+
+## More examples
+
+- [An unanswered choice](https://kbui.kcb.pro/storybook/?path=/story/components-radiogroup--empty-selection): Start without a selected option.
+- [Segmented choices](https://kbui.kcb.pro/storybook/?path=/story/components-radiogroup--segmented): Compare a visual treatment with the same single-choice contract.
+- [Validation feedback](https://kbui.kcb.pro/storybook/?path=/story/components-radiogroup--invalid): Explain why a choice is required.
+
+## Reference
+
+| Prop                    | Type                        | Default      | Notes                                                    |
+| ----------------------- | --------------------------- | ------------ | -------------------------------------------------------- |
+| `label`                 | `string`                    | required     | Visible accessible group label                           |
+| `value`                 | `string \| null`            | required     | Controlled choice; null means no choice                  |
+| `onValueChange`         | `(value: string) => void`   | required     | Next choice request                                      |
+| `appearance`            | `"standard" \| "segmented"` | `"standard"` | Segmented tray for compact single-choice controls        |
+| `selectionMotion`       | `"slide" \| "none"`         | `"slide"`    | Segmented selection background glides or moves instantly |
+| `selectionTone`         | `"primary" \| "neutral"`    | `"primary"`  | Accent pill by default; neutral uses the raised surface  |
+| `disabled`              | `boolean`                   | `false`      | Disable every item                                       |
+| `name`                  | `string`                    |              | Native form field name                                   |
+| `description` / `error` | `string`                    |              | Associated help and invalid-state text                   |
+| `visuallyHidden`        | `boolean`                   | `false`      | Hide group label visually                                |
+| `ref`                   | `Ref<HTMLDivElement>`       |              | Group root                                               |
+
+```tsx
+<RadioGroup
+  label="Density"
+  name="density"
+  value={density}
+  onValueChange={setDensity}
+>
+  <RadioGroup.Item value="compact">Compact</RadioGroup.Item>
+  <RadioGroup.Item value="comfortable">Comfortable</RadioGroup.Item>
+</RadioGroup>
+```
+
+`RadioGroup.Item` forwards Base UI Radio props, including `value`, `disabled` and the native control ref. `className` styles the item label; `controlClassName` styles its radio slot. The group uses the shared theme colors and shadows. Adjust the control size with `--kb-radiogroup-size` and the spacing with `--kb-radiogroup-gap`.
+
+Set `appearance="segmented"` for compact choices such as view, density, or a filter. The control still behaves as a radio group, rather than tabs with associated panels. Your app manages the value and resets it when the form resets. An item’s `required` prop participates in native form validation. Changing the appearance keeps the same controls and focus.
+
+The segmented selection uses a pill shape with the primary accent color by default. Set `selectionTone="neutral"` for a raised surface with neutral text and borders. Both tones follow the current light or dark theme. The background slides along the padded track and follows option widths, wrapped rows and layout changes. Set `selectionMotion="none"` for instant changes. Reduced-motion preferences disable movement regardless of this setting; forced-colors mode uses the selected option’s system highlight.
+
+In dark mode, the primary pill uses a darker orange with white text for contrast. Override `--kb-radiogroup-primary-background` and `--kb-radiogroup-primary-color` together to customize this pair without changing other primary controls.
+
+## Related components
+
+Use [Checkbox](Checkbox.md) for independent choices and [Select](Select.md) when the options belong in a dropdown.

package/docs/components/ScrollArea.md

@@ -0,0 +1,40 @@
+# ScrollArea
+
+Keep logs, activity, or other long content inside a height cap. Let ordinary page content scroll with the page when a separate region is unnecessary.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-scrollarea--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { ScrollArea } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <ScrollArea label="Activity log" maxHeight="12rem">
+      <p>Project created.</p>
+      <p>Review requested.</p>
+    </ScrollArea>
+  );
+}
+```
+
+## More examples
+
+- [Keyboard scrolling](https://kbui.kcb.pro/storybook/?path=/story/components-scrollarea--default): Focus the named scrolling region and try the keyboard.
+
+## Reference
+
+| Prop         | Type              | Default  | Notes                                             |
+| ------------ | ----------------- | -------- | ------------------------------------------------- |
+| `label`      | `string`          | required | Accessible name of the focusable scrolling region |
+| `children`   | `ReactNode`       | required | Content inside the viewport                       |
+| `maxHeight`  | CSS length string | unset    | Height cap, such as 12rem; longer content scrolls |
+| `classNames` | keyed classes     | unset    | Style viewport, scrollbar, or thumb               |
+
+Tab reaches the viewport so keyboard users can scroll it. Keep the focus indicator visible and give the region a specific name such as Build output.
+
+## Related components
+
+Use [Panel](Panel.md) to group the scrolling content with its heading and actions.

package/docs/components/Select.md

@@ -0,0 +1,71 @@
+# Select
+
+Use Select to choose one option from a dropdown. Each option has a string value, a visible label, and an optional disabled flag. Pass `null` to show the placeholder. Your app stores the selected value and decides whether it is valid.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-select--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Select } from "@kb.ui/react";
+import { useState } from "react";
+
+export function Example() {
+  const [value, setValue] = useState<string | null>(null);
+  return (
+    <Select
+      label="Frequency"
+      value={value}
+      onValueChange={setValue}
+      options={[
+        { value: "daily", label: "Daily" },
+        { value: "weekly", label: "Weekly" },
+      ]}
+    />
+  );
+}
+```
+
+## More examples
+
+- [No available options](https://kbui.kcb.pro/storybook/?path=/story/components-select--empty): Inspect the empty helper and field description.
+- [Validation feedback](https://kbui.kcb.pro/storybook/?path=/story/components-select--invalid): Explain a selection that needs correction.
+- [A retained selection](https://kbui.kcb.pro/storybook/?path=/story/components-select--read-only): Keep the chosen value while preventing changes.
+
+## Reference
+
+| Prop                                  | Type                               | Default              | Notes                                                     |
+| ------------------------------------- | ---------------------------------- | -------------------- | --------------------------------------------------------- |
+| `label`                               | `string`                           | required             | Visible field label and accessible popup name             |
+| `value`                               | `string \| null`                   | required             | Controlled selection; null means unset                    |
+| `onValueChange`                       | `(value: string \| null) => void`  | required             | Next valid choice request                                 |
+| `options`                             | `readonly SelectOption[]`          | required             | Ordered unique values, labels and optional disabled flags |
+| `placeholder`                         | `string`                           | `"Choose an option"` | Text for unset values                                     |
+| `description` / `error`               | `string`                           |                      | Associated help and invalid-state text                    |
+| `disabled` / `readOnly`               | `boolean`                          | `false`              | Prevent edits; disabled also blocks form submission       |
+| `name`                                | `string`                           |                      | Native hidden form field name                             |
+| `container`                           | `Select.Portal.Props["container"]` | field root           | Portal host; default retains nested theme                 |
+| `controlClassName` / `popupClassName` | `string`                           |                      | Trigger and popup slot classes                            |
+| `className` / `ref`                   | root div props                     |                      | Wrapper class and native root ref                         |
+
+```tsx
+<Select
+  label="View"
+  name="view"
+  value={view}
+  onValueChange={setView}
+  options={[
+    { value: "recent", label: "Recent" },
+    { value: "all", label: "All records" },
+  ]}
+/>
+```
+
+Use the arrow keys or type to find an option, Enter to select it, and Escape to close the popup and return focus. Disabled options cannot be selected. When there are no options, the trigger is disabled and “No options available” appears below it. Opening the popup leaves the page scrollable. Pointer selection returns focus without a keyboard ring; keyboard dismissal keeps a visible focus indicator.
+
+By default, the popup mounts inside the field root and inherits its theme. If you provide a custom `container`, apply the theme there too. Use `--kb-select-popup-min-width`, `--kb-select-max-height`, and `--kb-select-layer` to adjust the popup’s size and stacking order.
+
+## Related components
+
+Use [RadioGroup](RadioGroup.md) for a visible set of choices and [Menu](Menu.md) for actions.

package/docs/components/Separator.md

@@ -0,0 +1,40 @@
+# Separator
+
+Native hr thematic break; decorative dividers are hidden from assistive technology. Native hr props and ref pass through; orientation and decorative own role, aria-hidden and aria-orientation.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/layout-separator--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Separator } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <div>
+      <p>Project summary</p>
+      <Separator />
+      <p>Review history</p>
+    </div>
+  );
+}
+```
+
+## More examples
+
+- [A divider in a row](https://kbui.kcb.pro/storybook/?path=/story/layout-separator--vertical): Inspect orientation and stretching.
+- [Visual grouping](https://kbui.kcb.pro/storybook/?path=/story/layout-separator--decorative): Hide a decorative rule from assistive technology.
+
+## Reference
+
+| Prop          | Values                                               | Default      |
+| ------------- | ---------------------------------------------------- | ------------ |
+| `orientation` | `horizontal` `vertical`                              | `horizontal` |
+| `decorative`  | Hide a visual-only divider from assistive technology | `false`      |
+
+Vertical rules stretch inside Inline and have a 1rem minimum height. No tab stop or resizing interaction is added. See [Layout composition](https://github.com/KhallilB/kbui/blob/main/docs/guides/layout.md).
+
+## Related components
+
+Use [Inline](Inline.md) to arrange a row and [Panel](Panel.md) to group a complete section.

package/docs/components/Skeleton.md

@@ -0,0 +1,46 @@
+# Skeleton
+
+Reserve the footprint of incoming text, media, or cards so the page does not jump when asynchronous data resolves.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-skeleton--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Card, Skeleton } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <Card aria-busy="true" aria-label="Loading release summary">
+      <Skeleton variant="text" lines={3} animation="wave" />
+    </Card>
+  );
+}
+```
+
+## More examples
+
+- [Wave, pulse, and accent synthesis](https://kbui.kcb.pro/storybook/?path=/story/components-skeleton--wave-and-pulse): Choreograph staggered multi-line wave cascades, breathing pulse blocks, and warm accent-tinted synthesis placeholders.
+- [Structured card placeholder](https://kbui.kcb.pro/storybook/?path=/story/components-skeleton--card-placeholder): Combine avatar circles, pills, rectangular wells, and multi-line text placeholders.
+- [Shapes and sizes](https://kbui.kcb.pro/storybook/?path=/story/components-skeleton--shapes-and-sizes): Compare `text`, `rect`, `circle`, and `pill` geometry across the size scale.
+- [Loading-to-content transition](https://kbui.kcb.pro/storybook/?path=/story/components-skeleton--content-transition): Toggle `loading` to swap placeholder bars for resolved children without layout shift.
+
+## Reference
+
+| Prop         | Type                                  | Default     | Notes                                                                                     |
+| ------------ | ------------------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
+| `variant`    | `text` / `rect` / `circle` / `pill`   | `text`      | Matches incoming typography, media blocks, avatars, or status chips                       |
+| `size`       | `sm` / `md` / `lg`                    | `md`        | Scales line height and circle diameter                                                    |
+| `lines`      | `number`                              | `1`         | Number of stacked lines when `variant="text"`; the final line shortens naturally          |
+| `width`      | `number` / `string`                   | unset       | Explicit inline size override (`px` number or CSS length)                                 |
+| `height`     | `number` / `string`                   | unset       | Explicit block size override (`px` number or CSS length)                                  |
+| `animated`   | `boolean`                             | `true`      | Enables motion that stops automatically under `prefers-reduced-motion`                    |
+| `animation`  | `shimmer` / `pulse` / `wave` / `none` | `"shimmer"` | Selects specular sweep, breathing pulse, staggered multi-line wave, or static placeholder |
+| `tone`       | `default` / `subtle` / `accent`       | `"default"` | Surface treatment (`default` surface, `subtle` recessed well, or `accent` synthesis tint) |
+| `loading`    | `boolean`                             | `true`      | Renders decorative placeholders when `true`, or `children` inside `.kb-skeleton-content`  |
+| `classNames` | keyed classes                         | unset       | Style `line` or `content`                                                                 |
+
+## Related components
+
+Use [Spinner](Spinner.md) for compact indeterminate waits, [EmptyState](EmptyState.md) when a query resolves with zero items, and [Card](Card.md) as the owning surface with `aria-busy="true"`.

package/docs/components/Spinner.md

@@ -0,0 +1,40 @@
+# Spinner
+
+Signal an indeterminate wait when completion percentage is unknown. Pair standalone indicators with a clear status label, or mark the spinner decorative inside a button that already names its busy action.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-spinner--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Spinner } from "@kb.ui/react";
+
+export function Example() {
+  return <Spinner label="Loading workspace" variant="orbit" appearance="pill" showLabel />;
+}
+```
+
+## More examples
+
+- [Fancy variants and status pills](https://kbui.kcb.pro/storybook/?path=/story/components-spinner--fancy-variants): Compare `ring`, `orbit`, `dots`, and `bars` indicators alongside elevated `pill` status framing.
+- [Visible status label](https://kbui.kcb.pro/storybook/?path=/story/components-spinner--with-visible-label): Pair the animated arc with explicit text describing what is loading.
+- [Busy button submission](https://kbui.kcb.pro/storybook/?path=/story/components-spinner--busy-button): Render a decorative spinner inside a disabled button during asynchronous submission.
+- [Sizes and tones](https://kbui.kcb.pro/storybook/?path=/story/components-spinner--sizes-and-tones): Match compact controls, inline status rows, or section-level waits.
+
+## Reference
+
+| Prop         | Type                                                                         | Default     | Notes                                                                                |
+| ------------ | ---------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------ |
+| `label`      | `string`                                                                     | `"Loading"` | Accessible status text announced by `role="status"`                                  |
+| `showLabel`  | `boolean`                                                                    | `false`     | Renders `label` visibly beside the spinner instead of `.kb-sr-only`                  |
+| `decorative` | `boolean`                                                                    | `false`     | Omits `role="status"` and sets `aria-hidden="true"` inside already-labeled controls  |
+| `size`       | `sm` / `md` / `lg`                                                           | `md`        | Scales the SVG indicator and accompanying label                                      |
+| `tone`       | `current` / `accent` / `neutral` / `info` / `success` / `warning` / `danger` | `accent`    | Stroke ink; use `current` inside buttons or badges to inherit text color             |
+| `variant`    | `ring` / `orbit` / `dots` / `bars`                                           | `ring`      | Selects classic arc, dual counter-rotating orbit, staggered wave dots, or equalizer bars |
+| `appearance` | `plain` / `pill`                                                             | `plain`     | Wraps the indicator and label in a tinted status pill when set to `pill`             |
+| `classNames` | keyed classes                                                                | unset       | Style `icon`, `track`, `arc`, `core`, `dot`, `bar`, or `label`                       |
+
+## Related components
+
+Use [Progress](Progress.md) when a numeric completion ratio exists, [Skeleton](Skeleton.md) to preserve layout geometry while loading content, and [Status](Status.md) for persistent state labels.

package/docs/components/Split.md

@@ -0,0 +1,47 @@
+# Split
+
+Two children form equal or weighted columns through layout-owned `.kb-split-track` wrappers. Below the available-width threshold, columns stack in source order. Layout uses CSS alone, including inside nested panels. Native props and matching ref pass through.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/layout-split--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Split } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <Split>
+      <section aria-labelledby="main-title">
+        <h2 id="main-title">Project</h2>
+        <p>Current work.</p>
+      </section>
+      <aside aria-label="Project details">Last updated today.</aside>
+    </Split>
+  );
+}
+```
+
+## More examples
+
+- [Stacked columns](https://kbui.kcb.pro/storybook/?path=/story/layout-split--responsive): Resize the available width and inspect reading order.
+- [Readable column content](https://kbui.kcb.pro/storybook/?path=/story/layout-split--content-measures): Retain text measure within layout tracks.
+- [Nested columns](https://kbui.kcb.pro/storybook/?path=/story/layout-split--nested): Inspect collapse behavior inside another layout.
+
+## Reference
+
+| Prop         | Values                                             | Default   |
+| ------------ | -------------------------------------------------- | --------- |
+| `as`         | `div` `section` `article`                          | `div`     |
+| `ratio`      | `equal` (1:1) `wide-start` (2:1) `wide-end` (1:2)  | `equal`   |
+| `collapse`   | `sm` (32rem) `md` (48rem) `lg` (64rem)             | `md`      |
+| `gap`        | `none` `sm` `md` `lg`, same scale as Inline        | `md`      |
+| `align`      | `start` `center` `end` `baseline` `stretch`        | `stretch` |
+| `classNames` | `{ track?: string }`, applied to each column track | unset     |
+
+Provide two children; empty conditional children add no track. Each track owns column sizing, so Text keeps its reading measure and nested token overrides stay local. Non-default generic native elements require an explicit `as`. Use Grid for variable child counts. See [Layout composition](https://github.com/KhallilB/kbui/blob/main/docs/guides/layout.md).
+
+## Related components
+
+Use [Grid](Grid.md) for a variable number of children and [Container](Container.md) for the page boundary.

package/docs/components/Stat.md

@@ -0,0 +1,34 @@
+# Stat
+
+Show a value with the label that explains it. Include units and a time period in the label or value when they affect the meaning.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-stat--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Stat } from "@kb.ui/react";
+
+export function Example() {
+  return <Stat label="Open tasks" value={12} />;
+}
+```
+
+## More examples
+
+- [A headline figure](https://kbui.kcb.pro/storybook/?path=/story/components-stat--display): Compare emphasis for one primary value.
+- [Several measures](https://kbui.kcb.pro/storybook/?path=/story/components-stat--row): Keep labels beside comparable figures.
+
+## Reference
+
+| Prop         | Type             | Default  | Notes                                              |
+| ------------ | ---------------- | -------- | -------------------------------------------------- |
+| `label`      | `ReactNode`      | required | What the value measures; read before the value     |
+| `value`      | `ReactNode`      | required | Number or short text; include units where needed   |
+| `size`       | `md` / `display` | `md`     | Use display for one headline number, md for groups |
+| `classNames` | keyed classes    | unset    | Style the label and value separately               |
+
+## Related components
+
+Use [Progress](Progress.md) when the number represents completion and [Status](Status.md) for changing state.

package/docs/components/Status.md

@@ -0,0 +1,47 @@
+# Status
+
+Use Status for a state such as running, blocked, or complete. Always include text so the meaning is clear without relying on color or an icon.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-status--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Status } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <Status tone="running" live>
+      Build running
+    </Status>
+  );
+}
+```
+
+## More examples
+
+- [Changing state](https://kbui.kcb.pro/storybook/?path=/story/components-status--live): Inspect the status announcement contract.
+- [Supporting iconography](https://kbui.kcb.pro/storybook/?path=/story/components-status--with-icon): Keep meaning in text when an icon is present.
+- [A compact state label](https://kbui.kcb.pro/storybook/?path=/story/components-status--chip): Compare a contained appearance.
+
+## Reference
+
+```tsx
+<Status tone="running" appearance="chip" icon={<PlayIcon />} live>
+  Running
+</Status>
+```
+
+| Prop         | Values                                                             | Default   | Notes                                                                   |
+| ------------ | ------------------------------------------------------------------ | --------- | ----------------------------------------------------------------------- |
+| `children`   | `ReactNode`                                                        | unset     | State text such as Running or Blocked; keep it meaningful without color |
+| `tone`       | `neutral` / `info` / `running` / `success` / `warning` / `blocked` | `neutral` | Reinforces the written state                                            |
+| `appearance` | `plain` / `chip`                                                   | `plain`   | Plain stays inline; chip adds separation with a tinted surface          |
+| `icon`       | `ReactNode`                                                        | unset     | Optional decorative icon; the text still names the state                |
+| `live`       | `boolean`                                                          | `false`   | Adds role=status for changing text; does not move focus                 |
+| `compact`    | `boolean`                                                          | `false`   | Tighter spacing and smaller text for dense layouts                      |
+
+## Related components
+
+Use [Badge](Badge.md) for static metadata, [Progress](Progress.md) for completion, and [Callout](Callout.md) for a fuller message.

package/docs/components/Switch.md

@@ -0,0 +1,73 @@
+# Switch
+
+Use Switch for a preference that takes effect as soon as it changes. Pass `checked` and update it in `onCheckedChange`; your app handles saving and form reset. Switch uses a labelled native checkbox with `role="switch"`. Use Checkbox when people are selecting items 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-switch--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Switch } from "@kb.ui/react";
+import { useState } from "react";
+
+export function Example() {
+  const [checked, setChecked] = useState(false);
+  return (
+    <Switch
+      label="Email notifications"
+      checked={checked}
+      onCheckedChange={setChecked}
+    />
+  );
+}
+```
+
+## More examples
+
+- [Form integration](https://kbui.kcb.pro/storybook/?path=/story/components-switch--native-form): Include an on/off value in a native form.
+- [A retained setting](https://kbui.kcb.pro/storybook/?path=/story/components-switch--read-only): Show a setting while blocking edits.
+- [Validation feedback](https://kbui.kcb.pro/storybook/?path=/story/components-switch--with-error): Associate a correction with the setting.
+
+## Reference
+
+| Prop                                   | Type                                                                    | Default              | Notes                                                                                                                                |
+| -------------------------------------- | ----------------------------------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `label`                                | `string`                                                                | required             | Associated visible label and accessible name                                                                                         |
+| `checked`                              | `boolean`                                                               | required             | Current controlled state                                                                                                             |
+| `onCheckedChange`                      | `(checked: boolean) => void`                                            | required             | Requests next state; owner updates checked                                                                                           |
+| `size`                                 | `"sm" \| "md" \| "lg"`                                                  | `"md"`               | Visual track size (`36×20px`, `44×24px`, `56×32px`); `Fieldset` defaults nested switches to `"sm"` while keeping a 44px touch target |
+| `tone`                                 | `"accent" \| "neutral" \| "info" \| "success" \| "warning" \| "danger"` | `"accent"`           | Checked-state track tone when `onTone` is unset                                                                                      |
+| `offTone` / `onTone`                   | `SwitchTone`                                                            | `"neutral"` / `tone` | Independent track tone for unchecked and checked sides                                                                               |
+| `offColor` / `onColor`                 | `string`                                                                |                      | Custom CSS color for the unchecked or checked track                                                                                  |
+| `description` / `error`                | `string`                                                                |                      | Associated helper/error text; error sets aria-invalid                                                                                |
+| `disabled` / `readOnly`                | `boolean`                                                               | `false`              | Disabled blocks focus/changes; read-only keeps focus and form value while blocking edits                                             |
+| `visuallyHidden`                       | `boolean`                                                               | `false`              | Hide label visually, keep its accessible name                                                                                        |
+| `offIcon` / `onIcon`                   | `ReactNode`                                                             |                      | Decorative slots; do not place interactive content inside                                                                            |
+| `name` / `value` / `form` / `required` | native input props                                                      |                      | Native form ownership, successful value and validation                                                                               |
+| `ref`                                  | `Ref<HTMLInputElement>`                                                 |                      | Native checkbox, never an extra hidden control                                                                                       |
+| `className` / `controlClassName`       | `string`                                                                |                      | Root/native input class                                                                                                              |
+| `style`                                | `CSSProperties`                                                         |                      | Native input styles; CSS custom properties also reach visible track and thumb                                                        |
+
+```tsx
+import { useState } from "react";
+import { Switch } from "@kb.ui/react";
+
+export function Preference() {
+  const [checked, setChecked] = useState(false);
+  return (
+    <Switch
+      label="Email updates"
+      checked={checked}
+      onCheckedChange={setChecked}
+      name="updates"
+    />
+  );
+}
+```
+
+Import `useState` from React and `Switch` from `@kb.ui/react`. Clicking or pressing Space calls `onCheckedChange`. Unchecked or disabled controls submit no value; a checked control submits its native value (`"on"` unless you supply one). Reset `checked` in the form’s `onReset` handler when needed. Use `offTone`/`onTone` or `offColor`/`onColor` when both sides of a toggle carry distinct state colors. The `switch` token group controls its appearance in both themes, and reduced motion removes the thumb’s travel animation.
+
+## Related components
+
+Use [Checkbox](Checkbox.md) for a choice submitted with other answers and [RadioGroup](RadioGroup.md) for one of several settings.

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. Supply a readable minimum table width with `style` when columns should scroll rather than wrap. 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.