@kb.ui/react 0.10.4 → 0.12.0

package/dist/utils/CollapsiblePanel.d.ts

@@ -0,0 +1,10 @@
+import { useRender } from "@base-ui/react/use-render";
+type CollapsiblePanelProps<State> = {
+    nativeProps: useRender.ElementProps<"div">;
+    state: State;
+    render?: useRender.RenderProp<State> | undefined;
+};
+export declare function CollapsiblePanel<State extends {
+    open: boolean;
+}>({ nativeProps, state, render, }: CollapsiblePanelProps<State>): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export {};

package/dist/utils/useClipboard.d.ts

@@ -0,0 +1,28 @@
+export type CopyState = "idle" | "pending" | "copied" | "failed";
+export type CopyFeedbackProps = {
+    /** Disable copying while keeping content selectable. */
+    disabled?: boolean | undefined;
+    /** Idle copy button text and accessible name. */
+    copyLabel?: string | undefined;
+    /** Pending copy button text. */
+    copyingLabel?: string | undefined;
+    /** Successful copy button text. */
+    copiedLabel?: string | undefined;
+    /** Failed copy button text; activation retries. */
+    copyErrorLabel?: string | undefined;
+    /** Polite success announcement. */
+    successMessage?: string | undefined;
+    /** Visible, polite failure message with recovery instructions. */
+    errorMessage?: string | undefined;
+    /** Success feedback lifetime in milliseconds; zero keeps feedback until next action. */
+    feedbackDuration?: number | undefined;
+    /** Called after clipboard write succeeds for current content. */
+    onCopy?: ((value: string) => void) | undefined;
+    /** Called when current clipboard write fails, including unavailable Clipboard API. */
+    onCopyError?: ((error: unknown) => void) | undefined;
+};
+export declare function useClipboard(value: string, { disabled, feedbackDuration, onCopy, onCopyError }: CopyFeedbackProps): {
+    state: CopyState;
+    copy: () => Promise<void>;
+    disabled: boolean;
+};

package/docs/components/Accordion.md

@@ -0,0 +1,66 @@
+# Accordion
+
+Group related disclosures under headings. Single expansion is the default; enable `multiple` when several answers or sections should remain visible together.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-accordion--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Accordion } from "@kb.ui/react";
+
+export function DeliveryQuestions() {
+  return (
+    <Accordion multiple defaultValue={["delivery"]}>
+      <Accordion.Item value="delivery">
+        <Accordion.Header render={<h2 />}>
+          <Accordion.Trigger>When will my order arrive?</Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Panel>Orders dispatch within two working days.</Accordion.Panel>
+      </Accordion.Item>
+      <Accordion.Item value="returns">
+        <Accordion.Header render={<h2 />}>
+          <Accordion.Trigger>Can I return an item?</Accordion.Trigger>
+        </Accordion.Header>
+        <Accordion.Panel>Contact support with your order number.</Accordion.Panel>
+      </Accordion.Item>
+    </Accordion>
+  );
+}
+```
+
+## More examples
+
+- [Multiple](https://kbui.kcb.pro/storybook/?path=/story/components-accordion--multiple): independent expanded sections.
+- [Controlled](https://kbui.kcb.pro/storybook/?path=/story/components-accordion--controlled): application-owned values.
+- [Nested](https://kbui.kcb.pro/storybook/?path=/story/components-accordion--nested): independent groups with contextual heading ranks.
+- [Disabled](https://kbui.kcb.pro/storybook/?path=/story/components-accordion--disabled): unavailable controls with readable expanded details.
+
+## Reference
+
+| Part / prop | Type | Default | Purpose |
+|---|---|---|---|
+| `Accordion<Value>` | Base UI `Accordion` root props | `div` | Groups items; generic values preserve callback types. |
+| `value` / `defaultValue` | `Value[]` | `[]` | Controlled or initial expanded item values. Use arrays in both modes. |
+| `onValueChange` | `(values, details) => void` | — | Requests expansion changes; `details.cancel()` rejects them. |
+| `multiple` | `boolean` | `false` | Allows independent expanded items. |
+| `disabled` | `boolean` | `false` | Disables all triggers; does not conceal already open content. |
+| `keepMounted` / `hiddenUntilFound` | `boolean` | `false` | Root defaults for panel retention or supported browser search reveal. |
+| `Accordion.Item` | Base UI `Accordion` item props | `div` | Requires a stable unique `value` for controlled usage; accepts item `disabled`. |
+| `Accordion.Header` | Base UI `Accordion` heading props | `h3` | Contains the trigger; use `render={<h2 />}` or another heading for document hierarchy. |
+| `Accordion.Trigger` | Base UI `Accordion` trigger props | `button` | Visible section label and expansion control. |
+| `Accordion.Panel` | Base UI `Accordion` panel props | Named `region` | Owns content; accepts per-panel retention options. |
+| `className` / `render` / `ref` | Part-specific native props | — | Customize each part; class names accept strings. |
+
+Tab and Shift+Tab visit enabled triggers and expanded controls in DOM order. Enter/Space toggle the focused item. Base UI 1.9 uses normal Tab navigation; its deprecated orientation and `loopFocus` props do not add arrow-key navigation. Closing the last open item is allowed. No business validation is inferred from expansion.
+
+Keep essential information discoverable and interactive actions outside the heading button. Avoid an excessive number of region landmarks: keep groups focused and split large documents into meaningful sections. Hidden/unmounted content does not supply persistent form state: use `keepMounted` or caller-owned values. Nested groups own separate state.
+
+Style `--kb-accordion-padding`, `-radius`, `-background`, `-color`, `-border` and `-trigger-height`; classes cover root, item, header, trigger and panel. Preserve expanded/disabled attributes and native focus outlines when composing custom renderers.
+
+Panels expand and collapse through measured height transitions; reversing mid-transition follows the latest toggle. Content grows naturally once expanded. `--kb-accordion-motion-duration` and `-motion-easing` control panel and caret motion; reduced motion disables transitions. `.kb-accordion-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 [`Disclosure`](Disclosure.md) for a single optional section or [`Panel`](Panel.md) for a structured work surface. Use [`Popover`](Popover.md) for controls anchored outside normal document flow.

