@kb.ui/react 0.10.3 → 0.11.0

package/docs/components/Dialog.md

@@ -0,0 +1,84 @@
+# Dialog
+
+`Dialog` is composed from parts. Base UI handles focus trapping, closing on Escape and scroll locking.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-dialog--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Button, Dialog } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <Dialog>
+      <Dialog.Trigger render={<Button />}>View details</Dialog.Trigger>
+      <Dialog.Content
+        title="Project details"
+        description="Current project status."
+      >
+        <p>Three tasks remain.</p>
+        <Dialog.Actions>
+          <Dialog.Close render={<Button />}>Done</Dialog.Close>
+        </Dialog.Actions>
+      </Dialog.Content>
+    </Dialog>
+  );
+}
+```
+
+## More examples
+
+- [A confirmation task](https://kbui.kcb.pro/storybook/?path=/story/components-dialog--confirm): Open and close a modal from its trigger.
+- [Structured content](https://kbui.kcb.pro/storybook/?path=/story/components-dialog--sections): Inspect header, body, footer, and actions; opens a modal.
+- [A custom layout](https://kbui.kcb.pro/storybook/?path=/story/components-dialog--custom-layout): Inspect composed titles and descriptions; opens a modal.
+
+## Reference
+
+| Part                                            | Purpose                                                                                                                       |
+| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `Dialog`                                        | Root. Accepts `open`, `defaultOpen` and `onOpenChange` for controlled use.                                                    |
+| `Dialog.Trigger`                                | Opens the dialog. Use `render={<Button />}` to style it as a button.                                                          |
+| `Dialog.Content`                                | The dialog. `title` and `description` set its accessible name and description; `container` changes where it mounts.           |
+| `Content.layout` | `"center"` (default) or `"drawer"`; drawer slides from inline end, uses `--kb-dialog-width` and scrolls direct Body independently. |
+| `Dialog.Title`, `Dialog.Description`            | For custom layouts. Use these or the `Dialog.Content` props in a given dialog, not both, or it gets two titles.               |
+| `Dialog.Header`, `Dialog.Body`, `Dialog.Footer` | Optional structured sections; accept native `div` props and refs. Centered padding follows `--kb-dialog-{header,body,footer}-padding`; drawer sections use `--kb-dialog-padding`. |
+| `Dialog.Actions`                                | Aligns buttons along the bottom right.                                                                                        |
+| `Dialog.Close`                                  | Closes the dialog.                                                                                                            |
+
+| Prop on root or Content  | Type             | Default       | Notes                                                                         |
+| ------------------------ | ---------------- | ------------- | ----------------------------------------------------------------------------- |
+| `open` on Dialog         | `boolean`        | uncontrolled  | Current visibility when your app controls the dialog                          |
+| `defaultOpen` on Dialog  | `boolean`        | `false`       | Initial visibility; avoid starting open in a reading surface                  |
+| `onOpenChange` on Dialog | Base UI callback | unset         | Receives the next visibility and change details                               |
+| `title` on Content       | `ReactNode`      | unset         | Visible title and accessible name; use Dialog.Title for custom markup instead |
+| `description` on Content | `ReactNode`      | unset         | Supporting description; use Dialog.Description for custom markup instead      |
+| `container` on Content   | portal container | document body | Themed host for a nested dialog                                               |
+
+```tsx
+<Dialog>
+  <Dialog.Trigger render={<Button />}>Open</Dialog.Trigger>
+  <Dialog.Content title="Rename file">
+    <Input label="Name" />
+    <Dialog.Actions>
+      <Dialog.Close render={<Button variant="ghost" />}>Cancel</Dialog.Close>
+      <Button>Save</Button>
+    </Dialog.Actions>
+  </Dialog.Content>
+</Dialog>
+```
+
+## Related components
+
+Use [Menu](Menu.md) for a short action list and [Callout](Callout.md) for a message that belongs in the page.
+
+
+## Drawer and confirmation patterns
+
+The [overlay guide](../../../../docs/guides/forms-and-overlays.md#drawer-pattern) supplies complete drawer and asynchronous confirmation modules. Drawers use `Content layout="drawer"` with direct Header, Body and Footer sections. Header/actions remain visible while Body scrolls; the drawer follows logical direction and dynamic viewport height. Content title/description props automatically form a drawer Header. Focus a composed title initially for long content. Confirmations focus Cancel first, reject duplicate/pending dismissal, retain errors for retry and close only after success.
+
+- [Drawer](https://kbui.kcb.pro/storybook/?path=/story/components-dialog--drawer)
+- [Failure and retry](https://kbui.kcb.pro/storybook/?path=/story/components-dialog--confirmation-recovery)
+
+Use [Popover](Popover.md) for non-modal anchored controls and [Disclosure](Disclosure.md) for supporting details inline.

package/docs/components/Disclosure.md

@@ -0,0 +1,53 @@
+# Disclosure
+
+Reveal optional details or advanced controls inline. Base UI Collapsible owns the open state, trigger relationship and hidden panel behavior.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-disclosure--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Disclosure, Input } from "@kb.ui/react";
+
+export function AdvancedSettings() {
+  return (
+    <Disclosure>
+      <Disclosure.Trigger>Advanced settings</Disclosure.Trigger>
+      <Disclosure.Panel keepMounted>
+        <Input label="Reply-to address" defaultValue="team@example.com" />
+      </Disclosure.Panel>
+    </Disclosure>
+  );
+}
+```
+
+## More examples
+
+- [Retained draft](https://kbui.kcb.pro/storybook/?path=/story/components-disclosure--retained-draft): preserve an uncontrolled field through collapse.
+- [Controlled](https://kbui.kcb.pro/storybook/?path=/story/components-disclosure--controlled): caller-owned open state.
+- [Disabled](https://kbui.kcb.pro/storybook/?path=/story/components-disclosure--disabled): unavailable details.
+
+## Reference
+
+| Part / prop | Type | Default | Purpose |
+|---|---|---|---|
+| `Disclosure` | Base UI Collapsible root props | `div` | Groups trigger and panel; accepts native props and ref. |
+| `open` / `defaultOpen` | `boolean` | `false` | Controlled or initial expansion. |
+| `onOpenChange` | `(open, details) => void` | — | Requests a state change; `details.cancel()` rejects it. |
+| `disabled` | `boolean` | `false` | Prevents user toggling. |
+| `Disclosure.Trigger` | Base UI Collapsible trigger props | `button` | Native Enter/Space activation and expanded/controls relationships. |
+| `Disclosure.Panel` | Base UI Collapsible panel props | `div` | Contains optional details and controls. |
+| `Panel.keepMounted` | `boolean` | `false` | Retains DOM and uncontrolled draft state while closed. |
+| `Panel.hiddenUntilFound` | `boolean` | `false` | Uses browser find-in-page reveal where supported; overrides keepMounted. |
+| `className` / `render` / `ref` | Part-specific native props | — | Style, compose and reference each DOM part. Class names accept strings. |
+
+Tab reaches the trigger; Enter and Space toggle it without moving focus into the panel. Collapsed controls leave the accessibility tree and Tab order. No arrow-key navigation or modal behavior is added. Put essential instructions and errors where they remain discoverable. Unmounted content loses uncontrolled state; use keepMounted or store values outside the panel. Browser find-in-page reveal depends on engine support and the caller accepting controlled state changes.
+
+Style `--kb-disclosure-padding`, `-radius`, `-background`, `-color`, `-border` and `-trigger-height`. Preserve visible focus, hidden semantics and disabled state when overriding styles.
+
+Panels expand and collapse through measured height transitions; reversing mid-transition follows the latest toggle. Content grows naturally once expanded. `--kb-disclosure-motion-duration` and `-motion-easing` control panel and caret motion; reduced motion disables transitions. `.kb-disclosure-panel-content` owns inner padding, keeping the outer Panel measurable without clipping collapsed padding. Panel props, className, render and ref still target the outer node.
+
+## Related components
+
+Use [Accordion](Accordion.md) for related sections with headings, [Panel](Panel.md) for a structured work surface, or [Popover](Popover.md) for anchored supporting controls. [Overlay guidance](../../../../docs/guides/forms-and-overlays.md) covers choosing disclosure, popovers and modal patterns.

package/docs/components/EmptyState.md

@@ -0,0 +1,50 @@
+# EmptyState
+
+Explain why a collection, search result, or section has no content to show, and provide the direct action that populates or recovers 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-emptystate--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Button, EmptyState } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <EmptyState
+      eyebrow="Pipelines"
+      title="No release pipelines configured"
+      description="Create a pipeline to validate builds and publish signed packages."
+      actions={<Button size="sm">Create pipeline</Button>}
+    />
+  );
+}
+```
+
+## More examples
+
+- [Filtered zero results](https://kbui.kcb.pro/storybook/?path=/story/components-emptystate--filtered-zero-results): Give people a one-click way to clear active filters or widen their query.
+- [Recoverable section failure](https://kbui.kcb.pro/storybook/?path=/story/components-emptystate--recoverable-failure): Explain when a section failed to load and pair the explanation with a retry action.
+- [Surface variants](https://kbui.kcb.pro/storybook/?path=/story/components-emptystate--variants-and-sizes): Choose `surface`, `subtle`, or `plain` containers to match surrounding hierarchy.
+
+## Reference
+
+| Prop           | Type                                         | Default   | Notes                                                                                  |
+| -------------- | -------------------------------------------- | --------- | -------------------------------------------------------------------------------------- |
+| `title`        | `ReactNode`                                  | required  | Heading text naming what is missing or unavailable                                     |
+| `description`  | `ReactNode`                                  | unset     | Supporting guidance explaining how to populate or recover the view                     |
+| `eyebrow`      | `ReactNode`                                  | unset     | Short uppercase label above the title                                                  |
+| `icon`         | `ReactNode`                                  | unset     | Decorative emblem above the header; hidden from assistive technology                   |
+| `actions`      | `ReactNode`                                  | unset     | Primary and secondary buttons or links that resolve the empty state                    |
+| `footer`       | `ReactNode`                                  | unset     | Quiet footnote, error code, or secondary hint below actions                            |
+| `headingLevel` | `2` / `3` / `4`                              | `3`       | Semantic heading tag (`h2`–`h4`) matching the surrounding document outline             |
+| `variant`      | `surface` / `subtle` / `plain`               | `surface` | Raised bordered card, dashed recessed well, or borderless inline block                 |
+| `size`         | `sm` / `md` / `lg`                           | `md`      | Scales padding, icon badge, and heading typography                                     |
+| `tone`         | `neutral` / `info` / `warning` / `danger`    | `neutral` | Accentuates the icon badge and border for informational or failure states              |
+| `live`         | `boolean`                                    | `false`   | Adds `role="status"` when revealed dynamically after filtering or an async load error  |
+| `classNames`   | keyed classes                                | unset     | Style `icon`, `header`, `eyebrow`, `title`, `description`, `body`, `actions`, `footer` |
+
+## Related components
+
+Use [Skeleton](Skeleton.md) while the collection is still loading, [Callout](Callout.md) for inline notices beside populated content, and [Toast](Toast.md) for transient action feedback.

package/docs/components/ErrorSummary.md

@@ -0,0 +1,46 @@
+# ErrorSummary
+
+Place ErrorSummary at the top of a form when submission fails so people can see what went wrong and jump directly to each invalid field. When `items` is empty, nothing is rendered.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-errorsummary--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { ErrorSummary, Input } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <form noValidate>
+      <ErrorSummary
+        items={[{ href: "#email", label: "Enter an email address." }]}
+      />
+      <Input id="email" label="Email" error="Enter an email address." />
+    </form>
+  );
+}
+```
+
+This example shows a failed-submission state. The Form recovery story below demonstrates validation and moving focus to the summary after submission.
+
+## More examples
+
+- [Recover after submission](https://kbui.kcb.pro/storybook/?path=/story/components-errorsummary--form-recovery): Run validation, focus the summary, and jump to invalid fields.
+
+## Reference
+
+| Prop           | Type                                                                 | Default                | Notes                                                            |
+| -------------- | -------------------------------------------------------------------- | ---------------------- | ---------------------------------------------------------------- |
+| `items`        | `readonly ErrorSummaryItem[]`                                        | required               | Ordered `{ id?, href, label }` entries linking to invalid fields |
+| `title`        | `ReactNode`                                                          | `"There is a problem"` | Heading text naming the alert region                             |
+| `description`  | `ReactNode`                                                          | unset                  | Optional recovery guidance above the error list                  |
+| `headingLevel` | `2 \| 3 \| 4`                                                        | `2`                    | Heading rank for the summary title                               |
+| `onItemSelect` | `(href: string, event: MouseEvent<HTMLAnchorElement>) => void`       | unset                  | Called when a recovery link is clicked                           |
+| `classNames`   | `ClassNames<"title" \| "description" \| "list" \| "item" \| "link">` | unset                  | Classes for inner parts                                          |
+
+ErrorSummary renders an alert region with `tabIndex={-1}` so your submit handler can focus it when validation fails. Clicking an `#id` link focuses the matching control or the first enabled control inside a referenced group. Pair ErrorSummary with inline `error` props on each invalid field.
+
+## Related components
+
+Keep inline errors on [Input](Input.md), [Textarea](Textarea.md), and other fields. Use [FormActions](FormActions.md) for the submit controls.

package/docs/components/Fieldset.md

@@ -0,0 +1,42 @@
+# Fieldset
+
+Use Fieldset to group related controls into a named form section using native `fieldset` and `legend` semantics. Setting `disabled` disables descendant form controls natively.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-fieldset--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Fieldset, Input } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <Fieldset legend="Contact details" description="How we can reach you.">
+      <Input label="Email" type="email" name="email" />
+    </Fieldset>
+  );
+}
+```
+
+## More examples
+
+- [A group-level error](https://kbui.kcb.pro/storybook/?path=/story/components-fieldset--with-error): Explain a correction for a named group.
+- [An unavailable group](https://kbui.kcb.pro/storybook/?path=/story/components-fieldset--disabled): Inspect disabled descendant controls.
+
+## Reference
+
+| Prop             | Type                                                           | Default  | Notes                                                  |
+| ---------------- | -------------------------------------------------------------- | -------- | ------------------------------------------------------ |
+| `legend`         | `ReactNode`                                                    | required | Section heading rendered inside the native legend      |
+| `visuallyHidden` | `boolean`                                                      | `false`  | Hides the legend visually while keeping the group name |
+| `description`    | `ReactNode`                                                    | unset    | Section help text linked through aria-describedby      |
+| `error`          | `ReactNode`                                                    | unset    | Group-level error linked through aria-describedby      |
+| `disabled`       | `boolean`                                                      | `false`  | Disables all descendant controls in the fieldset       |
+| `classNames`     | `ClassNames<"legend" \| "description" \| "fields" \| "error">` | unset    | Classes for inner parts                                |
+
+Other native fieldset props and `ref` pass through to the `<fieldset>` element. Use `--kb-fieldset-gap`, `--kb-fieldset-fields-gap`, and `--kb-fieldset-legend-size` to tune spacing and legend typography.
+
+## Related components
+
+Use [Textarea](Textarea.md) and [Input](Input.md) for answers, [ErrorSummary](ErrorSummary.md) for submission recovery, and [FormActions](FormActions.md) for the action row.

package/docs/components/FileInput.md

@@ -0,0 +1,74 @@
+# FileInput
+
+Use FileInput to choose files, review the selected list, and remove items. Your app decides which files to accept, keeps the File objects, and handles uploads. See [Retained file selection](https://github.com/KhallilB/kbui/blob/main/docs/guides/file-inputs.md) for examples, keyboard behavior, and styling. Available since v0.6.0.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-fileinput--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { FileInput, type FileInputItem } from "@kb.ui/react";
+import { useState } from "react";
+
+type Attachment = FileInputItem & { file: File };
+
+export function Example() {
+  const [items, setItems] = useState<Attachment[]>([]);
+  return (
+    <FileInput
+      label="Attachments"
+      items={items}
+      onFiles={(files) =>
+        setItems((current) => [
+          ...current,
+          ...files.map((file) => ({
+            id: crypto.randomUUID(),
+            name: file.name,
+            file,
+          })),
+        ])
+      }
+      onRemove={(id) =>
+        setItems((current) => current.filter((item) => item.id !== id))
+      }
+    />
+  );
+}
+```
+
+The example retains each original `File` alongside its display metadata. Your app chooses acceptance rules and builds `FormData` for uploads; see [retained file selection](https://github.com/KhallilB/kbui/blob/main/docs/guides/file-inputs.md#choosing-and-removing-files).
+
+## More examples
+
+- [Rejected selection feedback](https://kbui.kcb.pro/storybook/?path=/story/components-fileinput--rejected): Keep accepted items visible while explaining a rejection.
+- [Image-picker hints](https://kbui.kcb.pro/storybook/?path=/story/components-fileinput--evidence): Compare image acceptance hints and helper text.
+- [Item metadata](https://kbui.kcb.pro/storybook/?path=/story/components-fileinput--custom-content): Customize retained-file content without losing its identity.
+
+## Reference
+
+| Prop                                                 | Type                                 | Default                 | Notes                                                                |
+| ---------------------------------------------------- | ------------------------------------ | ----------------------- | -------------------------------------------------------------------- |
+| `label`                                              | `string`                             | required                | Visible field name and accessible picker context                     |
+| `items`                                              | `readonly FileInputItem[]`           | required                | Retained files with stable ids, names, and optional descriptions     |
+| `onFiles`                                            | `(files: File[]) => void`            | required                | Check the selection and update retained files in your app            |
+| `onRemove`                                           | `(id: string) => void`               | required                | Request removal; update items to confirm it                          |
+| `accept`                                             | `string`                             | unset                   | Native picker hint, such as image/*; does not validate files         |
+| `multiple`                                           | `boolean`                            | `true`                  | Allow multiple selection; use a singular chooseLabel for single mode |
+| `disabled`, `readOnly`                               | `boolean`                            | `false`                 | Prevent edits while keeping the retained list visible                |
+| `description`, `error`                               | `string`                             | unset                   | Help or actionable rejection text associated with the field          |
+| `visuallyHidden`                                     | `boolean`                            | `false`                 | Hide the visual label while preserving its accessible name           |
+| `chooseLabel`                                        | `string`                             | Choose files            | Localized visible picker action                                      |
+| `emptyMessage`                                       | `string`                             | No files added.         | Localized empty-state text                                           |
+| `removeLabel`                                        | `(item: FileInputItem) => string`    | Remove + filename       | Accessible remove action; keep the filename in the name              |
+| `removedMessage`                                     | `(item: FileInputItem) => string`    | filename + removed.     | Announcement after removal is confirmed                              |
+| `selectionMessage`                                   | `(count: number) => string`          | count + files selected. | Announcement after native selection                                  |
+| `renderItem`                                         | `(item: FileInputItem) => ReactNode` | name + description      | Custom item content; keep visible file identity                      |
+| `inputRef`, `triggerRef`                             | element refs                         | unset                   | Hidden native input and visible picker access                        |
+| `triggerClassName`, `listClassName`, `itemClassName` | `string`                             | unset                   | Classes for picker, retained list, and items                         |
+
+Root native div props/ref and className pass through. Root aria-describedby merges after helper/error. Item button refs remain internal to preserve focus; use public item/content classes and renderItem for presentation. Use these props and classes rather than reaching into individual item buttons. The `×` mark is decorative; removal has a full accessible filename label.
+
+## Related components
+
+Use [Progress](Progress.md) to present caller-owned upload progress. File selection and uploading are separate steps.

package/docs/components/FormActions.md

@@ -0,0 +1,45 @@
+# FormActions
+
+Use FormActions at the bottom of a form or section to align submit, reset, and secondary buttons with consistent wrapping and spacing. Buttons stay in natural Tab order without toolbar arrow-key navigation.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-formactions--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Button, FormActions, Input } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <form onSubmit={(event) => event.preventDefault()}>
+      <Input label="Project name" name="project" />
+      <FormActions divider>
+        <Button type="submit">Save changes</Button>
+        <Button type="reset" variant="ghost">
+          Reset
+        </Button>
+      </FormActions>
+    </form>
+  );
+}
+```
+
+## More examples
+
+- [Separate the action row](https://kbui.kcb.pro/storybook/?path=/story/components-formactions--with-divider): Keep a boundary above the actions.
+- [Primary and secondary groups](https://kbui.kcb.pro/storybook/?path=/story/components-formactions--split-alignment): Compare actions at opposite ends of the row.
+
+## Reference
+
+| Prop       | Type                            | Default | Notes                                              |
+| ---------- | ------------------------------- | ------- | -------------------------------------------------- |
+| `align`    | `"end" \| "start" \| "between"` | `"end"` | Horizontal button alignment                        |
+| `divider`  | `boolean`                       | `false` | Adds a top border and spacing above the action row |
+| `children` | `ReactNode`                     | unset   | Form buttons in reading and Tab order              |
+
+Other native div props and `ref` pass through. Use `--kb-formactions-gap` and `--kb-formactions-padding-top` to adjust spacing.
+
+## Related components
+
+Use [Fieldset](Fieldset.md) for named groups and [ErrorSummary](ErrorSummary.md) for failed submission recovery. Use [Toolbar](Toolbar.md) when controls need arrow-key navigation.

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 on narrow mobile viewports) 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 and [Inline](Inline.md) for a wrapping row of independent items.

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
+
+Wrapping row for independent content or controls. Adds no toolbar role or keyboard handling; controls retain native tab order. Native props and 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`  |
+
+Non-default generic native elements require an explicit `as`. Lists retain markers and native list spacing. Use li children. Choose Toolbar when actions require its coordinated arrow-key model. 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 [Grid](Grid.md) when items need shared columns.