@kb.ui/react 0.10.3 → 0.11.0

package/docs/components/Input.md

@@ -0,0 +1,82 @@
+# Input
+
+Use Input for text entry. It keeps the label, help text, and error message together, and has space for icons or actions at either end.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-input--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Input } from "@kb.ui/react";
+
+export function Example() {
+  return <Input label="Email" type="email" name="email" autoComplete="email" />;
+}
+```
+
+## More examples
+
+- [Search and clear](https://kbui.kcb.pro/storybook/?path=/story/components-input--with-icons-and-actions): Keep the input stable while editing actions change.
+- [Validation feedback](https://kbui.kcb.pro/storybook/?path=/story/components-input--with-error): Associate an error with the field.
+- [A visually hidden label](https://kbui.kcb.pro/storybook/?path=/story/components-input--hidden-label): Retain the accessible name when hiding the visual label.
+
+## Reference
+
+| Prop                          | Type                   | Default  | Notes                                                         |
+| ----------------------------- | ---------------------- | -------- | ------------------------------------------------------------- |
+| `startContent` / `endContent` | `ReactNode`            |          | Icons or actions at either end; give actions accessible names |
+| `label`                       | `string`               | required | Visible label and accessible name                             |
+| `visuallyHidden`              | `boolean`              |          | Hides the label visually but keeps it for screen readers      |
+| `description`                 | `string`               |          | Help text below the field                                     |
+| `error`                       | `string`               |          | Shows an error message and marks the field invalid            |
+| `size`                        | `"sm" \| "md" \| "lg"` | `"md"`   | Field height. Replaces the native `size` attribute            |
+| `className`                   | `string`               |          | Applied to the wrapper, not the input element                 |
+
+Other native input props, including `value` and `defaultValue`, pass through to the input. Base UI's `onValueChange` is also supported.
+
+## Search composition
+
+Use `Input type="search"` with content slots and a `Button` when search needs a visible clear action. Your app handles filtering, submission, debounce, reset, and result announcements.
+
+```tsx
+import { useRef, useState } from "react";
+import { Button, Input } from "@kb.ui/react";
+
+export function SearchExample() {
+  const [query, setQuery] = useState("");
+  const control = useRef<HTMLInputElement>(null);
+  return (
+    <Input
+      ref={control}
+      label="Search components"
+      type="search"
+      name="q"
+      value={query}
+      onValueChange={setQuery}
+      endContent={
+        query ? (
+          <Button
+            type="button"
+            size="sm"
+            variant="ghost"
+            aria-label="Clear search"
+            onClick={() => {
+              setQuery("");
+              control.current?.focus();
+            }}
+          >
+            <span aria-hidden="true">×</span>
+          </Button>
+        ) : undefined
+      }
+    />
+  );
+}
+```
+
+The field label names the input. Give each action its own accessible name, and hide decorative icons with `aria-hidden`. Use `type="button"` on the clear action so it does not submit the form, then return focus to the input. Hide editing actions when the field is disabled or read-only. Adding or removing content at either end keeps the same input node, value, and focus. See the **Icons and actions** story for a working search example.
+
+## Related components
+
+Use [Textarea](Textarea.md) for multiline answers, [NumberField](NumberField.md) for numeric stepping, and [Combobox](Combobox.md) for a searchable choice from existing values.

package/docs/components/Link.md

@@ -0,0 +1,52 @@
+# Link
+
+Native anchor for navigation, with persistent underline and visible keyboard focus.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-link--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Link } from "@kb.ui/react";
+
+export function Example() {
+  return <Link href="/projects">Browse projects</Link>;
+}
+```
+
+## More examples
+
+- [Navigation within prose](https://kbui.kcb.pro/storybook/?path=/story/components-link--in-text): Inspect link treatment inside surrounding text.
+- [Router adapter](https://kbui.kcb.pro/storybook/?path=/story/components-link--with-router): Client-side navigation through `Link.Provider`.
+
+## Reference
+
+| Prop                                        | Type                | Default  | Notes                            |
+| ------------------------------------------- | ------------------- | -------- | -------------------------------- |
+| `href`                                      | `string`            | required | Navigation destination           |
+| `target`, `rel`, `download`, `aria-current` | Native anchor props | unset    | Passed through without rewriting |
+| `className`, `ref`                          | Native anchor props | unset    | Ref targets anchor               |
+
+Use descriptive link text. Use Button for an action. Links inherit surrounding type size; Tab focuses, Enter follows, and Space retains native behavior. Callers own new-tab wording and target/rel policy. No disabled link is provided. Color, underline and focus must remain visible.
+
+### Router links
+
+kbui never imports a router. Wrap your app once in `Link.Provider` with a component that renders an anchor: it receives `href` plus native anchor props, and must pass them and `ref` through. `Link` then renders through it and keeps `kb-link`; nested providers override outer ones, and without a provider it renders a plain `<a>`. A React Router adapter:
+
+```tsx
+import { Link, type LinkProps } from "@kb.ui/react";
+import { Link as RouterLink } from "react-router";
+
+const AppLink = ({ href, ...props }: LinkProps) => <RouterLink to={href} {...props} />;
+
+<Link.Provider component={AppLink}>
+  <App />
+</Link.Provider>;
+```
+
+`useLinkComponent()` returns the current component for your own anchors.
+
+## Related components
+
+Use [Button](Button.md) for an action and [Card](Card.md) to group content around a destination.

package/docs/components/Menu.md

@@ -0,0 +1,44 @@
+# Menu
+
+Offer a short list of actions without leaving the current context. Use a Select when people are choosing a saved field value.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-menu--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Button, Menu } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <Menu>
+      <Menu.Trigger render={<Button />}>Page actions</Menu.Trigger>
+      <Menu.Content>
+        <Menu.Item onClick={() => window.print()}>Print page</Menu.Item>
+      </Menu.Content>
+    </Menu>
+  );
+}
+```
+
+## More examples
+
+- [Keyboard interaction](https://kbui.kcb.pro/storybook/?path=/story/components-menu--default): Try the trigger, arrow keys, and dismissal.
+- [A themed popup](https://kbui.kcb.pro/storybook/?path=/story/components-menu--nested-theme): Keep a portaled popup within its intended theme.
+
+## Reference
+
+| Part             | Props and responsibility                                                                 |
+| ---------------- | ---------------------------------------------------------------------------------------- |
+| `Menu`           | Root; use open/defaultOpen and onOpenChange when your app controls visibility            |
+| `Menu.Trigger`   | Named trigger; render a Button for shared styling                                        |
+| `Menu.Content`   | Popup; side defaults to bottom, align to start; container chooses the themed portal host |
+| `Menu.Item`      | Action text and click handler; disabled prevents selection                               |
+| `Menu.Separator` | Divides related groups without adding a focus stop                                       |
+
+Name the trigger, keep action labels specific, and retain the default arrow-key and Escape behavior. A menu item should perform an action rather than contain another button.
+
+## Related components
+
+Use [Select](Select.md) for a saved field value and [Dialog](Dialog.md) for a focused task with content or fields.

package/docs/components/MultiSelect.md

@@ -0,0 +1,59 @@
+# MultiSelect
+
+Use MultiSelect when people need to search a longer list and keep multiple selections visible as removable chips. Selected values render inside a named chip toolbar with keyboard arrow/Backspace/Delete support and per-chip remove buttons. Choosing or deselecting an option keeps the popup open and preserves the filter. Escape, an outside click, or the toggle closes it.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-multiselect--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { useState } from "react";
+import { MultiSelect } from "@kb.ui/react";
+
+const scopes = [
+  { value: "payments:read", label: "Payments read" },
+  { value: "webhooks:manage", label: "Webhooks" },
+  { value: "reporting:export", label: "Reporting export" },
+];
+
+export function ScopeMultiSelect() {
+  const [selected, setSelected] = useState<string[]>(["payments:read"]);
+  return (
+    <MultiSelect
+      label="API scopes"
+      options={scopes}
+      value={selected}
+      onValueChange={setSelected}
+      placeholder="Filter scopes..."
+    />
+  );
+}
+```
+
+## More examples
+
+- [Several retained choices](https://kbui.kcb.pro/storybook/?path=/story/components-multiselect--many-selections): Inspect removable chips and their keyboard model.
+- [No matching options](https://kbui.kcb.pro/storybook/?path=/story/components-multiselect--empty): Inspect the empty filtering state.
+- [Validation feedback](https://kbui.kcb.pro/storybook/?path=/story/components-multiselect--invalid): Explain a selection that needs correction.
+
+## Reference
+
+| Prop                    | Type                                    | Default                   | Notes                                                 |
+| ----------------------- | --------------------------------------- | ------------------------- | ----------------------------------------------------- |
+| `label`                 | `string`                                | required                  | Visible field label and accessible combobox name      |
+| `options`               | `readonly MultiSelectOption[]`          | required                  | Selectable options filtered by label                  |
+| `value`                 | `readonly string[]`                     | required                  | Controlled array of selected option values            |
+| `onValueChange`         | `(value: string[]) => void`             | required                  | Called when selections are added, removed, or cleared |
+| `placeholder`           | `string`                                | unset                     | Input placeholder                                     |
+| `emptyMessage`          | `ReactNode`                             | `"No matching options"`   | Polite status text when no options match              |
+| `size`                  | `"sm" \| "md" \| "lg"`                  | `"md"`                    | Control height and text scale                         |
+| `description` / `error` | `ReactNode`                             | unset                     | Associated help and invalid-state text                |
+| `disabled` / `readOnly` | `boolean`                               | `false`                   | Prevent edits and chip removal                        |
+| `removeLabel`           | `(option: MultiSelectOption) => string` | `"Remove {option.label}"` | Accessible name for each chip remove button           |
+| `container`             | `Combobox.Portal.Props["container"]`    | field root                | Portal host; default retains nested theme             |
+| `classNames`            | `ClassNames<MultiSelectSlot>`           | unset                     | Extra classes for inner parts                         |
+
+## Related components
+
+Use [Combobox](Combobox.md) for one searchable choice and [Checkbox](Checkbox.md) for independent choices that should remain visible.

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` govern stepping. 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): Represent an empty field with null.
+- [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 pass through to the wrapper. Any `aria-describedby` values from the root and `inputProps` are added after the help and error IDs. Use the explicit NumberField props for the input’s value, type, disabled/read-only state, name, required state, and ref; `inputProps` cannot override those. Custom event handlers can prevent defaults, so take care to preserve keyboard behavior.
+
+## Related components
+
+Use [Input](Input.md) for text or identifiers whose leading zeroes and exact characters must be preserved.

package/docs/components/Panel.md

@@ -0,0 +1,145 @@
+# 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.
+
+## 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                            |
+| `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.
+
+## 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.