@kb.ui/react 0.10.3 → 0.11.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 columns across its immediate rows; missing optional content does not shift record titles. Metadata and actions stack beneath content below 40rem of available width. 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 3rem for leading content and 12rem for an aside; override `--kb-collectionrow-leading-width` and `--kb-collectionrow-aside-width` for your content. Set padding and gap with component tokens. Below 40rem of parent list width, metadata and actions stack beneath content in DOM order. 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/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`  |
+
+Non-default generic native elements require an explicit `as`; native props and refs follow that element. Explicit `gutter` owns its data attribute even when caller attributes conflict. Widths include gutters. Use one page boundary; nested containers should disable gutters when the parent owns padding.
+
+## Related components
+
+Use [Inline](Inline.md) for a row, [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.

package/docs/components/DescriptionList.md

@@ -0,0 +1,61 @@
+# DescriptionList
+
+Present named facts about one record with native description-list relationships. Use Table when readers need to compare the same fields across records.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-descriptionlist--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { DescriptionList, Link, Status } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <DescriptionList aria-label="Project details">
+      <DescriptionList.Item>
+        <DescriptionList.Term>Owner</DescriptionList.Term>
+        <DescriptionList.Detail><Link href="/people/ada">Ada Chen</Link></DescriptionList.Detail>
+      </DescriptionList.Item>
+      <DescriptionList.Item>
+        <DescriptionList.Term>Status</DescriptionList.Term>
+        <DescriptionList.Detail><Status tone="success">Ready for review</Status></DescriptionList.Detail>
+      </DescriptionList.Item>
+      <DescriptionList.Item>
+        <DescriptionList.Term>Open tasks</DescriptionList.Term>
+        <DescriptionList.Detail>{0}</DescriptionList.Detail>
+      </DescriptionList.Item>
+    </DescriptionList>
+  );
+}
+```
+
+## More examples
+
+- [Responsive](https://kbui.kcb.pro/storybook/?path=/story/components-descriptionlist--responsive): Stacks according to its parent width.
+- [Nested details](https://kbui.kcb.pro/storybook/?path=/story/components-descriptionlist--nested): Independent density and layout inside another detail value.
+
+## Reference
+
+| Part | Native element | Purpose |
+|---|---|---|
+| `DescriptionList` | `dl` | Root description list; native naming attributes, children, styles and ref pass through |
+| `DescriptionList.Item` | `div` | Groups one Term with one or more Detail elements |
+| `DescriptionList.Term` | `dt` | Meaningful label in reading order before its values |
+| `DescriptionList.Detail` | `dd` | Text, numbers, links, status or richer content; repeated Details support multiple values |
+
+| Prop | Default | Behavior |
+|---|---|---|
+| `layout` | `responsive` | `responsive` uses label/value columns, stacking below 32rem of available width; `horizontal` keeps columns; `stacked` always puts values below labels |
+| `density` | `comfortable` | `comfortable` or `dense`; changes immediate Item spacing |
+| `dividers` | true | Rules between immediate groups |
+
+Every part accepts its native attributes, `className`, `style` and ref. Types are `DescriptionListProps`, `DescriptionListItemProps`, `DescriptionListTermProps` and `DescriptionListDetailProps`. Use a real `dt` before its `dd` values; the description list does not become a table or listbox. Group alternate names inside one Term when they share values. Native IDs and `aria-labelledby` remain available for richer relationships.
+
+Values align to the same column across Items. Long labels, identifiers and composed Status text wrap, including chips with decorative icons; native links and controls retain their keyboard behavior. Use a deliberate stacked layout for narrow details, or override `--kb-descriptionlist-term-width` when the default 12rem label cap does not fit your labels. Other tokens control column/row gaps and comfortable/dense block padding. Nested lists keep their own layout and density.
+
+Keep zero values visible. Write a meaningful unavailable value such as Not scheduled rather than silently omitting a required fact. Your app owns formatting, units, timezone, localization, loading, errors and announcements. Do not use term text as an input label; controls still need their own labels and relationships. A description list supplies native relationships, not interactive field validation.
+
+## Related components
+
+Use [Table](Table.md) for comparing fields across records, [CollectionRow](CollectionRow.md) for summarizing records with actions, and [Status](Status.md) for an explicit state. See [Structured data](../../../../docs/guides/structured-data.md) for choosing and composing these patterns.