@kb.ui/react 0.10.4 → 0.12.0

package/docs/components/Collection.md

@@ -0,0 +1,183 @@
+# Collection
+
+Work through record sets using search, facet filters, sortable columns, page selection, pagination and bulk actions. `Collection` composes a native table and kbui controls. `useCollection` provides the same state contract for custom cards or lists. `Collection.Pagination` and `Collection.BulkActions` also work independently.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-collection--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Collection } from "@kb.ui/react";
+import { useState } from "react";
+
+type Project = { id: string; name: string; status: string };
+const initial: Project[] = [
+  { id: "web", name: "Website refresh", status: "Active" },
+  { id: "help", name: "Help center", status: "Paused" },
+];
+
+export function Projects() {
+  const [items, setItems] = useState(initial);
+  return (
+    <Collection
+      label="Projects"
+      items={items}
+      getKey={item => item.id}
+      getItemLabel={item => item.name}
+      columns={[
+        { key: "name", header: "Project", cell: item => item.name,
+          compare: (a, b) => a.name.localeCompare(b.name) },
+        { key: "status", header: "Status", cell: item => item.status },
+      ]}
+      matches={(item, query, filters) =>
+        item.name.toLowerCase().includes(query.toLowerCase()) &&
+        (!filters.status || item.status === filters.status)}
+      filters={[{ key: "status", label: "Status", options: [
+        { value: "Active", label: "Active" },
+        { value: "Paused", label: "Paused" },
+      ] }]}
+      bulkActions={[{ key: "archive", label: "Archive", onAction: async keys => {
+        setItems(current => current.filter(item => !keys.includes(item.id)));
+      } }]}
+    />
+  );
+}
+```
+
+## More examples
+
+- [Large collection](https://kbui.kcb.pro/storybook/?path=/story/components-collection--large-collection): Search and filter 120 records; paused records cannot be selected.
+- [Server pagination](https://kbui.kcb.pro/storybook/?path=/story/components-collection--server-pagination): Controlled state with application-owned data processing.
+- [Empty](https://kbui.kcb.pro/storybook/?path=/story/components-collection--empty), [loading](https://kbui.kcb.pro/storybook/?path=/story/components-collection--loading), and [fetch error](https://kbui.kcb.pro/storybook/?path=/story/components-collection--fetch-error): Explicit result states.
+- [Bulk failure](https://kbui.kcb.pro/storybook/?path=/story/components-collection--bulk-failure): Selection survives rejection so users can retry.
+
+## Reference
+
+### Collection props
+
+| Prop | Type | Default | Contract |
+| --- | --- | --- | --- |
+| `label` | `string` | required | Visible caption and accessible region name |
+| `items` | `readonly T[]` | required | Complete dataset in client mode; current response page in server mode |
+| `getKey` | `(item: T) => string` | required | Unique stable record ID; duplicates in supplied rows throw |
+| `getItemLabel` | `(item: T) => string` | required | Meaningful accessible checkbox name |
+| `columns` | `readonly CollectionColumn<T>[]` | required | Ordered unique keys, string headers and cell renderers |
+| `mode` | `client` / `server` | `client` | Server mode skips all local filtering, sorting and slicing |
+| `totalItems` | `number` | client derives it | Required in server mode; known filtered total, non-negative safe integer |
+| `matches` | `(item, query, filters) => boolean` | unset | Client predicate; also enables client search UI |
+| `compare` | `(a, b, sort) => number` | column comparator | Optional hook-level comparison override; return ascending order |
+| `filters` | `readonly CollectionFilter[]` | `[]` | Facet key, visible label and nonempty option values; empty string means All |
+| `isItemDisabled` | `(item: T) => boolean` | unset | Prevent individual and page selection of ineligible supplied records |
+| `state` / `onStateChange` | `CollectionState` / `(next) => void` | uncontrolled | Parent applies complete next state; suitable for URL or server ownership |
+| `defaultState` | `Partial<CollectionState>` | see state table | Initial uncontrolled state; later changes do not reinitialize it |
+| `selectable` | `boolean` | `true` | Show row/page checkboxes and selection actions |
+| `bulkActions` | `readonly CollectionBulkAction[]` | `[]` | Unique key, label, `onAction(keys)`, optional disabled flag |
+| `loading` | `boolean` | `false` | Mark busy, suppress stale rows and disable workflow controls |
+| `error` | `ReactNode` | unset | Fetch failure alert, suppress rows and disable workflow controls |
+| `empty` | `ReactNode` | `No matching records` | Zero-result content; include a useful next step |
+| `toolbar` | `ReactNode` | unset | Extra application-owned controls, retry or creation actions |
+| `className`, `style`, `ref` | native section props | unset | Root customization and element reference |
+| `classNames` | slot classes | unset | `toolbar`, `filters`, `viewport`, `table`, `caption`, `head`, `cell`, `row`, `empty`, `status`, `bulk`, `pagination` |
+
+A column has `key`, `header`, `cell(item)`, optional ascending `compare(a, b)`, and optional `sortable` for server-only sort requests. Sorting cycles ascending, descending, input order. Ties preserve supplied order. Sorting never mutates the supplied array. Search and facet interpretation belong to `matches`; kbui does not guess text from rendered React nodes. Server mode always exposes search and emits its value unchanged.
+
+### State and transitions
+
+| State field | Default | Transition contract |
+| --- | --- | --- |
+| `query` | `""` | `setQuery` resets page to one and clears selection |
+| `filters` | `{}` | `setFilter(key, value)` preserves other facets, resets page and clears selection |
+| `sort` | `null` | `{ key, direction: "ascending" or "descending" }`; `setSort` resets page, preserves selection |
+| `page` | `1` | One-based positive safe integer; effective page clamps when results shrink |
+| `pageSize` | `10` | Positive safe integer; `setPageSize` resets page and preserves selection |
+| `selectedKeys` | `[]` | Explicit unique IDs; never an implicit selection of every remote result |
+
+Client mode processes records in this order: predicate, stable comparison, page slice. Removed or newly disabled IDs disappear from effective selection. Server mode preserves off-page IDs; eligibility for unseen records remains the application’s responsibility. Both modes remove disabled IDs present in the current response. Zero results have one empty page. Invalid counts, pages and sizes throw `RangeError` rather than emitting broken navigation.
+
+`state` is controlled when supplied. Each controlled proposal starts from the latest accepted props; a rejected proposal cannot affect a later interaction. Combine coordinated controlled changes in the parent before applying one next state. Uncontrolled commands in one event compose sequentially, including derived page bounds and page selection. Retained methods consult the latest committed dataset, eligibility rules, callbacks and accepted state, so asynchronous completion removes only its submitted IDs. Rendered state remains owned by the parent until it accepts `onStateChange`. Normalized selection and clamped page never trigger `onStateChange` during data refresh; the next user transition emits normalized state. Uncontrolled state retains those corrections so deleted/reintroduced IDs stay deselected and growing datasets do not restore an obsolete page. Controlled parent stores should reconcile their canonical state when external data changes. Use immutable arrays/objects and stable IDs across refreshes.
+
+### useCollection
+
+Accepts `items`, `getKey`, `isItemDisabled`, `matches`, `compare`, `mode`, `totalItems`, `state`, `defaultState`, and `onStateChange`. It renders no DOM and performs no fetching or mutations.
+
+| Result | Contract |
+| --- | --- |
+| `state`, `items`, `totalItems`, `pageCount` | Effective normalized state, visible rows and derived page metadata |
+| `pageSelection` | `none`, `some`, or `all` among eligible current-page records |
+| `selectableCount` | Eligible current-page record count |
+| `setQuery`, `setFilter`, `setSort`, `setPage`, `setPageSize` | Apply transitions described above |
+| `toggle(key, checked)` | Change selection for a supplied eligible record; unknown or disabled IDs are ignored |
+| `selectPage(checked)` | Add/remove eligible page IDs while preserving off-page IDs |
+| `clearSelection()` | Clear all selected IDs |
+| `removeSelection(keys)` | Remove only specified IDs, suitable for successful submitted snapshots |
+
+For a custom list, reuse the controller and compound controls:
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Checkbox, Collection, useCollection } from "@kb.ui/react";
+import { useState } from "react";
+
+export function RecordList() {
+  const [items, setItems] = useState([
+    { id: "web", name: "Website refresh" },
+    { id: "help", name: "Help center" },
+  ]);
+  const [pending, setPending] = useState(false);
+  const collection = useCollection({ items, getKey: item => item.id });
+  return (
+    <section aria-label="Project list">
+      <ul>
+        {collection.items.map(item => (
+          <li key={item.id}>
+            <Checkbox label={item.name} disabled={pending}
+              checked={collection.state.selectedKeys.includes(item.id)}
+              onCheckedChange={checked => collection.toggle(item.id, checked)} />
+          </li>
+        ))}
+      </ul>
+      <Collection.BulkActions selectedKeys={collection.state.selectedKeys}
+        onClear={collection.clearSelection} onSuccess={collection.removeSelection}
+        onPendingChange={setPending} actions={[{ key: "archive", label: "Archive",
+          onAction: keys => setItems(current => current.filter(item => !keys.includes(item.id))) }]} />
+      <Collection.Pagination page={collection.state.page}
+        pageSize={collection.state.pageSize} totalItems={collection.totalItems}
+        onPageChange={collection.setPage} disabled={pending} />
+    </section>
+  );
+}
+```
+
+### Standalone controls
+
+| Component | Required props | Optional props and behavior |
+| --- | --- | --- |
+| `Collection.Pagination` | `page`, `pageSize`, `totalItems`, `onPageChange` | `onPageSizeChange`, `pageSizes` (10, 25, 50), `disabled`, native nav props/ref. Includes current page size, emits bounded page requests; caller resets page when size changes. |
+| `Collection.BulkActions` | `selectedKeys`, `actions`, `onClear` | `onSuccess(keys)`, `onPendingChange(boolean)`, `disabled`, native `fieldset` props/ref. Caller owns selection; omitted `onSuccess` preserves it. |
+
+### Bulk-action boundary
+
+Actions receive a copied, deduplicated ID array captured at submission. Selection counts use the same distinct IDs. Buttons remain mounted during selection changes. Empty selections and disabled actions cannot submit; an immediate lock prevents repeated submission before React rerenders. Pending actions disable other workflow controls in `Collection`. Success handlers come from the latest committed render; suspended renders cannot replace an active operation’s handler. A resolved operation removes only submitted IDs; a rejected operation announces a generic failure and retains selection. Clear selection dismisses the displayed failure.
+
+Applications own permission checks, destructive confirmation, server authorization, cancellation, idempotency, optimistic updates, undo, auditing and focus recovery after record removal. A resolved promise means the complete snapshot succeeded. For partial success, reconcile affected records and selection in controlled state and reject or show application-specific detail; kbui does not infer partial outcomes. Do not automatically retry mutations. Avoid changing dataset identity while an action is pending; remount with a different React key when switching collections.
+
+### Server ownership
+
+Supply controlled state, `mode="server"`, the current response’s rows and its filtered `totalItems`. Apply emitted query, facets, sort and page to your request. Keep `loading` true while rows belong to a previous request. Cancel or discard stale responses, reconcile out-of-range pages after deletions, and expose fetch failures with `error` and a retry action through `toolbar`. Map column sort keys to an explicit server allowlist. Validate IDs and permissions again at mutation time, including off-page records.
+
+Offset pagination requires a known total. Cursor paging, unknown totals, all-matching remote selection, virtualization, column resizing, drag ordering and spreadsheet grid navigation are outside this API. Use bounded server pages for large remote datasets; client mode processes the entire supplied array and has no benchmark-backed dataset-size guarantee.
+
+### Styling and accessibility
+
+Override `--kb-collection-gap`, `--kb-collection-cell-padding`, `--kb-collection-radius`, `--kb-collection-border`, `--kb-collection-header-background`, and `--kb-collection-selected-background`, and `--kb-collection-table-min-width` (36rem) on a subtree. Partial CSS imports also need `Button`, `Checkbox`, `Input` and `Select` styles. CSS provides layout and visual states; a non-React renderer owns every state transition and ARIA relationship.
+
+Filters and page-size controls use the shared `Select` theme, keyboard navigation, option indicators and focus recovery. Labels sit above fields; filter fields wrap and pagination buttons stay grouped, with long page counts wrapping within the available width.
+
+Native table semantics, `aria-sort`, mixed checkboxes, named pagination, polite statuses and failure alerts expose workflow state. Tab moves between controls; Space toggles checkboxes; Enter/Space activate buttons. The named table viewport is keyboard focusable for horizontal scrolling. Controls wrap on narrow screens; tabular content can scroll independently. Selection remains explicit in checkbox state in forced colors.
+
+Verify the full search, sort, select-across-pages, submit, failure and retry journey with keyboard and a supported screen reader. Check 320 CSS pixels, enlarged text, both themes and forced colors. Automated stories cover their fixtures; manual screen-reader announcement and complete-page WCAG conformance remain unverified. Follow the [shared accessibility verification procedure](../../../../docs/guides/accessibility.md).
+
+## Related components
+
+Use [`Grid`](Grid.md) for static card layout, [`Checkbox`](Checkbox.md) for independent choices, and [`MultiSelect`](MultiSelect.md) for choosing values rather than operating on records. Use [`Dialog`](Dialog.md) for application-owned confirmation and [`Toast`](Toast.md) for mutation outcomes outside the collection.

