<Textarea aria-label="Note" autoSize={{ minRows: 2, maxRows: 5 }} value={note} onChange={(event) => setNote(event.target.value)} />
    </div>
  )
}
```

### Textarea props

Multi-line text.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `invalid` | `boolean` |  |  |
| `autoSize` | `boolean \| AutoSize` |  | Grows with its text (between `minRows` and `maxRows` lines, when given). |

Also takes the attributes of its HTML element (`className`, `aria-*`, events).

## Select

Forms. A drop-down: a native select drawn as Tessera’s control, for the platform’s popup and accessibility.

```ts
import { Select } from '@kition/tessera-ui'
```

### When not to

- Two or three options always visible: use Segmented or Choice.

### Example: Sizes

```tsx
import { Select } from '@kition/tessera-ui'

export default function Demo() {
  return (
    <div className="demo-stack">
      <Select defaultValue="sheet" aria-label="Kit">
        <option value="sheet">Sheet</option>
        <option value="slide">Slide</option>
        <option value="photo">Photo</option>
      </Select>
      <Select size="lg" defaultValue="slide" aria-label="Kit (large)">
        <option value="sheet">Sheet</option>
        <option value="slide">Slide</option>
      </Select>
    </div>
  )
}
```

### Select props

A drop-down. It stays a native select, as kits' do, for the platform's popup and accessibility,
drawn as Tessera's control. Children are `<option>`s.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `ControlSize`: `'sm'`, `'md'`, `'lg'` | `'sm'` |  |
| `invalid` | `boolean` |  |  |

Also takes the attributes of its HTML element (`className`, `aria-*`, events).

## Switch

Forms. An on/off switch for a setting that applies at once.

```ts
import { Switch } from '@kition/tessera-ui'
```

### When to use

- A setting that takes effect without a Save.

### When not to

- A choice saved with a form: use Checkbox.

### Example: On, off, disabled

```tsx
import { useState } from 'react'
import { Switch } from '@kition/tessera-ui'

export default function Demo() {
  const [sync, setSync] = useState(true)
  return (
    <div className="demo-stack">
      <label style={{ display: 'flex', alignItems: 'center', gap: 10, fontSize: 14 }}>
        <Switch checked={sync} onCheckedChange={setSync} aria-label="Sync across devices" /> Sync across devices: {sync ? 'on' : 'off'}
      </label>
      <label style={{ display: 'flex', alignItems: 'center', gap: 10, fontSize: 14, color: 'var(--kit-text-muted)' }}>
        <Switch disabled aria-label="Beta features" /> Beta features (unavailable)
      </label>
    </div>
  )
}
```

### Switch props

An on/off switch for a setting that applies at once. Controlled with `checked` and `onCheckedChange`.

Also takes the attributes of its HTML element (`className`, `aria-*`, events).

## Field

Forms. A label, a control, and its hint or error, wired for screen readers.

```ts
import { Field } from '@kition/tessera-ui'
```

### When to use

- Every form control with a visible label.

### Example: Validation

```tsx
import { useState } from 'react'
import { Field, TextInput } from '@kition/tessera-ui'

export default function Demo() {
  const [email, setEmail] = useState('not-an-email')
  const valid = /^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(email)
  return (
    <Field label="Email" hint="We only use it to sign you in." error={valid ? undefined : 'Enter an email address.'}>
      {({ id, describedBy, invalid }) => (
        <TextInput id={id} aria-describedby={describedBy} invalid={invalid} size="md" value={email} onChange={(event) => setEmail(event.target.value)} />
      )}
    </Field>
  )
}
```

### Field props

A label, a control, and its help or error, wired together for screen readers.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `ReactNode` |  |  |
| `hint` | `ReactNode` |  | Help under the control; replaced by `error` when there is one. |
| `error` | `ReactNode` |  |  |
| `children` (required) | `ReactNode \| ((ids: { id: string; describedBy: string \| undefined; invalid: boolean }) => ReactNode)` |  | The control. Given a function, it receives the ids to put on it (`id`, `aria-describedby`). |
| `className` | `string` |  |  |

## NumberField

Forms. A number with a label you drag to scrub, arrows to step, and units.

```ts
import { NumberField } from '@kition/tessera-ui'
```

### When to use

- Opacity, size, angle, any bounded number in a panel.

### Keyboard

| Keys | What they do |
| --- | --- |
| Up, Down | Step the value by `step`; with Shift, by ten steps. |
| Enter | Commit what is typed. As hot text: open the field to type into. |
| Escape | Put back the value before typing. With nothing typed the key is left to the page, so a dialog still closes. |

### Example: Scrub, type, or arrow

```tsx
import { useState } from 'react'
import { NumberField } from '@kition/tessera-ui'

export default function Demo() {
  const [opacity, setOpacity] = useState(80)
  const [angle, setAngle] = useState(15)
  return (
    <div className="demo-stack">
      <NumberField label="Opacity" value={opacity} min={0} max={100} unit="%" onChange={(value) => setOpacity(value)} />
      <NumberField label="Angle" value={angle} min={-180} max={180} step={1} unit="°" onChange={(value) => setAngle(value)} />
    </div>
  )
}
```

### NumberField props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` |  |  |
| `name` | `string` |  | The field's accessible name and tooltip when `label` is a symbol rather than words (Photoshop's Character panel labels its fields with glyphs: tT, A↕, VA); `label` by default. |
| `value` (required) | `number` |  |  |
| `min` (required) | `number` |  |  |
| `max` (required) | `number` |  |  |
| `step` | `number` |  | Step for arrows and scrubbing; decimals shown follow it (1 → integer). |
| `unit` | `string` |  |  |
| `onChange` (required) | `(value: number, final: boolean) => void` |  | Called while scrubbing with `final: false`, and once with `final: true` on release, Enter, or blur. |
| `disabled` | `boolean` |  |  |
| `width` | `number` |  |  |
| `testId` | `string` |  |  |
| `uiId` | `string` |  | A Kit UI id when the field is a declared element. |
| `track` | `boolean` |  | A slider row: the label and field on one line, a slider from `min` to `max` under them. |
| `hot` | `boolean` |  | Hot text (Premiere's, upstream Film's `widgets::hot_number`): the value and its unit drawn as accent text, without a box or a visible label (`label` names it). Dragged sideways it scrubs by `speed` per CSS pixel (Shift ten times faster, Cmd, Ctrl, or Alt ten times finer), reporting `final: false` per move and the last value again with `final: true` on release; a click opens a field to type into, which commits on Enter or blur and leaves unchanged on Escape. |
| `speed` | `number` |  | Hot text: value units per CSS pixel dragged (`step` by default). |
| `onDone` | `() => void` |  | Hot text: called once a typed edit ends (Enter, Escape, or blur), so the editor can take the focus back. |

## Bar controls

Forms. Compact controls for options bars: Segmented, Choice, Checkbox, Hint, BarSeparator.

```ts
import { Segmented, Choice, Checkbox, Hint, BarSeparator } from '@kition/tessera-ui'
```

### When to use

- A tool’s options above the canvas.

### Example: An options bar

```tsx
import { useState } from 'react'
import { BarSeparator, Checkbox, Choice, Hint, Segmented } from '@kition/tessera-ui'
import { TextAlignCenterIcon, TextAlignEndIcon, TextAlignStartIcon } from '@kition/tessera-icons/react'

export default function Demo() {
  const [align, setAlign] = useState<'start' | 'center' | 'end'>('start')
  const [snap, setSnap] = useState(true)
  const [mode, setMode] = useState<'normal' | 'multiply' | 'screen'>('normal')
  return (
    <div className="demo-row">
      <Segmented
        label="Alignment"
        value={align}
        onChange={setAlign}
        segments={[
          { value: 'start', icon: TextAlignStartIcon, label: 'Left' },
          { value: 'center', icon: TextAlignCenterIcon, label: 'Center' },
          { value: 'end', icon: TextAlignEndIcon, label: 'Right' },
        ]}
      />
      <BarSeparator />
      <Choice label="Mode" value={mode} onChange={setMode} choices={[['normal', 'Normal'], ['multiply', 'Multiply'], ['screen', 'Screen']]} />
      <Checkbox label="Snap" checked={snap} onChange={setSnap} />
      <Hint>Alt-drag to copy</Hint>
    </div>
  )
}
```

### Segmented props

Buttons of which one is pressed: icons (selection modes, alignment) or words (24h, 7d, 30d).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` |  | The group's accessible name (for example "Selection mode"). |
| `value` (required) | `V` |  |  |
| `segments` (required) | `readonly Segment<V>[]` |  |  |
| `disabled` | `boolean` |  |  |
| `onChange` (required) | `(value: V) => void` |  |  |
| `testId` | `string` |  | Each button's test id is `${testId}-${value}`. |

### Choice props

A drop-down choice with its label before it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` |  |  |
| `quiet` | `boolean` |  | Draws no visible label (the drop-down still has `label` as its name). |
| `value` (required) | `V` |  |  |
| `choices` (required) | `readonly (readonly [V, string])[]` |  |  |
| `disabled` | `boolean` |  |  |
| `onChange` (required) | `(value: V) => void` |  |  |
| `testId` | `string` |  |  |

### Checkbox props

A check box with its label.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `ReactNode` |  |  |
| `checked` | `boolean` | `false` |  |
| `disabled` | `boolean` |  |  |
| `onChange` | `(checked: boolean) => void` |  |  |
| `testId` | `string` |  |  |
| `id` | `string` |  |  |

### Hint props

A muted usage hint in a row.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` |  |  |
| `testId` | `string` |  |  |

### BarSeparator props

A hairline between groups of controls in a row.

## Form

Forms. A form that keeps its values and checks them against rules before onFinish; useForm reaches it from outside, useWatch reads one field.

```ts
import { Form, FormItem } from '@kition/tessera-ui'
```

### When to use

- A settings page, a create or edit dialog, any form with validation.

### When not to

- One setting that applies at once: use a Switch on its own.

### Example: Rules, help, reset

Submit with the email empty to see the errors; they re-check as you type.

```tsx
import { Button, Checkbox, Form, FormItem, NumberInput, Select, TextInput, toast, useForm, useWatch } from '@kition/tessera-ui'

type Values = { email: string; credits: number | null; reason: string; plan: string; notify: boolean }

