@kb.ui/react 0.10.4 → 0.12.0

package/docs/components/NumberField.md

@@ -0,0 +1,65 @@
+# NumberField
+
+Use `NumberField` for quantities people can type or adjust with step buttons. Your app sets the range and validates the value. See [Numeric fields](https://github.com/KhallilB/kbui/blob/main/docs/guides/number-fields.md) for examples, keyboard behavior, and styling. Available since v0.6.0.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-numberfield--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { NumberField } from "@kb.ui/react";
+import { useState } from "react";
+
+export function Example() {
+  const [value, setValue] = useState<number | null>(1);
+  const error =
+    value === null || !Number.isInteger(value) || value < 0 || value > 99
+      ? "Enter a whole number from 0 to 99."
+      : "";
+  return (
+    <NumberField
+      label="Quantity"
+      value={value}
+      onValueChange={setValue}
+      min={0}
+      max={99}
+      step={1}
+      error={error}
+    />
+  );
+}
+```
+
+The field can be empty (`null`), and directly typed values remain available for your app to validate. The example validates a whole-number quantity; `min`, `max`, and `step` control the step buttons and stepping keys. See [numeric-field state and interaction](https://github.com/KhallilB/kbui/blob/main/docs/guides/number-fields.md#state-and-interaction) for locale and draft behavior.
+
+## More examples
+
+- [An unanswered quantity](https://kbui.kcb.pro/storybook/?path=/story/components-numberfield--empty): Use `null` for an empty field.
+- [Validation feedback](https://kbui.kcb.pro/storybook/?path=/story/components-numberfield--invalid): Explain a value that needs correction.
+- [Fractional steps](https://kbui.kcb.pro/storybook/?path=/story/components-numberfield--fractional): Compare non-integer increments.
+
+## Reference
+
+| Prop                                            | Type                              | Default                   | Notes                                                                   |
+| ----------------------------------------------- | --------------------------------- | ------------------------- | ----------------------------------------------------------------------- |
+| `label`                                         | `string`                          | required                  | Visible field name; include the quantity or unit                        |
+| `value`                                         | `number` or `null`                | required                  | Controlled number; null means no answer                                 |
+| `onValueChange`                                 | `(value: number \| null) => void` | required                  | Update your stored value after an edit                                  |
+| `min`, `max`                                    | `number`                          | unbounded                 | Bounds for stepping; your app validates direct drafts                   |
+| `step`                                          | `number`                          | `1`                       | Positive increment and alignment                                        |
+| `locale`                                        | `Intl.LocalesArgument`            | runtime locale            | Number formatting and editing locale                                    |
+| `size`                                          | `sm` / `md` / `lg`                | `md`                      | Control size; lg suits touch-heavy tasks                                |
+| `description`, `error`                          | `string`                          | unset                     | Associated help or a specific correction; error marks the field invalid |
+| `disabled`, `readOnly`                          | `boolean`                         | `false`                   | Prevent changes; disabled also prevents submission                      |
+| `name`, `form`, `required`                      | native form props                 | unset / false             | Form ownership and validation                                           |
+| `visuallyHidden`                                | `boolean`                         | `false`                   | Hide the visual label while keeping its accessible name                 |
+| `decrementLabel`, `incrementLabel`              | `string`                          | Decrease/Increase + label | Localized names for the step actions                                    |
+| `inputRef`, `inputProps`                        | input ref / native props          | unset                     | Visible input access and supported native event or ARIA extensions      |
+| `className`, `groupClassName`, `inputClassName` | `string`                          | unset                     | Classes for root, step group, and input                                 |
+
+Native `<div>` props and the root `ref` apply to the wrapper. Root and `inputProps` descriptions follow the help and error IDs in `aria-describedby`. Set the input’s value, type, disabled/read-only state, name, required state and ref through `NumberField` props; `inputProps` cannot override them. Custom event handlers can prevent default actions, so check keyboard behavior after adding them.
+
+## Related components
+
+Use [`Input`](Input.md) for text or identifiers whose leading zeroes and exact characters must be preserved.

package/docs/components/PageHeader.md

@@ -0,0 +1,68 @@
+# PageHeader
+
+Open a screen with its title, short context, status and page-level actions. Use one per screen, at the top of `main`.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-pageheader--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Badge, Button, Link, PageHeader } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <main>
+      <PageHeader
+        navigation={<Link href="/orders">← All orders</Link>}
+        eyebrow="Order"
+        title="#10482"
+        meta={<Badge tone="success">Paid</Badge>}
+        description="Placed on 12 October 2026 by Ana Ruiz · 3 items · €184.00"
+        actions={
+          <>
+            <Button variant="secondary">Refund</Button>
+            <Button>Fulfil order</Button>
+          </>
+        }
+      />
+    </main>
+  );
+}
+```
+
+The title renders as an `h1`. Actions sit at the end of the title row. Below 40rem of header width they take their own row under the heading, still end-aligned; wider headers move them below only when the heading's minimum width no longer fits.
+
+## More examples
+
+- [Detail with status](https://kbui.kcb.pro/storybook/?path=/story/components-pageheader--detail-with-status): Add a back link, an object-type eyebrow and status badges to a record screen.
+- [Breadcrumbs](https://kbui.kcb.pro/storybook/?path=/story/components-pageheader--breadcrumbs): Place a labelled breadcrumb `nav` in `navigation` for nested settings.
+- [With tabs](https://kbui.kcb.pro/storybook/?path=/story/components-pageheader--with-tabs): Put a `Tabs.List` in the body and draw a divider above the panels.
+- [Sizes](https://kbui.kcb.pro/storybook/?path=/story/components-pageheader--sizes): Choose `sm` for dense app shells and `lg` for landing screens.
+- [Narrow wrap](https://kbui.kcb.pro/storybook/?path=/story/components-pageheader--narrow-wrap): See long titles wrap and actions move below the heading at 320 pixels.
+
+## Reference
+
+| Prop           | Type            | Default  | Notes                                                                                                                 |
+| -------------- | --------------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
+| `title`        | `ReactNode`     | required | Page name, rendered as the heading                                                                                    |
+| `description`  | `ReactNode`     | unset    | One or two sentences of context below the title                                                                       |
+| `eyebrow`      | `ReactNode`     | unset    | Short section or object-type label above the title                                                                    |
+| `navigation`   | `ReactNode`     | unset    | Back link or breadcrumb `nav` above the heading                                                                       |
+| `meta`         | `ReactNode`     | unset    | `Status` badges or metadata beside the title; kept out of the heading's accessible name                                 |
+| `actions`      | `ReactNode`     | unset    | Page-level buttons or links; end-aligned, wrapping below the heading when narrow                                      |
+| `headingLevel` | `1` / `2` / `3` | `1`      | Heading rank; lower it only when the header introduces a region below an existing `h1`                                |
+| `size`         | `sm` / `md` / `lg` | `md`  | Title scale: `sm` uses the `h2` size, `md` the `h1` size, `lg` the display size                                       |
+| `divider`      | `boolean`       | `false`  | Draws a rule below the header                                                                                         |
+| `children`     | `ReactNode`     | unset    | Header body below the title row, such as a `Tabs.List` or filters                                                     |
+| `classNames`   | keyed classes   | unset    | Style `navigation`, `main`, `heading`, `eyebrow`, `headline`, `title`, `meta`, `description`, `actions`, `body`       |
+
+The root is a `div`, not `header`. A `header` outside `main` or a sectioning element becomes a banner landmark and would compete with the site header. Other native `div` props pass through to the root.
+
+Keep one primary action. Put secondary actions before it and move rarely used actions into a [`Menu`](Menu.md).
+
+For breadcrumbs, use a labelled `nav` with an ordered list and mark the current item with `aria-current="page"`. Reset list-item margins when using flex layout with `gap`, allow the trail to wrap, and hide decorative separators from assistive technology. Links keep their normal Tab order. See the [breadcrumb example](https://kbui.kcb.pro/storybook/?path=/story/components-pageheader--breadcrumbs) and [WAI breadcrumb pattern](https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/).
+
+## Related components
+
+Use [`Heading`](Heading.md) for section titles inside the page, [`EmptyState`](EmptyState.md) when the page has no content yet, [`Toolbar`](Toolbar.md) for a dense group of controls that act on the content below, and [`Container`](Container.md) to set the page width the header shares with its content.

package/docs/components/Panel.md

@@ -0,0 +1,153 @@
+# Panel
+
+Use `Panel` for a section that needs a header, body, and actions. Its parts help keep those areas aligned. Give the section an accessible name with `aria-labelledby`, pointing to the heading in `Panel.Header`.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-panel--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Button, Panel } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <Panel aria-labelledby="queue-title">
+      <Panel.Header>
+        <h2 id="queue-title">Review queue</h2>
+      </Panel.Header>
+      <Panel.Body>Three items need review.</Panel.Body>
+      <Panel.Footer>
+        <Button>Open queue</Button>
+      </Panel.Footer>
+    </Panel>
+  );
+}
+```
+
+## More examples
+
+- [Optional details](https://kbui.kcb.pro/storybook/?path=/story/components-panel--collapsible): Expand and collapse a section from its toggle.
+- [Section actions](https://kbui.kcb.pro/storybook/?path=/story/components-panel--toolbar): Group actions alongside the section heading.
+- [Nested sections](https://kbui.kcb.pro/storybook/?path=/story/components-panel--nested): Inspect depth and grouping inside a parent panel.
+- [Opaque surface](https://kbui.kcb.pro/storybook/?path=/story/components-panel--opaque): Compare a glass panel with one that drops the blur.
+
+## Reference
+
+```tsx
+<Panel tone="active" rail="status" aria-labelledby="queue-title">
+  <Panel.Header>
+    <h2 id="queue-title">Queue</h2>
+    <Panel.Toolbar>
+      <Button size="sm">Retry</Button>
+    </Panel.Toolbar>
+  </Panel.Header>
+  <Panel.Body>
+    <Panel.Well>…</Panel.Well>
+  </Panel.Body>
+  <Panel.Footer>…</Panel.Footer>
+</Panel>
+```
+
+| Prop           | Values                                                 | Default      | Notes                                                                 |
+| -------------- | ------------------------------------------------------ | ------------ | --------------------------------------------------------------------- |
+| `tone`         | `quiet` / `default` / `sunken` / `active` / `critical` | `default`    | Changes the surface emphasis; pair state colors with explanatory text |
+| `rail`         | `none` / `accent` / `status`                           | `none`       | Accent stays the accent color; status follows the current tone        |
+| `density`      | `compact` / `standard`                                 | `standard`   | Changes padding without changing semantics                            |
+| `opaque`       | `boolean`                                              | `false`      | Solid fill with no backdrop filter, whatever the theme sets           |
+| `collapsible`  | `boolean`                                              | `false`      | Enables `Panel.Toggle` and collapsible body behavior                    |
+| `open`         | `boolean`                                              | uncontrolled | Current body visibility when collapsible is enabled                   |
+| `defaultOpen`  | `boolean`                                              | `false`      | Initial visibility for an uncontrolled collapsible panel              |
+| `onOpenChange` | `(open: boolean) => void`                              | unset        | Update open here when your app controls visibility                    |
+
+`quiet` removes the panel background; `sunken` gives it a recessed surface. Use `Panel.Well` for logs or other output that should sit inside the panel. Customize the shape with `--kb-panel-radius`, the rim with `--kb-panel-rim-top`, `--kb-panel-border`, and `--kb-panel-rim-bottom`, and the depth with `--kb-panel-shadow` or `--kb-panel-shadow-active`.
+
+For additional lighting, use `--kb-panel-sheen`, `--kb-panel-backdrop`, `--kb-panel-glow`, `--kb-panel-glow-active`, and `--kb-panel-glow-critical`. These effects stay off by default. Active and critical tones change the upper rim and glow colors. The rail follows the panel’s rounded corners.
+
+`opaque` turns off the theme’s glass for one panel: it drops `--kb-panel-backdrop` and paints the tone fill over the `--kb-panel-background-opaque` base. Use it under content that redraws often, such as a live terminal or log, where a backdrop blur costs memory and compositing work. It fills even a `quiet` panel. Nested panels keep their own glass; give each one that holds live content `opaque` too. Set `--kb-panel-background-opaque` in your theme to change the base; keep it a solid color that contrasts with `--kb-color-fg` in light and dark.
+
+```tsx
+<Panel opaque aria-labelledby="terminal-title">…</Panel>
+```
+
+## Resizable panels
+
+Put `Panel.Handle` between two panels in a `Panel.Group` to let people resize them. The handle sizes the panel before it, as a percentage of the group; the panel after it takes the remaining space. Name each handle with `aria-label` or `aria-labelledby`. A column group needs a height.
+
+```tsx
+<Panel.Group direction="row">
+  <Panel aria-labelledby="code-title">…</Panel>
+  <Panel.Handle aria-label="Resize code" defaultSize={50} min={25} max={75} />
+  <Panel aria-labelledby="view-title">…</Panel>
+</Panel.Group>
+```
+
+`size` (controlled) or `defaultSize` (default `50`) sets the size of the panel before the handle in percent. `min` and `max` limit it (defaults `10` and `90`), `step` sets the arrow-key change (default `5`), and `onSizeChange` receives the next size after a key press or drag.
+
+The handle follows the window splitter pattern. Arrow keys along the group's direction resize the panel, `Home` and `End` jump to the limits, and `Enter` collapses the panel to `min` and restores the previous size. Pointer drags work in both directions. Arrow keys do not flip in right-to-left layouts. Style the handle with `--kb-panel-handle-size`, `--kb-panel-handle-hit`, `--kb-panel-handle-grip`, `--kb-panel-handle-line` and `--kb-panel-handle-line-active`.
+
+## Related components
+
+Use [`Card`](Card.md) for a self-contained item and [`Grid`](Grid.md) or [`Split`](Split.md) to arrange sections.
+
+## Resizing without dragging
+
+The handle’s keyboard model supports keyboard access. For users who operate a pointer without dragging, provide controls for the same resizing task. This composition uses the existing controlled size API; the surrounding application supplies named click/tap buttons and feedback after button actions. Assess the chosen range and increments against the task’s required functionality.
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Button, Inline, Panel, Status } from "@kb.ui/react";
+import { useId, useState } from "react";
+
+export function ResizableWorkspace() {
+  const titleId = useId();
+  const [size, setSize] = useState(50);
+  const [message, setMessage] = useState("");
+  function resizeBy(amount: number) {
+    const next = Math.max(25, Math.min(75, size + amount));
+    setSize(next);
+    setMessage(`Code panel width ${next} percent.`);
+  }
+  return (
+    <>
+      <Inline>
+        <Button
+          type="button"
+          disabled={size <= 25}
+          onClick={() => resizeBy(-5)}
+        >
+          Make code narrower
+        </Button>
+        <Button type="button" disabled={size >= 75} onClick={() => resizeBy(5)}>
+          Make code wider
+        </Button>
+        <Status live>{message}</Status>
+      </Inline>
+      <Panel.Group direction="row" style={{ width: "100%", minHeight: 240 }}>
+        <Panel aria-labelledby={titleId}>
+          <Panel.Header>
+            <h2 id={titleId}>Code</h2>
+          </Panel.Header>
+          <Panel.Body>Editable source content.</Panel.Body>
+        </Panel>
+        <Panel.Handle
+          aria-labelledby={titleId}
+          size={size}
+          onSizeChange={(next) => {
+            setSize(next);
+            setMessage("");
+          }}
+          min={25}
+          max={75}
+          step={5}
+        />
+        <Panel aria-label="Preview">
+          <Panel.Body>Resulting preview.</Panel.Body>
+        </Panel>
+      </Panel.Group>
+    </>
+  );
+}
+```
+
+Click each resize button, then focus the handle and use its arrow keys, Home/End, and Enter. Check that pane width, separator value, disabled limits, focus visibility, and feedback stay correct. Test the actual composition at zoom and with supported assistive technology. See the shared [accessibility verification guide](https://github.com/KhallilB/kbui/blob/main/docs/guides/accessibility.md#keyboard-focus-and-pointer-input) for WCAG 2.5.7 and target-size requirements.

package/docs/components/Popover.md

@@ -0,0 +1,89 @@
+# Popover
+
+Reveal supporting controls or details in an anchored popup while retaining page context. Base UI owns positioning, focus management and dismissal. Non-modal interaction is the default.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-popover--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Button, Input, Popover } from "@kb.ui/react";
+
+export function ViewOptions() {
+  return (
+    <Popover>
+      <Popover.Trigger render={<Button variant="secondary" />}>View options</Popover.Trigger>
+      <Popover.Content title="View options">
+        <Popover.Body><Input label="Contains text" /></Popover.Body>
+        <Popover.Footer>
+          <Popover.Close render={<Button />}>Done</Popover.Close>
+        </Popover.Footer>
+      </Popover.Content>
+    </Popover>
+  );
+}
+```
+
+## More examples
+
+- [Display preferences](https://kbui.kcb.pro/storybook/?path=/story/components-popover--default): immediate, reversible changes to the activity list, with Reset and Done.
+- [Controlled editing](https://kbui.kcb.pro/storybook/?path=/story/components-popover--controlled): drafts, Cancel, validation and native Enter submission; only Save commits the new name.
+- [Nested theme](https://kbui.kcb.pro/storybook/?path=/story/components-popover--scoped-portal): portal inside a local theme host.
+- [Inside Dialog](https://kbui.kcb.pro/storybook/?path=/story/components-popover--inside-dialog): nested Escape dismissal and focus recovery.
+- [Scrolling workspace](https://kbui.kcb.pro/storybook/?path=/story/components-popover--scrolling): keep a compact form and its Done action visible while the surrounding workspace scrolls.
+
+## Reference
+
+| Part / prop | Type | Default | Purpose |
+|---|---|---|---|
+| `Popover` | Base UI `Popover` root props | — | Groups parts without adding a DOM element. |
+| `open` / `defaultOpen` | `boolean` | `false` | Controlled or initial open state. |
+| `onOpenChange` | `(open, details) => void` | — | Requests opening/dismissal; supports `details.cancel()`. |
+| `modal` | `boolean` or `"trap-focus"` | `false` | Configures interaction containment. Include Close for modal focus containment and touch-screen-reader escape. |
+| `Popover.Trigger` | Base UI `Popover` trigger props | `button` | Supports `Button` composition, refs and native disabled. |
+| `Popover.Content` | Base UI `Popover` popup props | `div` | Portaled interactive popup with ref and native attributes. |
+| `Content.title` / `description` | `ReactNode` | — | Adds associated Title and Description inside Header; omit when composing those parts. |
+| `Content.container` | Base UI portal container | `document.body` | Targets a stable theme host, including refs. |
+| `Content.side` / `align` | Base UI positioner values | `bottom` / `start` | Preferred placement; collision handling may adjust it. |
+| `Content.sideOffset` | Base UI side offset | `6` | Gap from trigger in CSS pixels. |
+| `Content.positionerProps` | Base UI positioner props | — | Advanced collision boundary/padding, offsets, custom anchor, styles and ref; excludes children, `className`, side, align and `sideOffset`. |
+| `Content.initialFocus` / `finalFocus` | Base UI focus target | Primitive defaults | Customize entry and return focus; supports refs and callbacks. |
+| `Content.className` | `string` | — | Additional popup class. |
+| `Content.classNames` | `{ positioner?: string }` | — | Additional class on positioning wrapper. |
+| `Popover.Title` / `Description` | Base UI naming part props | — | Compose accessible names and descriptions; accepts string `className` and refs. |
+| `Popover.Header` / `Body` / `Footer` | Native `div` props and refs | `div` | Header and Footer stay outside Body scrolling. Body must be a direct Content child; Footer holds visible actions. |
+| `Popover.Close` | Base UI close props | `button` | Dismisses without performing an application action. |
+
+Name every popup with title, Title or `aria-label`. Include a visible Close action, especially for touch and modal usage. Escape closes the popup and restores focus; a non-modal outside press dismisses while allowing outside interaction. Default keyboard opening focuses the first tabbable control or the popup; touch opening can focus the popup to avoid launching a virtual keyboard. Keep required instructions available outside temporary content.
+
+Keep popovers short: show the relevant controls and a visible Done/Close action together. Avoid artificial height caps, large descriptions or long lists of secondary content. Use `Dialog`, Drawer or inline `Disclosure` when a task needs more room.
+
+For constrained viewports, compose direct Header, Body and Footer children. Content title/description props create Header automatically. Only Body shrinks and scrolls; Footer actions and the heading stay visible. A long scrollable Body needs a name and `tabIndex={0}` for keyboard scrolling; keep essential instructions and actions outside it. The outer popup can still scroll as a fallback when enlarged header/footer content alone exceeds available space. The popup fits the positioning engine's available width/height. `positionerProps` retains Base UI collision and anchor configuration. Set `container` for nested themes and keep the host outside clipping/transformed ancestors when needed. See [theme hosts and portals](../../../../docs/guides/forms-and-overlays.md#theme-hosts-and-portals).
+
+Style `--kb-popover-width`, `-padding`, `-background`, `-color`, `-border`, `-radius` and `-shadow`. `--kb-popover-motion-duration`, `-motion-easing`, `-enter-scale` and `-enter-offset` control anchored motion; reduced motion disables transitions and movement. Position changes track scrolling immediately. Change theme-dependent aliases on the appropriate portal host.
+
+## Interaction patterns
+
+Use an explicit button with a descriptive label. A decorative chevron can show that it reveals controls; preserve the trigger's expanded state and native Enter/Space handling. Open by click, tap or keyboard activation. Keep non-modal controls in normal Tab order and provide a visible dismissal action. Escape returns focus to the trigger; outside press dismisses without blocking the surrounding page. Base UI owns these behaviors and adapts touch focus to avoid opening a virtual keyboard unnecessarily.
+
+Choose one update model and explain it:
+
+| Task | Update model | Actions and dismissal |
+|---|---|---|
+| View preferences | Apply immediately; show the effect in surrounding content. | Reset restores defaults; Done, Escape and outside press retain the chosen settings. |
+| Edit a value | Keep a separate draft until valid submission. | Save/Enter commits; Cancel, Escape and outside press discard the draft. Reopening starts from the saved value. |
+
+The Default and Controlled stories implement these two models. Do not label a dismiss-only button Save, and do not silently commit a draft on outside dismissal. Keep asynchronous operations and error recovery application-owned.
+
+Test the actual embedding viewport. A portal escapes DOM clipping but cannot escape an iframe's viewport. Leave space around the trigger for the complete panel and its actions; a tiny host must offer a larger preview or compose `Dialog`/Drawer. Do not accept a Body that collapses to zero height while a field technically remains in the accessibility tree. Catalog previews reserve the popup footprint and open the real panel at mobile/desktop widths, including paired themes.
+
+Follow the [Base UI focus/positioning contract](https://base-ui.com/react/components/popover) and [WAI non-modal dialog guidance](https://www.w3.org/TR/wai-aria-1.2/#dialog). For complex tasks on compact screens, use an explicit sheet/dialog composition and preserve its modal semantics rather than changing modes during an open interaction.
+
+## Verification limits
+
+Run `bun run test:overlays` for Chromium, Firefox and WebKit checks in both themes and motion preferences. Scans exclude only Base UI’s implementation focus guards, following maintainer guidance; real controls retain naming checks. Native keyboard and scanner negative-control regressions protect that boundary. See [overlay verification](../../../../docs/guides/accessibility.md#overlay-compatibility) for the policy and manual screen-reader assessment limits.
+
+## Related components
+
+Use [`Tooltip`](Tooltip.md) for brief non-interactive hints, [`Menu`](Menu.md) for action lists, [`Disclosure`](Disclosure.md) for inline details, and [`Dialog`](Dialog.md) for modal tasks and the documented drawer/confirmation patterns.

package/docs/components/Progress.md

@@ -0,0 +1,37 @@
+# Progress
+
+Show how much of a known task is complete. Use a task label rather than a percentage as the accessible name.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-progress--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Progress } from "@kb.ui/react";
+
+export function Example() {
+  return <Progress label="Upload progress" value={60} />;
+}
+```
+
+## More examples
+
+- [Counted work](https://kbui.kcb.pro/storybook/?path=/story/components-progress--steps): Present a readable completed/total value.
+- [Completed work](https://kbui.kcb.pro/storybook/?path=/story/components-progress--complete): Inspect the final state.
+
+## Reference
+
+| Prop         | Type          | Default              | Notes                                                       |
+| ------------ | ------------- | -------------------- | ----------------------------------------------------------- |
+| `label`      | `ReactNode`   | required             | Visible task name and accessible progressbar label          |
+| `value`      | `number`      | required             | Completed amount, from zero to max                          |
+| `max`        | `number`      | `100`                | Total amount; set it for counts such as three of five steps |
+| `valueText`  | `string`      | formatted percentage | Visible and announced value, such as 3 of 5 files           |
+| `classNames` | keyed classes | unset                | Style head, label, value, track, or indicator               |
+
+The current value stays available to assistive technology. Your app owns task completion and any separate completion announcement.
+
+## Related components
+
+Use [`Status`](Status.md) for a textual state and [`Stat`](Stat.md) for a headline measure without completion semantics.

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): Show a compact layout with the same single-choice behavior.
+- [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.