# GPUIxUI

> The documentation for GPUIxUI, a native UI component library for GPUix and React. Components render through GPUix host elements, not the DOM.

This is every page the site serves, as Markdown, in the order the sidebar
shows them. `/llms.txt` is the same list as an index, one line per page.
The site is a browser application documenting a native library, so a browser
preview is a labelled approximation of the component unless the page says it
mounts the real renderer (`/live`, the wasm build). `.agents/slop/COMPONENTS.md` in the
repository — not a page's existence — is the status record for every
component.

---

# Guide

Source: https://gpuixui.sudokw.com/getting-started

Add a component, render a window, pick a theme.

## Install [#install]

```sh
npx shadcn@latest add @sudokw/primitives-button
```

```json
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "@gpuix/react"
  }
}
```

React 19. `@gpuix/native` ships prebuilt for Apple Silicon, Linux x64 and
Windows. Any other host builds the binding once, as
[`apps/playground/README.md`](https://github.com/Cyberistic/GPUIXUI/blob/master/apps/playground/README.md#the-binding-on-this-host)
describes.

## First component [#first-component]

```tsx
import { render } from "@gpuix/react";
import { Button } from "@gpuixui/primitives";
import { darkTheme } from "@gpuixui/tokens";
import { ThemeProvider } from "@gpuixui/tokens/react";

render(
  <ThemeProvider theme={darkTheme}>
    <Button variant="primary" onActivate={save}>
      Save changes
    </Button>
  </ThemeProvider>,
);
```

`render` takes **one** element: a fragment at the root paints only its last
child.

## Theme [#theme]

```tsx
import { getTheme, platformTheme } from "@gpuixui/tokens";
import { ThemeProvider } from "@gpuixui/tokens/react";

const theme = platformTheme(getTheme("dark"), "win32");

<ThemeProvider theme={theme}>{app}</ThemeProvider>;
```

Modes: `light`, `dark`. Contrast: `default`, `high`. Platforms: `darwin`,
`win32`, `linux`, `default`.

## Next [#next]

- [Components](/components)
- [Blocks](/blocks)
- [Themes](/themes)
- [Registry](/registry)
- [Reference](/reference)

---

# Omarchy

Source: https://gpuixui.sudokw.com/getting-started/omarchy

Develop on Hyprland/Arch, and follow the theme the desktop is running.

## Run [#run]

```sh
git clone https://github.com/Cyberistic/GPUIXUI.git
cd GPUIXUI
nub install
nub run dev:playground
```

## Follow the live theme [#follow-the-live-theme]

```tsx
import { readFileSync } from "node:fs";
import { decodeOmarchyPalette, paletteToTokens } from "@gpuixui/tokens";
import { ThemeProvider } from "@gpuixui/tokens/react";

const file = decodeOmarchyPalette(
  readFileSync(
    `${process.env.HOME}/.local/state/omarchy/current/theme/colors.toml`,
    "utf8",
  ),
);

<ThemeProvider theme={paletteToTokens(file.palette)}>{app}</ThemeProvider>;
```

---

# Build prompt

Source: https://gpuixui.sudokw.com/getting-started/prompt

A copyable build prompt, generated from the pages

Paste this into an agent before it starts. It is generated at build time from the
pages the site ships: component rows from the Components index, block rows from
the block pages' frontmatter.

<PromptPage />

---

# Terminal

Source: https://gpuixui.sudokw.com/getting-started/terminal

Run the same view inside kitty or Ghostty instead of a window.

`render` takes `terminal: true`, and the runtime paints the app into the terminal it was started from:

```tsx
import { render } from "@gpuix/react";

render(<App />, { terminal: true });
```

`GPUIX_TERMINAL=1` sets the same option, so an unchanged entrypoint runs either way:

```sh
GPUIX_TERMINAL=1 nub src/main.tsx
```

The playground in this repository:

```sh
nub run --filter playground build
GPUIX_TERMINAL=1 nub apps/playground/dist/main.js
```

---

# Examples

Source: https://gpuixui.sudokw.com/examples

Every worked example a package ships, and the file to copy.

Each package keeps a worked example beside its components, generated from `packages/*/examples/*.example.tsx`. They are GPUix modules, not browser components: the page shows the source, not a rendering.

<ExamplesIndex />

## Running one [#running-one]

```bash
nub run --filter @gpuixui/primitives test:runtime
```

```bash
nub run --filter playground build
nub apps/playground/dist/smoke/run.js --only examples-mount
```

The scenario's checks are in `apps/playground/README.md`.

## Adding one [#adding-one]

Create `packages/<package>/examples/<id>.example.tsx` exporting one component with a `<Name> example: …` header, and add it to that package's `examples/index.ts`.

---

# Introduction

Source: https://gpuixui.sudokw.com/introduction

Native React components for GPUix

**Native components, open source, built on GPUix.**

Every component renders through GPUix host elements: no DOM, CSS or browser runtime.

```tsx
import { Badge } from "@gpuixui/components/badge";
import { lightTheme } from "@gpuixui/tokens";
import { ThemeProvider } from "@gpuixui/tokens/react";

<ThemeProvider theme={lightTheme}>
  <Badge variant="success">Connected</Badge>
</ThemeProvider>;
```

Compound parts validate their placement: a `DialogTitle` inside `Dialog` but
outside `DialogContent` throws, and the message names the parent and what to do
instead.

```tsx
<Dialog>
  <DialogTrigger>Rename project</DialogTrigger>
  <DialogContent label="Rename project">
    <DialogHeader>
      <DialogTitle>Rename project</DialogTitle>
      <DialogDescription>Used everywhere the project is named.</DialogDescription>
    </DialogHeader>
    <DialogFooter>
      <DialogClose variant="ghost">Cancel</DialogClose>
      <DialogClose variant="primary">Save</DialogClose>
    </DialogFooter>
  </DialogContent>
</Dialog>;
```

## Start here [#start-here]

<Cards>
  <Card title="Guide" href="/getting-started">
    Clone the workspace, render the first component and pick a theme.
  </Card>
  <Card title="Components" href="/components">
    Every component the library ships, with its keyboard contract and API.
  </Card>
  <Card title="Blocks" href="/blocks">
    Whole windows assembled from the library's parts.
  </Card>
  <Card title="Runtime capabilities" href="https://github.com/Cyberistic/GPUIXUI/blob/master/docs/gpuix-capabilities.md">
    What the pinned runtime provides, what it does not, and what to do instead.
  </Card>
</Cards>

---

# API reference

Source: https://gpuixui.sudokw.com/reference

Every export the workspace publishes

The public API is each package's `exports` map: an import outside it is internal and may move without a major version.

Generated from this workspace's source, on `@gpuix/native` 0.11.0 and `@gpuix/react` 0.11.0.

<ApiReference />

The filter travels in the URL (`?q=createTheme`).

[`/llms.txt`](/llms.txt) lists every page, grouped the way the sidebar groups it.
[`/llms-full.txt`](/llms-full.txt) is the same pages as one Markdown document:
prose, API tables and limits.

## Where the signatures live [#where-the-signatures-live]

| Question | Where |
| -------- | ----- |
| The props, defaults and consequences of a part | The component's page under [Components](/components) or [Primitives](/primitives) |
| Whether a component ships, and what the runtime measured | [`.agents/slop/COMPONENTS.md`](https://github.com/Cyberistic/GPUIXUI/blob/master/.agents/slop/COMPONENTS.md) |
| Colour, type, spacing, radius, density and platform styles | The [guide](/getting-started) and [`docs/tokens.md`](https://github.com/Cyberistic/GPUIXUI/blob/master/docs/tokens.md) |
| What the runtime provides and refuses | [`docs/gpuix-capabilities.md`](https://github.com/Cyberistic/GPUIXUI/blob/master/docs/gpuix-capabilities.md) |

---

# Registry

Source: https://gpuixui.sudokw.com/registry

Install a component's source with the shadcn CLI.

Every component is a [shadcn registry](https://ui.shadcn.com/docs/registry)
item. `shadcn add` copies the source into your project; it renders through
GPUix, not the DOM.

## Install [#install]

```sh
npx shadcn@latest add @sudokw/primitives-button
```

Or by direct address:

```sh
npx shadcn@latest add https://gpuixui.sudokw.com/primitives-button.json
```

That installs the component, its parts, the `@gpuixui/*` runtime and the npm
packages they import. Items are `<package>-<component>`; list them with
`npx shadcn@latest search @sudokw`.

## Set the JSX runtime [#set-the-jsx-runtime]

```json
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "@gpuix/react"
  }
}
```

## Render it [#render-it]

```tsx
import { render } from "@gpuix/react";
import { Button } from "@/components/ui/gpuixui/primitives/components/Button";
import { ThemeProvider } from "@/components/ui/gpuixui/primitives/components/ThemeProvider";
import { darkTheme } from "@/components/ui/gpuixui/tokens";

render(
  <ThemeProvider theme={darkTheme}>
    <Button variant="primary" onActivate={save}>
      Save changes
    </Button>
  </ThemeProvider>,
);
```

`ThemeProvider` is required. `@gpuix/native` ships binaries for Apple Silicon,
Linux x64 and Windows.

Files land under your `ui` alias in `gpuixui/`:

```
src/components/ui/gpuixui/primitives/components/Button.tsx
src/components/ui/gpuixui/tokens/index.ts
```

The runtime items (`gpuix-tokens`, `gpuix-tw`, `gpuix-motion`,
`gpuix-primitives`) install once per project. The site serves the index at
[`/registry.json`](/registry.json) and one document per item at `/<name>.json`.

---

# Themes

Source: https://gpuixui.sudokw.com/themes

Edit the tokens live, pick a look, import a shadcn theme.

<ThemeEditor />

## Reading the audit [#reading-the-audit]

`mutedForeground on muted — 3.90:1 (needs 4.5:1)`. A ratio that **cannot be
computed** prints **unmeasurable** — a wash, not a pass; the prefix names the
report it came from.

Switch box:

`switch height — 22 cannot hold a knob that needs 32`

`switch width — 0 cannot be laid out (needs a size greater than zero)`

Edits are stored per mode over the platform style; a browser that refuses site
storage keeps the editor. **Reset** clears them; **Copy theme** prints it.

## The looks [#the-looks]

<LookPicker />

## Bring a shadcn theme [#bring-a-shadcn-theme]

```tsx
import { shadcnTheme } from "@gpuixui/tokens";

const theme = shadcnTheme(css, "dark");
```

**Default** is shadcn's neutral theme, audited as warnings.

## styles.css [#stylescss]

<ThemeStylesheet />

## The style reference [#the-style-reference]

<StyleReference />

### Type scale [#type-scale]

<TypeScale />

### Spacing, radius and density [#spacing-radius-and-density]

<TokenScales />

## Blocks [#blocks]

<BlockPreview name="desktop-01" />

---

# Components

Source: https://gpuixui.sudokw.com/components

Every component the library ships

<ComponentIndex />

---

# Accordion

Source: https://gpuixui.sudokw.com/components/accordion

Stacked sections, one or several open

<ComponentPreview name="accordion-demo" />

<ComponentPreview name="accordion-composition" />

## Installation [#installation]

<Install packageName="@gpuixui/components" importName="Accordion" />
<ComponentSource name="accordion" file="packages/components/src/accordion.tsx" />

## Usage [#usage]

```tsx
import {
  Accordion,
  AccordionContent,
  AccordionItem,
  AccordionTrigger,
} from "@gpuixui/components/accordion";

<Accordion type="single" collapsible defaultValue="surface">
  <AccordionItem value="surface">
    <AccordionTrigger>What is a GPUix surface?</AccordionTrigger>
    <AccordionContent>
      A tree of hosted elements the renderer lays out and paints.
    </AccordionContent>
  </AccordionItem>
  <AccordionItem value="motion">
    <AccordionTrigger>Why does the panel animate?</AccordionTrigger>
    <AccordionContent>Its measured height is the tween target.</AccordionContent>
  </AccordionItem>
</Accordion>;
```

## Composition [#composition]

```text
Accordion
├── AccordionItem
│   ├── AccordionTrigger
│   └── AccordionContent
```

## API reference [#api-reference]

| Part | Prop | Type | Default |
| ---- | ---- | ---- | ------- |
| `Accordion` | `type` | `"single" \| "multiple"` | required |
| `Accordion` | `collapsible` | `boolean` — single mode only | `false` |
| `Accordion` | `value` | `string \| null` (single) · `ReadonlyArray<string>` (multiple) | — ; a stored open set that is not a list means uncontrolled |
| `Accordion` | `defaultValue` | the same union, for the uncontrolled form | `null` · `[]` — a stored default that is not a list opens no sections |
| `Accordion` | `onValueChange` | `(value: string \| null) => void` · `(values: ReadonlyArray<string>) => void` | — |
| `AccordionItem` | `value` | `string` | required |
| `AccordionItem` | `disabled` | `boolean` | `false` |
| `AccordionTrigger` | `style` | `StateStyle<{ open, disabled, focused }>` | the recipe |
| `AccordionContent` | `children` | `ReactNode` | — |
| any part | `className` | `string` | — |

---

# Alert

Source: https://gpuixui.sudokw.com/components/alert

A persistent, in-flow message about the current state

<ComponentPreview name="alert-tones" />

<ComponentPreview name="alert-composition" />

## Installation [#installation]

<Install packageName="@gpuixui/components" importName="Alert" />
<ComponentSource name="alert" file="packages/components/src/alert.tsx" />

## Usage [#usage]

```tsx
import {
  Alert,
  AlertContent,
  AlertDescription,
  AlertTitle,
} from "@gpuixui/components/alert";

<Alert tone="warning">
  <AlertContent>
    <AlertTitle>3 tokens are missing</AlertTitle>
    <AlertDescription>
      The platform themes fall back to the default palette.
    </AlertDescription>
  </AlertContent>
</Alert>;
```

## Composition [#composition]

```text
Alert
├── AlertIcon
├── AlertContent
│   ├── AlertTitle
│   ├── AlertDescription
│   └── AlertLink
└── AlertDismiss
```

## API reference [#api-reference]

| Part | Prop | Type | Default | Consequence |
| ---- | ---- | ---- | ------- | ----------- |
| `Alert` | `tone` | `"info" \| "success" \| "warning" \| "danger"` | `"info"` — a stored name the union does not carry | the surface, edge and readable colour every part inherits |
| `Alert` | `children` | parts | — | the composition; a part outside the root throws |
| any part | `className` | `string` | — | joined after that part's recipe; `style` still merges last |
| `AlertLink` | `onSelect` | `() => void` | — | the text action's handler, on click, `Enter` or `Space` |
| `AlertDismiss` | `onDismiss` | `() => void` (required) | — | runs on click, `Enter` or `Space`; there is no optional dismiss |
| `AlertDismiss` | `label` | `string` | `"Dismiss"` | the control's accessible name |

---

# Aspect ratio

Source: https://gpuixui.sudokw.com/components/aspect-ratio

A box whose height follows its width through one ratio

<ComponentPreview name="aspect-ratio-demo" />

## Usage [#usage]

```tsx
import { AspectRatio } from "@gpuixui/components/aspect-ratio";

export const Still = () => (
  <div style={{ width: 360 }}>
    <AspectRatio ratio={16 / 9}>
      <div style={{ width: "100%", height: "100%" }} />
    </AspectRatio>
  </div>
);
```

## Composition [#composition]

```text
AspectRatio
└── content
```

## API [#api]

| Part | Prop | Type | Default |
| ---- | ---- | ---- | ------- |
| `AspectRatio` | `ratio` | `number` — width divided by height | `1` |
| `AspectRatio` | `className` | `string` | — |
| `AspectRatio` | `style` | `StyleDesc` — merged last | — |
| `AspectRatio` | `children` | `ReactNode` — the content that fills the box | — |
| `AspectRatio` | `testId` | `string` | — |

---

# Auth

Source: https://gpuixui.sudokw.com/components/auth

Sign in, sign up, reset and one-time codes

### Sign in [#sign-in]

<ComponentPreview name="auth-sign-in" />

### Sign up [#sign-up]

<ComponentPreview name="auth-sign-up" />

### Forgot password [#forgot-password]

<ComponentPreview name="auth-forgot-password" />

### One-time code [#one-time-code]

<ComponentPreview name="auth-one-time-code" />

## Installation [#installation]

<Install packageName="@gpuixui/primitives" importName="Button" />

<Install packageName="@gpuixui/components" importName="Card" />

<ComponentSource name="auth" file="apps/docs/src/components/docs/auth-blocks.tsx" />

## Usage [#usage]

```tsx
import { Button, Input, Label, Separator, Stack, Text } from "@gpuixui/primitives";
import {
  Card,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
} from "@gpuixui/components/card";

export function SignInCard() {
  return (
    <Card variant="outline" style={{ width: 360 }}>
      <CardHeader>
        <CardTitle>Login to your account</CardTitle>
        <CardDescription>Enter your email below to login to your account</CardDescription>
      </CardHeader>
      <CardContent>
        <Stack direction="column" gap="md">
          <Label>Email</Label>
          <Input label="Email" placeholder="you@example.com" fullWidth />
          <Label>Password</Label>
          <Input label="Password" placeholder="••••••••" fullWidth />
          <Button variant="primary" fullWidth onActivate={signIn}>
            Sign in
          </Button>
          <Separator label="or continue with" />
          <Button variant="secondary" fullWidth onActivate={signInWithGitHub}>
            GitHub
          </Button>
        </Stack>
      </CardContent>
      <Text role="caption" tone="muted">
        Don't have an account?
      </Text>
    </Card>
  );
}
```

## Composition [#composition]

| Part | Responsibility |
| ---- | -------------- |
| `Card` | the centred surface, `variant="outline"` |
| `CardHeader` / `CardTitle` / `CardDescription` | the mark, the title and the sentence under it |
| `CardContent` | the field column, the actions and the divider |
| `CardFooter` | the route to the neighbouring card |
| `Label` / `Input` | one named field |
| `Checkbox` | the terms gate and the remembered session |
| `OTPField` | the six code cells |
| `Separator` | the "or continue with" divider |
| `Button` | the primary action, the providers, the links and the resend control |
| `Text` | the footer sentence and the inline note |

## API reference [#api-reference]

Each recipe adds its own callback set.

## Recipes [#recipes]

| Member | Contract |
| ------ | -------- |
| `LoginPage` | `onSubmit`, `onProvider`, `pending`, `error` |
| `SignupPage` | `onSubmit`, `pending`, `error` |
| `ForgotPasswordPage` | `onSubmit`, `pending` |
| `OtpPage` | `onSubmit`, `onResend` |
| `SignInPage` | the full page — navbar, form card and quote panel — over the same callbacks |

## Keyboard [#keyboard]

| Key | Contract |
| --- | -------- |
| `Tab` | walks fields, links, the primary action, both providers and the footer in order |
| `Enter` | submits the focused form; the primary action carries the busy state |
| `Space` | toggles the focused checkbox; the terms gate is submitted with the form |
| `Backspace` | in an empty one-time-code cell, moves focus to the previous cell |
| `Tab` from a code cell | leaves the group; the cells are one tab stop each, not a roving group |

---

# Auto height

Source: https://gpuixui.sudokw.com/components/auto-height

A reveal that grows to its content's measured height

<ComponentPreview name="auto-height-demo" />

## Usage [#usage]

```tsx
import { AutoHeight } from "@gpuixui/components/auto-height";

<AutoHeight open={open}>
  <text>Retry budget: 5 attempts</text>
  <text>Timeout: 30 seconds</text>
</AutoHeight>;
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `children` | `ReactNode` | — |
| `open` | `boolean` (required) | — |
| `level` | `MotionLevel` | `"normal"` |
| `timing` | `SurfaceTiming` | the `level`'s |
| `className` | `string` | — |
| `contentClassName` | `string` | — |
| `style` | `StateStyle<AutoHeightState>` | — |

## Motion [#motion]

The box grows to the content's measured height on the `normal` level (200 ms): it eases out on the way open and in on the way back. A caller that moves a box between two resting states passes its own `timing`, so the height and the fade paint on one curve. The content fades in `20 ms` after the height starts, so the two do not race, and it fades out with the closing box. The subtree stays mounted for the exit window and unmounts after it. Under `MotionProvider preference="reduced"` the duration is zero and the measured height paints at once.

---

# Avatar

Source: https://gpuixui.sudokw.com/components/avatar

A person or team as a picture, falling back to initials

<ComponentPreview name="avatar-states" />

<ComponentPreview name="avatar-workflow" />

## Installation [#installation]

<Install packageName="@gpuixui/components" importName="Avatar" />
<ComponentSource name="avatar" file="packages/components/src/avatar.tsx" />

## Usage [#usage]

```tsx
import { Avatar } from "@gpuixui/components/avatar";

<Avatar name="Ada Lovelace" src="/photos/ada.png" size="md" status="online" />;

// Without a picture the initials are derived from the name.
<Avatar name="Jean-Luc Picard" />;
```

## API reference [#api-reference]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `name` | `string` | — (required) | the accessible label **and** the initials' source |
| `src` | `string` | — | a path, data URL or `http(s)` URL; without it the initials paint |
| `size` | `"xs" \| "sm" \| "md" \| "lg"` | `"md"` | the diameter from `avatarSize`; a stored name the scale does not carry falls back to `md` |
| `status` | `"online" \| "away" \| "busy" \| "offline"` | — | paints the dot and becomes the node's description; a stored name the union does not carry paints no dot |
| `color` | `string` | the muted role | fills the disc |
| `initials` | `boolean` | `true` | `false` paints a plain colour dot; the name stays the accessible one |
| `radius` | `number` | a circle | a rounded square in place of the circle |
| `clickThrough` | `boolean` | on, unless the avatar has its own press handler | lets a press fall through to the row, card or trigger the avatar sits in; an avatar given `onClick` keeps its press |
| `className` | `string` | — | joined after the root recipe |
| `style` | `StyleDesc \| (state) => StyleDesc` | — | merged last |

---

# Avatar group

Source: https://gpuixui.sudokw.com/components/avatar-group

A facepile of overlapping avatars with an overflow chip

<ComponentPreview name="avatar-group-demo" />

## Usage [#usage]

```tsx
import { AvatarGroup } from "@gpuixui/components/avatar-group";

<AvatarGroup
  members={[
    { name: "Ada Lovelace", status: "online" },
    { name: "Grace Hopper", status: "busy" },
    { name: "Alan Turing" },
    { name: "Katherine Johnson" },
  ]}
  max={3}
  label="Project team"
/>;
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `members` | `ReadonlyArray<AvatarGroupMember>` (a value that is not a list reads as none; an entry without a text `name` is dropped) | — |
| `max` | `number` | everyone |
| `size` | `"xs" \| "sm" \| "md" \| "lg"` | `"md"` |
| `overlap` | `number` | quarter of the diameter |
| `ringColor` | `string` | theme `background` |
| `label` | `string` | `${count} avatars` |
| `stepMs` | `number` | `40` |
| `rise` | `number` | `6` |
| `level` | `MotionLevel` | `"normal"` |
| `className` | `string` | — |
| `style` | `StateStyle<AvatarGroupState>` | — |

---

# Badge

Source: https://gpuixui.sudokw.com/components/badge

A short status label on a pill, never a control

<ComponentPreview name="badge-workflow" />

## Installation [#installation]

<Install packageName="@gpuixui/components" importName="Badge" />
<ComponentSource name="badge" file="packages/components/src/badge.tsx" />

## Usage [#usage]

```tsx
import { Badge } from "@gpuixui/components/badge";

<Badge variant="success" size="sm">
  Passed
</Badge>;
<Badge>main</Badge>;
```

## API reference [#api-reference]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `variant` | `"neutral" \| "primary" \| "success" \| "warning" \| "danger" \| "info" \| "outline"` | `"neutral"` — a stored name the union does not carry | the fill, ink and edge in **Variants** below |
| `size` | `"sm" \| "md"` | `"md"` — a stored name the union does not carry | the fixed type step and the pill's height in **Sizes** below |
| `className` | `string` | none | joined last |
| `style` | `StyleDesc` | none | merged last |
| `children` | `ReactNode` | — | the label |

**Variants**

| Variant | Fill | Ink | Edge |
| ------- | ---- | --- | ---- |
| `neutral` | `muted` | `mutedForeground` | none |
| `primary` | `primary` | `primaryForeground` | none |
| `success` | `successSoft` | `successSoftForeground` | `success` at 30% |
| `warning` | `warningSoft` | `warningSoftForeground` | `warning` at 30% |
| `danger` | `destructiveSoft` | `destructiveSoftForeground` | `destructive` at 30% |
| `info` | `infoSoft` | `infoSoftForeground` | `info` at 30% |
| `outline` | none | `mutedForeground` | `borderStrong` |

**Sizes**

| Size | Type | Pill height |
| ---- | ---- | ----------- |
| `sm` | 12/16, weight 400 | 20px |
| `md` | 14/20, weight 500 | 24px |

---

# Breadcrumb

Source: https://gpuixui.sudokw.com/components/breadcrumb

The trail to the current page, with a collapsing middle

<ComponentPreview name="breadcrumb-workflow" />

## Installation [#installation]

<Install packageName="@gpuixui/components" importName="Breadcrumb" />
<ComponentSource
  name="breadcrumb"
  file="packages/components/src/breadcrumb.tsx"
/>

## Usage [#usage]

```tsx
import {
  Breadcrumb,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbPage,
  BreadcrumbSeparator,
} from "@gpuixui/components/breadcrumb";

<Breadcrumb maxItems={4}>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink onSelect={() => go("Projects")}>Projects</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbLink onSelect={() => go("GPUIXUI")}>GPUIXUI</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbPage>breadcrumb.tsx</BreadcrumbPage>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>;
```

## Composition [#composition]

```text
Breadcrumb
└── BreadcrumbList
    └── BreadcrumbItem
        ├── BreadcrumbLink
        ├── BreadcrumbPage
        └── BreadcrumbSeparator
```

## API reference [#api-reference]

| Part | Prop | Type | Default | Consequence |
| ---- | ---- | ---- | ------- | ----------- |
| `Breadcrumb` | `maxItems` | `number` | — | rendered entries to keep; below `3` is clamped to `3`, absent means no collapse |
| `Breadcrumb` | `separator` | `ReactNode` | `/` | the glyph between entries; a node, so a chevron works |
| `Breadcrumb` | `children` | parts | — | `BreadcrumbList` |
| `BreadcrumbList` | `children` | parts | — | the items and any authored separators |
| `BreadcrumbItem` | `children` | parts | — | `BreadcrumbLink` or `BreadcrumbPage` |
| `BreadcrumbLink` | `onSelect` | `() => void` | — | runs on click, `Enter` or `Space` |
| `BreadcrumbLink` | `current` | `boolean` | `false` | renders the current page instead of a link |
| `BreadcrumbPage` | `children` | text | — | the current page; not focusable |
| `BreadcrumbSeparator` | `children` | text | `/` | the default glyph when none is authored |
| all parts | `className` | `string` | — | an extra recipe class, joined last |

---

# Bubble

Source: https://gpuixui.sudokw.com/components/bubble

The message surface, with variants and reactions

<ComponentPreview name="bubble-demo" />

A bubble is the surface one message wears. It is independent of `Message`: use
it for a reply, a quoted message, a suggestion or a notification. `Message` owns
the author, avatar, timestamp and row layout; `Bubble` owns the painted box.

## Installation [#installation]

```bash
nub add @gpuixui/components
```

## Usage [#usage]

```tsx
import {
  Bubble,
  BubbleAction,
  BubbleActions,
  BubbleContent,
} from "@gpuixui/components";

<Bubble variant="muted" align="end">
  <BubbleContent>Roll it out to the whole team.</BubbleContent>
  <BubbleActions label="Message actions">
    <BubbleAction label="Copy" onClick={copy} />
  </BubbleActions>
</Bubble>;
```

## Composition [#composition]

```text
Bubble
├── BubbleContent
├── BubbleActions
│   └── BubbleAction
└── BubbleReactions
```

`BubbleGroup` stacks consecutive bubbles from one sender:

```text
BubbleGroup
├── Bubble group="first"
├── Bubble group="middle"
└── Bubble group="last"
```

## Variants [#variants]

| Variant       | Description                                                |
| ------------- | ---------------------------------------------------------- |
| `default`     | The primary fill, usually the reader's own message.         |
| `secondary`   | The neutral secondary fill.                                 |
| `muted`       | A quiet supporting surface.                                 |
| `tinted`      | A soft primary tint.                                        |
| `outline`     | A bordered surface on the page fill.                        |
| `ghost`       | Unframed prose; it takes the whole row instead of 80%.      |
| `destructive` | A soft destructive surface for a failed turn or an error.   |

A bubble is at most 80% of its row (`ghost` is 100%). Pass `maxWidth` to change
the cap.

## Grouping [#grouping]

`BubbleGroup` tightens the gap to the theme's `md` (8px). Each bubble names its
place with `group`: `first` joins below, `middle` joins both sides, `last`
joins above and keeps a short tail on the sender's corner, and `single` is the
whole radius. The joined corner is the theme's `sm` step and the outer corners
keep `xl`, so a run reads as one column without losing its frame.

## Shape [#shape]

The surface is shadcn's: `px-3 py-2` (12px by 8px), the `body` type role
(14px/20px), and the theme's `xl` corner. A bubble is at most 80% of its row
(`ghost` is 100%); pass `maxWidth` to change the cap.

## Actions and reactions [#actions-and-reactions]

`BubbleActions` is laid out even while hidden and fades in on pointer-over or
when one of its `BubbleAction`s holds focus, so revealing it never moves the
bubble.

`BubbleReactions` is the pill on the bubble's edge: inset 12px from the
sender's side, a full radius, the `muted` fill and a page-fill ring around it so
it reads as cut out of the surface. It hangs a quarter of its height over the
bubble's bottom edge — `translate-y-3/4`'s crossing, expressed as a negative
inset from inside the column — and the rest of the pill's box lays out below the
edge, so the next row cannot paint over it.

## API [#api]

| Part | Renders | Props |
| ---- | ------- | ----- |
| `Bubble` | the row: optional avatar, content column, 80% cap | `variant?`, `align?`, `group?`, `maxWidth?`, `avatar?`, `className?`, `children` |
| `BubbleContent` | the framed surface | `className?`, `children` |
| `BubbleActions` | a named group that reserves its height and fades in | `label?`, `className?`, `children` |
| `BubbleAction` | one small ghost action, and the `Button` busy state | `label` (required), `onClick`, `disabled?`, `className?`, `loading?`, `loadingLabel?`, `leading?`, `trailing?`, `reducedMotion?` |
| `BubbleReactions` | a named pill that hangs over the surface's edge | `label` (required), `className?`, `children` |
| `BubbleGroup` | a tighter column | `gap?`, `className?`, `children` |

---

# Button

Source: https://gpuixui.sudokw.com/components/button

The primary action, with busy and disabled states

<ComponentPreview name="button-variants" />

<ComponentPreview name="button-sizes" />
<ComponentPreview name="button-states" />

## Installation [#installation]

<Install packageName="@gpuixui/primitives" importName="Button" />
<ComponentSource
  name="button"
  file="packages/primitives/src/components/Button.tsx"
/>

## Usage [#usage]

```tsx
import { Button } from "@gpuixui/primitives";

<Button variant="primary" onActivate={save}>
  Save changes
</Button>;
```

## API reference [#api-reference]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `variant` | `"primary" \| "secondary" \| "outline" \| "ghost" \| "destructive" \| "link"` | `"primary"` | paint from the variant table |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | height and padding from density |
| `square` | `boolean` | `false` | icon-only geometry |
| `fullWidth` | `boolean` | `false` | `width: 100%` |
| `disabled` | `boolean` | `false` | blocks activation, leaves the tab order |
| `tabIndex` | `number` | `0`, or `-1` while `disabled` | the action's Tab stop; a caller's value wins both ways |
| `loading` | `boolean` | `false` | spinner, `Loading` description, blocks activation |
| `loadingLabel` | `string` | the provider's `loading.busy` (`Loading`) | the spinner's accessible name |
| `reducedMotion` | `boolean` | the provider's preference (`false` when none) | lands the busy spinner at rest; the prop wins |
| `leading` / `trailing` | `ReactNode` | none | icon or element beside the label |
| `label` | `string` | none | accessible name; required for an icon-only button |
| `onActivate` | `(event: EventPayload) => void` | none | click or activating key, with that event; not called while busy |
| `onClick` | `(event) => void` | none | raw click, called before `onActivate` |
| `onKeyDown` / `onKeyUp` | `(event: KeyEvent) => void` | none | composed **after** the activation |
| `onFocus` / `onBlur` | `(event) => void` | none | composed before the button's own |
| `onMouseEnter` / `onMouseLeave` / `aria-description` | the tooltip trigger pair and its words | none | a `Tooltip` forwards them; a hover lands on the element itself |
| `ref` | `Ref<PublicInstance>` | none | the element itself, for a caller that focuses or measures it |
| `className` | `string` | none | joined last |
| `style` | `StyleDesc` | none | merged last |
| `testId` | `string` | none | stable locator |
| `children` | `ReactNode` | none | visible label |

---

# Calendar

Source: https://gpuixui.sudokw.com/components/calendar

A month grid for a day, several days, or a range

<ComponentPreview name="calendar-single" />

<ComponentPreview name="calendar-range" />

<ComponentPreview name="calendar-dropdowns" />

## Installation [#installation]

<Install packageName="@gpuixui/components" importName="Calendar" />
<ComponentSource name="calendar" file="packages/components/src/calendar.tsx" />

## Usage [#usage]

```tsx
import { Calendar } from "@gpuixui/components/calendar";
import { useState } from "react";

export const ReviewDate = () => {
  const [day, setDay] = useState<string | null>("2026-10-17");

  return <Calendar selected={day} onSelect={setDay} today="2026-10-17" />;
};
```

```tsx
<Calendar
  mode="range"
  numberOfMonths={2}
  disabled={{ weekdays: [0, 6] }}
  selected={range}
  onSelect={setRange}
  today="2026-10-17"
/>
```

## API reference [#api-reference]

### `Calendar` [#calendar]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `mode` | `"single" \| "multiple" \| "range"` | `"single"` | selects the value shape `selected` and `onSelect` speak |
| `selected` | `string \| null` · `ReadonlyArray<string>` · `{ from, to } \| null` | none | the controlled selection, typed by `mode` |
| `onSelect` | `(day \| days \| range) => void` | none | the next selection; the component never stores it |
| `numberOfMonths` | `1 \| 2` | `1` | months painted side by side, sharing one nav pair |
| `showOutsideDays` | `boolean` | `true` | paints the neighbouring months' days, which are also selectable |
| `captionLayout` | `"label" \| "dropdown"` | `"label"` | a month caption, or month and year jump controls |
| `weekStartsOn` | `0 \| 1` | `1` | the first column: Sunday (`0`) or Monday (`1`) |
| `fromYear` / `toYear` | `number` | today ± 10 | the years a dropdown or a `Shift` page may reach |
| `disabled` | `{ before?, after?, range?, weekdays?, filter? }` | none | refuses days; `before`/`after` also bound paging and the arrows |
| `today` | `string` | the runtime clock | the ISO day painted as today; pass it for a deterministic surface |
| `defaultMonth` | `string` | the selection or today | the ISO day whose month the grid opens on |
| `autoFocus` | `boolean` | `false` | takes focus on mount, for a calendar opened inside a popover |
| `label` | `string` | `"Calendar"` | the grid's accessible name, followed by the selection summary |
| `onDismiss` | `() => void` | none | called by `Escape`; a popover passes its close |
| `className` | `string` | none | joined after the recipe, so it wins conflicts |

---

# Card

Source: https://gpuixui.sudokw.com/components/card

A bounded surface that groups related content

<ComponentPreview name="card-variants" />

<ComponentPreview name="card-composition" />

## Installation [#installation]

<Install packageName="@gpuixui/components" importName="Card" />
<ComponentSource name="card" file="packages/components/src/card.tsx" />

## Usage [#usage]

```tsx
import {
  Card,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@gpuixui/components/card";

<Card>
  <CardHeader>
    <CardTitle>Pro plan</CardTitle>
    <CardDescription>
      Everything in Starter, plus seats and invoicing.
    </CardDescription>
  </CardHeader>
  <CardContent>{rows}</CardContent>
  <CardFooter>{actions}</CardFooter>
</Card>;
```

## Composition [#composition]

```text
Card
├── CardHeader
│   ├── CardTitle
│   └── CardDescription
├── CardContent
└── CardFooter
```

## API reference [#api-reference]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `variant` | `"outline" \| "elevated" \| "plain"` | `"outline"` — a stored name the union does not carry | the edge and lift in **Treatments** below |
| `className` | `string` | none | a recipe class string joined after the component's own, so it wins a conflict |
| `style` | `StyleDesc` | none | merged last, after the compiled recipe |
| `children` | `PartChildren` | none | the parts; text and numbers are rejected for every part that hosts parts |

**Treatments**

| Treatment | Edge | Lift |
| --------- | ---- | ---- |
| `outline` | 1px `border` | none |
| `elevated` | none | `elevation.sm` |
| `plain` | none | none |

All three paint the `card` fill and a fixed 8px corner; `outline` edges in
`border-input`, compiled to `border`.

---

# Carousel

Source: https://gpuixui.sudokw.com/components/carousel

Discrete slide stepping, a dot per slide, arrow keys

<ComponentPreview name="carousel-workflow" />

## Installation [#installation]

<Install packageName="@gpuixui/components" importName="Carousel" />
<ComponentSource name="carousel" file="packages/components/src/carousel.tsx" />

## Usage [#usage]

```tsx
import {
  Carousel,
  CarouselControl,
  CarouselIndicators,
  CarouselSlide,
  CarouselTrack,
} from "@gpuixui/components";
import { useState } from "react";

export const WorkspacePreviews = () => {
  const [index, setIndex] = useState(0);

  return (
    <Carousel label="Workspace previews" onValueChange={setIndex} value={index}>
      <CarouselTrack>
        <CarouselSlide>Overview</CarouselSlide>
        <CarouselSlide>Activity</CarouselSlide>
        <CarouselSlide>Members</CarouselSlide>
      </CarouselTrack>
      <CarouselControl direction="previous" />
      <CarouselControl direction="next" />
      <CarouselIndicators />
    </Carousel>
  );
};
```

## Composition [#composition]

```text
Carousel
├── CarouselTrack
│   └── CarouselSlide
├── CarouselControl
└── CarouselIndicators
```

## API reference [#api-reference]

### `Carousel` [#carousel]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `label` | `string` | — | the region's accessible name; required |
| `value` | `number` | — | controlled slide index |
| `defaultValue` | `number` | `0` | the opening slide when uncontrolled |
| `onValueChange` | `(value: number) => void` | none | the next index |
| `loop` | `boolean` | `false` | wraps past both ends and keeps both controls live |
| `className` | `string` | — | joined last |
| `children` | `ReactNode` | none | the track and the controls, directly inside |

### `CarouselTrack` [#carouseltrack]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `children` | `ReactNode` | none | the slides, as direct children |
| `className` | `string` | — | joined last |

### `CarouselSlide` [#carouselslide]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `children` | `ReactNode` | none | the slide's content |
| `style` | `StateStyle<CarouselSlideState>` | — | `{ active, index }`, merged last |
| `className` | `string` | — | joined last |

### `CarouselControl` [#carouselcontrol]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `direction` | `"previous" \| "next"` | — | which way it steps; required |
| `label` | `string` | `"Previous slide"` / `"Next slide"` | the accessible name |
| `disabled` | `boolean` | `false` | adds to the edge rule; never removes it |

### `CarouselIndicators` [#carouselindicators]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `label` | `string` | `"Choose a slide"` | the dot group's accessible name |
| `style` | `StateStyle<CarouselIndicatorsState>` | — | `{ active, count }`, merged last |
| `className` | `string` | — | joined last |

---

# Chat

Source: https://gpuixui.sudokw.com/components/chat

A conversation with a following transcript

<ComponentPreview name="chat-demo" />

Chat is the whole conversation: a fixed header, the flexible transcript and a
fixed composer. The transcript is a `MessageScroller`, each turn is a `Message`
around a `Bubble`, and the field is `ChatComposer`. The transport is yours; the
status machine is shared so the composer and the header cannot disagree.

Every turn wears a bubble — the reader's on the `default` fill and the end edge,
the agent's `muted` on the start — and the row supplies the avatar, author and
timestamp. Only the row that starts a run paints its avatar and meta line; the
rows after it are a `MessageGroup` (6px apart) whose bubbles name `group="first"`
and `group="last"` so their inner corners join.

## Installation [#installation]

```bash
nub add @gpuixui/components
```

## Usage [#usage]

```tsx
import {
  Bubble,
  BubbleContent,
  ChatComposer,
  ChatHeader,
  ChatMessages,
  ChatRoot,
  Message,
  MessageAvatar,
  MessageContent,
  MessageHeader,
  chatMove,
} from "@gpuixui/components";

<ChatRoot
  status={status}
  onStatusChange={setStatus}
  onSubmit={send}
  onStop={stop}
  onRetry={retry}
>
  <ChatHeader title="Release thread" />
  <ChatMessages>
    {messages.map((message) => (
      <Message key={message.id} variant={message.role} timestamp={message.at}>
        <MessageAvatar />
        <MessageContent streaming={message.streaming}>
          <MessageHeader />
          <Bubble
            align={message.role === "user" ? "end" : "start"}
            variant={message.role === "user" ? "default" : "muted"}
            group={message.group}
          >
            <BubbleContent>{message.body}</BubbleContent>
          </Bubble>
        </MessageContent>
      </Message>
    ))}
  </ChatMessages>
  <ChatComposer hint="Enter sends · Shift+Enter adds a line" />
</ChatRoot>;
```

## Composition [#composition]

```text
ChatRoot
├── ChatHeader
├── ChatMessages        the MessageScroller
│   ├── MessageScrollerViewport
│   │   └── MessageScrollerContent
│   │       └── MessageScrollerItem
│   └── MessageScrollerJumpToLatest
└── ChatComposer
```

## The fixed rows [#the-fixed-rows]

`ChatRoot` is a column whose middle grows. `ChatHeader` and `ChatComposer` do
not shrink; `ChatMessages` is `flex: 1 1 0` with `min-height: 0`, so a row
arriving, a reply streaming or the jump control appearing changes nothing above
or below the transcript. Give `ChatRoot` a bounded height — directly, or through
a sized flex parent — because the transcript needs one to scroll.

The passed-in `ChatMessages` children are rows. Wrap each turn in a `Message`
(or a `MessageGroup` for consecutive rows from one sender). A `Bubble` is always
a child of `MessageContent`; the message never builds one.

## Status [#status]

The four states are `idle`, `submitting`, `streaming` and `error`, and
`chatMove` is the only rule set. Send is refused while a reply is open, the
refused draft stays in the field, Stop emits the stop intent, and Escape stops a
reply. The header announces the state; the failure sentence replaces the status
line in place, so a failed reply does not take height from the transcript.

## While a reply is open [#while-a-reply-is-open]

- Send is replaced by Stop.
- Enter still arrives as the field's image submit; the machine refuses it, so
  the draft is kept.
- A reply's row can grow token by token; the transcript follows it only while
  the reader is at the end.

## Failed replies [#failed-replies]

The failure copy is one line in the header with the full sentence in
`aria-description`; Retry is beside it. It used to be a row between the viewport
and the composer, which shrank the viewport when it appeared — the layout shift
this release removes.

## API [#api]

| Part | Renders | Props |
| ---- | ------- | ----- |
| `ChatRoot` | `role="region"` named by `label` | `status?`, `defaultStatus?`, `onStatusChange?`, `onSubmit` (required), `onStop?`, `onRetry?`, `error?`, `label?`, `className?`, `children` |
| `ChatHeader` | a fixed row: title, status/error, actions | `title?`, `description?`, `actions?`, `className?` |
| `ChatMessages` | the scroller, the empty panel and the jump rail | `empty?`, `emptyTitle?`, `emptyDescription?`, `className?`, `children` |
| `ChatComposer` | a field and its Send/Stop control | `value?`, `defaultValue?`, `onValueChange?`, `label?`, `placeholder?`, `submitLabel?`, `stopLabel?`, `hint?`, `attachments?`, `disabled?`, `className?`, `style?` |

`ChatMessages` is also the transcript's public seam: render
`MessageScrollerItem` rows inside it (through `Message`) and pass
`MessageScrollerItem scrollAnchor` on a turn's first row if you want that turn
placed near the top.

---

# Checkbox

Source: https://gpuixui.sudokw.com/components/checkbox

An independent yes/no with an optional mixed state

<ComponentPreview name="checkbox-workflow" />

## Installation [#installation]

<Install packageName="@gpuixui/primitives" importName="Checkbox" />
<ComponentSource
  name="checkbox"
  file="packages/primitives/src/components/Checkbox.tsx"
/>

## Usage [#usage]

```tsx
import { Checkbox } from "@gpuixui/primitives";
import { useState } from "react";

export const Digest = () => {
  const [email, setEmail] = useState(true);

  return (
    <Checkbox
      checked={email}
      label="Email notifications"
      onCheckedChange={setEmail}
    />
  );
};
```

## Composition [#composition]

```text
Checkbox
└── CheckboxIndicator

CheckboxGroup
└── Checkbox
    └── CheckboxIndicator
```

## API reference [#api-reference]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `checked` | `boolean` | — | controlled state; omit to let the box keep its own |
| `defaultChecked` | `boolean` | `false` | initial state when uncontrolled |
| `onCheckedChange` | `(next: boolean) => void` | none | the next boolean, only when it changed |
| `onChange` | `(next: boolean) => void` | none | deprecated alias for `onCheckedChange`; the new name wins when both are passed |
| `children` | `ReactNode` | the default glyph | the mark's content |
| `indeterminate` | `boolean` | `false` | paints a dash and announces `mixed`; overrides `checked` |
| `disabled` | `boolean` | `false` | refuses pointer and keys and leaves the tab order |
| `invalid` | `boolean` | `false` | the empty box takes the destructive edge |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | the drawing's side from `iconSize`; the target stays 24px |
| `accent` | `"primary" \| "destructive"` | `"primary"` | the fill and mark roles |
| `label` | `string` | none | the accessible name; a visible `Label` does not supply it |
| `description` | `string` | none | announced help (`aria-description`); wins over a tooltip's text |
| `className` | `string` | — | joined after the recipe, so it wins conflicts |
| `style` | `StateStyle<CheckboxState>` | — | resolved against the live state and merged last |
| `testId` | `string` | — | stable locator |
| `ref` / `aria-id` / `onLayout` | host address | none | the box is the addressed element: focus it, measure it, and name it for automation |
| `onMouseEnter` / `onMouseLeave` / `aria-description` | the tooltip trigger pair and its words | none | forwarded to the box, so a checkbox can be a `Tooltip` trigger; the tip's words arrive as `aria-description` |
| `onClick` / `onKeyDown` / `onKeyUp` / `onFocus` / `onBlur` | host handlers | none | composed with the box's own; yours runs first |

### `CheckboxIndicator` [#checkboxindicator]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `children` | `ReactNode` | the default check/dash | the glyph |
| `className` | `string` | — | compiled through the recipe registry after the part's rules |
| `style` | `StyleDesc` | — | merged last |

---

# Code block

Source: https://gpuixui.sudokw.com/components/code-block

Source or output, tokenized by @tanstack/highlight

<ComponentPreview name="code-block-demo" />

## Usage [#usage]

```tsx
import { CodeBlock } from "@gpuixui/components/code-block";

<CodeBlock
  code={source}
  title="src/app.tsx"
  language="tsx"
  lineNumbers
/>;
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `code` | `string` | — |
| `title` | `string` | falls back to `path` |
| `path` | `string` | — |
| `language` | `string` | path's extension |
| `lineNumbers` | `boolean` | `false` |
| `height` | `number` | — |
| `level` | `SurfaceLevel` | `"normal"` |
| `emptyLabel` | `string` | `"No code"` |
| `copyLabel` | `string` | `"Copy"` |
| `copiedLabel` | `string` | `"Copied"` |
| `onCopy` | `(code: string) => void` | — |
| `className` | `string` | — |
| `style` | `StateStyle<CodeBlockState>` | — |

---

# Collapsible

Source: https://gpuixui.sudokw.com/components/collapsible

One section that reveals its body on demand

<ComponentPreview name="collapsible-workflow" />

For several sections at once, use [Accordion](/components/accordion); it prerenders its bodies.

## Installation [#installation]

<Install packageName="@gpuixui/components" importName="Collapsible" />
<ComponentSource name="collapsible" file="packages/components/src/collapsible.tsx" />

## Usage [#usage]

```tsx
import {
  Collapsible,
  CollapsibleContent,
  CollapsibleTrigger,
} from "@gpuixui/components/collapsible";

<Collapsible defaultOpen={false}>
  <CollapsibleTrigger>Advanced options</CollapsibleTrigger>
  <CollapsibleContent>
    Retry budget: 3 attempts
  </CollapsibleContent>
</Collapsible>;
```

## Composition [#composition]

```text
Collapsible
├── CollapsibleTrigger
└── CollapsibleContent
```

## API reference [#api-reference]

| Part | Prop | Type | Default | Consequence |
| ---- | ---- | ---- | ------- | ----------- |
| `Collapsible` | `open` | `boolean` | — | controlled state; omit it to let the root keep its own |
| `Collapsible` | `defaultOpen` | `boolean` | `false` | the uncontrolled starting state, open on the first frame |
| `Collapsible` | `onOpenChange` | `(open: boolean) => void` | none | the next state the trigger reports |
| `Collapsible` | `children` | `CollapsibleTrigger` and `CollapsibleContent` | — | the direct parts; a misplaced family part throws |
| `CollapsibleTrigger` | `disabled` | `boolean` | `false` | leaves the tab order, dims, and refuses click, `Enter` and `Space` |
| `CollapsibleTrigger` | `className` | `string` | — | joined after the recipe, so it wins conflicts |
| `CollapsibleTrigger` | `style` | `StateStyle<CollapsibleTriggerState>` | the recipe | resolved against the live state and merged last |
| `CollapsibleContent` | `className` | `string` | — | joined after the recipe on the measured box |
| `CollapsibleContent` | `children` | `ReactNode` | — | the body; mounted only while open, and during the exit |

---

# Color picker

Source: https://gpuixui.sudokw.com/components/color-picker

A swatch that opens the saturation, hue and alpha rails

<ComponentPreview name="color-picker-workflow" />

<ComponentPreview name="color-picker-states" />

## Installation [#installation]

<Install packageName="@gpuixui/components" importName="ColorPicker" />
<ComponentSource
  name="colorPicker"
  file="packages/components/src/color-picker.tsx"
/>

## Usage [#usage]

```tsx
import { useState } from "react";
import { ColorPicker } from "@gpuixui/components";

const [accent, setAccent] = useState("#2F6BFF");

<ColorPicker
  label="Accent colour"
  background="#FFFFFF"
  onValueChange={setAccent}
  swatches={["#2F6BFF", "#2563EB", "#0D9488", "#D97706"]}
  value={accent}
/>;
```

## API reference [#api-reference]

### `ColorPicker` [#colorpicker]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `label` | `string` | — | the trigger and panel's name; a blank value reads as `"Color picker"` so the trigger and the `<label> hex value` field are always named |
| `value` | `string` | — | the controlled colour; `undefined` is uncontrolled, and a stored value that is not text means uncontrolled |
| `defaultValue` | `string` | `"#000000"` | the uncontrolled starting colour; a stored default that is not text paints `"#000000"` |
| `onValueChange` | `(hex: string) => void` | — | every committed colour, as uppercase hex with two alpha digits when not opaque |
| `background` | `string` | the theme's page | the surface the contrast readout measures against; an unreadable value leaves the readout at `1.00:1` |
| `swatches` | `ReadonlyArray<string>` | six theme roles | the preset row, in order; a stored value that is not a list paints the theme's defaults |
| `disabled` | `boolean` | `false` | the trigger leaves the tab order and no part accepts a change |
| `className` | `string` | — | compiled through `@gpuixui/tw`, joined after the trigger's recipe |
| `style` | `StateStyle<ColorPickerState>` | — | resolved against `{ disabled, valid }`, merged last |
| `testId` | `string` | — | the root's locator; the trigger uses it, and its parts derive `-swatch`, `-panel`, `-done`, `-area`, `-hue`, `-alpha`, `-hex`, `-error` and `-preset` (each preset adds `-<index>`) |

---

# Color swatches

Source: https://gpuixui.sudokw.com/components/color-swatches

One colour chosen from a fixed row

<ComponentPreview name="color-swatches-demo" />

## Usage [#usage]

```tsx
import { ColorSwatches } from "@gpuixui/components/color-swatches";

<ColorSwatches
  label="Accent colour"
  colors={["#3B82F6", "#8B5CF6", "#EC4899"]}
  value={accent}
  onValueChange={setAccent}
/>;
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `label` | `string` — the group's accessible name | — |
| `colors` | `ReadonlyArray<string>` | — |
| `value` | `string` — the chosen colour; it wears the ring | — |
| `onValueChange` | `(color: string) => void` | — |
| `size` | `number` — one swatch's diameter | `16` |

Use [Color picker](/components/color-picker) when any colour is allowed.

---

# Combobox

Source: https://gpuixui.sudokw.com/components/combobox

A searchable single- or multi-select with ranked options

<ComponentPreview name="combobox-workflow" />

<ComponentPreview name="combobox-multiple" />

## Installation [#installation]

<Install packageName="@gpuixui/components" importName="Combobox" />
<ComponentSource name="combobox" file="packages/components/src/combobox.tsx" />

## Usage [#usage]

```tsx
import { useState } from "react";
import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxList,
  ComboboxTrigger,
} from "@gpuixui/components/combobox";

const people = [
  {
    value: "ada",
    label: "Ada Lovelace",
    description: "Engineering · compilers",
  },
  {
    value: "grace",
    label: "Grace Hopper",
    description: "Platform · releases",
  },
];

export const ReviewerField = () => {
  const [reviewer, setReviewer] = useState<string | null>("ada");

  return (
    <Combobox
      onValueChange={(value) =>
        setReviewer(typeof value === "string" ? value : null)
      }
      options={people}
      value={reviewer ?? undefined}
    >
      <ComboboxTrigger label="Reviewer" placeholder="Choose a reviewer…" />
      <ComboboxContent>
        <ComboboxInput label="Search reviewers" />
        <ComboboxList label="Reviewers" />
        <ComboboxEmpty />
      </ComboboxContent>
    </Combobox>
  );
};
```

## Composition [#composition]

```text
Combobox
├── ComboboxTrigger
└── ComboboxContent
    ├── ComboboxInput
    ├── ComboboxList
    │   └── ComboboxItem
    └── ComboboxEmpty
```

## API reference [#api-reference]

### Combobox [#combobox]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `options` | `ReadonlyArray<ComboboxOption>` — `{ value, label, description?, disabled? }` | required; a stored value that is not a list paints no rows |
| `value` | `string \| ReadonlyArray<string>` — controlled | uncontrolled; a stored value that is neither text nor a list means uncontrolled |
| `defaultValue` | `string \| ReadonlyArray<string>` — initial selection when uncontrolled | — |
| `onValueChange` | `(value: string \| null \| ReadonlyArray<string>) => void` | — |
| `multiple` | `boolean` | `false` |
| `disabled` | `boolean` | `false` |
| `onQueryChange` | `(query: string) => void` — every search the popup runs, including the empty one it opens with | — |
| `shouldFilter` | `boolean` — rank `options` locally; `false` keeps the caller's order | `true` |
| `loading` | `boolean` — the caller's fetch is in flight; an empty list says `Searching…` | `false` |
| `onCreate` | `(query: string) => void` — single mode only; the caller adds the option | — |
| `createLabel` | `(query: string) => string` | `Create "…"` |
| `children` | parts — `ComboboxTrigger`, `ComboboxContent` | — |

### ComboboxTrigger [#comboboxtrigger]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `placeholder` | `string` — shown while nothing is selected | `"Select…"` |
| `label` | `string` — the trigger's accessible name | — |
| `className` | `string` — joined after the trigger recipe | — |
| `testId` | `string` | `"combobox-trigger"` |

### ComboboxContent [#comboboxcontent]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `side` | `"top" \| "right" \| "bottom" \| "left"` | `"bottom"` — a stored name the union does not carry |
| `align` | `"start" \| "center" \| "end"` | `"start"` — a stored name the union does not carry |
| `sideOffset` | `number` — the gap to the trigger | `4` |
| `alignOffset` | `number` — added on top of the measured centre correction | `0` |
| `className` | `string` — joined after the surface recipe | — |
| `children` | parts — `ComboboxInput`, `ComboboxList`, `ComboboxEmpty` | — |

### ComboboxInput [#comboboxinput]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `placeholder` | `string` | `"Search…"` |
| `label` | `string` | `"Search options"` |

### ComboboxList [#comboboxlist]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `label` | `string` — the listbox's accessible name | `"Options"` |
| `itemStyle` | `StateStyle<ComboboxItemState>` — resolved per row | the recipe |

### ComboboxItem [#comboboxitem]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `value` | `string` — the label and description are read from the root's option | required |
| `style` | `StateStyle<ComboboxItemState>` — `{ selected, highlighted, disabled }` | the recipe |

### ComboboxEmpty [#comboboxempty]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `children` | `ReactNode` | `No matches` |

---

# Command menu

Source: https://gpuixui.sudokw.com/components/command-menu

A searchable action list, the ⌘K palette

<ComponentPreview name="command-menu-demo" />

## Installation [#installation]

<Install packageName="@gpuixui/components" importName="CommandMenu" />
<ComponentSource
  name="commandMenu"
  file="packages/components/src/command-menu.tsx"
/>

## Usage [#usage]

```tsx
import {
  CommandMenu,
  CommandMenuEmpty,
  CommandMenuInput,
  CommandMenuList,
} from "@gpuixui/components/command-menu";

const actions = [
  {
    id: "new-file",
    label: "New file",
    group: "File",
    shortcut: "⌘N",
    perform: newFile,
  },
  {
    id: "toggle-sidebar",
    label: "Toggle sidebar",
    group: "View",
    shortcut: "⌘B",
    perform: toggleSidebar,
  },
];

<CommandMenu open={open} onOpenChange={setOpen} actions={actions}>
  <CommandMenuInput placeholder="Type a command…" />
  <CommandMenuList />
  <CommandMenuEmpty>No matching commands</CommandMenuEmpty>
</CommandMenu>;
```

## Composition [#composition]

```text
CommandMenu
├── CommandMenuInput
├── CommandMenuList
│   └── CommandMenuItem
└── CommandMenuEmpty
```

## API reference [#api-reference]

| Part | Renders | Props |
| ---- | ------- | ----- |
| `CommandMenu` | the composed `Dialog` surface | `open` (required), `onOpenChange` (required), `actions` (required; a stored value that is not a list paints the empty state), `recents` (a stored value that is not a list carries no recents), `filter`, `children` |
| `CommandMenuInput` | host `<input>` | `placeholder` (default `"Type a command…"`; an empty field announces it as `aria-description`), `label` (default `"Search commands"`), `className` |
| `CommandMenuList` | scrolling match column | `className`; the root's ranked matches are its content |
| `CommandMenuItem` | one runnable row | `action` (required), `className` |
| `CommandMenuEmpty` | the no-match message | `children` (default `No matching commands`), `className` |

---

# Confirmation dialog

Source: https://gpuixui.sudokw.com/components/confirm-dialog

The safe workflow for an action that cannot be undone

<ComponentPreview name="confirm-dialog-demo" />

<ComponentPreview name="confirm-dialog-states" />

## Installation [#installation]

<Install packageName="@gpuixui/components" importName="ConfirmDialog" />
<ComponentSource name="confirmDialog" file="packages/components/src/confirm-dialog.tsx" />

## Usage [#usage]

```tsx
import {
  Alert,
  AlertContent,
  AlertDescription,
  AlertTitle,
} from "@gpuixui/components/alert";
import { ConfirmDialog } from "@gpuixui/components/confirm-dialog";
import { Button } from "@gpuixui/primitives";
import { useState } from "react";

export const ArchiveProject = () => {
  const [open, setOpen] = useState(false);
  const [saving, setSaving] = useState(false);
  const [error, setError] = useState<string | null>(null);

  const archive = async () => {
    setSaving(true);
    setError(null);
    try {
      await archiveProject();
      setOpen(false);
    } catch {
      setError("The workspace service timed out. Nothing was archived.");
    } finally {
      setSaving(false);
    }
  };

  return (
    <>
      <Button variant="destructive" onClick={() => setOpen(true)}>
        Archive project
      </Button>
      <ConfirmDialog
        open={open}
        onOpenChange={setOpen}
        title="Archive this project?"
        description="The project leaves everyone's sidebar. Its 18 open tasks stay attached and no files are deleted."
        confirmLabel={error === null ? "Archive project" : "Try again"}
        tone="danger"
        loading={saving}
        onConfirm={() => void archive()}
      >
        {error === null ? null : (
          <Alert tone="danger">
            <AlertContent>
              <AlertTitle>Archive failed</AlertTitle>
              <AlertDescription>{error}</AlertDescription>
            </AlertContent>
          </Alert>
        )}
      </ConfirmDialog>
    </>
  );
};
```

## Composition [#composition]

```text
ConfirmDialog
├── DialogContent
│   ├── DialogHeader
│   └── footer (actions)
└── children
```

## API reference [#api-reference]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `open` | `boolean` (required) | — | the controlled open state |
| `onOpenChange` | `(open: boolean) => void` (required) | — | reports Cancel, Escape and an outside press |
| `title` | `string` (required) | — | the dialog's accessible name and its heading |
| `description` | `string` (required) | — | the consequence, as one paragraph |
| `confirmLabel` | `string` | `"Confirm"` | the confirm action's label |
| `cancelLabel` | `string` | `"Cancel"` | the cancel action's label |
| `tone` | `"default" \| "danger"` | `"default"` | `"danger"` paints the destructive action variant |
| `loading` | `boolean` | `false` | disables both actions, paints the busy mark, and ignores Escape and an outside press |
| `onConfirm` | `() => void` (required) | — | runs on activation; never closes the dialog |
| `children` | `ReactNode` | — | extra body between the description and the actions |

---

# Context menu

Source: https://gpuixui.sudokw.com/components/context-menu

Menu rows at the pointer, or opened from the keyboard

<ComponentPreview name="context-menu-workflow" />

## Installation [#installation]

<Install packageName="@gpuixui/components" importName="ContextMenu" />
<ComponentSource name="contextMenu" file="packages/components/src/context-menu.tsx" />

## Usage [#usage]

```tsx
import {
  ContextMenu,
  ContextMenuCheckboxItem,
  ContextMenuContent,
  ContextMenuItem,
  ContextMenuSeparator,
  ContextMenuSub,
  ContextMenuSubContent,
  ContextMenuSubTrigger,
  ContextMenuTrigger,
} from "@gpuixui/components/context-menu";

<ContextMenu>
  <ContextMenuTrigger>
    <text>release-notes.md</text>
  </ContextMenuTrigger>
  <ContextMenuContent label="Project actions">
    <ContextMenuItem onSelect={open}>Open</ContextMenuItem>
    <ContextMenuItem onSelect={rename}>Rename</ContextMenuItem>
    <ContextMenuItem disabled>Move to trash</ContextMenuItem>
    <ContextMenuSub>
      <ContextMenuSubTrigger>Share</ContextMenuSubTrigger>
      <ContextMenuSubContent label="Share">
        <ContextMenuItem onSelect={copyLink}>Copy link</ContextMenuItem>
        <ContextMenuItem onSelect={email}>Email</ContextMenuItem>
      </ContextMenuSubContent>
    </ContextMenuSub>
    <ContextMenuSeparator />
    <ContextMenuCheckboxItem
      checked={showHidden}
      onCheckedChange={setShowHidden}
    >
      Show hidden files
    </ContextMenuCheckboxItem>
  </ContextMenuContent>
</ContextMenu>;
```

## Composition [#composition]

```text
ContextMenu
├── ContextMenuTrigger
└── ContextMenuContent
    ├── ContextMenuItem
    ├── ContextMenuCheckboxItem
    ├── ContextMenuRadioGroup
    │   └── ContextMenuRadioItem
    ├── ContextMenuSeparator
    ├── ContextMenuLabel
    ├── ContextMenuGroup
    └── ContextMenuSub
        ├── ContextMenuSubTrigger
        └── ContextMenuSubContent
```

## API reference [#api-reference]

### `ContextMenu` [#contextmenu]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `open` | `boolean` | uncontrolled | controlled open state |
| `defaultOpen` | `boolean` | `false` | the initial state when uncontrolled |
| `onOpenChange` | `(open: boolean, details: { reason }) => void` | none | reports the next state and why it changed: `trigger-press`, `item-press`, `escape-key`, `outside-press`, `focus-out` or `pointer-leave`; a controlled menu waits for the caller |
| `children` | parts | none | `ContextMenuTrigger` and `ContextMenuContent` |

### `ContextMenuTrigger` [#contextmenutrigger]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `disabled` | `boolean` | `false` | no aux click, no `Shift+F10`, out of the tab order, dimmed |
| `children` | nodes | none | the area the reader presses |
| `style` | host style | none | merged last over the card-like box |

### `ContextMenuContent` [#contextmenucontent]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `label` | `string` | `"Context menu"` | the surface's accessible name |
| `children` | parts | none | rows, groups, labels, separators and submenus |
| `className` | `string` | none | compiled through `@gpuixui/tw` and joined after the recipe |
| `style` | host style | none | merged last on the surface |

### `ContextMenuItem` and `ContextMenuCheckboxItem` [#contextmenuitem-and-contextmenucheckboxitem]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `onSelect` | `() => void` | none | runs once when the row is activated |
| `disabled` | `boolean` | `false` | skipped by arrows and type-ahead; paints the measured disabled pair |
| `tone` | `"default" \| "destructive"` | `"default"` — a stored name the union does not carry | a destructive row paints the status tone's readable role |
| `leading` / `trailing` | `ReactNode` | none | slots before and after the label |
| `textValue` | `string` | the label | the text type-ahead searches |
| `closeOnSelect` | `boolean` | `true` | whether activation closes the menu |
| `checked` | `boolean` | none | the checkbox row's state (required on `ContextMenuCheckboxItem`) |
| `onCheckedChange` | `(checked: boolean) => void` | none | reported when the checkbox row toggles (required) |
| `className` | `string` | none | compiled through `@gpuixui/tw` and joined after the recipe |
| `style` | `MenuItemState` callback | none | `{ disabled, highlighted }`, merged after the row's roles |

### `ContextMenuRadioGroup` and `ContextMenuRadioItem` [#contextmenuradiogroup-and-contextmenuradioitem]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `value` | `string` | none | the chosen row's value (required on the group) |
| `onValueChange` | `(value: string) => void` | none | reported with a row's value when it is chosen, never the current one (required) |
| `label` | `string` | none | the choice's accessible name; a painted `ContextMenuLabel` does not name the group |
| `className` | `string` | none | compiled through `@gpuixui/tw`, joined after the recipe |
| `children` | parts | none | the group's `ContextMenuRadioItem` rows |
| `value` | `string` | none | this row's value inside the group (required on `ContextMenuRadioItem`) |
| `closeOnSelect` / `disabled` / `tone` / `leading` / `trailing` / `textValue` | as the action row | — | the row's own slots, tone and type-ahead key |
| `style` | `MenuRadioItemState` callback | none | `{ checked, disabled, highlighted }`, merged after the row's roles |

### `ContextMenuSub`, `ContextMenuSubTrigger`, `ContextMenuSubContent` [#contextmenusub-contextmenusubtrigger-contextmenusubcontent]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `children` | parts | none | `ContextMenuSub` holds a trigger and its content |
| `label` | `string` | none | the second level's accessible name |
| `disabled` / `leading` / `trailing` / `textValue` | the row surface | — | the sub trigger is an ordinary row that opens the second level |
| `className` / `style` | host | none | merged last |

---

# Copy button

Source: https://gpuixui.sudokw.com/components/copy-button

An icon action that copies a value and acknowledges it

<ComponentPreview name="copy-button-demo" />

## Usage [#usage]

```tsx
import { useState } from "react";
import { CopyButton } from "@gpuixui/components";

const [mirror, setMirror] = useState("");

<CopyButton text={token} onCopy={setMirror} />;
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `text` | `string` | — |
| `onCopy` | `(text: string) => void` | — |
| `label` | `string` | `"Copy"` |
| `copiedLabel` | `string` | `"Copied"` |
| `acknowledgeMs` | `number` | `1200` |
| `size` | `"sm" \| "md" \| "lg"` | `"sm"` |
| `disabled` | `boolean` | `false` |
| `color` | `string` | `mutedForeground` |
| `level` | `SurfaceLevel` | `"fast"` |
| `className` | `string` | — |
| `style` | `StateStyle<CopyButtonState>` | — |

---

# Countdown

Source: https://gpuixui.sudokw.com/components/countdown

A remaining duration as clock text

<ComponentPreview name="countdown-demo" />

## Usage [#usage]

```tsx
import { Countdown } from "@gpuixui/components";

<Countdown remainingMs={90_000} label="Offer ends in" />;
// 01:30
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `remainingMs` | `number` (required) | — (negative or unreadable renders `00:00`, expired) |
| `label` | `string` | — |
| `showDays` | `boolean` | `false` |
| `style` | `StateStyle<CountdownState>` | — |
| `className` | `string` | — |

---

# Counting number

Source: https://gpuixui.sudokw.com/components/counting-number

A number that counts to its value

<ComponentPreview name="counting-number-demo" />

## Usage [#usage]

```tsx
import { CountingNumber } from "@gpuixui/components";

<CountingNumber value={1284} from={0} role="display" />;
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `value` | `number` (required) | — |
| `from` | `number` | `value` |
| `durationMs` | `number` | `320` |
| `decimals` | `number` | `0` |
| `format` | `(value: number) => string` | — |
| `label` | `string` | the target's text |
| `role` | `TextRole` | `"body"` |
| `className` | `string` | — |
| `style` | `StateStyle<CountingNumberState>` | — |

---

# Date picker

Source: https://gpuixui.sudokw.com/components/date-picker

A day or a span of days, chosen from a Calendar

<ComponentPreview name="date-picker-workflow" />

<ComponentPreview name="date-picker-states" />

<ComponentPreview name="date-picker-range" />

<ComponentPreview name="date-picker-presets" />

## Installation [#installation]

<Install packageName="@gpuixui/components" importName="DatePicker" />
<ComponentSource name="datePicker" file="packages/components/src/date-picker.tsx" />

## Usage [#usage]

```tsx
import {
  DatePicker,
  DatePickerCalendar,
  DatePickerContent,
  DatePickerTrigger,
} from "@gpuixui/components/date-picker";
import { useState } from "react";

export const DeploymentWindow = () => {
  const [due, setDue] = useState<string | null>("2026-10-30");

  return (
    <DatePicker
      clearable
      max="2026-12-18"
      min="2026-10-26"
      onValueChange={setDue}
      today="2026-10-22"
      value={due}
    >
      <DatePickerTrigger label="Deployment date" />
      <DatePickerContent>
        <DatePickerCalendar />
      </DatePickerContent>
    </DatePicker>
  );
};
```

A span is `mode="range"`: the value is `{ from, to }`, and it closes on the second day.

```tsx
<DatePicker
  mode="range"
  clearable
  onValueChange={setWindow}
  today="2026-10-22"
  value={window}
>
  <DatePickerTrigger label="Booking window" />
  <DatePickerContent>
    <DatePickerCalendar label="Booking calendar" />
  </DatePickerContent>
</DatePicker>
```

## Composition [#composition]

```text
DatePicker
├── DatePickerTrigger
└── DatePickerContent
    └── DatePickerCalendar
```

## API reference [#api-reference]

### `DatePicker` [#datepicker]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `mode` | `"single" \| "range"` | `"single"` | selects the value shape `value` and `onValueChange` speak |
| `value` | `string \| null` · `{ from, to } \| null` | none | the controlled value; `undefined` makes the picker uncontrolled |
| `defaultValue` | `string \| null` · `{ from, to } \| null` | `null` | the opening value when uncontrolled |
| `onValueChange` | `(value \| range \| null) => void` | none | the chosen day, the span, or `null` from Clear |
| `weekStartsOn` | `0 \| 1` | `1` | the grid's first column |
| `min` | `string` | unbounded | the first selectable ISO day, inclusive |
| `max` | `string` | unbounded | the last selectable ISO day, inclusive |
| `clearable` | `boolean` | `false` | adds the Clear row while a value is set |
| `disabled` | `boolean` | `false` | leaves the tab order and does not open the surface |
| `today` | `string` | the runtime clock | the ISO day the grid marks as today |
| `numberOfMonths` | `1 \| 2` | `1`, or `2` in range mode | months painted side by side |
| `showOutsideDays` | `boolean` | `true` | paints the neighbouring months' days |
| `captionLayout` | `"label" \| "dropdown"` | `"label"` | a caption, or month and year jump controls |
| `fromYear` / `toYear` | `number` | today ± 10 | the years a dropdown may reach |
| `children` | `ReactNode` | none | the trigger and the content, directly inside |

### `DatePickerTrigger` [#datepickertrigger]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `placeholder` | `string` | `"Pick a date"` | the text painted while no value is set |
| `label` | `string` | — | the trigger's accessible name (the caret is decorative) |
| `variant` | `"primary" \| "secondary" \| "ghost" \| "danger"` | `"secondary"` | the trigger's fill and label role |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | the control height the trigger takes from the theme's density |
| `disabled` | `boolean` | `false` | adds to the root's disabled rule; never removes it |
| `className` | `string` | — | joined after the recipe, so it wins conflicts |
| `testId` | `string` | `"date-picker-trigger"` | the trigger's test identity |
| `onActivate` | `(event) => void` | — | the action's one handler: it opens the surface from a press or an activating key |
| `onClick` | `(event) => void` | — | the deprecated alias; only runs when `onActivate` is absent |

### `DatePickerContent` [#datepickercontent]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `side` | `"top" \| "right" \| "bottom" \| "left"` | `"bottom"` | where the surface anchors relative to the trigger |
| `align` | `"start" \| "center" \| "end"` | `"start"` | the surface's alignment on that side |
| `sideOffset` | `number` | `6` | the gap between trigger and surface, in pixels |
| `className` | `string` | — | joined after the recipe |
| `children` | `ReactNode` | none | the calendar, directly inside |

### `DatePickerCalendar` [#datepickercalendar]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `label` | `string` | `"Calendar"` | the grid's accessible name |

---

# Diagram

Source: https://gpuixui.sudokw.com/components/diagram

A Mermaid source, drawn by Pele

A **diagram** is a drawing, and this is the component that draws one. You give
it a Mermaid source and it renders the diagram, themed in the library's own
colours.

<ComponentPreview name="diagram-demo" />

The renderer is [Pele](https://pele.run) — a zero-dependency Mermaid renderer
that needs no DOM. Measured in a plain Node process, with `typeof document` and
`typeof window` both `undefined`, a flowchart rendered to a 403×64 SVG.

The drawing travels as one image, so the whole diagram is **one element** in
the frame.

## Usage [#usage]

```tsx
import { Diagram } from "@gpuixui/components/diagram";

<Diagram
  aria-label="The render path"
  source={"flowchart LR\n  A[Author] --> B[Component]"}
  caption="How a component becomes a picture"
/>;
```

## The source is the API [#the-source-is-the-api]

A diagram is written in Mermaid, and the fence is the whole interface:

````mdx
```mermaid
flowchart LR
  A[Author] --> B[Component]
```
````

Every diagram type Mermaid 12.1 knows is supported, because Pele renders all of
them. A source the parser refuses paints the parser's sentence in the
drawing's place — the reader sees what went wrong rather than an empty frame.

## Theming [#theming]

Pele writes its palette as CSS custom properties. A raster cannot read them,
so the component reads the theme and **bakes the values into** the drawing.

| Pele role | The library's role |
| --- | --- |
| `--pele-bg` | `card` |
| `--pele-fg` | `foreground` |
| `--pele-muted` | `muted-foreground` |
| `--pele-line` | `border-strong` |
| `--pele-surface` | `muted` |
| `--pele-surface-alt` | `accent` |
| `--pele-accent` | `primary` |
| `--pele-border` | `border` |

The three roles that are not colours — `--pele-radius`, `--pele-font` and
`--pele-font-mono` — are given literal values, because a raster carries no
font of its own.

## API [#api]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `source` | `string` | — | the Mermaid source; the whole interface |
| `label` | `string` | the host's `aria-label` | the drawing's name for a reader |
| `caption` | `string` | — | a line of words under the drawing |
| `maxWidth` | `number` | — | the width the drawing may use, so a narrow box adapts the layout |
| `fontSize` | `number` | — | the base font size, in pixels |
| `idPrefix` | `string` | — | the prefix on the drawing's ids, so two diagrams on one page do not collide |
| `className` | `string` | — | a class string, joined after the recipe so it wins conflicts |
| `style` | `StateStyle` | — | the caller's style, merged last |
| `children` | `ReactNode` | — | what a caller paints beside the drawing — a legend, a note |
| `testId` | `string` | — | the test id the drawing and the failure state answer to |

---

# Dialog

Source: https://gpuixui.sudokw.com/components/dialog

A modal surface that takes the window until it is dismissed

<ComponentPreview name="dialog-demo" />

## Installation [#installation]

<Install packageName="@gpuixui/components" importName="Dialog" />
<ComponentSource name="dialog" file="packages/components/src/dialog.tsx" />

## Usage [#usage]

```tsx
import {
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@gpuixui/components/dialog";
import { Button } from "@gpuixui/primitives";

<Dialog>
  <DialogTrigger>Delete workspace</DialogTrigger>
  <DialogContent label="Delete workspace">
    <DialogHeader>
      <DialogTitle>Delete this workspace?</DialogTitle>
      <DialogDescription>
        The workspace and its 42 files are removed for everyone.
      </DialogDescription>
    </DialogHeader>
    <DialogFooter>
      <DialogClose>Cancel</DialogClose>
      <Button variant="destructive">Delete workspace</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>;
```

## Composition [#composition]

```text
Dialog
├── DialogTrigger
└── DialogContent
    ├── DialogHeader
    │   ├── DialogTitle
    │   └── DialogDescription
    ├── DialogFooter
    │   └── DialogClose
    └── (close control)
```

## API reference [#api-reference]

### Dialog [#dialog]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `open` | `boolean` | uncontrolled |
| `defaultOpen` | `boolean` | `false` |
| `onOpenChange` | `(open: boolean) => void` | none |
| `dismissible` | `boolean` | `true` |
| `children` | parts — `DialogTrigger`, `DialogContent`, `DialogClose` | — |

### DialogContent [#dialogcontent]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `label` | `string` (required) | none |
| `role` | `"dialog" \| "alertdialog"` | `"dialog"` |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` — a stored name the union does not carry |
| `showClose` | `boolean` | `true` |
| `initialFocus` | `() => number \| null` | none |
| `className` | `string` — joined after the surface recipe | — |
| `children` | `ReactNode` — the surface's content | — |

### DialogTrigger and DialogClose [#dialogtrigger-and-dialogclose]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `disabled` | `boolean` | `false` |
| `onClick` | `(event: EventPayload) => void` | none |
| `variant` | `"primary" \| "secondary" \| "ghost" \| "danger"` | `"secondary"` |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` |
| `loading`, `loadingLabel`, `reducedMotion`, `leading`, `trailing` | the shared `Button` busy contract | — |
| `className` | `string` — joined after the button recipe | none |

## Theming [#theming]

The box paints the theme's `elevation.lg` beside its 1px `foreground` ring. Its corner is the recipe's fixed **32px** (`rounded-4xl`); the preview draws the platform radius plus 8px and is the approximation.

---

# Disclosure

Source: https://gpuixui.sudokw.com/components/disclosure

An inspector section headed by a triangle

<ComponentPreview name="disclosure-demo" />

## Usage [#usage]

```tsx
import { Disclosure } from "@gpuixui/components/disclosure";

<Disclosure title="Details">
  <PropertyRows />
</Disclosure>;
```

## Composition [#composition]

```text
Disclosure (a Collapsible)
├── trigger — the triangle and the 13-point semibold title
└── content — opened through the collapsible's measured reveal
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `title` | `string` | — |
| `defaultOpen` | `boolean` | `true`, as an inspector opens |
| `testId` | `string` — on the header | — |
| `children` | `ReactNode` — the body | — |

---

# Drawer

Source: https://gpuixui.sudokw.com/components/drawer

A modal panel anchored to any window edge

<ComponentPreview name="drawer-workflow" />

## Installation [#installation]

<Install packageName="@gpuixui/components" importName="Drawer" />
<ComponentSource
  name="drawer"
  file="packages/components/src/drawer.tsx"
/>

## Usage [#usage]

```tsx
import {
  Drawer,
  DrawerClose,
  DrawerContent,
  DrawerDescription,
  DrawerFooter,
  DrawerHeader,
  DrawerTitle,
  DrawerTrigger,
} from "@gpuixui/components/drawer";

<Drawer>
  <DrawerTrigger>Filters</DrawerTrigger>
  <DrawerContent label="Filters" side="right" size="md">
    <DrawerHeader>
      <DrawerTitle>Filters</DrawerTitle>
      <DrawerDescription>Narrow the result set.</DrawerDescription>
    </DrawerHeader>
    <DrawerFooter>
      <DrawerClose variant="ghost">Cancel</DrawerClose>
      <DrawerClose variant="primary">Apply filters</DrawerClose>
    </DrawerFooter>
  </DrawerContent>
</Drawer>;
```

## Composition [#composition]

```text
Drawer
├── DrawerTrigger
└── DrawerContent
    ├── DrawerHeader
    │   ├── DrawerTitle
    │   └── DrawerDescription
    ├── DrawerFooter
    │   └── DrawerClose
    └── (close control)
```

## API reference [#api-reference]

### `Drawer` [#drawer]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `open` | `boolean` | uncontrolled | controlled state; omit to let the drawer keep its own |
| `defaultOpen` | `boolean` | `false` | the initial state when uncontrolled |
| `onOpenChange` | `(open: boolean) => void` | none | reports the next state; a controlled drawer does not move until the caller re-renders |
| `dismissible` | `boolean` | `true` | whether Escape and an outside press close the surface; the close control is unaffected |
| `children` | parts | none | `DrawerTrigger`, `DrawerClose` and `DrawerContent` |

### `DrawerContent` [#drawercontent]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `label` | `string` (required) | none | the dialog's accessible name |
| `side` | `"left" \| "right" \| "top" \| "bottom"` | `"right"` | the edge the surface is anchored to; a stored name the union does not carry opens on the default `"right"` edge |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | the requested width or height, clamped by the window; a stored name the union does not carry paints the house `"md"` box |
| `showClose` | `boolean` | `true` | renders the close control, a `@gpuixui/icons` `x` named "Close drawer" |
| `inset` | `number` | none | a top sheet hangs this far below the window's top, centred and at most the window's width less 80 — AppKit's sheet under the toolbar |
| `grabber` | `boolean` | `true` | paints the vaul handle on a `top` or `bottom` sheet; a column never shows one |
| `initialFocus` | `() => number \| null` | none | the native id to focus after the surface receives focus |
| `className` | `string` | none | compiled through `@gpuixui/tw` and joined after the recipe |
| `children` | parts | none | the header, title, description, body and footer |

---

# Dropdown menu

Source: https://gpuixui.sudokw.com/components/dropdown-menu

A list of actions anchored to the control that opened it

<ComponentPreview name="dropdown-menu-demo" />

## Installation [#installation]

<Install packageName="@gpuixui/components" importName="DropdownMenu" />
<ComponentSource name="dropdownMenu" file="packages/components/src/dropdown-menu.tsx" />

## Usage [#usage]

```tsx
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuSeparator,
  DropdownMenuTrigger,
} from "@gpuixui/components/dropdown-menu";

<DropdownMenu>
  <DropdownMenuTrigger variant="secondary" size="sm">
    Actions
  </DropdownMenuTrigger>
  <DropdownMenuContent label="File actions" align="end">
    <DropdownMenuItem onSelect={() => rename(file)}>Rename</DropdownMenuItem>
    <DropdownMenuItem disabled>Duplicate</DropdownMenuItem>
    <DropdownMenuSeparator />
    <DropdownMenuItem tone="destructive" onSelect={() => remove(file)}>
      Delete
    </DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>;
```

## Composition [#composition]

```text
DropdownMenu
├── DropdownMenuTrigger
└── DropdownMenuContent
    ├── DropdownMenuItem
    ├── DropdownMenuCheckboxItem
    ├── DropdownMenuRadioGroup
    │   └── DropdownMenuRadioItem
    ├── DropdownMenuSeparator
    ├── DropdownMenuLabel
    ├── DropdownMenuGroup
    └── DropdownMenuSub
        ├── DropdownMenuSubTrigger
        └── DropdownMenuSubContent
```

## API reference [#api-reference]

### DropdownMenu [#dropdownmenu]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `open` | `boolean` | uncontrolled |
| `defaultOpen` | `boolean` | `false` |
| `onOpenChange` | `(open: boolean) => void` | none |
| `children` | parts — a trigger, the content and its rows | — |

### DropdownMenuContent [#dropdownmenucontent]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `label` | `string` (required) | the menu's accessible name |
| `side` | `"top" \| "right" \| "bottom" \| "left"` | `"bottom"` — a stored name the union does not carry |
| `align` | `"start" \| "center" \| "end"` | `"start"` — a stored name the union does not carry |
| `sideOffset` | `number` | `4` |
| `collisionPadding` | `number` | `8` |
| `alignOffset` | `number` | `0` — added to the measured centre correction |
| `className` | `string` | none — joined after the surface recipe |
| `children` | parts — the rows, groups and separators | none |

### DropdownMenuItem [#dropdownmenuitem]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `onSelect` | `() => void` | none — runs, then closes |
| `disabled` | `boolean` | `false` |
| `tone` | `"default" \| "destructive"` | `"default"` — a stored name the union does not carry |
| `leading` | `ReactNode` | none — a slot before the label |
| `trailing` | `ReactNode` | none — a slot after it, for a shortcut |
| `textValue` | `string` | the plain text children |
| `closeOnSelect` | `boolean` | `true` |
| `className` | `string` | none — joined after the row recipe |
| `style` | `StyleDesc \| (state: MenuItemState) => StyleDesc` | none |

### DropdownMenuCheckboxItem [#dropdownmenucheckboxitem]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `checked` | `boolean` (required) | none |
| `onCheckedChange` | `(checked: boolean) => void` (required) | none |
| `closeOnSelect` | `boolean` | `false` — the row stays open |
| `onSelect` / `disabled` / `tone` / `leading` / `trailing` / `textValue` | the row surface — see `DropdownMenuItem` | none |
| `className` | `string` | none — joined after the row recipe |
| `style` | `StyleDesc \| (state: MenuCheckboxItemState) => StyleDesc` | none |

### DropdownMenuRadioGroup / DropdownMenuRadioItem [#dropdownmenuradiogroup--dropdownmenuradioitem]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `value` | `string` (required, group) | none — the choice the group marks |
| `onValueChange` | `(value: string) => void` (required, group) | none — reports the chosen row's value |
| `label` | `string` | none — the choice's accessible name |
| `className` | `string` | none — compiled through `@gpuixui/tw` |
| `children` | parts — the group's `DropdownMenuRadioItem` rows | none (group) |
| `value` | `string` (required, row) | none — this row's value in the group |
| `closeOnSelect` / `disabled` / `tone` / `leading` / `trailing` / `textValue` | the row surface — see `DropdownMenuItem` | none (row) |
| `style` | `StyleDesc \| (state: MenuRadioItemState) => StyleDesc` | none — resolved against `{ checked, disabled, highlighted }` |

---

# Empty state

Source: https://gpuixui.sudokw.com/components/empty-state

The panel a collection shows when it has no rows

<ComponentPreview name="empty-state-demo" />

## Installation [#installation]

<Install packageName="@gpuixui/components" importName="EmptyState" />
<ComponentSource
  name="emptyState"
  file="packages/components/src/empty-state.tsx"
/>

## Usage [#usage]

```tsx
import { useState } from "react";
import { Card } from "@gpuixui/components";
import { EmptyState } from "@gpuixui/components/empty-state";
import { Button } from "@gpuixui/primitives";

export const ProjectsPanel = () => {
  const [creating, setCreating] = useState(false);

  if (creating) return <text>Create a project…</text>;

  return (
    <Card>
      <EmptyState
        title="No projects yet"
        description="A project holds your files, runs and settings."
        action={
          <Button variant="primary" onClick={() => setCreating(true)}>
            New project
          </Button>
        }
      />
    </Card>
  );
};
```

## Composition [#composition]

```text
EmptyState
├── icon
├── title
├── description
└── action
```

## API reference [#api-reference]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `title` | `string` | required | the line a reader scans first; painted in `foreground` |
| `description` | `string` | none | support copy under the title, wrapped at 360px |
| `action` | `ReactNode` | none | the way out, usually a `Button`; the only focusable part |
| `icon` | `ReactNode` | none | a decorative glyph above the title, painted in `mutedForeground` |
| `className` | `string` | none | compiled through `@gpuixui/tw`, joined after the recipe |
| `style` | `StyleDesc` | none | merged last, so a caller overrides any recipe property |
| `testId` | `string` | none | stable locator |

---

# Field and inline validation

Source: https://gpuixui.sudokw.com/components/field

A label, control and one message slot around an input

<ComponentPreview name="field-validation" />

## Installation [#installation]

<Install packageName="@gpuixui/components" importName="Field" />
<ComponentSource name="field" file="packages/components/src/field.tsx" />

## Usage [#usage]

```tsx
import { Effect, Option, Schema } from "effect";
import { useState } from "react";
import { Field, FieldInput } from "@gpuixui/components/field";
import { validate } from "@gpuixui/components/validation/logic";

const WorkspaceSlug = Schema.NonEmptyString.check(
  Schema.isPattern(/^[a-z0-9]+(-[a-z0-9]+)*$/, {
    identifier: "WorkspaceSlugPattern",
    title: "Workspace URL",
    message: "Use lowercase letters, numbers and single hyphens",
  }),
);

export const WorkspaceForm = () => {
  const [slug, setSlug] = useState("");
  const [error, setError] = useState<string>();

  const submit = () => {
    const message = Effect.runSync(validate(WorkspaceSlug)(slug));
    setError(Option.getOrUndefined(message));
  };

  return (
    <Field
      label="Workspace URL"
      description="Lowercase words joined by hyphens."
      error={error}
      required
    >
      <FieldInput
        value={slug}
        onChange={(event) => setSlug(event.value ?? "")}
      />
    </Field>
  );
};
```

## Composition [#composition]

```text
Field
├── FieldLabel
├── FieldDescription
├── FieldError
└── FieldInput

Fieldset
└── Field
```

## API reference [#api-reference]

| Part | Prop | Type | Default |
| ---- | ---- | ---- | ------- |
| `Field` | `label` | `string` — the visible label and the input's name | required |
| `Field` | `description` | `string` — hidden while `error` is present | — |
| `Field` | `error` | `string` — the message, which also paints the control invalid | — |
| `Field` | `required` | `boolean` — appends the `*` marker | `false` |
| `Field` | `className` | `string` — joined after the recipe | — |
| `Field` | `children` | the control; only `FieldInput` is accepted | — |
| `FieldLabel` | `required` | `boolean` — the marker without changing the name | `false` |
| `FieldDescription` | `children` | `ReactNode` | — |
| `FieldError` | `children` | `ReactNode` | — |
| `FieldInput` | `invalid` | `boolean` — overrides the field's own error as the validity signal | the field's state |
| `FieldInput` | `disabled` | `boolean` — also inferred from a disabled `Fieldset` | `false` |
| `FieldInput` | `style` | `StateStyle<{ disabled, focused, invalid }>` | the recipe |
| `FieldInput` | `value` / `defaultValue` | `string` — the text; omit `value` to let the field keep its draft | — |
| `FieldInput` | `onValueChange` / `onChange` | `(value: string) => void` · the raw host payload, first | — |
| `FieldInput` | `onSubmit` | `(event: EventPayload) => void` — `Enter` in the input | — |
| `FieldInput` | `placeholder` / `readOnly` / `autoFocus` | `string` · `boolean` · `boolean` | — |
| `FieldInput` | `size` / `fullWidth` / `tabIndex` | `"sm" \| "md" \| "lg"` · `boolean` · `number` | `"md"` · `false` · the field's place |
| `FieldInput` | `testId` | `string` — a stable locator | — |
| `FieldInput` | `ref` / `aria-id` / `onLayout` | the addressed element: focus it, measure it, name it for automation | — |
| `FieldInput` | `onClick` / `onKeyDown` / `onKeyUp` / `onFocus` / `onBlur` | host handlers, composed with the field's own | — |
| `Fieldset` | `legend` | `string` — the visible heading and the group's name | required |
| `Fieldset` | `disabled` | `boolean` — reaches the controls that honour it | `false` |

---

# Fieldset

Source: https://gpuixui.sudokw.com/components/fieldset

A named group of fields with a disabled state

<ComponentPreview name="fieldset-demo" />

## Usage [#usage]

```tsx
import { Field, FieldInput, Fieldset } from "@gpuixui/components";

<Fieldset legend="Billing address" disabled={saving}>
  <Field label="Street" description="Street and number">
    <FieldInput value={street} onChange={(event) => setStreet(event.value ?? "")} />
  </Field>
  <Field label="City" description="Where the invoice is sent">
    <FieldInput value={city} onChange={(event) => setCity(event.value ?? "")} />
  </Field>
</Fieldset>;
```

## Composition [#composition]

```text
Fieldset
└── FieldsetLegend
```

## API [#api]

| Part | Renders | Props |
| ---- | ------- | ----- |
| `Fieldset` | `div` with `role="group"` | `legend` (required), `disabled?`, `className?`, `children` |
| `FieldsetLegend` | `text` | `disabled?`, `className?` |

---

# Form

Source: https://gpuixui.sudokw.com/components/form

Schema validation and a submit lifecycle around fields

<ComponentPreview name="form-workflow" />

## Installation [#installation]

<Install packageName="@gpuixui/components" importName="Form" />
<ComponentSource name="form" file="packages/components/src/form.tsx" />

## Usage [#usage]

```tsx
import { Form } from "@gpuixui/components/form";
import { Field, FieldInput } from "@gpuixui/components/field";
import { Button } from "@gpuixui/primitives";
import { Schema } from "effect";
import { useState } from "react";

const Account = Schema.Struct({
  email: Schema.NonEmptyString,
  name: Schema.NonEmptyString,
});

export const CreateAccount = () => {
  const [draft, setDraft] = useState({ email: "", name: "" });

  return (
    <Form
      label="Create account"
      schema={Account}
      value={draft}
      onSubmit={(account) => save(account.email, account.name)}
    >
      {(state) => (
        <>
          <Field label="Email">
            <FieldInput
              value={draft.email}
              onChange={(event) =>
                setDraft({ ...draft, email: event.value ?? "" })
              }
            />
          </Field>
          <Field label="Name">
            <FieldInput
              value={draft.name}
              onChange={(event) =>
                setDraft({ ...draft, name: event.value ?? "" })
              }
            />
          </Field>
          <Button
            onClick={state.submit}
            disabled={state.pending}
            loading={state.pending}
          >
            Create account
          </Button>
        </>
      )}
    </Form>
  );
};
```

## Composition [#composition]

```text
Form
├── message block
└── children (fields)
```

## API reference [#api-reference]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `schema` | `Schema.ConstraintDecoder<T>` | none | decides whether the value may be submitted; its messages are the ones painted |
| `value` | `unknown` | none | the caller's draft; the form never reads a value from the runtime |
| `onSubmit` | `(value: T) => void` | none | receives the **decoded** value, only when the schema accepts it |
| `pending` | `boolean` | `false` | refuses `submit` while true, so one press is one save |
| `label` | `string` | none | makes the root `role="form"` with `aria-label`; without it the root is a plain container |
| `className` | `string` | none | joined after the recipe, so it wins conflicts |
| `children` | `(state: FormState) => ReactNode` | none | the render prop: `errors`, `pending`, `submit`, `form` |
| `style` | `StateStyle` | none | merged last on the root |

---

# Glyph

Source: https://gpuixui.sudokw.com/components/glyph

A wall of generated characters for its own box

<ComponentPreview name="glyph-demo" />

## Usage [#usage]

```tsx
import { Glyph } from "@gpuixui/components/glyph";

<Glyph
  marks="+/*<>[]{}"
  cellSize={20}
  density={0.6}
  seed={5}
  style={{ width: 520, height: 220 }}
>
  <text>Open the command deck</text>
</Glyph>;
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `children` | `ReactNode` | — |
| `marks` | `string` | `.+*/\<>[]{}~` |
| `cellSize` | `number` | `22` |
| `density` | `number` | `0.55` |
| `seed` | `number` | `1` |
| `color` | `string` | theme `border` |
| `breatheMs` | `number` | `8_000` |
| `level` | `MotionLevel` | `"slow"` |
| `className` | `string` | — |
| `style` | `StateStyle<GlyphState>` | — |

---

# Gradient

Source: https://gpuixui.sudokw.com/components/gradient

A two-stop gradient surface that breathes between ramps

<ComponentPreview name="gradient-demo" />

## Usage [#usage]

```tsx
import { Gradient } from "@gpuixui/components/gradient";

<Gradient
  from="#7C5CFF"
  to="#101014"
  angle={120}
  shift={80}
  style={{ padding: 32 }}
>
  <text>Ship faster with panels</text>
</Gradient>;
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `from` | `string` | theme `primary` |
| `to` | `string` | `from` at zero alpha |
| `angle` | `number` | `135` |
| `shift` | `number` | `90` |
| `durationMs` | `number` | `6_000` |
| `radius` | `number` | `0` |
| `level` | `MotionLevel` | `"slow"` |
| `className` | `string` | — |
| `style` | `StateStyle<GradientState>` | — |
| `children` | `ReactNode` | — |

---

# Gradient text

Source: https://gpuixui.sudokw.com/components/gradient-text

A phrase painted as a per-glyph colour ramp

<ComponentPreview name="gradient-text-demo" />

## Usage [#usage]

```tsx
import { GradientText } from "@gpuixui/components/gradient-text";

<GradientText text="Native by default" />;

// Own the colours.
<GradientText text="Fast by design" from="#7C5CFF" to="#24C6A8" role="h2" />;
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `text` | `string` (required) | — |
| `from` | `string` | theme `foreground` |
| `to` | `string` | theme `primary` |
| `role` | `TextRole` | `"display"` |
| `level` | `MotionLevel` | `"slow"` |
| `className` | `string` | — |
| `style` | `StateStyle<GradientTextState>` | — |

---

# Highlight text

Source: https://gpuixui.sudokw.com/components/highlight-text

A phrase whose matches a marker wash sweeps across

<ComponentPreview name="highlight-text-demo" />

## Usage [#usage]

```tsx
import { HighlightText } from "@gpuixui/components/highlight-text";

<HighlightText text="Native by default" query="native" />;
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `text` | `string` (required) | — |
| `query` | `string` | — |
| `ranges` | `ReadonlyArray<readonly [number, number]>` | — |
| `caseSensitive` | `boolean` | `false` |
| `wholeWord` | `boolean` | `false` |
| `stepMs` | `number` | `60` |
| `color` | `string` | `findHighlight(theme).color` |
| `activeColor` | `string` | `findHighlight(theme).activeColor` |
| `activeIndex` | `number` | — |
| `role` | `TextRole` | `"body"` |
| `className` | `string` | — |
| `style` | `StateStyle<HighlightTextState>` | — |

## Ranges [#ranges]

`ranges` names `[start, end)` pairs in the phrase's **UTF-16 units** and wins
over `query`. A pair is the part of it **inside the phrase**: a start below `0`
or an end past the phrase is clamped to it, a fractional index is truncated to
the unit it names, and a pair that is not two numbers or whose ends meet after
that is **no range at all**. A find bar can therefore pass the ranges its own
arithmetic produced — `indexOf` answers `-1` for no match — without sending a
negative offset to the runtime's `highlight`, which reads absolute units.

---

# Hotkey recorder

Source: https://gpuixui.sudokw.com/components/hotkey-recorder

Capture a chord and display it as keycaps

<ComponentPreview name="hotkey-recorder-demo" />

Using [TanStack Hotkeys](https://tanstack.com/hotkeys).

## Usage [#usage]

```tsx
import { HotkeyRecorder } from "@gpuixui/components";

<HotkeyRecorder
  label="Toggle command palette"
  value={hotkey}
  onChange={setHotkey}
/>;
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `label` | `string` | — |
| `value` | `string \| null` | `null` |
| `onChange` | `(value: string \| null) => void` | — |
| `onRecordingChange` | `(recording: boolean) => void` | — |
| `placeholder` | `string` | `"Click to record"` |
| `disabled` | `boolean` | `false` |
| `style` | `StateStyle<HotkeyRecorderState>` | — |
| `className` | `string` | — |

## Gating your own bindings [#gating-your-own-bindings]

A recorded key is swallowed with `preventDefault`, which removes the element's
default action — **not** the window's. GPUix still delivers the key to an
application-level `onKeyDown`, measured by the playground's
`hotkey-recorder-lifecycle` probe (`window=shift,k` on the press that stored
`Mod+Shift+K`), so the app owns the gate:

```tsx
const [recording, setRecording] = useState(false);

<AppShell
  onKeyDown={(event) => {
    if (recording) return;
    dispatchShortcut(event);
  }}
>
  <HotkeyRecorder
    label="Toggle command palette"
    value={hotkey}
    onChange={setHotkey}
    onRecordingChange={setRecording}
  />
</AppShell>;
```

---

# Hover card

Source: https://gpuixui.sudokw.com/components/hover-card

A rich surface previewed from a name, on hover or on focus

<ComponentPreview name="hover-card-demo" />

## Usage [#usage]

```tsx
import {
  HoverCard,
  HoverCardContent,
  HoverCardTrigger,
} from "@gpuixui/components/hover-card";

export const Mention = () => (
  <HoverCard>
    <HoverCardTrigger>@ada</HoverCardTrigger>
    <HoverCardContent label="Ada Lovelace">
      <text>Mathematician · Analytical Engine</text>
    </HoverCardContent>
  </HoverCard>
);
```

## The trigger is a link [#the-trigger-is-a-link]

shadcn's trigger is an anchor; `0.11.0` has none, so `HoverCardTrigger` is the
shared action painted as the library's **`link`** look — underlined text with no
fill and no edge — rather than the ghost chip it used to wear, which read as a
toggle button sitting in a sentence. It keeps the action's press, focus and
`aria-expanded`, and opens on hover after `openDelay`, on focus at once, or on a
press.

## Composition [#composition]

```text
HoverCard
├── HoverCardTrigger
└── HoverCardContent
```

## API [#api]

| Part | Prop | Type | Default |
| ---- | ---- | ---- | ------- |
| `HoverCard` | `open` / `defaultOpen` | `boolean` | — / `false` |
| `HoverCard` | `onOpenChange` | `(open: boolean) => void` | — |
| `HoverCard` | `openDelay` | `number` — milliseconds of hover before opening | `700` |
| `HoverCard` | `closeDelay` | `number` — milliseconds after the last hold leaves | `300` |
| `HoverCard` | `children` | `PartChildren` | — |
| `HoverCardTrigger` | action props | `variant` (`"link"` by default), `size`, `disabled`, `onClick`, `aria-label`, `style`, `ref`, `testId` — the shared `Button` contract | `size="md"` |
| `HoverCardTrigger` | busy props | `loading`, `loadingLabel`, `reducedMotion`, `leading`, `trailing` — the shared `Button` busy contract | — |
| `HoverCardContent` | `label` | `string` — the surface's accessible name | — |
| `HoverCardContent` | `side` | `"top" \| "right" \| "bottom" \| "left"` | `"bottom"` |
| `HoverCardContent` | `align` | `"start" \| "center" \| "end"` | `"center"` |
| `HoverCardContent` | `sideOffset` | `number` | `4` |
| `HoverCardContent` | `collisionPadding` | `number` | `8` |
| `HoverCardContent` | `className` / `style` | `string` / `StyleDesc` | — |
| `HoverCardContent` | `testId` / `children` | `string` / `PartChildren` | — |

---

# Image zoom

Source: https://gpuixui.sudokw.com/components/image-zoom

A frame whose picture magnifies under the pointer

<ComponentPreview name="image-zoom-demo" />

## Usage [#usage]

```tsx
import { ImageZoom } from "@gpuixui/components/image-zoom";

<ImageZoom
  src="/maps/harbour.png"
  alt="A chart of the harbour with four approaches"
  width={360}
  height={200}
/>;
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `src` | `string` | — |
| `alt` | `string` (required) | — (a blank value reads as `"Picture"`) |
| `width` | `number` | `240` |
| `height` | `number` | `160` |
| `scale` | `number` | `1.6` |
| `radius` | `number` | `theme.radius.md` (a value that cannot be painted reads as the default; `0` stays square) |
| `level` | `MotionLevel` | `"normal"` |
| `className` | `string` | — |
| `style` | `StateStyle<ImageZoomState>` | — |

---

# Inline edit

Source: https://gpuixui.sudokw.com/components/inline-edit

Rename a value where it is displayed

<ComponentPreview name="inline-edit-workflow" />

## Installation [#installation]

<Install packageName="@gpuixui/components" importName="InlineEdit" />
<ComponentSource
  name="inlineEdit"
  file="packages/components/src/inline-edit.tsx"
/>

## Usage [#usage]

```tsx
import { InlineEdit } from "@gpuixui/components";
import { useState } from "react";

export const RenameProject = () => {
  const [name, setName] = useState("Docs site");

  return (
    <InlineEdit
      label="Project name"
      onCommit={(next) => {
        setName(next);
      }}
      value={name}
    />
  );
};
```

## API reference [#api-reference]

### `InlineEdit` [#inlineedit]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `value` | `string` | — | the committed text; required, and the caller owns it |
| `onCommit` | `(value: string) => void` | — | called on a **changed** `Enter` or blur commit, never twice per edit, and never when the caller disables the control mid-edit |
| `label` | `string` | — | the accessible name of both the display and the input |
| `placeholder` | `string` | `"—"` | painted in `mutedForeground` while the value is empty |
| `disabled` | `boolean` | `false` | leaves the tab order, ignores activation and fades to 0.5 |
| `editing` | `boolean` | — | the controlled edit state; `undefined` leaves it to the control |
| `defaultEditing` | `boolean` | `false` | the uncontrolled starting state |
| `onEditingChange` | `(editing: boolean) => void` | — | reports the edit state the control took |
| `style` | `StateStyle<InlineEditState>` | — | resolved against `{ editing, disabled }`, merged last |
| `className` | `string` | — | joined after the recipe, so it wins conflicts |
| `testId` | `string` | — | stable locator |
| `defaultValue` / `onValueChange` / `onChange` | the field surface it inherits — see `Input` | — | the draft the control keeps before a commit, and every edit it reports |
| `onSubmit` | `(event: EventPayload) => void` | — | `Enter` while editing; the commit has already run |
| `readOnly` / `autoFocus` | `boolean` | `false` | uneditable, or focused on mount |
| `invalid` / `description` | `boolean` · `string` | `false` · none | validation paint, and the help the field announces |
| `size` / `fullWidth` / `tabIndex` | `"sm" \| "md" \| "lg"` · `boolean` · `number` | `"md"` · `false` · the field's place | the input's height, its width, and its tab stop |
| `ref` / `aria-id` / `onLayout` | the addressed element | — | the input while editing: focus it, measure it, name it for automation |
| `onClick` / `onKeyDown` / `onKeyUp` / `onFocus` / `onBlur` | host handlers | — | composed with the control's own; yours runs first |

---

# Input group

Source: https://gpuixui.sudokw.com/components/input-group

A field and its addons inside one bordered, focus-ringed row

<ComponentPreview name="input-group-demo" />

## Usage [#usage]

```tsx
import {
  InputGroup,
  InputGroupAddon,
  InputGroupInput,
  InputGroupText,
} from "@gpuixui/components/input-group";

export const Search = () => (
  <InputGroup label="Search" description="Files and people in this space.">
    <InputGroupInput placeholder="Search…" />
    <InputGroupAddon align="inline-start">
      <InputGroupText>⌘</InputGroupText>
    </InputGroupAddon>
    <InputGroupAddon align="inline-end">
      <InputGroupText>K</InputGroupText>
    </InputGroupAddon>
  </InputGroup>
);
```

## Composition [#composition]

```text
InputGroup
├── label / description / error   (the group's own slots)
├── InputGroupAddon  align="block-start"
├── InputGroupAddon  align="inline-start"
├── InputGroupInput | InputGroupTextarea
├── InputGroupAddon  align="inline-end"
├── InputGroupButton
├── InputGroupText
└── InputGroupAddon  align="block-end"
```

## API [#api]

| Part | Prop | Type | Default |
| ---- | ---- | ---- | ------- |
| `InputGroup` | `label` | `string` — the visible label and every group field's name | — |
| `InputGroup` | `description` | `string` — supporting copy, hidden while an error shows | — |
| `InputGroup` | `error` | `string` — paints the row invalid and takes the description slot | — |
| `InputGroup` | `invalid` | `boolean` — invalid without a message | `false` |
| `InputGroup` | `className` / `style` | `string` / `StyleDesc` | — |
| `InputGroup` | `testId` / `children` | `string` / `PartChildren` | — |
| `InputGroupAddon` | `align` | `"inline-start" \| "inline-end" \| "block-start" \| "block-end"` | `"inline-start"` |
| `InputGroupAddon` | `className` / `style` | `string` / `StyleDesc` | — |
| `InputGroupAddon` | `testId` / `children` | `string` / `ReactNode` | — |
| `InputGroupButton` | action props | `variant` (`"ghost"` by default), `size`, `disabled`, `onClick` — the shared `Button` contract | `size="sm"` |
| `InputGroupButton` | busy props | `loading`, `loadingLabel`, `reducedMotion`, `leading`, `trailing` — the shared `Button` busy contract | — |
| `InputGroupText` | `className` / `style` | `string` / `StyleDesc` | — |
| `InputGroupText` | `children` | `ReactNode` | — |
| `InputGroupInput` | field props | `value`, `defaultValue`, `onValueChange`, `onChange`, `onSubmit`, `placeholder`, `readOnly`, `disabled`, `autoFocus`, `invalid`, `size`, `fullWidth`, `label`, `tabIndex`, `description`, `onClick`, `onKeyDown`, `onKeyUp`, `onFocus`, `onBlur`, `ref`, `aria-id`, `onLayout`, `className`, `style`, `testId` — the primitives' input contract | — |
| `InputGroupTextarea` | field props | the same as `InputGroupInput` without `onSubmit`, plus `minRows` and `maxRows` | — |

---

# Inset group

Source: https://gpuixui.sudokw.com/components/inset-group

A settings form's grouped rows, as System Settings draws them

<ComponentPreview name="inset-group-demo" />

## Usage [#usage]

```tsx
import { InsetGroup, InsetGroupRow } from "@gpuixui/components/inset-group";

<InsetGroup title="Notifications">
  <InsetGroupRow
    label="Show previews"
    description="Message text on the lock screen"
    control={<Switch label="Show previews" />}
  />
  <InsetGroupRow label="Badge app icon" control={<Switch label="Badge app icon" />} />
</InsetGroup>;
```

## Composition [#composition]

```text
InsetGroup
├── title (optional)
└── box — rounded card, hairline edge
    └── InsetGroupRow × n — label leading, control trailing, a hairline between rows
```

## API [#api]

| Part | Prop | Type | Default |
| ---- | ---- | ---- | ------- |
| `InsetGroup` | `title` | `string` | — |
| `InsetGroup` | `titleTone` | `"strong" \| "muted"` — a muted caption reads as System Settings' section label | `"strong"` |
| `InsetGroup` | `elevated` | `boolean` — lifts the box on the theme's `md` shadow | `false` |
| `InsetGroup` | `insetDividers` | `boolean` — hairlines stop short of the box's edges | `false` |
| `InsetGroup` | `children` | `ReactNode` — the `InsetGroupRow`s | — |
| `InsetGroupRow` | `label` | `string` | — |
| `InsetGroupRow` | `description` | `string` — a secondary line | — |
| `InsetGroupRow` | `control` | `ReactNode` — a switch, a select, a segmented control | — |

---

# Item

Source: https://gpuixui.sudokw.com/components/item

One row of a list, with media, text and actions

<ComponentPreview name="item-demo" />

## Usage [#usage]

```tsx
import {
  Item,
  ItemActions,
  ItemContent,
  ItemDescription,
  ItemGroup,
  ItemMedia,
  ItemTitle,
} from "@gpuixui/components/item";

export const Files = () => (
  <ItemGroup>
    <Item variant="outline">
      <ItemMedia variant="icon">▤</ItemMedia>
      <ItemContent>
        <ItemTitle>design-system.md</ItemTitle>
        <ItemDescription>Tokens and semantic roles.</ItemDescription>
      </ItemContent>
      <ItemActions>
        <Button size="sm">Open</Button>
      </ItemActions>
    </Item>
  </ItemGroup>
);
```

## Composition [#composition]

```text
ItemGroup
└── Item
    ├── ItemHeader      (own line, above)
    ├── ItemMedia       (before the content)
    ├── ItemContent
    │   ├── ItemTitle
    │   └── ItemDescription
    ├── ItemActions     (after the content)
    └── ItemFooter      (own line, below)
```

## API [#api]

| Part | Prop | Type | Default |
| ---- | ---- | ---- | ------- |
| `Item` | `variant` | `"default" \| "outline" \| "muted"` | `"default"` |
| `Item` | `size` | `"default" \| "sm"` | `"default"` |
| `Item` | `className` | `string` | — |
| `Item` | `children` | `PartChildren` | — |
| `ItemGroup` | `className` / `children` | `string` / `PartChildren` | — |
| `ItemMedia` | `variant` | `"default" \| "icon" \| "image"` | `"default"` |
| `ItemMedia` | `className` / `children` | `string` / `PartChildren` | — |
| `ItemContent` | `className` / `children` | `string` / `PartChildren` | — |
| `ItemTitle` | `className` / `children` | `string` / `ReactNode` | — |
| `ItemDescription` | `className` / `children` | `string` / `ReactNode` | — |
| `ItemActions` | `className` / `children` | `string` / `PartChildren` | — |
| `ItemHeader` | `className` / `children` | `string` / `PartChildren` | — |
| `ItemFooter` | `className` / `children` | `string` / `PartChildren` | — |

---

# Kanban

Source: https://gpuixui.sudokw.com/components/kanban

Columns of cards a person reorders with a pointer or the arrow keys

A board places cards in columns and reports every move. The board owns the flat
placement list in uncontrolled mode, and a controlled `order` keeps it in the
caller's store.

This page is the source, not a live preview. The board is a GPUix surface; the
browser drawing on [the Kanban block](/docs/blocks/kanban) is an illustration
of it.

## Usage [#usage]

```tsx
import { Kanban } from "@gpuixui/components/kanban";
import type {
  KanbanCard,
  KanbanColumn,
  KanbanMove,
} from "@gpuixui/components/kanban";

const columns: ReadonlyArray<KanbanColumn> = [
  { id: "open", title: "Open" },
  { id: "hunting", title: "Hunting" },
  { id: "cleared", title: "Cleared" },
];

const cards: ReadonlyArray<KanbanCard> = [
  { id: "exam", column: "open", title: "Pass the Hunter Exam" },
  { id: "troupe", column: "hunting", title: "Track the Phantom Troupe" },
];

const move = (next: KanbanMove) => save(next);

<Kanban
  label="Hunter contracts"
  columns={columns}
  cards={cards}
  onMove={move}
  onCardClick={(card) => open(card.id)}
/>;
```

## Moving [#moving]

A card moves by pointer or keyboard; both routes produce the same `KanbanMove`.

- **Pointer** — press a card, move, release. A single insertion line marks the
  slot; the source card stays in place at reduced opacity and no column or card
  is tinted.
- **Keyboard** — a focused card moves with `Up`/`Down` inside its column and
  `Left`/`Right` into the neighbouring one. The move stops at the ends; it does
  not wrap. `Enter` or `Space` presses the card.

`onMove` reports `id`, `from`, `to` and `index`. The index counts the destination
column **without** the moving card, which is the slot the line painted.
`onOrderChange` reports the whole arrangement after an accepted move.

## Controlled order [#controlled-order]

Pass `order` to own the arrangement, or `defaultOrder` to start uncontrolled.
An order saved before a card was added is still readable: a card the order does
not name is appended to its own `column`, and an entry naming a card or column
this render does not carry is dropped.

## Limitations [#limitations]

- `0.11.0` has no `aria-grabbed` or `aria-dropeffect`, so a drag is not
  announced as a drag; the card's name and the arrow contract carry the
  interaction.
- No live region: a move is not announced. The column counts are painted text.
- The runtime has no `document`, `window` or `getBoundingClientRect`, so
  `@dnd-kit/core` cannot run here. Drag is pointer capture plus
  `renderer.getElementBounds` — the same model the shipped `Slider` uses.
- There is no auto-scroll while a long column is dragged past its edge.

## API [#api]

| Part | Prop | Type | Default |
| ---- | ---- | ---- | ------- |
| `Kanban` | `columns` | `ReadonlyArray<KanbanColumn>` — `id` and `title` | — |
| `Kanban` | `cards` | `ReadonlyArray<KanbanCard>` — `id`, `column`, `title`, optional `description` | — |
| `Kanban` | `order` | `KanbanOrder` — a controlled placement list | — |
| `Kanban` | `defaultOrder` | `KanbanOrder` — the uncontrolled starting list | the cards' own columns |
| `Kanban` | `onOrderChange` | `(order: KanbanOrder) => void` | — |
| `Kanban` | `onMove` | `(move: KanbanMove) => void` | — |
| `Kanban` | `onCardClick` | `(card: KanbanCard) => void` | — |
| `Kanban` | `label` | `string` — the board's accessible name | `Kanban board` |
| `Kanban` | `cardLabel` | `(card: KanbanCard) => string` | the card's title |
| `Kanban` | `renderCard` | `(card, state) => ReactNode` — content inside the drag surface | title and description |
| `Kanban` | `style` | `StyleDesc` — merged last | — |
| `Kanban` | `testId` | `string` — card and column locators extend it | — |

`KanbanMove` is `{ id, from, to, index }`; `KanbanOrder` is
`ReadonlyArray<{ id, column }>` in reading order.

## Related [#related]

- [Kanban block](/docs/blocks/kanban) — the browser drawing of this board
- [Card](/docs/components/card) — the content a card can hold
- [List](/docs/components/list) — a single-column alternative

---

# Keyboard shortcuts

Source: https://gpuixui.sudokw.com/components/keyboard-shortcuts

A cheat sheet of chords as platform keycaps

<ComponentPreview name="keyboard-shortcuts-demo" />

## Usage [#usage]

```tsx
import {
  KeyboardShortcut,
  KeyboardShortcuts,
  KeyboardShortcutsGroup,
} from "@gpuixui/components";

<KeyboardShortcuts label="Editor shortcuts">
  <KeyboardShortcutsGroup label="File">
    <KeyboardShortcut label="New file" accelerator="mod+n" />
    <KeyboardShortcut label="Save" accelerator="mod+s" />
  </KeyboardShortcutsGroup>
</KeyboardShortcuts>;
```

## Composition [#composition]

```text
KeyboardShortcuts
└── KeyboardShortcutsGroup
    └── KeyboardShortcut
        └── Keycap
```

## API [#api]

| Part | Renders | Props |
| ---- | ------- | ----- |
| `KeyboardShortcuts` | `div` with `role="list"` | `label?`, `className?`, `children` |
| `KeyboardShortcutsGroup` | `div` with `role="group"` | `label` (required), `className?`, `children` |
| `KeyboardShortcut` | `div` with `role="listitem"` | `label` (required), `accelerator` (required), `platform?`, `style?`, `className?` |
| `Keycap` | one key cap | `children: string`, `style?`, `className?` |

---

# Knob

Source: https://gpuixui.sudokw.com/components/knob

A rotary control for one value in a range

<ComponentPreview name="knob-demo" />

## Usage [#usage]

```tsx
import { Knob } from "@gpuixui/components/knob";

<Knob label="Gain" value={gain} onValueChange={setGain} />;
```

Drag upward to turn it up, or focus it and use the arrow keys, Home and End.
The sweep runs through 270°, with the middle of the range at the top.

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `label` | `string` — the accessible name | — |
| `value` | `number` | uncontrolled |
| `defaultValue` | `number` | `min` |
| `min`, `max` | `number` | `0`, `100` |
| `step` | `number` | `1` |
| `size` | `number` — the diameter | `48` |
| `disabled` | `boolean` | `false` |
| `indicatorColor` | `string` | the theme's primary |
| `onValueChange` | `(value: number) => void` | — |
| `style` | `StyleDesc` | — |

Use [Slider](/primitives/slider) when the exact position along a range matters.

---

# List

Source: https://gpuixui.sudokw.com/components/list

Rows with one tab stop, type-ahead and a row action

<ComponentPreview name="list-demo" />

<ComponentPreview name="list-multiple" />

## Installation [#installation]

<Install packageName="@gpuixui/components" importName="List" />
<ComponentSource name="list" file="packages/components/src/list.tsx" />

## Usage [#usage]

```tsx
import {
  List,
  ListItem,
  ListItemDescription,
  ListItemTitle,
} from "@gpuixui/components/list";

const files = [
  { value: "readme", title: "README.md", description: "The project's front door" },
  { value: "design", title: "Design notes", description: "docs/design-notes.md" },
];

export const FileList = ({ open }: { open: (value: string) => void }) => (
  <List defaultValue="readme" onActivate={open} selectionMode="single">
    {files.map((file) => (
      <ListItem key={file.value} textValue={file.title} value={file.value}>
        <ListItemTitle>{file.title}</ListItemTitle>
        <ListItemDescription>{file.description}</ListItemDescription>
      </ListItem>
    ))}
  </List>
);
```

## Composition [#composition]

```text
List
└── ListItem
    ├── ListItemTitle
    ├── ListItemDescription
    ├── leading
    └── trailing
```

## API reference [#api-reference]

### List [#list]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `selectionMode` | `"none" \| "single" \| "multiple"` | `"none"` |
| `value` | `string` (single) · `ReadonlyArray<string>` (multiple) — controlled | — |
| `defaultValue` | the same shape, initial selection when uncontrolled | `""` · `[]` |
| `onValueChange` | `(value: string) => void` (single) · `(values: ReadonlyArray<string>) => void` (multiple) | — |
| `onActivate` | `(value: string) => void` — single and `none` only; absent from the multiple variant | — |
| `dense` | `boolean` — a row at `density.rowHeight` instead of `rowHeight + spacing.md` | `false` |
| `children` | parts — `ListItem` rows, one `ListSection` per group | — |
| `className` | `string` — joined after the root recipe | — |

### ListItem [#listitem]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `value` | `string` (required) | — |
| `textValue` | `string` — the text type-ahead matches | — |
| `disabled` | `boolean` | `false` |
| `leading` | `ReactNode` — an icon, avatar or marker | — |
| `trailing` | `ReactNode` — metadata, a badge or an action | — |
| `children` | parts — `ListItemTitle`, `ListItemDescription` and the row's slots | — |
| `className` | `string` — joined after the row recipe | — |
| `style` | `StyleDesc` or a function of `{ active, disabled, selected }` | — |

---

# Mention input

Source: https://gpuixui.sudokw.com/components/mention-input

`@name` autocompletion in a text field

<ComponentPreview name="mention-input-demo" />

## Installation [#installation]

```bash
nub add @gpuixui/components
```

## Usage [#usage]

```tsx
import {
  MentionInput,
  MentionInputItem,
  MentionInputList,
} from "@gpuixui/components";

<MentionInput
  label="Comment"
  value={comment}
  onValueChange={setComment}
  onMention={(name) => notify(name)}
>
  <MentionInputList>
    {people.map((person) => (
      <MentionInputItem key={person} value={person} />
    ))}
  </MentionInputList>
</MentionInput>;
```

## Composition [#composition]

```text
MentionInput
├── MentionInputList
│   └── MentionInputItem
```

## API [#api]

| Part | Renders | Props |
| ---- | ------- | ----- |
| `MentionInput` | a `role="group"` field wrapping an `<input>` | `label` (required), `value?`, `defaultValue?`, `onValueChange?`, `onMention?`, `maxVisible?`, `disabled?`, `className?`, `children`, `placeholder?`, `readOnly?`, `autoFocus?`, `invalid?`, `size?`, `fullWidth?`, `tabIndex?`, `testId?`, `onClick?`, `onKeyDown?`, `onKeyUp?`, `onFocus?`, `onBlur?`, `ref?`, `aria-id?`, `onLayout?`, `description?` |
| `MentionInputList` | anchored suggestion surface, labelled "Mentions" | `className?`, `children` |
| `MentionInputItem` | a selected button row | `value` (required), `label?`, `style?`, `className?` |

## Motion [#motion]

The suggestion list enters and leaves on the house `normal` level: a fade plus 4px
of travel out from the field's bottom edge. Closing the query — `Escape` or a
selection — keeps the box painted for its exit window, carrying the rows the
reader dismissed rather than re-ranking an empty query mid-fade, and the seam's
leaving guard stops a ghost row taking the press while the row drops its own tab
stop with the box. A list that only narrows to nothing is cut instead: the field
is still open and a ghost of rows the query no longer matches would misreport the
search. A field the caller disables cuts its list too, because the control
refuses every route and there is no gesture to finish.
`MotionProvider preference="reduced"` removes the journey: the box is gone in the
frame it closes.

---

# Message

Source: https://gpuixui.sudokw.com/components/message

A typical agent conversation

<ComponentPreview name="message-demo" />

`Message` is the layout of one turn. It owns the author, avatar, timestamp,
metadata and alignment; `MessageContent` is the column between the avatar and
the row's edge; a `Bubble` is always a child and is never built here. The data
slots the row carried before — reasoning, tool calls, citations, streaming —
stay as props on `MessageContent` and paint outside the bubble surface.

## Installation [#installation]

```bash
nub add @gpuixui/components
```

## Usage [#usage]

```tsx
import {
  Bubble,
  BubbleContent,
  Message,
  MessageActions,
  MessageAvatar,
  MessageContent,
  MessageFooter,
  MessageHeader,
} from "@gpuixui/components";

<Message variant="assistant" timestamp="09:42">
  <MessageAvatar />
  <MessageContent
    reasoning={message.reasoning}
    toolCalls={message.tools}
    sources={message.sources}
    streaming={message.streaming}
  >
    <MessageHeader />
    <Bubble>
      <BubbleContent>{message.body}</BubbleContent>
    </Bubble>
    <MessageFooter>
      <MessageActions onCopy={copy} onRetry={retry} />
    </MessageFooter>
  </MessageContent>
</Message>;
```

## Composition [#composition]

```text
Message
├── MessageAvatar
└── MessageContent
    ├── MessageHeader
    ├── Bubble
    │   └── BubbleContent
    └── MessageFooter
        └── MessageActions
```

`MessageGroup` stacks consecutive rows from one sender.

## Author and timestamp [#author-and-timestamp]

`Message` reads the author once and shares it with `MessageHeader` and
`MessageAvatar`, so a row cannot publish two different names. `variant` selects
the default author (`You`, `Assistant`, `System`) and the default side (`end`
for a user, `start` otherwise); `author`, `timestamp` and `meta` override what
the header paints. A timestamp is the caller's formatted string; no locale is
applied.

## Data slots [#data-slots]

Reasoning, tool calls, citations and the streaming marker are data, not
markup: presence is the only switch, and a restored record's absent slot paints
nothing. They sit outside the bubble, so a trace can be read without being
painted into the reply.

## Actions [#actions]

`MessageActions` renders nothing when no handler can serve a control. Put it in
`MessageFooter`; the footer follows the row's side.

## API [#api]

| Part | Renders | Props |
| ---- | ------- | ----- |
| `Message` | `role="group"` named by `label` or the author | `variant?`, `align?`, `author?`, `timestamp?`, `meta?`, `avatarSrc?`, `label?`, `className?`, `children` |
| `MessageAvatar` | the shipped `Avatar` at `sm` | `name?`, `src?`, `className?` |
| `MessageHeader` | the author, timestamp and meta line | `className?` |
| `MessageContent` | the slot column between avatar and edge | `reasoning?`, `toolCalls?`, `sources?`, `streaming?`, `streamingLabel?`, `reasoningLabel?`, `sourcesLabel?`, `className?`, `style?`, `children` |
| `MessageFooter` | the under-bubble line, on the row's side | `className?`, `children` |
| `MessageActions` | a named action row, or `null` | `onCopy?`, `onRetry?`, `onFeedback?`, `copyLabel?`, `retryLabel?`, `helpfulLabel?`, `notHelpfulLabel?`, `className?` |
| `MessageGroup` | consecutive rows, tighter | `gap?`, `className?`, `children` |

## Breaking change [#breaking-change]

`MessageRoot` is now `Message`. The old root built the bubble itself; the new
one does not. Every row must place a `Bubble` inside `MessageContent`, and
actions move from `MessageContent` to `MessageFooter`. This is the shadcn
structure the component is modelled on; the split is what lets a bubble be
quoted, grouped or reused on its own.

---

# Message Scroller

Source: https://gpuixui.sudokw.com/components/message-scroller

Follows new content, keeps a scrolled-up reader in place

<ComponentPreview name="message-scroller-demo" />

MessageScroller is the transcript. It follows new rows and a growing streamed
reply while the reader is at the end; the moment they scroll away it stops, keeps
their position and offers the way back with the number of rows that arrived
unseen.

## Installation [#installation]

```bash
nub add @gpuixui/components
```

## Usage [#usage]

```tsx
import {
  MessageScroller,
  MessageScrollerContent,
  MessageScrollerItem,
  MessageScrollerJumpToLatest,
  MessageScrollerViewport,
} from "@gpuixui/components";

<MessageScroller label="Conversation" streaming={streaming}>
  <MessageScrollerViewport style={{ height: 320 }}>
    <MessageScrollerContent>
      {messages.map((message) => (
        <MessageScrollerItem key={message.id}>
          <text>{message.body}</text>
        </MessageScrollerItem>
      ))}
    </MessageScrollerContent>
  </MessageScrollerViewport>
  <MessageScrollerJumpToLatest />
</MessageScroller>;
```

## Composition [#composition]

```text
MessageScroller
├── MessageScrollerViewport
│   └── MessageScrollerContent
│       └── MessageScrollerItem
└── MessageScrollerJumpToLatest
```

## The height contract [#the-height-contract]

The viewport is the flexible middle of the scroller: it grows, may shrink and
never makes the frame taller. The jump control floats over the viewport's bottom
edge, centred, so showing it does not take height from the transcript or move
anything below the scroller. The root is the positioned box that the control
resolves against. Give the scroller a bounded height (directly, or through a
sized flex parent) because a viewport with no height has nothing to scroll.

The viewport carries no inset of its own: put the transcript's padding on
`MessageScrollerContent` (or the rows), so the scrollbar sits at the edge and
the first and last row keep their inset.

## Following and releasing [#following-and-releasing]

- A reader inside `threshold` (default 24px) of the tail is at the end. New rows
  and a reply that grows keep the tail visible.
- Scrolling away releases the view: appends and growth change nothing, and the
  floating control counts the rows that arrived.
- Jump to latest returns to the end and re-pins.
- A row that grows through its own state is still followed while pinned: the
  item's own `onLayout` size report is the measurement, so no React render is
  needed.
- A sibling that re-renders does not move the tail: the follow rule depends on
  the row count and on measured sizes, never on a plain render.
- An observation the scroller cannot read (`NaN`) is ignored; the pin state is
  kept.

## Turn anchoring [#turn-anchoring]

`MessageScrollerItem scrollAnchor` places a newly mounted row near the top with
`previousItemPeek` of the row above still visible, but only while the reader is
pinned. It is opt-in: a Chat that appends a user row and a reply should mark the
user row as the anchor if it wants shadcn's turn behaviour. An unpinned reader
is never moved.

## API [#api]

| Part | Renders | Props |
| ---- | ------- | ----- |
| `MessageScroller` | `role="group"` named by `label` | `label` (required), `threshold?`, `previousItemPeek?`, `pinned?`, `defaultPinned?`, `onPinnedChange?`, `streaming?`, `className?`, `children` |
| `MessageScrollerViewport` | the scroll container and its tail sentinel | `style`, `onScroll?`, `onLayout?`, `ref?`, `className?`, `children` |
| `MessageScrollerContent` | the rows column; publishes `aria-busy` | `className?`, `children` |
| `MessageScrollerItem` | one row, no surface; reports its size | `scrollAnchor?`, `className?`, `children`, `ref?` |
| `MessageScrollerJumpToLatest` | a floating secondary control, centred over the viewport's bottom edge | `label?`, `className?`, `style?` |

---

# MultiStepForm

Source: https://gpuixui.sudokw.com/components/multi-step-form

A gated wizard over Stepper, submitted on the last step

<ComponentPreview name="multi-step-form-workflow" />

## Usage [#usage]

```tsx
import { MultiStepForm } from "@gpuixui/components";
import * as Option from "effect/Option";

<MultiStepForm
  label="Create a workspace"
  steps={[
    {
      id: "name",
      title: "Name",
      content: <WorkspaceNameField value={name} onChange={setName} />,
      gate: () =>
        namePattern.test(name)
          ? Option.none()
          : Option.some("Use 3 to 24 lowercase letters, digits or hyphens"),
    },
    {
      id: "port",
      title: "Port",
      content: <PortField value={port} onChange={setPort} />,
      gate: () =>
        portUsable(port) ? Option.none() : Option.some("Enter a port from 1024 to 65535"),
    },
    {
      id: "review",
      title: "Review",
      content: <Review draft={{ name, port }} />,
      gate: () =>
        accepted ? Option.none() : Option.some("Accept the checklist first"),
    },
  ]}
  onSubmit={create}
/>;
```

## Steps [#steps]

Each entry of `steps` is a `MultiStep`:

| Field | Type | Default | Notes |
| ----- | ---- | ------- | ----- |
| `id` | `string` | required | The step's stable key, shared with its indicator row. |
| `title` | `string` | required | The step's name in the indicator and in the content's announcement; a blank title reads as its position (`Step 2`), and a value a saved record kept as something other than text is no title at all. |
| `description` | `string` | — | One line of supporting copy in the indicator; a blank line paints nothing, and a non-text field paints the same way. |
| `content` | `ReactNode` | required | Mounted only while the step is current. |
| `gate` | `() => Option.Option<string>` | — | Runs before the step moves and before the last step submits; the message it returns keeps the reader put, and a message that says nothing paints the shipped sentence instead of an empty alert. A `gate` that is not a function — the `null` a saved record wrote for a field it never carried — is no gate, so the step moves. |

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `steps` | `ReadonlyArray<MultiStep>` | required |
| `onSubmit` | `() => void` | required |
| `step` | `number` | — (uncontrolled) |
| `defaultStep` | `number` | `1` |
| `onStepChange` | `(step: number) => void` | — |
| `pending` | `boolean` | `false` |
| `submitLabel` | `string` | `"Submit"` |
| `nextLabel` | `string` | `"Next"` |
| `backLabel` | `string` | `"Back"` |
| `label` | `string` | — |
| `className` | `string` | — |
| `style` | `StyleDesc` | — |

## Names [#names]

`label` names the wizard group; a blank name is an **absence**, so the root is not published with an empty name. The indicator is always named (`Steps` when the wizard is not), a step whose `title` arrived blank is named by its position (`Step 2`) so no list item is unnamed and no announcement opens with a comma, and a title is published trimmed. That rule is the **stepper's** (`stepName` in `stepper/logic.ts`), so a `StepperStep` written directly and the wizard's content announcement cannot disagree about it. A blank `description` paints no line — an empty string lays out a zero-height run, but a run of spaces would lay out a full line. **A field a record kept as something other than text is no copy at all**: a saved definition's `title: 42` or `description: {}` reads through `textOf` before the blank rule, so the step keeps its position name and paints no description line instead of the render throwing out of `accessibleName`. The three action labels are copy too: a blank `nextLabel`, `backLabel` or `submitLabel` reads as its documented default, because a missing i18n row must not paint a blank box as the wizard's only way forward.

A gate's message is copy on the same rule. `Some("")` still **refuses** the move, so a table with a missing row cannot release a step its author gated, but the painted alert reads `This step is not complete yet.` rather than nothing — an invisible refusal leaves the reader pressing a button that does nothing.

---

# Navigation menu

Source: https://gpuixui.sudokw.com/components/navigation-menu

A horizontal nav that opens one anchored panel at a time

<ComponentPreview name="navigation-menu-demo" />

<ComponentPreview name="navigation-menu-states" />

## Installation [#installation]

<Install packageName="@gpuixui/components" importName="NavigationMenu" />
<ComponentSource
  name="navigationMenu"
  file="packages/components/src/navigation-menu.tsx"
/>

## Usage [#usage]

```tsx
import {
  NavigationMenu,
  NavigationMenuContent,
  NavigationMenuItem,
  NavigationMenuLink,
  NavigationMenuList,
  NavigationMenuTrigger,
} from "@gpuixui/components/navigation-menu";

<NavigationMenu label="Product" onValueChange={setSection} value={section}>
  <NavigationMenuList>
    <NavigationMenuItem value="platform">
      <NavigationMenuTrigger>Platform</NavigationMenuTrigger>
      <NavigationMenuContent>
        <NavigationMenuLink onSelect={() => open("overview")}>
          Overview
        </NavigationMenuLink>
      </NavigationMenuContent>
    </NavigationMenuItem>
  </NavigationMenuList>
</NavigationMenu>;
```

## Composition [#composition]

```text
NavigationMenu
└── NavigationMenuList
    └── NavigationMenuItem
        ├── NavigationMenuTrigger
        └── NavigationMenuContent
            └── NavigationMenuLink
```

## API reference [#api-reference]

| Part | Renders | Props |
| ---- | ------- | ----- |
| `NavigationMenu` | `role="navigation"`, named by `label` | `label` (required), `value`, `defaultValue`, `onValueChange`, `openDelay`, `closeDelay`, `className`, `children` |
| `NavigationMenuList` | `role="list"` row | `className`, `children` |
| `NavigationMenuItem` | `role="listitem"` | `value` (required), `className`, `children` |
| `NavigationMenuTrigger` | button carrying `aria-expanded` and a fixed-slot chevron | every `Button` prop, plus `disabled`; `trailing` renders before the chevron; `onActivate` is the action's handler and `onClick` its deprecated alias |
| `NavigationMenuContent` | anchored `role="group"` panel | `className`, `children` |
| `NavigationMenuLink` | full-width ghost button row | `onSelect`; `onActivate` with `onClick` as the deprecated alias; every `Button` prop |

---

# Page transition

Source: https://gpuixui.sudokw.com/components/page-transition

A region that swaps views with the house motion

<ComponentPreview name="page-transition-demo" />

## Installation [#installation]

```bash
nub add @gpuixui/components
```

## Usage [#usage]

```tsx
import { PageTransition } from "@gpuixui/components";

<PageTransition viewKey={section}>
  {section === "account" ? <AccountView /> : <BillingView />}
</PageTransition>;
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `viewKey` | `string` | — |
| `children` | `ReactNode` | — |
| `direction` | `"forward" \| "back"` | `"forward"` |
| `distance` | `number` | `16` |
| `level` | `SurfaceLevel` | `"normal"` |
| `className` | `string` | — |
| `style` | `StateStyle<PageTransitionPaint>` | — |

---

# Pagination

Source: https://gpuixui.sudokw.com/components/pagination

Previous and next controls around a stable-width page window

<ComponentPreview name="pagination-workflow" />

## Installation [#installation]

<Install packageName="@gpuixui/components" importName="Pagination" />
<ComponentSource
  name="pagination"
  file="packages/components/src/pagination.tsx"
/>

## Usage [#usage]

```tsx
import { useState } from "react";
import {
  Pagination,
  PaginationList,
  PaginationNext,
  PaginationPrevious,
} from "@gpuixui/components/pagination";

const PAGE_SIZE = 5;

export const DeploymentPages = ({ deployments }: { deployments: string[] }) => {
  const [page, setPage] = useState(1);
  const pageCount = Math.ceil(deployments.length / PAGE_SIZE);
  const rows = deployments.slice((page - 1) * PAGE_SIZE, page * PAGE_SIZE);

  return (
    <>
      <DeploymentList rows={rows} />
      <Pagination page={page} pageCount={pageCount} onPageChange={setPage}>
        <PaginationPrevious />
        <PaginationList />
        <PaginationNext />
      </Pagination>
    </>
  );
};
```

## Composition [#composition]

```text
Pagination
├── PaginationPrevious
├── PaginationList
│   ├── PaginationItem
│   └── PaginationEllipsis
└── PaginationNext
```

## API reference [#api-reference]

| Part | Prop | Type | Default | Consequence |
| ---- | ---- | ---- | ------- | ----------- |
| `Pagination` | `page` | `number` (required) | — | the current page, 1-based; clamped into `[1, pageCount]` |
| `Pagination` | `pageCount` | `number` (required) | — | pages that exist; zero or fewer renders nothing |
| `Pagination` | `onPageChange` | `(page: number) => void` (required) | — | a step or a page press |
| `Pagination` | `siblingCount` | `number` | `1` | pages shown either side of the current one |
| `Pagination` | `showEdges` | `boolean` | `true` | keep the first and last page visible |
| `Pagination` | `children` | parts | — | `PaginationPrevious`, `PaginationList`, `PaginationNext` |
| `PaginationItem` | `page` | `number` (required) | — | the page this button goes to |
| `PaginationItem` | `style` | `StateStyle<PaginationItemState>` | recipe | a style or a function of `{ active }` |
| `PaginationPrevious` / `PaginationNext` | — | — | — | step by one; disabled at their end |
| `PaginationList` / `PaginationEllipsis` | `className` | `string` | — | an extra recipe class, joined last |

---

# Pinned list

Source: https://gpuixui.sudokw.com/components/pinned-list

Headers that stay pinned while rows scroll under them

<ComponentPreview name="pinned-list-demo" />

## Installation [#installation]

```bash
nub add @gpuixui/components
```

## Usage [#usage]

```tsx
import { PinnedList } from "@gpuixui/components/pinned-list";

<PinnedList
  testId="settings"
  aria-label="Settings"
  style={{ height: 360 }}
  sections={[
    { title: "Account", children: <AccountRows /> },
    { title: "Notifications", children: <NotificationRows /> },
    { title: "Danger zone", children: <DangerRows /> },
  ]}
/>;
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `sections` | `ReadonlyArray<PinnedListSection>` (a value that is not a list reads as none; an entry without a text `title` is dropped) | — |
| `headerHeight` | `number` | `32` |
| `surfaceColor` | `string` | theme `background` |
| `className` | `string` | — |
| `style` | `StyleDesc` | — |
| `testId` | `string` | — |
| `aria-label` | `string` | the runtime's "Scroll region" |
| `onScrollChange` | `(event) => void` | — |
| `onLayout` | `(event) => void` | — |

---

# Popover

Source: https://gpuixui.sudokw.com/components/popover

A floating panel anchored to the control that opened it

<ComponentPreview name="popover-demo" />

## Installation [#installation]

<Install packageName="@gpuixui/components" importName="Popover" />
<ComponentSource name="popover" file="packages/components/src/popover.tsx" />

## Usage [#usage]

```tsx
import {
  Popover,
  PopoverContent,
  PopoverTrigger,
} from "@gpuixui/components/popover";

<Popover>
  <PopoverTrigger variant="secondary">Columns</PopoverTrigger>
  <PopoverContent side="bottom" align="start">
    <ColumnToggles />
  </PopoverContent>
</Popover>;
```

## Composition [#composition]

```text
Popover
├── PopoverTrigger
└── PopoverContent
```

## Sides [#sides]

<ComponentPreview name="popover-sides" />

## Collision [#collision]

<ComponentPreview name="popover-collision" />

## API reference [#api-reference]

### Popover [#popover]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `open` | `boolean` | uncontrolled |
| `defaultOpen` | `boolean` | `false` |
| `onOpenChange` | `(open: boolean) => void` | none |
| `children` | parts — `PopoverTrigger`, `PopoverContent` | — |

### PopoverContent [#popovercontent]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `side` | `"top" \| "right" \| "bottom" \| "left"` | `"bottom"` — a stored name the union does not carry |
| `align` | `"start" \| "center" \| "end"` | `"center"` — a stored name the union does not carry |
| `sideOffset` | `number` | `6` |
| `collisionPadding` | `number` | `8` |
| `alignOffset` | `number` | `0` |
| `className` | `string` — joined after the surface recipe | — |
| `children` | `ReactNode` — the surface's content | — |

### PopoverTrigger [#popovertrigger]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `onActivate` | `(event) => void` | — |
| `onClick` | `(event) => void` | — |

## Theming [#theming]

The surface paints the theme's `elevation.lg` beside its 1px `foreground` ring. Its corner is the recipe's fixed **24px** (`rounded-3xl`); the preview follows the platform radius and is the approximation.

---

# Preview card

Source: https://gpuixui.sudokw.com/components/preview-card

A rich, hoverable card shown on hover or on a press

<ComponentPreview name="preview-card-demo" />

## Installation [#installation]

```bash
nub add @gpuixui/components
```

## Usage [#usage]

```tsx
import {
  PreviewCard,
  PreviewCardContent,
  PreviewCardTrigger,
} from "@gpuixui/components";

<PreviewCard>
  <PreviewCardTrigger>design-system.md</PreviewCardTrigger>
  <PreviewCardContent label="design-system.md">
    <text>Tokens, semantic roles and the theme extension mechanism.</text>
  </PreviewCardContent>
</PreviewCard>;
```

## Composition [#composition]

```text
PreviewCard
├── PreviewCardTrigger
└── PreviewCardContent
```

## Behaviour [#behaviour]

- `PreviewCardContent` takes the popover's `align`: `start` shares the trigger's
  left edge, `center` (the default) its centre line and `end` its right edge,
  measured against the trigger rather than the runtime's containing block.
- The card is hoverable, so the pointer can leave the trigger and cross the 6px
  gap: the close is delayed (`closeDelay`, 150 ms by default) and the card's own
  enter cancels it.

## API [#api]

| Part | Renders | Props |
| ---- | ------- | ----- |
| `PreviewCard` | a positioning root; owns open state and the timers | `open?`, `defaultOpen?`, `onOpenChange?`, `openDelay?`, `closeDelay?`, `children` |
| `PreviewCardTrigger` | button, `aria-expanded` | button props |
| `PreviewCardContent` | anchored `role="group"` named by `label` | `label` (required), `side?`, `align?` (default `center`), `sideOffset?`, `collisionPadding?`, `alignOffset?`, `className?`, `children` |

---

# Progress

Source: https://gpuixui.sudokw.com/components/progress

A determinate or indeterminate bar in the caller's scale

<ComponentPreview name="progress-values" />

## Usage [#usage]

```tsx
import {
  Progress,
  ProgressLabel,
  ProgressValue,
} from "@gpuixui/components/progress";

<Progress value={30} max={120} label="Uploading">
  <ProgressLabel />
  <ProgressValue />
</Progress>;
```

`value` and `max` are the caller's units: `30 of 120` above paints the same
quarter-full bar as `25 of 100`. Omit `value` — or pass the `null` JSON writes
for a field a record never carried — for the indeterminate segment.

## Composition [#composition]

```text
Progress
├── ProgressLabel
├── ProgressValue
└── ProgressTrack
    └── ProgressIndicator
```

The root always paints the track and its fill after the children, so a caller
who composes only the label and the value still gets a bar. The four parts read
the root's state, so a share is computed once.

## API [#api]

| Part | Prop | Type | Default |
| ---- | ---- | ---- | ------- |
| `Progress` | `value` | `number \| null` | — (indeterminate) |
| `Progress` | `max` | `number` | `100` |
| `Progress` | `tone` | `"primary" \| "success" \| "destructive" \| "muted"` | `"primary"` |
| `Progress` | `size` | `"sm" \| "md"` | `"md"` |
| `Progress` | `label` | `string` | — |
| `Progress` | `formatValue` | `(percent: number) => string` | `` `${percent}%` `` |
| `Progress` | `loadingText` | `string` | the provider's `loading` word |
| `Progress` | `reducedMotion` | `boolean` | the motion provider |
| `Progress` | `children` | `ReactNode` | the track |
| `Progress` | `style` | `StyleDesc` | — |
| `Progress` | `className` | `string` | — |
| `Progress` | `testId` | `string` | — |
| `Progress` | `ref` / `aria-id` / `onLayout` | host props | — |
| `ProgressTrack` | `style`, `className`, `testId` | — | — |
| `ProgressIndicator` | `style`, `className`, `testId` | — | — |
| `ProgressLabel` | `children`, `testId` | `ReactNode`, `string` | the root's `label` |
| `ProgressValue` | `testId` | `string` | — |

---

# Reorderable tabs

Source: https://gpuixui.sudokw.com/components/reorderable-tabs

A tab strip you can drag, close and reorder with the keyboard.

<EditorTabsPreview />

## Usage [#usage]

```tsx
import { ReorderableTabs } from "@/components/docs/reorderable-tabs";

<ReorderableTabs
  active={active}
  label="Open editor files"
  onActivate={setActive}
  onClose={closeFile}
  onReorder={setTabs}
  tabs={tabs}
/>;
```

## Interaction [#interaction]

- Drag a tab to a new slot; the strip shifts its neighbours by the gap and snaps on release.
- <kbd>Alt</kbd> + <kbd>←</kbd>/<kbd>→</kbd> moves the focused tab.
- <kbd>×</kbd> closes a tab; a closing tab collapses its measured width first.

The caller owns the order and the open tab, so a replay or an explorer press can put a closed tab back. This is a browser drawing, not the native `Tabs` component.

## API [#api]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `tabs` | `ReadonlyArray<ReorderableTab>` | — | the open files, in strip order |
| `active` | `string \| null` | — | the open tab; `null` when every tab is closed |
| `label` | `string` | — | the strip's accessible name |
| `onActivate` | `(id: string) => void` | — | reports the pressed tab |
| `onReorder` | `(tabs: ReadonlyArray<ReorderableTab>) => void` | — | reports the new order |
| `onClose` | `(id: string) => void` | — | reports the closed tab |
| `className` / `tabClassName` / `closeClassName` | `string` | none | joined onto the strip, tab and close button |

---

# Reveal

Source: https://gpuixui.sudokw.com/components/reveal

Content that fades and travels into place

<ComponentPreview name="reveal-demo" />

## Installation [#installation]

```bash
nub add @gpuixui/components
```

## Usage [#usage]

```tsx
import { Reveal } from "@gpuixui/components/reveal";

<Reveal>
  <text>Automatic updates are on.</text>
</Reveal>;
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `children` | `ReactNode` | — |
| `open` | `boolean` | — |
| `from` | `RevealFrom` | `"below"` |
| `distance` | `number` | `8` |
| `level` | `MotionLevel` | `"normal"` |
| `delayMs` | `number` | `0` |
| `className` | `string` | — |
| `style` | `StateStyle<RevealState>` | — |

---

# Scroll fade

Source: https://gpuixui.sudokw.com/components/scroll-fade

An edge that fades where more content is hidden

<ComponentPreview name="scroll-fade-demo" />

## Installation [#installation]

```bash
nub add @gpuixui/components
```

## Usage [#usage]

```tsx
import { ScrollFade } from "@gpuixui/components/scroll-fade";

<ScrollFade color={theme.colors.card} style={{ height: 240 }}>
  {notes.map((note) => (
    <Note key={note.id} note={note} />
  ))}
</ScrollFade>;
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `children` | `ReactNode` | — |
| `color` | `string` | theme `background` |
| `edgeSize` | `number` | `32` |
| `label` | `string` | the runtime's "Scroll region" |
| `testId` | `string` | — |
| `className` | `string` | — |
| `style` | `StyleDesc` | — |

---

# Scroll progress

Source: https://gpuixui.sudokw.com/components/scroll-progress

A reading line for how far through content a reader is

<ComponentPreview name="scroll-progress-demo" />

## Installation [#installation]

```bash
nub add @gpuixui/components
```

## Usage [#usage]

```tsx
import { ScrollProgress } from "@gpuixui/components/scroll-progress";

<ScrollProgress label="Settings read" style={{ height: 240 }}>
  {settings.map((setting) => (
    <SettingsRow key={setting.id} setting={setting} />
  ))}
</ScrollProgress>;
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `children` | `ReactNode` | — |
| `side` | `"top" \| "bottom"` | `"bottom"` |
| `thickness` | `number` | `3` |
| `color` | `string` | `theme.colors.primary` |
| `trackColor` | `string` | `theme.colors.muted` |
| `label` | `string` | — |
| `testId` | `string` | — |
| `className` | `string` | — |
| `style` | `StyleDesc` | — |

---

# Search input

Source: https://gpuixui.sudokw.com/components/search-input

A single-line search field with a clear affordance

<ComponentPreview name="search-input-workflow" />

## Installation [#installation]

<Install packageName="@gpuixui/components" importName="SearchInput" />
<ComponentSource
  name="searchInput"
  file="packages/components/src/search-input.tsx"
/>

## Usage [#usage]

```tsx
import { SearchInput } from "@gpuixui/components/search-input";
import { Text } from "@gpuixui/primitives";
import { useState } from "react";

export const FileFilter = () => {
  const [query, setQuery] = useState("");
  const [last, setLast] = useState("none");

  return (
    <>
      <SearchInput
        aria-label="Filter files"
        placeholder="Filter files…"
        value={query}
        onValueChange={setQuery}
        onSubmit={setLast}
        onClear={() => setQuery("")}
      />
      <Text role="caption">Last submitted: {last}</Text>
    </>
  );
};
```

## Composition [#composition]

```text
SearchInput
├── leading mark
├── input
└── clear control
```

## API reference [#api-reference]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `value` | `string` | none | the controlled text; omit it to let the field keep its own |
| `defaultValue` | `string` | `""` | the initial text in uncontrolled mode |
| `onValueChange` | `(value: string) => void` | none | every edit, including the clear and `Escape` paths |
| `onChange` | host change event | none | the raw host payload, called before the value is applied |
| `onSubmit` | `(value: string) => void` | none | `Enter`, with the current text |
| `onClear` | `() => void` | none | the clear control or `Escape`, only when the field held text |
| `placeholder` | `string` | `"Search…"` | the hint the field paints — and announces — while the value is empty |
| `disabled` | `boolean` | `false` | `readOnly` plus the half-opacity paint; no ring, no tab stop, and an inert clear target |
| `className` | `string` | none | joined after the recipe, so it wins conflicts |
| `style` | `StateStyle<SearchInputState>` | none | resolved against `{ disabled, focused }` and merged last on the field surface |
| `testId` | `string` | `"search-input"` | the input's locator; the painted hint is `${testId}-hint` |
| `label` / `description` | `string` | none | the field's accessible name, and the help it announces |
| `invalid` | `boolean` | `false` | the destructive edge a failed search paints |
| `required` | `boolean` | `false` | the field is required by the form around it |
| `readOnly` / `autoFocus` | `boolean` | `false` | uneditable, or focused on mount |
| `size` / `fullWidth` / `tabIndex` | `"sm" \| "md" \| "lg"` · `boolean` · `number` | `"md"` · `false` · the field's place | height and padding from density, the full width, and the tab order |
| `ref` / `aria-id` / `onLayout` | the addressed element | none | the inner `<input>`: focus it, measure it, name it for automation |
| `onClick` / `onKeyDown` / `onKeyUp` / `onFocus` / `onBlur` | host handlers | none | composed with the field's own; yours runs first |

---

# Segmented control

Source: https://gpuixui.sudokw.com/components/segmented-control

One choice among a few, as a Mac view switcher

<ComponentPreview name="segmented-control-demo" />

## Usage [#usage]

```tsx
import { SegmentedControl } from "@gpuixui/components/segmented-control";

const [view, setView] = useState("list");

<SegmentedControl
  label="View"
  value={view}
  onValueChange={setView}
  items={[
    { value: "list", label: "List", icon: "list" },
    { value: "board", label: "Board", icon: "grid" },
  ]}
/>;
```

## Composition [#composition]

```text
SegmentedControl (the muted track, one tab stop)
└── segment × n (the primitives' action; the chosen one raised)
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `label` | `string` — the group's accessible name | — |
| `items` | `{ value, label, icon?, disabled? }[]` | — |
| `value` | `string` — the chosen segment | — |
| `onValueChange` | `(value: string) => void` | — |
| `size` | `"sm" \| "md"` | `"sm"` |

## Behaviour [#behaviour]

- The arrow keys **select** as they move and stop at either end, skipping a
  disabled segment — a Mac segmented control's rule, not a tab list's. Focus
  follows the choice.
- Segments share the track's width equally.

## The chosen segment [#the-chosen-segment]

The chosen segment is the surface raised off the track. In a light theme that is the page's `background`;
in a dark theme the page is darker than the track, so it lifts the track colour toward white instead.

---

# Select

Source: https://gpuixui.sudokw.com/components/select

One choice from a list, in a popover

<ComponentPreview name="select-workflow" />

## Installation [#installation]

<Install packageName="@gpuixui/primitives" importName="Select" />
<ComponentSource
  name="select"
  file="packages/primitives/src/components/Select.tsx"
/>

## Usage [#usage]

```tsx
import { useState } from "react";
import { Label, Select } from "@gpuixui/primitives";

const regions = [
  {
    label: "Europe",
    options: [
      { value: "eu-west", label: "Europe — West (Ireland)" },
      { value: "eu-central", label: "Europe — Central (Frankfurt)" },
    ],
  },
  {
    label: "Americas",
    options: [
      { value: "us-east", label: "United States — East" },
      { value: "us-west", label: "United States — West" },
    ],
  },
];

export const DeployTarget = () => {
  const [region, setRegion] = useState("eu-west");

  return (
    <>
      <Label>Region</Label>
      <Select
        label="Region"
        onValueChange={setRegion}
        options={regions}
        value={region}
      />
    </>
  );
};
```

## Composition [#composition]

```text
Select
├── trigger (built in)
├── content
│   └── item
└── group / label / separator
```

## API reference [#api-reference]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `options` | `ReadonlyArray<SelectOption \| SelectOptionGroup>` | required | the rows, or named groups of them, in render order |
| `value` | `string` | none | controlled selection |
| `defaultValue` | `string` | none | initial selection when uncontrolled |
| `selectedValue` | `string` | `value ?? defaultValue` | the choice a closed trigger announces — a parent's mirror of an uncontrolled select's value |
| `open` | `boolean` | none | controlled open state |
| `defaultOpen` | `boolean` | `false` | the list's initial state while `open` is omitted |
| `onOpenChange` | `(open: boolean) => void` | none | the open state the runtime reported |
| `onValueChange` | `(value: string) => void` | none | the committed value |
| `onChange` | `(value: string) => void` | none | deprecated alias; `onValueChange` wins when both are passed |
| `placeholder` | `string` | none | the trigger's text before a choice |
| `disabled` | `boolean` | `false` | refuses to open |
| `invalid` | `boolean` | `false` | `destructive` edge on the trigger |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | height and padding from density |
| `fullWidth` | `boolean` | `false` | trigger and list fill the parent |
| `side` | `FloatingSide` | the runtime's choice | which side the list opens on |
| `align` | `FloatingAlign` | GPUix's default | how the list is aligned against the trigger |
| `label` | `string` | none | the accessible name — put a visible `Label` beside it |
| `description` | `string` | none | announced help after the name; a blank one publishes nothing |
| `ref` / `aria-id` / `onLayout` | host props | none | the trigger is the addressed element — the one a form focuses, an automation host names and a layout measures |
| `style` | `StyleDesc` | none | merged last on the wrapper, which paints only its width |
| `triggerStyle` | `StateStyle<SelectTriggerState>` | none | resolved against the trigger's live state, merged last |
| `itemStyle` | `StateStyle<SelectItemState>` | none | resolved per row against that row's state, merged last |
| `testId` | `string` | none | locator for the wrapper — it is **not** the trigger |
| `triggerTestId` | `string` | none | locator for the element that opens the list |
| `itemTestId` | `(value: string) => string` | none | locator for an option row, derived from its value |

---

# Separator

Source: https://gpuixui.sudokw.com/components/separator

A rule between regions, decorative or announced

<ComponentPreview name="separator-roles" />

## Usage [#usage]

```tsx
import { Separator } from "@gpuixui/components/separator";

<Separator />;
<Separator orientation="vertical" />;
<Separator decorative />;
```

A semantic rule is a `separator` node a reader can find between two regions;
`decorative` keeps a rule in the drawing and out of the accessibility tree. The
default is semantic, because a divider that separates content is content.

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |
| `decorative` | `boolean` | `false` |
| `inset` | `"2xs" \| "xs" \| "sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "4xl" \| "5xl"` | — |
| `label` | `string` | — |
| `style` | `StyleDesc` | — |
| `className` | `string` | — |
| `testId` | `string` | — |
| `aria-id` | `string` | — |

---

# Sheet

Source: https://gpuixui.sudokw.com/components/sheet

A modal panel anchored to any of four window edges

<ComponentPreview name="drawer-sides" />

The drawing opens on the surface: the frame is the window, the `md` panel is
flush to the right edge it names, and the edge buttons re-open it — `top` and
`bottom` wear the grabber — while the veil washes and blurs the page behind it.

## Usage [#usage]

```tsx
import {
  Sheet,
  SheetClose,
  SheetContent,
  SheetDescription,
  SheetFooter,
  SheetHeader,
  SheetTitle,
  SheetTrigger,
} from "@gpuixui/components";
```

`Sheet` is shadcn's name for the surface `Drawer` already paints: a veil over
the window, a panel on one edge, a focus trap inside it, Escape and an outside
press to close, and focus returned to the opener. It re-exports that machinery,
so the drawing above is the Drawer page's — there is one implementation, not two.

The sheet **animates in**: the panel slides its own span from the edge it names
(a bottom sheet rises a whole 320px) over the `slow` level, the veil fades, and
the surface is clipped by the window while it travels. A bottom sheet wears the
vaul grabber and rounded inner corners; `MotionProvider preference="reduced"`
paints the settled frame at once. The veil is the page's background at 55%; the
blur the drawing carries has no native route (`StyleDesc` has no `filter`).

```tsx
<Sheet>
  <SheetTrigger>Filters</SheetTrigger>
  <SheetContent side="right" label="Filters">
    <SheetHeader>
      <SheetTitle>Filters</SheetTitle>
      <SheetDescription>Narrow the result set, then apply.</SheetDescription>
    </SheetHeader>
    <SheetFooter>
      <SheetClose>Cancel</SheetClose>
    </SheetFooter>
  </SheetContent>
</Sheet>
```

## API [#api]

| Part | Prop | Type | Default |
| ---- | ---- | ---- | ------- |
| `Sheet` | `open` | `boolean` | uncontrolled |
| `Sheet` | `onOpenChange` | `(open: boolean) => void` | none |
| `Sheet` | `dismissible` | `boolean` | `true` |
| `SheetTrigger` | `disabled` | `boolean` | `false` |
| `SheetClose` | `disabled` | `boolean` | `false` |
| `SheetContent` | `side` | "left" \| "right" \| "top" \| "bottom" | `"right"` |
| `SheetContent` | `size` | "sm" \| "md" \| "lg" | `"md"` |
| `SheetContent` | `label` | `string` (required) | none |
| `SheetContent` | `grabber` | `boolean` — the vaul handle on a top/bottom sheet | `true` |
| `SheetContent` | `initialFocus` | `() => number \| null` | none |
| `SheetHeader` | `children` | `ReactNode` | — |
| `SheetTitle` | `children` | `ReactNode` | — |
| `SheetDescription` | `children` | `ReactNode` | — |
| `SheetFooter` | `children` | `ReactNode` | — |

---

# Shimmer

Source: https://gpuixui.sudokw.com/components/shimmer

A travelling highlight painted into text, or a surface band over children the runtime cannot recolour

<ComponentPreview name="shimmer-demo" />

## Usage [#usage]

```tsx
import { Shimmer } from "@gpuixui/components/shimmer";

// A plain string is inked one code point at a time from the travelling profile.
<Shimmer label="Generating a reply" durationMs={2000}>
  Generating a reply…
</Shimmer>;

// A finished surface: the text rests and no profile runs.
<Shimmer active={false}>Done</Shimmer>;

// Composed children cannot be recoloured, so they keep the surface band.
<Shimmer label="Reading the conversation">
  <Card>
    <Text role="body">The assistant is reading the conversation.</Text>
  </Card>
</Shimmer>;
```

A **string** child is a text run: every code point is its own text host and
takes the profile's ink at its place in the line. Any **other** child keeps the
surface band — a row of thin two-stop ramps over the content — because the
runtime cannot recolour a tree it did not build.

## Two drawings, honestly [#two-drawings-honestly]

The browser can put a gradient *inside* the glyphs with `background-clip: text`.
The native runtime cannot: it has no mask and no background-clip, and a `<text>`
host paints one `color`. So the native component does the strongest thing it can
and says what it is:

- **A string child** is split into words and code points. Each code point takes
  one colour sampled from the same triangular profile the band uses, blending
  from the theme's `mutedForeground` toward the chosen accent. The sheen is discrete
  at glyph resolution, not a continuous fill.
- **Any other child** keeps the band: `SHIMMER_STEPS` (16) strips, each a
  two-stop ramp between neighbouring samples of that profile, stepping once per
  `durationMs / SHIMMER_STEPS` (125 ms at the default).

The two paths are not the same drawing, and neither is presented as the other.
The browser preview puts the gradient in the text; the native string path is the
closest the runtime gets to it.

## API [#api]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `children` | `ReactNode` | none | a string is inked per code point; any other child keeps the surface band |
| `active` | `boolean` | `true` | whether the profile runs; false rests the text and paints no band |
| `durationMs` | `number` | `2000` | one complete sweep; an unusable value falls back to two seconds |
| `accent` | `"foreground" \| "primary" \| "muted"` | `"foreground"` | the role the highlight paints; a text run blends toward it from the muted role, a band paints it at a low alpha |
| `role` | text role | `"body"` | the typographic role a text run paints |
| `label` | `string` | none | an accessible name; when set, the surface is a `status` node, and a blank name is decoration |
| `reducedMotion` | `boolean` | the motion provider | rests the text, paints no band and schedules no interval |
| `className` | `string` | — | joined after the surface recipe, so it wins conflicts |
| `style` | `StyleState<ShimmerState>` | — | a style, or a function of the frame's `peak`, `active` and `reducedMotion` |
| `testId` | `string` | — | stable locator; a text run is `testId-ink`, a band is `testId-overlay` |

---

# Sidebar

Source: https://gpuixui.sudokw.com/components/sidebar

The persistent navigation panel, collapsible to icons

<ComponentPreview name="sidebar-demo" />

## Usage [#usage]

```tsx
import {
  Sidebar,
  SidebarContent,
  SidebarFooter,
  SidebarGroup,
  SidebarGroupContent,
  SidebarGroupLabel,
  SidebarHeader,
  SidebarInset,
  SidebarMenu,
  SidebarMenuButton,
  SidebarMenuItem,
  SidebarProvider,
  SidebarRail,
  SidebarTrigger,
  SidebarUserMenu,
} from "@gpuixui/components";

<SidebarProvider collapsible="icon">
  <Sidebar>
    <SidebarHeader>…</SidebarHeader>
    <SidebarContent>
      <SidebarGroup>
        <SidebarGroupLabel>Platform</SidebarGroupLabel>
        <SidebarGroupContent>
          <SidebarMenu>
            <SidebarMenuItem>
              <SidebarMenuButton label="Playground" tooltip="Playground" isActive>
                <Icon name="terminal" size="sm" color={theme.colors.accentForeground} />
              </SidebarMenuButton>
            </SidebarMenuItem>
          </SidebarMenu>
        </SidebarGroupContent>
      </SidebarGroup>
    </SidebarContent>
    <SidebarFooter>
      <SidebarUserMenu user={{ name: "Benji", email: "benji@example.com" }} />
    </SidebarFooter>
    <SidebarRail />
  </Sidebar>
  <SidebarInset>
    <SidebarTrigger />
  </SidebarInset>
</SidebarProvider>;
```

## Composition [#composition]

```text
SidebarProvider
├── Sidebar
│   ├── SidebarHeader
│   │   └── SidebarMenu
│   │       └── SidebarMenuItem
│   │           ├── SidebarMenuButton
│   │           ├── SidebarMenuAction
│   │           └── SidebarMenuBadge
│   ├── SidebarContent
│   │   └── SidebarGroup
│   │       ├── SidebarGroupLabel
│   │       ├── SidebarGroupAction
│   │       └── SidebarGroupContent
│   │           └── SidebarMenu
│   │               └── SidebarMenuItem
│   │                   ├── SidebarMenuButton
│   │                   └── SidebarMenuSub
│   │                       └── SidebarMenuSubItem
│   │                           └── SidebarMenuSubButton
│   ├── SidebarFooter
│   │   └── SidebarUserMenu
│   └── SidebarRail
└── SidebarInset
```

`Sidebar` renders its children once. On a window narrower than 768px that tree
is the modal sheet; the parts are the same, so a panel does not need a second
layout for mobile.

## Behaviour [#behaviour]

- **Collapsing** is `collapsible`: `"offcanvas"` parks the panel outside the
  window edge, `"icon"` shrinks it to a 48px rail (64px for the floating and
  inset variants, which keep their `p-2` gutter), and `"none"` leaves it fixed.
  The gap in the flow pays the same width, so the content beside it moves by
  exactly the panel it loses.
- **The keyboard** is ⌘/Ctrl + B. `SIDEBAR_KEYBOARD_SHORTCUT` is exported, and
  `toggleSidebar()` is on `useSidebar()`. On a narrow window the shortcut opens
  and closes the sheet.
- **The open state persists** through `SidebarPreference`: the default jar uses
  shadcn's `sidebar_state` key and seven-day lifetime, in process memory. Pass
  `preference` to keep it across launches.
- **Icon mode** clips the label and publishes the row's `tooltip`; only one tip
  can be open, and the active row keeps its accent. `badge`, `action` and
  sub-menus hide with the labels, as shadcn's selectors do.
- **The mobile sheet** is a `role="dialog"` with a scrim: pressing the scrim
  dismisses it, Tab wraps inside it, Escape closes it, and focus returns to the
  trigger. The desktop state is untouched.
- **The rail** toggles on a press and on an 8px drag toward its edge. It stays
  at the window edge while an offcanvas panel is parked, so the panel can be
  reopened.

## API [#api]

| Part | Renders | Props |
| ---- | ------- | ----- |
| `SidebarProvider` | a full-size row and the state | `defaultOpen?`, `open?`, `onOpenChange?`, `preference?`, `side?`, `variant?`, `collapsible?`, `width?`, `iconWidth?`, `mobileWidth?`, `className?`, `style?`, `children` |
| `Sidebar` | the panel, or the sheet below 768px | `side?`, `variant?`, `collapsible?`, `className?`, `style?`, `children` |
| `SidebarTrigger` | the toggle action | `size?` |
| `SidebarRail` | the edge strip | `className?`, `style?` |
| `SidebarInset` | `role="main"` content | `className?`, `style?`, `children` |
| `SidebarHeader` | the heading block | `className?`, `children` |
| `SidebarContent` | the scrolling middle | `className?`, `style?`, `children` |
| `SidebarFooter` | the footer block | `className?`, `children` |
| `SidebarSeparator` | a hairline | `className?`, `style?` |
| `SidebarGroup` | a labelled group | `className?`, `children` |
| `SidebarGroupLabel` | the group heading (text) | `children?`, `className?` |
| `SidebarGroupAction` | an icon-only group action | `label`, `children?`, `className?` |
| `SidebarGroupContent` | the rows under a heading | `className?`, `children` |
| `SidebarMenu` | `role="list"` | `className?`, `children` |
| `SidebarMenuItem` | `role="listitem"` | `className?`, `children` |
| `SidebarMenuButton` | a row action | `label?`, `isActive?`, `variant?`, `size?`, `tooltip?`, `disabled?`, `children?`, `trailing?`, `className?`, `onClick?` |
| `SidebarMenuAction` | a row's trailing action | `label`, `showOnHover?`, `children?`, `className?` |
| `SidebarMenuBadge` | a row's count | `children?`, `className?` |
| `SidebarMenuSkeleton` | a loading row | `showIcon?`, `className?` |
| `SidebarMenuSub` | a submenu list | `className?`, `children` |
| `SidebarMenuSubItem` | one submenu row | `className?`, `children` |
| `SidebarMenuSubButton` | a submenu action | `label?`, `isActive?`, `size?`, `disabled?`, `children?`, `className?`, `onClick?` |
| `SidebarInput` | a plain field at the panel height | `value?`, `placeholder?`, `readOnly?`, `disabled?`, `className?`, `style?`, `testId?`, `onChange?` |
| `useSidebar` | the context | returns `state`, `open`, `setOpen`, `openMobile`, `setOpenMobile`, `isMobile`, `toggleSidebar`, `side`, `variant`, `collapsible`, `tooltip`, `showTooltip`, `hideTooltip` |

`SIDEBAR_WIDTH`, `SIDEBAR_WIDTH_ICON`, `SIDEBAR_WIDTH_MOBILE`, `SIDEBAR_BREAKPOINT`
and `SIDEBAR_KEYBOARD_SHORTCUT` are exported from the component module.

## Widths and the shortcut [#widths-and-the-shortcut]

`width` (default 256, shadcn's 16rem), `iconWidth` (48, 3rem) and `mobileWidth`
(288, 18rem) are shadcn's CSS variables as numbers a caller can override. A
non-finite, zero or negative value reads as the default.

The provider hears Cmd/Ctrl+B through the keys that bubble inside its subtree.
GPUix delivers window keys only to the application's render handler, so an app
that wants the shortcut to work with focus outside the sidebar forwards its root
`onKeyDown` through `isSidebarShortcut(event)` — the same rule the provider runs.

---

# Skeleton

Source: https://gpuixui.sudokw.com/components/skeleton

A placeholder block that reserves the box content will paint

<ComponentPreview name="skeleton-states" />

<ComponentPreview name="skeleton-list" />

## Usage [#usage]

```tsx
import { Skeleton } from "@gpuixui/components/skeleton";

<Skeleton width="45%" height={14} />;
<Skeleton width={40} height={40} circle />;
<Skeleton width={120} height={20} animate={false} />;
```

`animate` is the shadcn switch. Leaving it out lets the app's `MotionProvider`
decide; `false` paints one frame and schedules no timer, which is the still
image a reduced-motion preference asks for.

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `animate` | `boolean` | the motion provider |
| `width` | `number \| string` | `"100%"` |
| `height` | `number \| string` | the body line height |
| `radius` | `"none" \| "sm" \| "md" \| "lg" \| "xl" \| "full"` | `"sm"` |
| `circle` | `boolean` | `false` |
| `style` | `StyleDesc` | — |
| `className` | `string` | — |
| `testId` | `string` | — |
| `ref` / `aria-id` / `onLayout` | host props | — |

## Theming [#theming]

The block paints the theme's `skeleton` role, which the token contract measures
on every strip a placeholder can stand in — the page, a card, a popover and a
muted toolbar — so a switched platform style repaints it without a component
change.

---

# Slider

Source: https://gpuixui.sudokw.com/components/slider

One value on a track, or the two ends of a range

<ComponentPreview name="slider-values" />

## Usage [#usage]

```tsx
import { Slider } from "@gpuixui/components/slider";

<Slider label="Volume" defaultValue={40} onValueChange={setVolume} />;

// A pair paints two thumbs; the ends are kept in order.
<Slider label="Price" defaultValue={[20, 80]} min={0} max={200} step={5} />;
```

The shape of `value` chooses the surface: a number is one thumb, a
`[from, to]` pair is a range. A pair passed as `[70, 20]` paints as `20 … 70`,
and each end stops on the other rather than crossing it.

## Keyboard [#keyboard]

| Key | Effect |
| --- | ------ |
| `ArrowRight` / `ArrowUp` | one `step` forward |
| `ArrowLeft` / `ArrowDown` | one `step` back |
| `PageUp` / `PageDown` | ten steps |
| `Home` / `End` | the track's ends |

A disabled slider stays out of the tab order and answers none of these keys.

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `value` | `number \| readonly [number, number]` | — |
| `defaultValue` | `number \| readonly [number, number]` | — |
| `onValueChange` | `(value: SliderValue) => void` | — |
| `onValueCommit` | `(value: SliderValue) => void` | — |
| `min` | `number` | `0` |
| `max` | `number` | `100` |
| `step` | `number` | `1` (`0` is continuous) |
| `disabled` | `boolean` | `false` |
| `invalid` | `boolean` | `false` |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |
| `label` | `string` | — |
| `description` | `string` | — |
| `formatValue` | `(value: number) => string` | `String(value)` |
| `className` | `string` | — |
| `testId` | `string` | — |
| `style` | `StyleDesc` | — |
| `ref` / `aria-id` / `onLayout` | host props | — |

---

# Sliding number

Source: https://gpuixui.sudokw.com/components/sliding-number

A number whose digits roll like a counter

<ComponentPreview name="sliding-number-demo" />

## Installation [#installation]

```bash
nub add @gpuixui/components
```

## Usage [#usage]

```tsx
import { SlidingNumber } from "@gpuixui/components/sliding-number";

<SlidingNumber value={deploys} role="display" label={`${deploys} deploys`} />;
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `value` | `number` | — |
| `decimals` | `number` | `0` |
| `prefix` | `string` | — |
| `suffix` | `string` | — |
| `label` | `string` | the reading |
| `level` | `MotionLevel` | `"normal"` |
| `role` | `TextRole` | `"body"` |
| `className` | `string` | — |
| `style` | `StateStyle<{ value, text, reducedMotion }>` | — |

---

# Spinner

Source: https://gpuixui.sudokw.com/components/spinner

A ring of ticks whose lit arc steps around the circle, in three sizes

<ComponentPreview name="spinner-sizes" />

<ComponentPreview name="spinner-in-buttons" />

## Usage [#usage]

```tsx
import { Spinner } from "@gpuixui/components/spinner";

<Spinner label="Refreshing revenue" />;
<Spinner size="sm" />;
<Spinner size="lg" accent="muted" label="Archiving" />;
```

`size` is a step on the theme's icon scale, so a spinner lines up with the text
or glyph beside it. A button takes the same mark through `Button`'s `loading`
prop instead of composing one.

## The anatomy, and why it steps [#the-anatomy-and-why-it-steps]

The reference spinner is a loader circle: one arc of a ring, turning. That
anatomy is what this mark keeps — a ring, a gap, an arc — but the runtime cannot
rotate it. `@gpuix/native@0.11.0` publishes no `transform`, so the ring is
**composed from static ticks** (`spinnerTicks` places 12 of them on a circle) and
the **lit arc** moves instead: the head is opaque, the seven ticks behind it fade
to a fifth, and the other five are empty. One tick advances per interval, so the
gap travels around the circle rather than the ring turning.

`MotionProvider preference="reduced"` — or `reducedMotion` on this spinner —
holds the resting arc and schedules no interval. The preview above is a browser
drawing: it paints the same geometry and steps it on the same cadence.

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` |
| `label` | `string` | the provider's `loading.busy` (`"Loading"`) |
| `accent` | `"primary" \| "destructive" \| "muted" \| "on-primary" \| "on-secondary" \| "on-destructive" \| "on-accent" \| "on-disabled"` | `"primary"` |
| `reducedMotion` | `boolean` | the motion provider |
| `className` | `string` | — |
| `style` | `StyleDesc` | — |
| `testId` | `string` | — |
| `ref` / `aria-id` / `onLayout` | host props | — |

---

# Stepper

Source: https://gpuixui.sudokw.com/components/stepper

Progress through named steps, from one value

<ComponentPreview name="stepper-workflow" />

## Installation [#installation]

<Install packageName="@gpuixui/components" importName="Stepper" />
<ComponentSource
  name="stepper"
  file="packages/components/src/stepper.tsx"
/>

## Usage [#usage]

```tsx
import { Stepper, StepperStep } from "@gpuixui/components";

<Stepper label="Checkout" value={2}>
  <StepperStep description="Email and password" label="Account" value={1} />
  <StepperStep description="Card and address" label="Billing" value={2} />
  <StepperStep label="Review" value={3} />
</Stepper>;
```

## Composition [#composition]

```text
Stepper
└── StepperStep
```

## API reference [#api-reference]

### `Stepper` [#stepper]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `value` | `number` | — | the current step, 1-based; steps below it are complete |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` — a stored name the union does not carry | a row of steps, or a column for a sidebar |
| `label` | `string` | none | the list's accessible name (`aria-label`) |
| `children` | `ReactNode` | — | `StepperStep` parts, in order |
| `style` | `StyleDesc` | — | merged last |
| `className` | `string` | — | joined last |
| `testId` | `string` | — | stable locator |

### `StepperStep` [#stepperstep]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `value` | `number` | — | this step's position, 1-based, on the root's scale |
| `label` | `string` | — | the step's name and its accessible name |
| `description` | `string` | none | support copy under the name |
| `style` | `StateStyle<StepperStepState>` | — | merged last |
| `className` | `string` | — | joined last |
| `testId` | `string` | — | stable locator |

---

# Switch

Source: https://gpuixui.sudokw.com/components/switch

An immediate on/off pill with a sliding knob

<ComponentPreview name="switch-workflow" />

## Installation [#installation]

<Install packageName="@gpuixui/primitives" importName="Switch" />
<ComponentSource
  name="switch"
  file="packages/primitives/src/components/Switch.tsx"
/>

## Usage [#usage]

```tsx
import { Switch } from "@gpuixui/primitives";
import { useState } from "react";

export const Theme = () => {
  const [dark, setDark] = useState(false);

  return (
    <Switch
      checked={dark}
      label="Dark theme"
      onCheckedChange={setDark}
    />
  );
};
```

## Composition [#composition]

```text
Switch
└── SwitchThumb
```

## API reference [#api-reference]

### `Switch` [#switch]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `checked` | `boolean` | — | controlled state; omit to let the switch keep its own |
| `defaultChecked` | `boolean` | `false` | initial state when uncontrolled |
| `onCheckedChange` | `(next: boolean) => void` | none | the next boolean, only when it changed |
| `onChange` | `(next: boolean) => void` | none | deprecated alias for `onCheckedChange`; the new name wins when both are passed |
| `children` | `ReactNode` | none | a glyph on the knob |
| `disabled` | `boolean` | `false` | refuses pointer and keys and leaves the tab order |
| `invalid` | `boolean` | `false` | an off pill takes the destructive edge |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | the pill's height from `iconSize`; the band stays 24px |
| `accent` | `"primary" \| "destructive"` | `"primary"` | the checked fill and the knob's on-colour |
| `label` | `string` | none | the accessible name; a visible `Label` does not supply it |
| `description` | `string` | none | announced help (`aria-description`); wins over a tooltip's text |
| `reducedMotion` | `boolean` | the provider's preference (`false` when none) | the knob lands on its position instead of sliding there; the slide is the timing table's `fast` level (160 ms) on its `standard` curve; the prop wins |
| `style` | `StateStyle<SwitchState>` | — | resolved against the live state and merged last |
| `className` | `string` | — | joined after the recipe, so it wins conflicts |
| `testId` | `string` | — | stable locator |
| `ref` / `aria-id` / `onLayout` | host address | none | the press band is the addressed element: focus it, measure it, and name it for automation |
| `onMouseEnter` / `onMouseLeave` / `aria-description` | the tooltip trigger pair and its words | none | forwarded to the press band, so a switch can be a `Tooltip` trigger; the tip's words land on the same help channel |
| `onClick` / `onKeyDown` / `onKeyUp` / `onFocus` / `onBlur` | host handlers | none | composed with the switch's own; yours runs first |

### `SwitchThumb` [#switchthumb]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `children` | `ReactNode` | the plain filled knob | a glyph on the knob |
| `className` | `string` | — | compiled through the recipe, joined after the thumb's rules |
| `style` | `StyleDesc` | — | merged last |

---

# Table

Source: https://gpuixui.sudokw.com/components/table

A bounded grid with a pinned header and sortable columns

<ComponentPreview name="table-workflow" />

<ComponentPreview name="table-states" />

## Installation [#installation]

<Install packageName="@gpuixui/data" importName="Table" />
<ComponentSource name="table" file="packages/data/src/table/table.tsx" />

## Usage [#usage]

```tsx
import {
  Table,
  TableBody,
  TableCell,
  TableHeader,
  TableHeaderCell,
  TableRow,
  TableViewport,
  useColumns,
  useTable,
} from "@gpuixui/data";

const columns = useColumns({
  columns: [
    { id: "service", label: "Service", width: 260 },
    { id: "environment", label: "Environment", width: 140 },
  ],
});

const table = useTable({
  rows,
  keyOf: (row) => row.id,
  columns: [
    { id: "service", valueOf: (row) => row.service },
    { id: "environment", valueOf: (row) => row.environment },
  ],
  hiddenColumns: columns.hidden,
});

<Table aria-label="Deploy queue" height={320}>
  <TableViewport>
    <TableHeader>
      <TableRow>
        <TableHeaderCell width={260}>Service</TableHeaderCell>
        <TableHeaderCell width={140}>Environment</TableHeaderCell>
      </TableRow>
    </TableHeader>
    <TableBody>
      {table.rows.map((row) => (
        <TableRow
          key={row.id}
          onClick={(event) => table.press(row.id, event.modifiers)}
          selected={table.isSelected(row.id)}
        >
          <TableCell width={260}>{row.service}</TableCell>
          <TableCell width={140}>{row.environment}</TableCell>
        </TableRow>
      ))}
    </TableBody>
  </TableViewport>
</Table>;
```

## Composition [#composition]

```text
Table
└── TableViewport
    ├── TableHeader
    │   └── TableHeaderCell
    ├── TableBody
    │   └── TableRow
    │       └── TableCell
    ├── TableCaption
    ├── TableEmpty
    └── TableSkeleton
```

## API reference [#api-reference]

### Table [#table]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `height` | `number` — a definite height; the header stays painted and the body scrolls | — |
| `children` | `ReactNode` — a `TableHeader`, an optional `TableSkeleton`, one `TableBody` | — |
| `className` | `string` — joined after the recipe, so it wins conflicts | — |

### TableViewport, TableHeader, TableBody [#tableviewport-tableheader-tablebody]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `rows` | `number` — the skeleton's row count when the body has no children | `3` |
| `height` | `number` — the body height `Table` measures and hands down | measured |
| `children` | `ReactNode` — the rows, or the header cells the part owns | — |
| `className` | `string` | — |

### TableRow [#tablerow]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `selected` | `boolean` — the chosen record's wash and label role | `false` |
| `disabled` | `boolean` — no press, no pointer cursor | `false` |
| `instanceRef` | `Ref<PublicInstance>` — the painted element, for `renderer.focusElement` | — |
| `children` | `ReactNode` — the row's cells | — |
| `className` | `string` | — |

### TableHeaderCell, TableCell [#tableheadercell-tablecell]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `width` | `number` — a fixed track; omitted, the cell shares the leftover width | — |
| `align` | `"left" \| "center" \| "right"` | `"left"` |
| `children` | `ReactNode` — the cell's text or element | — |
| `className` | `string` | — |

### TableSkeleton [#tableskeleton]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `rows` | `number` — bars, one row each | `3` |
| `columns` | `number` — bars per row | `3` |

### TableSortHeader [#tablesortheader]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `field` | `string` — the field a press reports | — |
| `label` | `string` — the visible label and the base of the accessible name | — |
| `sort` | `Option<SortState>` — the primary sort, for a single-sort consumer | — |
| `order` | `SortOrder` — the whole order, primary first | `sort` alone |
| `initialDirection` | `"asc" \| "desc"` — the direction a first press starts at | `"asc"` |
| `onSort` | `(next: SortState) => void` — the single-column contract | — |
| `onSortPress` | `(field, initialDirection, modifiers) => void` — the raw press, so the controller can compose an order | — |
| `width` | `number` — a fixed track | — |
| `align` | `"left" \| "center" \| "right"` | `"left"` |
| `resize` | `TableColumnResizeProps` — the divider; needs a fixed `width` | — |
| `testId` | `string` | — |

### The sort surface `useTable` exposes [#the-sort-surface-usetable-exposes]

| Member | Type | Consequence |
| ------ | ---- | ----------- |
| `sort` | `Option<SortState>` | the primary entry, for a single-sort readout or header |
| `sortOrder` | `SortOrder` | every sorted field, primary first — what the rows and the header read |
| `setSort` | `(sort: Option<SortState>) => void` | replace the order with one entry, or none |
| `toggleSort` | `(field: string, additive?: boolean) => void` | the press cycle; `additive` keeps the order and adds a tie-break |
| `pressSort` | `(field, initialDirection, modifiers?) => void` | the raw press; `modifiers.shift` is what sets `additive` |
| `rows` | `ReadonlyArray<Row>` | filtered by the query, then ordered by every entry in turn |

---

# Tabs

Source: https://gpuixui.sudokw.com/components/tabs

A roving-focus tab list and the panels it switches

<ComponentPreview name="tabs-demo" />

## Installation [#installation]

<Install packageName="@gpuixui/components" importName="Tabs" />
<ComponentSource name="tabs" file="packages/components/src/tabs.tsx" />

## Usage [#usage]

```tsx
import {
  Tabs,
  TabsContent,
  TabsList,
  TabsTrigger,
} from "@gpuixui/components/tabs";

<Tabs defaultValue="profile">
  <TabsList label="Account settings">
    <TabsTrigger value="profile">Profile</TabsTrigger>
    <TabsTrigger value="notifications">Notifications</TabsTrigger>
  </TabsList>
  <TabsContent value="profile">…</TabsContent>
  <TabsContent value="notifications">…</TabsContent>
</Tabs>;
```

## Composition [#composition]

```text
Tabs
├── TabsList
│   └── TabsTrigger
└── TabsContent
```

## API reference [#api-reference]

### Tabs [#tabs]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `value` | `string` | uncontrolled |
| `defaultValue` | `string` | `""` — no tab selected |
| `onValueChange` | `(value: string) => void` | none |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` — a stored name the union does not carry |
| `activation` | `"automatic" \| "manual"` | `"automatic"` — a stored name the union does not carry |
| `className` | `string` | — |
| `children` | parts — `TabsList`, `TabsContent` | — |

### TabsList [#tabslist]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `label` | `string` | none |
| `variant` | `"pill" \| "line"` | `"pill"`; `"line"` draws a thin bar under the chosen tab |
| `className` | `string` | — |
| `children` | parts — `TabsTrigger` | — |

### TabsTrigger [#tabstrigger]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `value` | `string` (required) | none |
| `disabled` | `boolean` | `false` |
| `style` | `StyleDesc \| (state) => StyleDesc` | none |
| `className` | `string` | — |

---

# Tag input

Source: https://gpuixui.sudokw.com/components/tag-input

Keywords entered through a field, as removable chips

<ComponentPreview name="tag-input-workflow" />

## Installation [#installation]

<Install packageName="@gpuixui/components" importName="TagInput" />
<ComponentSource
  name="tagInput"
  file="packages/components/src/tag-input.tsx"
/>

## Usage [#usage]

```tsx
import {
  TagInput,
  TagInputChip,
  TagInputField,
} from "@gpuixui/components/tag-input";
import { useState } from "react";

export const Keywords = () => {
  const [keywords, setKeywords] = useState<ReadonlyArray<string>>(["design"]);

  return (
    <TagInput
      label="Package keywords"
      max={5}
      hint="5 max"
      caption={`${keywords.length} of 5 keywords`}
      value={keywords}
      onValueChange={setKeywords}
    >
      {keywords.map((keyword) => (
        <TagInputChip key={keyword} value={keyword} />
      ))}
      <TagInputField aria-label="Add a keyword" placeholder="Add a keyword…" />
    </TagInput>
  );
};
```

## Composition [#composition]

```text
TagInput
├── TagInputChip
└── TagInputField
```

## API reference [#api-reference]

### `TagInput` [#taginput]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `value` | `ReadonlyArray<string>` | — | the tokens; the caller owns and renders them, and a stored value that is not a list carries no tokens |
| `onValueChange` | `(value: ReadonlyArray<string>) => void` | — | the list after every accepted edit, including a removal |
| `label` | `string` | — | the group's accessible name |
| `max` | `number` | none | additions past it are refused; the chips stay |
| `allowDuplicates` | `boolean` | `false` | a repeated token is accepted as its own chip |
| `disabled` | `boolean` | `false` | refuses every edit path and renders no removal control |
| `hint` | `string` | none | a quiet note at the end of the field; blank renders nothing |
| `caption` | `string` | none | a caption under the field for the caller's preset or limit; blank renders nothing |
| `children` | `PartChildren` | — | `TagInputChip` and `TagInputField`, directly inside |
| `className` | `string` | — | joined after the outer recipe, so it wins conflicts |
| `style` | `StyleDesc` | — | merged last over the recipe |
| `testId` | `string` | — | stable locator for the group |

### `TagInputField` [#taginputfield]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `placeholder` | `string` | none | painted in the `placeholder` role while the draft is empty |
| `className` | `string` | — | joined after the field recipe |
| `style` | `StateStyle<TagInputFieldState>` | — | resolved against `{ disabled }` and merged last |
| `testId` | `string` | — | the input's locator; the painted hint follows it |
| `onKeyDown` / `onFocus` / `onBlur` | host handlers | none | composed with the component's own; yours runs first |
| `label` / `description` / `invalid` | `string` · `string` · `boolean` | none · none · `false` | the field's name, its announced help, and the invalid edge |
| `disabled` / `readOnly` / `autoFocus` | `boolean` | `false` | inherited from the root's `disabled`, an uneditable field, and focus on mount |
| `size` / `fullWidth` / `tabIndex` | `"sm" \| "md" \| "lg"` · `boolean` · `number` | `"md"` · `false` · the field's place | the input's height, its width, and its tab stop |
| `ref` / `aria-id` / `onLayout` | the addressed element | none | the draft input: focus it, measure it, name it for automation |
| `onClick` / `onKeyUp` | host handlers | none | composed with the field's own; yours runs first |
| `onValueChange` / `defaultValue` | the field surface it inherits — see `Input` | none | the draft the field keeps before the tag is committed |

### `TagInputChip` [#taginputchip]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `value` | `string` | — | the token this chip removes; also its key |
| `className` | `string` | — | joined after the chip recipe |
| `style` | `StateStyle<TagInputChipState>` | — | resolved against `{ disabled }` and merged last |
| `testId` | `string` | none | the removal control is addressable as `<testId>-remove` |

---

# Theme toggler

Source: https://gpuixui.sudokw.com/components/theme-toggler

The control that switches light and dark

<ComponentPreview name="theme-toggler-demo" />

## Installation [#installation]

```bash
nub add @gpuixui/components
```

## Usage [#usage]

```tsx
import { useState } from "react";
import {
  ThemeProvider,
  ThemeToggler,
  darkTheme,
  lightTheme,
} from "@gpuixui/components";

const [mode, setMode] = useState<"light" | "dark">("dark");

<ThemeProvider theme={mode === "dark" ? darkTheme : lightTheme}>
  <ThemeToggler mode={mode} onChange={setMode} />
</ThemeProvider>;
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `mode` | `"light" \| "dark"` | — |
| `onChange` | `(mode: "light" \| "dark") => void` | — |
| `lightLabel` | `string` | `"Switch to light theme"` |
| `darkLabel` | `string` | `"Switch to dark theme"` |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` |
| `level` | `SurfaceLevel` | `"slow"` |
| `className` | `string` | — |
| `style` | `StateStyle<ThemeTogglerState>` | — |

---

# Time picker

Source: https://gpuixui.sudokw.com/components/time-picker

A time of day, entered as an HH:mm field

<ComponentPreview name="time-picker-workflow" />

## Installation [#installation]

<Install packageName="@gpuixui/components" importName="TimePicker" />
<ComponentSource name="timePicker" file="packages/components/src/time-picker.tsx" />

## Usage [#usage]

```tsx
import {
  TimePicker,
  TimePickerClear,
  TimePickerSegment,
  TimePickerSeparator,
} from "@gpuixui/components/time-picker";
import { Button } from "@gpuixui/primitives";
import { useState } from "react";

export const DeploymentWindow = () => {
  const [opens, setOpens] = useState<string | null>("09:30");
  const [saved, setSaved] = useState<string | null>(null);

  return (
    <>
      <TimePicker
        clearable
        label="Opens at"
        minuteStep={15}
        onValueChange={(next) => {
          setOpens(next);
          setSaved(null);
        }}
        value={opens}
      >
        <TimePickerSegment segment="hours" />
        <TimePickerSeparator />
        <TimePickerSegment segment="minutes" />
        <TimePickerClear />
      </TimePicker>
      {/* `opens` is `HH:mm` or `null`. */}
      <Button disabled={opens === null} onClick={() => setSaved(opens)}>
        {saved === null ? "Save window" : `Saved ${saved}`}
      </Button>
    </>
  );
};
```

## Composition [#composition]

```text
TimePicker
├── TimePickerSegment
├── TimePickerSeparator
└── TimePickerClear
```

## API reference [#api-reference]

### `TimePicker` [#timepicker]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `value` | `string \| null` | — | the controlled `HH:mm`; `undefined` makes the field uncontrolled |
| `defaultValue` | `string \| null` | `null` | the opening time when uncontrolled |
| `onValueChange` | `(value: string \| null) => void` | none | every accepted edit, including the clear path |
| `label` | `string` | `"Time"` | the group's accessible name, and the prefix of each segment's name |
| `minuteStep` | `number` | `1` | the arrow-key step, normalised to an integer in `1..59` |
| `clearable` | `boolean` | `false` | renders the clear control while a time is set |
| `disabled` | `boolean` | `false` | both segments become `readOnly`, leave the tab order, and no clear is rendered |
| `testId` | `string` | `"time-picker"` | the base id of the parts: `-hours`, `-minutes`, `-clear` |
| `className` | `string` | — | joined last |
| `children` | `ReactNode` | none | the segments, separator and clear control, directly inside |

### `TimePickerSegment` [#timepickersegment]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `segment` | `"hours" \| "minutes"` | required | which half this input edits, and the maximum it clamps to |
| `style` | `StateStyle<TimePickerSegmentState>` | the recipe | a style, or a function of `{ disabled, focused }` |

### `TimePickerSeparator` [#timepickerseparator]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `children` | `ReactNode` | `":"` | the painted separator |

### `TimePickerClear` [#timepickerclear]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `label` | `string` | `"Clear time"` | the control's accessible name |

---

# Timeline

Source: https://gpuixui.sudokw.com/components/timeline

A read-only rail of events the app marks

<ComponentPreview name="timeline-workflow" />

## Installation [#installation]

<Install packageName="@gpuixui/components" importName="Timeline" />
<ComponentSource
  name="timeline"
  file="packages/components/src/timeline.tsx"
/>

## Usage [#usage]

```tsx
import { Timeline, TimelineItem } from "@gpuixui/components";

<Timeline label="Release Aurora">
  <TimelineItem status="complete" timestamp="09:41" title="Build started" />
  <TimelineItem
    description="412 tests, 0 failures"
    status="complete"
    timestamp="09:44"
    title="Tests passed"
  />
  <TimelineItem status="current" timestamp="09:52" title="Deploying" />
  <TimelineItem status="upcoming" title="Smoke checks" />
</Timeline>;
```

## Composition [#composition]

```text
Timeline
└── TimelineItem
```

## API reference [#api-reference]

### `Timeline` [#timeline]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `label` | `string` | none | the list's accessible name (`aria-label`) |
| `children` | `ReactNode` | — | `TimelineItem` parts, passed directly |
| `style` | `StyleDesc` | — | merged last |
| `className` | `string` | — | compiled through `@gpuixui/tw`, joined after the recipe |
| `testId` | `string` | — | stable locator |

### `TimelineItem` [#timelineitem]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `title` | `string` | — | the event's name and its accessible name |
| `description` | `string` | none | one line of support copy under the title |
| `timestamp` | `string` | none | when it happened, as the consumer formats it |
| `status` | `"complete" \| "current" \| "upcoming"` | `"complete"` | the dot's fill, and whether the title is muted |
| `style` | `StateStyle<TimelineItemState>` | — | resolved against `{ status, last }`, merged last |
| `className` | `string` | — | joined after the recipe, so it wins conflicts |
| `testId` | `string` | — | stable locator |

---

# Toast

Source: https://gpuixui.sudokw.com/components/toast

A stacked, auto-dismissing notification queue

<ComponentPreview name="toast-workflow" />

<ComponentPreview name="toast-tones" />

## Installation [#installation]

<Install packageName="@gpuixui/components" importName="ToastProvider" />
<ComponentSource name="toast" file="packages/components/src/toast.tsx" />

## Usage [#usage]

```tsx
import { Duration } from "effect";
import { Button } from "@gpuixui/primitives";
import {
  ToastProvider,
  ToastViewport,
  useToast,
} from "@gpuixui/components/toast";

const PublishBar = () => {
  const toast = useToast();

  return (
    <Button
      onActivate={() =>
        toast.push(
          {
            title: "Changes published",
            description: "The site rebuilds in about a minute.",
            tone: "success",
            action: { label: "Undo" },
            duration: Duration.seconds(8),
          },
          { onAction: () => restore() },
        )
      }
    >
      Publish changes
    </Button>
  );
};

export const App = () => (
  <ToastProvider>
    <PublishBar />
    {/* Render the viewport last. */}
    <ToastViewport />
  </ToastProvider>
);
```

```tsx
const rows = await toast.promise(importRows(file), {
  loading: { title: "Importing rows", description: "Reading the file…" },
  success: (count) => ({ title: `Imported ${count} rows`, tone: "success" }),
  error: (cause) => ({ title: "Import failed", description: String(cause), tone: "danger" }),
});
```

## Composition [#composition]

```text
ToastProvider
└── ToastViewport
```

## API reference [#api-reference]

| Part | Prop | Type | Default |
| ---- | ---- | ---- | ------- |
| `ToastProvider` | `max` | `number` — toasts kept before the oldest is dropped | `3` |
| `ToastProvider` | `defaultDuration` | `Duration.Input` | 5 seconds |
| `ToastProvider` | `children` | the tree that may push | — |
| `ToastViewport` | `swipe` | `boolean` — sideways drag to dismiss | `true` |
| `ToastViewport` | `children` | an optional control before the stack | — |
| `ToastViewport` | `className` | `string` — joined after the recipe | — |
| `useToast` | `toasts` | `ReadonlyArray<Toast>` — oldest first | — |
| `useToast` | `push` | `(draft, options?) => void` — `title` required; `description`, `tone`, `duration`, `action`, `phase` optional | — |
| `useToast` | `promise` | `(p, { loading, success, error }) => Promise` — settles one row | — |
| `useToast` | `dismiss` | `(id: string) => void` | — |
| `useToast` | `dismissAll` | `() => void` | — |
| `useToast` | `pause` | `(id: string) => void` — stop one clock | — |
| `useToast` | `resume` | `(id: string) => void` — restart with the remaining time | — |
| `useToast` | `hold` | `(held: boolean) => void` — the stack's clock | — |
| `useToast` | `actionFor` | `(id: string) => Option<() => void>` — the queued handler | — |
| `ToastInput` | `title` | `string` — non-empty; empty input is dropped | required |
| `ToastInput` | `description` | `string` | — |
| `ToastInput` | `tone` | `"info" \| "success" \| "warning" \| "danger"` | `"info"` |
| `ToastInput` | `phase` | `"loading" \| "settled"` — a loading row has no clock | `"settled"` |
| `ToastInput` | `duration` | `Duration.Input` — `0` keeps it until dismissed | the provider's default |
| `ToastInput` | `action` | `{ label }` — the handler travels beside the draft | — |

---

# Toggle

Source: https://gpuixui.sudokw.com/components/toggle

A button that stays on, for a mode the next action uses

<ComponentPreview name="toggle-toolbar" />

## Usage [#usage]

```tsx
import { Toggle } from "@gpuixui/components/toggle";

<Toggle pressed={bold} onPressedChange={setBold} label="Bold">
  Bold
</Toggle>;

// An icon-only toggle still needs a name.
<Toggle square label="Grid view" leading={<Icon name="grid" color={colour} />} />;
```

A toggle is not a `Switch`: a switch changes a setting immediately, while a
toggle sets a mode for the next action ("bold", "grid view") and lives in a
toolbar beside other actions.

## Keyboard [#keyboard]

`Enter` activates on the key press and `Space` on the release, the platform's
button contract; a held key does not repeat the activation.

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `pressed` | `boolean` | — (uncontrolled) |
| `defaultPressed` | `boolean` | `false` |
| `onPressedChange` | `(pressed: boolean) => void` | — |
| `variant` | `"default" \| "outline"` | `"default"` |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` |
| `square` | `boolean` | `false` |
| `disabled` | `boolean` | `false` |
| `loading` | `boolean` | `false` |
| `loadingLabel` | `string` | the provider's `loading.busy` |
| `reducedMotion` | `boolean` | the motion provider |
| `leading` / `trailing` | `ReactNode` | — |
| `label` | `string` | the text children |
| `description` | `string` | — |
| `style` | `StateStyle<ToggleState>` | — |
| `className` | `string` | — |
| `testId` | `string` | — |
| `ref` / `aria-id` / `onLayout` | host props | — |

---

# Toggle group

Source: https://gpuixui.sudokw.com/components/toggle-group

A toolbar of related modes with one tab stop

<ComponentPreview name="toggle-group-toolbar" />

## Usage [#usage]

```tsx
import {
  ToggleGroup,
  ToggleGroupItem,
} from "@gpuixui/components/toggle-group";

<ToggleGroup type="single" label="Alignment" defaultValue="left">
  <ToggleGroupItem value="left" label="Align left">
    Left
  </ToggleGroupItem>
  <ToggleGroupItem value="centre" label="Align centre">
    Centre
  </ToggleGroupItem>
</ToggleGroup>;

<ToggleGroup type="multiple" label="Formatting" defaultValue={["bold"]}>
  <ToggleGroupItem value="bold" label="Bold">
    Bold
  </ToggleGroupItem>
  <ToggleGroupItem value="italic" label="Italic">
    Italic
  </ToggleGroupItem>
</ToggleGroup>;
```

`type="single"` keeps at most one mode on and clears it when the live option is
pressed again; `type="multiple"` lets any number stay on. The group is one tab
stop: the arrow keys move focus between options without pressing them.

## Keyboard [#keyboard]

| Key | Effect |
| --- | ------ |
| `ArrowRight` / `ArrowLeft` | move focus along a horizontal group |
| `ArrowDown` / `ArrowUp` | move focus along a vertical group |
| `Home` / `End` | the first or last enabled option |
| `Enter` / `Space` | press the focused option |

## API [#api]

| Part | Prop | Type | Default |
| ---- | ---- | ---- | ------- |
| `ToggleGroup` | `type` | `"single" \| "multiple"` | `"multiple"` |
| `ToggleGroup` | `value` | `string` for single, `readonly string[]` for multiple | — |
| `ToggleGroup` | `defaultValue` | the same shape as `value` | — |
| `ToggleGroup` | `onValueChange` | `(next: string) => void` or `(next: readonly string[]) => void` | — |
| `ToggleGroup` | `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` |
| `ToggleGroup` | `variant` | `"default" \| "outline"` | `"default"` |
| `ToggleGroup` | `size` | `"sm" \| "md" \| "lg"` | `"md"` |
| `ToggleGroup` | `square` | `boolean` | `false` |
| `ToggleGroup` | `disabled` | `boolean` | `false` |
| `ToggleGroup` | `label` | `string` | — |
| `ToggleGroup` | `description` | `string` | — |
| `ToggleGroup` | `options` / `children` | option data, or the item elements | — |
| `ToggleGroup` | `style` / `itemStyle` | `StateStyle<…>` | — |
| `ToggleGroup` | `className` | `string` | — |
| `ToggleGroup` | `testId` | `string` | — |
| `ToggleGroup` | `itemTestId` | `(value: string) => string` | — |
| `ToggleGroup` | `ref` / `aria-id` / `onLayout` | host props (on the tab stop) | — |
| `ToggleGroupItem` | `value` | `string` (required) | — |
| `ToggleGroupItem` | `label` | `string` (required) | — |
| `ToggleGroupItem` | `description` | `string` | — |
| `ToggleGroupItem` | `disabled` | `boolean` | `false` |
| `ToggleGroupItem` | `children` | `ReactNode` | `label` |

---

# Tooltip

Source: https://gpuixui.sudokw.com/components/tooltip

A short label on hover

<ComponentPreview name="tooltip-demo" />

<ComponentPreview name="tooltip-states" />

## Installation [#installation]

<Install packageName="@gpuixui/primitives" importName="Tooltip" />
<ComponentSource
  name="tooltip"
  file="packages/primitives/src/components/Tooltip.tsx"
/>

## Usage [#usage]

```tsx
import { Icon } from "@gpuixui/icons";
import { IconButton, Tooltip, useTheme } from "@gpuixui/primitives";

const theme = useTheme();

export const RevenueHelp = () => (
  <Tooltip content="Booked revenue, net of refunds." side="bottom">
    <IconButton
      icon={
        <Icon
          color={theme.colors.mutedForeground}
          name="info"
          size={theme.iconSize.sm}
        />
      }
      label="Revenue definition"
    />
  </Tooltip>
);
```

## Composition [#composition]

```text
Tooltip
├── trigger
└── tip
```

## API reference [#api-reference]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `content` | `ReactNode` | — (required) | the label; keep it short, the runtime does not wrap overlay content |
| `description` | `string` | `content` when it is a string | the trigger's accessible description; required for a non-text tip |
| `children` | `ReactNode` | — (required) | the trigger: a focusable host element, or a control that forwards the trigger pair |
| `side` | `FloatingSide` | `"top"` | the **preferred** side; the runtime moves the layer when it would leave the window |
| `align` | `FloatingAlign` | `"center"` | alignment against the trigger |
| `delay` | `number` | the provider's `0` | the hover delay in milliseconds |
| `open` | `boolean` | the runtime's state | takes the open state; the tip paints only while it is `true` |
| `defaultOpen` | `boolean` | `false` | starts open before any interaction; ignored while `open` is set |
| `onOpenChange` | `(open: boolean) => void` | — | every state the runtime asked for, controlled or not |
| `disableHoverableContent` | `boolean` | `false` | close as soon as the pointer leaves the trigger, instead of letting it cross onto the tip |
| `reducedMotion` | `boolean` | the provider's preference (`false` when none) | removes the journey — the tip lands at once and a close unmounts at once instead of holding the exit; the prop wins |
| `className` | `string` | — | joined after the tip's recipe, so it wins conflicts |
| `style` | `StyleDesc` | — | merged after the recipe **and** `className`, so it is the last word |
| `testId` | `string` | — | lands on the tip's surface |

`TooltipProvider` sets one timing for every tip below it.

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `delay` | `number` | the runtime's `0` | milliseconds before a tip opens; a tip's own `delay` wins |
| `skipDelay` | `number` | the runtime's `300` | the window after a close in which the next tip opens with no wait |
| `disableHoverableContent` | `boolean` | the runtime's `false` | close as soon as the pointer leaves the trigger, for every tip below |
| `children` | `ReactNode` | — (required) | the tree the provider covers |

---

# User menu

Source: https://gpuixui.sudokw.com/components/user-menu

An avatar and name that open the account actions

<ComponentPreview name="user-menu-demo" />

## Usage [#usage]

```tsx
import { UserMenu, SidebarUserMenu } from "@gpuixui/components";

const user = { name: "Benji", email: "benji@example.com" };

<UserMenu
  user={user}
  onUpgrade={() => undefined}
  onAccount={() => undefined}
  onBilling={() => undefined}
  onNotifications={() => undefined}
  onLogOut={() => undefined}
/>;
```

```tsx
<SidebarFooter>
  <SidebarUserMenu user={user} onLogOut={signOut} />
</SidebarFooter>;
```

## API [#api]

| Part | Renders | Props |
| ---- | ------- | ----- |
| `UserMenu` | the trigger and its account menu | `user`, `onUpgrade?`, `onAccount?`, `onBilling?`, `onNotifications?`, `onLogOut?`, `side?`, `align?`, `collapsed?`, `className?`, `testId?`, `menuTestId?` |
| `SidebarUserMenu` | `UserMenu` in `SidebarMenu` / `SidebarMenuItem` | the same, without `collapsed` (the sidebar supplies it) |

`user` is `{ name: string; email: string; avatar?: string }`. Without `avatar`
the avatar paints the initials.

---

# Primitives

Source: https://gpuixui.sudokw.com/primitives

The Tier 1 layer over GPUix host elements

<Install packageName="@gpuixui/primitives" importName="Stack" />

Five primitives live under [Components](/components):
[Button](/components/button), [Checkbox](/components/checkbox),
[Select](/components/select), [Switch](/components/switch) and
[Tooltip](/components/tooltip).

## Layout [#layout]

| Primitive | What it is |
| --------- | ---------- |
| [Box](/primitives/box) | The one container — a semantic surface and flex facts |
| [Stack](/primitives/stack) | Children along one axis, spaced by the theme scale |
| [Grid](/primitives/grid) | Equal tracks in two dimensions |
| [Separator](/primitives/separator) | One theme-coloured rule, with an optional caption |
| [Spacer](/primitives/spacer) | A fixed step, or a flexible filler |
| [ScrollArea](/primitives/scroll-area) | A bounded container that scrolls |

## Type and icons [#type-and-icons]

| Primitive | What it is |
| --------- | ---------- |
| [Text](/primitives/text) | One run of type, named by a theme role and a tone |
| [Label](/primitives/label) | A control's name, required marker and description |
| [Icons](/graphics/icons/icon) | 83 monochrome icons and their size scale |

## Actions [#actions]

| Primitive | What it is |
| --------- | ---------- |
| [Button](/components/button) | The primary action, with busy and disabled states |
| [Icon button](/primitives/icon-button) | A square, icon-only action with a required name |
| [Button group](/primitives/button-group) | A row of related actions |
| [Toggle](/primitives/toggle) | A button with a persistent on/off state |
| [Toggle group](/primitives/toggle-group) | Related modes in one toolbar |

## Text and numeric inputs [#text-and-numeric-inputs]

| Primitive | What it is |
| --------- | ---------- |
| [Input](/primitives/input) | A single-line text field |
| [Text area](/primitives/textarea) | A multi-line text field sized in rows |
| [Number field](/primitives/number-field) | A number field with steps and optional bounds |
| [OTP field](/primitives/otp-field) | A one-time code in length cells |

## Choice [#choice]

| Primitive | What it is |
| --------- | ---------- |
| [Select](/components/select) | One choice from a list |
| [Checkbox](/components/checkbox) | An independent yes/no, optionally indeterminate |
| [Checkbox group](/primitives/checkbox-group) | Several choices sharing one tab stop |
| [Radio group](/primitives/radio-group) | One choice from a small set |
| [Switch](/components/switch) | An immediate on/off |
| [Slider](/primitives/slider) | A value on a track |
| [Range slider](/primitives/range-slider) | The two ends of one interval |
| [Rating](/primitives/rating) | A whole number of stars, or none |

## Value and progress [#value-and-progress]

| Primitive | What it is |
| --------- | ---------- |
| [Progress](/primitives/progress) | A determinate or indeterminate progress bar |
| [Meter](/primitives/meter) | A measurement inside a range |

## Feedback [#feedback]

| Primitive | What it is |
| --------- | ---------- |
| [Skeleton](/primitives/skeleton) | A pulsing placeholder |
| [Spinner](/primitives/spinner) | Three dots, because the runtime cannot rotate |
| [Tooltip](/components/tooltip) | A short label on hover or keyboard focus |
| [Theme provider](/primitives/theme-provider) | Supplies the theme every primitive draws with |

## The icon set [#the-icon-set]

The glyphs live with the rest of the drawings, under
[Icons](/graphics/icons/icon): every icon the package ships, drawn from its own
markup.

---

# Box

Source: https://gpuixui.sudokw.com/primitives/box

A surface with tone, padding, radius, border and flex facts

<ComponentPreview name="box-demo" />

## Usage [#usage]

```tsx
import { Box, Text } from "@gpuixui/primitives";

<Box tone="card" padding="md" radius="md" border>
  <Text role="body">A surface with the card role.</Text>
</Box>;
```

## API [#api]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `tone` | `SurfaceTone` | required | the semantic background |
| `padding` | spacing step | none | padding on all four sides |
| `paddingX` / `paddingY` | spacing step | none | per-axis padding, overriding `padding` there |
| `radius` | `none \| sm \| md \| lg \| xl \| full` | none | corner radius; a stored name this release does not carry paints no corner |
| `border` | `boolean` | `false` | one thin border on the `border` role |
| `borderStyle` | `"solid" \| "dashed"` | `"solid"` | the edge style; no effect without `border` |
| `aspectRatio` | `number` | none | width ÷ height; a non-finite, zero or negative ratio is dropped |
| `elevation` | `sm \| md \| lg \| overlay` | none | the theme's shadow at that level; a stored level name this release does not carry paints `md`, the default lift, and the reserved `overlay` paints none |
| `grow` / `shrink` | `boolean` | `false` | flex growth, or allow shrinking below content |
| `fullWidth` / `fullHeight` | `boolean` | `false` | `100%` on that axis |
| `ref` | `Ref<PublicInstance>` | — | the painted element, for a measurement, a scroll or a focus call |
| `aria-id` | `string` | — | the element's author id, exposed as the platform's automation id |
| `onLayout` | `(event: EventPayload) => void` | — | the painted box after the first paint and each resize |
| `className` | `string` | — | a Tailwind class string, joined after the recipe so it wins conflicts |
| `style` | `StyleDesc` | — | merged last, so it wins property by property |
| `children` | `ReactNode` | — | content |
| `testId` | `string` | — | stable locator |

---

# ButtonGroup

Source: https://gpuixui.sudokw.com/primitives/button-group

A row or column of related actions, attached or separated

<ComponentPreview name="button-group-demo" />

## Usage [#usage]

```tsx
import { Button, ButtonGroup } from "@gpuixui/primitives";

<ButtonGroup mode="attached" label="Text alignment">
  <Button variant="ghost">Left</Button>
  <Button variant="secondary">Center</Button>
  <Button variant="ghost">Right</Button>
</ButtonGroup>;
```

## API [#api]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `mode` | `"attached" \| "separated"` | `"attached"` | zero gap + clipped group, or a spaced group; a stored name this release does not carry reads as the default (`buttonGroupModeOf`) |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | a row, or a column with one shared width; a stored name reads as the default (`buttonGroupOrientationOf`) |
| `gap` | spacing step, or `null` | `"sm"` | the gap in separated mode; a step the theme does not carry — including the `null` JSON writes for a field a record never set — reads as the documented default (`spaceStep`) |
| `label` | `string` | none | the group's accessible name, written as `aria-label` |
| `ref` | `Ref<PublicInstance>` | — | the group's own wrapper, the element that clips the two ends — not an action; press one through its `testId` |
| `aria-id` | `string` | — | the wrapper's author id, exposed as the platform's automation id |
| `onLayout` | `(event: EventPayload) => void` | — | the wrapper's painted box after the first paint and each resize |
| `className` | `string` | — | a Tailwind class string, joined after the recipe so it wins conflicts |
| `style` | `StyleDesc` | — | merged last |
| `testId` | `string` | — | stable locator for the wrapper |
| `children` | `ReactNode` | — | the buttons |

---

# Checkbox group

Source: https://gpuixui.sudokw.com/primitives/checkbox-group

Several independent choices sharing one tab stop

<ComponentPreview name="checkbox-group-demo" />

## Usage [#usage]

```tsx
import { CheckboxGroup } from "@gpuixui/primitives";

<CheckboxGroup
  label="Channels"
  value={channels}
  onValueChange={setChannels}
  options={[
    { value: "email", label: "Email" },
    { value: "push", label: "Push", description: "Desktop app" },
    { value: "sms", label: "SMS", disabled: true },
  ]}
/>;
```

## API [#api]

### `CheckboxGroup` [#checkboxgroup]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `options` | `ReadonlyArray<GroupOption>` | — | the choices as data; omit with item children |
| `children` | `ReactNode` | — | `CheckboxGroupItem` elements, for rich content |
| `value` | `ReadonlyArray<string>` | — | controlled values |
| `defaultValue` | `ReadonlyArray<string>` | `[]` | the initial values when uncontrolled |
| `onValueChange` | `(next: ReadonlyArray<string>) => void` | none | the on values |
| `onChange` | `(next: ReadonlyArray<string>) => void` | none | deprecated alias for `onValueChange` |
| `orientation` | `"vertical" \| "horizontal"` | `"vertical"` | which arrow pair moves focus; a name this release does not carry reads as `"vertical"` |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | box side from `iconSize` |
| `accent` | `"primary" \| "destructive"` | `"primary"` | the fill and mark colour; a stored name the table does not carry reads as `primary` |
| `disabled` | `boolean` | `false` | disables every option |
| `invalid` | `boolean` | `false` | the empty box's border and every row's focus ring take the destructive role |
| `label` | `string` | none | the group's accessible name |
| `description` | `string` | none | announced help on the group node |
| `ref` / `aria-id` / `onLayout` | host props | none | land on the row that holds the tab stop |
| `style` | `StateStyle<CheckboxGroupState>` | — | resolved against the live state, merged last |
| `itemStyle` | `StateStyle<CheckboxItemState>` | — | resolved per option row, merged last |
| `onClick` / `onKeyDown` / `onKeyUp` / `onFocus` / `onBlur` | host handlers | none | composed with the group's own; yours runs first |
| `className` | `string` | — | compiled after the recipe, so it wins conflicts |
| `testId` | `string` | — | stable locator for the group |
| `itemTestId` | `(value: string) => string` | — | per-row locator, derived from its value |

### `CheckboxGroupItem` [#checkboxgroupitem]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `value` | `string` | — | the value this option adds |
| `label` | `string` | — | accessible name, and the visible text unless `children` replaces it |
| `description` | `string` | none | a caption beside the name, announced as the row's help (`aria-description`); a blank one paints and announces nothing |
| `disabled` | `boolean` | `false` | the option cannot be chosen and takes no focus |
| `children` | `ReactNode` | — | rich content drawn instead of the name pair |

---

# Grid

Source: https://gpuixui.sudokw.com/primitives/grid

Equal tracks in two dimensions

<ComponentPreview name="grid-demo" />

## Usage [#usage]

```tsx
import { Grid, Text } from "@gpuixui/primitives";

<Grid columns={2} gap="sm">
  <Text role="caption" tone="muted">Width</Text>
  <Text role="code">1280 px</Text>
  <Text role="caption" tone="muted">Height</Text>
  <Text role="code">800 px</Text>
</Grid>;
```

## API [#api]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `columns` | `number` | required | equal column tracks; floored, minimum 1 |
| `rows` | `number` | auto | equal fixed rows; floored, minimum 1 |
| `gap` | spacing step | none | both axes, from `spacing` |
| `grow` | `boolean` | `false` | takes leftover space on the parent's axis |
| `ref` | `Ref<PublicInstance>` | — | the painted element, for a measurement, a scroll or a focus call |
| `aria-id` | `string` | — | the element's author id, exposed as the platform's automation id |
| `onLayout` | `(event: EventPayload) => void` | — | the painted box after the first paint and each resize |
| `className` | `string` | — | a Tailwind class string, joined after the recipe so it wins conflicts |
| `style` | `StyleDesc` | — | merged last |
| `children` | `ReactNode` | — | cells, in source order |
| `testId` | `string` | — | stable locator |

---

# IconButton

Source: https://gpuixui.sudokw.com/primitives/icon-button

A square, icon-only action with a required name

<ComponentPreview name="icon-button-demo" />

## Usage [#usage]

```tsx
import { IconButton, Stack, useTheme } from "@gpuixui/primitives";
import { Icon } from "@gpuixui/icons";

const theme = useTheme();

<Stack direction="row" gap="2xs">
  <IconButton
    label="Delete layer"
    icon={<Icon name="trash" color={theme.colors.destructiveForeground} />}
    variant="destructive"
    onActivate={removeLayer}
  />
  <IconButton
    label="Layer settings"
    icon={<Icon name="settings" color={theme.colors.foreground} />}
    onActivate={openSettings}
  />
</Stack>;
```

## API [#api]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `label` | `string` | required | the accessible name; never derived from the glyph |
| `icon` | `ReactNode` | required | the glyph painted inside the button |
| `variant` | `ButtonVariant` | `"ghost"` | the paint from `core/variants.ts` |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | square side from `density.controlHeight` |
| `disabled` | `boolean` | `false` | blocks activation; out of the Tab order (`tabIndex: -1`) |
| `loading` | `boolean` | `false` | spinner, busy description, blocks activation |
| `loadingLabel` | `string` | `loading.busy` (`"Loading"`) | the busy word, announced as the description and the spinner's name; a blank one silences both |
| `reducedMotion` | `boolean` | the motion provider | holds the busy spinner's lit dot; the prop overrides the provider |
| `onActivate` | `(event: EventPayload) => void` | none | click or activating key; not called while busy |
| `onClick` / `onKeyDown` / `onKeyUp` / `onFocus` / `onBlur` | host handlers | none | composed with the button's own; a click is observed first, an activating key acts first |
| `onMouseEnter` / `onMouseLeave` / `aria-description` | `TooltipTriggerProps` | none | forwarded to the press target, so the control can be a `Tooltip` trigger |
| `ref` | `Ref<PublicInstance>` | — | the element itself |
| `aria-expanded` / `aria-selected` | `boolean` | — | announced state, forwarded through `ActionHostProps` |
| `tabIndex` | `number` | `0`, or `-1` while `disabled` | the action's Tab stop; see `Button`'s row — a leaving surface names `-1` for the close action it keeps painted |
| `className` | `string` | — | a Tailwind string joined after the recipe |
| `style` | `StateStyle<ButtonState>` | — | resolved against `{ disabled, focused }`, merged last |
| `testId` | `string` | — | stable locator |

---

# Input

Source: https://gpuixui.sudokw.com/primitives/input

A single-line text field, controlled or uncontrolled

<ComponentPreview name="input-demo" />

## Usage [#usage]

```tsx
import { Input, Label, labelledBy } from "@gpuixui/primitives";

const email = "Contact email";
const help = "Where notifications are delivered.";

<Label description={help}>{email}</Label>
<Input
  {...labelledBy(email)}
  description={help}
  value={value}
  onValueChange={setValue}
  placeholder="you@example.com"
  fullWidth
/>;
```

## API [#api]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `value` | `string` | — | controlled text |
| `defaultValue` | `string` | `""` | initial text when uncontrolled |
| `onValueChange` | `(value: string) => void` | none | called after each edit that changed the value |
| `onChange` | `(value: string) => void` | none | deprecated alias for `onValueChange` |
| `onSubmit` | `(event) => void` | none | Enter; the raw runtime event |
| `placeholder` | `string` | none | empty-state text: painted in the `placeholder` role and announced as the field's description while the box is empty (the host's own hint is a fixed grey no theme reaches); a blank one paints nothing and announces nothing |
| `readOnly` | `boolean` | `false` | accepts focus and selection, refuses edits |
| `disabled` | `boolean` | `false` | read-only, out of the tab order, de-emphasised |
| `autoFocus` | `boolean` | `false` | takes focus on mount |
| `invalid` | `boolean` | `false` | border and focus ring take the destructive role |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | height and padding from density |
| `fullWidth` | `boolean` | `false` | `width: 100%` |
| `label` | `string` | none | accessible name; a visible `Label` does not name the field on its own |
| `description` | `string` | none | announced help after the name (`aria-description`); a caller's permanent help wins over the hint |
| `tabIndex` | `number` | none | the field's place in the tab order |
| `ref` / `aria-id` / `onLayout` | host props | none | the native `<input>` is the addressed element |
| `onClick` / `onKeyDown` / `onKeyUp` / `onFocus` / `onBlur` | host handlers | none | composed with the field's own; yours runs first |
| `className` | `string` | — | a Tailwind class string, joined after the recipe so it wins conflicts |
| `style` | `StateStyle<FieldState>` | — | resolved against the live state, merged last |
| `testId` | `string` | — | stable locator |

---

# Label

Source: https://gpuixui.sudokw.com/primitives/label

A control's visible name, with a required marker

<ComponentPreview name="label-demo" />

## Usage [#usage]

```tsx
import { useRef } from "react";
import type { PublicInstance } from "@gpuix/react";
import { Input, Label, labelledBy } from "@gpuixui/primitives";

const name = "Workspace name";
const help = "Shown on invitations and in the app switcher.";

export const NameField = () => {
  const ref = useRef<PublicInstance>(null);
  return (
    <>
      <Label target={ref} description={help}>
        {name}
      </Label>
      <Input ref={ref} {...labelledBy(name)} description={help} fullWidth />
    </>
  );
};
```

## API [#api]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `target` | `RefObject<PublicInstance \| null>` | none | a press on the label focuses this control |
| `disabled` | `boolean` | `false` | drops that press, for a control that is disabled |
| `required` | `boolean` | `false` | appends a destructive `*`; visual only |
| `invalid` | `boolean` | `false` | paints the name in the destructive role |
| `description` | `string` | none | a caption line under the name; a blank one paints nothing, the rule a blank name keeps |
| `className` | `string` | — | a Tailwind class string, joined after the recipe so it wins conflicts |
| `style` | `StyleDesc` | — | merged last |
| `testId` | `string` | — | stable locator |
| `children` | `ReactNode` | — | the name |

---

# Meter

Source: https://gpuixui.sudokw.com/primitives/meter

A measurement inside a range

<ComponentPreview name="meter-demo" />

## Usage [#usage]

```tsx
import { Meter, Stack, Text } from "@gpuixui/primitives";

<Stack direction="column" gap="xs">
  <Text role="caption" tone="muted">Disk usage · 68 of 100 GB</Text>
  <Meter label="Disk usage" value={68} max={100} formatValue={(v) => `${v} GB`} />
</Stack>;
```

## API [#api]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `value` | `number` | required | the measurement; clamped into the range |
| `min` / `max` | `number` | `0` / `100` | the range the fill is a fraction of; a stored bound that is not a number is that default |
| `tone` | `primary \| success \| destructive \| muted` | `"primary"` | the fill's colour role; a stored name the table does not carry reads as `primary` |
| `size` | `"sm" \| "md"` | `"md"` | track height from `spacing.xs` / `sm`; a stored name the table does not carry reads as `md` |
| `label` | `string` | none | accessible name, and `MeterLabel`'s default text; a blank label is no name, and a caption child that says nothing falls back to it rather than painting a blank line |
| `formatValue` | `(value: number) => string` | `String` | the announced and displayed measurement; a blank answer keeps the number |
| `children` | `ReactNode` | the track | the parts to draw |
| `style` | `StyleDesc` | — | merged last, on the root frame |
| `className` | `string` | — | Tailwind classes, joined last on the root frame |
| `ref` / `aria-id` / `onLayout` | host props | none | the root frame itself: the box a layout measures, the instance a caller holds, and the author id an automation host addresses |
| `testId` | `string` | — | stable locator, on the root |

---

# NumberField

Source: https://gpuixui.sudokw.com/primitives/number-field

A number in a text field, with steps and optional bounds

<ComponentPreview name="number-field-demo" />

## Usage [#usage]

```tsx
import { NumberField, Label, Stack } from "@gpuixui/primitives";
import { useState } from "react";

const [copies, setCopies] = useState(1);

<Stack direction="column" gap="xs">
  <Label description="1–99">Copies</Label>
  <NumberField label="Copies" value={copies} onValueChange={setCopies} min={1} max={99} />
</Stack>;
```

## API [#api]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `value` | `number` | — | controlled value |
| `defaultValue` | `number` | none | start value; the field shows empty without one |
| `onValueChange` | `(value: number) => void` | — | the clamped number, after a valid edit or step |
| `onValueCommit` | `(value: number) => void` | — | the value a gesture ended on: once per stepper press, once per scrub release, once per arrow or page key that moved it, and once when a typed edit ends on a readable value |
| `onChange` | `(value: number) => void` | — | deprecated alias for `onValueChange` |
| `min` / `max` | `number` | none | bound the value; absent means unbounded, and an inverted pair is the range it means |
| `step` | `number` | `1` | arrow step |
| `precision` | `number` | the value's own decimals | decimals painted on commit; it rounds and pads the text, and the value keeps its own. A stored value that is not a number (a record's `null`, text) is no precision at all, so the field paints the value's own decimals rather than rounding it to a whole number |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | field height and padding |
| `disabled` | `boolean` | `false` | read-only, out of the tab order, inert |
| `invalid` | `boolean` | `false` | destructive border |
| `label` | `string` | none | accessible name |
| `onSubmit` | `(event: EventPayload) => void` | — | Enter: the draft commits first, then this reports |
| `description` | `string` | none | announced help on the input (`aria-description`); a caller's permanent help wins over the hint |
| `placeholder` | `string` | none | empty-field hint, painted in the `placeholder` role and announced as the field's description while the box is empty (the host's own hint is a fixed grey no theme reaches) |
| `autoFocus` | `boolean` | `false` | focus on mount |
| `formatValue` | `(value: number) => string` | fixed decimals | the display text, display-only; pair it with `parseValue`. An answer that says nothing (`""` or only spaces — a locale table's missing row) is no answer, so the field paints the value it holds instead of an empty box |
| `parseValue` | `(text: string) => Option<number>` | none | reads the text `formatValue` painted; tried first, then decimal |
| `className` | `string` | — | a Tailwind class string, joined after the recipe so it wins conflicts |
| `style` | `StateStyle<FieldState>` | — | resolved against the live state, merged last |
| `children` | `ReactNode` | input + steppers | the parts to draw |
| `onClick` / `onKeyDown` / `onKeyUp` / `onFocus` / `onBlur` | host handlers | none | composed with the field's own; a disabled field keeps them observable |
| `ref` / `aria-id` / `onLayout` | host props | none | the native `<input>` is the addressed element |
| `testId` | `string` | — | stable locator on the field's chrome |

### `NumberFieldScrubHandle` [#numberfieldscrubhandle]

The label an inspector drags. Mount it beside a `NumberField` and give both the
same value and bounds: a horizontal drag moves one step per 4px, a held Shift
multiplies that by 10, and `min`/`max` clamp it. A press that does not travel is a
click, so the field beside it stays a text field.

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `value` | `number` | — | the value a drag starts from |
| `min` / `max` | `number` | none | the bounds a drag clamps to |
| `step` | `number` | `1` | the step one scrub count moves |
| `onValueChange` | `(value: number) => void` | — | every frame of a drag, already clamped |
| `onValueCommit` | `(value: number) => void` | — | the value the whole drag ended on |
| `disabled` | `boolean` | `false` | takes no gesture, and paints no resize cursor |
| `children` | `ReactNode` | — | the visible words a reader drags |
| `style` / `className` / `testId` | host props | — | merged after the handle's own |

---

# OTPField

Source: https://gpuixui.sudokw.com/primitives/otp-field

A one-time code in length cells, held as one string

<ComponentPreview name="otp-field-demo" />

## Usage [#usage]

```tsx
import { OTPField, Label, Stack } from "@gpuixui/primitives";
import { useState } from "react";

const [code, setCode] = useState("");

<Stack direction="column" gap="xs">
  <Label description="Six digits from your authenticator">
    Verification code
  </Label>
  <OTPField
    label="Verification code"
    value={code}
    onValueChange={setCode}
    onComplete={(complete) => verify(complete)}
  />
</Stack>;
```

## API [#api]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `length` | `number` | `6` | number of cells; a stored value that is not a number is six, and a number that cannot be laid out resolves to one |
| `value` | `string` | — | controlled code, normalised to letters/digits; a stored value that is not text is no code |
| `defaultValue` | `string` | — | initial code when uncontrolled; a stored value that is not text is no code |
| `onValueChange` | `(value: string) => void` | — | the code after every edit that changed it |
| `onChange` | `(value: string) => void` | — | deprecated alias for `onValueChange` |
| `onComplete` | `(value: string) => void` | — | fires when an edit makes the code full |
| `onSubmit` | `(event: EventPayload) => void` | — | Enter in any cell, with the code unchanged |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | cell height and width, from the density scale |
| `disabled` | `boolean` | `false` | read-only, out of the tab order, inert |
| `invalid` | `boolean` | `false` | destructive border on every cell |
| `label` | `string` | none | group name; each cell is named `<label> digit N` |
| `description` | `string` | none | announced help, carried by every cell (`aria-description`) |
| `autoFocus` | `boolean` | `false` | focuses the first cell on mount |
| `className` | `string` | — | a Tailwind class string, joined after the recipe so it wins conflicts |
| `style` | `StateStyle<FieldState>` | — | on the group; resolved against the live state, merged last |
| `children` | `ReactNode` | `length` cells | the cell parts to draw |
| `onClick` / `onKeyDown` / `onKeyUp` / `onFocus` / `onBlur` | host handlers | none | composed with each cell's own, on every cell |
| `ref` / `aria-id` / `onLayout` | host props | none | land on the first cell; the code belongs to the group |
| `testId` | `string` | — | the group's locator; cells are `<testId>-cell-N` |

---

# Progress

Source: https://gpuixui.sudokw.com/primitives/progress

A determinate or indeterminate progress bar

<ComponentPreview name="progress-demo" />

## Usage [#usage]

```tsx
import { Progress, Stack, Text } from "@gpuixui/primitives";

<Stack direction="column" gap="xs">
  <Text role="caption" tone="muted">Uploading · 42%</Text>
  <Progress value={42} label="Uploading" />
</Stack>;
```

## API [#api]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `value` | `number` | — | 0–100 determinate fill; omit for indeterminate, and a stored `null` — or any value that is not a number — reads as omitted |
| `buffer` | `number` | none | 0–100 held-ahead point; paints the segment between `value` and itself, and a stored value that is not a number paints no segment |
| `tone` | `primary \| success \| destructive \| muted` | `"primary"` | the fill's colour role; a stored name the table does not carry reads as `primary` |
| `size` | `"sm" \| "md"` | `"md"` | track height from `spacing.xs`/`sm`; a stored name the table does not carry reads as `md` |
| `label` | `string` | none | accessible name, and `ProgressLabel`'s default text; a blank label is no name, and a caption child that says nothing falls back to it rather than painting a blank line |
| `formatValue` | `(percent: number) => string` | `` `${percent}%` `` | the announced and painted share; a blank answer keeps the default |
| `loadingText` | `string` | `loading.indeterminate` (`"loading"`) | what an indeterminate bar says instead of a percentage; a blank one keeps the provider's |
| `reducedMotion` | `boolean` | the motion provider | holds the indeterminate segment; no effect with `value`. The prop overrides the provider |
| `children` | `ReactNode` | the track | the parts to draw |
| `style` | `StyleDesc` | — | merged last, on the root frame |
| `className` | `string` | — | Tailwind classes, joined last on the root frame |
| `ref` / `aria-id` / `onLayout` | host props | none | the root frame itself: the box a layout measures, the instance a caller holds, and the author id an automation host addresses |
| `testId` | `string` | — | stable locator, on the root |

A widget record kept in JSON stores a share it never learned as `null` rather than `undefined`. That reads as **absent**, like an omitted prop: the bar paints the moving segment and says the loading word, while `0` remains the empty share it names. A share that is not a number at all is the same absence — text a store wrote, or a field a decoder could not read — because the library does not turn text into a number here (`parseNumberText` is the explicit seam that does). Read as a measurement it would paint `width: "NaN%"` and announce `"NaN%"`: a bar with no fill that still claims a value.

---

# RadioGroup

Source: https://gpuixui.sudokw.com/primitives/radio-group

One choice from a small set, with arrow navigation

<ComponentPreview name="radio-group-demo" />

## Usage [#usage]

```tsx
import { RadioGroup } from "@gpuixui/primitives";

<RadioGroup
  label="Digest cadence"
  value={cadence}
  onValueChange={setCadence}
  options={[
    { value: "daily", label: "Daily" },
    { value: "weekly", label: "Weekly", description: "Every Monday." },
    { value: "never", label: "Never" },
  ]}
/>;
```

## API [#api]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `options` | `ReadonlyArray<RadioOption>` | — | the choices as data (`{ value, label, description? }`); a description paints a caption beside the name and is announced as the row's help |
| `children` | `ReactNode` | — | `<RadioGroupItem>` elements, for rich content |
| `value` | `string` | — | controlled selection; the arrows and the single tab stop continue from the row that holds focus, so an owner that has not applied the choice yet cannot stall navigation |
| `defaultValue` | `string` | `""` | initial selection when uncontrolled |
| `onValueChange` | `(value: string) => void` | none | the selected item's value |
| `onChange` | `(value: string) => void` | none | deprecated alias for `onValueChange` |
| `orientation` | `"vertical" \| "horizontal"` | `"vertical"` | layout and the arrow axis; a name this release does not carry reads as `"vertical"` |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | radio circle size |
| `accent` | `"primary" \| "destructive"` | `"primary"` | the dot's fill; a stored name the table does not carry reads as `primary` |
| `disabled` | `boolean` | `false` | disables every option |
| `invalid` | `boolean` | `false` | every empty circle's edge and every row's focus ring take the destructive role; a chosen radio keeps its accent fill |
| `label` | `string` | none | accessible name for the group |
| `description` | `string` | none | announced help for the group (`aria-description`) |
| `ref` / `aria-id` / `onLayout` | host address | none | land on the row that holds the tab stop |
| `className` | `string` | — | a Tailwind class string, joined after the recipe so it wins conflicts |
| `style` | `StateStyle<RadioGroupState>` | — | resolved against the live state, merged last |
| `itemStyle` | `StateStyle<RadioItemState>` | — | resolved per option row, merged last |
| `onClick` / `onKeyDown` / `onKeyUp` / `onFocus` / `onBlur` | host handlers | none | composed with the group's own; yours runs first |
| `testId` | `string` | — | stable locator for the group (the wrapper) |
| `itemTestId` | `(value: string) => string` | — | per-row locator, derived from its value |

---

# RangeSlider

Source: https://gpuixui.sudokw.com/primitives/range-slider

Two values, the ends of one interval, on one track

<ComponentPreview name="range-slider-demo" />

## Usage [#usage]

```tsx
import { RangeSlider, Stack, Text } from "@gpuixui/primitives";
import { useState } from "react";

const [price, setPrice] = useState<readonly [number, number]>([20, 80]);

<Stack direction="column" gap="sm">
  <Text role="caption" tone="muted">${price[0]} – ${price[1]}</Text>
  <RangeSlider
    label="Budget"
    value={price}
    onValueChange={setPrice}
    step={5}
    formatValue={(value) => `$${value}`}
  />
</Stack>;
```

## API [#api]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `value` | `readonly [number, number]` | — | controlled span |
| `defaultValue` | `readonly [number, number]` | `[min, max]` | uncontrolled start |
| `onValueChange` | `(value: readonly [number, number]) => void` | — | called with the ordered pair |
| `onValueCommit` | `(value: readonly [number, number]) => void` | — | the span a gesture ended on: once per drag release, once per key that moved an end |
| `onChange` | `(value: readonly [number, number]) => void` | — | deprecated alias for `onValueChange` |
| `min` / `max` | `number` | `0` / `100` | the closed range; a stored bound that is not a number is that default |
| `step` | `number` | `1` | quantisation; `0` is continuous; a stored step that is not a number is `1` |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | thumb and track metrics |
| `disabled` | `boolean` | `false` | both thumbs leave the tab order |
| `invalid` | `boolean` | `false` | destructive fill and thumb borders |
| `label` | `string` | none | group name; thumbs become the provider's `rangeEnd` sentence (`"<label> minimum"` / `"<label> maximum"`) |
| `description` | `string` | none | announced help on the group node |
| `formatValue` | `(value: number) => string` | `String` | the announced text of each thumb; a blank answer keeps the number |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | the axis the two values run along; a vertical track needs a definite height |
| `style` | `StateStyle<SliderState>` | — | resolved against the live state, merged last on the track |
| `className` | `string` | — | joined after the recipe, so it wins conflicts |
| `children` | `ReactNode` | — | the parts to draw; omit for the default composition |
| `onClick` / `onKeyDown` / `onKeyUp` / `onFocus` / `onBlur` | host handlers | none | composed with the range's own; keys land on a thumb |
| `ref` / `aria-id` | host props | none | land on the thumb that holds the tab stop — the end the reader last used, the start while neither holds focus — because the group node cannot take focus; the address moves with the reader |
| `onLayout` | `(event: EventPayload) => void` | none | the painted box of the thumb holding the tab stop — a thumb's, never the track's — reported on mount and again when the address moves; wrap the slider to measure the whole control |
| `testId` | `string` | — | stable locator for the track |

---

# Rating

Source: https://gpuixui.sudokw.com/primitives/rating

A score in stars, whole or in halves

<ComponentPreview name="rating-demo" />

## Usage [#usage]

```tsx
import { Rating, Stack, Text } from "@gpuixui/primitives";
import { useState } from "react";

const [score, setScore] = useState(0);

<Stack direction="column" gap="xs">
  <Rating label="Quality" value={score} onValueChange={setScore} />
  <Text role="caption" tone="muted">
    {score === 0 ? "Not rated" : `${score} of 5`}
  </Text>
</Stack>;
```

## API [#api]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `value` | `number` | — | controlled rating, `0..max` |
| `defaultValue` | `number` | `0` | uncontrolled start |
| `onValueChange` | `(value: number) => void` | — | the new rating; `0` means cleared |
| `onChange` | `(value: number) => void` | — | deprecated alias for `onValueChange` |
| `max` | `number` | `5` | how many stars to paint; a stored `null` is the default five, while a count that is there and cannot be laid out is one star |
| `allowHalf` | `boolean` | `false` | score in halves |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | star size from `iconSize` |
| `disabled` | `boolean` | `false` | out of the tab order, half opacity, inert |
| `readOnly` | `boolean` | `false` | shows the value, takes no input, no tab stop |
| `label` | `string` | none | the group's name |
| `description` | `string` | none | announced help for the group (`aria-description`) |
| `invalid` | `boolean` | `false` | chosen stars paint destructive |
| `className` | `string` | — | a Tailwind class string, joined after the recipe so it wins conflicts |
| `style` | `StateStyle<RatingState>` | — | resolved against the live state, merged last |
| `onClick` / `onKeyDown` / `onKeyUp` / `onFocus` / `onBlur` | host handlers | none | composed with the rating's own |
| `ref` / `aria-id` / `onLayout` | host props | none | land on the star that holds the tab stop, so they follow the score; measure a wrapper for the whole control |
| `testId` | `string` | — | stable locator on the group |

---

# ScrollArea

Source: https://gpuixui.sudokw.com/primitives/scroll-area

A bounded container that scrolls on the chosen axes

<ComponentPreview name="scroll-area-demo" />

## Usage [#usage]

```tsx
import { ScrollArea, Stack, Text } from "@gpuixui/primitives";

<ScrollArea axis="vertical" style={{ height: 240 }} padding="md" label="Rows">
  <Stack direction="column" gap="sm">
    {rows.map((row) => (
      <Text role="body" key={row}>{row}</Text>
    ))}
  </Stack>
</ScrollArea>;
```

## API [#api]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `axis` | `"vertical" \| "horizontal" \| "both"` | `"vertical"` | which overflow axes are `scroll`; a stored name this release does not carry reads as the default, in the paint and in the keys (`scrollAxis`) |
| `onScroll` | `(event: EventPayload) => void` | none | wheel/trackpad deltas |
| `onScrollChange` | `(event: EventPayload) => void` | none | the absolute offset after any move |
| `onLayout` | `(event: EventPayload) => void` | none | the scroller's painted box (`width`/`height`), reported on mount and on a size change; a composed `ScrollAreaViewport` defaults to it |
| `padding` | spacing step | none | frame padding; it does not scroll |
| `radius` | radius step | none | frame radius; the scroller is clipped by it, and a stored name this release does not carry paints no corner |
| `border` | `boolean` | `false` | the frame's `border` role |
| `scrollbarColor` | `string` | `colors.scrollbar` | the viewport thumb's colour |
| `scrollbarWidth` | `number` | platform's | the viewport thumb's thickness in px |
| `focusable` | `boolean` | `true` | whether the viewport is a tab stop |
| `label` | `string` | `"Scroll region"` | names the region (`role="group"` + `aria-label`) |
| `style` | `StyleDesc` | — | merged last on the frame; put the bounded size here |
| `className` | `string` | — | Tailwind classes, joined last on the frame |
| `children` | `ReactNode` | — | viewport content, or a composed `ScrollAreaViewport` |
| `testId` | `string` | — | the frame's locator |
| `viewportTestId` | `string` | — | the implicit viewport's locator |
| `viewportRef` | `Ref<PublicInstance>` | — | the implicit viewport's element |

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `ref` | `Ref<PublicInstance>` | — | the scroller itself; `scrollTo` and `scrollIntoView` address this element |

---

# Separator

Source: https://gpuixui.sudokw.com/primitives/separator

One theme-coloured rule between regions

<ComponentPreview name="separator-demo" />

## Usage [#usage]

```tsx
import { Separator, Stack, Text } from "@gpuixui/primitives";

<Stack direction="column" gap="md">
  <Text role="h3">Account</Text>
  <Separator orientation="horizontal" />
  <Text role="body">Profile and sign-in details.</Text>
</Stack>;
```

## API [#api]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `orientation` | `"horizontal" \| "vertical"` | required | which way the rule runs; a stored name this release does not carry draws the **horizontal** rule — read raw, it drew a vertical hairline while keeping the caption row |
| `inset` | spacing step | none | margin at both ends, from `spacing` |
| `label` | `string` | none | a centred caption; ignored for vertical rules, and a blank or whitespace-only caption is no caption (it would paint a full blank line) |
| `className` | `string` | — | a Tailwind class string, joined after the recipe so it wins conflicts |
| `style` | `StyleDesc` | — | merged last |
| `testId` | `string` | — | stable locator |

---

# Skeleton

Source: https://gpuixui.sudokw.com/primitives/skeleton

A pulsing placeholder for content that has not arrived

<ComponentPreview name="skeleton-demo" />

## Usage [#usage]

```tsx
import { Skeleton, Stack } from "@gpuixui/primitives";

<Stack direction="column" gap="sm">
  <Skeleton height={36} width="45%" />
  <Skeleton height={14} width="70%" />
  <Skeleton height={12} />
</Stack>;
```

## API [#api]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `width` | `number \| string` | `"100%"` | the block's width; a side that is not a paintable length (a `NaN` measurement, or a stored `""`) takes the default, because the runtime refuses the whole style batch for a dimension it cannot parse |
| `height` | `number \| string` | body line height | the block's height, with the same rule for a side it cannot paint |
| `radius` | `sm \| md \| lg \| xl \| none` | `"sm"` | corner radius; a stored name this release does not carry keeps `sm` |
| `circle` | `boolean` | `false` | full radius; the missing side mirrors the other |
| `reducedMotion` | `boolean` | the motion provider | paints the full-opacity frame and schedules no pulse; the prop overrides the provider |
| `className` | `string` | — | a Tailwind class string, joined after the recipe so it wins conflicts |
| `style` | `StyleDesc` | — | merged last |
| `ref` / `aria-id` / `onLayout` | host props | none | the placeholder itself: the box a layout measures (so a placeholder can reserve exactly what it stands in for), the instance a caller holds, and the author id an automation host addresses |
| `testId` | `string` | — | stable locator |

---

# Slider

Source: https://gpuixui.sudokw.com/primitives/slider

A value on a track, by click, drag or keyboard

<ComponentPreview name="slider-demo" />

## Usage [#usage]

```tsx
import { Slider, Stack, Text } from "@gpuixui/primitives";
import { useState } from "react";

const [quality, setQuality] = useState(62);

<Stack direction="column" gap="sm">
  <Text role="caption" tone="muted">Quality · {quality}%</Text>
  <Slider
    label="Quality"
    value={quality}
    onValueChange={setQuality}
    formatValue={(value) => `${value}%`}
  />
</Stack>;
```

## API [#api]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `value` | `number` | — | controlled value |
| `defaultValue` | `number` | `min` | uncontrolled start |
| `onValueChange` | `(value: number) => void` | — | called only when the value changed |
| `onValueCommit` | `(value: number) => void` | — | the value a gesture ended on: once per drag release, once per key that moved it |
| `onChange` | `(value: number) => void` | — | deprecated alias for `onValueChange` |
| `min` / `max` | `number` | `0` / `100` | the closed range; a stored bound that is not a number is that default |
| `step` | `number` | `1` | quantisation; `0` is continuous; a stored step that is not a number is `1` |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | thumb `iconSize`, track `density.controlHeight` |
| `disabled` | `boolean` | `false` | out of the tab order, half opacity |
| `invalid` | `boolean` | `false` | the destructive role on the fill and thumb border |
| `label` | `string` | none | accessible name |
| `description` | `string` | none | announced help |
| `formatValue` | `(value: number) => string` | `String` | the announced text; a blank answer keeps the number |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | the axis the value runs along; a vertical track needs a definite height |
| `style` | `StateStyle<SliderState>` | — | resolved against the live state, merged last on the track |
| `className` | `string` | — | joined after the recipe, so it wins conflicts |
| `children` | `ReactNode` | — | the parts to draw; omit for the default composition |
| `onClick` / `onKeyDown` / `onKeyUp` / `onFocus` / `onBlur` | host handlers | none | composed with the slider's own; the press and keys reach the track |
| `ref` / `aria-id` / `onLayout` | host props | none | land on the track, the element that carries the pointer and the value |
| `testId` | `string` | — | stable locator for the track |

---

# Spacer

Source: https://gpuixui.sudokw.com/primitives/spacer

Empty space as a fixed step or a flexible filler

<ComponentPreview name="spacer-demo" />

## Usage [#usage]

```tsx
import { Spacer, Stack, Text } from "@gpuixui/primitives";

<Stack direction="row" align="center" gap="sm">
  <Text role="caption" tone="muted">Read-only</Text>
  <Spacer />
  <Text role="caption" tone="primary">Reset all</Text>
</Stack>;
```

## API [#api]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `size` | spacing step | none (flexible) | a fixed square gap on both axes; `spaceStep` reads a stored step this theme does not carry as the default — a flexible filler — rather than a fixed item with no side |
| `ref` | `Ref<PublicInstance>` | — | the painted element |
| `aria-id` | `string` | — | the element's author id, exposed as the platform's automation id |
| `onLayout` | `(event: EventPayload) => void` | — | the painted box after the first paint and each resize |
| `className` | `string` | — | a Tailwind class string, joined after the fixed gap so it wins conflicts |
| `style` | `StyleDesc` | — | merged last |
| `testId` | `string` | — | stable locator |

---

# Spinner

Source: https://gpuixui.sudokw.com/primitives/spinner

An activity indicator drawn as a ring whose lit arc steps around the circle, because the runtime cannot rotate

<ComponentPreview name="spinner-demo" />

## Usage [#usage]

```tsx
import { Spinner, Stack, Text } from "@gpuixui/primitives";

<Stack direction="row" align="center" gap="sm">
  <Spinner label="Refreshing revenue" />
  <Text role="caption" tone="muted">Refreshing…</Text>
</Stack>;
```

## API [#api]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `size` | `IconSize \| number` | `"md"` | the ring's side: a theme step, or raw pixels |
| `accent` | `primary \| destructive \| muted \| on-primary \| on-secondary \| on-destructive \| on-accent \| on-disabled` | `"primary"` | the role every tick paints; a stored name the table does not carry reads as `primary` |
| `label` | `string` | `loading.busy` (`"Loading"`) | accessible name announced as a status; a blank one paints the ring as decoration (no node to walk into) |
| `reducedMotion` | `boolean` | the motion provider | holds the resting arc and schedules no interval; the prop overrides the provider |
| `className` | `string` | — | a Tailwind class string, joined after the recipe so it wins conflicts |
| `style` | `StyleDesc` | — | merged last |
| `ref` / `aria-id` / `onLayout` | host props | none | the indicator's own box: the group a layout measures, the instance a caller holds, and the author id an automation host addresses |
| `testId` | `string` | — | stable locator |

## How the ring moves [#how-the-ring-moves]

The runtime paints a box and its opacity, and nothing else: it cannot rotate. So
the ring is `SPINNER_RING_TICKS` (12) static ticks placed on a circle by
`spinnerTicks`, and the **lit arc** moves instead — one head fully opaque, the
`SPINNER_ARC_TICKS` (7) behind it fading to `SPINNER_FADE_FLOOR` (0.2), the rest
of the ring empty. The head advances one tick per interval. That gap is what
reads as a turning arc; nothing rotates.

---

# Stack

Source: https://gpuixui.sudokw.com/primitives/stack

Children laid out along one axis, spaced by the theme scale

<ComponentPreview name="stack-demo" />

## Usage [#usage]

```tsx
import { Stack, Text, Button } from "@gpuixui/primitives";

<Stack direction="column" gap="sm">
  <Text role="h3">Danger zone</Text>
  <Stack direction="row" gap="sm" justify="end">
    <Button variant="outline">Cancel</Button>
    <Button variant="destructive">Delete</Button>
  </Stack>
</Stack>;
```

## API [#api]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `direction` | `"row" \| "column"` | required | the main axis; a stored name this release does not carry paints the **column** the recipe has always drawn, in the resolver too (`stackDirection`) |
| `gap` | spacing step | none | distance between children, from `spacing` |
| `align` | `start \| center \| end \| stretch \| baseline` | `stretch` | cross-axis alignment |
| `justify` | `start \| center \| end \| between \| around` | runtime default | main-axis distribution |
| `wrap` | `boolean` | `false` | allows wrapping to a second line |
| `grow` | `boolean` | `false` | takes leftover space on the parent's axis |
| `fullWidth` / `fullHeight` | `boolean` | `false` | `100%` on that axis |
| `ref` | `Ref<PublicInstance>` | — | the painted element, for a measurement, a scroll or a focus call |
| `aria-id` | `string` | — | the element's author id, exposed as the platform's automation id |
| `onLayout` | `(event: EventPayload) => void` | — | the painted box after the first paint and each resize |
| `className` | `string` | — | a Tailwind class string, joined after the recipe so it wins conflicts |
| `style` | `StyleDesc` | — | merged last |
| `children` | `ReactNode` | — | content |
| `testId` | `string` | — | stable locator |

---

# Text

Source: https://gpuixui.sudokw.com/primitives/text

One run of type, named by a theme role and a semantic tone

<ComponentPreview name="text-demo" />

## Usage [#usage]

```tsx
import { Text, Stack } from "@gpuixui/primitives";

<Stack direction="column" gap="2xs">
  <Text role="h2">Version 0.11.0</Text>
  <Text role="body" tone="muted">
    Released 17 October 2026.
  </Text>
  <Text role="code">nub add @gpuixui/primitives</Text>
</Stack>;
```

## API [#api]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `role` | `TextRole` | `"body"` | size, leading, weight and family; a stored name the scale does not carry reads as `body` |
| `tone` | `TextTone` | `"default"` | colour role; a stored name the table does not carry reads as `default` |
| `align` | `"start" \| "center" \| "end"` | runtime default (left) | horizontal alignment; the runtime has no writing direction, so `start` paints left and `end` paints right, and a stored name this release does not carry paints the default |
| `truncate` | `boolean` | `false` | one line, clipped with an ellipsis |
| `clamp` | `number` | none | cut to a box N lines tall; a stored `null` is no clamp (the default), while a count that is there and cannot be laid out is one line |
| `selectable` | `boolean` | `false` | `userSelect: "text"` plus the theme's `selection` wash |
| `className` | `string` | — | a Tailwind class string, joined after the recipe so it wins conflicts |
| `style` | `StyleDesc` | — | merged last |
| `ref` / `aria-id` / `onLayout` | host props | none | the `<text>` element itself: the box a measurement reads (its own wrapped height, not a wrapper's), the instance a caller holds, and the author id an automation host addresses |
| `testId` | `string` | — | stable locator |
| `children` | `ReactNode` | — | the string (or inline nodes) |

---

# TextArea

Source: https://gpuixui.sudokw.com/primitives/textarea

A multi-line text field sized in rows

<ComponentPreview name="textarea-demo" />

## Usage [#usage]

```tsx
import { Label, TextArea, labelledBy } from "@gpuixui/primitives";

const notes = "Description";
const help = "Markdown is not interpreted.";

<Label description={help}>{notes}</Label>
<TextArea
  {...labelledBy(notes)}
  description={help}
  value={value}
  onValueChange={setValue}
  minRows={3}
  maxRows={8}
  fullWidth
/>;
```

## API [#api]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `minRows` | `number` | runtime default | visible floor, in whole rows: a fraction floors, an unusable count reads as one, and a saved value that is not a number (JSON's `null`, text) leaves the runtime's own height |
| `maxRows` | `number` | runtime default | rows after which the field scrolls, in whole rows: a fraction floors, an unusable count reads as one, a saved value that is not a number leaves the runtime's own height (a cap read as one row collapsed a restored six-line field), and a cap below `minRows` is raised to it |
| `value` | `string` | — | controlled text |
| `defaultValue` | `string` | `""` | initial text when uncontrolled |
| `onValueChange` | `(value: string) => void` | none | called after each edit |
| `onChange` | `(value: string) => void` | none | deprecated alias for `onValueChange` |
| `placeholder` | `string` | none | empty-state text: painted in the `placeholder` role and announced as the field's description while the box is empty (the host's own hint is a fixed grey no theme reaches) |
| `readOnly` | `boolean` | `false` | accepts focus, refuses edits |
| `disabled` | `boolean` | `false` | read-only, out of the tab order |
| `invalid` | `boolean` | `false` | border and focus ring take the destructive role |
| `autoFocus` | `boolean` | `false` | takes focus on mount |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | row padding from density (a textarea's height is its rows) |
| `fullWidth` | `boolean` | `false` | `width: 100%` |
| `label` | `string` | none | accessible name |
| `description` | `string` | none | announced help (`aria-description`); a caller's permanent help wins over the hint |
| `tabIndex` | `number` | none | the field's place in the tab order; a disabled field sits at `-1` |
| `ref` / `aria-id` / `onLayout` | host props | none | the native `<textarea>` is the addressed element |
| `onClick` / `onKeyDown` / `onKeyUp` / `onFocus` / `onBlur` | host handlers | none | composed with the field's own; yours runs first |
| `className` | `string` | — | a Tailwind class string, joined after the recipe so it wins conflicts |
| `style` | `StateStyle<FieldState>` | — | resolved against the live state, merged last |
| `testId` | `string` | — | stable locator |

---

# ThemeProvider

Source: https://gpuixui.sudokw.com/primitives/theme-provider

Supplies the theme every primitive draws with

<ComponentPreview name="theme-provider-demo" />

## Usage [#usage]

```tsx
import { ThemeProvider, Box, Text } from "@gpuixui/primitives";
import { darkTheme } from "@gpuixui/tokens";

<ThemeProvider theme={darkTheme}>
  <Box tone="background" padding="lg">
    <Text role="h2">Settings</Text>
  </Box>
</ThemeProvider>;
```

## API [#api]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `theme` | `PrimitiveTheme` | required | every colour, size, radius and font a primitive paints |
| `density` | `Density \| null` | `theme.density` | swaps the numeric metrics group; colours stay, and a stored `null` is no override |
| `messages` | `MessagesSource \| null` | the shipped English | the words a control announces; see §Words |
| `children` | `ReactNode` | — | the tree that may render primitives |

## Words [#words]

A control's state word is interface copy, and this runtime has no `aria-checked`,
`aria-pressed`, `aria-busy` or `aria-valuenow`: a checkbox, a switch, a toggle, a
rating star and a busy action announce `aria-valuetext` or `aria-description`
instead, so a localised interface owns those words.

| Key | Words | Announced by |
| --- | ----- | ------------ |
| `selection` | `checked`, `unchecked`, `mixed` | Checkbox, CheckboxGroup, RadioGroup, Switch |
| `press` | `pressed`, `notPressed` | Toggle, ToggleGroup |
| `star` | `checked`, `half`, `unchecked` | Rating |
| `loading` | `busy`, `indeterminate` | a busy Button/IconButton and its Spinner, an indeterminate Progress |
| `starName(index, max)` | the sentence naming one star | Rating |
| `codeDigit(index, label)` | the sentence naming one code cell | OTPField |
| `rangeEnd(label, end)` | the sentence naming one end | RangeSlider |
| `scrollRegion` | the default name of a focusable scroller | ScrollArea |

A group's rows merge with the table above the provider: a row left out — or
written `null` — keeps that table's word, and a row written blank keeps the
shipped word. `MessagesSource` is the shape a stored table takes, so a decoded
one needs no cast; JSON cannot carry the three sentences, so they are absent and
inherit, and a table written as `null` (a settings record whose `messages` field
was never set) is absence whole — the table above stands.

A slot the store wrote as something a word cannot be also inherits, because a
saved table is data: an app that keeps its copy as a template string wrote text
where `starName`, `codeDigit` or `rangeEnd` belongs, and a row written as a
number, a flag or an object is not a word. Only a function is a sentence and only
text is a row; anything else keeps the table above, rather than being called or
trimmed mid-render.

---

# Toggle

Source: https://gpuixui.sudokw.com/primitives/toggle

A button whose action has a persistent on/off state

<ComponentPreview name="toggle-demo" />

## Usage [#usage]

```tsx
import { Toggle } from "@gpuixui/primitives";
import { useState } from "react";

const [grid, setGrid] = useState(true);

<Toggle pressed={grid} onPressedChange={setGrid} label="Grid" variant="outline">
  Grid
</Toggle>;
```

## API [#api]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `pressed` | `boolean` | — | controlled state |
| `defaultPressed` | `boolean` | `false` | uncontrolled start |
| `onPressedChange` | `(pressed: boolean) => void` | — | called with the new state |
| `variant` | `"default" \| "outline"` | `"default"` | no chrome at rest, or a border; a stored name the table does not carry reads as `default` |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | from the density scale |
| `square` | `boolean` | `false` | equal width and height, for an icon-only toggle |
| `disabled` | `boolean` | `false` | out of the tab order, half opacity, no activation |
| `loading` | `boolean` | `false` | a spinner, the busy word announced, activation refused |
| `loadingLabel` | `string` | `loading.busy` (`"Loading"`) | the busy word, announced as the description and the spinner's name; a blank one silences both |
| `reducedMotion` | `boolean` | the motion provider | holds the busy spinner's lit dot; the prop overrides the provider |
| `leading` / `trailing` | `ReactNode` | — | an icon or a count beside the label |
| `label` | `string` | none | accessible name; required when icon-only |
| `description` | `string` | none | announced help |
| `ref` / `aria-id` / `onLayout` | host address | none | the button element is the addressed element |
| `onClick` / `onKeyDown` / `onKeyUp` / `onFocus` / `onBlur` | host handlers | none | composed with the toggle's own; yours runs first |
| `onMouseEnter` / `onMouseLeave` | host handlers | none | forwarded to the host; the pair a `Tooltip` trigger needs |
| `aria-description` | `string` | none | supplementary description; `Tooltip` passes the tip here |
| `className` | `string` | — | a Tailwind class string, joined after the recipe so it wins conflicts |
| `style` | `StateStyle<ToggleState>` | — | resolved against the live state, merged last |
| `children` | `ReactNode` | — | the visible label |
| `testId` | `string` | — | stable locator |

---

# Toggle group

Source: https://gpuixui.sudokw.com/primitives/toggle-group

A toolbar of related modes, pressed and unpressed

<ComponentPreview name="toggle-group-demo" />

## Usage [#usage]

```tsx
import { ToggleGroup } from "@gpuixui/primitives";

<ToggleGroup
  type="multiple"
  label="Formatting"
  value={formats}
  onValueChange={setFormats}
  options={[
    { value: "bold", label: "Bold" },
    { value: "italic", label: "Italic" },
  ]}
/>;
```

## API [#api]

### `ToggleGroup` [#togglegroup]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `type` | `"single" \| "multiple"` | `"multiple"` | at most one pressed value, or any number |
| `options` | `ReadonlyArray<GroupOption>` | — | the choices as data; omit with item children |
| `children` | `ReactNode` | — | `ToggleGroupItem` elements, for rich content |
| `value` | `string \| ReadonlyArray<string>` | — | controlled pressed values |
| `defaultValue` | `string \| ReadonlyArray<string>` | `[]` | the initial pressed values |
| `onValueChange` | `(next: string \| ReadonlyArray<string>) => void` | none | the pressed values, shaped by `type` |
| `orientation` | `"vertical" \| "horizontal"` | `"horizontal"` | the group's stack direction and arrow pair; a name this release does not carry reads as `"horizontal"` |
| `variant` | `"default" \| "outline"` | `"default"` | no chrome at rest, or a border |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | from the density scale |
| `square` | `boolean` | `false` | equal width and height per option |
| `disabled` | `boolean` | `false` | disables every option and removes the group's stop |
| `label` | `string` | none | the group's accessible name |
| `description` | `string` | none | announced help on the group node |
| `ref` / `aria-id` / `onLayout` | host props | none | land on the option that holds the tab stop |
| `style` | `StateStyle<ToggleGroupState>` | — | resolved against the group's live state, merged last |
| `itemStyle` | `StateStyle<ToggleItemState>` | — | resolved per option button, merged last |
| `onClick` / `onKeyDown` / `onKeyUp` / `onFocus` / `onBlur` | host handlers | none | composed with the group's own; yours runs first |
| `className` | `string` | — | compiled after the recipe, so it wins conflicts |
| `testId` | `string` | — | stable locator for the group |
| `itemTestId` | `(value: string) => string` | — | per-row locator, derived from its value |

### `ToggleGroupItem` [#togglegroupitem]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `value` | `string` | — | the value this option presses |
| `label` | `string` | — | accessible name, and the visible text unless `children` replaces it |
| `description` | `string` | none | a caption beside the name, announced as the row's help (`aria-description`); a blank one paints and announces nothing |
| `disabled` | `boolean` | `false` | the option cannot be pressed and takes no focus |
| `children` | `ReactNode` | — | rich content drawn instead of the name pair |

---

# Charts

Source: https://gpuixui.sudokw.com/graphics/charts

Seventeen chart types, one line of code each

<ComponentPreview name="charts-demo" />

## Usage [#usage]

```tsx
import { BarChart } from "@gpuixui/data";

<BarChart
  aria-label="Revenue against cost by quarter"
  labels={["Q1", "Q2", "Q3", "Q4"]}
  series={[
    { key: "revenue", label: "Revenue", values: [32, 48, 41, 60] },
    { key: "cost", label: "Cost", values: [18, 22, 26, 24] },
  ]}
/>;
```

## The seventeen [#the-seventeen]

| Type | Draws |
| ---- | ----- |
| [`BarChart`](/graphics/charts/charts#barchart) | one bar per category, grouped or single |
| [`StackedBar`](/graphics/charts/charts#stackedbar) | categories stacked to their total |
| [`LineChart`](/graphics/charts/charts#linechart) | a trend per series, linear, smooth or step |
| [`AreaChart`](/graphics/charts/charts#areachart) | a filled trend, stacked or on its own |
| [`ComposedChart`](/graphics/charts/charts#composedchart) | bars and lines on one axis |
| [`ScatterChart`](/graphics/charts/charts#scatterchart) | points, for correlation |
| [`CandleChart`](/graphics/charts/charts#candlechart) | open, high, low and close |
| [`FunnelChart`](/graphics/charts/charts#funnelchart) | stages narrowing to a result |
| [`PieChart`](/graphics/charts/charts#piechart--donutchart) · [`DonutChart`](/graphics/charts/charts#piechart--donutchart) | part-to-whole, as a ring |
| [`RadarChart`](/graphics/charts/charts#radarchart) | a profile across axes |
| [`RadialChart`](/graphics/charts/charts#radialchart) | concentric rings, as a gauge |
| [`RadialBarChart`](/graphics/charts/charts#radialbarchart) | bars extending from the centre |
| [`TreemapChart`](/graphics/charts/charts#treemapchart) | a hierarchy, by area |
| [`SankeyChart`](/graphics/charts/charts#sankeychart) | a flow, by ribbon thickness |
| [`SunburstChart`](/graphics/charts/charts#sunburstchart) | a hierarchy, by arc angle |
| [`Sparkline`](/graphics/charts/charts#sparkline) | a trend in one line |
| [`ChartLegend`](/graphics/charts/charts#chartlegend) | the key beside any of them |

---

# Charts

Source: https://gpuixui.sudokw.com/graphics/charts/charts

Bar, stacked, line, area, pie, donut, radar, radial, treemap, sankey, sunburst and sparkline charts

A chart is a **scene**. `BarChart`, `AreaChart`, `PieChart` and the rest compile
to one document, and the runtime paints it as **one element** carrying
**every series' own colour** and a **real gradient**.

The compiler is [TanStack Charts](https://tanstack.com/charts), and only
its DOM-free subpaths are used — `/scene`, `/line`, `/bar`, `/area`, `/tick`,
`/svg` and `/scales/*` — because its DOM renderers need a `document` this
runtime does not have.

Every component below takes the same frame options — `grid`, `tooltip`,
`colors`, `legend`, `axis`, `xLabels`, `ticks`, `width`, `height` and `config`.

## API [#api]

### `BarChart` [#barchart]

```tsx
<BarChart
  aria-label="Signups by month"
  labels={MONTHS}
  series={[{ key: "signups", label: "Signups", values: SIGNUPS }]}
  orientation="horizontal" // vertical by default
  radius={4}
  valueLabels
  valueLabelFormat={(value, series) => `${series.label} ${value}`}
/>;
```

Negative values stand below the axis; a zero paints no bar but keeps its slot.


| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `orientation` | `"vertical" \| "horizontal"` | `"vertical"` | bars grow up, or right from the axis |
| `radius` | `number` | `3` | the bar's corner, clamped to half its width and height |
| `valueLabels` | `boolean` | `false` | each bar's value prints above it |
| `valueLabelFormat` | `(value, series, category) => string` | `valueFormat`, then the value | what a bar's label says |

### `StackedBar` [#stackedbar]

```tsx
<StackedBar
  aria-label="Revenue and cost"
  labels={QUARTERS}
  series={[revenue, cost]}
  percent // each category reads as 100%
/>;
```


| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `radius` | `number` | `3` | the segment's corner, clamped to the bar |
| `percent` | `boolean` | `false` | values become shares of each category's total, on a 0–100 axis |

### `LineChart` [#linechart]

```tsx
<LineChart
  aria-label="Churn"
  labels={QUARTERS}
  series={[churn]}
  curve="smooth" // linear, smooth or step
  dots
  showLabels
  dotIcons={["check", "info", "bell", "circle"]}
  lineWidth={2}
/>;
```


| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `curve` | `"linear" \| "smooth" \| "step"` | `"linear"` | a spline through every point, or a held step |
| `dots` | `boolean` | `false` | a dot paints on every point |
| `dashed` | `boolean` | `false` | the line paints dashes |
| `lineWidth` | `number` | `2` | the stroke's weight, in pixels |
| `showLabels` | `boolean` | `false` | each point's value paints above it |
| `dotIcons` | `IconName[]` | none | an icon per category paints on each point |
| `pointTooltip` | `boolean` | `false` | a hit zone on every point shows that datum |
| `dotIcons` | `IconName[]` | none | an icon per category paints on each point |

### `ScatterChart` [#scatterchart]

```tsx
<ScatterChart
  aria-label="Response time against load"
  labels={LOADS}
  series={[{ key: "latency", label: "Latency", values: [12, 30, 58] }]}
/>;
```

One point per datum, and no line between them: a point sits where its value
sits, so a point outside the range is clipped to the plot's edge rather than
drawing outside the frame. A datum with no number paints no point.

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `radius` | `number` | `3` | each point's radius, in pixels |

### `CandleChart` [#candlechart]

```tsx
<CandleChart
  aria-label="Daily prices"
  labels={DAYS}
  series={[]}
  candles={[
    { open: 10, high: 20, low: 5, close: 18 },
    { open: 18, high: 19, low: 12, close: 13 },
  ]}
/>;
```

The open, high, low and close of each period. A candle that closed **above**
its open paints in the `upColor` and one that closed at or below it in the
`downColor`, so a reader who cannot separate two hues still reads the
direction.

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `candles` | `Candle[]` | — | the open, high, low and close of each period, one per category |
| `width` | `number` | `6` | each candle's body width, in pixels |
| `upColor` | `string` | the theme's `success` | the colour an up day paints |
| `downColor` | `string` | the theme's `destructive` | the colour a down day paints |

### `FunnelChart` [#funnelchart]

```tsx
<FunnelChart
  aria-label="Signups"
  labels={["Visit", "Sign up", "Buy"]}
  series={[]}
  stages={[100, 60, 20]}
/>;
```

A stage per datum, each a share of the **first**. The stages are centred and
narrow, so a funnel reads as a funnel rather than as bars of different widths
stacked to one side.

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `stages` | `number[]` | — | each stage's value; the first is the widest |
| `stageLabels` | `string[]` | the categories | the names the stages answer to |

### `TreemapChart` [#treemapchart]

```tsx
<TreemapChart
  aria-label="Where the time goes"
  nodes={[
    { path: "engineering", value: 60 },
    { path: "design", value: 25 },
    { path: "operations", value: 15 },
  ]}
/>
```

A hierarchy as nested rectangles, each area its value's share of the whole.
The cells are **squared** by the compiler, so a large value is a wide cell
rather than a tall one — the shape reads as the value's shape.

A node's **path** is its route through the tree: `"root/engineering"` is a
node named `engineering` under `root`. The list may name only the leaves — a
root is added when the list names none — and a node that carries no value of
its own holds its subtree's.

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `nodes` | `{ path: string; value?: number }[]` | — | the hierarchy, one row per node |
| `size` | `number` | `200` | the plot's size, in pixels |
| `method` | `"squarify" \| "binary" \| "dice" \| "slice" \| "slice-dice"` | `"squarify"` | how the cells are squared |
| `ratio` | `number` | the compiler's | the target aspect ratio of a cell |
| `paddingInner` | `number` | `0` | the gap between adjacent cells |
| `paddingOuter` | `number` | `0` | the gap between a parent's edge and its children |
| `colors` | `string[]` | the theme's series scale | the categorical palette |
| `nodeColors` | `Map<string, string>` | — | a node's own colour, by its path |
| `legend` | `boolean` | `true` | the legend paints under the cells |
| `valueFormat` | `(value: number) => string` | — | how a value prints in the legend |
| `animate` | `boolean` | `true` | a mount and a data change animate |
| `animationDuration` | `number` | `1500` | how long a mount or a data change takes, in ms |
| `testId` | `string` | — | the chart's test id; a cell is `${testId}-cell-${path}` |
| `label` | `string` | the chart's own name | the name the document announces |

### `RadialBarChart` [#radialbarchart]

```tsx
<RadialBarChart
  aria-label="The letters"
  data={[
    { key: "E", label: "E", value: 40 },
    { key: "T", label: "T", value: 30 },
    { key: "A", label: "A", value: 20 },
  ]}
/>
```

One bar per category, each extending out from the centre. The bar's length
is its value's share of the largest, and the categories own their own slots
around the circle — so a reader compares the lengths and the sectors at
once.

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `data` | `{ key: string; label?: string; value: number }[]` | — | one row per category |
| `size` | `number` | `200` | the plot's size, in pixels |
| `radiusRatio` | `number` | `0.8` | the share of the plot the bars' ring occupies |
| `bandPadding` | `number` | `0.12` | the share of each category's slot left empty |
| `colors` | `string[]` | the theme's series scale | the categorical palette |
| `legend` | `boolean` | `true` | the legend paints under the bars |
| `valueFormat` | `(value: number) => string` | — | how a value prints in the legend |
| `animate` | `boolean` | `true` | a mount and a data change animate |
| `animationDuration` | `number` | `1500` | how long a mount or a data change takes, in ms |
| `testId` | `string` | — | the chart's test id; a cell is `${testId}-cell-${path}` |
| `label` | `string` | the chart's own name | the name the document announces |

### `SankeyChart` [#sankeychart]

```tsx
<SankeyChart
  aria-label="The pipeline"
  nodes={[
    { id: "visits", name: "Visits" },
    { id: "signups", name: "Signups" },
    { id: "buys", name: "Buys" },
  ]}
  links={[
    { source: "visits", target: "signups", value: 60 },
    { source: "signups", target: "buys", value: 20 },
  ]}
/>
```

A flow between nodes, each ribbon's thickness its value. A link naming a node
the graph does not hold is **dropped**: the compiler rejects such a link, and
a reader who drew a flow to a node that is not there would rather see the
flow that is.

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `nodes` | `{ id: string; name?: string }[]` | — | the nodes the flow runs through |
| `links` | `{ source: string; target: string; value: number }[]` | — | the edges the flow runs along |
| `size` | `number` | `200` | the plot's size, in pixels |
| `nodeWidth` | `number` | the compiler's | a node's width, in pixels |
| `nodePadding` | `number` | the compiler's | the gap between same-column nodes |
| `colors` | `string[]` | the theme's series scale | the categorical palette |
| `nodeColors` | `Map<string, string>` | — | a node's own colour, by its id |
| `legend` | `boolean` | `true` | the legend paints under the flow |
| `valueFormat` | `(value: number) => string` | — | how a value prints in the legend |
| `animate` | `boolean` | `true` | a mount and a data change animate |
| `animationDuration` | `number` | `1500` | how long a mount or a data change takes, in ms |
| `testId` | `string` | — | the chart's test id; a cell is `${testId}-cell-${path}` |
| `label` | `string` | the chart's own name | the name the document announces |

### `SunburstChart` [#sunburstchart]

```tsx
<SunburstChart
  aria-label="The store"
  nodes={[
    { path: "root/engineering", value: 60 },
    { path: "root/design", value: 25 },
    { path: "root/operations", value: 15 },
  ]}
/>
```

The same hierarchy a treemap draws, as **concentric rings**: each arc's angle
is its value's share of its parent, and the rings are drawn from the centre
out. A hierarchy deeper than `visibleDepth` is not drawn.

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `nodes` | `{ path: string; value?: number }[]` | — | the hierarchy, one row per node |
| `size` | `number` | `200` | the plot's size, in pixels |
| `innerRadius` | `number` | the compiler's | the hole at the centre, as a share of the outer radius |
| `ringPadding` | `number` | `0` | the gap between the rings, in pixels |
| `visibleDepth` | `number` | every ring | how many rings of the hierarchy are drawn |
| `colors` | `string[]` | the theme's series scale | the categorical palette |
| `nodeColors` | `Map<string, string>` | — | a node's own colour, by its path |
| `legend` | `boolean` | `true` | the legend paints under the rings |
| `valueFormat` | `(value: number) => string` | — | how a value prints in the legend |
| `animate` | `boolean` | `true` | a mount and a data change animate |
| `animationDuration` | `number` | `1500` | how long a mount or a data change takes, in ms |
| `testId` | `string` | — | the chart's test id; a cell is `${testId}-cell-${path}` |
| `label` | `string` | the chart's own name | the name the document announces |

### `ComposedChart` [#composedchart]

```tsx
<ComposedChart
  aria-label="Installs and conversion"
  labels={MONTHS}
  series={[installs, conversion]}
  lineKeys={["conversion"]}
/>;
```

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `lineKeys` | `string[]` | `[]` | those series paint as lines; the rest paint as bars |
| `radius` | `number` | `3` | the bar's corner, clamped to the bar |

### `AreaChart` [#areachart]

```tsx
<AreaChart
  aria-label="Revenue by quarter"
  labels={QUARTERS}
  series={[revenue, cost]}
  stacked
  gradient
/>;
```


| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `curve` | `"linear" \| "smooth" \| "step"` | `"smooth"` | how the area's edge joins its points |
| `stacked` | `boolean` | `false` | each series stands on the one before it |
| `gradient` | `boolean` | `true` | the fill fades toward the axis in nested bands |
| `fillOpacity` | `number` | `0.35` | the fill's top opacity |
| `dots` | `boolean` | `false` | a dot paints on every point |
| `lineWidth` | `number` | `2` | the edge's stroke weight |
| `showLabels` | `boolean` | `false` | each point's value paints above it |
| `pointTooltip` | `boolean` | `false` | a hit zone on every point shows that datum |
| `dotIcons` | `IconName[]` | none | an icon per category paints on each point |

### `PieChart` · `DonutChart` [#piechart--donutchart]

```tsx
<PieChart
  aria-label="Traffic by source"
  data={sources}
  size={160}
  padAngle={0.03}
  showLabels
  stacked
  labelPosition="outside"
  labelFormat={(datum, share) => `${datum.label} ${Math.round(share * 100)}%`}
  activeIndex={active} // controlled: set it from a press
  onSliceActivate={(datum, index) => setActive(index)}
/>;
```


| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `data` | `ChartDatum[]` | — | `{ key, label, value }` per slice |
| `size` | `number` | `160` | the ring's square box |
| `innerRadius` | `number` | `0` (`0.62` for `DonutChart`) | the hole's share of the radius |
| `padAngle` | `number` | `0.02` | the gap between slices, in radians |
| `legend` | `boolean` | `true` | paints the legend under the ring |
| `legendValues` | `boolean` | `true` | each legend row prints its value |
| `colors` | `string[]` | the theme scale | the palette override |
| `valueFormat` | `(value: number) => string` | one decimal | how a value prints |
| `centerLabel` | `string` | none | words in the ring's centre |
| `showLabels` | `boolean` | `false` | each slice's label paints on its arc |
| `labelPosition` | `"inside" \| "outside"` | `"inside"` | a label inside the arc, or outside with a leader line |
| `labelFormat` | `(datum, share) => string` | the datum's label | what a slice's label says |
| `activeIndex` | `number` | none | that slice stands proud of the ring |
| `stacked` | `boolean` | `false` | each datum owns a concentric band instead of a slice |
| `onSliceActivate` | `(datum, index) => void` | none | a press on a slice reports the datum |
| `animate` | `boolean` | `true` | a mount and a data change animate |
| `animationDuration` | `number` | `1500` | how long a mount or a data change takes, in ms |
| `className` | `string` | — | joined after the recipe |
| `testId` | `string` | — | the ring's locator; a slice is `-layer-<key>` |

### `RadarChart` [#radarchart]

```tsx
<RadarChart
  aria-label="Coverage by discipline"
  labels={["Ship", "Review", "Test", "Design", "Docs"]}
  series={[team]}
  levels={4}
  gridShape="circle"
  gridFill
  gridAt={[0.25, 0.5, 0.75, 1]}
  radius={80}
  dots
  dotIcons={["check", "circle", "info", "bell", "eye"]}
  axisLabelFormat={(label) => label.toUpperCase()}
/>;
```


| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `levels` | `number` | `4` | the number of webs the grid draws |
| `dots` | `boolean` | `false` | a dot paints on every corner |
| `fillOpacity` | `number` | `0.25` | the series polygon's opacity |
| `webs` | `boolean` | `true` | the webs and spokes paint |
| `gridShape` | `"polygon" \| "circle"` | `"polygon"` | the web follows the axes, or rings at each level |
| `gridFill` | `boolean` | `false` | the webs fill at a low opacity |
| `fill` | `boolean` | `true` | the series polygon fills; `false` draws lines only |
| `radius` | `number` | the box's half, less padding | the outer radius in pixels |
| `gridAt` | `number[]` | even levels | the webs' radii, as fractions of the outer radius |
| `dotIcons` | `IconName[]` | none | an icon per axis paints on every corner |
| `axisLabelFormat` | `(label, index) => string` | the label as given | how an axis label prints |
| `pointTooltip` | `boolean` | `false` | a hit zone on every corner shows that axis' datum |

### `RadialChart` [#radialchart]

```tsx
<RadialChart
  aria-label="Storage by service"
  data={storage}
  max={100}
  centerLabel="62%"
  thickness={10}
  track
  grid
  rounded
  showLabels
/>;
```


| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `data` | `ChartDatum[]` | — | one concentric ring per datum |
| `size` | `number` | `160` | the plot's square box |
| `max` | `number` | the largest datum | the value a full ring stands for |
| `thickness` | `number` | `10` | one ring's thickness |
| `gap` | `number` | `4` | the space between rings |
| `track` | `boolean` | `false` | a muted ring behind each value |
| `grid` | `boolean` | `false` | guide rings at each quarter of the radius |
| `rounded` | `boolean` | `false` | each arc's ends round off with a cap |
| `showLabels` | `boolean` | `false` | each ring's value prints at the end of its arc |
| `animate` | `boolean` | `true` | a mount and a data change animate |
| `animationDuration` | `number` | `1500` | how long a mount or a data change takes, in ms |
| `legend` | `boolean` | `true` | paints the legend under the rings |
| `colors` | `string[]` | the theme scale | the palette override |
| `valueFormat` | `(value: number) => string` | one decimal | how a value prints |
| `centerLabel` | `string` | none | words at the rings' centre |
| `className` | `string` | — | joined after the recipe |
| `testId` | `string` | — | the chart's locator; a ring is `-layer-<key>` |

### `Sparkline` [#sparkline]

```tsx
<Sparkline aria-label="Revenue trend" values={revenue.values} width={120} height={32} />;
```


| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `values` | `number[]` | — | one point each, in paint order |
| `width` | `number` | `120` | the plot's width |
| `height` | `number` | `32` | the plot's height |
| `color` | `string` | the first categorical swatch | the line's colour; a blank one is the default |
| `curve` | `"linear" \| "smooth" \| "step"` | `"smooth"` | how the line joins its points |
| `filled` | `boolean` | `false` | the line fills down to the floor |
| `animate` | `boolean` | `true` | a mount and a data change animate |
| `animationDuration` | `number` | `1500` | how long a mount or a data change takes, in ms |
| `className` | `string` | — | joined after the recipe |
| `testId` | `string` | — | the plot's locator |

### `ChartLegend` [#chartlegend]

```tsx
<ChartLegend
  items={[
    { key: "revenue", label: "Revenue", color: series1 },
    { key: "cost", label: "Cost", color: series2 },
  ]}
/>;
```


| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `items` | `ChartLegendItem[]` | — | `{ key, label, color, value? }` per series |
| `shape` | `"square" \| "dot" \| "line"` | `"square"` | the mark beside each row |
| `testId` | `string` | — | the legend's locator; a swatch is `-swatch-<key>` |

### The shared frame [#the-shared-frame]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `series` | `ChartSeries[]` | — | `{ key, label, values, color? }` per series; a blank label reads as `key` |
| `labels` | `string[]` | — | one label per category |
| `config` | `ChartConfig` | — | a keyed table of `{ label?, icon?, color?, theme? }` per series, decoupled from the data; a chart that names it **and** a `data` paints the series the two make |
| `data` | `ChartRow[]` | — | one row per category, one field per series — the `dataKey` route; the first row's first string field names the category |
| `width` | `number` | `320` | the plot's width |
| `height` | `number` | `160` | the plot's height |
| `legend` | `boolean \| "top" \| "bottom"` | 2+ series, bottom | where the legend paints |
| `legendShape` | `"square" \| "dot" \| "line"` | `"square"` | the mark beside each legend row |
| `axis` | `boolean` | `true` | the y-axis tick column |
| `grid` | `boolean` | `true` | the horizontal grid lines |
| `xLabels` | `boolean` | `true` | the category labels |
| `ticks` | `number` | `4` | the steps the axis divides its range into |
| `colors` | `string[]` | the theme scale | the palette override |
| `tooltip` | `boolean` | `true` | the hovered column's readout |
| `tooltipIndicator` | `"dot" \| "line" \| "none" \| "icon"` | `"dot"` | the mark beside each readout row |
| `tooltipIcons` | `IconName[]` | none | an icon per series, when the indicator is `"icon"` |
| `labelFormat` | `(label: string) => string` | the label as given | how the hovered category's name prints |
| `activeBand` | `boolean` | `false` | a wash behind the hovered column |
| `crosshair` | `boolean` | `false` | a vertical rule at the hovered column — the cue a reader follows from the pointer to the value it names |
| `domain` | `[number, number]` | all categories | the category window a brush leaves, as `[start, end)` indexes |
| `view` | `[number, number]` | every category | the continuous window a zoom shows, in category units |
| `zoom` | `boolean` | `false` | a navigation strip that pans on drag and zooms on the wheel |
| `onViewChange` | `(view) => void` | none | reports each pan or zoom step |
| `brush` | `boolean` | `false` | a brush strip under the plot reports a dragged window |
| `onDomainChange` | `(domain) => void` | none | reports each drag step as `[start, end)` |
| `animate` | `boolean` | `true` | a mount and a data change animate |
| `animationDuration` | `number` | `1500` | how long a mount or a data change takes, in ms |
| `valueFormat` | `(value: number) => string` | one decimal | how a value prints in the readout |
| `className` | `string` | — | joined after the recipe |
| `testId` | `string` | — | the chart's locator; a series layer is `-layer-<key>` |

## Limitations [#limitations]

- **Measured in a window**: `chart-surface-lifecycle` (41 checks, 0.11.0)
  samples the bar, the stack, the ring and the line the shipped geometry draws.
- A category label wider than its slot is **clipped at the slot's edge**.
- A mark cannot answer a press, so there is no per-mark tooltip and no zoom.

---

# Diagrams

Source: https://gpuixui.sudokw.com/graphics/diagrams

A Mermaid source, drawn by Pele

A fence tagged `mermaid` is the whole API. [Pele](https://pele.run) renders it at
build time, so the drawing is in the HTML and the fence stays copyable.

```mermaid
flowchart LR
  subgraph author[Author]
    component[Component] --> recipe[Recipe]
  end
  subgraph render[Render]
    recipe --> themed[Themed surface]
    themed --> frame[Frame]
  end
  author --> render
  render --> reader([Reader])
```

| Pele role | The page's role |
| --- | --- |
| `--pele-bg` | `--card` |
| `--pele-fg` | `--foreground` |
| `--pele-muted` | `--muted-foreground` |
| `--pele-line` | `--border-strong` |
| `--pele-surface` | `--muted` |
| `--pele-accent` | `--ring` |
| `--pele-border` | `--border` |

Every value is a `var()`, so the surface decides the colours.

A source Pele cannot read prints the parser's sentence with the source under it:

```mermaid
this is not a diagram
```

## The `Diagram` component [#the-diagram-component]

A **diagram** is a drawing, and
[the `Diagram` component](/components/diagram) is what draws one. You give it
a Mermaid source and it renders the diagram, themed in the library's own
colours.

The renderer is [Pele](https://pele.run) — a zero-dependency Mermaid renderer
that needs no DOM. Measured in a plain Node process, with `typeof document` and
`typeof window` both `undefined`, a flowchart rendered to a 403×64 SVG.

```tsx
import { Diagram } from "@gpuixui/components/diagram";

<Diagram
  aria-label="The render path"
  source={"flowchart LR\n  A[Author] --> B[Component]"}
  caption="How a component becomes a picture"
/>;
```

### The theme roles [#the-theme-roles]

The component reads the theme's colours and **bakes them into** the drawing as
literal values, because a raster resolves no custom property — and Pele writes
its palette twice, as the public `--pele-*` set and an internal `--_*` set.

| Pele role | The library's role |
| --- | --- |
| `--pele-bg` | `card` |
| `--pele-fg` | `foreground` |
| `--pele-muted` | `muted-foreground` |
| `--pele-line` | `border-strong` |
| `--pele-surface` | `muted` |
| `--pele-surface-alt` | `accent` |
| `--pele-accent` | `primary` |
| `--pele-border` | `border` |

The three roles that are not colours — `--pele-radius`, `--pele-font` and
`--pele-font-mono` — are given literal values, because a raster carries no
font of its own.

## Interactive diagrams [#interactive-diagrams]

The same Pele render, with a zoom/pan canvas. The drawing below is live — wheel
or the buttons to zoom, drag to pan.

<DiagramExample />

```tsx
import { DiagramView } from "@/components/diagram/DiagramView";
import { ZoomPan } from "@/components/diagram/ZoomPan";

<ZoomPan
  controls={({ zoomIn, zoomOut, resetZoom, centerView, scalePercent }) => (
    <>…</>
  )}
>
  <DiagramView chart={source} config={{ theme: "ocean" }} />
</ZoomPan>;
```

### `DiagramView` [#diagramview]

| Prop | Type | Default |
| --- | --- | --- |
| `chart` | `string` | required |
| `config.theme` | `"default" \| "dark" \| "forest" \| "neutral" \| "base"` or a named palette | `"default"` |
| `config.themeVariables` | `Partial<DiagramThemeVariables>` | none |
| `config.fontFamily` | `string` | Pele's default |
| `config.fontSize` | `number` | Pele's default |
| `config.maxWidth` | `number` | none |
| `config.responsive` | `boolean` | `true` |
| `label` | `string` | `"Diagram"` |
| `onSuccess` | `(svg: string) => void` | none |
| `onError` | `(message: string) => void` | none |
| `className` | `string` | — |

`themeVariables` keeps Mermaid's names (`primaryColor`, `primaryTextColor`,
`primaryBorderColor`, `background`, `textColor`, `lineColor`,
`secondaryColor`, `tertiaryColor`) and maps them to Pele's roles, so a config
copied from Mermaid keeps working. A variable Pele has no role for is ignored
rather than painted as a property nothing reads.

## Playground [#playground]

Edit the source, switch a template, pick a theme, then zoom, fit or reset. Copy and download take the
rendered SVG Pele produced.

<DiagramPlayground />

```tsx
import { DiagramPlayground } from "@/components/diagram/DiagramPlayground";

<DiagramPlayground defaultValue={source} />;
```

The preview renders one deferred value behind the editor, so typing stays
smooth while the diagram still follows the source. Pele is synchronous, so the
picture appears on the same render as its source; there is no spinner state to
show.

## Themes [#themes]

`default` reads the page's roles, so it follows the light/dark switch without a
second render. A named theme sets the `--pele-*` properties on the diagram's
wrapper; the SVG is not rendered again.

| Theme | Character |
| --- | --- |
| `default` | the page's own roles |
| `dark` | slate surfaces and near-white ink |
| `forest` | green surfaces on a pale page |
| `neutral` | grey, no hue |
| `base` | indigo accent |
| `emerald`, `teal`, `lime`, `mint` | green family |
| `coral`, `amber`, `crimson`, `bronze` | warm family |
| `ocean`, `sky`, `indigo` | cool family |
| `violet`, `rose` | purple / pink |
| `slate`, `charcoal` | dark family |

## The category [#the-category]

This is the **Graphics** category: the things the library draws.

| Page | What it is |
| ---- | ---------- |
| [Charts](/graphics/charts/charts) | bar, line, area, pie, radar and radial charts, on the GPU |
| [Icons](/graphics/icons/icon) | the glyph set and its two accessibility rules |
| [Diagrams](/graphics/diagrams) | this page — the `Diagram` component |

The charts are [TanStack Charts](https://github.com/TanStack/charts)' scene
compiler, compiled to a document the runtime's own renderer paints; the icons
are the library's own set; the diagrams are Pele's renderer, on the same
document route. One category, one paint path.

---

# Icon set

Source: https://gpuixui.sudokw.com/graphics/icons

Every glyph the set ships, with the geometry it paints and its naming rule.

- [Icons](https://gpuixui.sudokw.com/graphics/icons/icon): 83 monochrome icons and their size scale

---

# Icons

Source: https://gpuixui.sudokw.com/graphics/icons/icon

83 monochrome icons and their size scale

## Usage [#usage]

```tsx
import { Icon } from "@gpuixui/icons";
import { useTheme } from "@gpuixui/primitives";

const theme = useTheme();

// Decoration: takes itself out of the accessibility tree.
<Icon name="search" color={theme.colors.mutedForeground} />;

// Meaningful on its own: announced as an image.
<Icon name="warning" color={theme.colors.destructive} size="md" label="Overdue" />;
```

An icon is data: the runtime paints it from `<svg source>` and tints it with the
element's own `style.color`. It carries no colour, size or state of its own, so
one markup serves every theme and platform look.

The grid above is the whole set, drawn from the markup the package ships and
painted by the browser through `style.color`, so a tile cannot be redrawn from
memory.

## API [#api]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `name` | `IconName` | required | which icon; TypeScript rejects an unknown name, and a **stored** name the set does not carry paints the `help` mark |
| `color` | `string` | required | the tint; pass a theme role |
| `size` | `IconSize \| number` | `"md"` | a named step or raw pixels; a name the scale does not carry resolves to `md` |
| `label` | `string` | none | accessible name; a non-blank label promotes the icon to an image |
| `testId` | `string` | — | stable locator |
| `rotation` | `number` | `0` | clockwise degrees about the 24x24 centre, written into the markup; `NaN` reads as no turn |
| `motion` | `MotionProps` | none | a tween for the icon's own box: `width`/`height` size the path and `left`/`top` keep it centred, because the runtime has no `transform` |
| `style` | `StyleDesc` | none | extra style merged over the icon's own, last |

## Notes [#notes]
- Monochrome only: no two-tone, duotone or brand marks.
- A static turn, not a spin: use `Spinner` for a moving mark.
- No icon font and no ligatures.

The geometry is Lucide's (`lucide-static@1.61.0`, ISC and MIT), recorded in
`.agents/slop/LICENSES/lucide.md`; `star-filled` and `sort-asc` are the package's own.

---

# Data display

Source: https://gpuixui.sudokw.com/data-display

The data lane's shipped surfaces

**A hidden column leaves the search, and keeps its sort.**

Rows are built from the [layout primitives](/primitives/stack) and the [Components](/components).

## The lane [#the-lane]

Statuses come from `.agents/slop/COMPONENTS.md`.

<LaneTable lane="data-display" />

<ComponentPreview name="table-workflow" />

A header press sorts, a row press selects, the field filters, and the Columns
menu hides a column.

## What ships today [#what-ships-today]

<LanePages lane="data-display" />

| Piece | Page |
| ----- | ---- |
| Table | [Table](/components/table) — the frame, fixed header, measured body, sort, selection, filter, column menu and virtual body |
| List / ListItem | [List](/components/list) |
| Pagination | [Pagination](/components/pagination) |
| Empty state | [Empty state](/components/empty-state) |
| Cards, badges, progress | [Components](/components) |
| Message scroller | [Message scroller](/components/message-scroller) |
| Command menu | [Command menu](/components/command-menu) |

---

# Advanced filtering / query builders

Source: https://gpuixui.sudokw.com/data-display/advanced-filter

A builder over a typed predicate tree

## Usage [#usage]

```tsx
import { AdvancedFilter, emptyTree } from "@gpuixui/data";
import { useState } from "react";

const [tree, setTree] = useState<FilterTree>(emptyTree);

<AdvancedFilter
  fields={[
    { field: "status", label: "Status" },
    { field: "size", label: "Size" },
  ]}
  tree={tree}
  onChange={setTree}
/>;
```

## API [#api]

The tree's own readers are exported beside the builder:

| Export | What it does |
| ------ | ------------ |
| `emptyTree` | the empty `all` group, which matches everything |
| `FilterTree` | the schema a stored query is decoded and validated through |
| `isFilterTree(value)` | whether a value is a tree this release can read |
| `readFilterTree(value)` | `Option<FilterTree>`: a stored query, or the refusal |
| `filterByTree(rows, tree, valueOf)` | the rows a tree keeps |
| `matchesTree(tree, row, valueOf)` | whether one row matches |
| `describeTree(tree)` | the sentence a tree reads as |

### `AdvancedFilter` [#advancedfilter]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `fields` | `AdvancedFilterField[]` | — | the fields a clause may name; a blank label reads as the field's own name, a value that is not a list offers no field, and a list that offers none — or whose entries name a blank `field` — paints no Add control |
| `tree` | `FilterTree` | — | the tree the builder paints |
| `onChange` | `(next: FilterTree) => void` | — | receives every edited tree |
| `title` | `string` | `Filters` | the title above the builder; a blank title reads as `Filters` |
| `className` | `string` | — | joined after the recipe |
| `testId` | `string` | — | the builder's id; a clause is `${testId}-${slot}-…` |

### `AdvancedFilterField` [#advancedfilterfield]

| Field | Type | Consequence |
| ----- | ---- | ----------- |
| `field` | `string` | the field a clause reads, and the fallback name when the label is blank |
| `label` | `string` | the words the builder shows for it |

## A saved query [#a-saved-query]

A tree is stored data: a saved query outlives the release that wrote it, and a
store or a hand-edited record can hand back a node or a comparison this build
does not carry. Decode it before it reaches a builder or a table:

```ts
const saved = readFilterTree(storedQuery);

Option.match(saved, {
  onNone: () => promptToRebuildTheQuery(),
  onSome: (tree) => setTree(tree),
});
```

A tree this release cannot read is **refused, never approximated**: the table
keeps **no** rows rather than showing every record the query meant to hide, and
`describeTree` answers `a filter this release cannot read`. The builder paints
that sentence with Clear, so a reader can recover from a query whose clauses it
cannot edit. A `null`/`undefined` query is no filter at all — `useTable` and the
builder read it as the empty tree.

A tree the schema **can** read may still name no field: a query saved before its
field was picked carries a blank `field`, which the tree's schema accepts. The
builder does not refuse it — there is a clause to edit — it reads the missing
name as `Field`, so the row is named and its sentence says which part is absent.

---

# Charts

Source: https://gpuixui.sudokw.com/data-display/charts

Bar, stacked, line, area, pie, donut, radar, radial and sparkline charts

One `<svg>` per series, tinted through `style.color`. Axis, labels, legend and
the hover readout are text and boxes beside the plot, so every chart inherits the
surface it sits on. The paint is window-verified by `chart-surface-lifecycle`.

## Usage [#usage]

```tsx
import {
  AreaChart,
  BarChart,
  ChartLegend,
  ComposedChart,
  DonutChart,
  LineChart,
  PieChart,
  RadarChart,
  RadialChart,
  Sparkline,
  StackedBar,
} from "@gpuixui/data";

<BarChart
  aria-label="Revenue against cost by quarter"
  labels={["Q1", "Q2", "Q3", "Q4"]}
  series={[
    { key: "revenue", label: "Revenue", values: [32, 48, 41, 60] },
    { key: "cost", label: "Cost", values: [18, 22, 26, 24] },
  ]}
  width={320}
  height={140}
/>;
```

Every cartesian chart shares the frame's options: `grid`, `tooltip`, `colors`,
`legend`, `axis`, `xLabels`, `ticks` and `valueFormat`. Hovering a column shows
each series' value; `tooltip={false}` turns it off.

## API [#api]

### `BarChart` [#barchart]

```tsx
<BarChart
  aria-label="Signups by month"
  labels={MONTHS}
  series={[{ key: "signups", label: "Signups", values: SIGNUPS }]}
  orientation="horizontal" // vertical by default
  radius={4}
  valueLabels
  valueLabelFormat={(value, series) => `${series.label} ${value}`}
/>;
```

Negative values stand below the axis; a zero paints no bar but keeps its slot.


| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `orientation` | `"vertical" \| "horizontal"` | `"vertical"` | bars grow up, or right from the axis |
| `radius` | `number` | `3` | the bar's corner, clamped to half its width and height |
| `valueLabels` | `boolean` | `false` | each bar's value prints above it |
| `valueLabelFormat` | `(value, series, category) => string` | `valueFormat`, then the value | what a bar's label says |

### `StackedBar` [#stackedbar]

```tsx
<StackedBar
  aria-label="Revenue and cost"
  labels={QUARTERS}
  series={[revenue, cost]}
  percent // each category reads as 100%
/>;
```


| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `radius` | `number` | `3` | the segment's corner, clamped to the bar |
| `percent` | `boolean` | `false` | values become shares of each category's total, on a 0–100 axis |

### `LineChart` [#linechart]

```tsx
<LineChart
  aria-label="Churn"
  labels={QUARTERS}
  series={[churn]}
  curve="smooth" // linear, smooth or step
  dots
  showLabels
  dotIcons={["check", "info", "bell", "circle"]}
  lineWidth={2}
/>;
```


| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `curve` | `"linear" \| "smooth" \| "step"` | `"linear"` | a spline through every point, or a held step |
| `dots` | `boolean` | `false` | a dot paints on every point |
| `dashed` | `boolean` | `false` | the line paints dashes |
| `lineWidth` | `number` | `2` | the stroke's weight, in pixels |
| `showLabels` | `boolean` | `false` | each point's value paints above it |
| `dotIcons` | `IconName[]` | none | an icon per category paints on each point |
| `pointTooltip` | `boolean` | `false` | a hit zone on every point shows that datum |
| `dotIcons` | `IconName[]` | none | an icon per category paints on each point |

### `ComposedChart` [#composedchart]

```tsx
<ComposedChart
  aria-label="Installs and conversion"
  labels={MONTHS}
  series={[installs, conversion]}
  lineKeys={["conversion"]}
/>;
```

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `lineKeys` | `string[]` | `[]` | those series paint as lines; the rest paint as bars |
| `radius` | `number` | `3` | the bar's corner, clamped to the bar |

### `AreaChart` [#areachart]

```tsx
<AreaChart
  aria-label="Revenue by quarter"
  labels={QUARTERS}
  series={[revenue, cost]}
  stacked
  gradient
/>;
```


| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `curve` | `"linear" \| "smooth" \| "step"` | `"smooth"` | how the area's edge joins its points |
| `stacked` | `boolean` | `false` | each series stands on the one before it |
| `gradient` | `boolean` | `true` | the fill fades toward the axis in nested bands |
| `fillOpacity` | `number` | `0.35` | the fill's top opacity |
| `dots` | `boolean` | `false` | a dot paints on every point |
| `lineWidth` | `number` | `2` | the edge's stroke weight |
| `showLabels` | `boolean` | `false` | each point's value paints above it |
| `pointTooltip` | `boolean` | `false` | a hit zone on every point shows that datum |
| `dotIcons` | `IconName[]` | none | an icon per category paints on each point |

### `PieChart` · `DonutChart` [#piechart--donutchart]

```tsx
<PieChart
  aria-label="Traffic by source"
  data={sources}
  size={160}
  padAngle={0.03}
  showLabels
  stacked
  labelPosition="outside"
  labelFormat={(datum, share) => `${datum.label} ${Math.round(share * 100)}%`}
  activeIndex={active} // controlled: set it from a press
  onSliceActivate={(datum, index) => setActive(index)}
/>;
```


| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `data` | `ChartDatum[]` | — | `{ key, label, value }` per slice |
| `size` | `number` | `160` | the ring's square box |
| `innerRadius` | `number` | `0` (`0.62` for `DonutChart`) | the hole's share of the radius |
| `padAngle` | `number` | `0.02` | the gap between slices, in radians |
| `legend` | `boolean` | `true` | paints the legend under the ring |
| `legendValues` | `boolean` | `true` | each legend row prints its value |
| `colors` | `string[]` | the theme scale | the palette override |
| `valueFormat` | `(value: number) => string` | one decimal | how a value prints |
| `centerLabel` | `string` | none | words in the ring's centre |
| `showLabels` | `boolean` | `false` | each slice's label paints on its arc |
| `labelPosition` | `"inside" \| "outside"` | `"inside"` | a label inside the arc, or outside with a leader line |
| `labelFormat` | `(datum, share) => string` | the datum's label | what a slice's label says |
| `activeIndex` | `number` | none | that slice stands proud of the ring |
| `stacked` | `boolean` | `false` | each datum owns a concentric band instead of a slice |
| `onSliceActivate` | `(datum, index) => void` | none | a press on a slice reports the datum |
| `animate` | `boolean` | `false` | a data change tweens the ring's values |
| `animationDuration` | `number` | `320` | how long that tween takes, in ms |
| `className` | `string` | — | joined after the recipe |
| `testId` | `string` | — | the ring's locator; a slice is `-layer-<key>` |

### `RadarChart` [#radarchart]

```tsx
<RadarChart
  aria-label="Coverage by discipline"
  labels={["Ship", "Review", "Test", "Design", "Docs"]}
  series={[team]}
  levels={4}
  gridShape="circle"
  gridFill
  gridAt={[0.25, 0.5, 0.75, 1]}
  radius={80}
  dots
  dotIcons={["check", "circle", "info", "bell", "eye"]}
  axisLabelFormat={(label) => label.toUpperCase()}
/>;
```


| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `levels` | `number` | `4` | the number of webs the grid draws |
| `dots` | `boolean` | `false` | a dot paints on every corner |
| `fillOpacity` | `number` | `0.25` | the series polygon's opacity |
| `webs` | `boolean` | `true` | the webs and spokes paint |
| `gridShape` | `"polygon" \| "circle"` | `"polygon"` | the web follows the axes, or rings at each level |
| `gridFill` | `boolean` | `false` | the webs fill at a low opacity |
| `fill` | `boolean` | `true` | the series polygon fills; `false` draws lines only |
| `radius` | `number` | the box's half, less padding | the outer radius in pixels |
| `gridAt` | `number[]` | even levels | the webs' radii, as fractions of the outer radius |
| `dotIcons` | `IconName[]` | none | an icon per axis paints on every corner |
| `axisLabelFormat` | `(label, index) => string` | the label as given | how an axis label prints |
| `pointTooltip` | `boolean` | `false` | a hit zone on every corner shows that axis' datum |

### `RadialChart` [#radialchart]

```tsx
<RadialChart
  aria-label="Storage by service"
  data={storage}
  max={100}
  centerLabel="62%"
  thickness={10}
  track
  grid
  rounded
  showLabels
/>;
```


| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `data` | `ChartDatum[]` | — | one concentric ring per datum |
| `size` | `number` | `160` | the plot's square box |
| `max` | `number` | the largest datum | the value a full ring stands for |
| `thickness` | `number` | `10` | one ring's thickness |
| `gap` | `number` | `4` | the space between rings |
| `track` | `boolean` | `false` | a muted ring behind each value |
| `grid` | `boolean` | `false` | guide rings at each quarter of the radius |
| `rounded` | `boolean` | `false` | each arc's ends round off with a cap |
| `showLabels` | `boolean` | `false` | each ring's value prints at the end of its arc |
| `animate` | `boolean` | `false` | a data change tweens the rings' values |
| `animationDuration` | `number` | `320` | how long that tween takes, in ms |
| `legend` | `boolean` | `true` | paints the legend under the rings |
| `colors` | `string[]` | the theme scale | the palette override |
| `valueFormat` | `(value: number) => string` | one decimal | how a value prints |
| `centerLabel` | `string` | none | words at the rings' centre |
| `className` | `string` | — | joined after the recipe |
| `testId` | `string` | — | the chart's locator; a ring is `-layer-<key>` |

### `Sparkline` [#sparkline]

```tsx
<Sparkline aria-label="Revenue trend" values={revenue.values} width={120} height={32} />;
```


| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `values` | `number[]` | — | one point each, in paint order |
| `width` | `number` | `120` | the plot's width |
| `height` | `number` | `32` | the plot's height |
| `color` | `string` | the first categorical swatch | the line's colour; a blank one is the default |
| `curve` | `"linear" \| "smooth" \| "step"` | `"smooth"` | how the line joins its points |
| `filled` | `boolean` | `false` | the line fills down to the floor |
| `animate` | `boolean` | `false` | a data change tweens the line |
| `animationDuration` | `number` | `320` | how long that tween takes, in ms |
| `className` | `string` | — | joined after the recipe |
| `testId` | `string` | — | the plot's locator |

### `ChartLegend` [#chartlegend]

```tsx
<ChartLegend
  items={[
    { key: "revenue", label: "Revenue", color: series1 },
    { key: "cost", label: "Cost", color: series2 },
  ]}
/>;
```


| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `items` | `ChartLegendItem[]` | — | `{ key, label, color, value? }` per series |
| `shape` | `"square" \| "dot" \| "line"` | `"square"` | the mark beside each row |
| `testId` | `string` | — | the legend's locator; a swatch is `-swatch-<key>` |

### The shared frame [#the-shared-frame]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `series` | `ChartSeries[]` | — | `{ key, label, values, color? }` per series; a blank label reads as `key` |
| `labels` | `string[]` | — | one label per category |
| `width` | `number` | `320` | the plot's width |
| `height` | `number` | `160` | the plot's height |
| `legend` | `boolean \| "top" \| "bottom"` | 2+ series, bottom | where the legend paints |
| `legendShape` | `"square" \| "dot" \| "line"` | `"square"` | the mark beside each legend row |
| `axis` | `boolean` | `true` | the y-axis tick column |
| `grid` | `boolean` | `true` | the horizontal grid lines |
| `xLabels` | `boolean` | `true` | the category labels |
| `ticks` | `number` | `4` | the steps the axis divides its range into |
| `colors` | `string[]` | the theme scale | the palette override |
| `tooltip` | `boolean` | `true` | the hovered column's readout |
| `tooltipIndicator` | `"dot" \| "line" \| "none" \| "icon"` | `"dot"` | the mark beside each readout row |
| `tooltipIcons` | `IconName[]` | none | an icon per series, when the indicator is `"icon"` |
| `labelFormat` | `(label: string) => string` | the label as given | how the hovered category's name prints |
| `activeBand` | `boolean` | `false` | a wash behind the hovered column |
| `domain` | `[number, number]` | all categories | the category window a brush leaves, as `[start, end)` indexes |
| `view` | `[number, number]` | every category | the continuous window a zoom shows, in category units |
| `zoom` | `boolean` | `false` | a navigation strip that pans on drag and zooms on the wheel |
| `onViewChange` | `(view) => void` | none | reports each pan or zoom step |
| `brush` | `boolean` | `false` | a brush strip under the plot reports a dragged window |
| `onDomainChange` | `(domain) => void` | none | reports each drag step as `[start, end)` |
| `animate` | `boolean` | `false` | a data change tweens its values |
| `animationDuration` | `number` | `320` | how long that tween takes, in ms |
| `valueFormat` | `(value: number) => string` | one decimal | how a value prints in the readout |
| `className` | `string` | — | joined after the recipe |
| `testId` | `string` | — | the chart's locator; a series layer is `-layer-<key>` |

## Tooltip [#tooltip]

```tsx
<BarChart
  aria-label="Revenue"
  labels={QUARTERS}
  series={[revenue, cost]}
  tooltipIndicator="line"
  labelFormat={(label) => `Quarter ${label}`}
  valueFormat={(value) => `${value}k`}
  activeBand
/>;
```

The readout follows the pointer inside a column. `tooltipIndicator` marks each
row with a dot, a line or nothing; `labelFormat`
rewrites the category's name and `valueFormat` rewrites every value.

## Legend [#legend]

```tsx
<BarChart
  aria-label="Revenue"
  labels={QUARTERS}
  series={[revenue, cost]}
  legend="top"
  legendShape="line"
/>;

<ChartLegend
  shape="dot"
  items={[
    { key: "revenue", label: "Revenue", color: series1, value: "181k" },
    { key: "cost", label: "Cost", color: series2, value: "90k" },
  ]}
/>;
```

`legendShape` draws a square, a dot or a line before each row; a row with a
`value` prints it after its label.

## Zoom and pan [#zoom-and-pan]

```tsx
<BarChart
  aria-label="Revenue"
  labels={QUARTERS}
  series={[revenue]}
  view={view} // controlled: drag the strip to pan, wheel to zoom
  zoom
  onViewChange={setView}
/>;
```

`view` is a **continuous** window in category units: an edge of `1.5` puts
category 1 half off the plot's left edge, and a span of two shows two
categories. `zoom` paints the navigation strip; dragging it pans and the wheel
zooms around the window's centre. Its **Reset** control returns `[0, labels]`.

## Brush [#brush]

```tsx
<BarChart
  aria-label="Revenue"
  labels={QUARTERS}
  series={[revenue]}
  domain={window} // controlled: the drag reports into it
  brush
  onDomainChange={setWindow}
/>;
```

`brush` paints a strip under the plot; dragging across it reports
`onDomainChange` for the categories it covers, and the controlled `domain` is
what the plot paints. `domain` is the same window as `[start, end)` indexes;
the chart paints only those categories and measures its axis over them. A stored window that is
reversed, fractional or past the end is normalized to whole indexes inside the
list, and a window that leaves nothing paints the whole chart.

## Animation [#animation]

```tsx
<BarChart
  aria-label="Revenue"
  labels={QUARTERS}
  series={[revenue, cost]}
  animate
  animationDuration={320}
/>;
```

`animate` tweens a data change from the values on screen to the new ones;
`animationDuration` is that run in milliseconds. A chart with a
`MotionProvider preference="reduced"` above it paints the new values at once —
the resting frame is the same one the tween lands on.

## Reference parity [#reference-parity]

Every example shadcn's charts app ships, and the native chart that answers it.
Every row is now **native**: a shipped component paints it. The status column
stays so a future gap can be named honestly. **Live** mounts that row's chart
through the real GPUix web build (`/live?scene=parity&only=<id>`).

| Reference | Native | Option | Status | Live |
| --------- | ------ | ------ | ------ | ---- |
| `chart-area-axes` | AreaChart | `axis` | native | [live](/live?scene=parity&only=chart-area-axes) |
| `chart-area-default` | AreaChart | `gradient` | native | [live](/live?scene=parity&only=chart-area-default) |
| `chart-area-gradient` | AreaChart | `gradient` | native | [live](/live?scene=parity&only=chart-area-gradient) |
| `chart-area-icons` | AreaChart | `dotIcons` | native — icons paint as a native overlay on each point | [live](/live?scene=parity&only=chart-area-icons) |
| `chart-area-interactive` | AreaChart | `tooltip` | native | [live](/live?scene=parity&only=chart-area-interactive) |
| `chart-area-legend` | AreaChart | `legend` | native | [live](/live?scene=parity&only=chart-area-legend) |
| `chart-area-linear` | AreaChart | `curve` | native | [live](/live?scene=parity&only=chart-area-linear) |
| `chart-area-stacked` | AreaChart | `stacked` | native | [live](/live?scene=parity&only=chart-area-stacked) |
| `chart-area-stacked-expand` | AreaChart | `stacked` | native | [live](/live?scene=parity&only=chart-area-stacked-expand) |
| `chart-area-step` | AreaChart | `curve` | native | [live](/live?scene=parity&only=chart-area-step) |
| `chart-bar-active` | BarChart | `activeBand` | native | [live](/live?scene=parity&only=chart-bar-active) |
| `chart-bar-default` | BarChart | `radius` | native | [live](/live?scene=parity&only=chart-bar-default) |
| `chart-bar-horizontal` | BarChart | `orientation` | native | [live](/live?scene=parity&only=chart-bar-horizontal) |
| `chart-bar-interactive` | BarChart | `tooltip` | native | [live](/live?scene=parity&only=chart-bar-interactive) |
| `chart-bar-label` | BarChart | `valueLabels` | native | [live](/live?scene=parity&only=chart-bar-label) |
| `chart-bar-label-custom` | BarChart | `valueLabelFormat` | native | [live](/live?scene=parity&only=chart-bar-label-custom) |
| `chart-bar-mixed` | ComposedChart | `lineKeys` | native | [live](/live?scene=parity&only=chart-bar-mixed) |
| `chart-bar-multiple` | BarChart | `series` | native | [live](/live?scene=parity&only=chart-bar-multiple) |
| `chart-bar-negative` | BarChart | `series` | native | [live](/live?scene=parity&only=chart-bar-negative) |
| `chart-bar-stacked` | StackedBar | `percent` | native | [live](/live?scene=parity&only=chart-bar-stacked) |
| `chart-line-default` | LineChart | `lineWidth` | native | [live](/live?scene=parity&only=chart-line-default) |
| `chart-line-dots` | LineChart | `dots` | native | [live](/live?scene=parity&only=chart-line-dots) |
| `chart-line-dots-colors` | LineChart | `colors` | native | [live](/live?scene=parity&only=chart-line-dots-colors) |
| `chart-line-dots-custom` | LineChart | `dotIcons` | native | [live](/live?scene=parity&only=chart-line-dots-custom) |
| `chart-line-interactive` | LineChart | `tooltip` | native | [live](/live?scene=parity&only=chart-line-interactive) |
| `chart-line-label` | LineChart | `showLabels` | native | [live](/live?scene=parity&only=chart-line-label) |
| `chart-line-label-custom` | LineChart | `valueFormat` | native | [live](/live?scene=parity&only=chart-line-label-custom) |
| `chart-line-linear` | LineChart | `curve` | native | [live](/live?scene=parity&only=chart-line-linear) |
| `chart-line-multiple` | LineChart | `series` | native | [live](/live?scene=parity&only=chart-line-multiple) |
| `chart-line-step` | LineChart | `curve` | native | [live](/live?scene=parity&only=chart-line-step) |
| `chart-pie-donut` | DonutChart | `innerRadius` | native | [live](/live?scene=parity&only=chart-pie-donut) |
| `chart-pie-donut-active` | DonutChart | `activeIndex` | native | [live](/live?scene=parity&only=chart-pie-donut-active) |
| `chart-pie-donut-text` | DonutChart | `centerLabel` | native | [live](/live?scene=parity&only=chart-pie-donut-text) |
| `chart-pie-interactive` | PieChart | `onSliceActivate` | native | [live](/live?scene=parity&only=chart-pie-interactive) |
| `chart-pie-label` | PieChart | `showLabels` | native | [live](/live?scene=parity&only=chart-pie-label) |
| `chart-pie-label-custom` | PieChart | `labelFormat` | native | [live](/live?scene=parity&only=chart-pie-label-custom) |
| `chart-pie-label-list` | PieChart | `labelPosition` | native | [live](/live?scene=parity&only=chart-pie-label-list) |
| `chart-pie-legend` | PieChart | `legendValues` | native | [live](/live?scene=parity&only=chart-pie-legend) |
| `chart-pie-separator-none` | PieChart | `padAngle` | native | [live](/live?scene=parity&only=chart-pie-separator-none) |
| `chart-pie-simple` | PieChart | `data` | native | [live](/live?scene=parity&only=chart-pie-simple) |
| `chart-pie-stacked` | PieChart | `stacked` | native — each datum owns a concentric band | [live](/live?scene=parity&only=chart-pie-stacked) |
| `chart-radar-default` | RadarChart | `fill` | native | [live](/live?scene=parity&only=chart-radar-default) |
| `chart-radar-dots` | RadarChart | `dots` | native | [live](/live?scene=parity&only=chart-radar-dots) |
| `chart-radar-grid-circle` | RadarChart | `gridShape` | native | [live](/live?scene=parity&only=chart-radar-grid-circle) |
| `chart-radar-grid-circle-fill` | RadarChart | `gridFill` | native | [live](/live?scene=parity&only=chart-radar-grid-circle-fill) |
| `chart-radar-grid-circle-no-lines` | RadarChart | `webs` | native | [live](/live?scene=parity&only=chart-radar-grid-circle-no-lines) |
| `chart-radar-grid-custom` | RadarChart | `gridAt` | native | [live](/live?scene=parity&only=chart-radar-grid-custom) |
| `chart-radar-grid-fill` | RadarChart | `gridFill` | native | [live](/live?scene=parity&only=chart-radar-grid-fill) |
| `chart-radar-grid-none` | RadarChart | `webs` | native | [live](/live?scene=parity&only=chart-radar-grid-none) |
| `chart-radar-icons` | RadarChart | `dotIcons` | native | [live](/live?scene=parity&only=chart-radar-icons) |
| `chart-radar-label-custom` | RadarChart | `axisLabelFormat` | native | [live](/live?scene=parity&only=chart-radar-label-custom) |
| `chart-radar-legend` | RadarChart | `legend` | native | [live](/live?scene=parity&only=chart-radar-legend) |
| `chart-radar-lines-only` | RadarChart | `fill` | native | [live](/live?scene=parity&only=chart-radar-lines-only) |
| `chart-radar-multiple` | RadarChart | `series` | native | [live](/live?scene=parity&only=chart-radar-multiple) |
| `chart-radar-radius` | RadarChart | `radius` | native | [live](/live?scene=parity&only=chart-radar-radius) |
| `chart-radial-grid` | RadialChart | `grid` | native | [live](/live?scene=parity&only=chart-radial-grid) |
| `chart-radial-label` | RadialChart | `showLabels` | native | [live](/live?scene=parity&only=chart-radial-label) |
| `chart-radial-shape` | RadialChart | `rounded` | native | [live](/live?scene=parity&only=chart-radial-shape) |
| `chart-radial-simple` | RadialChart | `data` | native | [live](/live?scene=parity&only=chart-radial-simple) |
| `chart-radial-stacked` | RadialChart | `data` | native | [live](/live?scene=parity&only=chart-radial-stacked) |
| `chart-radial-text` | RadialChart | `centerLabel` | native | [live](/live?scene=parity&only=chart-radial-text) |
| `chart-tooltip-advanced` | BarChart | `tooltip` | native | [live](/live?scene=parity&only=chart-tooltip-advanced) |
| `chart-tooltip-default` | BarChart | `tooltip` | native | [live](/live?scene=parity&only=chart-tooltip-default) |
| `chart-tooltip-formatter` | BarChart | `valueFormat` | native | [live](/live?scene=parity&only=chart-tooltip-formatter) |
| `chart-tooltip-icons` | BarChart | `tooltipIcons` | native — each readout row paints its series' icon | [live](/live?scene=parity&only=chart-tooltip-icons) |
| `chart-tooltip-indicator-line` | BarChart | `tooltipIndicator` | native | [live](/live?scene=parity&only=chart-tooltip-indicator-line) |
| `chart-tooltip-indicator-none` | BarChart | `tooltipIndicator` | native | [live](/live?scene=parity&only=chart-tooltip-indicator-none) |
| `chart-tooltip-label-custom` | BarChart | `labelFormat` | native | [live](/live?scene=parity&only=chart-tooltip-label-custom) |
| `chart-tooltip-label-formatter` | BarChart | `labelFormat` | native | [live](/live?scene=parity&only=chart-tooltip-label-formatter) |
| `chart-legend-default` | ChartLegend | `items` | native | [live](/live?scene=parity&only=chart-legend-default) |
| `chart-legend-shapes` | ChartLegend | `shape` | native | [live](/live?scene=parity&only=chart-legend-shapes) |

## Limitations [#limitations]

- One tint per layer: two colours inside one series need two layers.
- A category label wider than its slot is clipped at the slot's edge, so two
  neighbouring categories never paint over each other.
- No zoom, pan or animation between data sets.
- A hover readout is per category, not per mark: it names every series' value at
  that column rather than the one shape under the pointer.

---

# Charts

Source: https://gpuixui.sudokw.com/data-display/charts/charts

Bar, stacked, line, area, pie, donut, radar, radial, treemap, sankey, sunburst and sparkline charts

A chart is a **scene**. `BarChart`, `AreaChart`, `PieChart` and the rest compile
to one document, and the runtime paints it as **one element** carrying
**every series' own colour** and a **real gradient**.

The compiler is [TanStack Charts](https://tanstack.com/charts), and only
its DOM-free subpaths are used — `/scene`, `/line`, `/bar`, `/area`, `/tick`,
`/svg` and `/scales/*` — because its DOM renderers need a `document` this
runtime does not have.

Every component below takes the same frame options — `grid`, `tooltip`,
`colors`, `legend`, `axis`, `xLabels`, `ticks`, `width`, `height` and `config`.

## API [#api]

### `BarChart` [#barchart]

```tsx
<BarChart
  aria-label="Signups by month"
  labels={MONTHS}
  series={[{ key: "signups", label: "Signups", values: SIGNUPS }]}
  orientation="horizontal" // vertical by default
  radius={4}
  valueLabels
  valueLabelFormat={(value, series) => `${series.label} ${value}`}
/>;
```

Negative values stand below the axis; a zero paints no bar but keeps its slot.


| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `orientation` | `"vertical" \| "horizontal"` | `"vertical"` | bars grow up, or right from the axis |
| `radius` | `number` | `3` | the bar's corner, clamped to half its width and height |
| `valueLabels` | `boolean` | `false` | each bar's value prints above it |
| `valueLabelFormat` | `(value, series, category) => string` | `valueFormat`, then the value | what a bar's label says |

### `StackedBar` [#stackedbar]

```tsx
<StackedBar
  aria-label="Revenue and cost"
  labels={QUARTERS}
  series={[revenue, cost]}
  percent // each category reads as 100%
/>;
```


| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `radius` | `number` | `3` | the segment's corner, clamped to the bar |
| `percent` | `boolean` | `false` | values become shares of each category's total, on a 0–100 axis |

### `LineChart` [#linechart]

```tsx
<LineChart
  aria-label="Churn"
  labels={QUARTERS}
  series={[churn]}
  curve="smooth" // linear, smooth or step
  dots
  showLabels
  dotIcons={["check", "info", "bell", "circle"]}
  lineWidth={2}
/>;
```


| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `curve` | `"linear" \| "smooth" \| "step"` | `"linear"` | a spline through every point, or a held step |
| `dots` | `boolean` | `false` | a dot paints on every point |
| `dashed` | `boolean` | `false` | the line paints dashes |
| `lineWidth` | `number` | `2` | the stroke's weight, in pixels |
| `showLabels` | `boolean` | `false` | each point's value paints above it |
| `dotIcons` | `IconName[]` | none | an icon per category paints on each point |
| `pointTooltip` | `boolean` | `false` | a hit zone on every point shows that datum |
| `dotIcons` | `IconName[]` | none | an icon per category paints on each point |

### `ScatterChart` [#scatterchart]

```tsx
<ScatterChart
  aria-label="Response time against load"
  labels={LOADS}
  series={[{ key: "latency", label: "Latency", values: [12, 30, 58] }]}
/>;
```

One point per datum, and no line between them: a point sits where its value
sits, so a point outside the range is clipped to the plot's edge rather than
drawing outside the frame. A datum with no number paints no point.

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `radius` | `number` | `3` | each point's radius, in pixels |

### `CandleChart` [#candlechart]

```tsx
<CandleChart
  aria-label="Daily prices"
  labels={DAYS}
  series={[]}
  candles={[
    { open: 10, high: 20, low: 5, close: 18 },
    { open: 18, high: 19, low: 12, close: 13 },
  ]}
/>;
```

The open, high, low and close of each period. A candle that closed **above**
its open paints in the `upColor` and one that closed at or below it in the
`downColor`, so a reader who cannot separate two hues still reads the
direction.

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `candles` | `Candle[]` | — | the open, high, low and close of each period, one per category |
| `width` | `number` | `6` | each candle's body width, in pixels |
| `upColor` | `string` | the theme's `success` | the colour an up day paints |
| `downColor` | `string` | the theme's `destructive` | the colour a down day paints |

### `FunnelChart` [#funnelchart]

```tsx
<FunnelChart
  aria-label="Signups"
  labels={["Visit", "Sign up", "Buy"]}
  series={[]}
  stages={[100, 60, 20]}
/>;
```

A stage per datum, each a share of the **first**. The stages are centred and
narrow, so a funnel reads as a funnel rather than as bars of different widths
stacked to one side.

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `stages` | `number[]` | — | each stage's value; the first is the widest |
| `stageLabels` | `string[]` | the categories | the names the stages answer to |

### `TreemapChart` [#treemapchart]

```tsx
<TreemapChart
  aria-label="Where the time goes"
  nodes={[
    { path: "engineering", value: 60 },
    { path: "design", value: 25 },
    { path: "operations", value: 15 },
  ]}
/>
```

A hierarchy as nested rectangles, each area its value's share of the whole.
The cells are **squared** by the compiler, so a large value is a wide cell
rather than a tall one — the shape reads as the value's shape.

A node's **path** is its route through the tree: `"root/engineering"` is a
node named `engineering` under `root`. The list may name only the leaves — a
root is added when the list names none — and a node that carries no value of
its own holds its subtree's.

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `nodes` | `{ path: string; value?: number }[]` | — | the hierarchy, one row per node |
| `size` | `number` | `200` | the plot's size, in pixels |
| `method` | `"squarify" \| "binary" \| "dice" \| "slice" \| "slice-dice"` | `"squarify"` | how the cells are squared |
| `ratio` | `number` | the compiler's | the target aspect ratio of a cell |
| `paddingInner` | `number` | `0` | the gap between adjacent cells |
| `paddingOuter` | `number` | `0` | the gap between a parent's edge and its children |
| `colors` | `string[]` | the theme's series scale | the categorical palette |
| `nodeColors` | `Map<string, string>` | — | a node's own colour, by its path |
| `legend` | `boolean` | `true` | the legend paints under the cells |
| `valueFormat` | `(value: number) => string` | — | how a value prints in the legend |
| `animate` | `boolean` | `true` | a mount and a data change animate |
| `animationDuration` | `number` | `1500` | how long a mount or a data change takes, in ms |
| `testId` | `string` | — | the chart's test id; a cell is `${testId}-cell-${path}` |
| `label` | `string` | the chart's own name | the name the document announces |

### `RadialBarChart` [#radialbarchart]

```tsx
<RadialBarChart
  aria-label="The letters"
  data={[
    { key: "E", label: "E", value: 40 },
    { key: "T", label: "T", value: 30 },
    { key: "A", label: "A", value: 20 },
  ]}
/>
```

One bar per category, each extending out from the centre. The bar's length
is its value's share of the largest, and the categories own their own slots
around the circle — so a reader compares the lengths and the sectors at
once.

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `data` | `{ key: string; label?: string; value: number }[]` | — | one row per category |
| `size` | `number` | `200` | the plot's size, in pixels |
| `radiusRatio` | `number` | `0.8` | the share of the plot the bars' ring occupies |
| `bandPadding` | `number` | `0.12` | the share of each category's slot left empty |
| `colors` | `string[]` | the theme's series scale | the categorical palette |
| `legend` | `boolean` | `true` | the legend paints under the bars |
| `valueFormat` | `(value: number) => string` | — | how a value prints in the legend |
| `animate` | `boolean` | `true` | a mount and a data change animate |
| `animationDuration` | `number` | `1500` | how long a mount or a data change takes, in ms |
| `testId` | `string` | — | the chart's test id; a cell is `${testId}-cell-${path}` |
| `label` | `string` | the chart's own name | the name the document announces |

### `SankeyChart` [#sankeychart]

```tsx
<SankeyChart
  aria-label="The pipeline"
  nodes={[
    { id: "visits", name: "Visits" },
    { id: "signups", name: "Signups" },
    { id: "buys", name: "Buys" },
  ]}
  links={[
    { source: "visits", target: "signups", value: 60 },
    { source: "signups", target: "buys", value: 20 },
  ]}
/>
```

A flow between nodes, each ribbon's thickness its value. A link naming a node
the graph does not hold is **dropped**: the compiler rejects such a link, and
a reader who drew a flow to a node that is not there would rather see the
flow that is.

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `nodes` | `{ id: string; name?: string }[]` | — | the nodes the flow runs through |
| `links` | `{ source: string; target: string; value: number }[]` | — | the edges the flow runs along |
| `size` | `number` | `200` | the plot's size, in pixels |
| `nodeWidth` | `number` | the compiler's | a node's width, in pixels |
| `nodePadding` | `number` | the compiler's | the gap between same-column nodes |
| `colors` | `string[]` | the theme's series scale | the categorical palette |
| `nodeColors` | `Map<string, string>` | — | a node's own colour, by its id |
| `legend` | `boolean` | `true` | the legend paints under the flow |
| `valueFormat` | `(value: number) => string` | — | how a value prints in the legend |
| `animate` | `boolean` | `true` | a mount and a data change animate |
| `animationDuration` | `number` | `1500` | how long a mount or a data change takes, in ms |
| `testId` | `string` | — | the chart's test id; a cell is `${testId}-cell-${path}` |
| `label` | `string` | the chart's own name | the name the document announces |

### `SunburstChart` [#sunburstchart]

```tsx
<SunburstChart
  aria-label="The store"
  nodes={[
    { path: "root/engineering", value: 60 },
    { path: "root/design", value: 25 },
    { path: "root/operations", value: 15 },
  ]}
/>
```

The same hierarchy a treemap draws, as **concentric rings**: each arc's angle
is its value's share of its parent, and the rings are drawn from the centre
out. A hierarchy deeper than `visibleDepth` is not drawn.

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `nodes` | `{ path: string; value?: number }[]` | — | the hierarchy, one row per node |
| `size` | `number` | `200` | the plot's size, in pixels |
| `innerRadius` | `number` | the compiler's | the hole at the centre, as a share of the outer radius |
| `ringPadding` | `number` | `0` | the gap between the rings, in pixels |
| `visibleDepth` | `number` | every ring | how many rings of the hierarchy are drawn |
| `colors` | `string[]` | the theme's series scale | the categorical palette |
| `nodeColors` | `Map<string, string>` | — | a node's own colour, by its path |
| `legend` | `boolean` | `true` | the legend paints under the rings |
| `valueFormat` | `(value: number) => string` | — | how a value prints in the legend |
| `animate` | `boolean` | `true` | a mount and a data change animate |
| `animationDuration` | `number` | `1500` | how long a mount or a data change takes, in ms |
| `testId` | `string` | — | the chart's test id; a cell is `${testId}-cell-${path}` |
| `label` | `string` | the chart's own name | the name the document announces |

### `ComposedChart` [#composedchart]

```tsx
<ComposedChart
  aria-label="Installs and conversion"
  labels={MONTHS}
  series={[installs, conversion]}
  lineKeys={["conversion"]}
/>;
```

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `lineKeys` | `string[]` | `[]` | those series paint as lines; the rest paint as bars |
| `radius` | `number` | `3` | the bar's corner, clamped to the bar |

### `AreaChart` [#areachart]

```tsx
<AreaChart
  aria-label="Revenue by quarter"
  labels={QUARTERS}
  series={[revenue, cost]}
  stacked
  gradient
/>;
```


| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `curve` | `"linear" \| "smooth" \| "step"` | `"smooth"` | how the area's edge joins its points |
| `stacked` | `boolean` | `false` | each series stands on the one before it |
| `gradient` | `boolean` | `true` | the fill fades toward the axis in nested bands |
| `fillOpacity` | `number` | `0.35` | the fill's top opacity |
| `dots` | `boolean` | `false` | a dot paints on every point |
| `lineWidth` | `number` | `2` | the edge's stroke weight |
| `showLabels` | `boolean` | `false` | each point's value paints above it |
| `pointTooltip` | `boolean` | `false` | a hit zone on every point shows that datum |
| `dotIcons` | `IconName[]` | none | an icon per category paints on each point |

### `PieChart` · `DonutChart` [#piechart--donutchart]

```tsx
<PieChart
  aria-label="Traffic by source"
  data={sources}
  size={160}
  padAngle={0.03}
  showLabels
  stacked
  labelPosition="outside"
  labelFormat={(datum, share) => `${datum.label} ${Math.round(share * 100)}%`}
  activeIndex={active} // controlled: set it from a press
  onSliceActivate={(datum, index) => setActive(index)}
/>;
```


| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `data` | `ChartDatum[]` | — | `{ key, label, value }` per slice |
| `size` | `number` | `160` | the ring's square box |
| `innerRadius` | `number` | `0` (`0.62` for `DonutChart`) | the hole's share of the radius |
| `padAngle` | `number` | `0.02` | the gap between slices, in radians |
| `legend` | `boolean` | `true` | paints the legend under the ring |
| `legendValues` | `boolean` | `true` | each legend row prints its value |
| `colors` | `string[]` | the theme scale | the palette override |
| `valueFormat` | `(value: number) => string` | one decimal | how a value prints |
| `centerLabel` | `string` | none | words in the ring's centre |
| `showLabels` | `boolean` | `false` | each slice's label paints on its arc |
| `labelPosition` | `"inside" \| "outside"` | `"inside"` | a label inside the arc, or outside with a leader line |
| `labelFormat` | `(datum, share) => string` | the datum's label | what a slice's label says |
| `activeIndex` | `number` | none | that slice stands proud of the ring |
| `stacked` | `boolean` | `false` | each datum owns a concentric band instead of a slice |
| `onSliceActivate` | `(datum, index) => void` | none | a press on a slice reports the datum |
| `animate` | `boolean` | `true` | a mount and a data change animate |
| `animationDuration` | `number` | `1500` | how long a mount or a data change takes, in ms |
| `className` | `string` | — | joined after the recipe |
| `testId` | `string` | — | the ring's locator; a slice is `-layer-<key>` |

### `RadarChart` [#radarchart]

```tsx
<RadarChart
  aria-label="Coverage by discipline"
  labels={["Ship", "Review", "Test", "Design", "Docs"]}
  series={[team]}
  levels={4}
  gridShape="circle"
  gridFill
  gridAt={[0.25, 0.5, 0.75, 1]}
  radius={80}
  dots
  dotIcons={["check", "circle", "info", "bell", "eye"]}
  axisLabelFormat={(label) => label.toUpperCase()}
/>;
```


| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `levels` | `number` | `4` | the number of webs the grid draws |
| `dots` | `boolean` | `false` | a dot paints on every corner |
| `fillOpacity` | `number` | `0.25` | the series polygon's opacity |
| `webs` | `boolean` | `true` | the webs and spokes paint |
| `gridShape` | `"polygon" \| "circle"` | `"polygon"` | the web follows the axes, or rings at each level |
| `gridFill` | `boolean` | `false` | the webs fill at a low opacity |
| `fill` | `boolean` | `true` | the series polygon fills; `false` draws lines only |
| `radius` | `number` | the box's half, less padding | the outer radius in pixels |
| `gridAt` | `number[]` | even levels | the webs' radii, as fractions of the outer radius |
| `dotIcons` | `IconName[]` | none | an icon per axis paints on every corner |
| `axisLabelFormat` | `(label, index) => string` | the label as given | how an axis label prints |
| `pointTooltip` | `boolean` | `false` | a hit zone on every corner shows that axis' datum |

### `RadialChart` [#radialchart]

```tsx
<RadialChart
  aria-label="Storage by service"
  data={storage}
  max={100}
  centerLabel="62%"
  thickness={10}
  track
  grid
  rounded
  showLabels
/>;
```


| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `data` | `ChartDatum[]` | — | one concentric ring per datum |
| `size` | `number` | `160` | the plot's square box |
| `max` | `number` | the largest datum | the value a full ring stands for |
| `thickness` | `number` | `10` | one ring's thickness |
| `gap` | `number` | `4` | the space between rings |
| `track` | `boolean` | `false` | a muted ring behind each value |
| `grid` | `boolean` | `false` | guide rings at each quarter of the radius |
| `rounded` | `boolean` | `false` | each arc's ends round off with a cap |
| `showLabels` | `boolean` | `false` | each ring's value prints at the end of its arc |
| `animate` | `boolean` | `true` | a mount and a data change animate |
| `animationDuration` | `number` | `1500` | how long a mount or a data change takes, in ms |
| `legend` | `boolean` | `true` | paints the legend under the rings |
| `colors` | `string[]` | the theme scale | the palette override |
| `valueFormat` | `(value: number) => string` | one decimal | how a value prints |
| `centerLabel` | `string` | none | words at the rings' centre |
| `className` | `string` | — | joined after the recipe |
| `testId` | `string` | — | the chart's locator; a ring is `-layer-<key>` |

### `Sparkline` [#sparkline]

```tsx
<Sparkline aria-label="Revenue trend" values={revenue.values} width={120} height={32} />;
```


| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `values` | `number[]` | — | one point each, in paint order |
| `width` | `number` | `120` | the plot's width |
| `height` | `number` | `32` | the plot's height |
| `color` | `string` | the first categorical swatch | the line's colour; a blank one is the default |
| `curve` | `"linear" \| "smooth" \| "step"` | `"smooth"` | how the line joins its points |
| `filled` | `boolean` | `false` | the line fills down to the floor |
| `animate` | `boolean` | `true` | a mount and a data change animate |
| `animationDuration` | `number` | `1500` | how long a mount or a data change takes, in ms |
| `className` | `string` | — | joined after the recipe |
| `testId` | `string` | — | the plot's locator |

### `ChartLegend` [#chartlegend]

```tsx
<ChartLegend
  items={[
    { key: "revenue", label: "Revenue", color: series1 },
    { key: "cost", label: "Cost", color: series2 },
  ]}
/>;
```


| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `items` | `ChartLegendItem[]` | — | `{ key, label, color, value? }` per series |
| `shape` | `"square" \| "dot" \| "line"` | `"square"` | the mark beside each row |
| `testId` | `string` | — | the legend's locator; a swatch is `-swatch-<key>` |

### The shared frame [#the-shared-frame]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `series` | `ChartSeries[]` | — | `{ key, label, values, color? }` per series; a blank label reads as `key` |
| `labels` | `string[]` | — | one label per category |
| `config` | `ChartConfig` | — | a keyed table of `{ label?, icon?, color?, theme? }` per series, decoupled from the data; a chart that names it **and** a `data` paints the series the two make |
| `data` | `ChartRow[]` | — | one row per category, one field per series — the `dataKey` route; the first row's first string field names the category |
| `width` | `number` | `320` | the plot's width |
| `height` | `number` | `160` | the plot's height |
| `legend` | `boolean \| "top" \| "bottom"` | 2+ series, bottom | where the legend paints |
| `legendShape` | `"square" \| "dot" \| "line"` | `"square"` | the mark beside each legend row |
| `axis` | `boolean` | `true` | the y-axis tick column |
| `grid` | `boolean` | `true` | the horizontal grid lines |
| `xLabels` | `boolean` | `true` | the category labels |
| `ticks` | `number` | `4` | the steps the axis divides its range into |
| `colors` | `string[]` | the theme scale | the palette override |
| `tooltip` | `boolean` | `true` | the hovered column's readout |
| `tooltipIndicator` | `"dot" \| "line" \| "none" \| "icon"` | `"dot"` | the mark beside each readout row |
| `tooltipIcons` | `IconName[]` | none | an icon per series, when the indicator is `"icon"` |
| `labelFormat` | `(label: string) => string` | the label as given | how the hovered category's name prints |
| `activeBand` | `boolean` | `false` | a wash behind the hovered column |
| `crosshair` | `boolean` | `false` | a vertical rule at the hovered column — the cue a reader follows from the pointer to the value it names |
| `domain` | `[number, number]` | all categories | the category window a brush leaves, as `[start, end)` indexes |
| `view` | `[number, number]` | every category | the continuous window a zoom shows, in category units |
| `zoom` | `boolean` | `false` | a navigation strip that pans on drag and zooms on the wheel |
| `onViewChange` | `(view) => void` | none | reports each pan or zoom step |
| `brush` | `boolean` | `false` | a brush strip under the plot reports a dragged window |
| `onDomainChange` | `(domain) => void` | none | reports each drag step as `[start, end)` |
| `animate` | `boolean` | `true` | a mount and a data change animate |
| `animationDuration` | `number` | `1500` | how long a mount or a data change takes, in ms |
| `valueFormat` | `(value: number) => string` | one decimal | how a value prints in the readout |
| `className` | `string` | — | joined after the recipe |
| `testId` | `string` | — | the chart's locator; a series layer is `-layer-<key>` |

## Limitations [#limitations]

- **Measured in a window**: `chart-surface-lifecycle` (41 checks, 0.11.0)
  samples the bar, the stack, the ring and the line the shipped geometry draws.
- A category label wider than its slot is **clipped at the slot's edge**.
- A mark cannot answer a press, so there is no per-mark tooltip and no zoom.

---

# Charts

Source: https://gpuixui.sudokw.com/data-display/charts/index

Seventeen chart types, one line of code each

<ComponentPreview name="charts-demo" />

## Usage [#usage]

```tsx
import { BarChart } from "@gpuixui/data";

<BarChart
  aria-label="Revenue against cost by quarter"
  labels={["Q1", "Q2", "Q3", "Q4"]}
  series={[
    { key: "revenue", label: "Revenue", values: [32, 48, 41, 60] },
    { key: "cost", label: "Cost", values: [18, 22, 26, 24] },
  ]}
/>;
```

## The seventeen [#the-seventeen]

| Type | Draws |
| ---- | ----- |
| [`BarChart`](/graphics/charts/charts#barchart) | one bar per category, grouped or single |
| [`StackedBar`](/graphics/charts/charts#stackedbar) | categories stacked to their total |
| [`LineChart`](/graphics/charts/charts#linechart) | a trend per series, linear, smooth or step |
| [`AreaChart`](/graphics/charts/charts#areachart) | a filled trend, stacked or on its own |
| [`ComposedChart`](/graphics/charts/charts#composedchart) | bars and lines on one axis |
| [`ScatterChart`](/graphics/charts/charts#scatterchart) | points, for correlation |
| [`CandleChart`](/graphics/charts/charts#candlechart) | open, high, low and close |
| [`FunnelChart`](/graphics/charts/charts#funnelchart) | stages narrowing to a result |
| [`PieChart`](/graphics/charts/charts#piechart--donutchart) · [`DonutChart`](/graphics/charts/charts#piechart--donutchart) | part-to-whole, as a ring |
| [`RadarChart`](/graphics/charts/charts#radarchart) | a profile across axes |
| [`RadialChart`](/graphics/charts/charts#radialchart) | concentric rings, as a gauge |
| [`RadialBarChart`](/graphics/charts/charts#radialbarchart) | bars extending from the centre |
| [`TreemapChart`](/graphics/charts/charts#treemapchart) | a hierarchy, by area |
| [`SankeyChart`](/graphics/charts/charts#sankeychart) | a flow, by ribbon thickness |
| [`SunburstChart`](/graphics/charts/charts#sunburstchart) | a hierarchy, by arc angle |
| [`Sparkline`](/graphics/charts/charts#sparkline) | a trend in one line |
| [`ChartLegend`](/graphics/charts/charts#chartlegend) | the key beside any of them |

---

# Column configuration

Source: https://gpuixui.sudokw.com/data-display/column-configuration

Show, hide, reorder and resize a table's columns

## Usage [#usage]

```tsx
import {
  ColumnMenu,
  Table,
  TableBody,
  TableCell,
  TableHeader,
  TableRow,
  TableSortHeader,
  TableViewport,
  columnName,
  useColumns,
  useTable,
} from "@gpuixui/data";

const columns = useColumns({ columns: FILE_COLUMNS });
const table = useTable({
  rows,
  keyOf: (row) => row.id,
  columns: FILE_COLUMNS,
  hiddenColumns: columns.hidden,
});

<ColumnMenu
  state={columns.state}
  onChange={columns.apply}
  onReset={columns.reset}
  testId="file-columns"
/>;

<Table height={320} aria-label="Files">
  <TableViewport>
    <TableHeader>
      <TableRow>
        {columns.visible.map((column) => (
          <TableSortHeader
            key={column.id}
            field={column.id}
            label={column.label}
            width={column.width}
            sort={table.sort}
            onSortPress={table.pressSort}
            resize={{
              minWidth: column.minWidth,
              maxWidth: column.maxWidth,
              // One column's words, read the way its header reads them.
              label: `Resize the ${columnName(column.label, column.id).toLowerCase()} column`,
              onResize: (width) => columns.resize(column.id, width),
            }}
          />
        ))}
      </TableRow>
    </TableHeader>
    <TableBody>
      {table.rows.map((row) => (
        <TableRow key={row.id}>
          {columns.visible.map((column) => (
            <TableCell key={column.id} width={column.width}>
              {column.valueOf(row)}
            </TableCell>
          ))}
        </TableRow>
      ))}
    </TableBody>
  </TableViewport>
</Table>;
```

## The drag [#the-drag]

The divider is a `separator` tab stop inside the header cell it ends, not a
spacer column: its 6px strip paints, which is what lets GPUI's hit test stop on
it. Four rules are the ones a window measured (`pointer-capture`,
`column-resize-lifecycle`):

- **The press arms pointer capture.** The strip subscribes to both `onMouseDown`
  and `onMouseMove`; a move-only strip hears one move of eight and never
  resizes.
- **The press and its moves land before React commits**, so the width a gesture
  started from lives in a ref and is read again at the next press — a second
  drag measures from the width the first one ended at.
- **Only the primary button arms it.** The runtime delivers `mouseDown` for all
  three buttons, so a right press (the context-menu gesture) or a middle one
  would otherwise start a resize nobody asked for.
- **A move that holds no primary button ends the gesture.** The runtime reports
  the button a move holds, and a window the pointer left never hears the
  release. Without that rule the strip stays armed and the reader's next
  **hover** over it resizes the column by however far the pointer travelled; a
  press after it starts a fresh gesture from the width on screen. The dock
  package's divider follows the same rule.

The arrows step the focused divider by `step` (16px), and Home/End name the
column's own bounds; every route clamps, because a reader can hold an arrow
against a bound exactly as a pointer can drag past it. **One number drives the
announcement, the drag and the arrows**: the width read through the column's own
bounds. A width the strip cannot measure (`NaN`) is the floor, and a width past
the bounds is the bound — so a consumer that does not clamp still resizes by a
step instead of landing back on the bound the divider already announced.

## Saving and restoring [#saving-and-restoring]

A reader's column set is worth remembering, and a saved set is **data**: the
release that reads it may have added, renamed or dropped a column since, and a
store writes `null` for a field it never set. Two functions are the boundary —
`columnConfig` saves, `restoreColumns` reads:

```tsx
import { columnConfig, restoreColumns, useColumns } from "@gpuixui/data";

// Save what the reader configured (order, hidden ids and widths).
const saved = columnConfig(columns.state);

// Restore it at mount; the hook reads the configuration once.
const columns = useColumns({ columns: FILE_COLUMNS, stored });

// A controlled grid can read the same data without the hook.
const state = restoreColumns(FILE_COLUMNS, saved);
```

`restoreColumns` applies the saved **order**, **hidden ids** and **widths** to
the definitions the current release ships: a saved id this release dropped is
skipped, and a column the release added follows the saved ones in its
definition's place. Every label, accessor and bound comes from the current
definition, never from the store. A saved width is clamped to the column's own
bounds, and a width that is not a finite number reads as the definition's; a
hidden id that no longer exists hides nothing, and the last visible column
cannot be hidden. A stored value that is not a configuration reads as the
shipped columns, so a corrupt or missing record opens the table rather than
taking it down.

## API [#api]

### `ColumnMenu` [#columnmenu]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `state` | `ColumnState` | — | the configured columns, in paint order |
| `onChange` | `(next: ColumnState) => void` | — | receives every complete next state |
| `onReset` | `() => void` | — | restores the definitions; omit to hide the row |
| `label` | `string` | `"Columns"` | the trigger's label |
| `contentLabel` | `string` | the trigger's label | the menu surface's accessible name |
| `disabled` | `boolean` | — | refuses the trigger |
| `testId` | `string` | — | derives `-toggle-<id>`, `-move-<id>`, `-move-<id>-left`/`-right` and `-reset` |

A blank `label` or `contentLabel` reads as the documented default rather than
publishing an unnamed trigger or surface: a default only covers an *absent*
prop, and a locale table with a missing row answers `""`. The trigger and the
menu both announce `Columns` then (`src/behaviour/surface-a11y.test.tsx`).

A **column's** label is content the same way: a saved configuration can restore
a column with no title and a locale table can answer `""`. Every row the menu
paints for that column reads it through `columnName`, so a blank label reads as
the column's `id` — the visibility row is named `name`, not left unnamed, and
the submenu says `Move name` rather than `Move ` and stops.
(`src/behaviour/surface-a11y.test.tsx` mounts a blank and a whitespace label.)

### `TableColumnDivider` [#tablecolumndivider]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `width` | `number` | — | the column's current width; one outside the bounds reads as the bound, and an unreadable one as the floor |
| `minWidth` | `number` | `80` | the narrowest a drag may reach |
| `maxWidth` | `number` | `640` | the widest a drag may reach |
| `onResize` | `(width: number) => void` | — | receives every clamped width |
| `label` | `string` | `"Resize column"` | the divider's accessible name; a blank one reads as the default |
| `step` | `number` | `16` | pixels one arrow press moves it |
| `className` | `string` | — | joined after the recipe |
| `testId` | `string` | — | the divider's locator |

A **blank** `label` reads as `Resize column` rather than publishing a nameless
control: the divider is a focusable `separator`, so a locale table with a
missing row — or a saved label that answers `""` — used to leave the one control
that resizes a column unnamed while its width stayed announced. A name that
should say *which* column is composed from the column's own words, the way the
header composes it (`columnName`); `src/behaviour/surface-a11y.test.tsx` mounts
an empty and a whitespace label and reads both names off the tree.

### `useColumns` options [#usecolumns-options]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `columns` | `ReadonlyArray<ColumnDef>` | — | the definitions, in paint order |
| `stored` | `unknown` | — | a configuration `columnConfig` saved; read once at mount through `restoreColumns` |

### `useColumns` [#usecolumns]

| Field | Type | Consequence |
| ----- | ---- | ----------- |
| `state` | `ColumnState` | the configured columns |
| `visible` | `ReadonlyArray<Column>` | the one list the header and rows paint |
| `hidden` | `ReadonlyArray<string>` | the hidden ids, for `useTable`'s filter |
| `contentWidth` | `number` | the sum of the visible tracks |
| `widthOf` / `offsetOf` / `isVisible` | `(id) => …` | per-column reads |
| `apply` | `(next: ColumnState) => void` | stores a state a menu produced |
| `setVisible` / `toggle` / `move` / `resize` / `reset` | functions | the reducers, applied |

---

# Data toolbars

Source: https://gpuixui.sudokw.com/data-display/data-toolbar

The row of controls a data surface acts from

## Usage [#usage]

```tsx
import { DataToolbar } from "@gpuixui/data";

<DataToolbar search={{ value: query, onValueChange: setQuery }}>
  <Button onActivate={reset}>Reset</Button>
</DataToolbar>;
```

## API [#api]

### `DataToolbar` [#datatoolbar]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `children` | `ReactNode` | — | the controls the row holds |
| `search` | `ToolbarSearch` | — | the field at the head of the row; a `null` a store wrote for an absent field paints no field |
| `className` | `string` | — | joined after the recipe |
| `testId` | `string` | — | the field derives from it: `${testId}-search` |

### `ToolbarSearch` [#toolbarsearch]

| Field | Type | Default | Consequence |
| ----- | ---- | ------- | ----------- |
| `value` | `string` | — | the query the field shows; the toolbar owns no state |
| `onValueChange` | `(next: string) => void` | — | receives the **debounced** query |
| `placeholder` | `string` | `Search…` | the hint a reader sees in the empty field; a blank one reads as the default |
| `label` | `string` | `Search` | the field's accessible name; a blank name reads as `Search` |
| `debounceMs` | `number` | `150` | how long the query waits before it is reported; `0` reports every edit at once, and a value that is not finite or is negative reads as `150` |

---

# Expandable rows

Source: https://gpuixui.sudokw.com/data-display/expandable-rows

A table row that opens a detail panel under itself

`TableExpandableRow` opens a detail panel under its row.

## Usage [#usage]

```tsx
import {
  Table,
  TableBody,
  TableExpandableRow,
  TableHeader,
  TableHeaderCell,
  TableRow,
  TableViewport,
} from "@gpuixui/data";
import { useState } from "react";

const [open, setOpen] = useState<string | null>(null);

<Table height={300} aria-label="Files with details">
  <TableViewport>
    <TableHeader>
      <TableRow>
        <TableHeaderCell width={32} />
        <TableHeaderCell width={200}>Name</TableHeaderCell>
      </TableRow>
    </TableHeader>
    <TableBody>
      {files.map((file) => (
        <TableExpandableRow
          key={file.id}
          expanded={open === file.id}
          onToggle={() => setOpen(open === file.id ? null : file.id)}
          cells={<TableCell width={200}>{file.name}</TableCell>}
          detail={<KeyValue entries={detailOf(file)} />}
        />
      ))}
    </TableBody>
  </TableViewport>
</Table>;
```

## API [#api]

### `TableExpandableRow` [#tableexpandablerow]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `expanded` | `boolean` | `false` | the panel under the row paints |
| `onToggle` | `() => void` | — | the row's press, and the activation its Enter/Space makes; the caller flips `expanded` |
| `cells` | `ReactNode` | — | the row's cells, after the expander track |
| `detail` | `ReactNode` | — | the panel painted under the row while it is open |
| `toggleWidth` | `number` | `32` | the expander track's width |
| `detailTestId` | `string` | — | the panel's test id |
| `selected` | `boolean` | `false` | the row is chosen: it paints the selection wash (from `TableRow`) |
| `disabled` | `boolean` | `false` | refuses the press and the keys, and paints no pointer state |
| `tabIndex` | `number` | `0` | the row's place in the Tab order; a disabled row takes `-1` |
| `instanceRef` | `Ref<PublicInstance>` | — | the row's painted element, for moving native focus to it |
| `className` | `string` | — | joined after the row's recipe |

---

# Frozen columns

Source: https://gpuixui.sudokw.com/data-display/frozen-columns

A pinned column beside a grid that pans

## Usage [#usage]

```tsx
import { FrozenTable, TableCell, TableHeaderCell, TableRow } from "@gpuixui/data";

<FrozenTable
  height={320}
  frozenWidth={180}
  contentWidth={420}
  rows={table.rows}
  rowKey={(row) => row.id}
  aria-label="Files"
  frozenHeader={
    <TableRow>
      <TableHeaderCell width={180}>Name</TableHeaderCell>
    </TableRow>
  }
  frozenRow={(row) => (
    <TableRow selected={table.isSelected(row.id)} onClick={() => table.pressRow(row)}>
      <TableCell width={180}>{row.name}</TableCell>
    </TableRow>
  )}
  header={
    <TableRow>
      <TableHeaderCell width={140}>Status</TableHeaderCell>
    </TableRow>
  }
  row={(row) => (
    <TableRow selected={table.isSelected(row.id)} onClick={() => table.pressRow(row)}>
      <TableCell width={140}>{row.status}</TableCell>
    </TableRow>
  )}
/>;
```

## API [#api]

### `FrozenTable` [#frozentable]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `height` | `number` | — | the grid's definite height; one the layout cannot paint reads as no height (see below) |
| `frozenWidth` | `number` | — | the frozen pane's width; one the layout cannot paint reads as no width (see below) |
| `contentWidth` | `number` | — | the scrolling columns' total width; one the layout cannot paint reads as no width |
| `rows` | `ReadonlyArray<Row>` | — | the records, in paint order; a value that is not a list paints the empty message (see below) |
| `rowKey` | `(row: Row) => string` | — | the stable React key of a record |
| `frozenHeader` | `ReactNode` | — | the frozen column's header cells |
| `frozenRow` | `(row: Row) => ReactNode` | — | the frozen column's row |
| `header` | `ReactNode` | — | the scrolling columns' header cells |
| `row` | `(row: Row) => ReactNode` | — | the scrolling columns' row |
| `empty` | `ReactNode` | `No rows` | the data pane's empty message, wrapped in a `TableEmpty` row |
| `frozenTestId` / `bodyTestId` / `viewportTestId` | `string` | — | locators for a probe |
| `style` / `testId` / `ref` / `aria-label` | host props | — | on the grid |

## The grid's box [#the-grids-box]

`height` bounds both row scrollers: the frozen pane's and the data pane's each
get the caller's height less the taller of the two measured headers, so a record
keeps one `y` across the seam.

A height is often computed — a share of a window, a pane's measured box, a value
read from storage before the first layout — and one the layout cannot paint
(`NaN`, an infinity, a negative) reads as **no height**: the composition takes
the share of the pane it sits in and bounds both scrollers from the height that
box painted. A height that does paint is the caller's, exactly.

Measured in the renderer on 0.11.0: in a 320-point pane, `height={NaN}` painted
both row scrollers at **0 points** against the **276** the same grid paints with
a readable height, so the grid showed no row at all and neither pane could
scroll. `src/behaviour/paintable-height.test.tsx` holds the case beside the four
other bounded surfaces, and the rule itself lives in `internal/size.ts`.

The two widths are sizes too, and a caller computes them the same way — a share
of the pane, the sum of the columns a release ships, a saved layout read before
the first measurement. A width the layout cannot paint (`NaN`, an infinity, a
negative) reads as **no width**: the frozen pane takes the track its own cells
declare, and the data pane's column takes the pane it sits in. A width that does
paint is the caller's, exactly.

Measured in the renderer on 0.11.0, in a 1280-point frame with a 120-point frozen
cell and a readable `frozenWidth={180}`: `frozenWidth={-180}` painted **no frozen
pane at all** (0 points) and handed the data pane the whole frame (1280), while
`frozenWidth={NaN}` painted the pane at its own content (120) against the 180 the
readable width gives it; `contentWidth={-420}` painted the data pane's column at
**0 points**, so the scrolling header and rows had no box at all.
`src/behaviour/paintable-width.test.tsx` holds the three beside two readable
widths as its control.

## The rows a store kept [#the-rows-a-store-kept]

`rows` is stored data as often as a literal — a saved workspace restores a
panel's rows, and `snapshot?.rows` is `undefined` while the snapshot is still
absent. It is read through `listOf`, so a value that is not a list fills no pane
and the data pane paints its `empty` message (a `TableEmpty` row, `No rows` by
default): an empty grid, not a crashed one.

Measured before the read: `rows={null}` threw
`Cannot read properties of null (reading 'map')` out of the first render, the
frozen pane, the data pane and the empty message all failed to paint, and
`rows={undefined}` threw the same way. `src/behaviour/stored-rows.test.tsx`
mounts both absences and reads the message out of the renderer, with a readable
list as its own control.

---

# Key-value displays

Source: https://gpuixui.sudokw.com/data-display/key-value

A two-column list of labels and values

## Usage [#usage]

```tsx
import { KeyValue } from "@gpuixui/data";

<KeyValue
  entries={[
    { key: "width", label: "Width", value: "120" },
    { key: "height", label: "Height", value: "80" },
  ]}
/>;
```

## API [#api]

### `KeyValue` [#keyvalue]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `entries` | `KeyValueEntry[]` | — | the rows, in the order they paint; a value that is not a list paints no rows, and an entry without a text `key` is not a row |
| `labelWidth` | `number` | `120` | the label column's width; one the layout cannot paint reads as `120` |
| `valueWidth` | `number` | — | the value column's width; omitted — or one that cannot paint — and the value fills the row |
| `className` | `string` | — | joined after the recipe |
| `testId` | `string` | — | every cell derives from it |

### `KeyValueEntry` [#keyvalueentry]

| Field | Type | Consequence |
| ----- | ---- | ----------- |
| `key` | `string` | the stable identity a row is addressed by; the cells derive their ids from it, and an entry whose `key` is not text is not a row |
| `label` | `string` | the words in the fixed label column; a blank one reads as the row's `key` |
| `value` | `ReactNode` | the value, already rendered by the caller; a string or a number is painted as its own `Label` |

---

# Property panels

Source: https://gpuixui.sudokw.com/data-display/property-panel

A panel of property rows over one object the caller owns

<ComponentPreview name="property-panel-demo" />

## Usage [#usage]

```tsx
import { PropertyPanel } from "@gpuixui/data";

<PropertyPanel
  title="Properties"
  rows={[
    { kind: "readonly", key: "tag", label: "Tag", value: tag },
    { kind: "editable", key: "name", label: "Name", value: name, onChange: setName },
  ]}
/>;
```

## API [#api]

### `PropertyPanel` [#propertypanel]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `title` | `string` | — | the panel's header; a blank title paints no header, never an unnamed one |
| `rows` | `PropertyRow[]` | — | the rows, in the order they paint; a blank label reads as the row's key, a value that is not a list paints no rows, and a row without a text `key` is not a row |
| `labelWidth` | `number` | `120` | the label column's width; one the layout cannot paint reads as `120` (the key-value list's rule) |
| `className` | `string` | — | joined after the recipe |

### `PropertyRow` [#propertyrow]

| Field | Type | Which rows | Consequence |
| ----- | ---- | ---------- | ----------- |
| `kind` | `"readonly" \| "editable"` | both | the discriminator; only an editable row carries a change |
| `key` | `string` | both | the stable identity a row is addressed by; an editable row's field is `property-${key}`, and a row whose `key` is not text is not a row |
| `label` | `string` | both | the words in the label column, and an editable field's accessible name |
| `value` | `string` | both | the value the row shows, or the text the field edits |
| `onChange` | `(next: string) => void` | editable | receives every edit of the row's value |

---

# Statistic / metric cards

Source: https://gpuixui.sudokw.com/data-display/stat-card

A card that shows one derived reading

## Usage [#usage]

```tsx
import { StatCard } from "@gpuixui/data";

<StatCard label="Area" value={`${width * height}`} unit="px²" />;
```

## API [#api]

### `StatCard` [#statcard]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `label` | `string` | — | what the reading measures |
| `value` | `ReactNode` | — | the reading, already rendered by the caller |
| `unit` | `string` | — | the unit, beside the reading |
| `hint` | `ReactNode` | — | a line under the reading |
| `trend` | `StatTrend` | — | the movement of the reading; a `null` a store wrote for an absent trend paints no trend |
| `className` | `string` | — | joined after the recipe |

### `StatTrend` [#stattrend]

| Field | Type | Consequence |
| ----- | ---- | ----------- |
| `direction` | `"up" \| "down" \| "flat"` | which way the reading moved; it chooses the status tone's readable role |
| `text` | `string \| null` | the trend's own words, e.g. `+12%`; a nullish or blank one paints no words |

---

# Filtering controls

Source: https://gpuixui.sudokw.com/data-display/table-filtering

The field a data surface narrows its rows from

## Usage [#usage]

```tsx
import { TableFilterField } from "@gpuixui/data";

<TableFilterField
  value={query}
  label="Filter services"
  onValueChange={setQuery}
/>;
```

The field owns no query state: the table holds `value` and narrows on each
`onValueChange`. The field reports every edit at once — a debounce is the
caller's, as `DataToolbar`'s search is — so a table that wants one wraps it.

## API [#api]

### `TableFilterField` [#tablefilterfield]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `value` | `string` | — | the query the field shows; the table owns it |
| `onValueChange` | `(next: string) => void` | — | receives every edit, not a debounced one |
| `label` | `string` | `Filter rows` | the field's accessible name; a blank name reads as the default |
| `placeholder` | `string` | `Filter…` | the hint a reader sees in the empty field; a blank hint reads as the default |
| `width` | `number` | — | the wrapper's width in pixels; unset, the field fills its row |
| `testId` | `string` | — | the input's handle, for an automation host |

---

# Table selection

Source: https://gpuixui.sudokw.com/data-display/table-selection

A checkbox column for a data table

## Usage [#usage]

```tsx
import {
  Table,
  TableBody,
  TableHeader,
  TableRow,
  TableSelectionCell,
  TableSelectionHeader,
  TableViewport,
  useTable,
} from "@gpuixui/data";

const table = useTable({ rows: files, keyOf: (row) => row.id, columns });

<Table height={320} aria-label="Files">
  <TableViewport>
    <TableHeader>
      <TableRow>
        <TableSelectionHeader
          checked={table.allSelected}
          indeterminate={table.someSelected}
          onCheckedChange={table.setAllSelected}
          disabled={table.rows.length === 0}
        />
        <TableHeaderCell width={260}>Name</TableHeaderCell>
      </TableRow>
    </TableHeader>
    <TableBody>
      {table.rows.map((file) => (
        <TableRow key={file.id} selected={table.isSelected(file.id)}>
          <TableSelectionCell
            checked={table.isSelected(file.id)}
            onCheckedChange={() => table.toggleSelection(file.id)}
            label={`Select ${file.name}`}
          />
          <TableCell width={260}>{file.name}</TableCell>
        </TableRow>
      ))}
    </TableBody>
  </TableViewport>
</Table>;
```

## API [#api]

### `TableSelectionHeader` [#tableselectionheader]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `checked` | `boolean` | — | whether every visible record is chosen |
| `indeterminate` | `boolean` | `false` | paints a dash when only some visible records are chosen |
| `onCheckedChange` | `(selected: boolean) => void` | — | the box's next state: choose every visible record, or clear the set |
| `label` | `string` | `Select every row` | the box's accessible name |
| `width` | `number` | `40` | the track width; the body box must match it |
| `disabled` | `boolean` | `false` | refuses the press |
| `testId` | `string` | — | the box's id; the header cell is `${testId}-cell` and its target `${testId}-target` |

A blank `label` is the documented default `Select every row`, not an unnamed
box: a default only covers an absent prop, and an i18n row with a missing
translation answers `""` (`src/behaviour/surface-a11y.test.tsx`).

### `TableSelectionCell` [#tableselectioncell]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `checked` | `boolean` | — | whether this record is chosen |
| `onCheckedChange` | `(selected: boolean) => void` | — | the box's next state; a controlled table flips the record's membership |
| `label` | `string` | `Select this row` | the record's accessible name, e.g. `Select file-001.ts`; a blank name reads as the default |
| `width` | `number` | `40` | the track width; the header box must match it |
| `disabled` | `boolean` | `false` | refuses the press |
| `testId` | `string` | — | the box's id; the cell is `${testId}-cell` and its target `${testId}-target` |

A row box's name is content: a record restored without its title interpolates
`Select ` and a saved label answers `""`. A blank or whitespace name reads as
the documented `Select this row` rather than leaving the box unnamed — the same
rule the header box follows (`src/behaviour/surface-a11y.test.tsx`).

---

# Table sorting

Source: https://gpuixui.sudokw.com/data-display/table-sorting

The press cycle a sortable header reports

Using [TanStack Table](https://tanstack.com/table).

## Usage [#usage]

```tsx
import { TableHeader, TableRow, TableSortHeader, useTable } from "@gpuixui/data";

const table = useTable({ rows, keyOf: (row) => row.id, columns });

<TableHeader>
  <TableRow>
    <TableSortHeader
      field="status"
      label="Status"
      sort={table.sort}
      order={table.sortOrder}
      onSortPress={table.pressSort}
      width={110}
    />
    <TableSortHeader
      field="name"
      label="Name"
      sort={table.sort}
      order={table.sortOrder}
      onSortPress={table.pressSort}
      width={260}
    />
  </TableRow>
</TableHeader>;
```

## API [#api]

| Part | Prop | Type | Default | Consequence |
| ---- | ---- | ---- | ------- | ----------- |
| `TableSortHeader` | `field` | `string` | — | the column the press sorts by |
| `TableSortHeader` | `label` | `string` | — | the visible label, and the base of the announced name; a blank label reads as `field`, so a sortable column is never unnamed |
| `TableSortHeader` | `sort` | `Option<SortState>` | — | the primary sort, for the glyph and the single-sort callback |
| `TableSortHeader` | `order` | `SortOrder` | `sort` alone | the whole order; a multi-entry order adds each field's place to the glyph and the name |
| `TableSortHeader` | `onSortPress` | `(field, initialDirection, modifiers?) => void` | — | the raw press, for a controller that composes an order (`useTable().pressSort`) |
| `TableSortHeader` | `onSort` | `(next: SortState) => void` | — | the single-column alternative: the next entry the press cycle produces |
| `TableSortHeader` | `initialDirection` | `"asc" \| "desc"` | `"asc"` | the direction a first press starts at |
| `TableSortHeader` | `width` | `number` | — | a fixed track; a resizable column needs one |
| `TableSortHeader` | `align` | `"left" \| "center" \| "right"` | `"left"` | where the label sits across the track |
| `TableSortHeader` | `testId` | `string` | — | the header cell's test id; the press control is `${testId}-sort` |
| `TableSortHeader` | `resize` | `TableColumnResizeProps` | — | the divider's bounds and callback |
| `useTable` | `sort` | `Option<SortState>` | — | the primary sort |
| `useTable` | `sortOrder` | `SortOrder` | `[]` | every field in the order, primary first; an entry naming a column this grid does not hold is not counted |
| `useTable` | `pressSort` | `(field, initialDirection, modifiers?) => void` | — | the order a header press produces; Shift adds a tie-break |
| `useTable` | `toggleSort` | `(field, additive?) => void` | — | the same cycle without the runtime's modifiers |
| `useTable` | `setSort` | `(next: Option<SortState>) => void` | — | replace the order with one field, or clear it |
| `useTable` | `save` | `() => GridConfig` | — | the record to keep: the order the grid runs, the query and the core's chosen ids |

## A saved order is read [#a-saved-order-is-read]

A store-driven grid builds its table with `constructGrid`, so the state it
restores — a workspace's sorting, its query, its chosen ids — arrives as data
rather than as React state. JSON writes a field that was never set as `null`,
and a release that renames a column leaves the entry it named behind, so the
state is read before the core sees it: `readGridState(stored)` answers the three
slices as the shapes they mean, and `constructGrid` reads its own `state` the
same way.

- a sorting list that is not a list is **no sort** (the source order), and an
  entry that names no column is dropped;
- a query that is not text is **no query** — nothing typed narrowed the set;
- a chosen set keeps only the ids the store set to `true`.

A saved order can also name a **column this release dropped**: the row model
skips an entry it has no column to compare, and the order the grid reports —
`sortOrder`, and every header's "sort N of M" — drops the entry too, because a
sort that cannot run is not a sort. A column this grid still holds keeps its
entry whether or not it is hidden.

Measured before the read: `globalFilter: null` threw `Cannot read properties of
null (reading 'trim')` out of the first build, `sorting: null` threw
`state.sorting is not iterable`, and a `[null]` entry threw `Cannot read
properties of null (reading 'id')` — a grid that remembered its state could not
reopen at all. The same rule covers `hiddenColumns`: a stored list that is not a
list of text ids hides nothing.

```ts
import { constructGrid, readGridState } from "@gpuixui/data";

// `saved` is whatever the store handed back.
const table = constructGrid({
  rows,
  keyOf: (row) => row.id,
  columns,
  state: readGridState(saved),
  onSortingChange: setSorting,
  onGlobalFilterChange: setQuery,
  onRowSelectionChange: setChosen,
});
```

## Saving the state a grid holds [#saving-the-state-a-grid-holds]

`gridConfig(state)` writes the record `readGridState` reads, and
`useTable().save` composes it from the controller — the shape a workspace keeps
beside `columnConfig`'s:

```tsx
import { useTable } from "@gpuixui/data";

const table = useTable({ rows, keyOf: (row) => row.id, columns, stored });

// wherever the workspace persists its state
const saved = table.save();
// { sorting: [{ id, desc }], globalFilter, rowSelection: { [id]: true } }
```

The record is written from the order the grid **runs**, so an entry naming a
dropped column is not persisted back, and from the **core's** chosen ids rather
than the retained view: a filter that hides a chosen record keeps it in the
core, so a grid saved while narrowed restores that record when the query widens
again. The range anchor is a gesture cursor, not state — it starts fresh at the
next press after a restore. `save` returns its own arrays and record, so a store
can serialise the value without aliasing what the grid paints from.

`nub run --filter @gpuixui/data test:behaviour` measures the round trip in the
renderer: a grid sorted by name, a chosen record, and a query that hides it are
saved and reopened as they were left.

## The rows a store hands back [#the-rows-a-store-hands-back]

`rows` is stored data like the record beside it: a workspace restores a grid's
records from JSON, and an app passes `snapshot?.rows` while the snapshot is still
absent — `undefined` at runtime, though the prop type says a list is present.
`useTable` and `constructGrid` read the list through `listOf`, so a value that is
not a list is **no rows**: the grid paints `0 rows` and its own empty state,
where the core's `data` access used to throw
`Cannot read properties of null (reading 'length')` out of the first build. A
readable list is the caller's own, untouched
(`behaviour/stored-rows.test.tsx`).

---

# Tree views

Source: https://gpuixui.sudokw.com/data-display/tree-view

Expandable rows of a hierarchy, with arrow keys

## Usage [#usage]

```tsx
import { TreeView, useExpandedRows } from "@gpuixui/data";

const tree = useExpandedRows({
  roots: files,
  keyOf: (node) => node.name,
  childrenOf: (node) => node.children ?? [],
  labelOf: (node) => node.name,
  initialExpanded: ["src"],
});

<TreeView
  aria-label="Workspace files"
  height={260}
  rows={tree.rows}
  cursor={tree.cursor}
  onCursorChange={tree.setCursor}
  labelOf={(node) => node.name}
  onActivate={(row) => open(row.node)}
/>;
```

## API [#api]

### `useExpandedRows` [#useexpandedrows]

The controller holds the expansion set and the cursor. A saved workspace hands
its open folders back, so `initialExpanded` is **data**: only an iterable
carrying text keys opens anything (`expandedSet`), and a value a store wrote as
something else — an object where JSON has no `Set`, a number, `null` — is **no
expansion**, the state a fresh tree starts in, rather than a `TypeError` on the
first render. An entry that is not text is not a key.

The hierarchy is data as well, so `roots` and every node's `childrenOf` are read
as **lists**: JSON writes `null` for a list a record never carried, and a
hand-built node often omits it, so a leaf with `children: null` is the ordinary
shape of a saved tree. An absent `roots` paints no rows and an absent children
list is a leaf — `flattenTree`, `branchKeys` and `expandedPath` all read the slot
through `listOf`, so a stored hierarchy cannot take the render down
(`behaviour/tree.test.tsx`'s stored-children case).

### `TreeView` [#treeview]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `rows` | `TreeRow<T>[]` | — | the visible rows, in paint order; a value that is not a list paints an empty tree (see below) |
| `labelOf` | `(node: T) => string` | — | the row's accessible name and type-ahead match; a blank label reads as the row's key |
| `cursor` | `TreeCursor` | — | the caller's cursor; omit for an uncontrolled tree |
| `onCursorChange` | `(cursor: TreeCursor) => void` | — | reports every cursor |
| `defaultCursor` | `TreeCursor` | nothing open | the uncontrolled tree's start |
| `onActivate` | `(row: TreeRow<T>) => void` | — | a press or Enter on a row |
| `renderRow` | `(row: TreeRow<T>) => ReactNode` | `labelOf` as text | paints a row's content |
| `height` | `number` | — | a definite height; the rows scroll inside it |
| `className` | `string` | — | joined after the recipe |
| `testId` | `string` | — | the tree's locator |

A blank `labelOf` reads as the row's key **everywhere the row's words are
read**: the paint, the accessible name and the type-ahead match. A tree whose
names never arrived therefore still paints a word and a typed prefix reaches it
(`behaviour/tree.test.tsx`'s blank-label cases).

A row is built at the density's `rowHeight`, read through the primitives'
density seam (`rowHeightOf(theme)`): a theme a store restored without the
density group paints the library's row instead of throwing from the first row
(`tree/row.test.ts`), and `VirtualTree` resolves its own `rowHeight` through the
same seam.

The rows are stored data as often as a literal: a workspace that keeps its
flattened list hands the tree whatever the store gave back, and `snapshot?.rows`
is `undefined` until the snapshot arrives. `rows` is read through `listOf`, so a
value that is not a list paints the tree's frame and no rows — before the read,
the type-ahead's mapping threw `Cannot read properties of null (reading 'map')`
in the first render and nothing painted at all
(`behaviour/stored-rows.test.tsx`).

---

# Virtual trees

Source: https://gpuixui.sudokw.com/data-display/virtual-tree

A hierarchy painted one window at a time

## Usage [#usage]

```tsx
import { VirtualTree, useExpandedRows } from "@gpuixui/data";

const tree = useExpandedRows({ roots: files, keyOf, childrenOf, labelOf });

<VirtualTree
  aria-label="Workspace files"
  height={320}
  rows={tree.rows}
  cursor={tree.cursor}
  onCursorChange={tree.setCursor}
  labelOf={labelOf}
  onActivate={(row) => open(row.node)}
/>;
```

## API [#api]

### `VirtualTree` [#virtualtree]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `rows` | `TreeRow<T>[]` | — | the **whole** flattened set, in paint order |
| `labelOf` | `(node: T) => string` | — | the row's accessible name and what type-ahead matches; a blank label reads as the row's key |
| `cursor` | `TreeCursor` | — | the caller's cursor; omit it for an uncontrolled tree |
| `onCursorChange` | `(cursor: TreeCursor) => void` | — | reports every cursor a key, a press or a window move produces |
| `defaultCursor` | `TreeCursor` | nothing open | the uncontrolled tree's start |
| `onActivate` | `(row: TreeRow<T>) => void` | — | a press or Enter on a row |
| `renderRow` | `(row: TreeRow<T>) => ReactNode` | `labelOf` as text | paints a row's content after its inset and chevron |
| `height` | `number` | the bounded column's height | the viewport height; a height the layout cannot paint is **no height**, so the tree fills the column and windows against the height it measured |
| `rowHeight` | `number` | the density's `rowHeight`, or the library's row when the theme carries no density group | every row paints exactly this height |
| `overdraw` | `number` | `4` | rows mounted beyond the viewport on each side |
| `onVisibleRange` | `(range: VisibleRange) => void` | — | the runtime's lagging report, for a readout or pagination |
| `instanceRef` | `(instance: PublicInstance \| null) => void` | — | the list's painted element, for a probe that reads its scroll anchor |
| `className` | `string` | — | joined after the recipe |
| `testId` | `string` | — | the tree; each row is `${testId}-row-${key}` and its chevron slot `${testId}-row-${key}-slot` |

---

# Virtualization

Source: https://gpuixui.sudokw.com/data-display/virtualization

A long list and table that mount one window of rows

Using [TanStack Virtual](https://tanstack.com/virtual).

## Usage [#usage]

```tsx
import { VirtualList } from "@gpuixui/data";

<VirtualList height={320} aria-label="Files">
  {rows.map((row) => (
    <div key={row.id} style={{ height: 32 }}>
      <text>{row.label}</text>
    </div>
  ))}
</VirtualList>;
```

## API [#api]

### `VirtualList` [#virtuallist]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `height` | `number` | caller's layout | a definite viewport height |
| `children` | `ReactNode` | — | the rows |
| `followTail` | `boolean` | `false` | keeps the list at its trailing edge as rows arrive |
| `alignment` | `"top" \| "bottom"` | `top` | where the content sits when it does not fill the viewport |
| `itemCount` | `number` | children mode | switches to the windowed mode |
| `estimatedItemHeight` | `number` | — | required with `itemCount`; a height the runtime cannot lay out is read as the shipped row's own (`37`) |
| `windowStart` | `number` | `0` | the first rendered slice's index |
| `onVisibleRange` | `(range: VisibleRange) => void` | — | the built window |
| `overdraw` | `number` | — | rows built beyond the viewport; a count the runtime cannot read is the default (`4`), a negative is `0` |
| `className` | `string` | — | joined after the list's own (empty) recipe |
| `ref` | `Ref<PublicInstance>` | — | the list's instance, for `scrollToItem` |

### `VirtualTable` [#virtualtable]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `count` | `number` | — | the logical row count; a fraction, a negative or an unreadable count is the whole, non-negative rows the table holds (`0` paints `empty`) |
| `height` | `number` | measured viewport | a definite table height; one the layout cannot paint is no height, so the table fills its column |
| `rowHeight` | `number` | — | every row must paint exactly this height; a height the window cannot divide is read as the shipped row's own (`37`) |
| `header` | `ReactNode` | — | the header row's cells |
| `row` | `(index: number) => ReactNode` | — | paints one absolute row index |
| `empty` | `ReactNode` | `No rows` | painted inside a `TableEmpty` row when `count` is `0`; a string paints as its own text element |
| `caption` | `ReactNode` | — | the line below the frame; a string paints as its own text element |
| `overdraw` | `number` | `4` | rows mounted beyond the viewport on each side; a count the window cannot read is `4`, a negative is `0` |
| `reveal` | `VirtualReveal` | — | `{ index }`; the window moves, then the body scrolls |
| `onVisibleRange` | `(range: VisibleRange) => void` | — | the runtime's lagging report |
| `className` | `string` | — | joined after the recipe |

### `VirtualTableBody` [#virtualtablebody]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `count` | `number` | — | the logical row count; read the same way `VirtualTable` reads it |
| `rowHeight` | `number` | — | the painted height of one row; a height the window cannot divide is `37` |
| `renderRow` | `(index: number) => ReactNode` | — | paints one absolute row index |
| `height` | `number` | the measured body | a definite body height; omit it inside a bounded `Table` |
| `overdraw` | `number` | `4` | rows mounted beyond the viewport on each side |
| `reveal` | `VirtualReveal` | — | `{ index }`; the window moves, then the body scrolls |
| `onVisibleRange` | `(range: VisibleRange) => void` | — | the runtime's lagging report |
| `instanceRef` | `Ref<PublicInstance>` | — | the list's instance, for a consumer that scrolls it itself |
| `testId` | `string` | — | the body's locator |

## The height a window needs [#the-height-a-window-needs]

A windowed surface computes its range from a viewport height and has no natural
height of its own: a content-sized box would report a height, mount more rows
and grow again. Give it a definite `height` when you can.

A height the layout cannot paint — `NaN`, an infinity, a negative, the value a
computed pane measure has before the first layout — reads as **no height**, so
the surface takes the share of its pane that the layout hands out and windows
against the height that box painted:

```tsx
<div style={{ display: "flex", flexDirection: "column", height: 320 }}>
  <VirtualTree aria-label="Files" rows={tree.rows} labelOf={labelOf} />
</div>
```

- `VirtualTable` fills its container and windows against the measured viewport
  frame, exactly as it does with a height;
- `VirtualTree` measures the column it fills and draws the list at that height.
  The runtime's `<virtual-list>` paints no surface of its own, so it reports no
  `onLayout` (measured on 0.11.0) — the list cannot measure itself.

The pane must bound the column's height. A surface with no viewport at all — an
auto-height or non-flex parent — has nothing to fill and paints no rows, which
is the same state as a window with no bound.

In a 320px pane both paint the window they paint at `height={320}`: 8 table rows
and 10 tree rows in `behaviour/paintable-height.test.tsx`.

## Paging versus windowing [#paging-versus-windowing]

The two bound paint differently, and a grid usually wants one of them:

- a **window** mounts the rows near the viewport and follows the scroll — the
  reader can reach any row, and the set is never sliced;
- a **page** slices the filtered and sorted set at a page size and paints one
  slice — the reader moves the slice, and every row on it is mounted.

Paging is `useTable`'s, and it runs on the same `@tanstack/table-core`
pagination row model the sort and the filter do, so the page is a slice of what
the core kept instead of a second filter:

| Member | Type | Default | Consequence |
| ------ | ---- | ------- | ----------- |
| `pageSize` (option) | `number` | `ALL_ROWS` | how many rows one page paints, read at mount (`setPageSize` after it); a value the grid cannot lay out is every row |
| `pageIndex` | `number` | `0` | the page the grid paints, **clamped** to the pages the kept set holds |
| `pageCount` | `number` | — | how many pages the kept set holds; never zero, so an empty grid is one page |
| `pageSize` | `number` | `ALL_ROWS` | the size the grid runs |
| `setPageIndex` | `(pageIndex: number) => void` | — | move to a page, clamped |
| `setPageSize` | `(pageSize: number) => void` | — | change the size, keeping the reader's top row in view |
| `nextPage` / `previousPage` | `() => void` | — | move one page, clamped at the ends |
| `rows` / `keys` | the page | — | the painted slice, and the order a Shift range spans |
| `kept` | `ReadonlyArray<Row>` | — | the rows the tree and the query keep, before sorting or a page |
| `selectedCount` | `number` | — | chosen records in the **kept set**, not on the page |
| `allSelected` / `someSelected` | `boolean` | — | the header box's state over the **painted page** |

Four rules are measured, not assumed:

- **a filter, a search or a new sort returns to the first page** — the records
  the reader was reading are not where the index says they are once the set
  changes (`setQuery`, `pressSort`, `toggleSort` and `setSort` all reset it);
  a new **predicate tree** does the same, and it arrives as a controlled prop
  rather than a gesture, so the index is stamped with the tree it was measured
  against and a replacement paints page one in the same commit;
- **a page index past the set clamps to its last page** — a saved workspace
  reopens with the page it was on, and a set that has since narrowed paints its
  last page instead of a blank one past the end — **and the arrows and a page
  size change measure from the page it paints**, so a saved index past the set
  cannot strand Previous on the page already shown or carry a new size past the
  reader's top row;
- **a page size change keeps the reader's top row in view**, so doubling the
  size shows the same records from the same first row;
- **the selection is the kept set's, not the page's** — a record chosen on page
  one is still chosen (and still saved) while page two paints, while the
  header's box covers only what it paints.

The page is part of the record a grid saves: `save()` writes `pagination`, and
`readGridState(stored)` reads it back, so a workspace reopens on the page the
reader left. `pageSize` of every row is `Infinity`, which JSON writes as `null`
and the reader takes as every row again. A store-driven grid builds the core
itself and passes `onPaginationChange`; `ALL_ROWS`, `DEFAULT_PAGINATION`,
`pageIndexOf`, `pageSizeOf`, `pageCountOf`, `clampPageIndex`, `withPageSize` and
`readPagination` are exported for the arithmetic it needs.

```tsx
const table = useTable({ rows, keyOf: (row) => row.id, columns, pageSize: 20 });

<Button
  disabled={table.pageIndex >= table.pageCount - 1}
  onActivate={table.nextPage}
>
  Next
</Button>;
// `Page ${table.pageIndex + 1} of ${table.pageCount}` · `${table.rows.length} rows`
```

`pagination/logic.test.ts` holds the arithmetic, `behaviour/table-pagination`
the page the shipped controller paints, and `behaviour/pagination-example` the
screen in `examples/table-pagination.example.tsx`. A grid that must never slice
its set uses the windowed surfaces above instead.

---

# Panel surfaces

Source: https://gpuixui.sudokw.com/dock

Split panes, panel groups and a dock layout for a workspace.

- [Docking layouts](https://gpuixui.sudokw.com/dock/dock-layout): A named tree of split and tab groups, rendered from a schema
- [Panel groups](https://gpuixui.sudokw.com/dock/panel-group): N panes in a row or column, each resizable
- [Split pane](https://gpuixui.sudokw.com/dock/split-pane): Two panes and the divider between them

---

# Docking layouts

Source: https://gpuixui.sudokw.com/dock/dock-layout

A named tree of split and tab groups, rendered from a schema

<ComponentPreview name="dock-layout-demo" />

## Usage [#usage]

```tsx
import { DockLayout, DockTab, type DockNode } from "@gpuixui/dock";
import { useState } from "react";

const initial: DockNode = {
  kind: "split",
  id: "root",
  orientation: "horizontal",
  size: 0.6,
  first: {
    kind: "tabs",
    id: "editor",
    activeTab: "code",
    tabs: [new DockTab({ id: "code", label: "Code" })],
  },
  second: {
    kind: "tabs",
    id: "preview",
    activeTab: "outline",
    tabs: [new DockTab({ id: "outline", label: "Outline" })],
  },
};

const [layout, setLayout] = useState(initial);

<DockLayout
  layout={layout}
  onLayoutChange={setLayout}
  renderTab={(id) => <Pane id={id} />}
/>;
```

## API [#api]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `layout` | `DockNode` | — | the tree; controlled |
| `onLayoutChange` | `(layout: DockNode) => void` | — | the next tree |
| `renderTab` | `(id: string) => ReactNode` | — | one tab's content |
| `className` | `string` | — | joined after the recipe |

---

# Panel groups

Source: https://gpuixui.sudokw.com/dock/panel-group

N panes in a row or column, each resizable

<ComponentPreview name="panel-group-demo" />

## Usage [#usage]

```tsx
import { PanelGroup, PanelLayout, Panel } from "@gpuixui/dock";
import { useState } from "react";

const initial = new PanelLayout({
  orientation: "horizontal",
  panels: [
    new Panel({ id: "sidebar", label: "Sidebar", size: 0.2, collapsible: true }),
    new Panel({ id: "editor", label: "Editor", size: 0.8 }),
  ],
});

const [layout, setLayout] = useState(initial);

<PanelGroup
  layout={layout}
  onLayoutChange={setLayout}
  renderPanel={(id) => <Pane id={id} />}
/>;
```

## API [#api]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `layout` | `PanelLayout` | — | the persisted shape; controlled |
| `onLayoutChange` | `(layout: PanelLayout) => void` | — | the next shape after a resize or a collapse |
| `renderPanel` | `(id: string) => ReactNode` | — | one pane's content |
| `dividerLabel` | `(index: number) => string \| undefined` | `Resize <left panel>` | one gap's accessible name |
| `className` | `string` | — | joined after the recipe |

## Resizable [#resizable]

The same group answers to shadcn's names. `ResizablePanelGroup` declares its
panes and handles, builds the `PanelLayout` they describe, and renders
`PanelGroup` — one divider, one keyboard step, one persisted shape.

```tsx
import {
  ResizableHandle,
  ResizablePanel,
  ResizablePanelGroup,
} from "@gpuixui/dock";

<ResizablePanelGroup direction="horizontal" defaultLayout={saved}>
  <ResizablePanel defaultSize={20} id="sidebar" label="Sidebar" collapsible>
    <Explorer />
  </ResizablePanel>
  <ResizableHandle label="Resize the explorer" />
  <ResizablePanel defaultSize={80} id="editor" label="Editor">
    <Editor />
  </ResizablePanel>
</ResizablePanelGroup>;
```

| Part | Props | Consequence |
| ---- | ----- | ----------- |
| `ResizablePanelGroup` | `direction`, `layout`, `defaultLayout`, `onLayoutChange`, `className`, `testId`, `children` | the axis and the shape; a controlled `layout` wins, and an omitted one is held by the group |
| `ResizablePanel` | `id`, `defaultSize`, `label`, `collapsible`, `children` | one pane; `defaultSize` is a share, and `label` defaults to `id` |
| `ResizableHandle` | `label` | one gap's accessible name; the divider itself is the group's |

`defaultSize` is a **fraction**, not a percentage that must sum to 100: `20` and
`80` mean the same shares as `0.2` and `0.8`, and `normalizePanels` rescales a
set that does not add up. The parts are declarations — they paint nothing — so
the group keeps the single tab stop a divider needs.

---

# Split pane

Source: https://gpuixui.sudokw.com/dock/split-pane

Two panes and the divider between them

<ComponentPreview name="panel-preview" />

## Usage [#usage]

```tsx
import { SplitPane } from "@gpuixui/dock";
import { useState } from "react";

const [size, setSize] = useState(240);

<SplitPane
  size={size}
  onResize={setSize}
  min={160}
  max={400}
  dividerLabel="Sidebar width"
  first={<Sidebar />}
  second={<Document />}
/>;
```

## API [#api]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `size` | `number` | — | the first pane's size in pixels; controlled |
| `onResize` | `(size: number) => void` | — | the first pane's settled size |
| `min` | `number` | `0` | the first pane's floor |
| `max` | `number` | unbounded | the first pane's ceiling |
| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | left/right vs stacked |
| `first` / `second` | `ReactNode` | — | the two panes |
| `dividerLabel` | `string` | — | the divider's accessible name |
| `disabled` | `boolean` | `false` | refuses the drag and the keys |

---

# Code surfaces

Source: https://gpuixui.sudokw.com/editor

A code editor, a diff, a Markdown editor and search-and-replace.

- [Code editor](https://gpuixui.sudokw.com/editor/code-editor): An editable code surface with tokenized highlighting
- [Diff viewer](https://gpuixui.sudokw.com/editor/diff-viewer): Two sources compared, tinted by change
- [MarkdownEditor](https://gpuixui.sudokw.com/editor/markdown-editor): Markdown editing with the rendered result beside it
- [Search and replace](https://gpuixui.sudokw.com/editor/search-replace): Find, match count, next/previous and replace-all

---

# Code editor

Source: https://gpuixui.sudokw.com/editor/code-editor

An editable code surface with tokenized highlighting

<ComponentPreview name="code-editor-demo" />

## Usage [#usage]

```tsx
import { CodeEditor } from "@gpuixui/editor";

<CodeEditor
  value={value}
  onValueChange={setValue}
  language="tsx"
  lineNumbers
/>;
```

## API [#api]

| Prop | Type | Default | Notes |
| ---- | ---- | ------- | ----- |
| `value` | `string` | — | The controlled text. A stored value that is not text reads as an empty document. |
| `defaultValue` | `string` | `""` | The uncontrolled starting text. A stored value that is not text reads as an empty document. |
| `onValueChange` | `(value: string) => void` | — | Every edit, including Tab and Enter. |
| `language` | `string` | — | The tokenizer's language id. An unknown id, or one that is not text, paints plain text. |
| `lineNumbers` | `boolean` | `true` | Number the rows in a gutter. |
| `tabMode` | `"insert" \| "focus"` | `"insert"` | What Tab does. A stored name that is neither reads as the default `"insert"`. |
| `indent` | `string` | `"  "` | The string Tab inserts. An empty string leaves Tab as the platform traversal, and a value that is not a string reads as the default. |
| `placeholder` | `string` | — | The editor's hint, painted in the theme's `placeholder` role and announced as the field's description; the host is handed none. |
| `readOnly` | `boolean` | `false` | View-only. |
| `disabled` | `boolean` | `false` | Not editable, out of the tab order, painted with the disabled chrome. |
| `minRows` | `number` | — | The least number of rows the editor paints. The highlight layer is what sizes the editor, so the floor is painted as empty rows. |
| `maxRows` | `number` | — | Passed to the field. The layer cannot follow a scroll (the runtime reports no offset), so it paints every line and the surface grows with the document. |
| `fullWidth` | `boolean` | `false` | Fill the available width. |
| `label` | `string` | `"Code editor"` | The accessible name. A blank or non-text name reads as the default. |
| `className` | `string` | — | A Tailwind class string, merged last. |
| `style` | `StateStyle<CodeEditorState>` | — | The surface, or a function of `{ disabled, focused }`. |
| `testId` | `string` | `"code-editor"` | The address an automation host locates the field by; the surface around it is `${testId}-surface`. |

---

# Diff viewer

Source: https://gpuixui.sudokw.com/editor/diff-viewer

Two sources compared, tinted by change

<ComponentPreview name="diff-viewer-demo" />

## Usage [#usage]

```tsx
import { DiffViewer } from "@gpuixui/editor";

<DiffViewer before={before} after={after} mode="unified" />;
```

## API [#api]

| Prop | Type | Default | Notes |
| ---- | ---- | ------- | ----- |
| `before` | `string` | — | The before source. |
| `after` | `string` | — | The after source. |
| `mode` | `"unified" \| "split"` | `"unified"` | One merged column, or two. A stored name that is neither reads as the default. |
| `contextLines` | `number` | `3` | Unchanged rows kept either side of a change before the diff skips to a hunk heading. A negative or non-numeric value reads as the default. |
| `lineNumbers` | `boolean` | `true` | Number the rows on both sides. |
| `wordDiff` | `boolean` | `true` | In split mode, mark the words that changed inside a paired line. |
| `ink` | `"tone" \| "code"` | `"tone"` | `code` keeps the text neutral and shows the change with the tint and a bar. |
| `annotations` | `ReadonlyArray<{ line, height, content }>` | `[]` | A review note under an after-side line; the before side keeps a spacer, so rows stay level. |
| `wrapColumns` | `number` | — | In split mode, wrap at this many characters and grow both cells of the row together. |
| `language` | `string` | — | With `ink="code"`, colour the code by syntax, and break wrapped lines after a space or punctuation. |
| `firstLine` | `{ before?, after? }` | `1` | The line number each side's numbering starts from, for an excerpt of a longer file. |
| `label` | `string` | `"Diff"` | The accessible name; a blank or non-text name reads as the default (the rows are presentational, so this is the whole surface's name). |
| `className` | `string` | — | A Tailwind class string, merged last. |
| `style` | `StateStyle<DiffViewerState>` | — | The surface, or a function of `{ changed }`. |
| `testId` | `string` | `"diff-viewer"` | The address an automation host locates the diff by. A unified line appends `-row-<index>`; a split line appends `-row-<index>-before` and `-row-<index>-after`; a hunk heading appends `-hunk-<index>`. |

## The row model [#the-row-model]

The viewer paints data, not decisions. `diff/logic` exports the whole script:

- `hunks(numbered, context)` groups the numbered script into hunks, keeps `context`
  unchanged rows either side of a change, and names the lines a skip dropped
  (`@@ -beforeStart,count +afterStart,count @@`). Two changes within `2·context`
  rows share a hunk, so their context windows abut and no change is shown twice.
- `rows(numbered, context)` is the unified sequence: a hunk heading, then each
  changed pair with the removal and the addition it became **adjacent**, then
  every context row once.
- `pairs(numbered, context)` is the split sequence: the same hunks zipped across the
  divider, with a blank cell on the side that ran out. A heading pairs with
  nothing on the right, so a split viewer paints it once across both columns.

## Split mode [#split-mode]

`mode="split"` puts a changed line and its replacement on **one** row: the two
equal columns share a row height, so a pair sits level across the divider. Each
column carries its own line-number gutter and its own horizontal scroller; a
long line scrolls inside the column it belongs to instead of pushing or clipping
its neighbour. A one-line edit is therefore one row with the old line on the
left and the new one on the right, not a removal and an addition stacked apart.

---

# MarkdownEditor

Source: https://gpuixui.sudokw.com/editor/markdown-editor

Markdown editing with the rendered result beside it

<ComponentPreview name="markdown-editor-demo" />

## Usage [#usage]

```tsx
import { MarkdownEditor } from "@gpuixui/editor";

<MarkdownEditor
  value={value}
  onValueChange={setValue}
  label="Release notes"
  width={640}
  height={300}
/>;
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `value` | `string` | — (uncontrolled) |
| `defaultValue` | `string` | `""` |
| `onValueChange` | `(value: string) => void` | — |
| `mode` | `"split" \| "source" \| "preview"` | — (uncontrolled) |
| `defaultMode` | `"split" \| "source" \| "preview"` | `"split"` |
| `onModeChange` | `(mode) => void` | — |
| `label` | `string` | `"Markdown editor"` |
| `placeholder` | `string` | — |
| `width` | `number` | `640` |
| `height` | `number` | `280` |
| `splitSize` | `number` | — (uncontrolled) |
| `defaultSplitSize` | `number` | half the body |
| `onSplitSizeChange` | `(size: number) => void` | — |
| `readOnly` | `boolean` | `false` |
| `disabled` | `boolean` | `false` |
| `className` | `string` | — |
| `style` | `StyleDesc` | — |
| `testId` | `string` | — |

## Names [#names]

`label` names the editor and every part of it: the source field is `"<label> source"`, the preview `"<label> preview"` and the split's divider `"<label> split"`. A label that arrives blank — from an i18n table or a saved record — is an absence, so each part falls back to `Markdown editor` rather than publishing `" source"`; a label that is not text at all (a number a record kept) is no name either, so the parts keep the same default instead of the render throwing out of the name seam.

## Views [#views]

The three view buttons are a choice, not three separate actions: the painted
view is the one with `secondary` paint, and it also carries **`aria-selected`** —
0.11.0 has no `aria-current`, and `aria-selected` is the substitution the
Pagination, Stepper and Timeline controls publish for the same job. Every button
states its own value, so the colour of the paint is not the only channel that
says which view is showing; a reader on a screen reader gets the same fact from
the control it is on.

---

# Search and replace

Source: https://gpuixui.sudokw.com/editor/search-replace

Find, match count, next/previous and replace-all

<ComponentPreview name="search-replace-demo" />

## Usage [#usage]

```tsx
import { SearchReplace } from "@gpuixui/editor";

<SearchReplace value={value} onValueChange={setValue} />;
```

## API [#api]

| Prop | Type | Default | Notes |
| ---- | ---- | ------- | ----- |
| `value` | `string` | — | The controlled document text. |
| `onValueChange` | `(value: string) => void` | — | Reports a single replace and a replace-all. |
| `placeholder` | `string` | `"Find"` | The find field's hint. |
| `replacePlaceholder` | `string` | `"Replace with"` | The replacement field's hint. |
| `findLabel` | `string` | `"Find"` | The find field's accessible name; a blank or non-text name reads as the default. |
| `replaceFieldLabel` | `string` | `"Replace with"` | The replacement field's accessible name; a blank or non-text name reads as the default. |
| `replaceLabel` / `replaceAllLabel` | `string` | `"Replace"` / `"Replace all"` | The actions' names; a blank one reads as its default. |
| `nextLabel` / `previousLabel` | `string` | `"Next match"` / `"Previous match"` | The navigation names; a blank one reads as its default. |
| `disabled` | `boolean` | `false` | Refuse every route, `F3` included: a read-only host still receives keys. |
| `className` | `string` | — | A Tailwind class string, merged last. |
| `testId` | `string` | `"search-replace"` | The address an automation host locates the bar by; its parts append their own suffix. |

## Matching [#matching]

The scan is literal: a regex character in the query matches itself, and there is
no pattern mode. Two toggles narrow it:

- **`Aa` — match case** (on by default). Off, the query runs as the escaped
  literal in a case-insensitive pattern rather than a lowered copy of the text:
  lowering can change a string's length, and therefore its offsets.
- **`W` — match whole word** (off by default). A match must not touch a letter,
  digit or underscore on either side.

Both options feed the count, the single replace and replace-all, so the `n / m`
readout is the number of replacements a replace-all would make. Matches never
overlap — a candidate that starts inside the match before it is skipped — and
the word rule is applied first, so a whole-word match that begins inside an
occurrence the rule rejects is still found.

A **changed query, or a flipped option, starts at its first match**: the active
index numbers one range set, so it cannot name a match in the next one. A
document edit is different — after a single replace the bar stays on the match
that moved into the active slot, which is the one the reader is working through.

---

# File surfaces

Source: https://gpuixui.sudokw.com/files

A file tree, a log viewer and an inspector panel.

- [File trees](https://gpuixui.sudokw.com/files/file-tree): A file tree with declarative folders and one selection
- [Log viewers](https://gpuixui.sudokw.com/files/log-viewer): A tail-anchored log list with a level filter
- [Property panels](https://gpuixui.sudokw.com/files/property-panel): A key/value editor for text, number, boolean and select

---

# File trees

Source: https://gpuixui.sudokw.com/files/file-tree

A file tree with declarative folders and one selection

## Usage [#usage]

```tsx
import {
  FileTree,
  FileTreeFile,
  FileTreeFolder,
} from "@gpuixui/files";

const [file, setFile] = useState("src/index.ts");

<FileTree
  aria-label="Project files"
  defaultExpanded={["src"]}
  height={280}
  selected={file}
  onSelect={setFile}
>
  <FileTreeFolder path="src" name="src">
    <FileTreeFolder path="src/components" name="components">
      <FileTreeFile path="src/components/button.tsx" name="button.tsx" />
    </FileTreeFolder>
    <FileTreeFile path="src/index.ts" name="index.ts" />
  </FileTreeFolder>
  <FileTreeFile path="readme.md" name="readme.md" />
</FileTree>;
```

A folder press toggles **only that folder's** subtree. A file press selects it
and calls `onSelect` once. The tree holds one tab stop — the selected file while
it paints, else the first row — and the arrow keys walk the visible rows, with
Right opening and Left closing a folder.

The selected file wears the **accent** wash with the accent's foreground, as
the reference's `bg-accent text-accent-foreground` does: a row is one of many,
so a brand fill would read as a pressed primary button.

`FileTreeFolder` and `FileTreeFile` declare the tree; `FileTree` reads their
props into the same `FileNode` model `buildFileTree` produces and paints one
flat row list. The declarations are not rendered recursively, which is what
lets the generic tree keep its single tab stop and its visible-row order.

## API [#api]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `expanded` | `Iterable<string>` | — | the open folder paths, when the caller holds them |
| `defaultExpanded` | `Iterable<string>` | none | the open paths at first paint; a saved JSON list works |
| `selected` | `string \| null` | none | the selected file path; a non-text stored value paints no selection |
| `onSelect` | `(path: string) => void` | — | a file press or Enter, called once per activation |
| `onExpandedChange` | `(expanded: string[]) => void` | — | the open paths after every change, sorted |
| `height` | `number` | — | a definite height; the rows scroll inside it |
| `className` | `string` | — | merged after the frame's own recipe |
| `testId` | `string` | — | the tree; each row is `${testId}-row-${path}` |

## Parts [#parts]

### `FileTreeFolder` [#filetreefolder]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `path` | `string` | — | the folder's stable path and expansion key |
| `name` | `string` | — | the row's visible and accessible name |
| `children` | `ReactNode` | — | the folder's entries, in paint order |

### `FileTreeFile` [#filetreefile]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `path` | `string` | — | the file's stable path and what `onSelect` reports |
| `name` | `string` | — | the row's visible and accessible name |
| `icon` | `IconName` | the kind's glyph | an icon that overrides the file's kind |
| `children` | `ReactNode` | the default row | a custom row after the guides and chevron slot |

A custom row is how a file carries actions or an inline editor: the caller
supplies its own `FileTreeIcon`, `FileTreeName` and controls, exactly as the
reference's `FileTreeActions` sits beside its button.

### `FileTreeIcon` and `FileTreeName` [#filetreeicon-and-filetreename]

The two row slots the default row composes. `FileTreeIcon` takes `name`
(`IconName`), `selected` and a `children` fallback; `FileTreeName` takes
`selected` and the name. Both paint in the selected row's ink when `selected` is
set, so a custom row can match the tree.

## Reference anatomy [#reference-anatomy]

| shadcn AI Elements | GPUixUI |
| ------------------ | ------- |
| `FileTree` (`role="tree"`, frame, `expanded` / `defaultExpanded` / `selectedPath` / `onSelect`) | `FileTree` (`role="tree"`, frame, `expanded` / `defaultExpanded` / `selected` / `onSelect`) |
| `FileTreeFolder` (Collapsible, trigger, `FileTreeIcon`, `FileTreeName`, nested lane) | `FileTreeFolder` (one row, chevron glyph, folder glyph, name, inset by depth) |
| `FileTreeFile` (Button, spacer, icon, name) | `FileTreeFile` (one row, blank chevron slot, file glyph, name) |
| `FileTreeIcon` (shrink-0 span) | `FileTreeIcon` (icon-sized slot) |
| `FileTreeName` (truncate span) | `FileTreeName` (one ellipsized line) |
| `FileTreeActions` (right-aligned, stops the row press) | omitted: a `FileTreeFile` custom row is the action slot |

A row is the theme's `label` type role — the reference's `text-sm` in the sans
family — and every row is the density's `rowHeight`, rounded one step under the
radius. The tree paints **no frame of its own**: no border, no background, no
guide rails, so the surface it sits on (a card, a sidebar, a sheet) is the only
one. One folder glyph and one file glyph cover every row; the chevron says
whether a folder is open, and the kind a name classifies into is a fact an app
can ask for without the paint following it.

---

# Log viewers

Source: https://gpuixui.sudokw.com/files/log-viewer

A tail-anchored log list with a level filter

## Usage [#usage]

```tsx
import { LogViewer } from "@gpuixui/files";

<LogViewer
  height={240}
  lines={lines}
  enabledLevels={levels}
  onEnabledLevelsChange={setLevels}
  followTail={follow}
  onFollowTailChange={setFollow}
/>;
```

## API [#api]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `lines` | `string[]` | — | the raw log lines, one per row |
| `height` | `number` | — | a definite viewport height |
| `rowHeight` | `number` | the density's `rowHeight` | the painted height of one row |
| `enabledLevels` | `LogLevel[]` | every level | the enabled levels; omit to let the viewer hold its own |
| `onEnabledLevelsChange` | `(levels: LogLevel[]) => void` | — | reports the enabled levels after every change |
| `followTail` | `boolean` | `true` | follow appends; omit to let the viewer hold its own |
| `onFollowTailChange` | `(follow: boolean) => void` | — | reports the follow state after every change |
| `testId` | `string` | — | the list's test id |

---

# Property panels

Source: https://gpuixui.sudokw.com/files/property-panel

A key/value editor for text, number, boolean and select

## Usage [#usage]

```tsx
import { PropertyPanel, type PropertyRow } from "@gpuixui/files";

const rows: ReadonlyArray<PropertyRow> = [
  { type: "text", key: "name", label: "Name", value: name },
  { type: "number", key: "count", label: "Count", value: count },
  { type: "boolean", key: "active", label: "Active", value: active },
  { type: "select", key: "kind", label: "Kind", value: kind, options: KINDS },
];

<PropertyPanel title="Shape" rows={rows} onChange={(record) => apply(record)} />;
```

A number row's label is its scrub handle: drag it horizontally to step the
value (Shift is ten steps) and a click still selects the field for typing. A
row's optional `min`/`max`/`step` bound the drag and the field.

## API [#api]

| Prop | Type | Default | Consequence |
| ---- | ---- | ------- | ----------- |
| `rows` | `PropertyRow[]` | — | the rows, in paint order |
| `onChange` | `(record: PropertyRecord) => void` | — | receives the whole record after every edit |
| `title` | `string` | — | the panel's header title |
| `labelWidth` | `number` | `120` | the label column's width, in pixels |
| `testId` | `string` | — | the panel; each label is `${testId}-label-${key}` |

---

# Media surfaces

Source: https://gpuixui.sudokw.com/media

Image preview, upload, crop and QR surfaces for a file workflow.

- [CropArea](https://gpuixui.sudokw.com/media/crop-area): A picture with a controlled crop hole and drag handles
- [DropZone](https://gpuixui.sudokw.com/media/drop-zone): A drop target that reports files and offers a picker
- [FileUpload](https://gpuixui.sudokw.com/media/file-upload): A queue of files with progress, retry and remove
- [ImagePreview](https://gpuixui.sudokw.com/media/image-preview): An image surface with loading, error and pointer zoom
- [MediaPlayer](https://gpuixui.sudokw.com/media/media-player): A clip's poster and Mux's transport, on the app's clock
- [QrCode](https://gpuixui.sudokw.com/media/qr-code): A QR symbol from the package's own encoder

---

# CropArea

Source: https://gpuixui.sudokw.com/media/crop-area

A picture with a controlled crop hole and drag handles

<ComponentPreview name="crop-area-demo" />

## Usage [#usage]

```tsx
import { useState } from "react";
import { CropArea, CropRect } from "@gpuixui/media";

const [crop, setCrop] = useState(
  new CropRect({ x: 60, y: 40, width: 100, height: 100 }),
);

<CropArea
  src={picture}
  alt="The picture being cropped"
  width={240}
  height={160}
  value={crop}
  onChange={setCrop}
  aspectRatio={1}
  guides
  label="Crop the thumbnail"
/>;
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `src` | `string` | required (blank paints no picture; a non-text value paints none too) |
| `alt` | `string` | required (a blank or non-text value reads as `"Picture"`) |
| `width` | `number` | required |
| `height` | `number` | required |
| `value` | `CropRect` | required (an absent value reads as the origin at the smallest side) |
| `onChange` | `(crop: CropRect) => void` | required |
| `minSize` | `number` | `24` |
| `handleSize` | `number` | `10` |
| `aspectRatio` | `number` (width / height) | — (free) |
| `guides` | `boolean` | `false` |
| `label` | `string` | `"Crop area"` (a blank name reads as the default) |
| `disabled` | `boolean` | `false` |
| `className` | `string` | — |
| `style` | `StyleDesc` | — |

---

# DropZone

Source: https://gpuixui.sudokw.com/media/drop-zone

A drop target that reports files and offers a picker

<ComponentPreview name="drop-zone-demo" />

## Usage [#usage]

```tsx
import { DropZone } from "@gpuixui/media";

<DropZone
  label="Drop files here"
  description="or pick them from the platform"
  onDrop={({ files }) => addFiles(files.map((file) => file.path))}
  onPick={() => renderer.promptForPaths({ allowMultiple: true })}
/>;
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `label` | `string` (required) | `"Drop files"` (a blank label reads as the default) |
| `onDrop` | `(payload: DropPayload) => void` (required) | — |
| `description` | `string` | — |
| `onPick` | `() => void` | — |
| `pickLabel` | `string` | `"Choose files"` (a blank label reads as the default) |
| `disabled` | `boolean` | `false` |
| `className` | `string` | — |

---

# FileUpload

Source: https://gpuixui.sudokw.com/media/file-upload

A queue of files with progress, retry and remove

<ComponentPreview name="file-upload-demo" />

## Usage [#usage]

```tsx
import { FileUpload, type UploadFunction } from "@gpuixui/media";

const upload: UploadFunction = async (file, onProgress) => {
  await transfer(file.path, (fraction) => onProgress(fraction));
};

<FileUpload
  upload={upload}
  files={files}
  onRemoveFile={(id) => setFiles(files.filter((file) => file.id !== id))}
/>;
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `upload` | `UploadFunction` (required) | — |
| `files` | `ReadonlyArray<UploadFile>` (required) | — (a value that is not a list carries no files; a blank or non-text `name` reads as the file's `id`) |
| `onRemoveFile` | `(id: string) => void` | — |
| `label` | `string` | `"Upload files"` |
| `emptyLabel` | `string` | `"No files"` |
| `retryLabel` | `string` | `"Retry"` |
| `removeLabel` | `string` | `"Remove"` |
| `className` | `string` | — |

---

# ImagePreview

Source: https://gpuixui.sudokw.com/media/image-preview

An image surface with loading, error and pointer zoom

<ComponentPreview name="image-preview-demo" />

## Usage [#usage]

```tsx
import { ImagePreview } from "@gpuixui/media";

<ImagePreview
  src={bytesReady ? "data:image/png;base64,…" : ""}
  alt="The dashboard screenshot"
  status={fetchFailed ? "error" : bytesReady ? "loaded" : "loading"}
  caption="Figure 1 — the revenue dashboard"
  onRetry={() => refetch()}
/>;
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `src` | `string` (required) | — (a blank or non-text value paints the error state) |
| `alt` | `string` (required) | — (a blank or non-text value reads as `"Picture"`) |
| `status` | `ImagePreviewStatus` | `"error"` for blank `src`, else `"loaded"` |
| `caption` | `string` | — |
| `loadingLabel` | `string` | `"Loading"` |
| `errorLabel` | `string` | `"Could not load image"` |
| `retryLabel` | `string` | `"Retry"` |
| `onRetry` | `() => void` | — |
| `width` / `height` | `number` | `240` / `160` |
| `zoom` | `boolean` | `true` |
| `scale` | `number` | `ImageZoom`'s `1.6` |
| `radius` | `number` | `theme.radius.md` |
| `className` | `string` | — |

---

# MediaPlayer

Source: https://gpuixui.sudokw.com/media/media-player

A clip's poster and Mux's transport, on the app's clock

<ComponentPreview name="media-player-demo" />

## Usage [#usage]

```tsx
import * as Option from "effect/Option";
import { MediaPlayer, type MediaFrame } from "@gpuixui/media";

// The caller decodes or generates each frame: a file, a stream or a sequence.
const frameAt = (playhead: number): Option.Option<MediaFrame> =>
  Option.some(frames[Math.floor(playhead / 1000)] ?? firstFrame);

<MediaPlayer
  duration={24_000}
  frameAt={frameAt}
  alt="A clip's frame"
  label="Generated clip"
  width={640}
  height={360}
  buffered={18_000}
  qualities={["Auto", "1080p", "720p"]}
  onPlayheadChange={(playhead) => savePosition(playhead)}
/>;
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `duration` | `number` (milliseconds) | required |
| `frameAt` | `(playhead) => Option<MediaFrame>` (a value that is not a function reads as no source) | — (no picture) |
| `alt` | `string` | required (a blank name reads as the player's own) |
| `label` | `string` | `"Media player"` (a blank name reads as the default) |
| `width` | `number` | `640` |
| `height` | `number` | `360` |
| `buffered` | `number` (milliseconds) | the whole clip |
| `defaultPlayhead` | `number` | `0` |
| `onPlayheadChange` | `(playhead: number) => void` | — |
| `defaultPlaying` | `boolean` | `false` |
| `onPlayingChange` | `(playing: boolean) => void` | — |
| `defaultVolume` | `number` (`0…1`) | `1` |
| `onVolumeChange` | `(volume: number) => void` | — |
| `defaultMuted` | `boolean` | `false` |
| `onMutedChange` | `(muted: boolean) => void` | — |
| `rates` | `ReadonlyArray<number>` | `[0.5, 1, 1.5, 2]` |
| `defaultRate` | `number` | `1` |
| `onRateChange` | `(rate: number) => void` | — |
| `qualities` | `ReadonlyArray<string>` | `[]` (the settings menu offers speed only) |
| `defaultQuality` | `string` | the first quality |
| `onQualityChange` | `(quality: string) => void` | — |
| `tickMs` | `number` | `100` |
| `seekStep` | `number` | `1000` |
| `largeSeekStep` | `number` | `10000` |
| `idleMs` | `number` | `3000` |
| `onFullscreenChange` | `(fullscreen: boolean) => void` | — |
| `playLabel` | `string` | `"Play"` (a blank label reads as the default) |
| `pauseLabel` | `string` | `"Pause"` (a blank label reads as the default) |
| `disabled` | `boolean` | `false` |
| `className` | `string` | — |
| `style` | `StyleDesc` | — |
| `testId` | `string` | `"media-player"` |

A `MediaFrame` is `{ width, height, pixels }`, where `pixels` are straight RGBA
bytes (`width * height * 4`). The player pushes them with
`ImgInstance.setImagePixels` from a layout effect; the route is measured by the
`media-frame-lifecycle` probe. A frame whose box or buffer cannot be laid out
paints no new picture rather than a broken one.

## Keyboard [#keyboard]

The player is a focusable group, so its keys work while it, its timeline or any
control inside it holds the focus:

| Key | What it does |
| --- | ------------ |
| `Space` / `K` | play or pause |
| `Left` / `Right` | seek back or forward by `seekStep` |
| `Shift` + `Left` / `Right` | seek back or forward by `largeSeekStep` |
| `J` / `L` | seek back or forward by `largeSeekStep` |
| `Up` / `Down` | raise or lower the volume by five points |
| `Home` / `End` | seek to the clip's start or end (and stop a running clip) |
| `M` | mute or unmute |
| `F` | ask the window for fullscreen |

Every control is a shipped `Button`/`IconButton` with its own name, so Enter and
Space activate the focused control as they do elsewhere in the library.

## Pointer [#pointer]

The timeline is a seek control: a press seeks to the share of the clip the
pointer names, and a drag while the primary button is held scrubs. The painted
rail is 4 points tall with a 12-point thumb, and the hit target is the
**24-point** band around it (`targetSize.minimum`); the rail is
pointer-transparent inside that band. The player reads the band's box from the
renderer at press time — the route the shipped `Slider` uses — so a resize is
picked up without a second measurement. A press outside the band's ends clamps
to 0:00 or the clip's end, a secondary press begins no scrub, and a move that
holds no button ends the gesture.

The bar fades out after `idleMs` without a pointer move, key or focus, and any
of those brings it back. A popup keeps it painted while it is open.

---

# QrCode

Source: https://gpuixui.sudokw.com/media/qr-code

A QR symbol from the package's own encoder

<ComponentPreview name="qr-code-demo" />

## Usage [#usage]

```tsx
import { QrCode } from "@gpuixui/media";

<QrCode
  value="https://gpuixui.dev/components/qr-code"
  label="The component documentation"
  size={160}
/>;
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `value` | `string` | required |
| `level` | `"L" \| "M" \| "Q" \| "H"` | `"M"` |
| `size` | `number` | `160` |
| `quietZone` | `number` | `4` |
| `ink` | `string` | `#111111` (a blank or non-text value reads as the default) |
| `paper` | `string` | `#FFFFFF` (a blank or non-text value reads as the default) |
| `label` | `string` | `"QR code"` |
| `className` | `string` | — |
| `style` | `StyleDesc` | — |

## Modes [#modes]

The encoder carries the value in the densest mode it **wholly** fits, and a
version a step smaller than byte mode alone would need:

| Value | Mode | A version-1 `L` symbol holds |
| ----- | ---- | ---------------------------- |
| digits only | numeric | 41 digits |
| the 45-character table (`0-9`, `A-Z`, space, `$%*+-./:`) | alphanumeric | 25 characters |
| anything else, as UTF-8 | byte | 17 bytes |

A value that mixes the sets — `INV-2026-OK`, a URL with a lower-case path — is
carried as **one** byte-mode segment rather than split into several, so the
symbol is always valid though not always the smallest one the standard allows.
The mode is a property of the value, not a prop: a caller who needs the smaller
symbol writes a payload the table already covers.

---

# Shell surfaces

Source: https://gpuixui.sudokw.com/shell

The app menu, the status bar and the toolbar that frame a window.

- [Application menu](https://gpuixui.sudokw.com/shell/app-menu): The in-window menu bar, with keyboard traversal
- [Status bar](https://gpuixui.sudokw.com/shell/status-bar): The bottom strip of the application chrome — left, centre and right groups, tones, hairline separators, truncation and a mono type scale
- [Toolbar](https://gpuixui.sudokw.com/shell/toolbar): A horizontal action strip with an overflow menu

---

# Application menu

Source: https://gpuixui.sudokw.com/shell/app-menu

The in-window menu bar, with keyboard traversal

## Usage [#usage]

```tsx
import { AppMenu, type AppMenuEntry } from "@gpuixui/shell";

const menus: ReadonlyArray<AppMenuEntry> = [
  {
    id: "file",
    label: "File",
    items: [
      { id: "new", label: "New file", accelerator: "mod+n" },
      { id: "save", label: "Save", accelerator: "mod+s" },
    ],
  },
  { id: "edit", label: "Edit", items: [{ id: "undo", label: "Undo", accelerator: "mod+z" }] },
];

<AppMenu label="Editor" menus={menus} onSelect={(menuId, itemId) => run(menuId, itemId)} />;
```

## Pointer [#pointer]

A closed bar opens nothing on hover: a menu opens on press. Once one menu is
open, moving the pointer onto a sibling title switches to that menu at once and
closes the previous one, the macOS menu-bar rule; pressing the open title again
closes it. Moving off a title into its dropdown keeps the dropdown open.

## API [#api]

| Part | Renders | Props |
| ---- | ------- | ----- |
| `AppMenu` | `div` with `role="menubar"` | `label?`, `menus` (required), `platform?`, `onSelect?`, `className?` |
| `AppMenuItem` | a dropdown row | `id`, `label`, `accelerator?`, `disabled?` |
| `AppMenuEntry` | a top-level menu | `id`, `label`, `disabled?`, `items` |

---

# Status bar

Source: https://gpuixui.sudokw.com/shell/status-bar

The bottom strip of the application chrome — left, centre and right groups, tones, hairline separators, truncation and a mono type scale

## Usage [#usage]

```tsx
import { StatusBar } from "@gpuixui/shell";

<StatusBar
  label="Editor status"
  left={[
    { id: "branch", label: "main" },
    { id: "position", label: "Ln 12, Col 4" },
  ]}
  center={[{ id: "file", label: "packages/shell/src/status-bar/status-bar.tsx" }]}
  right={[
    { id: "encoding", label: "UTF-8" },
    { id: "errors", label: "3 errors", tone: "destructive" },
  ]}
/>;
```

## Anatomy [#anatomy]

gpui-kit's bar has three regions and the centre follows the pinned ends:

- `left` pins to the leading edge and `right` to the trailing edge.
- `center` is **centred** when both pinned groups have items, **end-aligned**
  when only `left` does, and **start-aligned** otherwise. The rule is
  `centerAlignment` and it treats an empty group as absent.
- A hairline `1px` separator sits between the items of one group, never around
  the group.
- Every label truncates (`overflow: hidden`, `textOverflow: ellipsis`,
  `nowrap`) and shrinks before the group would overflow.
- Labels are `text-xs` in the theme's **mono** scale — a status readout is
  scanned, not read as prose.
- `tone` paints a status role's readable foreground; `default` keeps the bar's
  own foreground.

## API [#api]

| Part | Renders | Props |
| ---- | ------- | ----- |
| `StatusBar` | `div` with `role="status"` | `label?`, `left?`, `center?`, `right?`, `className?` |
| `StatusBarItem` | one `<text>` in a group | `id`, `label`, `tone?` |

---

# Toolbar

Source: https://gpuixui.sudokw.com/shell/toolbar

A horizontal action strip with an overflow menu

## Usage [#usage]

```tsx
import { Toolbar, type ToolbarAction } from "@gpuixui/shell";

const actions: ReadonlyArray<ToolbarAction> = [
  { id: "open", label: "Open", icon: "file", group: "file" },
  { id: "save", label: "Save", icon: "download", group: "file" },
  { id: "copy", label: "Copy", icon: "copy", group: "edit" },
  { id: "link", label: "Link", icon: "link", group: "edit" },
];

<Toolbar label="Document" max={5} actions={actions} onAction={(id) => run(id)} />;
```

## API [#api]

| Part | Renders | Props |
| ---- | ------- | ----- |
| `Toolbar` | `div` with `role="toolbar"` | `label?`, `actions` (required), `max?`, `onAction?`, `modes?`, `mode?`, `onModeChange?`, `modesLabel?`, `className?` |
| `ToolbarAction` | one `Button` in the leading group | `id`, `label`, `icon?`, `group?`, `disabled?` |
| `ToolbarMode` | one option in the trailing `ToggleGroup` | `id`, `label`, `disabled?` |

The strip is a leading group of actions, a flexible spacer, then the trailing
group — the mode group and the overflow trigger.

---

# Workspace

Source: https://gpuixui.sudokw.com/workspace

The desktop-shell lane, with split and dock

## The lane [#the-lane]

Statuses come from `.agents/slop/COMPONENTS.md`.

<LaneTable lane="workspace" />

<ComponentPreview name="panel-preview" />

The divider's 6px box announces its size through `aria-valuetext`; a focused
divider steps 16px with the arrow keys.

## What composes a window [#what-composes-a-window]

| Part of the shell | Compose it from | Page |
| ----------------- | --------------- | ---- |
| The frame | `Box` + `Stack` + `Separator` + `ScrollArea` | [Stack](/primitives/stack) |
| Resizable split panes | `SplitPane` | [Split pane](/dock/split-pane) |
| Panel groups | `PanelGroup` | [Panel groups](/dock/panel-group) |
| A docked arrangement | `DockLayout` | [Docking layouts](/dock/dock-layout) |
| Tabbed panels | `Tabs` | [Tabs](/components/tabs) |
| Command palette | `CommandMenu` | [Command menu](/components/command-menu) |
| Application menus | `AppMenu` | [Application menu](/shell/app-menu) |
| Breadcrumb navigation | `Breadcrumb` | [Breadcrumb](/components/breadcrumb) |
| Toolbars | `Toolbar` | [Toolbar](/shell/toolbar) |
| Status bars | `StatusBar` | [Status bar](/shell/status-bar) |
| Notifications | `Toast` provider and viewport | [Toast](/components/toast) |
| A whole window | The [Dashboard](/blocks/dashboard) block | [Blocks](/blocks) |

The frames themselves are on [Primitives](/primitives/stack); the [dock](/dock/split-pane) and [shell](/shell/app-menu) pages stay in Workspace, and the rest are under [Components](/components).

## What ships today [#what-ships-today]

<LanePages lane="workspace" />

## Persistence [#persistence]

Decode a stored `DockNode` or `PanelLayout` with its JSON schema; open the
default when the decode fails:

```ts
import { DockNodeJson } from "@gpuixui/dock";
import * as Schema from "effect/Schema";

const saved = Schema.encodeUnknownSync(DockNodeJson)(layout);
const restored = Schema.decodeUnknownSync(DockNodeJson)(saved);
```

## Moving a tab [#moving-a-tab]

A tab strip is `Tabs` plus the app's own drag state; `Cmd+Shift+Left`/`Right`
step it without wrapping.

- A dragged tab leaves its strip and lands at the dropped slot; the source selects the tab that took its place.
- A moved panel's draft survives the remount; restore the focus it drops.
- A release outside both strips misses.
- **A detached tab is not available.** The window holds one process; move a tab to another pane or layer with `createPortal`.

---

# Effects

Source: https://gpuixui.sudokw.com/effects

Decorative motion — particles, stars, shine and ripple, kinetic text — kept out of the core library.

- [Bubbles](https://gpuixui.sudokw.com/effects/bubbles): A decorative field of rising bubbles
- [Fireworks](https://gpuixui.sudokw.com/effects/fireworks): A decorative field of bursting sparks
- [Gravity stars](https://gpuixui.sudokw.com/effects/gravity-stars): A decorative field of stars falling into a well
- [Hexagon](https://gpuixui.sudokw.com/effects/hexagon): A tiled hexagon outline field generated for its box
- [Liquid button](https://gpuixui.sudokw.com/effects/liquid-button): An action a soft fill floods into on hover
- [Magnetic](https://gpuixui.sudokw.com/effects/magnetic): Content that leans toward the pointer over it
- [Motion grid](https://gpuixui.sudokw.com/effects/motion-grid): Cells that travel to their new slots when order changes
- [Particles](https://gpuixui.sudokw.com/effects/particles): A decorative field of drifting motes
- [Ripple button](https://gpuixui.sudokw.com/effects/ripple-button): An action whose press spreads a wash from the pointer
- [Rolling text](https://gpuixui.sudokw.com/effects/rolling-text): A value that rolls into place when it changes
- [Rotating text](https://gpuixui.sudokw.com/effects/rotating-text): One line whose phrase changes on an interval
- [Shader layer](https://gpuixui.sudokw.com/effects/shader-layer): Fire, liquid metal, glass and backdrop effects painted by GPUI in painter order
- [Shine button](https://gpuixui.sudokw.com/effects/shine-button): An action a soft sheen crosses under the pointer
- [Sliding text](https://gpuixui.sudokw.com/effects/sliding-text): A value that slides horizontally into place when it changes
- [Splitting text](https://gpuixui.sudokw.com/effects/splitting-text): A headline that arrives word by word
- [Stars](https://gpuixui.sudokw.com/effects/stars): A decorative field of twinkling lights
- [Typing text](https://gpuixui.sudokw.com/effects/typing-text): A string that arrives a character at a time

---

# Bubbles

Source: https://gpuixui.sudokw.com/effects/bubbles

A decorative field of rising bubbles

<ComponentPreview name="bubbles-demo" />

## Usage [#usage]

```tsx
import { Bubbles } from "@gpuixui/fx/bubbles";

<div style={{ position: "relative", height: 260, overflow: "hidden" }}>
  <div style={{ position: "absolute", top: 0, right: 0, bottom: 0, left: 0 }}>
    <Bubbles count={32} seed={7} />
  </div>
  <EmptyState title="Preparing your workspace" />
</div>;
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `count` | `number` | `24` |
| `seed` | `number` | `1` |
| `minSize` | `number` | `6` |
| `maxSize` | `number` | `28` |
| `color` | `string` | theme `primary` |
| `riseMs` | `number` | `7_000` |
| `level` | `MotionLevel` | `"slow"` |
| `className` | `string` | — |
| `style` | `StateStyle<BubblesState>` | — |

---

# Fireworks

Source: https://gpuixui.sudokw.com/effects/fireworks

A decorative field of bursting sparks

<ComponentPreview name="fireworks-demo" />

## Usage [#usage]

```tsx
import { Fireworks } from "@gpuixui/fx/fireworks";

<div style={{ position: "relative", height: 260, overflow: "hidden" }}>
  <div style={{ position: "absolute", top: 0, right: 0, bottom: 0, left: 0 }}>
    <Fireworks bursts={3} sparks={20} seed={5} />
  </div>
  <EmptyState title="Release published" />
</div>;
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `bursts` | `number` | `3` |
| `sparks` | `number` | `18` |
| `seed` | `number` | `1` |
| `minSize` | `number` | `2` |
| `maxSize` | `number` | `4` |
| `color` | `string` | theme `primary` |
| `burstMs` | `number` | `1_400` |
| `level` | `MotionLevel` | `"slow"` |
| `className` | `string` | — |
| `style` | `StateStyle<FireworksState>` | — |

---

# Gravity stars

Source: https://gpuixui.sudokw.com/effects/gravity-stars

A decorative field of stars falling into a well

<ComponentPreview name="gravity-stars-demo" />

## Usage [#usage]

```tsx
import { GravityStars } from "@gpuixui/fx/gravity-stars";

<div style={{ position: "relative", height: 280, overflow: "hidden" }}>
  <div style={{ position: "absolute", top: 0, right: 0, bottom: 0, left: 0 }}>
    <GravityStars count={44} seed={7} />
  </div>
  <SignInCard />
</div>;
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `count` | `number` | `36` |
| `seed` | `number` | `1` |
| `minSize` | `number` | `1` |
| `maxSize` | `number` | `3` |
| `color` | `string` | theme `primary` |
| `fallMs` | `number` | `3_000` |
| `level` | `MotionLevel` | `"slow"` |
| `className` | `string` | — |
| `style` | `StateStyle<GravityStarsState>` | — |

---

# Hexagon

Source: https://gpuixui.sudokw.com/effects/hexagon

A tiled hexagon outline field generated for its box

<ComponentPreview name="hexagon-demo" />

## Usage [#usage]

```tsx
import { Hexagon } from "@gpuixui/fx/hexagon";

<Hexagon
  radius={34}
  stroke={1}
  style={{ width: 520, height: 260 }}
/>;
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `children` | `ReactNode` | — |
| `radius` | `number` | `30` |
| `stroke` | `number` | `1` |
| `color` | `string` | theme `border` |
| `breatheMs` | `number` | `8_000` |
| `level` | `MotionLevel` | `"slow"` |
| `className` | `string` | — |
| `style` | `StateStyle<HexagonState>` | — |

---

# Liquid button

Source: https://gpuixui.sudokw.com/effects/liquid-button

An action a soft fill floods into on hover

<ComponentPreview name="liquid-button-demo" />

## Usage [#usage]

```tsx
import { LiquidButton } from "@gpuixui/fx/liquid-button";

<LiquidButton variant="primary" onClick={save}>
  Save draft
</LiquidButton>;
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `variant` | `"primary" \| "secondary" \| "ghost" \| "danger"` | `"secondary"` |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` |
| `disabled` | `boolean` | `false` |
| `loading`, `loadingLabel`, `reducedMotion`, `leading`, `trailing` | the shared `Button` busy contract | — |
| `level` | `MotionLevel` | `"normal"` |
| `liquidColor` | `string` | label ink at 16% |
| `onMouseMove` | `(event) => void` | — |
| `onMouseLeave` | `(event) => void` | — |
| `onLayout` | `(event) => void` | — |
| `style` | `StyleDesc` | — |

---

# Magnetic

Source: https://gpuixui.sudokw.com/effects/magnetic

Content that leans toward the pointer over it

<ComponentPreview name="magnetic-demo" />

## Installation [#installation]

```bash
nub add @gpuixui/components
```

## Usage [#usage]

```tsx
import { Magnetic } from "@gpuixui/fx/magnetic";

<Magnetic onClick={open}>
  <Card>
    <CardTitle>Notes</CardTitle>
  </Card>
</Magnetic>;
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `children` | `ReactNode` | — |
| `strength` | `number` | `0.35` |
| `maxOffset` | `number` | `12` |
| `level` | `MotionLevel` | `"fast"` |
| `className` | `string` | — |
| `style` | `StateStyle<{ pulled, reducedMotion }>` | — |
| `onMouseMove` | `(event) => void` | — |
| `onMouseLeave` | `(event) => void` | — |
| `onLayout` | `(event) => void` | — |

---

# Motion grid

Source: https://gpuixui.sudokw.com/effects/motion-grid

Cells that travel to their new slots when order changes

<ComponentPreview name="motion-grid-demo" />

## Installation [#installation]

```bash
nub add @gpuixui/components
```

## Usage [#usage]

```tsx
import { MotionGrid } from "@gpuixui/fx/motion-grid";

<MotionGrid
  items={tools.map((tool) => ({ id: tool.id, content: <ToolCard tool={tool} /> }))}
  columns={3}
  cellWidth={160}
  rowHeight={120}
  gap={12}
  label="Tool board"
/>;
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `items` | `ReadonlyArray<MotionGridItem>` (a value that is not a list reads as none; an entry without a text `id` is dropped) | — |
| `columns` | `number` | `3` |
| `cellWidth` | `number` | `160` |
| `rowHeight` | `number` | `120` |
| `gap` | `number` | `12` |
| `level` | `MotionLevel` | `"normal"` |
| `label` | `string` | — |
| `className` | `string` | — |
| `style` | `StateStyle<MotionGridState>` | — |

---

# Particles

Source: https://gpuixui.sudokw.com/effects/particles

A decorative field of drifting motes

<ComponentPreview name="particles-demo" />

## Installation [#installation]

```bash
nub add @gpuixui/components
```

## Usage [#usage]

```tsx
import { Particles } from "@gpuixui/fx/particles";

<div style={{ position: "relative", height: 220, overflow: "hidden" }}>
  <div style={{ position: "absolute", top: 0, right: 0, bottom: 0, left: 0 }}>
    <Particles count={28} seed={7} />
  </div>
  <Hero copy="Aurora 3.0" />
</div>;
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `count` | `number` | `24` |
| `seed` | `number` | `1` |
| `minSize` | `number` | `2` |
| `maxSize` | `number` | `5` |
| `color` | `string` | theme `primary` |
| `driftMs` | `number` | `14_000` |
| `level` | `MotionLevel` | `"slow"` |
| `className` | `string` | — |
| `style` | `StateStyle<{ count, reducedMotion, width, height }>` | — |

---

# Ripple button

Source: https://gpuixui.sudokw.com/effects/ripple-button

An action whose press spreads a wash from the pointer

<ComponentPreview name="ripple-button-demo" />

## Installation [#installation]

```bash
nub add @gpuixui/components
```

## Usage [#usage]

```tsx
import { RippleButton } from "@gpuixui/fx/ripple-button";

<RippleButton variant="primary" onClick={deploy}>
  Deploy
</RippleButton>;
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `variant` | `"primary" \| "secondary" \| "ghost" \| "danger"` | `"secondary"` |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` |
| `disabled` | `boolean` | `false` |
| `loading`, `loadingLabel`, `reducedMotion`, `leading`, `trailing` | the shared `Button` busy contract | — |
| `level` | `MotionLevel` | `"notice"` |
| `rippleColor` | `string` | the label ink at 28% |
| `onClick` | `(event) => void` | — |
| `onLayout` | `(event) => void` | — |
| `style` | `StyleDesc` | — |

---

# Rolling text

Source: https://gpuixui.sudokw.com/effects/rolling-text

A value that rolls into place when it changes

<ComponentPreview name="rolling-text-demo" />

## Installation [#installation]

```bash
nub add @gpuixui/components
```

## Usage [#usage]

```tsx
import { RollingText } from "@gpuixui/fx/rolling-text";

<RollingText text={String(deploys)} role="display" />;
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `text` | `string` | — |
| `direction` | `"up" \| "down"` | `"up"` |
| `level` | `MotionLevel` | `"normal"` |
| `role` | `TextRole` | `"body"` |
| `className` | `string` | — |
| `style` | `StateStyle<RollingTextState>` | — |

## A value that keeps changing [#a-value-that-keeps-changing]

The swap is timed from the exit the **change** started, not from the newest value: a value arriving mid-exit replaces the pending one, and the window is the exit half of `level`, so a live counter — a value updated faster than one swap — still commits a swap every window and shows a newer value instead of emptying the clip. Once the changes stop, the last value is the one that paints.

Under `MotionProvider preference="reduced"` the swap is immediate, so there is no window to wait.

---

# Rotating text

Source: https://gpuixui.sudokw.com/effects/rotating-text

One line whose phrase changes on an interval

<ComponentPreview name="rotating-text-demo" />

## Installation [#installation]

```bash
nub add @gpuixui/components
```

## Usage [#usage]

```tsx
import { RotatingText } from "@gpuixui/fx/rotating-text";

<RotatingText
  phrases={["Faster builds", "Safer releases", "One runtime"]}
  intervalMs={3000}
/>;
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `phrases` | `ReadonlyArray<string>` | — |
| `intervalMs` | `number` | `3000` |
| `index` | `number` | — |
| `defaultIndex` | `number` | `0` |
| `onIndexChange` | `(index: number) => void` | — |
| `label` | `string` | the phrase on screen |
| `role` | `TextRole` | `"body"` |
| `className` | `string` | — |
| `style` | `StateStyle<RotatingTextState>` | — |

---

# Shader layer

Source: https://gpuixui.sudokw.com/effects/shader-layer

Fire, liquid metal, glass and backdrop effects painted by GPUI in painter order

<ComponentPreview name="shader-layer-demo" />

Every effect is real WGSL painted between your components, so a backdrop effect
distorts the live pixels of whatever is under it. The clip above is a capture of
real components, not an illustration.

## Installation [#installation]

Stock GPUI has fixed primitives, so these effects need the patched binary from
`@gpuixui/native`. Register it once at your entry point:

```tsx
import "@gpuixui/native/register";
```

The patch carries Metal and wgpu, including WebGPU in the browser. DirectX is
not implemented, and WebGL2 skips any effect that reads the backdrop.

## Usage [#usage]

```tsx
import { liquidMetal, ShaderLayer, useShaderClock } from "@gpuixui/fx/shader-layer";

const time = useShaderClock();

<ShaderLayer fx={liquidMetal({ rect, radius: 28, time })} />;
```

An effect is a plain value. Factories are pure functions of `time`, so the same
inputs give the same frame, and `useShaderClock` holds still under reduced motion.

## Effects [#effects]

| Factory | Paints | Reads the backdrop |
| ---- | ---- | ---- |
| `firePlan` | a simulated flame and smoke on a persistent grid | no |
| `glow`, `pulse`, `shimmer` | aura, radiating rings, a loading sweep | no |
| `sparkles` | twinkles, or a burst at a chosen time | no |
| `electric` | lightning running round a rounded rect | no |
| `liquidMetal`, `plastic`, `mesh` | material fills | no |
| `lens`, `fluted`, `shockwave` | refractive glass and a travelling wave | yes |
| `waterRipple` | drops that refract and tint what is below | yes |
| `bungeeGum` | stretches the pixels at a point along a strand | yes |
| `enScan` | an expanding ring that reveals edges | yes |
| `godspeed` | glitch bands and colour split | yes |
| `singularity` | swirls everything into a black hole | yes |
| `zetsu` | dissolves everything into cells | yes |

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `fx` | `Fx \| null` | — |

`Fx` is `{ source, box, params, time, data?, readsBackdrop?, simulationSource?, simulationGrid?, simulationUniform? }`.
`box` is relative to the parent, and the backdrop factories expect their points in the same space.

The material, glow, glass and fire effects are ported from
[rune-fx](https://github.com/anomalyco/rune) (MIT, © Anomaly).

---

# Shine button

Source: https://gpuixui.sudokw.com/effects/shine-button

An action a soft sheen crosses under the pointer

<ComponentPreview name="shine-button-demo" />

## Installation [#installation]

```bash
nub add @gpuixui/components
```

## Usage [#usage]

```tsx
import { ShineButton } from "@gpuixui/fx/shine-button";

<ShineButton variant="primary" onClick={deploy}>
  Deploy
</ShineButton>;
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `variant` | `"primary" \| "secondary" \| "ghost" \| "danger"` | `"secondary"` |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` |
| `disabled` | `boolean` | `false` |
| `loading`, `loadingLabel`, `reducedMotion`, `leading`, `trailing` | the shared `Button` busy contract | — |
| `level` | `MotionLevel` | `"notice"` |
| `sheenColor` | `string` | the label colour |
| `onMouseEnter` | `(event) => void` | — |
| `onLayout` | `(event) => void` | — |
| `style` | `StyleDesc` | — |

---

# Sliding text

Source: https://gpuixui.sudokw.com/effects/sliding-text

A value that slides horizontally into place when it changes

<ComponentPreview name="sliding-text-demo" />

## Installation [#installation]

```bash
nub add @gpuixui/components
```

## Usage [#usage]

```tsx
import { SlidingText } from "@gpuixui/fx/sliding-text";

<div style={{ width: 220 }}>
  <SlidingText text={status} role="bodyStrong" />
</div>;
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `text` | `string` | — |
| `direction` | `"forward" \| "back"` | `"forward"` |
| `level` | `MotionLevel` | `"normal"` |
| `role` | `TextRole` | `"body"` |
| `className` | `string` | — |
| `style` | `StateStyle<SlidingTextState>` | — |

## A value that keeps changing [#a-value-that-keeps-changing]

The swap is timed from the exit the **change** started, not from the newest value: a value arriving mid-exit replaces the pending one, and the window is the exit half of `level`, so a live counter — a value updated faster than one swap — still commits a swap every window and shows a newer value instead of emptying the clip. Once the changes stop, the last value is the one that paints.

Under `MotionProvider preference="reduced"` the swap is immediate, so there is no window to wait.

---

# Splitting text

Source: https://gpuixui.sudokw.com/effects/splitting-text

A headline that arrives word by word

<ComponentPreview name="splitting-text-demo" />

## Installation [#installation]

```bash
nub add @gpuixui/components
```

## Usage [#usage]

```tsx
import { SplittingText } from "@gpuixui/fx/splitting-text";

<SplittingText text="Build native interfaces" role="h1" />;
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `text` | `string` | — |
| `split` | `"words" \| "characters"` | `"words"` |
| `stepMs` | `number` | `40` |
| `from` | `"start" \| "end" \| "center"` | `"start"` |
| `offset` | `number` | `8` |
| `role` | `TextRole` | `"body"` |
| `className` | `string` | — |
| `style` | `StateStyle<SplittingTextState>` | — |

---

# Stars

Source: https://gpuixui.sudokw.com/effects/stars

A decorative field of twinkling lights

<ComponentPreview name="stars-demo" />

## Installation [#installation]

```bash
nub add @gpuixui/components
```

## Usage [#usage]

```tsx
import { Stars } from "@gpuixui/fx/stars";

<div style={{ position: "relative", height: 240, overflow: "hidden" }}>
  <div style={{ position: "absolute", top: 0, right: 0, bottom: 0, left: 0 }}>
    <Stars count={64} seed={11} />
  </div>
  <EmptyState title="No builds yet" />
</div>;
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `count` | `number` | `48` |
| `seed` | `number` | `1` |
| `minSize` | `number` | `1` |
| `maxSize` | `number` | `3` |
| `color` | `string` | theme `foreground` |
| `twinkleMs` | `number` | `2_400` |
| `level` | `MotionLevel` | `"slow"` |
| `className` | `string` | — |
| `style` | `StateStyle<{ count, reducedMotion, width, height }>` | — |

---

# Typing text

Source: https://gpuixui.sudokw.com/effects/typing-text

A string that arrives a character at a time

<ComponentPreview name="typing-text-demo" />

## Installation [#installation]

```bash
nub add @gpuixui/components
```

## Usage [#usage]

```tsx
import { TypingText } from "@gpuixui/fx";

<TypingText text="Deploying to production…" speed={35} />;
```

## API [#api]

| Prop | Type | Default |
| ---- | ---- | ------- |
| `text` | `string` | — |
| `speed` | `number` | `45` |
| `delay` | `number` | `0` |
| `caret` | `boolean` | `false` |
| `label` | `string` | the whole `text` |
| `onComplete` | `() => void` | — |
| `role` | `TextRole` | `"body"` |
| `className` | `string` | — |
| `style` | `StateStyle<TypingTextState>` | — |

---

# Platform

Source: https://gpuixui.sudokw.com/platform

The behaviours only the operating system owns.

**The rule:** take OS-owned behaviour from the OS; paint everything else.

## What ships [#what-ships]

| Surface | Entry | What the OS owns |
| --- | --- | --- |
| Window | `Window`, `SourceList`, `nativeWindowOptions` | the traffic lights over the app's own sidebar and toolbar, and the blur behind them |
| Appearance | `watchAppearance`, `appearanceOverrides` | the accent colour, Light/Dark and Reduce Transparency, read from `defaults` |
| Window verbs | `useWindowActions` | minimise, zoom, fullscreen, rename, activate |
| Path picker | `window.pickPaths` | the system's open panel, and its cancel |

The window opts in with `nativeWindowOptions`, which sets `titlebarTransparent`,
`trafficLightX` / `trafficLightY` and the theme's `windowBackground` on macOS,
and nothing elsewhere:

```tsx
render(<App />, { title: "Files", ...nativeWindowOptions(theme, currentPlatform) });
```

## What stays painted [#what-stays-painted]

- The OS menu bar has no API, so `AppMenu` draws it in-window (`/shell/app-menu`).
- Alerts, sheets and popovers are the library's floating layers, not `NSAlert` or `NSPopover`.
- No native colour panel or tooltip; `Tooltip` is painted.

---

# Window

Source: https://gpuixui.sudokw.com/platform/native-window

The native window's anatomy — a sidebar under the traffic lights, a unified toolbar, opaque content.

<ComponentPreview name="platform-window" />

`Window` is the native frame: a sidebar under the traffic lights, a unified
toolbar, opaque content; macOS vibrancy shows the desktop behind
(`/theming#materials`).

```tsx
<Window
  sidebar={<SourceList label="Mailboxes" sections={sections} value={place} onValueChange={setPlace} />}
  toolbar={<WindowToolbar title="Inbox" actions={<SearchInput />} />}
  inspector={<Details />}
>
  <MessageList />
</Window>
```

Open it with `nativeWindowOptions`; Windows and Linux keep the system bar.

```tsx
render(<App />, { title: "Mail", ...nativeWindowOptions(theme, currentPlatform) });
```

| Prop | Type | Default | Consequence |
| --- | --- | --- | --- |
| `sidebar` | `ReactNode` | none | runs under the lights; without one the toolbar reserves their 90-point box |
| `sidebarWidth` | `number` | `220` | the starting width; drag the sidebar's hairline or focus it and use ←/→/Home/End |
| `sidebarMinWidth` / `sidebarMaxWidth` | `number` | `180` / `360` | the drag's bounds; equal bounds fix the width |
| `onSidebarWidthChange` | `(width) => void` | none | reports each new width, to persist it |
| `toolbar` | `ReactNode` | none | usually a `WindowToolbar` |
| `toolbarStyle` | `"unified" \| "compact"` | `"unified"` | 52 or 38 points tall |
| `inspector` | `ReactNode` | none | a trailing opaque pane, `inspectorWidth` wide (260) |
| `platform` | `PlatformName` | the host's | where the lights float; none in a terminal |

## Source list [#source-list]

`SourceList` is the sidebar's list: 28-point rows, titled sections, one tab
stop. ↑/↓/Home/End move the choice; typing jumps to a label.

- No hover wash; the chosen row is emphasized only while the list holds focus.
- A `collapsible` section folds from its header; `defaultCollapsed` starts it folded.

## Appearance [#appearance]

The runtime reports no accent colour, Light/Dark or Reduce Transparency, so
`@gpuixui/shell` reads them from `defaults`; `watchAppearance` emits changes
(polled every two seconds) and `appearanceOverrides` edits the theme.

```tsx
const app = watchAppearance.pipe(
  Stream.runForEach((appearance) =>
    Effect.sync(() =>
      setTheme(extendTheme(getTheme(appearance.mode), appearanceOverrides(appearance, base))),
    ),
  ),
  Effect.provide(NodeServices.layer),
);
```

- A sandboxed `.app` may be refused the global domain: `AppearanceReadError`.

---

# Window actions

Source: https://gpuixui.sudokw.com/platform/window

Minimise, zoom, fullscreen, rename, and the system's path picker.

<ComponentPreview name="platform-file-panel" />

`useWindowActions` binds the window's verbs for the tree it is called in; a host
without them fails at setup, naming them.

```tsx
const window = useWindowActions();

window.minimize();
window.zoom();
window.toggleFullscreen();
window.setTitle("Files");
```

`pickPaths` opens the system panel and answers `Picked` or `Cancelled`, and fails
with `FilePanelError` if the platform refuses.

```tsx
const chosen = await Effect.runPromise(
  window.pickPaths({ directories: true, prompt: "Choose a folder" }),
);

if (chosen._tag === "Picked") copy(chosen.paths);
```

| Action | What it does | Platform |
| --- | --- | --- |
| `activate` | brings the window forward | all |
| `minimize` | sends it to the Dock | all |
| `zoom` | the platform's zoom or maximise | all |
| `toggleFullscreen` | enters or leaves fullscreen | all |
| `setTitle` | renames the window | all |
| `pickPaths` | opens the system path panel | all |

---

# Blocks

Source: https://gpuixui.sudokw.com/blocks

Page-level recipes composed from the library

Each block pairs a browser reproduction with the `@gpuixui/*` source to copy.

<BlockIndex />

---

# All blocks

Source: https://gpuixui.sudokw.com/blocks/all

Every block, one per row, generated from the block pages' own frontmatter.

Every block the site serves, in one column.

<AllBlocks />

---

# Calendar

Source: https://gpuixui.sudokw.com/blocks/calendar

A month grid with the selected day's agenda beside it

<BlockPreview name="calendar-01" />

---

# Command centre

Source: https://gpuixui.sudokw.com/blocks/command-centre

A command palette over a dimmed page

<BlockPreview name="command-centre-01" />

---

# Conversations

Source: https://gpuixui.sudokw.com/blocks/conversations

A Messages-style window in four platform dresses

<BlockPreview name="conversations-01" />

Click a conversation to swap the thread, type to filter, press Enter to send.

---

# Dashboard

Source: https://gpuixui.sudokw.com/blocks/dashboard

An activity dashboard with stats and charts

<BlockPreview name="dashboard-01" />

---

# Dashboard 01

Source: https://gpuixui.sudokw.com/blocks/dashboard-01

shadcn's dashboard — an inset sidebar, stat cards, and a chart of every shape

<BlockPreview name="dashboard-01-shadcn" />

---

# Dashboard management

Source: https://gpuixui.sudokw.com/blocks/dashboard-management

A settings console with a workspace rail and one column of service sections

<BlockPreview name="dashboard-management-01" />

---

# Data table

Source: https://gpuixui.sudokw.com/blocks/data-table

A deploy table with filtering, sorting, selection and paging

<BlockPreview name="data-table-01" />

---

# Desktop

Source: https://gpuixui.sudokw.com/blocks/desktop

A whole XP-era or Aero-era desktop, from the library

<BlockPreview name="desktop-01" />

## The chrome, as CSS [#the-chrome-as-css]

Both looks, one stylesheet: the window frame, title bar, caption buttons, the
taskbar and the Start menu, in Luna's and Aero's own values.

<DesktopStyles />

---

# Email inbox

Source: https://gpuixui.sudokw.com/blocks/email-inbox

A mail client with a folder rail, message list and reading pane

<BlockPreview name="email-inbox-01" />

Click a message to repaint the reading pane, and use the tabs to filter the list.

---

# File manager

Source: https://gpuixui.sudokw.com/blocks/file-manager

A three-pane file browser

<BlockPreview name="file-manager-01" />

Click a tile to repaint the information rail; the four view buttons switch the layout.

---

# Kanban board

Source: https://gpuixui.sudokw.com/blocks/kanban

A hunter's contract board with counted columns

<BlockPreview name="kanban-01" />

---

# Notifications

Source: https://gpuixui.sudokw.com/blocks/notification-centre

A notification centre with filters and grouped rows

<BlockPreview name="notification-centre-01" />

---

# Pipeline

Source: https://gpuixui.sudokw.com/blocks/pipeline

A release pipeline in a native Mac window

<BlockPreview name="pipeline-01" />

---

# Profile settings

Source: https://gpuixui.sudokw.com/blocks/profile-settings

A profile page with a photo, contact details and tabbed settings

<BlockPreview name="settings-01" />

---

# Settings dialog

Source: https://gpuixui.sudokw.com/blocks/settings-dialog

A modal settings window

<BlockPreview name="settings-dialog-01" />

---

# Sidebar

Source: https://gpuixui.sudokw.com/blocks/sidebar

Sixteen sidebar blocks on one page, grouped

## Documentation panels [#documentation-panels]

### Sidebar 01 — Sectioned docs navigation [#sidebar-01--sectioned-docs-navigation]

A version switcher and search over four sections — [shadcn's `sidebar-01`](https://ui.shadcn.com/blocks/sidebar#sidebar-01).

<SidebarExample slug="sidebar-01" />

### Sidebar 02 — Collapsible sections [#sidebar-02--collapsible-sections]

The same tree with every section folding in place — [shadcn's `sidebar-02`](https://ui.shadcn.com/blocks/sidebar#sidebar-02).

<SidebarExample slug="sidebar-02" />

### Sidebar 03 — Submenus [#sidebar-03--submenus]

Always-open sections, each parent row over its submenu — [shadcn's `sidebar-03`](https://ui.shadcn.com/blocks/sidebar#sidebar-03).

<SidebarExample slug="sidebar-03" />

### Sidebar 04 — Floating submenus [#sidebar-04--floating-submenus]

The always-open tree on a floating, rounded panel — [shadcn's `sidebar-04`](https://ui.shadcn.com/blocks/sidebar#sidebar-04).

<SidebarExample slug="sidebar-04" />

### Sidebar 05 — Collapsible submenus [#sidebar-05--collapsible-submenus]

Parent rows that open a submenu from a plus — [shadcn's `sidebar-05`](https://ui.shadcn.com/blocks/sidebar#sidebar-05).

<SidebarExample slug="sidebar-05" />

### Sidebar 06 — Dropdown sections [#sidebar-06--dropdown-sections]

Each docs section behind its own dropdown, over a newsletter card — [shadcn's `sidebar-06`](https://ui.shadcn.com/blocks/sidebar#sidebar-06).

<SidebarExample slug="sidebar-06" />

## Workspace panels [#workspace-panels]

### Sidebar 07 — Icon rail [#sidebar-07--icon-rail]

A workspace nav that collapses to an icon rail — [shadcn's `sidebar-07`](https://ui.shadcn.com/blocks/sidebar#sidebar-07).

<SidebarExample slug="sidebar-07" />

### Sidebar 08 — Inset panel [#sidebar-08--inset-panel]

The panel on a card surface, the page in a rounded sheet beside it — [shadcn's `sidebar-08`](https://ui.shadcn.com/blocks/sidebar#sidebar-08).

<SidebarExample slug="sidebar-08" />

### Sidebar 10 — Actions popover [#sidebar-10--actions-popover]

The workspace panel beside a page header with an actions popover — [shadcn's `sidebar-10`](https://ui.shadcn.com/blocks/sidebar#sidebar-10).

<SidebarExample slug="sidebar-10" />

### Sidebar 11 — File tree [#sidebar-11--file-tree]

The changed files over the repository, UI folder open — [shadcn's `sidebar-11`](https://ui.shadcn.com/blocks/sidebar#sidebar-11).

<SidebarExample slug="sidebar-11" />

### Sidebar 12 — Calendar [#sidebar-12--calendar]

A month grid with calendar lists and New Calendar in the footer — [shadcn's `sidebar-12`](https://ui.shadcn.com/blocks/sidebar#sidebar-12).

<SidebarExample slug="sidebar-12" />

## More than one panel [#more-than-one-panel]

### Sidebar 09 — Nested inbox [#sidebar-09--nested-inbox]

An icon rail of folders, a message list and the open thread — [shadcn's `sidebar-09`](https://ui.shadcn.com/blocks/sidebar#sidebar-09).

<SidebarExample slug="sidebar-09" />

### Sidebar 14 — Right panel [#sidebar-14--right-panel]

The table of contents on the right edge, toggled from the header — [shadcn's `sidebar-14`](https://ui.shadcn.com/blocks/sidebar#sidebar-14).

<SidebarExample slug="sidebar-14" />

### Sidebar 15 — Two panels [#sidebar-15--two-panels]

Workspace and favorites left, the open project middle, the calendar right — [shadcn's `sidebar-15`](https://ui.shadcn.com/blocks/sidebar#sidebar-15).

<SidebarExample slug="sidebar-15" />

## Panels in a frame [#panels-in-a-frame]

### Sidebar 13 — Settings dialog [#sidebar-13--settings-dialog]

A settings panel inside a modal, section nav on the left — [shadcn's `sidebar-13`](https://ui.shadcn.com/blocks/sidebar#sidebar-13).

<SidebarExample slug="sidebar-13" />

### Sidebar 16 — Site header [#sidebar-16--site-header]

A sticky site header with toggle, trail and search above the workspace — [shadcn's `sidebar-16`](https://ui.shadcn.com/blocks/sidebar#sidebar-16).

<SidebarExample slug="sidebar-16" />

---

# Sign in

Source: https://gpuixui.sudokw.com/blocks/sign-in

A full sign-in page

<BlockPreview name="sign-in-01" />

Submit empty fields for the validation error; submit the credentials in the status row for success.

---

# Tasks

Source: https://gpuixui.sudokw.com/blocks/tasks

A Notion-style tasks view with an inbox and pinned docs

<BlockPreview name="tasks-01" />