package/docs/components/Avatar.md

@@ -0,0 +1,80 @@
+# Avatar
+
+Keep people and organizations recognizable through photo loading, missing images and request failures. Fallback initials share the same fixed frame as the image.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-avatar--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Avatar, Inline, Link, Text } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <Inline align="center" gap="md">
+      <Avatar name="Maya Chen" src="/people/maya.jpg" decorative />
+      <div>
+        <Link href="/people/maya">Maya Chen</Link>
+        <Text size="sm" tone="muted">Design director</Text>
+      </div>
+    </Inline>
+  );
+}
+```
+
+## More examples
+
+- [Shapes](https://kbui.kcb.pro/storybook/?path=/story/components-avatar--shapes): Circular, square, rounded, hexagonal and diamond silhouettes with photos and initials.
+- [Sizes](https://kbui.kcb.pro/storybook/?path=/story/components-avatar--sizes): Five fixed dimensions.
+- [Fallbacks](https://kbui.kcb.pro/storybook/?path=/story/components-avatar--fallbacks): Missing/broken photos, multilingual names and organization initials.
+- [People](https://kbui.kcb.pro/storybook/?path=/story/components-avatar--people): Visible identity, profile link and role.
+
+## Shapes
+
+`AvatarShape` accepts `circle`, `square`, `rounded`, `hexagon` and `diamond`. `square` has zero corner radius; `rounded` uses softly rounded corners.
+
+Shape changes only the silhouette. Photos and initials remain upright, and the accessible identity, size and image request state stay unchanged. Hexagon and diamond clip the media frame to their polygon; they do not rotate the content.
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Avatar, type AvatarShape, Inline } from "@kb.ui/react";
+
+const organizationShape: AvatarShape = "hexagon";
+
+export function ShapedIdentity() {
+  return (
+    <Inline gap="lg" align="center">
+      <Avatar name="Maya Chen" shape="circle" />
+      <Avatar name="North Studio" initials="N" shape="square" />
+      <Avatar name="Design team" initials="D" shape="rounded" style={{ borderRadius: "var(--kb-radius-sm)" }} />
+      <Avatar name="Field team" initials="F" shape={organizationShape} />
+      <Avatar name="Studio collection" initials="S" shape="diamond" />
+    </Inline>
+  );
+}
+```
+
+The default circle uses `--kb-avatar-radius`; rounded uses the existing `--kb-avatar-square-radius` token. A root `style.borderRadius` overrides the circle, square or rounded frame and is inherited by its media. Polygon clipping remains in effect for hexagon and diamond. Choose short initials that remain legible inside the silhouette, especially at smaller sizes.
+
+## Reference
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `name` | `string` | required | Full accessible identity; blank names use `Unknown person` |
+| `src`, `srcSet`, `sizes`, `loading` | native image attributes | unset | Photo request and responsive selection |
+| `initials` | `string` | first and last name initials | Override for local naming conventions, handles or brand marks |
+| `decorative` | `boolean` | `false` | Hide duplicate identity when adjacent text supplies it |
+| `size` | `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` | `"md"` | Defaults: 24, 32, 44, 56 and 80 CSS pixels |
+| `shape` | `AvatarShape` | `"circle"` | `circle`, `square`, `rounded`, `hexagon` or `diamond`; clips upright media |
+| `onLoad`, `onError` | native image handlers | unset | Photo result callbacks |
+| `classNames` | keyed classes | unset | `root`, `media`, `initials` |
+| `ref` | `Ref<HTMLSpanElement>` | unset | Root element; native `span` props pass through |
+
+Initials use the first Unicode code point of the first and last whitespace-separated names, uppercased; a single word contributes one initial. This is a convenience, not a universal naming rule. Supply `initials` for the person's preferred form. Empty identities render `?`; localize `Unknown person` through `aria-label`. The accessible name remains the full identity, not the initials.
+
+`Avatar` adds no focus stop. Place navigation in a named `Link` or an action in a `Button`. Use `decorative` when an equivalent visible name is adjacent or the parent control already supplies the identity. Keep presence and account state in separately labeled `Status`/`Badge` content. See [media recipes](../../../../docs/guides/media-and-identity.md).
+
+## Related components
+
+Use [`Image`](Image.md) for flexible media framing, [`Thumbnail`](Thumbnail.md) for captioned previews, and [`Status`](Status.md) for changing state.

