@kb.ui/react 0.10.4 → 0.12.0

package/docs/components/FormSection.md

@@ -0,0 +1,57 @@
+# FormSection
+
+Use `FormSection` to group related fields under a section heading, with optional help, a section error and the section's own actions. It renders a native `fieldset` named by its heading, so screen reader users can browse sections by heading and hear the group name on entry. Use [`Form`](Form.md) or [`Settings`](Settings.md) to arrange several sections.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-formsection--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Button, FormSection, Input } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <form onSubmit={(event) => event.preventDefault()}>
+      <FormSection
+        title="Profile"
+        description="Shown to everyone in your workspace."
+        actions={<Button type="submit">Save profile</Button>}
+      >
+        <Input label="Display name" name="name" />
+        <Input label="Job title" name="title" />
+      </FormSection>
+    </form>
+  );
+}
+```
+
+## More examples
+
+- [Heading beside fields](https://kbui.kcb.pro/storybook/?path=/story/components-formsection--split-layout): `Split` layout, which stacks below 40rem of section width.
+- [Section error](https://kbui.kcb.pro/storybook/?path=/story/components-formsection--section-error): A group-level error alongside a field error.
+- [Pending save](https://kbui.kcb.pro/storybook/?path=/story/components-formsection--pending-save): Lock every field and action while a save is in flight.
+
+## Reference
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `title` | `ReactNode` | required | Section heading; also names the group |
+| `headingLevel` | `2 \| 3 \| 4 \| 5 \| 6` | `2` | Heading rank; follow the page outline |
+| `description` | `ReactNode` | unset | Help text; added to the group's `aria-describedby` |
+| `error` | `ReactNode` | unset | Section error; sets `data-invalid` and `aria-invalid` and describes the group |
+| `actions` | `ReactNode` | unset | Buttons rendered in [`FormActions`](FormActions.md) after the fields |
+| `actionsAlign` | `"start" \| "end" \| "between"` | `"end"` | Alignment of the actions row |
+| `layout` | `"stack" \| "split"` | unset | Heading above or beside the fields; unset stacks, or splits inside `Settings` |
+| `disabled` | `boolean` | `false` | Native fieldset disabling for every field and action |
+| `classNames` | `{ header?, title?, description?, body?, fields?, error?, actions? }` | unset | Classes for inner parts |
+
+Other native `fieldset` props and `ref` pass through. A caller `aria-describedby` follows the description and error ids, and a caller `aria-invalid` token such as `"spelling"` is kept. The section heading names the group with `aria-labelledby`, unless you pass `aria-label`: a native `legend` cannot sit in the split layout's first column.
+
+`Split` layout puts the header in one third and the fields in two thirds when the section is at least `--kb-formsection-collapse` (40rem) wide, and stacks them below that. Actions sit last in the section body, end-aligned. Below 30rem of row width, each button or link in the actions fills its own row so targets stay wide on phones; other content, such as a spinner, keeps its size. Tokens: `--kb-formsection-gap`, `--kb-formsection-header-gap`, `--kb-formsection-fields-gap` and `--kb-formsection-collapse`.
+
+Your app owns validation, saving and the announcement of saved or failed sections. While saving, pass `disabled` and `aria-busy`. Native disabling takes focus away from the pressed Save button, so move focus to a status message outside the section (`role="status"`, `tabIndex={-1}`) and report the result there.
+
+## Related components
+
+Use [`Fieldset`](Fieldset.md) for a question-style group with a legend inside a section, [`FormActions`](FormActions.md) for a form-wide action row and [`ErrorSummary`](ErrorSummary.md) for recovery after a failed submit.

package/docs/components/Gallery.md

@@ -0,0 +1,84 @@
+# Gallery
+
+Use `Gallery` for a page of image-led items, such as a product catalog, a portfolio or a media library. It is the page frame, up to 80rem wide, with a header region, an optional filters region and the items as a list, with one to four columns as the gallery widens. For records you scan by text, use [`CollectionList`](CollectionList.md) or [`Table`](Table.md); for a handful of metrics or links, use [`Grid`](Grid.md).
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/layout-gallery--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Button, Card, Gallery, Grid, Heading, Image, Input, PageHeader, Text } from "@kb.ui/react";
+import { useState } from "react";
+
+const products = [
+  { id: "classic", name: "The Schu Classic", price: 89, src: "/schu-classic.jpg", alt: "Sage knit sneaker with a white sole" },
+  { id: "trail", name: "The Schu Trail", price: 99, src: "/schu-trail.jpg", alt: "Charcoal knit sneaker with an amber sole" },
+];
+
+export function Example() {
+  const [query, setQuery] = useState("");
+  const visible = products.filter((product) => product.name.toLowerCase().includes(query.toLowerCase()));
+  return (
+    <main>
+      <Gallery
+        header={<PageHeader title="Sneakers" description="Our own model beside the brands you love." />}
+        filters={
+          <>
+            <Input label="Search" type="search" value={query} onChange={(event) => setQuery(event.currentTarget.value)} />
+            <Text role="status" size="sm" tone="muted">
+              {visible.length === 1 ? "1 sneaker" : `${visible.length} sneakers`}
+            </Text>
+          </>
+        }
+        itemsLabel="Sneakers"
+        empty={<Text>No sneakers match your search.</Text>}
+      >
+        {visible.map((product, index) => (
+          <Gallery.Item key={product.id} featured={index === 0}>
+            <Card aria-labelledby={`${product.id}-name`}>
+              <Grid layout="stack" gap="sm">
+                <Image src={product.src} alt={product.alt} ratio={index === 0 ? "wide" : "landscape"} loading="lazy" />
+                <Heading level={2} size="sm" id={`${product.id}-name`}>
+                  {product.name}
+                </Heading>
+                <Text>${product.price}</Text>
+                <Button variant="secondary">
+                  Add to cart<span className="kb-sr-only">, {product.name}</span>
+                </Button>
+              </Grid>
+            </Card>
+          </Gallery.Item>
+        ))}
+      </Gallery>
+    </main>
+  );
+}
+```
+
+## More examples
+
+- [Product catalog](https://kbui.kcb.pro/storybook/?path=/story/layout-gallery--product-catalog): A sneaker shop that features its own model, with search, brand and sort filters.
+- [No results](https://kbui.kcb.pro/storybook/?path=/story/layout-gallery--no-results): The empty region replaces the list until the filters are cleared.
+- [Inspection](https://kbui.kcb.pro/storybook/?path=/story/layout-gallery--inspection): Square thumbnails that open a full, uncropped preview in a `Dialog`.
+
+## Reference
+
+| Part / prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `header` | `ReactNode` | unset | Page title, intro and actions; usually a `PageHeader` |
+| `filters` | `ReactNode` | unset | Search, filter and sort controls and a result count |
+| `itemsLabel` | `string` | unset | Accessible name for the item list |
+| `empty` | `ReactNode` | unset | Shown in place of the list when there are no items |
+| `classNames` | `{ header?, filters?, items?, empty? }` | unset | Classes for the regions |
+| `Gallery.Item` | native `li` props | `li` | One item; `featured` spans two columns once the list has two |
+
+Other native `div` props and `ref` pass through to the root; `Gallery.Item` forwards its own. The items region is a [`Grid`](Grid.md) rendered as `ul`, so wrap every item in `Gallery.Item`.
+
+Placement is fixed in the stylesheet and measured on the gallery's own width, not the viewport: one column below 30rem, two from 30rem, three from 48rem and four from 64rem. Filters share a row, each at least 12rem wide, and wrap below it. Item content stretches to the row height; spacing inside an item belongs to its content, such as a stacked `Grid`. Pass items directly or inside fragments: a component that renders no items still counts as one, so `empty` cannot replace the list. Put featured items first: the list keeps DOM order and does not backfill gaps. `Gallery` is also the page frame: it fills its parent up to 80rem, centred, with gutters of 1rem, then 1.5rem from 48rem and 2rem from 64rem of viewport width, so do not wrap it in a [`Container`](Container.md). Tokens: `--kb-gallery-max-width`, `--kb-gallery-gutter-sm`, `--kb-gallery-gutter-md`, `--kb-gallery-gutter-lg`, `--kb-gallery-gap`, `--kb-gallery-filters-gap` and `--kb-gallery-filter-min-width`.
+
+Give every meaningful image an `alt` that says what differs between items, such as colour or material; repeat nothing the item heading already says. Name each item with its heading and include that name in item actions. Announce result counts after filtering with a status message, and when a recovery action such as "Clear filters" removes the empty region, move focus to the control it reset. Your app owns data, filtering, pagination and cart state.
+
+## Related components
+
+Frame media with [`Image`](Image.md) or [`Thumbnail`](Thumbnail.md), open the page with [`PageHeader`](PageHeader.md), show an empty result with [`EmptyState`](EmptyState.md) and inspect an item in a [`Dialog`](Dialog.md).

package/docs/components/Grid.md

@@ -0,0 +1,66 @@
+# Grid
+
+Arrange cards or other content in responsive columns, fixed column counts, or a single vertical stack. `Grid` uses ordinary CSS layout, without an ARIA grid role or special keyboard navigation, and resets native list markers and margins when rendered as `ul` or `ol`.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/layout-grid--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Card, Grid } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <Grid as="ul" role="list" columns={2} gap="md" aria-label="Projects">
+      <Card as="li">
+        <h2>First project</h2>
+        <p>Ready for review.</p>
+      </Card>
+      <Card as="li">
+        <h2>Second project</h2>
+        <p>In progress.</p>
+      </Card>
+    </Grid>
+  );
+}
+```
+
+## More examples
+
+- [Fixed column counts](https://kbui.kcb.pro/storybook/?path=/story/layout-grid--columns): Compare one through four equal columns.
+- [Responsive minimum widths](https://kbui.kcb.pro/storybook/?path=/story/layout-grid--column-widths): Compare automatic wrapping at different minimum item widths.
+- [Gaps and alignment](https://kbui.kcb.pro/storybook/?path=/story/layout-grid--gaps-and-alignment): Compare spacing presets and cross-axis alignment.
+- [A vertical collection](https://kbui.kcb.pro/storybook/?path=/story/layout-grid--stacked-list): Keep list structure while stacking items.
+
+## Reference
+
+| Prop                        | Type                                                | Default                | Notes                                                                                                    |
+| --------------------------- | --------------------------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------- |
+| `as`                        | `div` / `ul` / `ol`                                 | `div`                  | Use ul or ol for a collection; children must then be list items                                          |
+| `layout`                    | `auto` / `stack`                                    | `auto`                 | Auto fits equal columns to available width; stack uses one column                                        |
+| `columns`                   | `auto` / `1` / `2` / `3` / `4`                      | `auto`                 | Explicit equal column count (collapsing to 1 when the grid is narrower than 30rem) or automatic wrapping |
+| `minItemWidth`              | `sm` / `md` / `lg`                                  | `md`                   | Minimum width (`14rem`, `18.75rem`, `24rem`) before automatic columns wrap                               |
+| `gap`                       | `none` / `sm` / `md` / `lg`                         | `lg` (`--kb-grid-gap`) | Space between columns and stacked rows                                                                   |
+| `align`                     | `start` / `center` / `end` / `baseline` / `stretch` | `stretch`              | Cross-axis alignment within each grid row                                                                |
+| `children`                  | `ReactNode`                                         | unset                  | Content in document and keyboard order                                                                   |
+| `className`, `style`, `ref` | native element props                                | unset                  | Style and reference the chosen container                                                                 |
+
+```tsx
+<Grid as="ul" role="list" layout="stack" gap="md" aria-label="Projects">
+  <Card as="li">
+    <h2>
+      <a href="/project">Project</a>
+    </h2>
+    <p>Summary</p>
+  </Card>
+</Grid>
+```
+
+Use `minItemWidth`, `columns`, `gap`, and `align` for common layouts, or override `--kb-grid-gap` and `--kb-grid-min-item-width` (`-sm`, `-md`, `-lg`) on a subtree. Keep the visual order the same as the reading order.
+
+`Grid` removes list markers. Include `role="list"` on list renderings to retain list exposure in Safari when `list-style: none` is applied; see [MDN’s list-style accessibility guidance](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/list-style#accessibility). Confirm list/item announcement with your supported browser and screen reader.
+
+## Related components
+
+Use [`Split`](Split.md) for exactly two weighted columns, [`Inline`](Inline.md) for a wrapping row of independent items, and [`Stack`](Stack.md) for vertical flow that never forms columns.

package/docs/components/Heading.md

@@ -0,0 +1,40 @@
+# Heading
+
+Native `h1`–`h6` headings with visual size independent of rank.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-heading--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Heading } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <Heading level={1} size="lg">
+      Project overview
+    </Heading>
+  );
+}
+```
+
+## More examples
+
+- [Document hierarchy](https://kbui.kcb.pro/storybook/?path=/story/components-heading--hierarchy): Compare semantic heading ranks.
+- [Visual hierarchy](https://kbui.kcb.pro/storybook/?path=/story/components-heading--sizes): Compare sizes separately from heading rank.
+- [A complete article](https://kbui.kcb.pro/storybook/?path=/story/components-heading--article): Combine `Heading`, `Text`, `Link`, and `Code`.
+
+## Reference
+
+| Prop               | Type                                      | Default    | Notes                                                                      |
+| ------------------ | ----------------------------------------- | ---------- | -------------------------------------------------------------------------- |
+| `level`            | `1` \| `2` \| `3` \| `4` \| `5` \| `6`    | `2`        | Document rank; choose from page structure                                  |
+| `size`             | `sm` \| `md` \| `lg` \| `xl` \| `display` | From level | Levels 1–6 map to xl, lg, md, sm, sm, sm; display is an explicit hero size |
+| `className`, `ref` | Native heading props                      | unset      | Classes merge; ref targets native heading                                  |
+
+Use one page title and nest section ranks without skipping levels. Adjust `size` for context without changing the outline. Headings have no margin; use `Grid` or parent layout for spacing. See [Typography](https://github.com/KhallilB/kbui/blob/main/docs/guides/typography.md) for composition, CSS recipes and accessibility guidance.
+
+## Related components
+
+Pair with [`Text`](Text.md), [`Link`](Link.md), and [`Code`](Code.md) for readable document content.

package/docs/components/Image.md

@@ -0,0 +1,62 @@
+# Image
+
+Reserve a stable frame for images, with crop, contain and fallback states. The same accessible alternative remains available while loading and after failure.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-image--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Image } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <Image
+      src="/products/studio-coat.jpg"
+      alt="Sand wool coat with broad lapels"
+      ratio="portrait"
+      fit="contain"
+      width={900}
+      height={1200}
+      fallback="Preview unavailable"
+    />
+  );
+}
+```
+
+## More examples
+
+- [Crop and contain](https://kbui.kcb.pro/storybook/?path=/story/components-image--crop-and-contain): Compare detail crops with complete product images.
+- [Ratios](https://kbui.kcb.pro/storybook/?path=/story/components-image--ratios): Square, wide, intrinsic and missing media.
+- [Failure and recovery](https://kbui.kcb.pro/storybook/?path=/story/components-image--failure-and-recovery): Replace a failed source without shifting layout.
+
+- [Editorial image library](https://kbui.kcb.pro/storybook/?path=/story/components-image--asset-library): Ten original portrait, object and scene illustrations with individual downloads.
+
+## Reference
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `alt` | `string` | required | Accessible alternative; empty string hides decorative media |
+| `src`, `srcSet`, `sizes` | native image attributes | unset | Responsive source selection; changing these resets request state |
+| `ratio` | `ImageRatio` | `"landscape"` | `square` (1:1), `landscape` (4:3), `portrait` (3:4), `wide` (16:9), or `auto` |
+| `width`, `height` | native image dimensions | unset | Forwarded to img; with `ratio="auto"`, reserve their ratio before loading |
+| `fit` | `"cover"` \| `"contain"` | `"cover"` | Crop to fill or show entire image |
+| `position` | CSS object position | browser center | Focal point, such as `"50% 25%"` |
+| `fallback` | `ReactNode` | image outline icon | Non-interactive visual for loading, missing and failed media |
+| `loading`, `fetchPriority` | native image attributes | browser defaults | Choose lazy/eager loading and priority per placement |
+| `decoding` | native image attribute | `"async"` | Decode preference |
+| `crossOrigin`, `referrerPolicy` | native image attributes | unset | Request policy |
+| `onLoad`, `onError` | native image handlers | unset | Observe request outcome; called with native img events |
+| `classNames` | keyed classes | unset | `root`, `image`, `fallback` |
+| `ref` | `Ref<HTMLSpanElement>` | unset | Frame element; remaining span props and style apply here |
+
+The frame exposes `data-state="empty|loading|loaded|error"`, `data-ratio`, and `data-fit`. The internal native image is hidden from assistive technology; the outer image role owns the alternative across all states. `aria-label`, `aria-labelledby`, and `aria-describedby` belong to the frame. An empty `alt` always hides the complete image.
+
+`auto` uses positive width and height; without both, it falls back to the landscape ratio. The image remains within the reserved frame, including after failure. A caller `style.aspectRatio` overrides framing. `Image` fetches follow native browser behavior; the component adds no timeout, retry loop, cache, upload or URL policy. A new source starts a fresh request; to retry the same URL intentionally, change the component key.
+
+Fallback content is visual-only and must contain no controls. Place a named replacement/retry `Button` and meaningful error text outside the frame. Use [media recipes](../../../../docs/guides/media-and-identity.md) for responsive sources, localized errors and CSS-only markup.
+
+## Related components
+
+Use [`Avatar`](Avatar.md) for fixed-size identity, [`Thumbnail`](Thumbnail.md) for captions and metadata, and [`Grid`](Grid.md) for responsive collections.

package/docs/components/Inline.md

@@ -0,0 +1,42 @@
+# Inline
+
+Use `Inline` for a row of content or controls that wraps when space runs out. Each control keeps its normal Tab stop; the row adds no toolbar role or keyboard handling. Native HTML props and the matching `ref` pass through.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/layout-inline--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Button, Inline } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <Inline>
+      <Button>Save changes</Button>
+      <Button variant="secondary">Cancel</Button>
+    </Inline>
+  );
+}
+```
+
+## More examples
+
+- [Wrapping actions](https://kbui.kcb.pro/storybook/?path=/story/layout-inline--wrapping): Inspect source order as controls wrap.
+- [A native list](https://kbui.kcb.pro/storybook/?path=/story/layout-inline--list): Retain list semantics inside a row.
+- [Mixed content](https://kbui.kcb.pro/storybook/?path=/story/layout-inline--alignment): Compare alignment with different content sizes.
+
+## Reference
+
+| Prop      | Values                                         | Default  |
+| --------- | ---------------------------------------------- | -------- |
+| `as`      | `div` `ul` `ol` `nav`                          | `div`    |
+| `gap`     | `none` `sm` (0.5rem) `md` (1rem) `lg` (1.5rem) | `md`     |
+| `align`   | `start` `center` `end` `baseline` `stretch`    | `center` |
+| `justify` | `start` `center` `end` `between`               | `start`  |
+
+Set `as` explicitly when using an element other than the default. Lists keep their markers and outer spacing; `gap` controls spacing between `<li>` children. Choose `Toolbar` when actions need arrow-key navigation. See [Layout composition](https://github.com/KhallilB/kbui/blob/main/docs/guides/layout.md).
+
+## Related components
+
+Use [`Toolbar`](Toolbar.md) when actions need coordinated arrow-key navigation. Use [`Stack`](Stack.md) for vertical flow and [`Grid`](Grid.md) when items need shared columns.

package/docs/components/Input.md

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

package/docs/components/Link.md

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

package/docs/components/Menu.md

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

package/docs/components/MultiSelect.md

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