export default function Demo() {
  const form = useForm<Values>()
  const credits = useWatch<number>('credits', form)
  return (
    <div style={{ maxWidth: 420 }}>
      <Form<Values> form={form} initialValues={{ email: '', credits: 100, reason: '', plan: 'pro', notify: true }} onFinish={(values) => toast('success', 'Credits added', `${values.credits} credits for ${values.email}`)}>
        <FormItem name="email" label="Email" rules={[{ required: true }, { type: 'email' }]}>
          <TextInput size="md" placeholder="ada@example.com" />
        </FormItem>
        <FormItem name="credits" label="Credits" rules={[{ required: true }, { min: 1, max: 100000 }]} extra={credits ? `About $${(credits / 100).toFixed(2)} of usage.` : undefined}>
          <NumberInput size="md" min={1} step={10} />
        </FormItem>
        <FormItem name="plan" label="Plan">
          <Select size="md">
            <option value="free">Free</option>
            <option value="pro">Pro</option>
            <option value="team">Team</option>
          </Select>
        </FormItem>
        <FormItem name="reason" label="Reason" rules={[{ required: true, whitespace: true }, { max: 120 }]} extra="Recorded in the credit ledger.">
          <TextInput size="md" />
        </FormItem>
        <FormItem name="notify" valuePropName="checked">
          <Checkbox label="Email the person" />
        </FormItem>
        <div style={{ display: 'flex', gap: 8 }}>
          <Button type="submit" variant="primary" size="md">Add credits</Button>
          <Button size="md" onClick={() => form.resetFields()}>Reset</Button>
        </div>
      </Form>
    </div>
  )
}
```

### Form props

A form that keeps its fields' values and checks them before `onFinish`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `form` | `FormInstance<T>` |  |  |
| `initialValues` | `Partial<T>` |  | The values it starts with (read once). |
| `onFinish` | `(values: T) => void` |  | Called with the values when the person submits and every field passes. |
| `onValuesChange` | `(changed: Partial<T>, values: T) => void` |  |  |
| `layout` | `FormLayout`: `'vertical'`, `'inline'` | `'vertical'` | `vertical` (default): labels above controls; `inline`: fields in a row (filters). |
| `disabled` | `boolean` | `false` |  |
| `className` | `string` |  |  |
| `id` | `string` |  |  |
| `children` (required) | `ReactNode` |  |  |

### FormItem props

A labelled control bound to one field of the form around it, with its rules and error.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` |  | The field's name in the values; without it the item only lays out a label and a control. |
| `label` | `ReactNode` |  |  |
| `rules` | `readonly FormRule[]` | `[]` |  |
| `extra` | `ReactNode` |  | Help under the control (replaced by the error while there is one). |
| `required` | `boolean` |  | Marks the label as required (implied by a `required` rule). |
| `valuePropName` | `string` | `'value'` | The control's prop that holds the value: `checked` for a check box or switch. |
| `trigger` | `string` | `'onChange'` | The control's prop that reports a change: `onCheckedChange` for a switch. |
| `getValueFromEvent` | `(...args: any[]) => unknown` | `fromEvent` | The value from what the control reports (an event's `target.value` or `checked`, or the value itself, by default). |
| `dependencies` | `readonly string[]` | `[]` | Fields whose changes re-check this one (a confirmation of a password). |
| `hidden` | `boolean` |  | Kept in the values but not drawn. |
| `className` | `string` |  |  |
| `children` (required) | `ReactNode` |  | One control element. |

## Combobox and MultiSelect

Forms. One choice from a long list, searched as the person types or on the server with onSearch, and several choices toggled in a list.

```ts
import { Combobox, MultiSelect } from '@kition/tessera-ui'
```

### When to use

- Picking a user, a record, a country: more choices than a Select shows well.

### When not to

- A handful of fixed choices: use Select.

### Example: Search and pick

```tsx
import { useState } from 'react'
import { Combobox } from '@kition/tessera-ui'

const PEOPLE = ['Ada Lovelace', 'Grace Hopper', 'Alan Turing', 'Katherine Johnson', 'Margaret Hamilton', 'Edsger Dijkstra', 'Barbara Liskov', 'Donald Knuth']

export default function Demo() {
  const [person, setPerson] = useState<number | undefined>(2)
  return (
    <div style={{ maxWidth: 320 }}>
      <Combobox
        label="Person"
        size="md"
        placeholder="Search people"
        value={person}
        onChange={setPerson}
        options={PEOPLE.map((name, index) => ({ value: index + 1, label: index === 5 ? `${name} (no GitHub)` : name, disabled: index === 5 }))}
      />
    </div>
  )
}
```

### Example: Several choices

```tsx
import { useState } from 'react'
import { MultiSelect } from '@kition/tessera-ui'

const MODES = ['free', 'reward', 'paid', 'hosted'].map((value) => ({ value, label: value }))

export default function Demo() {
  const [modes, setModes] = useState(['paid', 'hosted'])
  return (
    <div style={{ maxWidth: 280 }}>
      <MultiSelect label="Mode" placeholder="Any mode" size="md" values={modes} onChange={setModes} options={MODES} />
    </div>
  )
}
```

### Combobox props

One choice from a long list, searched as the person types; the choice can be cleared.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `V \| undefined` |  |  |
| `onChange` (required) | `(value: V \| undefined) => void` |  |  |
| `options` (required) | `readonly ComboboxOption<V>[]` |  |  |
| `onSearch` | `(query: string) => void` |  | Search on the server: called with each query, and the options shown are the caller's. Without it, the options are filtered here. |
| `loading` | `boolean` |  |  |
| `placeholder` | `string` |  |  |
| `emptyText` | `ReactNode` |  | Shown when nothing matches. |
| `label` (required) | `string` |  | The control's accessible name. |
| `size` | `ControlSize`: `'sm'`, `'md'`, `'lg'` | `'sm'` |  |
| `disabled` | `boolean` |  |  |
| `className` | `string` |  |  |
| `testId` | `string` |  |  |

### MultiSelect props

Several choices from a list: the chosen ones in the field, toggled in a list (searchable once it is long).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `values` (required) | `readonly V[]` |  |  |
| `onChange` (required) | `(values: V[]) => void` |  |  |
| `options` (required) | `readonly ComboboxOption<V>[]` |  |  |
| `placeholder` | `string` |  | Shown when nothing is chosen. |
| `label` (required) | `string` |  | The control's accessible name. |
| `size` | `ControlSize`: `'sm'`, `'md'`, `'lg'` | `'sm'` |  |
| `disabled` | `boolean` |  |  |
| `className` | `string` |  |  |
| `testId` | `string` |  |  |

## NumberInput, DateTimeInput, Popconfirm

Forms. A number field that is empty as null, a date or date-and-time field, and a confirmation beside the button it guards.

```ts
import { NumberInput, DateTimeInput, Popconfirm } from '@kition/tessera-ui'
```

### Example: Price, start time, delete

```tsx
import { useState } from 'react'
import { Button, DateTimeInput, NumberInput, Popconfirm, toast } from '@kition/tessera-ui'

export default function Demo() {
  const [price, setPrice] = useState<number | null>(0.25)
  const [start, setStart] = useState<string | null>('2026-10-25T09:00')
  return (
    <div className="demo-row" style={{ alignItems: 'flex-end' }}>
      <label style={{ display: 'grid', gap: 6 }}>
        Price per call
        <NumberInput value={price} onChange={setPrice} min={0} step={0.05} precision={2} style={{ width: 140 }} />
      </label>
      <label style={{ display: 'grid', gap: 6 }}>
        From
        <DateTimeInput withTime value={start} onChange={setStart} />
      </label>
      <Popconfirm title="Delete this pricing rule?" description="Calls are charged by the default rule afterwards." danger okText="Delete" onConfirm={() => toast('success', 'Rule deleted')}>
        <Button variant="danger">Delete rule</Button>
      </Popconfirm>
    </div>
  )
}
```

### NumberInput props

A field for a number, empty as `null`; arrows step it, and it rounds to `precision` when left.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `number \| null \| ''` |  | Optional inside a `FormItem`, which supplies it. |
| `onChange` | `(value: number \| null) => void` |  |  |
| `min` | `number` |  |  |
| `max` | `number` |  |  |
| `step` | `number` | `1` |  |
| `precision` | `number` |  | Decimals kept when the field is left. |
| `size` | `ControlSize`: `'sm'`, `'md'`, `'lg'` | `'sm'` |  |
| `invalid` | `boolean` |  |  |

Also takes the attributes of its HTML element (`className`, `aria-*`, events).

### DateTimeInput props

A date, or a date and time, from the platform's picker; cleared to `null`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string \| null` |  | Optional inside a `FormItem`, which supplies it. |
| `onChange` | `(value: string \| null) => void` |  |  |
| `withTime` | `boolean` |  | Asks for a time too. |
| `size` | `ControlSize`: `'sm'`, `'md'`, `'lg'` | `'sm'` |  |
| `invalid` | `boolean` |  |  |

Also takes the attributes of its HTML element (`className`, `aria-*`, events).

### Popconfirm props

Asks "are you sure?" next to the button that does something, before it does.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` (required) | `ReactNode` |  |  |
| `description` | `ReactNode` |  |  |
| `onConfirm` (required) | `() => void` |  |  |
| `okText` | `string` |  |  |
| `cancelText` | `string` |  |  |
| `danger` | `boolean` |  | Draws OK as a destructive button. |
| `disabled` | `boolean` |  | Lets the trigger act without asking. |
| `children` (required) | `ReactElement` |  | The button that asks. |

## Table

Data display. Records in rows and columns: columns say what each shows, dataSource holds the records; pages, pinned columns, loading and empty states.

```ts
import { Table, SelectionBar, Pagination } from '@kition/tessera-ui'
```

### When to use

- Lists of orders, users, events: anything scanned and compared row by row.

### When not to

- A spreadsheet the person edits: that is a kit.

### Example: Pages, pinned column, tags

```tsx
import { Table, Tag, type TableColumn } from '@kition/tessera-ui'

type Order = { id: string; customer: string; plan: string; amount: number; status: 'paid' | 'pending' | 'refunded' }

const ORDERS: Order[] = Array.from({ length: 23 }, (_, index) => ({
  id: `ord_${1040 + index}`,
  customer: ['Ada Lovelace', 'Grace Hopper', 'Alan Turing', 'Katherine Johnson'][index % 4],
  plan: index % 3 ? 'Pro' : 'Team',
  amount: 19 + (index % 5) * 10,
  status: (['paid', 'pending', 'refunded'] as const)[index % 3],
}))

const TONES = { paid: 'success', pending: 'warning', refunded: 'neutral' } as const

const columns: TableColumn<Order>[] = [
  { key: 'id', title: 'Order', dataIndex: 'id', width: 120, fixed: 'left' },
  { key: 'customer', title: 'Customer', dataIndex: 'customer', ellipsis: true },
  { key: 'plan', title: 'Plan', dataIndex: 'plan', width: 90 },
  { key: 'amount', title: 'Amount', dataIndex: 'amount', align: 'right', width: 100, render: (amount: number) => `$${amount}.00` },
  { key: 'status', title: 'Status', dataIndex: 'status', width: 110, render: (status: Order['status']) => <Tag tone={TONES[status]}>{status}</Tag> },
]

export default function Demo() {
  return <Table columns={columns} dataSource={ORDERS} rowKey="id" size="small" pagination={{ defaultPageSize: 8, showSizeChanger: true, pageSizeOptions: [8, 16, 32] }} />
}
```

### Example: Selection, row actions, SelectionBar

Row actions show while the pointer is over a row or focus is in it. SelectionBar floats at the bottom of the nearest positioned box; Escape in it clears the selection.

```tsx
import { useState, type Key } from 'react'
import { Button, IconButton, SelectionBar, Table, type TableColumn } from '@kition/tessera-ui'
import { CopyIcon, DownloadIcon, EllipsisIcon, FolderInputIcon, Share2Icon, StarIcon, TrashIcon } from '@kition/tessera-icons/react'

type File = { id: string; name: string; owner: string; modified: string }

const FILES: File[] = [
  { id: 'f1', name: 'Q4 plan.docx', owner: 'Ada', modified: 'Today 10:12' },
  { id: 'f2', name: 'Backlog.ktable', owner: 'Me', modified: 'Today 09:30' },
  { id: 'f3', name: 'Roadmap review.pptx', owner: 'Grace', modified: 'Yesterday' },
  { id: 'f4', name: 'Budget 2026.xlsx', owner: 'Me', modified: 'Yesterday' },
  { id: 'f5', name: 'User research.pdf', owner: 'Alan', modified: 'Oct 28' },
]

const columns: TableColumn<File>[] = [
  { key: 'name', title: 'Name', dataIndex: 'name', ellipsis: true },
  { key: 'owner', title: 'Owner', dataIndex: 'owner', width: 110 },
  { key: 'modified', title: 'Modified', dataIndex: 'modified', width: 140 },
]

export default function Demo() {
  const [selected, setSelected] = useState<Key[]>(['f2'])
  return (
    <div style={{ position: 'relative', minHeight: 360 }}>
      <Table
        columns={columns}
        dataSource={FILES}
        rowKey="id"
        pagination={false}
        rowSelection={{ selectedKeys: selected, onChange: setSelected, rowLabel: (file) => `Select ${file.name}` }}
        rowActions={(file) => (
          <>
            <IconButton icon={Share2Icon} label={`Share ${file.name}`} />
            <IconButton icon={DownloadIcon} label={`Download ${file.name}`} />
            <IconButton icon={StarIcon} label={`Star ${file.name}`} />
            <IconButton icon={EllipsisIcon} label={`More for ${file.name}`} />
          </>
        )}
      />
      <SelectionBar count={selected.length} onClear={() => setSelected([])}>
        <Button variant="ghost" size="sm"><Share2Icon size={16} />Share</Button>
        <Button variant="ghost" size="sm"><DownloadIcon size={16} />Download</Button>
        <Button variant="ghost" size="sm"><FolderInputIcon size={16} />Move</Button>
        <Button variant="ghost" size="sm"><CopyIcon size={16} />Copy</Button>
        <Button variant="ghost" size="sm"><TrashIcon size={16} />Delete</Button>
      </SelectionBar>
    </div>
  )
}
```

### Example: Empty and loading

```tsx
import { useState } from 'react'
import { Button, Empty, Table, type TableColumn } from '@kition/tessera-ui'

type Key = { id: string; name: string }
const columns: TableColumn<Key>[] = [
  { key: 'name', title: 'Name', dataIndex: 'name' },
  { key: 'id', title: 'ID', dataIndex: 'id', width: 160 },
]

export default function Demo() {
  const [loading, setLoading] = useState(false)
  return (
    <div style={{ display: 'grid', gap: 16 }}>
      <Table columns={columns} dataSource={[]} rowKey="id" emptyText={<Empty title="No API keys" description="Create a key to call the API from your own code."><Button size="sm" variant="primary">Create key</Button></Empty>} />
      <Button size="sm" onClick={() => { setLoading(true); setTimeout(() => setLoading(false), 1500) }}>Load for 1.5s</Button>
      <Table columns={columns} dataSource={[{ id: 'key_1', name: 'Build server' }]} rowKey="id" loading={loading} />
    </div>
  )
}
```

### Table props

Records in rows and columns: `columns` say what each shows (`dataIndex`, `render`), `dataSource`
holds the records. Pages through long lists, shows a spinner while loading and `emptyText` when
empty, and can pin columns and the header.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `columns` (required) | `readonly TableColumn<T>[]` |  |  |
| `dataSource` (required) | `readonly T[] \| undefined` |  |  |
| `rowKey` (required) | `string \| ((record: T) => Key)` |  | The field that identifies a record, or a function of it. |
| `loading` | `boolean` |  |  |
| `pagination` | `TablePagination \| false` |  | Pages of `defaultPageSize` rows (10 by default); `false` shows every row. |
| `size` | `'small' \| 'middle'` | `'middle'` | `small`: 36px rows for dense screens; `middle` (default): 44px. |
| `emptyText` | `ReactNode` |  | Shown when there are no rows (an `Empty`). |
| `sticky` | `boolean` |  | Keeps the header in view while the page scrolls. |
| `scrollX` | `number \| string` |  | The table's least width; it scrolls sideways in a narrower container. |
| `onRow` | `(record: T, index: number) => HTMLAttributes<HTMLTableRowElement>` |  |  |
| `rowSelection` | `TableSelection<T>` |  | Selects records with check boxes; selected rows are marked. Pair it with SelectionBar for their actions. |
| `rowActions` | `(record: T, index: number) => ReactNode` |  | A record's actions (icon buttons, a menu), at the row's end while the pointer is over the row or focus is in it. |
| `caption` | `ReactNode` |  | Caption above the table, for its accessible name. |
| `className` | `string` |  |  |
| `testId` | `string` |  |  |

### SelectionBar props

Actions on the selected records, floating at the bottom of the nearest positioned box: the count,
the actions, and a button that clears the selection. With Table's `rowSelection`, it replaces a
row of links on every record.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `count` (required) | `number` |  | How many records are selected; with none the bar is not drawn. |
| `children` (required) | `ReactNode` |  | The actions on the selection: Buttons (`variant="ghost"`) with an icon and a word. |
| `onClear` (required) | `() => void` |  | Clears the selection: the close button, and Escape while focus is in the bar. |
| `className` | `string` |  |  |
| `testId` | `string` |  |  |

### Pagination props

The pages of a long list: the range shown, page buttons, and an optional page size.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `page` (required) | `number` |  |  |
| `pageSize` (required) | `number` |  |  |
| `total` (required) | `number` |  |  |
| `onChange` (required) | `(page: number, pageSize: number) => void` |  |  |
| `pageSizeOptions` | `readonly number[]` |  | Offers these page sizes; without it the size is fixed. |
| `className` | `string` |  |  |

## Tag

Data display. A short status or category label on a soft tint of its tone.

```ts
import { Tag } from '@kition/tessera-ui'
```

### When to use

- A record’s status in a table or header.

### When not to

- A count beside a label: use Badge.

### Example: Tones

```tsx
import { Tag } from '@kition/tessera-ui'

export default function Demo() {
  return (
    <div className="demo-row">
      <Tag>Draft</Tag>
      <Tag tone="info">Processing</Tag>
      <Tag tone="success">Paid</Tag>
      <Tag tone="warning">Pending</Tag>
      <Tag tone="danger">Failed</Tag>
    </div>
  )
}
```

### Tag props

A short status or category label on a soft tint of its tone.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tone` | `Tone`: `'neutral'`, `'info'`, `'success'`, `'warning'`, `'danger'` | `'neutral'` |  |

Also takes the attributes of its HTML element (`className`, `aria-*`, events).

## Alert

Data display. A message in the page, in its tone, with an optional action or close.

```ts
import { Alert } from '@kition/tessera-ui'
```

### When to use

- A state of the account or page the person should know about.

### When not to

- A short confirmation after an action: use a toast.

### Example: Tones, action, close

```tsx
import { useState } from 'react'
import { Alert, Button } from '@kition/tessera-ui'

export default function Demo() {
  const [shown, setShown] = useState(true)
  return (
    <div style={{ display: 'grid', gap: 8 }}>
      <Alert title="Password sign-in is turned off" description="People sign in with GitHub or Google until you turn it back on." />
      <Alert tone="success" title="Credits added" />
      <Alert tone="warning" title="Your plan renews in 3 days" action={<Button size="sm">Manage</Button>} />
      {shown ? <Alert tone="danger" title="The last payment failed" description="Update the card to keep syncing." onClose={() => setShown(false)} /> : null}
    </div>
  )
}
```

### Alert props

A message in the page: what happened or what to know, in its tone, with an optional action.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tone` | `Exclude<Tone, 'neutral'>` | `'info'` |  |
| `title` (required) | `ReactNode` |  |  |
| `description` | `ReactNode` |  |  |
| `action` | `ReactNode` |  | A button or link at the end (Retry, Upgrade). |
| `onClose` | `() => void` |  | Shows a close button that calls it. |
| `className` | `string` |  |  |
| `testId` | `string` |  |  |

## Descriptions

Data display. Labelled values of one record, in columns; with Breadcrumb, Avatar, and Divider for a detail page.

```ts
import { Descriptions, Breadcrumb, Avatar, Divider } from '@kition/tessera-ui'
```

### Example: A user’s detail page

```tsx
import { Avatar, Breadcrumb, Descriptions, Divider, Tag } from '@kition/tessera-ui'

export default function Demo() {
  return (
    <div>
      <Breadcrumb items={[{ title: <a href="#users">Users</a> }, { title: 'Ada Lovelace' }]} />
      <div style={{ display: 'flex', alignItems: 'center', gap: 10, margin: '12px 0' }}>
        <Avatar name="Ada Lovelace" size={36} />
        <strong>Ada Lovelace</strong>
        <Tag tone="success">active</Tag>
      </div>
      <Divider>Account</Divider>
      <Descriptions
        columns={3}
        items={[
          { label: 'Email', children: 'ada@example.com' },
          { label: 'Plan', children: 'Pro (yearly)' },
          { label: 'Credits', children: '12,400' },
          { label: 'Signed up', children: '2026-03-14 09:21' },
          { label: 'Last active', children: '2 hours ago' },
          { label: 'Notes', children: 'Moved from the Team plan after the trial.', span: 3 },
        ]}
      />
    </div>
  )
}
```

### Descriptions props

Labelled values of one record (an order, a user), laid out in `columns` columns.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `readonly DescriptionItem[]` |  |  |
| `columns` | `number` | `3` |  |
| `title` | `ReactNode` |  |  |
| `className` | `string` |  |  |

### Breadcrumb props

Where the page sits: its parents (links in `title`) and then itself.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `readonly BreadcrumbItem[]` |  |  |
| `className` | `string` |  |  |

### Avatar props

A person's picture, or their initial on a tint when there is none.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `src` | `string` |  |  |
| `name` (required) | `string` |  |  |
| `size` | `number` | `28` |  |
| `className` | `string` |  |  |

### Divider props

A hairline between sections, with an optional label in it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` |  |  |
| `className` | `string` |  |  |

## Empty and Result

Data display. Nothing to show yet, and the outcome of a whole page or flow, each with what to do next.

```ts
import { Empty, Result } from '@kition/tessera-ui'
```

### Example: No feedback, access denied

```tsx
import { Button, Empty, Result } from '@kition/tessera-ui'

export default function Demo() {
  return (
    <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 16 }}>
      <Empty title="No feedback yet" description="Messages people send from the app arrive here.">
        <Button size="sm">Refresh</Button>
      </Empty>
      <Result status="forbidden" title="Access denied" description="Your account cannot open the admin console." extra={<Button size="sm" variant="primary">Sign in again</Button>} />
    </div>
  )
}
```

### Empty props

Nothing to show yet: a quiet drawing, what is missing, and what to do about it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `ReactNode` |  |  |
| `description` | `ReactNode` |  |  |
| `image` | `ReactNode` |  | Replaces the inbox drawing (an icon of the situation). |
| `children` | `ReactNode` |  | Actions under the text (Create, Retry). |
| `className` | `string` |  |  |

### Result props

The outcome of a whole page or flow (paid, access denied, page not found), with what to do next.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `status` | `ResultStatus`: `'info'`, `'success'`, `'warning'`, `'error'`, `'forbidden'`, `'notFound'` | `'info'` |  |
| `title` (required) | `ReactNode` |  |  |
| `description` | `ReactNode` |  |  |
| `extra` | `ReactNode` |  |  |
| `className` | `string` |  |  |

## Skeleton

Data display. A placeholder in the shape of content that is loading.

```ts
import { Skeleton } from '@kition/tessera-ui'
```

### Example: Title and paragraph

```tsx
import { Skeleton } from '@kition/tessera-ui'

export default function Demo() {
  return (
    <div style={{ display: 'grid', gap: 12, maxWidth: 360 }}>
      <Skeleton width={180} height={20} />
      <Skeleton lines={3} />
    </div>
  )
}
```

### Skeleton props

A placeholder in the shape of content that is loading; `lines` draws a paragraph. Size it with `width` and `height`, or with classes (16px tall by default).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `width` | `number \| string` |  |  |
| `height` | `number \| string` |  |  |
| `lines` | `number` |  |  |
| `className` | `string` |  |  |

## Charts

Data display. LineChart and BarChart draw one or more series over ordered categories; PieChart draws parts of a whole, as a pie or a donut. A legend, a readout under the pointer, the chart palette tokens or a colour of yours; height="fill" takes the height of its box.

```ts
import { LineChart, BarChart, PieChart } from '@kition/tessera-ui'
```

### Example: Growth by day

```tsx
import { LineChart } from '@kition/tessera-ui'

const days = Array.from({ length: 14 }, (_, index) => `10-${String(index + 10).padStart(2, '0')}`)
const DATA = days.flatMap((date, index) => [
  { date, metric: 'Visitors', value: Math.round(420 + Math.sin(index / 2) * 90 + index * 12) },
  { date, metric: 'Downloads', value: Math.round(120 + Math.cos(index / 3) * 30 + index * 6) },
  { date, metric: 'Sign-ups', value: Math.round(40 + Math.sin(index) * 8 + index * 2) },
])

export default function Demo() {
  return <LineChart label="Growth by day" data={DATA} xField="date" yField="value" seriesField="metric" height={260} />
}
```

### Example: Bars and a donut

```tsx
import { BarChart, PieChart } from '@kition/tessera-ui'

const STAGES = [
  { stage: 'Backlog', tasks: 14 },
  { stage: 'To do', tasks: 9 },
  { stage: 'Doing', tasks: 6 },
  { stage: 'Review', tasks: 4 },
  { stage: 'Done', tasks: 21 },
]

export default function Demo() {
  return (
    <div style={{ display: 'grid', gridTemplateColumns: '3fr 2fr', gap: 24 }}>
      <BarChart label="Tasks by stage" data={STAGES} xField="stage" yField="tasks" height={240} />
      <PieChart label="Share of tasks" data={STAGES} labelField="stage" valueField="tasks" innerRadius={0.6} height={200} />
    </div>
  )
}
```

### LineChart props

Lines of one or more series over ordered categories, with a legend and a hover readout.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` (required) | `readonly T[]` |  |  |
| `xField` (required) | `keyof T & string` |  | The field of each datum on the horizontal axis (categories in order of first appearance). |
| `yField` (required) | `keyof T & string` |  | The field holding the number. |
| `seriesField` | `keyof T & string` |  | The field naming the series a datum belongs to; one series without it. |
| `height` | `ChartHeight` |  |  |
| `color` | `string` |  | The colour of a single series (the palette's first by default). |
| `integers` | `boolean` |  | Counts: the axis steps only by whole numbers. |
| `formatX` | `(value: string) => string` |  |  |
| `formatY` | `(value: number) => string` |  |  |
| `label` (required) | `string` |  | The chart's accessible name. |
| `className` | `string` |  |  |
| `testId` | `string` |  |  |
| `dots` | `boolean` |  | Marks each point with a dot. |

### BarChart props

Bars of one or more series per category, side by side, with rounded tops.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` (required) | `readonly T[]` |  |  |
| `xField` (required) | `keyof T & string` |  | The field of each datum on the horizontal axis (categories in order of first appearance). |
| `yField` (required) | `keyof T & string` |  | The field holding the number. |
| `seriesField` | `keyof T & string` |  | The field naming the series a datum belongs to; one series without it. |
| `height` | `ChartHeight` |  |  |
| `color` | `string` |  | The colour of a single series (the palette's first by default). |
| `integers` | `boolean` |  | Counts: the axis steps only by whole numbers. |
| `formatX` | `(value: string) => string` |  |  |
| `formatY` | `(value: number) => string` |  |  |
| `label` (required) | `string` |  | The chart's accessible name. |
| `className` | `string` |  |  |
| `testId` | `string` |  |  |
| `maxBarWidth` | `number` |  | The widest a bar draws, in px. |

### PieChart props

Parts of a whole as slices of a pie (or a donut), with a legend and a readout of the slice under the pointer.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` (required) | `readonly T[]` |  |  |
| `labelField` (required) | `keyof T & string` |  | The field naming each slice. |
| `valueField` (required) | `keyof T & string` |  | The field holding each slice's number. |
| `height` | `ChartHeight` | `240` |  |
| `innerRadius` | `number` | `0` | The hole's size as a share of the radius (0.6 for a donut); a full pie by default. |
| `colors` | `readonly string[]` |  | Colours for the slices, in order; the chart palette by default. |
| `formatValue` | `(value: number) => string` | `(value) => value.toLocaleString()` |  |
| `label` (required) | `string` |  | The chart's accessible name. |
| `className` | `string` |  |  |
| `testId` | `string` |  |  |

## Tabs

Navigation. Sections of one page under a row of tabs; arrow keys move between them.

```ts
import { Tabs } from '@kition/tessera-ui'
```

### When not to

- Two or three views of the same data: use Segmented.

### Keyboard

| Keys | What they do |
| --- | --- |
| Left, Right | Open the previous or the next tab, wrapping at the ends; disabled tabs are skipped. |
| Home, End | Open the first or the last tab. |

### Example: With a range control

```tsx
import { Segmented, Tabs } from '@kition/tessera-ui'
import { useState } from 'react'

export default function Demo() {
  const [range, setRange] = useState<'24h' | '7d' | '30d'>('7d')
  return (
    <Tabs
      extra={<Segmented label="Range" value={range} onChange={setRange} segments={[{ value: '24h', label: '24h' }, { value: '7d', label: '7d' }, { value: '30d', label: '30d' }]} />}
      items={[
        { key: 'usage', label: 'Usage', children: `Generations in the last ${range}.` },
        { key: 'ledger', label: 'Credit ledger', children: 'Every credit added and spent.' },
        { key: 'keys', label: 'API keys', children: 'Keys this account created.' },
        { key: 'audit', label: 'Audit log', disabled: true },
      ]}
    />
  )
}
```

### Tabs props

Sections of one page under a row of tabs; arrow keys move between tabs.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `readonly TabItem[]` |  |  |
| `activeKey` | `string` |  | The open tab, when the screen holds it (with `onChange`); otherwise `defaultActiveKey` or the first. |
| `defaultActiveKey` | `string` |  |  |
| `onChange` | `(key: string) => void` |  |  |
| `extra` | `ReactNode` |  | Content at the end of the tab row (a filter, an action). |
| `className` | `string` |  |  |
| `testId` | `string` |  |  |

## AppRail

Navigation. A suite’s app switcher on the left edge: each app’s icon over its name, the open one marked, badges, the product mark above and the account below; compact shows icons only, each name as its tooltip.

```ts
import { AppRail } from '@kition/tessera-ui'
```

### When to use

- A product made of several apps (home, docs, wiki, inbox), each with its own sidebar.

### When not to

- The pages of one app: use NavMenu.
- Kinds of file: filter a list by kind instead.

### Example: Apps beside an app’s sidebar

```tsx
import { useState } from 'react'
import { AppRail, Avatar, IconButton, NavMenu, Switch } from '@kition/tessera-ui'
import { BookOpenIcon, ClockIcon, FolderIcon, InboxIcon, LayoutDashboardIcon, SettingsIcon, SparklesIcon, StarIcon, UsersIcon } from '@kition/tessera-icons/react'

export default function Demo() {
  const [app, setApp] = useState('docs')
  const [compact, setCompact] = useState(false)
  const go = (set: (key: string) => void) => (href: string, props: React.AnchorHTMLAttributes<HTMLAnchorElement> & { children: React.ReactNode }) => (
    <a href={href} {...props} onClick={(event) => { event.preventDefault(); set(href.slice(1)) }} />
  )
  return (
    <div style={{ display: 'flex', height: 460, border: '1px solid var(--kit-border)', borderRadius: 'var(--kit-radius-card)', overflow: 'hidden' }}>
      <AppRail
        label="Apps"
        compact={compact}
        selectedKey={app}
        renderLink={go(setApp)}
        header={<div style={{ width: 32, height: 32, borderRadius: 8, background: 'var(--kit-primary)' }} />}
        footer={
          <>
            <IconButton icon={SettingsIcon} label="Settings" />
            <Avatar name="Ada Lovelace" size={28} />
          </>
        }
        items={[
          { key: 'home', label: 'Home', icon: LayoutDashboardIcon, href: '#home' },
          { key: 'docs', label: 'Docs', icon: FolderIcon, href: '#docs' },
          { key: 'wiki', label: 'Wiki', icon: BookOpenIcon, href: '#wiki' },
          { key: 'inbox', label: 'Inbox', icon: InboxIcon, href: '#inbox', badge: 3 },
          { key: 'ai', label: 'AI', icon: SparklesIcon, href: '#ai' },
        ]}
      />
      <div style={{ width: 220, padding: 8, borderRight: '1px solid var(--kit-border)' }}>
        <NavMenu
          label="Docs"
          selectedKey="mine"
          items={[
            { key: 'recent', label: 'Recent', icon: ClockIcon, href: '#recent' },
            { key: 'mine', label: 'My files', icon: FolderIcon, href: '#mine' },
            { key: 'shared', label: 'Shared with me', icon: UsersIcon, href: '#shared', badge: 2 },
            { key: 'starred', label: 'Starred', icon: StarIcon, href: '#starred' },
          ]}
        />
      </div>
      <div style={{ flex: 1, padding: 16, color: 'var(--kit-text-muted)' }}>
        <label style={{ display: 'inline-flex', gap: 8, alignItems: 'center' }}><Switch checked={compact} onCheckedChange={setCompact} /> Icons only</label>
        <p>The {app} app</p>
      </div>
    </div>
  )
}
```

### AppRail props

A suite's app switcher: a narrow rail on the left edge with each app's icon over its name, the
open one marked, a badge on an icon, the product mark above and the account below. Each app has
its own sidebar (NavMenu) beside the rail.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `readonly AppRailItem[]` |  | The suite's apps, top to bottom. |
| `selectedKey` | `string` |  | The open app's key. |
| `header` | `ReactNode` |  | Above the apps: the product mark. |
| `footer` | `ReactNode` |  | At the bottom: settings, the account. |
| `compact` | `boolean` |  | Icons only: each app's name becomes its tooltip, and stays its accessible name. |
| `renderLink` | `(href: string, props: AnchorHTMLAttributes<HTMLAnchorElement> & { children: ReactNode }) => ReactNode` |  | Draws a link; a router passes its own (`<Link to={href} … />`). A plain `<a>` by default. |
| `label` (required) | `string` |  |  |
| `className` | `string` |  |  |

## NavMenu

Navigation. An app’s sidebar: its pages as links under headings, the current one marked; collapses to icons.

```ts
import { NavMenu } from '@kition/tessera-ui'
```

### Example: Admin sidebar

```tsx
import { useState } from 'react'
import { NavMenu, Switch } from '@kition/tessera-ui'
import { CreditCardIcon, KeyRoundIcon, LayoutDashboardIcon, MessageSquareIcon, UsersIcon } from '@kition/tessera-icons/react'

export default function Demo() {
  const [selected, setSelected] = useState('users')
  const [collapsed, setCollapsed] = useState(false)
  return (
    <div style={{ display: 'flex', gap: 24, alignItems: 'flex-start' }}>
      <div style={{ width: collapsed ? 52 : 220, padding: 8, borderRight: '1px solid var(--kit-border)' }}>
        <NavMenu
          label="Admin"
          selectedKey={selected}
          collapsed={collapsed}
          renderLink={(href, props) => <a href={href} {...props} onClick={(event) => { event.preventDefault(); setSelected(href.slice(1)) }} />}
          items={[
            { key: 'overview', label: 'Overview', icon: LayoutDashboardIcon, href: '#overview' },
            { key: 'people', label: 'People', items: [{ key: 'users', label: 'Users', icon: UsersIcon, href: '#users', badge: 1284 }, { key: 'feedback', label: 'Feedback', icon: MessageSquareIcon, href: '#feedback' }] },
            { key: 'billing', label: 'Billing', items: [{ key: 'orders', label: 'Orders', icon: CreditCardIcon, href: '#orders' }, { key: 'keys', label: 'API keys', icon: KeyRoundIcon, href: '#keys' }] },
          ]}
        />
      </div>
      <label style={{ display: 'inline-flex', gap: 8, alignItems: 'center' }}>
        <Switch checked={collapsed} onCheckedChange={setCollapsed} /> Collapsed
      </label>
    </div>
  )
}
```

### NavMenu props

An app's sidebar: its pages as links, grouped under headings, the current one marked.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `readonly (NavItem \| NavGroup)[]` |  | Pages, or groups of pages under a heading. |
| `selectedKey` | `string` |  | The current page's key. |
| `collapsed` | `boolean` |  | Icons only, each page's label in its tooltip (a collapsed sidebar). |
| `renderLink` | `(href: string, props: AnchorHTMLAttributes<HTMLAnchorElement> & { children: ReactNode }) => ReactNode` |  | Draws a link; a router passes its own (`<Link to={href} … />`). A plain `<a>` by default. |
| `label` (required) | `string` |  |  |
| `className` | `string` |  |  |

## Pagination

Navigation. The pages of a long list on the server: the range shown, page buttons, and a page size.

```ts
import { Pagination } from '@kition/tessera-ui'
```

### When to use

- A list the server pages; Table pages its own rows.

### Example: Page 6 of 57

```tsx
import { useState } from 'react'
import { Pagination } from '@kition/tessera-ui'

export default function Demo() {
  const [page, setPage] = useState(6)
  const [size, setSize] = useState(20)
  return <Pagination page={page} pageSize={size} total={1137} pageSizeOptions={[20, 50, 100]} onChange={(next, pageSize) => { setPage(next); setSize(pageSize) }} />
}
```

### Pagination props

The pages of a long list: the range shown, page buttons, and an optional page size.

## MenuButton

Menus and overlays. A button that opens a menu of MenuItems, with shortcuts and check marks.

```ts
import { MenuButton, MenuItem, MenuSeparator } from '@kition/tessera-ui'
```

### Example: Edit menu

```tsx
import { useState } from 'react'
import { Button, MenuButton, MenuItem, MenuSeparator, toast } from '@kition/tessera-ui'
import { ClipboardPasteIcon, CopyIcon, ScissorsIcon } from '@kition/tessera-icons/react'

export default function Demo() {
  const [snap, setSnap] = useState(true)
  return (
    <MenuButton trigger={({ toggle }) => <Button onClick={toggle}>Edit ▾</Button>}>
      <MenuItem icon={ScissorsIcon} label="Cut" shortcut="⌘X" onSelect={() => toast('info', 'Cut')} />
      <MenuItem icon={CopyIcon} label="Copy" shortcut="⌘C" onSelect={() => toast('info', 'Copy')} />
      <MenuItem icon={ClipboardPasteIcon} label="Paste" shortcut="⌘V" onSelect={() => toast('info', 'Paste')} />
      <MenuSeparator />
      <MenuItem label="Snap to grid" checked={snap} onSelect={() => setSnap(!snap)} />
    </MenuButton>
  )
}
```

### MenuButton props

A button that opens a menu below it; the menu takes the focus, and gives it back to the button
when it closes. With `placement` `auto` (a button along a panel's bottom), the menu opens above
the button when it does not fit below and there is more room above.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `trigger` (required) | `(props: { open: boolean; toggle: () => void }) => ReactNode` |  |  |
| `children` (required) | `ReactNode` |  |  |
| `align` | `'start' \| 'end'` | `'start'` |  |
| `placement` | `'below' \| 'auto'` | `'below'` |  |

### MenuItem props

A menu row. With `checked` set (true or false) it is a toggle: a check mark shows in the icon's
place while it is on (the state wins over the icon), and assistive technology hears it as a
checkbox item.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `IconComponent` |  |  |
| `label` (required) | `string` |  |  |
| `shortcut` | `string \| null` |  |  |
| `onSelect` (required) | `() => void` |  |  |
| `disabled` | `boolean` |  |  |
| `checked` | `boolean` |  |  |
| `testId` | `string` |  |  |
| `uiId` | `string` |  |  |

### MenuSeparator props

## ContextMenu

Menus and overlays. A menu at a point, for right-clicks.

```ts
import { ContextMenu } from '@kition/tessera-ui'
```

### Example: Right-click

```tsx
import { useState } from 'react'
import { ContextMenu, MenuItem, type ContextMenuPoint } from '@kition/tessera-ui'
import { CopyIcon, TrashIcon } from '@kition/tessera-icons/react'

export default function Demo() {
  const [at, setAt] = useState<ContextMenuPoint | null>(null)
  return (
    <>
      <div
        className="demo-target"
        onContextMenu={(event) => {
          event.preventDefault()
          setAt({ x: event.clientX, y: event.clientY })
        }}
      >
        Right-click here
      </div>
      <ContextMenu at={at} onClose={() => setAt(null)} label="Layer">
        <MenuItem icon={CopyIcon} label="Duplicate layer" onSelect={() => setAt(null)} />
        <MenuItem icon={TrashIcon} label="Delete layer" onSelect={() => setAt(null)} />
      </ContextMenu>
    </>
  )
}
```

### ContextMenu props

A menu at a point (a row's right-click menu): open while `at` is set, kept inside the window,
its first row focused (Up, Down, Home, and End move through the rows; the focus goes back where
it was when it closes), and closed through
`onClose` by a press outside it, Escape, or a choice in it (a `MenuItem`, any button). Its rows
are `MenuItem`s and `MenuSeparator`s, as in `MenuButton`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `at` (required) | `ContextMenuPoint \| null` |  |  |
| `onClose` (required) | `() => void` |  |  |
| `label` | `string` |  |  |
| `children` (required) | `ReactNode` |  |  |
| `testId` | `string` |  |  |

## Dialog

Menus and overlays. A modal (or modeless) dialog with a title, content, and actions; it traps focus and closes on Escape.

```ts
import { Dialog } from '@kition/tessera-ui'
```

### When to use

- A short task that needs values before it runs.

### When not to

- Long forms: use a panel or a page.

### Example: Image size

```tsx
import { useState } from 'react'
import { Button, Dialog, NumberField } from '@kition/tessera-ui'

export default function Demo() {
  const [open, setOpen] = useState(false)
  const [width, setWidth] = useState(1920)
  return (
    <>
      <Button onClick={() => setOpen(true)}>Image size…</Button>
      {open ? (
        <Dialog
          title="Image size"
          onClose={() => setOpen(false)}
          actions={
            <>
              <Button onClick={() => setOpen(false)}>Cancel</Button>
              <Button variant="primary" onClick={() => setOpen(false)}>OK</Button>
            </>
          }
        >
          <NumberField label="Width" value={width} min={1} max={10000} unit="px" onChange={(value) => setWidth(value)} />
        </Dialog>
      ) : null}
    </>
  )
}
```

### Dialog props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` (required) | `string` |  |  |
| `children` (required) | `ReactNode` |  |  |
| `actions` (required) | `ReactNode` |  |  |
| `onClose` (required) | `() => void` |  |  |
| `onEscape` | `(event: KeyboardEvent) => void` |  | Called for Escape in place of `onClose` (a dialog that lets a field keep its own Escape). |
| `modal` | `boolean` | `true` | Blocks the page behind a backdrop (the default), where a press outside closes it. With `false` the page stays usable: no backdrop, and the editor keeps its keys. |
| `uiId` | `string` |  |  |
| `testId` | `string` |  |  |
| `position` | `{ x: number; y: number } \| null` |  | Where the dialog's top left sits in the window (with `onMove`); null or absent: where the layout puts it. |
| `onMove` | `(position: { x: number; y: number }) => void` |  | Makes the dialog movable by its title: a drag moves it, and its place is reported once, on release (keep it, and give it back as `position`). Absent, the title does not move it. |

## PreviewDialog

Menus and overlays. A dialog whose values preview live in the document: the kit supplies begin, update and end.

```ts
import { PreviewDialog } from '@kition/tessera-ui'
```

### When to use

- Filters and adjustments (blur, levels) people tune by eye.

### Example: A filter

```tsx
import { useState } from 'react'
import { Button, GradientSlider, PreviewDialog } from '@kition/tessera-ui'

// A dialog whose changes preview live in the document; the kit supplies begin, update and end.
export default function Demo() {
  const [open, setOpen] = useState(false)
  const [amount, setAmount] = useState(40)
  return (
    <>
      <Button onClick={() => setOpen(true)}>Gaussian Blur…</Button>
      {open ? (
        <PreviewDialog
          title="Gaussian Blur"
          preview={{ begin: () => undefined, update: () => undefined, end: () => undefined, draft: amount }}
          onOk={() => setOpen(false)}
          onCancel={() => setOpen(false)}
          onReset={() => setAmount(40)}
        >
          <GradientSlider label="Radius" value={amount} min={0} max={250} onChange={(value) => setAmount(value)} />
        </PreviewDialog>
      ) : null}
    </>
  )
}
```

### PreviewDialog props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` (required) | `string` |  |  |
| `preview` | `PreviewDialogPreview` |  | Shows the Preview check box (on at first) when given; without it the dialog behaves as `Dialog`. |
| `okLabel` | `string` |  |  |
| `okDisabled` | `boolean` | `false` |  |
| `hideOk` | `boolean` | `false` | Draws no OK: one button (Cancel, named by `cancelLabel`) for a dialog that only shows information. |
| `onOk` (required) | `() => Promise<void> \| void` |  | Runs the command. The dialog does not close itself: once this resolves, the kit unmounts it (unless `keepOpen`). A failure shows in the dialog and leaves it open, previewing again. |
| `onCancel` (required) | `() => void` |  | Cancel, Escape, or a press outside (when modal). The kit unmounts the dialog. Not while OK runs. |
| `cancelLabel` | `string` |  | The Cancel button's label ("Done" in upstream's Find, "Close" for information). |
| `onReset` | `() => void` |  | Alt turns Cancel into Reset, which calls this (restores the dialog's defaults). |
| `keepOpen` | `boolean` | `false` | OK runs without closing, and the preview stays open (upstream's Find). |
| `modal` | `boolean` | `true` | Blocks the page (the default). With `false` there is no backdrop: a press outside does not cancel, Tab may leave the dialog, and the editor keeps its keys (to move the playhead under a picture preview). Escape still cancels. |
| `children` (required) | `ReactNode` |  |  |
| `uiId` | `string` |  | The dialog's Kit UI id. |
| `ids` | `{ ok?: string; cancel?: string; preview?: string }` |  | The buttons' Kit UI ids; Reset is the Cancel button. |
| `testId` | `string` | `'preview-dialog'` |  |
| `position` | `{ x: number; y: number } \| null` |  | Where the dialog sits (with `onMove`), as `Dialog`'s; absent: where the layout puts it. |
| `onMove` | `(position: { x: number; y: number }) => void` |  | Makes the dialog movable by its title, as `Dialog`'s (a kit keeps the place); absent, it does not move. |

## Toast

Menus and overlays. A short notice at the top. Render Toaster once; call toast() or toast.success(), .error(), .loading(), .promise() anywhere, with an id to replace a notice and an action button.

```ts
import { Toaster } from '@kition/tessera-ui'
```

### Example: Levels

```tsx
import { Button, toast } from '@kition/tessera-ui'

// Render <Toaster /> once near the root of the editor; toast() can then be called from anywhere.
export default function Demo() {
  return (
    <div className="demo-row">
      <Button onClick={() => toast('success', 'Saved', 'Budget 2027.xlsx')}>Success</Button>
      <Button onClick={() => toast('info', 'Agent is working', 'Rewriting slide 3')}>Info</Button>
      <Button onClick={() => toast('error', 'Could not save', 'The disk is full')}>Error</Button>
    </div>
  )
}
```

### Example: Actions, promises, sticky notices

```tsx
import { Button, toast } from '@kition/tessera-ui'

const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))

export default function Demo() {
  return (
    <div className="demo-row">
      <Button onClick={() => toast.info('Row deleted', { action: { label: 'Undo', onClick: () => toast.success('Row restored') } })}>With an action</Button>
      <Button onClick={() => void toast.promise(wait(1500).then(() => 3), { loading: 'Exporting…', success: (count) => `Exported ${count} files`, error: 'Export failed' })}>A promise</Button>
      <Button onClick={() => toast.error('Offline', { id: 'network', duration: Number.POSITIVE_INFINITY, description: 'Changes are kept until you reconnect.' })}>Sticky</Button>
      <Button variant="ghost" onClick={() => toast.dismiss()}>Dismiss all</Button>
    </div>
  )
}
```

### Toaster props

Where notices appear: centred at the top, `offset` px down (below a host's tab strip).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `offset` | `number` | `12` |  |
| `closeButton` | `boolean` | `true` |  |

## Modal

Menus and overlays. A composable modal dialog for host apps: header, content, footer; it traps focus and closes on Escape or an outside press.

```ts
import { Modal, ModalContent, ModalHeader, ModalTitle, ModalDescription, ModalBody, ModalFooter, ModalCloseButton } from '@kition/tessera-ui'
```

### When to use

- Confirming details or collecting a few values in an app (rename, share, create).

### When not to

- A kit tool’s settings: use Dialog.
- Editing beside the work: use Sheet.

### Example: Rename

```tsx
import { useState } from 'react'
import { Button, Field, Modal, ModalContent, ModalDescription, ModalFooter, ModalHeader, ModalTitle, TextInput } from '@kition/tessera-ui'

export default function Demo() {
  const [open, setOpen] = useState(false)
  const [name, setName] = useState('Quarterly plan')
  return (
    <>
      <Button variant="secondary" size="md" onClick={() => setOpen(true)}>Rename…</Button>
      <Modal open={open} onOpenChange={setOpen}>
        <ModalContent size="sm">
          <ModalHeader>
            <ModalTitle>Rename document</ModalTitle>
            <ModalDescription>The name shows in the tab and the file tree.</ModalDescription>
          </ModalHeader>
          <Field label="Name">{({ id }) => <TextInput id={id} size="lg" value={name} onChange={(event) => setName(event.target.value)} />}</Field>
          <ModalFooter>
            <Button variant="secondary" size="md" onClick={() => setOpen(false)}>Cancel</Button>
            <Button variant="primary" size="md" onClick={() => setOpen(false)}>Rename</Button>
          </ModalFooter>
        </ModalContent>
      </Modal>
    </>
  )
}
```

### Example: A long dialog

With `fixed` the header and footer stay put and ModalBody scrolls; a ModalCloseButton of your own can be disabled while work runs.

```tsx
import { useState } from 'react'
import { Button, Modal, ModalBody, ModalCloseButton, ModalContent, ModalFooter, ModalHeader, ModalTitle } from '@kition/tessera-ui'

export default function Demo() {
  const [open, setOpen] = useState(false)
  const [running, setRunning] = useState(false)
  return (
    <>
      <Button variant="secondary" size="md" onClick={() => setOpen(true)}>Import file…</Button>
      <Modal open={open} onOpenChange={(next) => (running ? undefined : setOpen(next))}>
        <ModalContent size="xl" fixed hideClose>
          <ModalHeader>
            <ModalTitle>Import a file</ModalTitle>
          </ModalHeader>
          <ModalBody>
            {Array.from({ length: 24 }, (_, i) => (
              <p key={i} style={{ margin: 0, fontSize: 14 }}>Column {i + 1}: text</p>
            ))}
          </ModalBody>
          <ModalFooter>
            <Button variant="ghost" size="md" disabled={running} onClick={() => setOpen(false)}>Cancel</Button>
            <Button
              variant="primary"
              size="md"
              loading={running}
              onClick={() => {
                setRunning(true)
                setTimeout(() => {
                  setRunning(false)
                  setOpen(false)
                }, 1200)
              }}
            >
              Import
            </Button>
          </ModalFooter>
          <ModalCloseButton disabled={running} />
        </ModalContent>
      </Modal>
    </>
  )
}
```

### Modal props

A modal dialog. Controlled with `open` and `onOpenChange`; Escape and an outside press close it.

Also takes the attributes of its HTML element (`className`, `aria-*`, events).

### ModalContent props

The dialog's panel, over a dimmed page: 12px radius, a hairline, the modal shadow.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `ModalSize`: `'sm'`, `'md'`, `'lg'`, `'none'`, `'xs'`, `'xl'`, `'2xl'`, `'3xl'`, `'4xl'` | `'lg'` | Its widest: `xs` 320px to `4xl` 896px; `none` leaves the width to `className`. |
| `hideClose` | `boolean` |  | No close button in the corner (the footer has its own way out). |
| `dismissible` | `boolean` | `true` | When false, an outside press does not close it (Escape still does). |
| `disableAutoFocus` | `boolean` |  | Keeps focus where it was instead of moving it into the dialog when it opens. |
| `fixed` | `boolean` |  | A long dialog: the header and footer stay put with hairlines, and `ModalBody` scrolls between them. |

Also takes the attributes of its HTML element (`className`, `aria-*`, events).

### ModalHeader props

The title and description at the top of a modal.

Also takes the attributes of its HTML element (`className`, `aria-*`, events).

### ModalTitle props

Also takes the attributes of its HTML element (`className`, `aria-*`, events).

### ModalDescription props

Also takes the attributes of its HTML element (`className`, `aria-*`, events).

### ModalBody props

The content between a modal's header and footer; it scrolls in a `fixed` modal.

Also takes the attributes of its HTML element (`className`, `aria-*`, events).

### ModalFooter props

The actions at the bottom of a modal, right-aligned; full width on a narrow window.

Also takes the attributes of its HTML element (`className`, `aria-*`, events).

### ModalCloseButton props

The close button in a modal's corner. ModalContent draws one; with `hideClose`, place your own,
for one you can disable (`disabled` while an import runs).

Also takes the attributes of its HTML element (`className`, `aria-*`, events).

## Tooltip

Menus and overlays. A short label shown on hover or keyboard focus, for an icon or a status that needs a word.

```ts
import { Tooltip, TooltipProvider, TooltipContent } from '@kition/tessera-ui'
```

### When to use

- Naming an icon-only control.
- Explaining a status mark (an error in a cell).

### When not to

- Anything the person must read to act: put it on the page.

### Example: Icon and button

```tsx
import { Button, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@kition/tessera-ui'
import { CircleAlertIcon } from '@kition/tessera-icons/react'

export default function Demo() {
  return (
    <TooltipProvider>
      <div className="demo-row">
        <Tooltip>
          <TooltipTrigger asChild>
            <Button variant="ghost" size="sm" iconOnly aria-label="Invalid value">
              <CircleAlertIcon />
            </Button>
          </TooltipTrigger>
          <TooltipContent>The value is not a date</TooltipContent>
        </Tooltip>
        <Tooltip>
          <TooltipTrigger asChild>
            <Button variant="secondary" size="sm">Hover or focus me</Button>
          </TooltipTrigger>
          <TooltipContent side="bottom">Tooltips name a control; they never hold the only copy of something.</TooltipContent>
        </Tooltip>
      </div>
    </TooltipProvider>
  )
}
```

### Tooltip props

A short label shown on hover or keyboard focus. Works on its own; a TooltipProvider above it shares one delay among several.

Also takes the attributes of its HTML element (`className`, `aria-*`, events).

### TooltipProvider props

Shares one hover delay among the tooltips inside it (`delayDuration`, 200 ms by default), so moving between them skips the wait.

Also takes the attributes of its HTML element (`className`, `aria-*`, events).

### TooltipContent props

The tooltip's bubble: dark, small, above the page.

Also takes the attributes of its HTML element (`className`, `aria-*`, events).

## Popover

Menus and overlays. Floating content anchored to a trigger, positioned to stay on screen: filters, pickers, small forms.

```ts
import { Popover, PopoverContent } from '@kition/tessera-ui'
```

### When to use

- Filter, sort, and group controls of a table.
- A picker under a button.

### When not to

- A list of commands: use MenuButton.

### Example: A filter

```tsx
import { Button, Popover, PopoverContent, PopoverTrigger, Select, Switch } from '@kition/tessera-ui'
import { FunnelIcon } from '@kition/tessera-icons/react'

export default function Demo() {
  return (
    <Popover>
      <PopoverTrigger asChild>
        <Button variant="secondary" size="sm">
          <FunnelIcon /> Filter
        </Button>
      </PopoverTrigger>
      <PopoverContent align="start">
        <div style={{ display: 'grid', gap: 12, padding: 14 }}>
          <strong style={{ fontSize: 13 }}>Show records where</strong>
          <Select size="md" defaultValue="open">
            <option value="open">Status is Open</option>
            <option value="done">Status is Done</option>
          </Select>
          <label style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between', fontSize: 13 }}>
            Include archived <Switch aria-label="Include archived" />
          </label>
        </div>
      </PopoverContent>
    </Popover>
  )
}
```

### Popover props

Floating content anchored to a trigger: filters, pickers, small forms.

Also takes the attributes of its HTML element (`className`, `aria-*`, events).

### PopoverContent props

The popover's panel: 12px radius, a hairline, the floating shadow; 288px wide unless `className` says otherwise.

Also takes the attributes of its HTML element (`className`, `aria-*`, events).

## Sheet

Menus and overlays. A panel that slides in from the right to edit one thing beside the work, guarding unsaved changes; from the left, it holds an app’s navigation on a phone.

```ts
import { Sheet } from '@kition/tessera-ui'
```

### When to use

- Editing a record’s field, a connection, a rule.

### When not to

- A quick question: use Modal or Confirm.

### Example: Edit a field

With unsaved changes, Escape, the backdrop, and the close button ask first.

```tsx
import { useState } from 'react'
import { Button, Field, Sheet, TextInput } from '@kition/tessera-ui'

export default function Demo() {
  const [open, setOpen] = useState(false)
  const [label, setLabel] = useState('Status')
  const [saved, setSaved] = useState('Status')
  const dirty = label !== saved
  return (
    <>
      <Button variant="secondary" size="md" onClick={() => setOpen(true)}>Edit field…</Button>
      <Sheet
        open={open}
        title="Edit field"
        dirty={dirty}
        onRequestClose={() => {
          if (window.confirm('Discard your changes?')) {
            setLabel(saved)
            setOpen(false)
          }
        }}
        onClose={() => setOpen(false)}
        footer={
          <>
            <Button variant="secondary" size="md" onClick={() => setOpen(false)}>Close</Button>
            <Button variant="primary" size="md" disabled={!dirty} onClick={() => setSaved(label)}>Save</Button>
          </>
        }
      >
        <Field label="Field name">{({ id }) => <TextInput id={id} size="lg" value={label} onChange={(event) => setLabel(event.target.value)} />}</Field>
      </Sheet>
    </>
  )
}
```

### Sheet props

A panel that slides in from the right over a dimmed page, for editing one thing beside the work.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` (required) | `boolean` |  |  |
| `onClose` (required) | `() => void` |  |  |
| `title` (required) | `ReactNode` |  |  |
| `children` (required) | `ReactNode` |  |  |
| `footer` | `ReactNode` |  | Actions at the bottom, right-aligned. |
| `dirty` | `boolean` | `false` | With unsaved changes, closing (Escape, the backdrop, the close button) calls `onRequestClose` instead. |
| `onRequestClose` | `() => void` |  |  |
| `width` | `number` | `400` | Its width in pixels. |
| `label` | `string` |  | Its accessible name, when `title` is not plain text (a logo and a name). |
| `side` | `'left' \| 'right'` | `'right'` | The edge it slides in from: `right` (default, editing beside the work) or `left` (an app's navigation on a phone). |
| `testId` | `string` | `'sheet'` | Test id of the sheet; its parts take `${testId}-backdrop`, `-header`, `-close`, `-footer`. |

## Confirm

Menus and overlays. `useConfirm()` asks a yes-or-no question and resolves a promise; asks queue one at a time.

```ts
import { ConfirmProvider } from '@kition/tessera-ui'
```

### When to use

- Before deleting or discarding.

### When not to

- Questions with more than two answers: use Modal.

### Example: Delete

A danger confirm puts focus on Cancel.

```tsx
import { useState } from 'react'
import { Button, ConfirmProvider, useConfirm } from '@kition/tessera-ui'

function DeleteButton() {
  const confirm = useConfirm()
  const [result, setResult] = useState('')
  return (
    <div className="demo-row">
      <Button
        variant="danger"
        size="md"
        onClick={async () => {
          const ok = await confirm({ title: 'Delete this table?', message: 'Its 240 records go to the trash for 30 days.', confirmLabel: 'Delete', variant: 'danger' })
          setResult(ok ? 'Deleted' : 'Kept')
        }}
      >
        Delete table
      </Button>
      <span>{result}</span>
    </div>
  )
}

export default function Demo() {
  return (
    <ConfirmProvider>
      <DeleteButton />
    </ConfirmProvider>
  )
}
```

### ConfirmProvider props

Lets `useConfirm` ask from anywhere inside it; asks queue and show one at a time.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` |  |  |

## Command

Menus and overlays. A searchable list of commands or choices: type to filter, arrows and Enter to pick.

```ts
import { Command, CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandSeparator, CommandShortcut } from '@kition/tessera-ui'
```

### When to use

- A command palette, a searchable picker inside a popover.

### Example: A command palette

```tsx
import { Command, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandSeparator, CommandShortcut, toast } from '@kition/tessera-ui'
import { FileTextIcon, SettingsIcon, TableIcon } from '@kition/tessera-icons/react'

export default function Demo() {
  const run = (name: string) => toast('info', name)
  return (
    <div style={{ width: 'min(100%, 420px)', border: '1px solid var(--kit-border)', borderRadius: 12, background: 'var(--kit-surface)' }}>
      <Command>
        <CommandInput placeholder="Type a command…" />
        <CommandList>
          <CommandEmpty>No matching command.</CommandEmpty>
          <CommandGroup heading="Create">
            <CommandItem onSelect={() => run('New document')}>
              <FileTextIcon size={16} /> New document <CommandShortcut>⌘N</CommandShortcut>
            </CommandItem>
            <CommandItem onSelect={() => run('New table')}>
              <TableIcon size={16} /> New table
            </CommandItem>
          </CommandGroup>
          <CommandSeparator />
          <CommandGroup heading="App">
            <CommandItem onSelect={() => run('Settings')}>
              <SettingsIcon size={16} /> Settings <CommandShortcut>⌘,</CommandShortcut>
            </CommandItem>
          </CommandGroup>
        </CommandList>
      </Command>
    </div>
  )
}
```

### Command props

A searchable list of commands or choices (cmdk): type to filter, arrows and Enter to pick.

Also takes the attributes of its HTML element (`className`, `aria-*`, events).

### CommandInput props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `wrapClassName` | `string` |  |  |

Also takes the attributes of its HTML element (`className`, `aria-*`, events).

### CommandList props

Also takes the attributes of its HTML element (`className`, `aria-*`, events).

### CommandEmpty props

Also takes the attributes of its HTML element (`className`, `aria-*`, events).

### CommandGroup props

Also takes the attributes of its HTML element (`className`, `aria-*`, events).

### CommandItem props

Also takes the attributes of its HTML element (`className`, `aria-*`, events).

### CommandSeparator props

Also takes the attributes of its HTML element (`className`, `aria-*`, events).

### CommandShortcut props

A shortcut at the end of a command item.

Also takes the attributes of its HTML element (`className`, `aria-*`, events).

## DropPanel

Menus and overlays. A popover anchored to an element, closing on a press outside or Escape.

```ts
import { DropPanel } from '@kition/tessera-ui'
```

### Example: A setting under a button

```tsx
import { useRef, useState } from 'react'
import { Button, DropPanel, NumberField } from '@kition/tessera-ui'

export default function Demo() {
  const anchor = useRef<HTMLSpanElement>(null)
  const [open, setOpen] = useState(false)
  const [radius, setRadius] = useState(8)
  return (
    <span ref={anchor}>
      <Button onClick={() => setOpen(!open)}>Corner radius ▾</Button>
      <DropPanel open={open} anchor={anchor} onClose={() => setOpen(false)} label="Corner radius">
        <div style={{ padding: 12, width: 220 }}>
          <NumberField label="Radius" value={radius} min={0} max={64} unit="px" onChange={(value) => setRadius(value)} />
        </div>
      </DropPanel>
    </span>
  )
}
```

### DropPanel props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` (required) | `boolean` |  |  |
| `anchor` (required) | `RefObject<HTMLElement \| null>` |  |  |
| `onClose` (required) | `() => void` |  |  |
| `label` (required) | `string` |  |  |
| `className` | `string` | `''` |  |
| `testId` | `string` |  |  |
| `children` (required) | `ReactNode` |  |  |

## Scrollbar

Editor chrome. A persistent scrollbar for a virtual document viewport, with a proportional thumb, dragging, track clicks and keyboard navigation.

```ts
import { Scrollbar } from '@kition/tessera-ui'
```

### When to use

- A canvas pans through a bounded document instead of scrolling DOM content.

### When not to

- An ordinary DOM list: use native overflow scrolling.

### Example: Page sections

```tsx
import { useState } from 'react'
import { Scrollbar } from '@kition/tessera-ui'

export default function Demo() {
  const [offset, setOffset] = useState(0)
  return (
    <div style={{ display: 'flex', height: 200, width: 300, border: '1px solid var(--kit-border)' }}>
      <div style={{ flex: 1, overflow: 'hidden' }}>
        <div style={{ transform: `translateY(${-offset}px)` }}>
          {Array.from({ length: 20 }, (_, index) => <div key={index} style={{ height: 40, paddingLeft: 12 }}>Page section {index + 1}</div>)}
        </div>
      </div>
      <Scrollbar label="Page sections" value={offset} max={600} page={200} onChange={setOffset} />
    </div>
  )
}
```

### Scrollbar props

A persistent scrollbar for virtual viewports, with proportional thumb, pointer capture and keyboard navigation.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` |  | Accessible name supplied by the editor's locale. |
| `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` |  |
| `value` (required) | `number` |  | Distance from the start of the content, in the caller's coordinates. |
| `max` (required) | `number` |  | Maximum scroll distance (content length minus visible length). |
| `page` (required) | `number` |  | Visible content length, in the same coordinates as value. |
| `onChange` (required) | `(value: number) => void` |  |  |
| `controls` | `string` |  |  |

## Ribbon

Editor chrome. Office-style command groups: large and small buttons, stacks, rows, and swatches; it collapses to Single line, and a ribbon too wide for its window gives way in steps (RibbonFit): small buttons, icons alone, then groups collapsed to one button each.

```ts
import { RibbonGroup, RibbonButton, RibbonStack, RibbonRow, RibbonItem, ColorGrid } from '@kition/tessera-ui'
```

### When to use

- A kit’s Home, Insert, Format tabs.

### Example: Home tab

Give each group an icon: it is the button the group collapses to when the ribbon has no room.

```tsx
import { useState } from 'react'
import { ColorGrid, MenuButton, RibbonButton, RibbonGroup, RibbonStack } from '@kition/tessera-ui'
import { BoldIcon, ClipboardPasteIcon, CopyIcon, ItalicIcon, LayersIcon, ScissorsIcon, SquareIcon } from '@kition/tessera-icons/react'

export default function Demo() {
  const [bold, setBold] = useState(false)
  const [fill, setFill] = useState('#5645d4')
  return (
    <div className="demo-ribbon">
      <RibbonGroup label="Clipboard">
        <RibbonButton icon={ClipboardPasteIcon} label="Paste" size="large" />
        <RibbonStack>
          <RibbonButton icon={ScissorsIcon} label="Cut" />
          <RibbonButton icon={CopyIcon} label="Copy" />
        </RibbonStack>
      </RibbonGroup>
      <RibbonGroup label="Font">
        <RibbonStack>
          <RibbonButton icon={BoldIcon} label="Bold" size="icon" pressed={bold} onClick={() => setBold(!bold)} />
          <RibbonButton icon={ItalicIcon} label="Italic" size="icon" />
        </RibbonStack>
      </RibbonGroup>
      <RibbonGroup label="Fill">
        <MenuButton trigger={({ toggle }) => <RibbonButton icon={SquareIcon} label="Fill" swatch={fill} onClick={toggle} />}>
          <ColorGrid onPick={setFill} />
        </MenuButton>
      </RibbonGroup>
      <RibbonGroup label="Arrange">
        <RibbonButton icon={LayersIcon} label="Layers" size="large" />
      </RibbonGroup>
    </div>
  )
}
```

### RibbonGroup props

A ribbon group. With an `id` (`group:<tab>/<group>`, or an engine menu path `menu:<Menu>/<Group>`
for groups built from commands) it follows the UI configuration and ends with the host's
buttons for it. In Single line it shows its primary items and a popover with the rest; `icon`
marks the one button a group without primary items becomes there, and the button a Classic
group collapses to when the ribbon has no room for it (`RibbonFit`).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `label` (required) | `string` |  |  |
| `icon` | `IconComponent` |  |  |
| `children` (required) | `ReactNode` |  |  |

### RibbonButton props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `IconComponent` |  |  |
| `label` (required) | `string` |  |  |
| `size` | `'large' \| 'small' \| 'icon'` | `'small'` |  |
| `pressed` | `boolean` |  |  |
| `swatch` | `string` |  | A colored mark under the icon (font color, fill). |
| `primary` | `boolean` |  | Shown in Single line's row (small); the group's other items wait in its popover. |
| `lineLabel` | `boolean` |  | In Single line's row, keep the label beside the icon; a primary item with an icon otherwise shows the icon alone there (its label stays its name and tooltip). |

Also takes the attributes of its HTML element (`className`, `aria-*`, events).

### RibbonStack props

Small buttons stacked in up to three rows; in a Single line group, its primary buttons in the row.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` |  |  |

### RibbonRow props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` |  |  |

### RibbonItem props

Any content in a ribbon group that is not a ribbon button (a field, a gallery): `primary` shows
it in Single line's row too; otherwise it waits in the group's popover there.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `primary` | `boolean` |  |  |
| `children` (required) | `ReactNode` |  |  |

### ColorGrid props

A grid of color swatches; `onPick` gets `#RRGGBB`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `colors` | `readonly string[]` | `[...PALETTE_COLORS, ...STANDARD_COLORS]` |  |
| `onPick` (required) | `(color: string) => void` |  |  |
| `testId` | `string` |  |  |

## OverflowStrip

Editor chrome. A row that scrolls sideways when it does not fit: the cut edge fades, and a button there scrolls.

```ts
import { OverflowStrip } from '@kition/tessera-ui'
```

### When to use

- A ribbon’s groups or a tool’s options bar in a narrow window.

### When not to

- Vertical lists: let the panel scroll.

### Example: Options bar

The row is wider than its box; use the arrows at the faded edges.

```tsx
import { Button, OverflowStrip } from '@kition/tessera-ui'

const TOOLS = ['Brush', 'Eraser', 'Clone', 'Heal', 'Dodge', 'Burn', 'Sponge', 'Smudge', 'Blur', 'Sharpen', 'Gradient', 'Fill', 'Text', 'Shape', 'Crop', 'Slice']

export default function Demo() {
  return (
    <div style={{ width: 'min(100%, 420px)', border: '1px solid var(--kit-border)', borderRadius: 8, background: 'var(--kit-surface)' }}>
      <OverflowStrip className="" panelClassName="demo-strip" labels={{ start: 'Scroll left', end: 'Scroll right' }} testId="tools">
        {TOOLS.map((tool) => (
          <Button key={tool}>{tool}</Button>
        ))}
      </OverflowStrip>
    </div>
  )
}
```

### OverflowStrip props

A row that scrolls sideways when its content does not fit (the ribbon's groups, a tool's options
bar): the cut edge fades, and a button there scrolls by most of a width. `className` and
`panelClassName` add to the outer box and the scrolled row; `resetKey` (the shown tab, the active
tool) re-measures; the buttons' test ids are `${testId}-start` and `${testId}-end`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` (required) | `string` |  |  |
| `panelClassName` (required) | `string` |  |  |
| `role` | `string` |  |  |
| `resetKey` | `unknown` |  |  |
| `labels` (required) | `{ start: string; end: string }` |  |  |
| `testId` (required) | `string` |  |  |
| `panelRef` | `RefObject<HTMLDivElement \| null>` |  | The scrolled row, for a caller that measures it (the frame's step-down). |
| `children` (required) | `ReactNode` |  |  |

## StatusBar

Editor chrome. The bottom bar: document facts on the left, zoom on the right.

```ts
import { StatusBar, StatusSpacer, ZoomControl } from '@kition/tessera-ui'
```

### Example: Zoom

```tsx
import { useState } from 'react'
import { StatusBar, StatusSpacer, ZoomControl } from '@kition/tessera-ui'

export default function Demo() {
  const [zoom, setZoom] = useState(1)
  return (
    <div className="demo-frame">
      <StatusBar>
        <span>Slide 3 of 12</span>
        <StatusSpacer />
        <ZoomControl zoom={zoom} onZoom={setZoom} onFit={() => setZoom(1)} labels={{ out: 'Zoom out', in: 'Zoom in', fit: 'Fit' }} />
      </StatusBar>
    </div>
  )
}
```

### StatusBar props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` |  |  |
| `onClick` | `(event: ReactMouseEvent<HTMLElement>) => void` |  |  |

### StatusSpacer props

### ZoomControl props

Zoom out, a slider from `min` to `max`, zoom in, the value, and fit.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `zoom` (required) | `number` |  |  |
| `onZoom` (required) | `(zoom: number) => void` |  |  |
| `onFit` (required) | `() => void` |  |  |
| `min` | `number` | `0.1` |  |
| `max` | `number` | `4` |  |
| `labels` (required) | `{ out: string; in: string; fit: string }` |  |  |

## TableSizePicker

Editor chrome. Pick a table size by hovering a grid.

```ts
import { TableSizePicker } from '@kition/tessera-ui'
```

### Example: Insert a table

```tsx
import { useState } from 'react'
import { TableSizePicker } from '@kition/tessera-ui'

export default function Demo() {
  const [picked, setPicked] = useState('')
  return (
    <div className="demo-stack">
      <TableSizePicker onPick={(rows, columns) => setPicked(`${rows} × ${columns}`)} label={(rows, columns) => `${columns} × ${rows} table`} />
      <span>{picked ? `Inserted a ${picked} table` : 'Pick a size'}</span>
    </div>
  )
}
```

### TableSizePicker props

Choosing a table's size by pointing at a grid of cells (Insert > Table).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `rows` | `number` | `8` |  |
| `columns` | `number` | `10` |  |
| `onPick` (required) | `(rows: number, columns: number) => void` |  |  |
| `label` (required) | `(rows: number, columns: number) => string` |  |  |

## Panel parts

Editor chrome. Pieces of list panels: visibility eyes, in-place rename, footers, thumbnails.

```ts
import { EyeButton, RenameField, PanelFooter, Thumbnail, Panel } from '@kition/tessera-ui'
```

### When to use

- Layers, tracks, pages panels.

### Example: A layer row

```tsx
import { useState } from 'react'
import { EyeButton, PanelFooter, RenameField } from '@kition/tessera-ui'

export default function Demo() {
  const [visible, setVisible] = useState(true)
  const [name, setName] = useState('Background')
  const [editing, setEditing] = useState(false)
  return (
    <div className="demo-frame" style={{ width: 280 }}>
      <div className="demo-layer-row">
        <EyeButton visible={visible} label={`Show ${name}`} onPress={() => setVisible(!visible)} />
        {editing ? (
          <RenameField value={name} label="Layer name" onChange={setName} onDone={() => setEditing(false)} />
        ) : (
          <span onDoubleClick={() => setEditing(true)}>{name}</span>
        )}
      </div>
      <PanelFooter start={<span>1 layer</span>} end={<span>Double-click to rename</span>} />
    </div>
  )
}
```

### EyeButton props

A row's eye: the eye icon while shown, an empty box while hidden (as Photoshop draws it).
A press toggles at once (`onPress` hears whether Alt was held); with `sweep`, dragging on from
the press down the eye column (mouse, pen, or touch) reaches every other eye of the group the
pointer crosses, through `sweep.onOver`, so the panel gives each the visibility the first press
set. A keyboard click toggles too. It is pressed while its row shows; `tabIndex` takes it out of
the tab order where a list moves the focus itself.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `visible` (required) | `boolean` |  |  |
| `label` (required) | `string` |  |  |
| `onPress` (required) | `(alt: boolean) => void` |  |  |
| `sweep` | `EyeSweep` |  |  |
| `tabIndex` | `number` |  |  |
| `testId` | `string` |  |  |

### RenameField props

A row name's in-place editor, focused with its text selected: Enter or leaving it commits,
Escape cancels (`onDone` once, with which); a composing input method keeps Enter for itself.
It keeps its presses and keys from the row (no selection change, no editor shortcut).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `string` |  |  |
| `label` (required) | `string` |  |  |
| `onChange` (required) | `(text: string) => void` |  |  |
| `onDone` (required) | `(commit: boolean) => void` |  |  |
| `testId` | `string` |  |  |

### PanelFooter props

The buttons along a list panel's bottom, as Photoshop's: `start` on the left, `end` on the right.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `start` | `ReactNode` |  |  |
| `end` | `ReactNode` |  |  |

### Thumbnail props

A thumbnail: `image` fitted in a `size` × `size` cell at its own aspect, over a checkerboard
where it is transparent, with a thin frame; an empty cell while there is no image (not drawn
yet, or its source could not draw one).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `image` (required) | `ThumbnailImage \| null` |  |  |
| `size` (required) | `number` |  |  |
| `testId` | `string` |  |  |

### Panel props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `side` (required) | `'left' \| 'right'` |  |  |
| `width` (required) | `number` |  |  |
| `title` | `string` |  |  |
| `children` (required) | `ReactNode` |  |  |
| `testId` | `string` |  |  |

## WorkspaceLayout

Workspace. Split, tabbed, resizable panels in a tree, as video and photo editors lay out their workspaces.

```ts
import { WorkspaceLayout } from '@kition/tessera-ui'
```

### Example: Editing workspace

Drag the gutters; drag tabs between groups.

```tsx
import { useState } from 'react'
import { WorkspaceLayout, type WorkspaceNode } from '@kition/tessera-ui'

const START: WorkspaceNode = {
  split: 'row',
  size: { ratio: 0.32 },
  a: { tabs: ['project', 'effects'], active: 0 },
  b: { split: 'column', size: { ratio: 0.6 }, a: { tabs: ['program'], active: 0 }, b: { tabs: ['timeline'], active: 0 } },
}

export default function Demo() {
  const [tree, setTree] = useState(START)
  const [focused, setFocused] = useState<string | null>('program')
  const [maximized, setMaximized] = useState<string | null>(null)
  const panel = (id: string, label: string) => ({ id, label, render: () => <div className="demo-pane">{label}</div> })
  return (
    <div style={{ height: 320 }}>
      <WorkspaceLayout
        tree={tree}
        onTree={setTree}
        panels={[panel('project', 'Project'), panel('effects', 'Effects'), panel('program', 'Program'), panel('timeline', 'Timeline')]}
        focused={focused}
        onFocus={setFocused}
        maximized={maximized}
        onMaximized={setMaximized}
        onRestore={() => setTree(START)}
      />
    </div>
  )
}
```

### WorkspaceLayout props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tree` (required) | `WorkspaceNode` |  |  |
| `onTree` (required) | `(tree: WorkspaceNode) => void` |  |  |
| `panels` (required) | `readonly WorkspacePanel[]` |  | Keep this array, and each panel's `render`, stable across renders (see above). |
| `focused` (required) | `string \| null` |  |  |
| `onFocus` (required) | `(panel: string) => void` |  |  |
| `maximized` (required) | `string \| null` |  | The maximized panel fills the area without changing the tree (upstream `keys.maximized`, the ` and Shift+` keys). The panel menu's Maximize Frame, as upstream, replaces the tree instead. |
| `onMaximized` (required) | `(panel: string \| null) => void` |  |  |
| `onRestore` (required) | `() => void` |  | Restore Workspace in the panel menu. |
| `testId` | `string` |  |  |

## DockArea

Workspace. A column of collapsible, resizable panel groups, remembered per kit.

```ts
import { DockArea } from '@kition/tessera-ui'
```

### Example: Right dock

```tsx
import { useState } from 'react'
import { DockArea } from '@kition/tessera-ui'

export default function Demo() {
  const [shown, setShown] = useState<ReadonlySet<string>>(new Set(['color', 'layers']))
  return (
    <div style={{ height: 320, display: 'flex', justifyContent: 'flex-end' }}>
      <DockArea
        kit="tessera-docs"
        width={260}
        shown={shown}
        onShownChange={setShown}
        groups={[
          { id: 'color', defaultHeight: 140, tabs: [{ id: 'color', label: 'Color', render: () => <div className="demo-pane">Color</div> }, { id: 'swatches', label: 'Swatches', render: () => <div className="demo-pane">Swatches</div> }] },
          { id: 'layers', defaultHeight: 160, tabs: [{ id: 'layers', label: 'Layers', render: () => <div className="demo-pane">Layers</div> }] },
        ]}
      />
    </div>
  )
}
```

### DockArea props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `kit` (required) | `string` |  | Remembers the layout per kit, in the kit's store (`kit:<kit>:dock`, see `kitStore`). |
| `groups` (required) | `readonly DockGroup[]` |  |  |
| `shown` (required) | `ReadonlySet<string>` |  | Groups the Window menu shows; others are not drawn. |
| `onShownChange` | `(shown: ReadonlySet<string>) => void` |  |  |
| `width` | `number` |  |  |
| `handle` | `Ref<DockAreaHandle>` |  | Receives the dock's `DockAreaHandle`. |
| `testId` | `string` | `'dock'` |  |

## FloatingPanels

Workspace. Movable, resizable windows over the workspace, remembered per kit.

```ts
import { FloatingPanels } from '@kition/tessera-ui'
```

### Example: A floating bin

```tsx
import { useState } from 'react'
import { Button, FloatingPanels } from '@kition/tessera-ui'

export default function Demo() {
  const [open, setOpen] = useState<string[]>(['bin'])
  const [focused, setFocused] = useState<string | null>('bin')
  return (
    <div style={{ position: 'relative', height: 300 }}>
      <Button onClick={() => setOpen(['bin'])}>Open the bin</Button>
      <FloatingPanels
        kit="tessera-docs"
        store="floating"
        panels={open.map((id) => ({ id, title: 'Bin: Interviews', render: () => <div className="demo-pane">12 clips</div> }))}
        onClose={(id) => setOpen(open.filter((item) => item !== id))}
        focused={focused}
        onFocus={setFocused}
        defaultSize={{ width: 280, height: 180 }}
      />
    </div>
  )
}
```

### FloatingPanels props

The floating windows layer (see the module's comment). Render it inside an element with a
non-static `position` (`relative`) that covers the area the windows may use: the layer fills
that element and keeps every window inside it.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `kit` (required) | `string` |  |  |
| `store` (required) | `string` |  | Store name for positions and sizes (`useKitStore`). It holds the windows' rectangles only: anything else under it is dropped on read, so a kit keeps its own list of open windows under a different name. |
| `panels` (required) | `readonly FloatingPanel[]` |  | The open windows, bottom to top as first opened. Keep the array and each `render` stable (`useMemo`, `useCallback`). |
| `onClose` (required) | `(id: string) => void` |  |  |
| `focused` (required) | `string \| null` |  | The window the kit treats as focused (drawn as such and raised); null for none. |
| `onFocus` (required) | `(id: string) => void` |  | A press or focus inside a window. |
| `defaultSize` | `FloatingSize` |  | A new window's size (upstream's `default_size`, 520 × 360). |
| `minSize` | `FloatingSize` |  | The smallest a window resizes to (upstream's `min_size`, 320 × 220). |
| `testId` | `string` |  |  |

## ColorPicker

Color. Saturation and brightness square, hue strip, hex and RGB fields.

```ts
import { ColorPicker } from '@kition/tessera-ui'
```

### Keyboard

| Keys | What they do |
| --- | --- |
| Arrows (on the square) | Change saturation (Left, Right) and brightness (Up, Down); with Shift, in larger steps. |
| Up, Down (on the hue strip) | Raise or lower the hue; with Shift, in larger steps. |
| Enter, Escape (in the hex field) | Commit the typed colour, or put the old one back. |

### Example: Pick a colour

```tsx
import { useState } from 'react'
import { ColorPicker, rgbToHex, type RGB } from '@kition/tessera-ui'

export default function Demo() {
  const [rgb, setRgb] = useState<RGB>([86, 69, 212])
  return (
    <div className="demo-row" style={{ alignItems: 'flex-start' }}>
      <div style={{ width: 240 }}>
        <ColorPicker value={rgb} onChange={(value) => setRgb(value)} />
      </div>
      <div className="demo-swatch" style={{ background: rgbToHex(rgb) }}>{rgbToHex(rgb)}</div>
    </div>
  )
}
```

### ColorPicker props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `RGB` |  |  |
| `onChange` (required) | `(rgb: RGB, final: boolean) => void` |  | Called on every pointer move and arrow key (`final: false` mid-drag, one `final: true` on release or key). |
| `disabled` | `boolean` |  |  |
| `testId` | `string` | `'color-picker'` |  |
| `uiId` | `string` |  | A Kit UI id when the picker is a declared element. |

## ColorWheel

Color. A grading wheel with a lightness slider, as colour correction panels use.

```ts
import { ColorWheel } from '@kition/tessera-ui'
```

### Keyboard

| Keys | What they do |
| --- | --- |
| Arrows | Move the puck by 0.01 of the radius; with Shift, by 0.1. |
| Home | Put the puck back at the centre. |

### Example: Shadows wheel

```tsx
import { useState } from 'react'
import { ColorWheel } from '@kition/tessera-ui'

export default function Demo() {
  const [shadows, setShadows] = useState<[number, number]>([0.2, -0.1])
  const [lightness, setLightness] = useState(0)
  return <ColorWheel label="Shadows" value={shadows} lightness={lightness} onChange={(value) => setShadows(value)} onLightness={(value) => setLightness(value)} />
}
```

### ColorWheel props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `readonly [number, number]` |  | The offset, `[x, y]`, y up, of length at most 1. |
| `lightness` (required) | `number` |  | -100 to 100. |
| `onChange` (required) | `(value: [number, number], phase: DragPhase) => void` |  |  |
| `onLightness` (required) | `(value: number, phase: DragPhase) => void` |  |  |
| `label` (required) | `string` |  | Shown above the wheel, and its accessible name. |
| `size` | `number` | `120` | The wheel's side in CSS pixels (120 by default, upstream's largest). The control is `size + 18` px wide: the lightness strip (16 px and a 2 px gap) sits outside the wheel, where upstream draws it inside the wheel's square. To fit upstream's row of three wheels (Film's Lumetri Color Wheels, Task 29), pass `size = min((available - 24) / 3, 120) - 18`. |
| `disabled` | `boolean` |  |  |
| `uiId` | `string` |  | The wheel's Kit UI id. |
| `lightnessUiId` | `string` |  | The lightness slider's Kit UI id. |
| `testId` | `string` |  |  |

## GradientSlider

Color. A slider drawn over its own gradient: temperature, tint, hue.

```ts
import { GradientSlider } from '@kition/tessera-ui'
```

### Keyboard

| Keys | What they do |
| --- | --- |
| Arrows | Change the value by a hundredth of the soft range (Right and Up raise it); with Shift, by ten of those. |
| Home, End | Go to the low or the high end of the soft range. |

### Example: White balance

```tsx
import { useState } from 'react'
import { GradientSlider, SLIDER_GRADIENTS } from '@kition/tessera-ui'

export default function Demo() {
  const [temperature, setTemperature] = useState(10)
  const [tint, setTint] = useState(-5)
  return (
    <div className="demo-stack" style={{ width: 300 }}>
      <GradientSlider label="Temperature" value={temperature} min={-100} max={100} stops={SLIDER_GRADIENTS.temperature} onChange={(value) => setTemperature(value)} />
      <GradientSlider label="Tint" value={tint} min={-100} max={100} stops={SLIDER_GRADIENTS.tint} onChange={(value) => setTint(value)} />
    </div>
  )
}
```

### GradientSlider props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `number` |  |  |
| `min` (required) | `number` |  |  |
| `max` (required) | `number` |  |  |
| `softMin` | `number` | `min` | The track's range (upstream's `soft_min`/`soft_max`); `min` and `max` by default. The hot text reaches `min`..`max`. |
| `softMax` | `number` | `max` |  |
| `decimals` | `number` | `0` | Decimals a value is rounded to (0 by default). |
| `default` | `number` |  | Restored by a double-click on the track; no double-click without it. |
| `stops` | `readonly string[]` |  | CSS gradient stops for the track (Temperature, Tint, Hue; see `SLIDER_GRADIENTS`); a plain track when absent. |
| `label` (required) | `string` |  |  |
| `onChange` (required) | `(value: number, phase: DragPhase) => void` |  |  |
| `disabled` | `boolean` |  |  |
| `uiId` | `string` |  |  |
| `testId` | `string` |  |  |

## CurveEditor

Color. Tone curves: drag points, double-click to add, with a histogram under them.

```ts
import { CurveEditor } from '@kition/tessera-ui'
```

### Keyboard

| Keys | What they do |
| --- | --- |
| Arrows (on a point) | Move the point by 0.01 of the range; with Shift, by 0.1. |
| Delete, Backspace | Remove the point. |

### Example: An RGB curve

```tsx
import { useState } from 'react'
import { CurveEditor, RGB_IDENTITY, type CurvePoint } from '@kition/tessera-ui'

export default function Demo() {
  const [points, setPoints] = useState<CurvePoint[]>([RGB_IDENTITY[0], [0.3, 0.22], [0.7, 0.8], RGB_IDENTITY[1]])
  return (
    <div style={{ width: 240 }}>
      <CurveEditor kind="rgb" points={points} onChange={(next) => setPoints(next)} />
    </div>
  )
}
```

### CurveEditor props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `points` (required) | `readonly CurvePoint[]` |  |  |
| `kind` (required) | `CurveKind`: `'rgb'`, `'hue'` |  | 'rgb': a square with protected end points; 'hue': periodic in x, a hue strip below, 0.45 aspect. |
| `samples` | `readonly number[]` |  | The curve's samples to draw (0..1 over x), given by the caller; `sampleCurve`'s by default. |
| `color` | `string` |  | The line and points' CSS colour; the theme's text colour by default. |
| `onChange` (required) | `(points: CurvePoint[], phase: DragPhase) => void` |  |  |
| `label` | `string` |  | The plot's accessible name ("Curve" by default). |
| `disabled` | `boolean` |  |  |
| `uiId` | `string` |  |  |
| `testId` | `string` |  |  |

## Histogram

Color. A smoothed histogram of an image’s tones.

```ts
import { Histogram } from '@kition/tessera-ui'
```

### Example: Luminance

```tsx
import { Histogram } from '@kition/tessera-ui'

const bins = Array.from({ length: 256 }, (_, i) => Math.exp(-((i - 110) ** 2) / 1800) * 900 + Math.exp(-((i - 200) ** 2) / 600) * 500 + 40)

export default function Demo() {
  return (
    <div style={{ width: 300 }}>
      <Histogram bins={bins} />
    </div>
  )
}
```

### Histogram props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `bins` (required) | `ArrayLike<number>` |  | Bin counts (256 for an 8-bit channel), left (shadows) to right (highlights). |
| `color` | `string` |  | A CSS color for the bars; the element's own (inherited) color by default. |
| `height` | `number` | `100` |  |
| `smooth` | `boolean` | `false` | Draws the bins through upstream's five-bin display kernel (`smoothHistogram`), as its Camera Raw histogram does. |
| `scale` | `'interior' \| 'rank'` | `'interior'` | What the bars are scaled to: `interior`, the interior bins' maximum (the default, see `scaleFor`), or `rank`, upstream's Histogram panel and tone editors (`tone.rs` `draw_histogram`): the 251st-smallest of 256 bins, so a handful of spikes (pure white, pure black) are clipped instead of flattening the rest. Either with 10% headroom. |
| `testId` | `string` | `'histogram'` |  |

## Timecode and transport

Media and time. A timecode field you can type or scrub, and the transport buttons of a player.

```ts
import { TimecodeField, TransportBar } from '@kition/tessera-ui'
```

### Keyboard

| Keys | What they do |
| --- | --- |
| Enter, F2 | Start typing a time into the timecode field. |
| Enter (while typing) | Commit the typed time. |
| Escape (while typing) | Stop typing and keep the time. |

### Example: A player

```tsx
import { useEffect, useState } from 'react'
import { TimecodeField, TransportBar } from '@kition/tessera-ui'
import { PauseIcon, PlayIcon, SkipBackIcon, SkipForwardIcon } from '@kition/tessera-icons/react'

export default function Demo() {
  const [time, setTime] = useState(83.4)
  const [playing, setPlaying] = useState(false)
  useEffect(() => {
    if (!playing) return
    const timer = setInterval(() => setTime((value) => value + 0.04), 40)
    return () => clearInterval(timer)
  }, [playing])
  return (
    <div className="demo-stack" style={{ width: 300 }}>
      <TimecodeField label="Playhead" value={time} fps={25} onChange={(seconds) => setTime(seconds)} accent />
      <TransportBar
        buttons={[
          { id: 'start', label: 'Go to start', icon: SkipBackIcon, onPress: () => setTime(0) },
          { id: 'play', label: playing ? 'Pause' : 'Play', icon: playing ? PauseIcon : PlayIcon, large: true, onPress: () => setPlaying(!playing) },
          { id: 'end', label: 'Go to end', icon: SkipForwardIcon, onPress: () => setTime(600) },
        ]}
      />
    </div>
  )
}
```

### TimecodeField props

A timecode readout: `value` (seconds) shown as timecode at `fps`. With `onChange` it scrubs
(one frame per 2 px, reported with `final: false`, then once with `final: true` on release) and
a click turns it into a text field (`parseTimecode`'s forms; Enter or blur commit with
`final: true`, Escape or text that is not a time reverts). Without `onChange` it only shows.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `number` |  | Seconds. |
| `fps` (required) | `number` |  |  |
| `dropFrame` | `boolean` |  |  |
| `onChange` | `(seconds: number, final: boolean) => void` |  | Called while scrubbing (`final: false`) and once on release, Enter, or blur. |
| `accent` | `boolean` |  | Upstream's accent-coloured playhead timecode. |
| `label` (required) | `string` |  |  |
| `uiId` | `string` |  |  |
| `testId` | `string` |  |  |

### TransportBar props

The buttons in `buttons`' order, centred. A button's `testId` is `<testId>-<id>`; one whose
Kit UI id the configuration hides is left out, and one it disables is disabled.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `buttons` (required) | `readonly TransportButton[]` |  |  |
| `testId` | `string` |  |  |

## LevelMeter

Media and time. Audio levels with peak hold, drawn on a canvas.

```ts
import { LevelMeter } from '@kition/tessera-ui'
```

### Example: Stereo

```tsx
import { useEffect, useState } from 'react'
import { LevelMeter } from '@kition/tessera-ui'

export default function Demo() {
  const [peaks, setPeaks] = useState([-12, -9])
  useEffect(() => {
    const timer = setInterval(() => setPeaks([-6 - Math.random() * 30, -4 - Math.random() * 30]), 100)
    return () => clearInterval(timer)
  }, [])
  return (
    <div style={{ height: 180 }}>
      <LevelMeter peaks={peaks} labels={['L', 'R']} />
    </div>
  )
}
```

### LevelMeter props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `peaks` (required) | `readonly number[]` |  | Current peak per channel, linear 0..1+ (above 1 clips). |
| `floor` | `number` | `-60` | dB at the bottom of the scale (upstream meters: -60). |
| `holds` | `readonly number[]` |  | Peak hold per channel, linear. |
| `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` |  |
| `labels` | `readonly string[]` |  | Channel captions under the bars ("S" "S" in upstream's solo buttons row, or "L" "R"). |
| `ref` | `Ref<LevelMeterHandle>` |  | Draws live levels without a React render. |
| `testId` | `string` |  |  |

## KeyframeLane

Media and time. Keyframes on a time lane: select, drag, and their interpolation shapes.

```ts
import { KeyframeLane } from '@kition/tessera-ui'
```

### Keyboard

| Keys | What they do |
| --- | --- |
| Left, Right | Move the selected keyframes by one frame. |
| Escape | While dragging: put the keyframes back where they were. |

### Example: Three keyframes

```tsx
import { useState } from 'react'
import { KeyframeLane, type Keyframe } from '@kition/tessera-ui'

export default function Demo() {
  const [keyframes, setKeyframes] = useState<Keyframe[]>([
    { id: 'a', time: 1 },
    { id: 'b', time: 3.5, interpolation: 'bezier' },
    { id: 'c', time: 6, interpolation: 'hold' },
  ])
  return (
    <div style={{ width: 360 }}>
      <KeyframeLane
        keyframes={keyframes}
        start={0}
        end={8}
        onSelect={(ids) => setKeyframes((list) => list.map((key) => ({ ...key, selected: ids.includes(key.id) })))}
        onMove={(ids, delta) => setKeyframes((list) => list.map((key) => (ids.includes(key.id) ? { ...key, time: Math.max(0, key.time + delta) } : key)))}
      />
    </div>
  )
}
```

### KeyframeLane props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `keyframes` (required) | `readonly Keyframe[]` |  |  |
| `start` (required) | `number` |  | Visible range in seconds and the lane's width map times to x. |
| `end` (required) | `number` |  |  |
| `onSelect` (required) | `(ids: string[], add: boolean) => void` |  |  |
| `onMove` (required) | `(ids: string[], delta: number) => void` |  | Called once on release with the dragged ids and the time delta. |
| `snap` | `(time: number) => number` |  |  |
| `fps` | `number` | `30` | Frames per second: an arrow key moves the selected keyframes one frame (30 by default). |
| `onMenu` | `(id: string, at: ContextMenuPoint) => void` |  | A keyframe's menu was asked for at a screen point (upstream's interpolation menu). |
| `uiId` | `string` |  | The Kit UI id every keyframe carries (`control:effects.keyframe`). |
| `testId` | `string` |  |  |

## Strings and elements

Integration. What components ask of the app around them: strings (StringsProvider) and element states (ElementsProvider). Without them, components draw in English with every element shown.

```ts
import { StringsProvider, ElementsProvider, Element } from '@kition/tessera-ui'
```

### Example: Strings and element states of your own

zh-CN strings; one group disabled, one hidden by the host.

```tsx
import { ElementsProvider, StringsProvider, createStrings, TESSERA_CATALOGS, PasswordInput, RibbonButton, RibbonGroup, type Elements } from '@kition/tessera-ui'
import { ClipboardPasteIcon } from '@kition/tessera-icons/react'

// An app gives Tessera its strings and element states.
const elements: Elements = {
  state: (id) => ({ hidden: id === 'group:home/hidden', disabled: id === 'group:home/clipboard' }),
  renderExtras: () => null,
  drawn: () => undefined,
}

export default function Demo() {
  return (
    <StringsProvider strings={createStrings(TESSERA_CATALOGS, 'zh-CN')}>
      <ElementsProvider elements={elements}>
        <div className="demo-ribbon">
          <RibbonGroup id="group:home/clipboard" label="Clipboard (disabled by the host)">
            <RibbonButton icon={ClipboardPasteIcon} label="Paste" size="large" />
          </RibbonGroup>
          <RibbonGroup id="group:home/hidden" label="Hidden by the host">
            <RibbonButton icon={ClipboardPasteIcon} label="Never drawn" size="large" />
          </RibbonGroup>
        </div>
        <div style={{ marginTop: 12, maxWidth: 280 }}>
          <PasswordInput size="md" defaultValue="secret" aria-label="Password" />
        </div>
      </ElementsProvider>
    </StringsProvider>
  )
}
```

### StringsProvider props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `strings` (required) | `Strings` |  |  |
| `children` (required) | `ReactNode` |  |  |

### ElementsProvider props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `elements` (required) | `Elements` |  |  |
| `children` (required) | `ReactNode` |  |  |

### Element props

Content that belongs to one element: not drawn when hidden; its form controls disabled when
disabled. A `fieldset` disables every control inside it without each control knowing.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` |  |  |
| `children` (required) | `ReactNode` |  |  |

## Tokens and skins

Every value a Tessera component draws with is a CSS variable. The 15 theme tokens are the Kit Harness Protocol's (Kit UI protocol, section 4): a host sends them in `ui/initialize` and `ui/theme`, and every kit that follows the protocol takes the skin. The component tokens are Tessera's own layout values. A skin (Paper, Graphite) is one value per theme token.

Package: `@kition/tessera-tokens` (CSS variables, TypeScript) and the Rust crate `tessera-tokens` · [On the site](https://tessera.kition.ai/tokens/) · [Theming guide](guides/theming.md)

```ts
import '@kition/tessera-tokens/tokens.css' // the Paper values on :root
import { SKINS, skinTheme } from '@kition/tessera-tokens'

const theme = skinTheme('graphite') // { colorScheme, tokens }, ready to send as ui/theme
```

### Theme tokens (sent by hosts)

| Token | Paper | Graphite | Meaning |
| --- | --- | --- | --- |
| `--kit-font-sans` | `Inter, system-ui, -apple-system, 'SF Pro Text', 'Segoe UI', Roboto, 'PingFang SC', 'Hiragino Sans GB', 'Noto Sans SC', sans-serif` | `Inter, system-ui, -apple-system, 'SF Pro Text', 'Segoe UI', Roboto, 'PingFang SC', 'Hiragino Sans GB', 'Noto Sans SC', sans-serif` | Interface font stack |
| `--kit-font-mono` | `ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace` | `ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace` | Monospace font stack |
| `--kit-surface` | `#ffffff` | `#1b1e23` | Editor background |
| `--kit-surface-muted` | `#fafaf9` | `#22262c` | Panels, rails, ribbon background |
| `--kit-canvas` | `#f6f5f4` | `#15171b` | Behind the document (pasteboard) |
| `--kit-text` | `#1a1a1a` | `#eceff1` | Primary text |
| `--kit-text-muted` | `#5d5b54` | `#a9b0ba` | Secondary text |
| `--kit-border` | `#e5e3df` | `#33373e` | Hairlines and control borders |
| `--kit-primary` | `#5645d4` | `#8b7ff0` | Primary action, selection, focus |
| `--kit-primary-text` | `#ffffff` | `#0b0a1f` | Text on primary |
| `--kit-primary-soft` | `rgba(86, 69, 212, 0.1)` | `rgba(86, 69, 212, 0.1)` | Selected and hovered backgrounds |
| `--kit-danger` | `#e03131` | `#e03131` | Destructive and error |
| `--kit-radius-control` | `8px` | `8px` | Buttons, inputs |
| `--kit-radius-card` | `12px` | `12px` | Cards, panels, dialogs |
| `--kit-shadow-card` | `0 1px 2px rgba(15, 15, 15, 0.06), 0 4px 16px rgba(15, 15, 15, 0.06)` | `0 1px 2px rgba(15, 15, 15, 0.06), 0 4px 16px rgba(15, 15, 15, 0.06)` | Card and popover shadow |

### Component tokens (Tessera's own)

| Token | Paper | Graphite | Meaning |
| --- | --- | --- | --- |
| `--kit-meter-bg` | `#e9e8e4` | `#e9e8e4` | Level meter track |
| `--kit-meter-ok` | `#2f9e44` | `#2f9e44` | Level meter green gradient, at the floor |
| `--kit-meter-ok-high` | `#40c057` | `#40c057` | Level meter green gradient, at -12 dB |
| `--kit-meter-warn` | `#e8a200` | `#e8a200` | Level meter yellow band |
| `--kit-meter-clip` | `#e03131` | `#e03131` | Level meter red band |
| `--kui-bar-height` | `36px` | `36px` | The top strip of both shells |
| `--kui-ribbon-row` | `24px` | `24px` | A ribbon row |
| `--kui-tab-underline` | `2px` | `2px` | The selected tab's underline |
| `--kui-tab-selected-weight` | `600` | `600` | The selected tab's font weight |
| `--kui-hover` | `color-mix(in srgb, var(--kit-text) 7%, transparent)` | `color-mix(in srgb, var(--kit-text) 7%, transparent)` | A control under the pointer: neutral, unlike a pressed toggle's --kit-primary-soft |
| `--kui-select-chevron` | `url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='%235d5b54' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='m6 9 6 6 6-6'/%3E%3C/svg%3E")` | `url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='%235d5b54' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='m6 9 6 6 6-6'/%3E%3C/svg%3E")` | Chevron-down for drop-downs, in --kit-text-muted (a data URI cannot read a variable) |
| `--kui-success` | `#18794e` | `#18794e` | Success: done, active, paid (tags, alerts, results); text on its own soft tint |
| `--kui-warning` | `#ad5700` | `#ad5700` | Warning: pending, needs attention (tags, alerts, results); text on its own soft tint |
| `--kui-chart-1` | `#5645d4` | `#5645d4` | Chart series 1: lines and their legend swatches, in order |
| `--kui-chart-2` | `#0d74ce` | `#0d74ce` | Chart series 2: lines and their legend swatches, in order |
| `--kui-chart-3` | `#18794e` | `#18794e` | Chart series 3: lines and their legend swatches, in order |
| `--kui-chart-4` | `#ad5700` | `#ad5700` | Chart series 4: lines and their legend swatches, in order |
| `--kui-chart-5` | `#ce2c31` | `#ce2c31` | Chart series 5: lines and their legend swatches, in order |
| `--kui-chart-6` | `#8145b5` | `#8145b5` | Chart series 6: lines and their legend swatches, in order |

### Rules

- A component never hard-codes a colour, radius, font, or shadow: it reads a token.
- An app that is not a kit sets the same variables in its own stylesheet.
- Every skin is held to WCAG AA contrast by the token package’s tests.
- The source of every value is `packages/tokens/tokens/*.tokens.json`.