package/docs/components/Badge.md

@@ -0,0 +1,37 @@
+# Badge
+
+Add a short label to a person, record, or resource. Keep the text meaningful without its color. Use `Status` when the information changes over time.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-badge--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Badge } from "@kb.ui/react";
+
+export function Example() {
+  return <Badge>New</Badge>;
+}
+```
+
+## More examples
+
+- [Literal identifiers](https://kbui.kcb.pro/storybook/?path=/story/components-badge--mono): Show an identifier in a monospace font.
+- [Semantic tones](https://kbui.kcb.pro/storybook/?path=/story/components-badge--tones): Check text remains meaningful across tones.
+
+## Reference
+
+| Prop           | Type                                                  | Default   | Notes                                                                       |
+| -------------- | ----------------------------------------------------- | --------- | --------------------------------------------------------------------------- |
+| `children`     | `ReactNode`                                           | unset     | Short metadata such as Reviewer, Draft, or a branch name                    |
+| `tone`         | `neutral` / `info` / `success` / `warning` / `danger` | `neutral` | Reinforces the text with ink and tint                                       |
+| `appearance`   | `chip` / `plain`                                      | `chip`    | Chip adds a tinted surface; plain stays inline                              |
+| `mono`         | `boolean`                                             | `false`   | Small uppercase monospace for short identifiers                             |
+| `preserveCase` | `boolean`                                             | `false`   | Preserve case and spacing for branch names, paths, and other literal values |
+
+You can pass native `<span>` props. `Badge` adds no Tab stop or live announcement.
+
+## Related components
+
+Use [`Status`](Status.md) for changing state and [`Code`](Code.md) for code within prose.

package/docs/components/Button.md

@@ -0,0 +1,46 @@
+# Button
+
+Use a `Button` for an action such as saving a form or opening a dialog. Choose a variant to match the action’s importance.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-button--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Button } from "@kb.ui/react";
+
+export function Example() {
+  return <Button type="submit">Save changes</Button>;
+}
+```
+
+## More examples
+
+- [Styled navigation](https://kbui.kcb.pro/storybook/?path=/story/components-button--as-link): Render a link with the correct semantics.
+- [Icon-only actions](https://kbui.kcb.pro/storybook/?path=/story/components-button--icon-only): Give the action an accessible name.
+- [Size choices](https://kbui.kcb.pro/storybook/?path=/story/components-button--sizes): Compare button sizes.
+
+## Reference
+
+| Prop        | Type                                              | Default     | Notes                                                                      |
+| ----------- | ------------------------------------------------- | ----------- | -------------------------------------------------------------------------- |
+| `children`  | `ReactNode`                                       | unset       | Visible action label, or an icon paired with `aria-label`                    |
+| `variant`   | `"primary" \| "secondary" \| "ghost" \| "danger"` | `"primary"` | Main, supporting, quiet, or destructive action emphasis                    |
+| `size`      | `sm` / `md` / `lg` / `icon`                       | `md`        | Height and padding; `icon` is square and requires `aria-label`                 |
+| `type`      | native `button` type                                | `button`    | Set `type="submit"` for form submission; use `type="button"` for other form actions          |
+| `disabled`  | `boolean`                                         | `false`     | Blocks interaction; explain unavailable actions in nearby text when needed |
+| `render`    | element                                           | unset       | Use an anchor with `nativeButton={false}` and `role="link"` for navigation         |
+| `className` | `string`                                          | unset       | Extra classes on the rendered control; function values are not supported   |
+
+All props accepted by a native `button` or Base UI's `Button` also work. To render a link, pass an anchor and tell Base UI it is not a native `button`:
+
+```tsx
+<Button render={<a href="/docs" />} nativeButton={false} role="link">
+  Docs
+</Button>
+```
+
+## Related components
+
+Use [`Link`](Link.md) for navigation. Group coordinated actions with [`Toolbar`](Toolbar.md), or independent wrapping actions with [`Inline`](Inline.md).

package/docs/components/Callout.md

@@ -0,0 +1,41 @@
+# Callout
+
+Keep a useful message close to the content it explains. Give people a concrete next step when they can resolve the issue.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-callout--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Callout } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <Callout title="Changes saved" tone="success">
+      You can close this page.
+    </Callout>
+  );
+}
+```
+
+## More examples
+
+- [Resolvable messages](https://kbui.kcb.pro/storybook/?path=/story/components-callout--with-actions): Place a next step beside its explanation.
+- [Message tones](https://kbui.kcb.pro/storybook/?path=/story/components-callout--tones): Compare how tone reinforces written meaning.
+
+## Reference
+
+| Prop         | Type                                                  | Default   | Notes                                                           |
+| ------------ | ----------------------------------------------------- | --------- | --------------------------------------------------------------- |
+| `children`   | `ReactNode`                                           | unset     | Message body; explain what happened and what to do next         |
+| `title`      | `ReactNode`                                           | unset     | Short summary above the message                                 |
+| `tone`       | `neutral` / `info` / `success` / `warning` / `danger` | `neutral` | Reinforces the message without replacing its wording            |
+| `icon`       | `ReactNode`                                           | unset     | Decorative icon; hidden from assistive technology               |
+| `actions`    | `ReactNode`                                           | unset     | Named buttons or links that help resolve the message; end-aligned, primary last |
+| `live`       | `boolean`                                             | `false`   | Adds `role=status` for changing message text; does not move focus |
+| `classNames` | keyed classes                                         | unset     | Style icon, content, title, body, or actions                    |
+
+## Related components
+
+Use [`Status`](Status.md) for a short changing state and [`Dialog`](Dialog.md) for a focused modal task.

package/docs/components/Card.md

@@ -0,0 +1,41 @@
+# Card
+
+Group related content with an optional title, summary, links, and actions. `Card` renders an article by default and adds no interaction of its own.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-card--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Card } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <Card>
+      <h2>Project summary</h2>
+      <p>Three tasks remain.</p>
+    </Card>
+  );
+}
+```
+
+## More examples
+
+- [A navigable card](https://kbui.kcb.pro/storybook/?path=/story/components-card--single-link): Use a real link for the primary destination.
+- [Quiet content rows](https://kbui.kcb.pro/storybook/?path=/story/components-card--plain): Show a flat card without a raised surface.
+
+## Reference
+
+| Prop                        | Type                     | Default    | Notes                                                                 |
+| --------------------------- | ------------------------ | ---------- | --------------------------------------------------------------------- |
+| `as`                        | `article` / `div` / `li` | `article`  | Choose the container for the document structure; use li inside a list |
+| `appearance`                | `outlined` / `plain`     | `outlined` | Outlined adds a raised surface; plain stays flat with a dividing line |
+| `children`                  | `ReactNode`              | unset      | Related content; your app provides headings, links, and actions       |
+| `className`, `style`, `ref` | native element props     | unset      | Style and reference the chosen container                              |
+
+`Card` adds no link, button, keyboard handler, or tab stop. If a link covers the whole card, keep other controls outside that link and style its focus state. Restyle with the card background, face, shadow, color, border, radius, and padding tokens; they share the theme's tactile materials.
+
+## Related components
+
+Arrange a collection with [`Grid`](Grid.md). Use [`Panel`](Panel.md) when a section needs structured header, body, and footer parts.

package/docs/components/Checkbox.md

@@ -0,0 +1,60 @@
+# Checkbox
+
+Use `Checkbox` when people can select options independently. It includes a label, help text, and error message. Pass `checked` and update it in `onCheckedChange`. Activating a mixed checkbox requests the checked state.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-checkbox--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Checkbox } from "@kb.ui/react";
+import { useState } from "react";
+
+export function Example() {
+  const [checked, setChecked] = useState(false);
+  return (
+    <Checkbox
+      label="Include archived projects"
+      checked={checked}
+      onCheckedChange={setChecked}
+    />
+  );
+}
+```
+
+## More examples
+
+- [Partial selection](https://kbui.kcb.pro/storybook/?path=/story/components-checkbox--mixed): Show a partly selected group.
+- [Validation feedback](https://kbui.kcb.pro/storybook/?path=/story/components-checkbox--invalid): Show an error for the choice.
+
+## Reference
+
+| Prop                          | Type                         | Default  | Notes                                                   |
+| ----------------------------- | ---------------------------- | -------- | ------------------------------------------------------- |
+| `label`                       | `string`                     | required | Visible accessible label                                |
+| `checked`                     | `boolean`                    | required | Controlled native checked state                         |
+| `onCheckedChange`             | `(checked: boolean) => void` | required | Next checked-state request                              |
+| `indeterminate`               | `boolean`                    | `false`  | Announces mixed state; activation requests checked      |
+| `disabled` / `readOnly`       | `boolean`                    | `false`  | Block changes; disabled also leaves keyboard order      |
+| `description` / `error`       | `string`                     |          | Associated helper and invalid-state text                |
+| `visuallyHidden`              | `boolean`                    | `false`  | Hide label visually                                     |
+| `controlClassName`            | `string`                     |          | Added to the native checkbox                            |
+| `ref`                         | `Ref<HTMLInputElement>`      |          | Native checkbox, including form and indeterminate state |
+| `name` / `value` / `required` | native `input` props           |          | Form serialization and validation                       |
+| `className`                   | `string`                     |          | Root class                                              |
+
+```tsx
+<Checkbox
+  label="Receive release updates"
+  name="updates"
+  checked={updates}
+  onCheckedChange={setUpdates}
+/>
+```
+
+Clicking the label or pressing Space calls `onCheckedChange`. The checkbox changes only when your app updates `checked`; otherwise its checked or mixed state stays as it was. Native input props are supported. `style` applies to the input, and CSS custom properties also reach the visible mark. Use `--kb-checkbox-size` to change its size. In forced colors, the native checkbox and its focus outline remain visible.
+
+## Related components
+
+Use [`RadioGroup`](RadioGroup.md) for one visible choice and [`Switch`](Switch.md) for an immediate on/off setting.

package/docs/components/Code.md

@@ -0,0 +1,77 @@
+# Code
+
+Literal inline code in native `code`, or syntax-highlighted multiline code blocks with a header, copy action, line numbers, line emphasis, and collapsible viewport.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Examples](#more-examples) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-code--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { Code } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <p>
+      Run <Code>bun run build</Code> before publishing.
+    </p>
+  );
+}
+```
+
+## More examples
+
+- [Multiline blocks](https://kbui.kcb.pro/storybook/?path=/story/components-code--multiline): Present source with a language label and copy action.
+- [Line numbers and emphasis](https://kbui.kcb.pro/storybook/?path=/story/components-code--line-numbers-and-highlights): Highlight the relevant part of a listing.
+- [Collapsible listings](https://kbui.kcb.pro/storybook/?path=/story/components-code--collapsible): Keep a long example within a bounded viewport.
+- [Code within prose](https://kbui.kcb.pro/storybook/?path=/story/components-code--in-text): Keep code legible inside a sentence.
+- [Long paths and commands](https://kbui.kcb.pro/storybook/?path=/story/components-code--long-token): Check wrapping with an unbroken token.
+
+## Reference
+
+| Prop                             | Type                           | Default                | Notes                                                                                                                                                    |
+| -------------------------------- | ------------------------------ | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `children`                       | `ReactNode`                    | unset                  | Pass source code as a string; multiline strings auto-switch to block mode                                                                                |
+| `block`                          | `boolean`                      | auto                   | Force block (`true`) or inline (`false`) rendering                                                                                                       |
+| `language`                       | `CodeLanguage`                 | `"tsx"` in block mode  | Grammar (`tsx`, `ts`, `jsx`, `js`, `css`, `html`, `json`, `bash`, `sh`, `shell`, `plain`, `text`) and badge label                                        |
+| `title`                          | `string`                       | unset                  | Filename or caption in the block header, or native `title` when `block={false}`                                                                          |
+| `copyable`                       | `boolean`                      | `true` in block mode   | Show the copy-to-clipboard button in the block header                                                                                                    |
+| `onCopy`                         | `(code: string) => void`       | unset                  | Called with the raw code string after a successful clipboard copy                                                                                        |
+| `lineNumbers`                    | `boolean`                      | `false`                | Render a non-selectable line-number gutter in block mode                                                                                                 |
+| `startLine`                      | `number`                       | `1`                    | Starting line number for `lineNumbers` and `highlightLines`                                                                                              |
+| `highlightLines`                 | `readonly number[]`            | unset                  | Line numbers (relative to `startLine`) to emphasize                                                                                                      |
+| `minLines`                       | `number`                       | unset                  | Minimum visible line count for the block (and default collapsed line count when `collapsible` is enabled without `collapsedLines`)                       |
+| `collapsible`                    | `boolean`                      | `false`                | Add an expand/collapse toggle for longer listings                                                                                                        |
+| `collapsedLines`                 | `number`                       | `minLines`             | Visible line count when a `collapsible` block is collapsed                                                                                               |
+| `defaultCollapsed` / `collapsed` | `boolean`                      | `false` / uncontrolled | Initial or controlled collapsed state when `collapsible` is enabled                                                                                      |
+| `onCollapsedChange`              | `(collapsed: boolean) => void` | unset                  | Called when the user toggles the collapsed state                                                                                                         |
+| `maxHeight`                      | `string \| number`             | unset                  | Maximum viewport height in block mode                                                                                                                    |
+| `tokens`                         | `readonly CodeToken[]`         | `tokenizeCode()`       | Custom `[start, end, kind]` syntax ranges overriding the built-in tokenizer                                                                              |
+| `classNames`                     | `ClassNames<CodePart>`         | unset                  | Extra classes for `header`, `meta`, `title`, `language`, `actions`, `toggle`, `copy`, `viewport`, `pre`, `content`, `line`, `lineNumber`, and `lineText` |
+| `className`, `ref`               | Native element props           | unset                  | Targets `code` in inline mode or root `div` in block mode                                                                                                |
+
+```tsx
+import { Code } from "@kb.ui/react";
+
+export function SnippetExample() {
+  return (
+    <Code
+      title="src/theme.ts"
+      language="ts"
+      lineNumbers
+      highlightLines={[2]}
+      minLines={4}
+    >
+      {`export const defaultTheme = "light";\nexport const accent = "persimmon";`}
+    </Code>
+  );
+}
+```
+
+Single-line strings without block props render as an inline `code` element that inherits surrounding line height and wraps long paths. Strings containing `\n` or any block prop (`language`, `title`, `copyable`, `lineNumbers`, `highlightLines`, `minLines`, `collapsible`, `collapsedLines`, `maxHeight`, `tokens`) switch automatically to a framed block listing unless `block={false}` is set. Line numbers use CSS `attr(data-line-number)` so selecting or reading `code.textContent` returns only the raw code. Customize block surfaces and syntax colors with `--kb-code-block-*` and `--kb-code-syntax-*`.
+
+Block copying shares the [copy feedback props](CopyableText.md#reference): `disabled`, `copyLabel`, `copyingLabel`, `copiedLabel`, `copyErrorLabel`, `successMessage`, `errorMessage`, `feedbackDuration` and `onCopyError`. `Code` defaults to `Copy code`, `Copy failed`, `Code copied to clipboard` and `Failed to copy code. Select and copy the text manually.`. `onCopy` is a successful-write callback rather than a native clipboard event handler. Pending writes retain focus and ignore repeated activation; errors remain visible until retry or source change. `classNames.feedback` styles the persistent polite status region. Block viewports expose a named keyboard scroll region using `title` or the label “Code”.
+
+## Related components
+
+Use [`CodeBlock`](CodeBlock.md) for explicit block semantics, [`CopyableText`](CopyableText.md) for copyable identifiers, [`Text`](Text.md) for prose and [`Link`](Link.md) for a destination.

package/docs/components/CodeBlock.md

@@ -0,0 +1,77 @@
+# CodeBlock
+
+An explicit block listing for commands, configuration and source. Reuses `Code` highlighting, line numbers, line emphasis and collapse behavior, with shared copy feedback and a keyboard-scrollable viewport.
+
+[All components](../../README.md#components) · [Usage](#usage) · [Reference](#reference) · [Live examples and accessibility](https://kbui.kcb.pro/storybook/?path=/docs/components-codeblock--docs)
+
+## Usage
+
+```tsx
+import "@kb.ui/react/styles.css";
+import { CodeBlock } from "@kb.ui/react";
+
+export function Example() {
+  return (
+    <CodeBlock title="Terminal" language="bash" copyLabel="Copy install command">
+      {"bun add @kb.ui/react"}
+    </CodeBlock>
+  );
+}
+```
+
+`children` must be the exact source string. Copy excludes line numbers, syntax markup, highlighted-line decoration and display padding. Collapsed blocks copy the full source. Empty strings disable copying. `CodeBlock` always renders a block, including single-line commands. It uses `.kb-codeblock.kb-code[data-block]`; shared `.kb-code-*` parts and `--kb-code-*` tokens remain compatible with `Code`.
+
+Clipboard feedback appears after the actual write resolves. Pending writes suppress repeat activation and preserve button focus. Errors stay visible with manual selection instructions until retry or source change. Success resets after `feedbackDuration` (two seconds by default, zero retains it). Changes to source or disabled state invalidate outstanding feedback; unmounted instances ignore completion. Already-issued operating-system writes cannot be cancelled.
+
+The named viewport has a keyboard focus stop for horizontal and vertical scrolling. `title` names that region, falling back to `Code`. Syntax color and line emphasis supplement source text; explain important lines in surrounding prose. The collapse action exposes its expanded state and controlled viewport without moving focus. Use controlled `collapsed` with `onCollapsedChange`, or `defaultCollapsed` for local state.
+
+Override `--kb-code-syntax-*` through `style` or a class to change individual syntax colors. The Colorful example maps keyword, string, tag, function and attribute colors to semantic theme tokens. All code and clipboard contents remain unchanged; verify contrast against the listing background after customization.
+
+## More examples
+
+- [Colorful](https://kbui.kcb.pro/storybook/?path=/story/components-codeblock--colorful): customize individual syntax roles with theme colors.
+- [Source](https://kbui.kcb.pro/storybook/?path=/story/components-codeblock--source): highlighted TSX with line numbers and emphasis.
+- [Configuration](https://kbui.kcb.pro/storybook/?path=/story/components-codeblock--configuration): JSON payload.
+- [Collapsible](https://kbui.kcb.pro/storybook/?path=/story/components-codeblock--collapsible): bounded long listings with full-source copy.
+- [Long command](https://kbui.kcb.pro/storybook/?path=/story/components-codeblock--long-command): keyboard scrolling without page overflow.
+- [Copy feedback](https://kbui.kcb.pro/storybook/?path=/story/components-codeblock--copy-feedback): exact clipboard text and retained focus.
+- [Copy failure](https://kbui.kcb.pro/storybook/?path=/story/components-codeblock--copy-failure): visible recovery instructions and retained source.
+- [Localized](https://kbui.kcb.pro/storybook/?path=/story/components-codeblock--localized): long translated labels wrap within narrow listings.
+- [Read only](https://kbui.kcb.pro/storybook/?path=/story/components-codeblock--read-only): source without a copy control.
+
+## Reference
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `children` | `string` | required | Exact source, including whitespace and trailing newlines |
+| `title` | `string` | unset | Header text and accessible viewport name |
+| `language` | `CodeLanguage` | unset | `tsx`, `ts`, `jsx`, `js`, `css`, `html`, `json`, `bash` and aliases; `plain` disables syntax coloring |
+| `copyable` | `boolean` | `true` | Show copy action and status region |
+| `disabled` | `boolean` | `false` | Disable copy while retaining source and collapse interaction |
+| `copyLabel`, `copyingLabel`, `copiedLabel`, `copyErrorLabel` | `string` | `"Copy code"`, `"Copying…"`, `"Copied"`, `"Copy failed"` | Visible button names; failed action retries |
+| `successMessage` | `string` | `"Code copied to clipboard"` | Polite success announcement |
+| `errorMessage` | `string` | `"Failed to copy code. Select and copy the text manually."` | Visible polite recovery instructions |
+| `feedbackDuration` | `number` | `2000` | Success reset in milliseconds; zero retains feedback, invalid or negative uses default |
+| `onCopy` | `(source: string) => void` | unset | Current clipboard write succeeded; replaces native clipboard event prop |
+| `onCopyError` | `(error: unknown) => void` | unset | Current write failed or API unavailable |
+| `lineNumbers` | `boolean` | `false` | Decorative line gutter |
+| `startLine` | `number` | `1` | First displayed line number |
+| `highlightLines` | `readonly number[]` | unset | Emphasized display line numbers, accounting for `startLine` |
+| `minLines` | `number` | unset | Minimum displayed lines without altering source |
+| `collapsible` | `boolean` | `false` | Show expand/collapse action |
+| `collapsedLines` | `number` | unset | Collapsed viewport line count; falls back to `minLines` |
+| `defaultCollapsed` | `boolean` | `false` | Initial local collapsed state |
+| `collapsed` | `boolean` | unset | Controlled collapsed state |
+| `onCollapsedChange` | `(collapsed: boolean) => void` | unset | Collapse state request |
+| `maxHeight` | `string \| number` | unset | Scrollable viewport limit; number interpreted as CSS pixels |
+| `tokens` | `readonly CodeToken[]` | automatic | Ordered, non-overlapping UTF-16 ranges for external syntax highlighting |
+| `classNames` | `Partial<Record<CodePart, string>>` | unset | Shared `Code` slots including `copy`, `feedback`, `viewport`, `line`, `lineNumber`, `lineText` |
+| `className`, `ref`, other props | Native root props | unset | Root `div`; ref typed as HTMLDivElement |
+
+No syntax dependency is added. Supported languages use `Code`'s small tokenizer; external highlighting can supply tokens. When loading standalone CSS parts, import both `code.css` and `codeblock.css` in that order. The bundled stylesheet includes both.
+
+Automated checks exercise exact copies, controlled collapse, keyboard activation, scrolling and accessibility scans. Verify real clipboard permission behavior and human screen-reader announcements in the consuming application. See [shared copy guidance](https://github.com/KhallilB/kbui/blob/main/docs/guides/copyable-content.md).
+
+## Related components
+
+Use [`Code`](Code.md) for inline literals or automatic block detection and [`CopyableText`](CopyableText.md) for identifiers and references outside source listings.