package/docs/components/CollectionList.md

@@ -0,0 +1,44 @@
+# CollectionList
+
+Group records in a native list when people scan names, summaries, status and actions. Use `Table` when column-by-column comparison is the main task.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-collectionlist--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { CollectionList, CollectionRow, Link, Status } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <CollectionList aria-label="Projects">
+      <CollectionRow title={<Link href="/projects/portal">Customer portal</Link>} description="Owned by Ada Chen" metadata={<Status tone="success">Ready for review</Status>} />
+      <CollectionRow title={<Link href="/projects/search">Search improvements</Link>} description="Owned by Lin Patel" metadata={<Status tone="warning">Needs changes</Status>} />
+    </CollectionList>
+  );
+}
+```
+
+## More examples
+
+- [Ordered sequence](https://kbui.kcb.pro/storybook/?path=/story/components-collectionlist--ordered): Native `ol` markers, alphabetic `type` and `start`.
+- [Filtering](https://kbui.kcb.pro/storybook/?path=/story/components-collectionlist--filterable): App-owned search, result announcement, empty recovery and stable search focus.
+
+## Reference
+
+| Prop | Default | Behavior |
+|---|---|---|
+| `as` | `ul` | `ul` for records without a required order; `ol` for an ordered sequence |
+| `density` | `comfortable` | `comfortable` or `dense`; affects immediate `CollectionRow` children |
+| `dividers` | true | Rules between immediate `CollectionRow` children |
+
+The root accepts native attributes, `className`, `style` and the correct list ref. With `as="ol"`, native `start`, `reversed`, `type` and numbering behavior remain available. Public types are `CollectionListElement` and generic `CollectionListProps`. A default `role="list"` preserves list semantics where list-style removal affects accessibility exposure; the native element still supplies the structure. See the [W3C list styling guidance](https://design-system.w3.org/styles/lists.html#considerations) for marker removal and list semantics. This is an ordinary list with normal Tab navigation, without listbox selection or arrow-key item navigation.
+
+Use `CollectionRow` or native `li` children. A non-row `li` retains native semantics but does not receive row slot styling. If a record has leading content or an aside, the list reserves matching minimum columns across its immediate rows; missing optional content does not shift record titles. Metadata and actions share one end-aligned line, and stack beneath content, still end-aligned, when a row is narrower than 48rem. Nested lists keep their own sizing and density. Ordered markers remain visible in both directions.
+
+Your app owns stable keys, data ordering, filtering, selection policy, pagination and requests. Keep filters mounted while results update so drafts and keyboard focus survive. Put useful empty/error guidance and a named retry action outside an empty list. Use `aria-busy` for pending content and a concise status message outside the busy subtree. Pagination or virtualization is app-owned; `CollectionList` renders the children you provide.
+
+## Related components
+
+[`CollectionRow`](CollectionRow.md) supplies record slots; [`DescriptionList`](DescriptionList.md) presents individual record facts; [`Table`](Table.md) supports aligned column comparison. See [Structured data](../../../../docs/guides/structured-data.md) for composition guidance.

package/docs/components/CollectionRow.md

@@ -0,0 +1,62 @@
+# CollectionRow
+
+Make one record easy to scan inside `CollectionList`. Compose its primary name, supporting detail, optional selection, metadata and independent actions.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-collectionrow--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Button, Checkbox, CollectionList, CollectionRow, Link, Status } from "@kb.ui/react";
+import { useState } from "react";
+
+export function Example() {
+  const [selected, setSelected] = useState(false);
+  const [message, setMessage] = useState("No action taken");
+  return (
+    <>
+      <p role="status">{message}</p>
+      <CollectionList aria-label="Projects">
+        <CollectionRow
+          title={<Link href="/projects/portal">Customer portal</Link>}
+          description="Owned by Ada Chen"
+          leading={<Checkbox label="Select Customer portal" visuallyHidden checked={selected} onCheckedChange={setSelected} />}
+          metadata={<Status tone="success">Ready for review</Status>}
+          actions={<Button variant="secondary" onClick={() => setMessage("Editing Customer portal")}>Edit portal</Button>}
+          selected={selected}
+        />
+      </CollectionList>
+    </>
+  );
+}
+```
+
+## More examples
+
+- [Selection and actions](https://kbui.kcb.pro/storybook/?path=/story/components-collectionrow--selection-and-actions): `Checkbox`, primary navigation, independent Buttons, `Menu` focus return and disabled actions.
+- [Long content](https://kbui.kcb.pro/storybook/?path=/story/components-collectionrow--long-content): Wrapping identifiers, metadata and action text.
+
+## Reference
+
+| Prop | Default | Behavior |
+|---|---|---|
+| `title` | required | Record name as a `ReactNode`; compose a `Link` or correctly ranked `Heading` when appropriate |
+| `description` | unset | Supporting `ReactNode`, including `DescriptionList` or zero values |
+| `leading` | unset | `Avatar`, decorative icon or a separately named selection control |
+| `metadata` | unset | `Status`, formatted number, timestamp or other concise `ReactNode` |
+| `actions` | unset | Named Buttons, links or `Menu` composition; controls keep their own semantics |
+| `selected` | false | Visual state; a selection control owns accessible checked state |
+| `classNames` | unset | Extra classes for `layout`, `leading`, `content`, `title`, `description`, `aside`, `metadata` and `actions` |
+
+`CollectionRow` renders native `li`; place it inside `CollectionList` or another native list. Optional null, boolean and empty-string content omits its slot; numeric zero remains visible. Native list-item attributes, `className`, `style` and ref pass through. `CollectionRowProps` replaces the native title tooltip attribute with the required record title; use a `Tooltip` composition for contextual help. `CollectionRow` has no whole-row click handler, navigation destination or automatic focus stop. A link in title handles navigation; an action `Button` handles its own workflow. Independent actions do not toggle selection implicitly.
+
+Keep a persistent, record-specific name on selection controls and actions. Hide decorative icons yourself, and supply meaningful alternative text for informative images. When content can be selected, keep `selected` consistent with `Checkbox` checked state; use stable IDs when filtering or sorting. Disable actual controls for unavailable operations rather than treating the whole row as disabled. A selected row is an ordinary list item, so `CollectionRow` does not emit grid/listbox `aria-selected` semantics.
+
+`CollectionList` aligns optional leading and aside columns across rows. The defaults reserve at least 3rem for leading content and 12rem for an aside; wider leading media, or an aside that needs more room to keep metadata and actions on one line, widens its own row, so set `--kb-collectionrow-leading-width` and `--kb-collectionrow-aside-width` to your widest content to keep every title aligned. Set padding and gap with component tokens. Metadata and actions share one end-aligned line; when the row itself is narrower than 48rem, inside or outside a list, they stack beneath content in DOM order and stay end-aligned. Long labels and composed `Status` text wrap, including chips with decorative icons. Action Buttons retain size-based minimum heights while expanding for text. Dense list spacing does not shrink control targets. Standalone native lists do not provide `CollectionList`'s shared responsive alignment; use the paired components for this behavior.
+
+Your app owns loading, error text, formatting, focus after a removed record, and selection scope. Avoid nesting interactive controls inside the title link or making the whole list item act as another button. Verify keyboard order, responsive wrapping and focus in your actual composition; automated stories do not establish screen-reader interoperability or complete-page accessibility.
+
+## Related components
+
+Use [`CollectionList`](CollectionList.md) for a native record list, [`DescriptionList`](DescriptionList.md) for key/value details, [`Table`](Table.md) for comparison across columns, and [`Menu`](Menu.md) for overflow actions. See [Structured data](../../../../docs/guides/structured-data.md) for the shared decision guide.

package/docs/components/Combobox.md

@@ -0,0 +1,88 @@
+# Combobox
+
+Use `Combobox` to filter a longer option list before choosing one or multiple values. Each option has a string `value`, a visible `label`, and an optional `disabled` flag. Single selection uses `string | null`; enable `multiple` to use a `readonly string[]` value and a `(value: string[]) => void` callback. Pass `null` or `[]` for the corresponding empty selection.
+
+Multiple mode delegates to [`MultiSelect`](MultiSelect.md), including removable chips, keyboard navigation, clear-all, form submission, and disabled/read-only states. Its popup stays open after selections and deselections, retaining the current filter. Press Escape, click outside, or use the toggle to dismiss it. It uses `.kb-multiselect` CSS anatomy and `ClassNames<MultiSelectSlot>` slots, including `chips`, `chip`, `chipLabel`, and `chipRemove`. Single mode retains `.kb-combobox` anatomy. `ComboboxProps` remains the extensible single-selection interface, so existing wrappers can keep extending it. `ComboboxSingleProps` aliases that interface; use `ComboboxMultipleProps` for a multiple-selection wrapper or React's `ComponentProps<typeof Combobox>` for the complete discriminated union.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-combobox--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { useState } from "react";
+import { Combobox } from "@kb.ui/react";
+
+const regions = [
+  { value: "us-east-1", label: "US East (N. Virginia)" },
+  { value: "eu-central-1", label: "EU Central (Frankfurt)" },
+];
+
+export function RegionCombobox() {
+  const [region, setRegion] = useState<string | null>("us-east-1");
+  return (
+    <Combobox
+      label="Deployment region"
+      options={regions}
+      value={region}
+      onValueChange={setRegion}
+      placeholder="Search regions..."
+    />
+  );
+}
+```
+
+### Multiple selections
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { useState } from "react";
+import { Combobox } from "@kb.ui/react";
+
+export function DeploymentRegions() {
+  const [regions, setRegions] = useState<string[]>([]);
+  return (
+    <Combobox
+      multiple
+      label="Deployment regions"
+      options={[
+        { value: "us-east-1", label: "US East (N. Virginia)" },
+        { value: "eu-central-1", label: "EU Central (Frankfurt)" },
+      ]}
+      value={regions}
+      onValueChange={setRegions}
+      placeholder="Search regions..."
+    />
+  );
+}
+```
+
+## More examples
+
+- [Multiple selections](https://kbui.kcb.pro/storybook/?path=/story/components-combobox--multiple): Filter once, choose several options, then remove chips individually.
+- [Retained selection](https://kbui.kcb.pro/storybook/?path=/story/components-combobox--preselected): Start with a known option.
+- [No matching options](https://kbui.kcb.pro/storybook/?path=/story/components-combobox--empty): Inspect the empty state when filtering finds nothing.
+- [Validation feedback](https://kbui.kcb.pro/storybook/?path=/story/components-combobox--invalid): Associate a correction with the field.
+
+## Reference
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `label` | `string` | required | Visible field label and accessible combobox name |
+| `options` | `readonly ComboboxOption[]` | required | Selectable options filtered by label |
+| `multiple` | `boolean` | `false` | Enable multiple selections; determines value and callback types |
+| `value` | `string \| null` or `readonly string[]` | required | Single selection or multiple selected values |
+| `onValueChange` | `(value: string \| null) => void` or `(value: string[]) => void` | required | Callback matches selection mode |
+| `placeholder` | `string` | unset | Input placeholder shown when empty |
+| `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; disabled also blocks form submission |
+| `clearLabel` / `toggleLabel` | `string` | derived from `label` | Accessible names for the clear and toggle buttons |
+| `container` | `Combobox.Portal.Props["container"]` | field root | Portal host; default retains nested theme |
+| `classNames` | `ClassNames<ComboboxSlot>` or `ClassNames<MultiSelectSlot>` | unset | Slots match selection mode |
+| `removeLabel` | `(option: ComboboxOption) => string` | `"Remove {option.label}"` | Multiple mode only; accessible chip removal name |
+
+## Related components
+
+Use [`Select`](Select.md) for a dropdown without text filtering, [`RadioGroup`](RadioGroup.md) for visible options, and [`MultiSelect`](MultiSelect.md) for several searchable choices.

package/docs/components/ConfirmAction.md

@@ -0,0 +1,100 @@
+# ConfirmAction
+
+`ConfirmAction` puts a destructive action behind a modal confirmation built on [`Dialog`](Dialog.md). The trigger only opens the confirmation; `onConfirm` runs after a second, explicit choice. It owns Cancel-first focus, the pending guard, blocked dismissal while pending, the failure alert with retry, and closing only after success.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-confirmaction--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { useState } from "react";
+import { ConfirmAction } from "@kb.ui/react";
+
+async function deleteProject(): Promise<void> {
+  const response = await fetch("/api/projects/portal", { method: "DELETE" });
+  if (!response.ok) throw new Error(`Delete failed: ${response.status}`);
+}
+
+export function Example() {
+  const [deleted, setDeleted] = useState(false);
+  return (
+    <>
+      <p role="status">{deleted ? "Project deleted." : ""}</p>
+      <ConfirmAction
+        title="Delete project?"
+        description="This permanently removes the project and its data."
+        pendingLabel="Deleting…"
+        errorMessage="Could not delete the project. Try again."
+        onConfirm={deleteProject}
+        onConfirmed={() => setDeleted(true)}
+      >
+        Delete project
+      </ConfirmAction>
+    </>
+  );
+}
+```
+
+## More examples
+
+- [Default](https://kbui.kcb.pro/storybook/?path=/story/components-confirmaction--default): A danger-zone deletion with consequence details and a pending state.
+- [Failure and retry](https://kbui.kcb.pro/storybook/?path=/story/components-confirmaction--failure-and-retry): The first attempt fails, the dialog stays open with an alert, and the retry succeeds.
+- [Row action](https://kbui.kcb.pro/storybook/?path=/story/components-confirmaction--row-action): A quiet row trigger whose success removes the row and moves focus to the list heading.
+
+## Reference
+
+| Part or behavior | Purpose |
+| --- | --- |
+| Trigger | A `danger` [`Button`](Button.md) by default. Native button props, `ref`, `className` and `disabled` reach it. Replace its look with `render`, such as `render={<Button variant="ghost" size="sm" />}`. |
+| Popup | A `Dialog.Content` with `.kb-confirmaction`. `title` names it and `description` describes it; `details` adds further consequence content. |
+| Actions | Cancel first, focused on open, then a `danger` confirm button. |
+| Pending | While `onConfirm` runs, the popup has `aria-busy` and `data-pending`, Escape is ignored, and both buttons stay focusable with `aria-disabled` and ignore presses, so focus is never dropped. |
+| Failure | A throw or rejection keeps the dialog open and shows `errorMessage` in a `role="alert"` danger [`Callout`](Callout.md). Confirming again retries. Closing or reopening clears the error. |
+| Success | The dialog closes, focus returns to the trigger or `finalFocus`, then `onConfirmed` runs. |
+| Outside press | Never dismisses, pending or not. |
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | required | Trigger text; also the confirm button text unless `confirmLabel` is set |
+| `title` | `ReactNode` | required | `Dialog` heading and accessible name; ask the question the action settles |
+| `description` | `ReactNode` | unset | The consequence; the dialog's accessible description |
+| `details` | `ReactNode` | unset | Further consequence content, such as what else is removed |
+| `onConfirm` | `() => unknown` | required | Runs the action. Return a promise for asynchronous work; throw or reject on failure |
+| `onConfirmed` | `() => void` | unset | Runs once per success, after the popup has unmounted; remove the trigger here. Also runs when success lands after a controlled close |
+| `confirmLabel` | `ReactNode` | `children` | Confirm button text; repeat the action's verb |
+| `pendingLabel` | `ReactNode` | `confirmLabel` | Confirm button text while the action runs |
+| `cancelLabel` | `ReactNode` | `"Cancel"` | Cancel button text |
+| `errorMessage` | `ReactNode \| (error: unknown) => ReactNode` | `"The action did not complete. Try again."` | Alert text after a failure; a function receives the thrown reason |
+| `open` | `boolean` | uncontrolled | Controlled visibility |
+| `defaultOpen` | `boolean` | `false` | Initial visibility when uncontrolled |
+| `onOpenChange` | `(open: boolean) => void` | unset | Each visibility change, including the close after success; pending dismissals never reach it |
+| `finalFocus` | `Dialog` `finalFocus` | trigger | Focus target after closing; set it when success removes the trigger |
+| `container` | portal container | document body | Themed host for the popup |
+| `classNames` | `{ popup?, backdrop?, details?, error? }` | unset | Classes for inner parts |
+| `render` | Base UI `render` | `<Button variant="danger" />` | Trigger element |
+
+```tsx
+<ConfirmAction
+  render={<Button variant="ghost" size="sm" />}
+  aria-label="Revoke Laptop"
+  title="Revoke Laptop?"
+  description="Requests signed with this key fail immediately."
+  confirmLabel="Revoke key"
+  finalFocus={listHeading}
+  onConfirm={() => revokeKey("laptop")}
+  onConfirmed={() => removeRow("laptop")}
+>
+  Revoke
+</ConfirmAction>
+```
+
+## Responsibilities
+
+The application owns the operation: authorization, idempotency, timeouts and what the server deletes. `onConfirm` must settle; a promise that never settles leaves the dialog pending. Announce success in the page, because the dialog is gone when it completes. Remove the trigger's row in `onConfirmed`, not inside `onConfirm`: a data layer that removes the row while the action is still settling unmounts the dialog mid-close and loses focus. Do not attach the same action anywhere else on the trigger; the confirmation is its one route.
+
+For an urgent interruption that needs `alertdialog` semantics, use an alert-dialog primitive. `ConfirmAction` remains a named modal dialog, as the [confirmation pattern](../../../../docs/guides/forms-and-overlays.md#confirmation-pattern) describes.
+
+## Related components
+
+Use [`Dialog`](Dialog.md) to compose a confirmation that needs fields or a different action layout. Use [`Button`](Button.md) `variant="danger"` alone only when the action is reversible, such as one with undo.

package/docs/components/Container.md

@@ -0,0 +1,41 @@
+# Container
+
+Centered page boundary with responsive inline gutters. Native props and matching ref pass through. See [Layout composition](https://github.com/KhallilB/kbui/blob/main/docs/guides/layout.md) for rules, CSS recipes and token overrides.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/layout-container--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Container } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <Container as="main">
+      <h1>Projects</h1>
+      <p>Your current work.</p>
+    </Container>
+  );
+}
+```
+
+## More examples
+
+- [A composed page](https://kbui.kcb.pro/storybook/?path=/story/layout-container--page): Combine a page boundary, content, and actions.
+- [Narrow viewports](https://kbui.kcb.pro/storybook/?path=/story/layout-container--responsive): Compare responsive gutters.
+- [Width choices](https://kbui.kcb.pro/storybook/?path=/story/layout-container--sizes): Compare available page widths.
+
+## Reference
+
+| Prop     | Values                                                     | Default |
+| -------- | ---------------------------------------------------------- | ------- |
+| `as`     | `div` `main` `section` `article` `aside` `header` `footer` | `div`   |
+| `size`   | `sm` (40rem) `md` (64rem) `lg` (80rem) `full` (unbounded)  | `lg`    |
+| `gutter` | Shared 1–2rem inline padding; false removes it             | `true`  |
+
+Set `as` explicitly when using an element other than the default; native props and refs then match that element. An explicit `gutter` value takes priority over a conflicting data attribute. Widths include side padding. Use one page container, and turn off nested gutters when the parent already provides padding.
+
+## Related components
+
+Use [`Inline`](Inline.md) for a row, [`Stack`](Stack.md) for vertical flow, [`Grid`](Grid.md) for a collection, and [`Split`](Split.md) for two responsive columns.

package/docs/components/CopyableText.md

@@ -0,0 +1,93 @@
+# CopyableText
+
+Copy identifiers, commands and references with explicit feedback. Values remain selectable, including when clipboard permission is denied.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-copyabletext--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { CopyableText } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <CopyableText
+      label="Request ID"
+      value="req_01JCP6NF8B4M2WQ9K7X3"
+      copyLabel="Copy request ID"
+    />
+  );
+}
+```
+
+`value` is the clipboard source. Case, whitespace, Unicode and trailing newlines are preserved. `children` can format the collapsed display independently; expanding or a copy failure reveals the exact value for inspection and manual copying. Do not use this component to conceal secrets.
+
+The native `button` retains focus while a write is pending. Repeated activation during that write does nothing. Success appears only after the Clipboard API resolves; its callback receives the copied value. If value changes, the component is disabled, or it unmounts, outstanding writes cannot update feedback or fire callbacks. A write already sent to the operating system cannot be cancelled.
+
+A visible failure message remains until retry or content change. Users can select the full value and copy manually. Clipboard writes require a secure context such as HTTPS or localhost; browser permission, user activation, iframe policy or host restrictions can still reject them. No legacy clipboard fallback is attempted.
+
+With `truncate`, a single-line preview has an explicit `Show full value` button. Activating it wraps the complete raw value across the field width; `Show less` restores the compact preview. The action works with touch, Enter and Space, retains focus, and exposes `aria-expanded` and `aria-controls`. It stays available when copying is disabled. A changed value resets the disclosure. Failure automatically expands it; users can collapse it again deliberately. CSS truncation preserves full text in the accessibility tree; disclosure controls visual wrapping. No hover-only tooltip is required.
+
+Set `tone` to color the value and softly tint field appearance. Neutral is the default; accent, info, success, warning and danger reuse semantic theme colors. Tone is emphasis, not clipboard state or an announcement. Keep meaning in the label and value, including forced-colors mode. For a custom neutral color, override `--kb-copyabletext-value-color`; use `classNames.value` for richer display styling.
+
+Set `highlight` to a string or array of literal, case-sensitive terms. Matches use semantic `mark` elements with bold emphasis; the longest match wins when terms overlap at the same position. Matching never interprets HTML or regular expressions and never changes copied content.
+
+Automatic `format="auto"` recognizes HTTP(S) and `www.` URLs, qualified ASCII email addresses, backtick-delimited inline code, fenced code, valid JSON objects/arrays, and conservative JavaScript/TypeScript, CSS, HTML and common package-manager/Git/curl command patterns. `Code` receives the existing syntax colors and suppresses navigation inside source. Delimiters, whitespace and clipboard bytes remain literal.
+
+Use `format="text"` for identifiers or prose that resemble code, or `format="code"` with `language` for explicit source. A language hint forces code in automatic mode. Detection is intentionally conservative; it does not validate email deliverability or infer every programming language. Unknown fenced languages render as plain code. For large listings, prefer `CodeBlock`.
+
+Detected links reuse `Link` styling and `Link.Provider`. Emails use mailto destinations with an encoded address; web links remain underlined native anchors. Sentence punctuation and unmatched closing brackets stay outside anchors. Set `linkify={false}` to disable detected links, or `linkify` with `format="text"` to opt back into links without code detection. Authored children retain caller-owned `Link`, strong, em or `Code` composition; automatic formatting applies to displayed raw source.
+
+In truncated previews, detected links become interactive only after expansion. This keeps clipped links out of Tab order. After expanding, Shift+Tab reaches links above the disclosure; Tab continues to Copy. Copying remains a separate action. Errors expand the same formatted raw source for manual selection. `mono={false}` gives prose the proportional font and body line spacing.
+
+## More examples
+
+- [Automatic recognition](https://kbui.kcb.pro/storybook/?path=/story/components-copyabletext--automatic): URLs, emails, inline commands and source code.
+- [Text and links](https://kbui.kcb.pro/storybook/?path=/story/components-copyabletext--rich-content): prose with literal highlights and native web links.
+- [References](https://kbui.kcb.pro/storybook/?path=/story/components-copyabletext--references): identifiers, URLs and invitation text.
+- [Inline](https://kbui.kcb.pro/storybook/?path=/story/components-copyabletext--inline): compact reference beside prose.
+- [Long values](https://kbui.kcb.pro/storybook/?path=/story/components-copyabletext--long-value): expand and collapse a full-width wrapped value.
+- [Colors](https://kbui.kcb.pro/storybook/?path=/story/components-copyabletext--colors): six value tones with matching field tints.
+- [Copy feedback](https://kbui.kcb.pro/storybook/?path=/story/components-copyabletext--copy-feedback): pending, focus retention and success.
+- [Copy failure](https://kbui.kcb.pro/storybook/?path=/story/components-copyabletext--copy-failure): persistent recovery instructions.
+- [Localized](https://kbui.kcb.pro/storybook/?path=/story/components-copyabletext--localized): translated button and announcement text.
+
+## Reference
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `value` | `string` | required | Exact clipboard contents; empty string disables action |
+| `children` | `ReactNode` | `value` | Optional display; exact value is shown on failure |
+| `label` | `string` | unset | Visible context above value; does not name the button |
+| `appearance` | `"field" \| "plain"` | `"field"` | Bordered field or inline treatment |
+| `size` | `"sm" \| "md"` | `"md"` | Density; default copy target follows button height token |
+| `mono` | `boolean` | `true` | Monospace value display |
+| `tone` | `CopyableTextTone` | `"neutral"` | `neutral`, `accent`, `info`, `success`, `warning` or `danger`; independent of copy state |
+| `truncate` | `boolean` | `false` | Single-line preview with explicit full-value disclosure |
+| `expandLabel` | `string` | `"Show full value"` | `Disclosure` text when collapsed |
+| `collapseLabel` | `string` | `"Show less"` | `Disclosure` text when expanded |
+| `disabled` | `boolean` | `false` | Disables copying, retains selectable value |
+| `copyLabel` | `string` | `"Copy"` | Visible action and accessible name; use specific purpose |
+| `copyingLabel` | `string` | `"Copying…"` | Pending label and polite announcement |
+| `copiedLabel` | `string` | `"Copied"` | Success label |
+| `copyErrorLabel` | `string` | `"Retry copy"` | Failure label; action retries |
+| `successMessage` | `string` | `"Copied to clipboard"` | Polite success announcement |
+| `errorMessage` | `string` | `"Copy failed. Select and copy the text manually."` | Visible polite error and recovery instructions |
+| `feedbackDuration` | `number` | `2000` | Success reset in milliseconds; zero retains success, invalid or negative uses default |
+| `onCopy` | `(value: string) => void` | unset | Current write succeeded; replaces native clipboard event prop |
+| `onCopyError` | `(error: unknown) => void` | unset | Current write failed, including unavailable API |
+| `highlight` | `string \| readonly string[]` | unset | Literal case-sensitive terms; empty terms ignored, longest overlapping match wins |
+| `format` | `CopyableTextFormat` | `"auto"` | `auto`, `text`, or `code`; conservative recognition with explicit overrides |
+| `language` | `CodeLanguage` | unset | `Code` hint; forces code in auto mode; text mode remains literal |
+| `linkify` | `boolean` | automatic | Override detected web/email links; false disables links; code ranges never become links |
+| `classNames` | `Partial<Record<CopyableTextPart, string>>` | unset | `label`, `value`, `actions`, `toggle`, `copy`, `feedback`, `link`, `highlight`, `code` slots |
+| `className`, `ref`, other props | Native `span` props | unset | Root element; native `onCopy` replaced by success callback |
+
+The root exposes `data-copy-state="idle|pending|copied|failed"`, appearance, size, tone, mono, expandable, expanded, truncate and disabled attributes. Pending sets `aria-disabled` on the button while preserving focus. The status region exists before interaction and is empty initially. Failure is both visible and announced; success has a visible button label and polite announcement.
+
+Use `--kb-copyabletext-highlight-background` for marked text and `Link` tokens for navigation styling. Standalone CSS users also load `link.css` and `code.css` for detected links and syntax styling. Use `--kb-copyabletext-*` tokens for gap, padding, radius, border, background, neutral value color, target size and minimum copy width. `className` styles the root; `classNames` styles individual parts. Verify contrast and target sizes after overrides. Automated tests cover component behavior, browser keyboard activation and accessibility scans; screen-reader announcement quality remains a human verification task.
+
+## Related components
+
+Use [`CodeBlock`](CodeBlock.md) for highlighted source and multiline commands, [`Code`](Code.md) for inline literals, and [`Link`](Link.md) for navigation. [Copyable content guidance](https://github.com/KhallilB/kbui/blob/main/docs/guides/copyable-content.md) covers shared recovery and localization.