# Texuli — full agent docs

> Complete catalog documentation generated from manifests (199 components).

## Blueprint envelope

A tree may travel in a blueprint envelope (`"format": "texuli-blueprint"`, `"version": 1`, `"spec"`, `"catalog"`, `"status": "draft"`, `"tree"`). Hosts validate it with `validateDraft` from `@texuli/catalog/validate` and paint it with `@texuli/player`.

Design system (spec 0.10.0, from 0.10.0): the envelope may carry `"designSystem"`, exactly one of `{"ref": "acme@2.1.0"}` (an exact `id@x.y.z` the host resolves, or `"texuli:<theme>"` for a library theme) and `{"inline": {"format": "texuli/design-system", "formatVersion": 1, "id", "version", "name", …}}` (a whole design-system document: colors, typography, shape, space and the other closed sections; never CSS). Never a version range, a URL, a path or a `data:` URL. The player applies it to its root; when it cannot (nothing resolves it, or the compiler refuses it for contrast, targets or URLs), the content paints in the default theme with a notice. Validation reports `check: "design-system"` with codes such as `extends-range`, `url-refused` and `unknown-key` and paths under `$.designSystem`.

---

# Accordion

> Stacked sections that expand and collapse one or more panels.

- **id:** `accordion`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `display`

### Use when

- FAQs and grouped detail the reader opens on demand

### Don't use when

- Peer views of one page (use tabs)
- A multi-step flow (use wizard)

### Accessibility

- Each header is a button that names its panel; expanded state is exposed
- Heading level is set so the outline stays valid

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `items` | array | yes | — | — | Sections: value, title, optional content |
| `type` | enum(single | multiple) | no | — | `"single"` | — |
| `value` | unknown | no | — | — | Open value or values |
| `onValueChange` | event | no | — | — | Open value changed |
| `collapsible` | boolean | no | — | `true` | — |
| `headingLevel` | number | no | — | `3` | — |
| `variant` | enum(default | bordered) | no | — | `"default"` | — |
| `disabled` | boolean | no | — | `false` | — |
| `class` | string | no | — | — | — |
| `content` | slot | no | — | — | Panel body for each item |

### Examples

#### FAQ (`faq`)

```json
{
  "headingLevel": 3,
  "items": [
    {
      "value": "hours",
      "title": "Hours",
      "content": "Weekdays 9–17."
    },
    {
      "value": "fees",
      "title": "Fees",
      "content": "No booking fee."
    }
  ]
}
```

### Related

- [`tabs`](components/tabs.md)
- [`stepper`](components/stepper.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Action form

> Groups fields whose submit proposes one named action intent to the host.

- **id:** `action-form`
- **package:** `@texuli/player`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `state`

### Use when

- Ask the host to do something with a few named values, such as a request

### Don't use when

- Payment or sign-in: those are host regions

### Accessibility

- A labelled form; invalid fields are marked and focused; the receipt is announced

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `action` | string | yes | — | — | The action name the host receives. |
| `label` | string | yes | untrusted | — | — |
| `children` | slot | no | — | — | — |

### Examples

#### Request access (`request`)

```json
{
  "action": "request-access",
  "label": "Request access"
}
```

### Related

- [`form-field`](components/form-field.md)
- [`form-submit`](components/form-submit.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Alert

> Inline feedback for a page section (status or error).

- **id:** `alert`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `display`

### Use when

- Report a result or problem next to the related content

### Don't use when

- A full-page failure (use error-state)
- A quiet tip in docs (use callout)

### Accessibility

- error tone uses role=alert; other tones use role=status; dismiss is named.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `tone` | enum(info | success | warning | error | brand | neutral) | no | — | `"info"` | — |
| `title` | string | no | — | — | Optional heading |
| `text` | string | no | untrusted | — | Body copy |
| `hideIcon` | boolean | no | — | `false` | — |
| `icon` | slot | no | — | — | Custom icon snippet |
| `actionLabel` | string | no | — | — | — |
| `actionHref` | string | no | developer | — | Optional action link (URL policy) |
| `onAction` | event | no | — | — | — |
| `dismissible` | boolean | no | — | `false` | — |
| `dismissLabel` | string | no | — | `"Dismiss"` | — |
| `onDismiss` | event | no | — | — | — |
| `class` | string | no | — | — | — |

### Examples

#### Warning alert (`warning`)

```json
{
  "tone": "warning",
  "title": "Check inventory",
  "text": "Three SKUs are low."
}
```

### Related

- [`callout`](components/callout.md)
- [`banner`](components/banner.md)
- [`error-state`](components/error-state.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# AlertDialog

> Modal confirm/cancel dialog for consequential actions.

- **id:** `alert-dialog`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `overlays`

### Use when

- Confirm delete or irreversible actions
- Require an explicit choice

### Don't use when

- Informational copy without a choice (use dialog or toast)

### Accessibility

- Role alertdialog; focus trapped until confirm or cancel
- Destructive mode styles the confirm action and warning icon

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `open` | boolean | no | — | `false` | — |
| `title` | string | yes | — | — | — |
| `description` | string | no | — | — | — |
| `confirmLabel` | string | no | — | `"Confirm"` | — |
| `cancelLabel` | string | no | — | `"Cancel"` | — |
| `destructive` | boolean | no | — | `false` | — |
| `onConfirm` | event | no | — | — | — |
| `onCancel` | event | no | — | — | — |
| `trigger` | slot | no | — | — | — |
| `children` | slot | no | — | — | — |
| `class` | string | no | — | — | — |
| `errorFallback` | string | no | — | — | — |
| `onOpenChange` | event | no | — | — | — |

### Examples

#### Destructive confirm (`delete`)

```json
{
  "title": "Delete note?",
  "description": "This cannot be undone.",
  "destructive": true,
  "confirmLabel": "Delete",
  "open": true
}
```

### Related

- [`dialog`](components/dialog.md)
- [`toaster`](components/toaster.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# AnalyticsGrid

> Auto-fit KPI and widget grid for dashboard screens.

- **id:** `analytics-grid`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `layouts`

### Use when

- KPI tiles and chart cards inside a dashboard

### Don't use when

- Single full-bleed chart

### Accessibility

- Optional region label names the metrics group.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `columns` | number | no | — | `3` | Preferred column count (1–4) |
| `minItem` | number | no | — | `280` | — |
| `gap` | string | no | — | `"1rem"` | — |
| `dense` | boolean | no | — | `false` | — |
| `label` | string | no | — | — | — |
| `children` | slot | yes | — | — | — |
| `class` | string | no | — | — | — |

### Examples

#### Three columns (`kpis`)

```json
{
  "columns": 3,
  "label": "Key metrics"
}
```

### Related

- [`layout-dashboard-grid`](components/layout-dashboard-grid.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# AppNav

> Desktop sidebar shell with mobile sheet drawer and main slot.

- **id:** `app-nav`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `overlays`

### Use when

- Full app chrome with responsive navigation

### Don't use when

- Sidebar alone inside a custom shell

### Accessibility

- Menu button opens a labelled sheet; main has a stable id.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `items` | array | no | — | — | — |
| `sections` | array | no | — | — | — |
| `collapsed` | boolean | no | — | `false` | — |
| `collapsible` | boolean | no | — | `true` | — |
| `variant` | enum(default | inset) | no | — | `"default"` | — |
| `header` | slot | no | — | — | — |
| `footer` | slot | no | — | — | — |
| `itemIcon` | slot | no | — | — | — |
| `children` | slot | no | — | — | — |
| `topBar` | slot | no | — | — | — |
| `label` | string | no | — | `"Main"` | — |
| `menuLabel` | string | no | — | `"Open navigation"` | — |
| `drawerTitle` | string | no | — | `"Navigation"` | — |
| `hrefTrust` | enum(developer | untrusted) | no | developer | `"developer"` | — |
| `mobileOpen` | boolean | no | — | `false` | — |
| `class` | string | no | — | — | — |

### Examples

#### App shell (`shell`)

```json
{
  "label": "Main"
}
```

### Related

- [`sidebar`](components/sidebar.md)
- [`sheet`](components/sheet.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Avatar

> A face or initials for one person, with an optional presence status.

- **id:** `avatar`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `display`

### Use when

- Show who wrote a message, who owns a task, or who is in a thread

### Don't use when

- A group of faces in one circle (use avatar-group-grid)

### Accessibility

- Named by the person unless decorative.
- Image URLs pass the untrusted image policy.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `name` | string | yes | untrusted | — | — |
| `src` | string | no | untrusted | — | — |
| `srcTrust` | enum(developer | untrusted) | no | — | `"untrusted"` | — |
| `srcset` | string | no | untrusted | — | — |
| `sizes` | string | no | — | — | — |
| `size` | enum(xs | sm | md | lg) | no | — | `"md"` | — |
| `tone` | enum(primary | success | warning | destructive | info | neutral) | no | — | — | — |
| `color` | enum(none | chart-1 | chart-2 | chart-3 | chart-4 | chart-5 | chart-6 | chart-7 | chart-8) | no | — | `"none"` | — |
| `shape` | enum(circle | square) | no | — | — | — |
| `status` | enum(online | away | busy | offline) | no | — | — | — |
| `decorative` | boolean | no | — | `false` | — |
| `delayMs` | number | no | — | `0` | — |
| `initials` | string | no | — | — | — |
| `class` | string | no | — | — | — |

### Examples

#### Named person (`person`)

```json
{
  "name": "Ada Example",
  "size": "md"
}
```

### Related

- [`avatar-group-grid`](components/avatar-group-grid.md)
- [`list-item`](components/list-item.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# AvatarGroupGrid

> Up to four faces in one avatar circle, +N past four.

- **id:** `avatar-group-grid`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `display`

### Use when

- A group chat shown as one avatar

### Don't use when

- A row of people (use AvatarGroup)

### Accessibility

- One image named by label or the member names.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `items` | array | yes | — | — | { name, src?, srcset? }[] |
| `size` | enum(xs | sm | md | lg) | no | — | `"md"` | — |
| `label` | string | no | — | — | Accessible name |
| `overflowLabel` | string | no | — | `"+{n}"` | — |
| `class` | string | no | — | — | — |

### Examples

#### Group chat (`chat`)

```json
{
  "items": [
    {
      "name": "Ada"
    },
    {
      "name": "Lin"
    }
  ]
}
```

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Badge

> A compact status or category label.

- **id:** `badge`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `display`

### Use when

- Show a short status or category next to a title

### Don't use when

- A removable filter (use tag)
- A toggleable filter chip (use chip)

### Accessibility

- Never convey meaning by color alone; pair with a word.
- In a catalog tree, set label (or put the word in an inline-text child).

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `variant` | enum(default | secondary | outline | success | warning | destructive | info | neutral) | no | — | `"default"` | — |
| `color` | enum(none | chart-1 | chart-2 | chart-3 | chart-4 | chart-5 | chart-6 | chart-7 | chart-8) | no | — | `"none"` | — |
| `label` | string | no | — | — | Plain-text badge word, escaped; replaces children when both are given |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | The badge word (an inline-text node in a tree) |

### Examples

#### Success badge (`success`)

```json
{
  "variant": "success"
}
```

#### Labelled badge (`labelled`)

```json
{
  "variant": "info",
  "label": "Shipped"
}
```

### Related

- [`tag`](components/tag.md)
- [`chip`](components/chip.md)
- [`inline-text`](components/inline-text.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Banner

> Full-width notice across a page or app shell.

- **id:** `banner`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `display`

### Use when

- Announce a global condition (maintenance, trial)

### Don't use when

- Inline field errors (use alert near the field)

### Accessibility

- Same tone roles as Alert; dismiss control is optional and named.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `tone` | enum(info | success | warning | error | brand | neutral) | no | — | `"info"` | — |
| `title` | string | no | — | — | Optional heading |
| `text` | string | no | untrusted | — | Body copy |
| `hideIcon` | boolean | no | — | `false` | — |
| `icon` | slot | no | — | — | Custom icon snippet |
| `actionLabel` | string | no | — | — | — |
| `actionHref` | string | no | developer | — | Optional action link (URL policy) |
| `onAction` | event | no | — | — | — |
| `dismissible` | boolean | no | — | `false` | — |
| `dismissLabel` | string | no | — | `"Dismiss"` | — |
| `onDismiss` | event | no | — | — | — |
| `class` | string | no | — | — | — |

### Examples

#### Brand banner (`brand`)

```json
{
  "tone": "brand",
  "title": "New workspace",
  "text": "Invite teammates from Settings.",
  "dismissible": true
}
```

### Related

- [`alert`](components/alert.md)
- [`callout`](components/callout.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Code blocks

> Validated, highlighted code.

- **id:** `blocks-code`
- **package:** `@texuli/blocks`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `content`

### Use when

- Render code blocks from structured content data.

### Don't use when

- Application navigation, account controls or mutations.

### Accessibility

- Provide the required accessible title, description or text alternatives.
- Keep data available in the component-provided text or table alternative.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `block` | object | yes | untrusted | — | Untrusted block data validated by the component before rendering. |
| `labels` | object | no | — | — | — |
| `oninvalid` | event | no | — | — | Host-provided callback; omit when no host behavior is needed. |
| `lineNumbers` | boolean | no | — | — | — |
| `highlights` | array | no | — | — | — |
| `hostStep` | number | no | — | — | — |
| `step` | number | no | — | — | — |
| `copyable` | boolean | no | — | — | — |

### Examples

#### Code blocks example (`basic`)

```json
{
  "block": {
    "type": "code",
    "code": "n = 1"
  }
}
```

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Data blocks

> Validated tables, statistics, key metrics and chart content blocks.

- **id:** `blocks-data`
- **package:** `@texuli/blocks`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `content`

### Use when

- Render data blocks from structured content data.

### Don't use when

- Application navigation, account controls or mutations.

### Accessibility

- Provide the required accessible title, description or text alternatives.
- Keep data available in the component-provided text or table alternative.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `block` | object | yes | untrusted | — | Untrusted block data validated by the component before rendering. |
| `labels` | object | no | — | — | — |
| `oninvalid` | event | no | — | — | Host-provided callback; omit when no host behavior is needed. |
| `mode` | enum(light | dark) | no | — | — | — |

### Examples

#### Data blocks example (`basic`)

```json
{
  "block": {
    "type": "stat",
    "items": [
      {
        "label": "Active",
        "value": "128"
      }
    ]
  }
}
```

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Diagram blocks

> Validated flow, tree, board and terminal diagrams.

- **id:** `blocks-diagram`
- **package:** `@texuli/blocks`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `content`

### Use when

- Render diagram blocks from structured content data.

### Don't use when

- Application navigation, account controls or mutations.

### Accessibility

- Provide the required accessible title, description or text alternatives.
- Keep data available in the component-provided text or table alternative.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `block` | object | yes | untrusted | — | Untrusted block data validated by the component before rendering. |
| `oninvalid` | event | no | — | — | Host-provided callback; omit when no host behavior is needed. |

### Examples

#### Diagram blocks example (`basic`)

```json
{
  "block": {
    "type": "flow",
    "nodes": [
      {
        "id": "plan",
        "label": "Plan"
      }
    ],
    "edges": []
  }
}
```

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Embed blocks

> Validated link previews (URL policy) and embed-app shells. Texuli never runs app JSON; hosts mount via mountEmbed with a sandboxed iframe contract.

- **id:** `blocks-embed`
- **package:** `@texuli/blocks`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `content`

### Use when

- Show a deferred mini-app shell where the host mounts after user Start.
- Show an offline link preview with HTTPS-only href (URL policy).

### Don't use when

- Application navigation, account controls or mutations.
- Running untrusted app JSON with innerHTML, eval, or an unsandboxed iframe.
- Relaxing iframe sandbox (especially adding allow-same-origin) or skipping CSP frame-src / postMessage origin checks.

### Accessibility

- Start control is a real button; nothing loads until activation.
- Iframe title (when used) names the embedded app; host must keep keyboard access inside the frame.
- Link previews use rel=noopener noreferrer on new-window links.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `block` | object | yes | untrusted | — | Untrusted block data validated by the component before rendering. |
| `mountEmbed` | event | no | — | — | Host runtime after user Start. Prefer createSandboxedEmbedMount (sandbox without allow-same-origin, referrerpolicy=no-referrer, HTTPS allowlist). Host CSP frame-src + postMessage origin checks required; never relax sandbox or inject HTML from app data. |
| `labels` | object | no | — | — | — |
| `oninvalid` | event | no | — | — | Host-provided callback; omit when no host behavior is needed. |

### Examples

#### Embed blocks example (`basic`)

```json
{
  "block": {
    "type": "link-preview",
    "href": "https://example.com/guide",
    "title": "Product guide"
  }
}
```

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Interactive blocks

> Validated polls, quizzes, calculators and checklists.

- **id:** `blocks-interactive`
- **package:** `@texuli/blocks`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `content`

### Use when

- Render interactive blocks from structured content data.

### Don't use when

- Application navigation, account controls or mutations.

### Accessibility

- Provide the required accessible title, description or text alternatives.
- Keep data available in the component-provided text or table alternative.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `block` | object | yes | untrusted | — | Untrusted block data validated by the component before rendering. |
| `labels` | object | no | — | — | — |
| `oninvalid` | event | no | — | — | Host-provided callback; omit when no host behavior is needed. |

### Examples

#### Interactive blocks example (`basic`)

```json
{
  "block": {
    "type": "checklist",
    "items": [
      {
        "id": "a",
        "label": "Plan"
      }
    ]
  }
}
```

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Map blocks

> Validated map points and routes.

- **id:** `blocks-map`
- **package:** `@texuli/blocks`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `content`

### Use when

- Render map blocks from structured content data.

### Don't use when

- Application navigation, account controls or mutations.

### Accessibility

- Provide the required accessible title, description or text alternatives.
- Keep data available in the component-provided text or table alternative.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `block` | object | yes | untrusted | — | Untrusted block data validated by the component before rendering. |
| `labels` | object | no | — | — | — |
| `locale` | string | no | — | — | — |
| `headingLevel` | number | no | — | — | — |
| `oninvalid` | event | no | — | — | Host-provided callback; omit when no host behavior is needed. |

### Examples

#### Map blocks example (`basic`)

```json
{
  "block": {
    "type": "map",
    "label": "Depot",
    "points": [
      {
        "id": "a",
        "label": "Depot",
        "lng": 0,
        "lat": 0
      }
    ]
  }
}
```

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Media blocks

> Validated image, figure, video and gallery content blocks.

- **id:** `blocks-media`
- **package:** `@texuli/blocks`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `content`

### Use when

- Render media blocks from structured content data.

### Don't use when

- Application navigation, account controls or mutations.

### Accessibility

- Provide the required accessible title, description or text alternatives.
- Keep data available in the component-provided text or table alternative.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `block` | object | yes | untrusted | — | Untrusted block data validated by the component before rendering. |
| `labels` | object | no | — | — | — |
| `resolveAvatar` | event | no | — | — | Host-provided callback; omit when no host behavior is needed. |
| `oninvalid` | event | no | — | — | Host-provided callback; omit when no host behavior is needed. |

### Examples

#### Media blocks example (`basic`)

```json
{
  "block": {
    "type": "image",
    "src": "images/team.webp",
    "alt": "A team planning together",
    "width": 960,
    "height": 540
  }
}
```

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Structure blocks

> Validated layouts and calls to action.

- **id:** `blocks-structure`
- **package:** `@texuli/blocks`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `content`

### Use when

- Render structure blocks from structured content data.

### Don't use when

- Application navigation, account controls or mutations.

### Accessibility

- Provide the required accessible title, description or text alternatives.
- Keep data available in the component-provided text or table alternative.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `block` | object | yes | untrusted | — | Untrusted block data validated by the component before rendering. |
| `labels` | object | no | — | — | — |
| `oninvalid` | event | no | — | — | Host-provided callback; omit when no host behavior is needed. |

### Examples

#### Structure blocks example (`basic`)

```json
{
  "block": {
    "type": "cta",
    "actions": [
      {
        "label": "Docs",
        "href": "https://example.com"
      }
    ]
  }
}
```

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Text blocks

> Validated heading, paragraph, list, quote and callout content.

- **id:** `blocks-text`
- **package:** `@texuli/blocks`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `content`

### Use when

- Render text blocks from structured content data.

### Don't use when

- Application navigation, account controls or mutations.

### Accessibility

- Provide the required accessible title, description or text alternatives.
- Keep data available in the component-provided text or table alternative.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `block` | object | yes | untrusted | — | Untrusted block data validated by the component before rendering. |
| `labels` | object | no | — | — | — |
| `oninvalid` | event | no | — | — | Host-provided callback; omit when no host behavior is needed. |

### Examples

#### Text blocks example (`basic`)

```json
{
  "block": {
    "type": "heading",
    "level": 2,
    "text": "Quarterly update"
  }
}
```

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# BottomNav

> A mobile tab bar of destinations. Host chrome; agents never emit it.

- **id:** `bottom-nav`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `layouts`

### Use when

- Primary destinations on a phone-sized app shell

### Don't use when

- In-page tabs (use tabs)
- Desktop sidebar navigation (use layout-sidebar)

### Accessibility

- A labelled nav landmark; the current destination uses aria-current, not color alone.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `items` | array | yes | — | — | Destinations: href, label, optional icon and badge |
| `label` | string | no | — | — | Accessible name of the landmark |
| `fixed` | boolean | no | — | `false` | — |
| `hrefTrust` | enum(developer | untrusted) | no | — | `"developer"` | — |
| `onSelect` | event | no | — | — | A destination was activated |
| `class` | string | no | — | — | — |

### Examples

#### Primary destinations (`primary`)

```json
{
  "items": [
    {
      "id": "home",
      "href": "/home",
      "label": "Home"
    },
    {
      "id": "inbox",
      "href": "/inbox",
      "label": "Inbox"
    }
  ]
}
```

### Related

- [`mobile-header`](components/mobile-header.md)
- [`tabs`](components/tabs.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Box

> A panel or region with layout options and token-based surface or color-reference fill.

- **id:** `box`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `display`

### Use when

- Frame a group of content as a bordered or filled panel
- Space and surface a region in a locked prototype, where visual utilities are refused

### Don't use when

- A clickable surface (use card with href)
- Page layout (use a layout)

### Accessibility

- Not interactive. Use as="section" or "aside" with a heading for a landmark-like region.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `as` | enum(div | section | article | aside | header | footer) | no | — | `"div"` | — |
| `padding` | enum(none | sm | md | lg | xl) | no | — | `"md"` | — |
| `radius` | enum(none | sm | md | lg | xl | full) | no | — | `"md"` | — |
| `border` | enum(none | default | strong | block-start | block-end | inline-start | inline-end | dashed) | no | — | `"none"` | All sides, one logical side (block-start, block-end, inline-start, inline-end), or dashed |
| `elevation` | enum(none | sm | md | lg) | no | — | `"none"` | — |
| `surface` | enum(transparent | default | muted | subtle | elevated | canvas | primary | brand | success | warning | destructive | info | primary-soft | translucent) | no | — | `"transparent"` | The surface (the variant axis): primary is solid, the semantic tones and primary-soft use soft token fills with AA ink, and translucent is glass for sticky headers |
| `fill` | enum(none | chart-1 | chart-2 | chart-3 | chart-4 | chart-5 | chart-6 | chart-7 | chart-8 | primary | secondary | success | warning | destructive | info | neutral) | no | — | `"none"` | Optional closed token reference (chart-1 through chart-8 or a semantic color role); never a CSS color or arbitrary value |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | The panel content |

### Examples

#### Bordered panel (`bordered`)

```json
{
  "padding": "lg",
  "border": "default",
  "surface": "default"
}
```

#### Muted region (`muted`)

```json
{
  "padding": "md",
  "radius": "lg",
  "surface": "muted"
}
```

#### App header (no card chrome) (`app-header`)

```json
{
  "as": "header",
  "padding": "md",
  "radius": "none",
  "border": "block-end",
  "surface": "default"
}
```

#### Brand logo tile (`logo-tile`)

```json
{
  "padding": "md",
  "radius": "lg",
  "surface": "primary"
}
```

#### Page canvas (`page-canvas`)

```json
{
  "as": "div",
  "padding": "lg",
  "radius": "none",
  "surface": "canvas"
}
```

#### Translucent sticky header (`sticky-header`)

```json
{
  "as": "header",
  "padding": "md",
  "radius": "none",
  "border": "block-end",
  "surface": "translucent"
}
```

#### Dashed panel (`dashed`)

```json
{
  "padding": "md",
  "border": "dashed",
  "surface": "default"
}
```

### Related

- [`card`](components/card.md)
- [`heading`](components/heading.md)
- [`text`](components/text.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Breadcrumb

> Hierarchy trail with URL-policy links.

- **id:** `breadcrumb`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `overlays`

### Use when

- Show location in a hierarchy

### Don't use when

- Primary navigation (use navigation-menu or sidebar)

### Accessibility

- nav landmark; current page is not a link.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `items` | array | yes | — | — | BreadcrumbItem[] |
| `label` | string | no | — | `"Breadcrumb"` | — |
| `size` | enum(sm | md | lg) | no | — | `"md"` | — |
| `separatorLabel` | string | no | — | `"Separator"` | — |
| `separator` | slot | no | — | — | — |
| `maxItems` | number | no | — | `0` | — |
| `hrefTrust` | enum(developer | untrusted) | no | developer | `"developer"` | — |
| `class` | string | no | — | — | — |

### Examples

#### Trail (`trail`)

```json
{
  "items": [
    {
      "label": "Workspace",
      "href": "https://example.com"
    },
    {
      "label": "Notes",
      "href": "https://example.com/notes"
    },
    {
      "label": "Harbor"
    }
  ]
}
```

### Related

- [`navigation-menu`](components/navigation-menu.md)
- [`pagination`](components/pagination.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Button

> A pressable action control with loading and optional link rendering.

- **id:** `button`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `forms`

### Use when

- Primary and secondary actions
- Submit and reset controls in forms

### Don't use when

- An icon-only control (use icon-button)
- A toggleable filter chip (use chip)
- Navigation that is not an action (use a link or nav item)

### Accessibility

- Real button or link element with an accessible name
- Busy state exposes aria-busy and aria-disabled, keeps focus and blocks further activation
- Rejected href schemes render as a non-interactive control

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `variant` | enum(default | secondary | outline | ghost | destructive | link) | no | — | `"default"` | — |
| `size` | enum(sm | md | lg | icon) | no | — | `"md"` | — |
| `tone` | enum(default | destructive | success | warning) | no | — | `"default"` | — |
| `href` | string | no | developer | — | Optional link target (URL policy) |
| `hrefTrust` | enum(developer | untrusted) | no | — | `"developer"` | — |
| `type` | enum(button | submit | reset) | no | — | `"button"` | — |
| `disabled` | boolean | no | — | `false` | — |
| `loading` | boolean | no | — | `false` | — |
| `loadingLabel` | string | no | — | — | Accessible name while loading |
| `autoLoading` | boolean | no | — | `true` | Show pending when onclick returns a promise |
| `label` | string | no | — | — | Plain-text label, escaped; replaces children when both are given |
| `onclick` | event | no | — | — | Activated handler; may return a promise |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | The visible label (an inline-text node in a tree) |

### Examples

#### Default button (`default`)

```json
{
  "variant": "default"
}
```

#### Outline destructive button (`outline-destructive`)

```json
{
  "variant": "outline",
  "tone": "destructive",
  "label": "Delete"
}
```

#### Loading button (`loading`)

```json
{
  "loading": true,
  "loadingLabel": "Saving"
}
```

#### Labelled submit button (`labelled`)

```json
{
  "type": "submit",
  "label": "Save changes"
}
```

### Related

- [`icon-button`](components/icon-button.md)
- [`button-group`](components/button-group.md)
- [`form`](components/form.md)
- [`inline-text`](components/inline-text.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# ButtonGroup

> Groups related buttons with shared borders and orientation.

- **id:** `button-group`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `forms`

### Use when

- Cluster related actions that share a single decision

### Don't use when

- Unrelated actions across a toolbar (use a plain flex row)

### Accessibility

- role=group with an optional accessible label.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `orientation` | enum(horizontal | vertical) | no | — | `"horizontal"` | — |
| `attached` | boolean | no | — | `true` | Share borders between buttons |
| `label` | string | no | — | — | Accessible name for the group |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | — |

### Examples

#### Attached horizontal group (`attached`)

```json
{
  "orientation": "horizontal",
  "attached": true,
  "label": "View mode"
}
```

### Related

- [`button`](components/button.md)
- [`icon-button`](components/icon-button.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Callout

> Emphasized documentation-style tip with a strong start edge.

- **id:** `callout`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `display`

### Use when

- Highlight a tip or note beside prose

### Don't use when

- A blocking error (use alert with error tone)
- A site-wide notice (use banner)

### Accessibility

- Same tone roles as Alert; never color-only meaning.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `tone` | enum(info | success | warning | error | brand | neutral) | no | — | `"info"` | — |
| `title` | string | no | — | — | Optional heading |
| `text` | string | no | untrusted | — | Body copy |
| `hideIcon` | boolean | no | — | `false` | — |
| `icon` | slot | no | — | — | Custom icon snippet |
| `actionLabel` | string | no | — | — | — |
| `actionHref` | string | no | developer | — | Optional action link (URL policy) |
| `onAction` | event | no | — | — | — |
| `dismissible` | boolean | no | — | `false` | — |
| `dismissLabel` | string | no | — | `"Dismiss"` | — |
| `onDismiss` | event | no | — | — | — |
| `class` | string | no | — | — | — |

### Examples

#### Info callout (`info-tip`)

```json
{
  "tone": "info",
  "title": "Tip",
  "text": "Export works offline in this prototype."
}
```

### Related

- [`alert`](components/alert.md)
- [`banner`](components/banner.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Canvas

> A whiteboard or diagram as data: shapes, sticky notes, text, frames, groups and connectors on an infinite canvas.

- **id:** `canvas`
- **package:** `@texuli/canvas`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `canvas`

### Use when

- Sketch a flow, a map of ideas, a retro board or an architecture diagram people can keep editing
- Lay out sticky notes in frames and connect shapes with arrows

### Don't use when

- A workflow with typed ports that runs: use workflow-graph
- A chart of data: use a chart family
- Prose: use document

### Accessibility

- Painted as an image named by the canvas title, with every shape and connector listed as text in reading order
- Text is data, never HTML; image refs pass the URL policy at the host tier
- Styles are a closed palette of theme tokens, never raw CSS

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `canvas` | object | yes | — | — | A Texuli canvas: { format: "texuli-canvas", formatVersion: 1, meta: { title }, shapes, connectors }. Shapes: rect, ellipse, diamond, line, arrow, path (points), text, sticky, image ({ ref, alt }), frame ({ title, children }) and group ({ children }), each with an id and x, y, width, height. Connectors: { id, from: { shape }, to: { shape }, routing: straight \| elbow \| curved, text }. |
| `label` | string | no | untrusted | — | Accessible name; defaults to the canvas title. |

### Examples

#### Decision flow (`decision`)

```json
{
  "canvas": {
    "format": "texuli-canvas",
    "formatVersion": 1,
    "meta": {
      "title": "Release decision"
    },
    "shapes": [
      {
        "id": "ask",
        "type": "ellipse",
        "x": 0,
        "y": 0,
        "width": 160,
        "height": 72,
        "text": "Ready to ship?"
      },
      {
        "id": "ship",
        "type": "rect",
        "x": 240,
        "y": 0,
        "width": 160,
        "height": 72,
        "text": "Ship on example.com"
      },
      {
        "id": "idea",
        "type": "sticky",
        "x": 0,
        "y": 120,
        "width": 160,
        "height": 120,
        "text": "Ask the beta testers",
        "color": "yellow"
      }
    ],
    "connectors": [
      {
        "id": "yes",
        "from": {
          "shape": "ask"
        },
        "to": {
          "shape": "ship"
        },
        "routing": "curved",
        "text": "yes"
      }
    ]
  }
}
```

### Related

- [`document`](components/document.md)
- [`workflow-graph`](components/workflow-graph.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Card

> A surface for grouping related content with optional stretched-link behavior.

- **id:** `card`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `display`

### Use when

- Group related content in a bordered surface
- Make a whole tile a single link

### Don't use when

- A single line of chrome (use badge or button)
- A data grid of many rows (use table)

### Accessibility

- When href is set, one real link covers the card; nested actions sit above it
- Rejected href schemes render as a non-interactive surface

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `variant` | enum(elevated | flat) | no | — | `"elevated"` | Visual elevation |
| `href` | string | no | developer | — | Optional link target (URL policy) |
| `hrefTrust` | enum(developer | untrusted) | no | — | `"developer"` | — |
| `linkLabel` | string | no | — | — | Accessible name of the stretched primary link |
| `actions` | slot | no | — | — | Secondary actions (pin, menu) above the stretched link |
| `class` | string | no | — | — | Extra classes |

### Examples

#### Elevated card (`elevated`)

```json
{
  "variant": "elevated"
}
```

#### Linked card (`linked`)

```json
{
  "variant": "flat",
  "href": "https://example.com/docs",
  "linkLabel": "Open documentation"
}
```

### Related

- [`button`](components/button.md)
- [`stat`](components/stat.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Carousel

> A labelled region of slides with previous, next and a picker.

- **id:** `carousel`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `display`

### Use when

- A few slides the person pages through, such as quotes or screenshots

### Don't use when

- A gallery of images with a lightbox (use media-image)
- Tabs (use tabs)

### Accessibility

- APG carousel: a named region, arrow keys, and a tablist when dots are shown.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `items` | array | yes | — | — | { id, label }[] in display order |
| `index` | number | no | — | `0` | — |
| `label` | string | no | — | — | — |
| `showControls` | boolean | no | — | `true` | — |
| `showDots` | boolean | no | — | `true` | — |
| `controls` | enum(below | overlay) | no | — | `"below"` | — |
| `loop` | boolean | no | — | `true` | — |
| `class` | string | no | — | — | — |

### Examples

#### Quotes (`quotes`)

```json
{
  "label": "Customer quotes",
  "items": [
    {
      "id": "a",
      "label": "Ada Example"
    },
    {
      "id": "b",
      "label": "Lin Example"
    }
  ]
}
```

### Related

- [`card`](components/card.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Area chart

> A categorical area chart with an accessible data table.

- **id:** `charts-area`
- **package:** `@texuli/charts`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `content`

### Use when

- Render area chart from structured content data.

### Don't use when

- Application navigation, account controls or mutations.

### Accessibility

- Provide the required accessible title, description or text alternatives.
- Keep data available in the component-provided text or table alternative.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `title` | string | yes | — | — | — |
| `description` | string | yes | — | — | — |
| `series` | array | yes | — | — | — |
| `mode` | enum(light | dark) | no | — | — | — |
| `renderer` | enum(svg | canvas | auto) | no | — | — | — |
| `class` | string | no | — | — | — |
| `interactive` | string | no | — | — | — |
| `fullDomain` | string | no | — | — | — |
| `visibleDomain` | string | no | — | — | — |
| `annotations` | string | no | — | — | — |
| `xKind` | enum(linear | category | time) | no | — | — | How x values read: category bands, a linear number scale, or time (x in epoch milliseconds, shown as UTC dates in locale). Omit to infer. |
| `locale` | string | no | — | — | BCP 47 language tag for dates and announced values, such as en-US. |

### Examples

#### Area chart example (`basic`)

```json
{
  "title": "Weekly activity",
  "description": "Activity by week",
  "series": []
}
```

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Bar chart

> A categorical bar chart with a zero baseline and accessible data table.

- **id:** `charts-bar`
- **package:** `@texuli/charts`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `content`

### Use when

- Render bar chart from structured content data.

### Don't use when

- Application navigation, account controls or mutations.

### Accessibility

- Provide the required accessible title, description or text alternatives.
- Keep data available in the component-provided text or table alternative.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `title` | string | yes | — | — | — |
| `description` | string | yes | — | — | — |
| `series` | array | yes | — | — | — |
| `mode` | enum(light | dark) | no | — | — | — |
| `renderer` | enum(svg | canvas | auto) | no | — | — | — |
| `class` | string | no | — | — | — |
| `interactive` | string | no | — | — | — |
| `fullDomain` | string | no | — | — | — |
| `visibleDomain` | string | no | — | — | — |
| `annotations` | string | no | — | — | — |
| `xKind` | enum(linear | category | time) | no | — | — | How x values read: category bands, a linear number scale, or time (x in epoch milliseconds, shown as UTC dates in locale). Omit to infer. |
| `locale` | string | no | — | — | BCP 47 language tag for dates and announced values, such as en-US. |

### Examples

#### Bar chart example (`basic`)

```json
{
  "title": "Weekly activity",
  "description": "Activity by week",
  "series": []
}
```

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Bubble chart

> A scatter plot where point size can encode another measure.

- **id:** `charts-bubble`
- **package:** `@texuli/charts`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `content`

### Use when

- Render bubble chart from structured content data.

### Don't use when

- Application navigation, account controls or mutations.

### Accessibility

- Provide the required accessible title, description or text alternatives.
- Keep data available in the component-provided text or table alternative.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `title` | string | yes | — | — | — |
| `description` | string | yes | — | — | — |
| `points` | array | yes | — | — | — |
| `series` | array | no | — | — | — |
| `mode` | enum(light | dark) | no | — | — | — |
| `interactive` | string | no | — | — | — |
| `class` | string | no | — | — | — |
| `width` | number | no | — | — | — |
| `height` | number | no | — | — | — |
| `annotations` | string | no | — | — | — |

### Examples

#### Bubble chart example (`basic`)

```json
{
  "title": "Usage and reach",
  "description": "Usage compared with reach",
  "points": []
}
```

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Bullet chart

> A compact value, range and target comparison.

- **id:** `charts-bullet`
- **package:** `@texuli/charts`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `content`

### Use when

- Render bullet chart from structured content data.

### Don't use when

- Application navigation, account controls or mutations.

### Accessibility

- Provide the required accessible title, description or text alternatives.
- Keep data available in the component-provided text or table alternative.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `label` | string | yes | — | — | — |
| `description` | string | no | — | — | — |
| `value` | number | yes | — | — | — |
| `max` | number | no | — | — | — |
| `target` | number | no | — | — | — |
| `ranges` | array | no | — | — | — |
| `format` | object | no | — | — | — |
| `labels` | object | no | — | — | — |

### Examples

#### Bullet chart example (`basic`)

```json
{
  "label": "Release progress",
  "value": 68,
  "max": 100,
  "target": 75
}
```

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Canvas chart renderer

> A low-level canvas mark renderer for dense chart series.

- **id:** `charts-canvas-renderer`
- **package:** `@texuli/charts`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `content`

### Use when

- Render canvas chart renderer from structured content data.

### Don't use when

- Application navigation, account controls or mutations.

### Accessibility

- Provide the required accessible title, description or text alternatives.
- Keep data available in the component-provided text or table alternative.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `kind` | enum(line | area | bar | stacked-bar | combo) | yes | — | — | — |
| `series` | array | yes | — | — | — |
| `width` | number | yes | — | — | — |
| `height` | number | yes | — | — | — |

### Examples

#### Canvas chart renderer example (`basic`)

```json
{
  "kind": "line",
  "series": [],
  "width": 640,
  "height": 320
}
```

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Cartesian chart

> The general line, area, bar, stacked bar or combo chart renderer.

- **id:** `charts-cartesian`
- **package:** `@texuli/charts`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `content`

### Use when

- Render cartesian chart from structured content data.

### Don't use when

- Application navigation, account controls or mutations.

### Accessibility

- Provide the required accessible title, description or text alternatives.
- Keep data available in the component-provided text or table alternative.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `kind` | enum(line | area | bar | stacked-bar | combo) | yes | — | — | — |
| `title` | string | yes | — | — | — |
| `description` | string | yes | — | — | — |
| `series` | array | yes | — | — | — |
| `mode` | enum(light | dark) | no | — | — | — |
| `class` | string | no | — | — | — |
| `renderer` | enum(svg | canvas | auto) | no | — | — | — |
| `interactive` | string | no | — | — | — |
| `fullDomain` | string | no | — | — | — |
| `visibleDomain` | string | no | — | — | — |
| `annotations` | string | no | — | — | — |
| `xKind` | enum(linear | category | time) | no | — | — | How x values read: category bands, a linear number scale, or time (x in epoch milliseconds, shown as UTC dates in locale). Omit to infer. |
| `locale` | string | no | — | — | BCP 47 language tag for dates and announced values, such as en-US. |

### Examples

#### Cartesian chart example (`basic`)

```json
{
  "kind": "line",
  "title": "Weekly activity",
  "description": "Activity by week",
  "series": []
}
```

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Combo chart

> A categorical chart that combines bar and line series.

- **id:** `charts-combo`
- **package:** `@texuli/charts`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `content`

### Use when

- Render combo chart from structured content data.

### Don't use when

- Application navigation, account controls or mutations.

### Accessibility

- Provide the required accessible title, description or text alternatives.
- Keep data available in the component-provided text or table alternative.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `title` | string | yes | — | — | — |
| `description` | string | yes | — | — | — |
| `series` | array | yes | — | — | — |
| `mode` | enum(light | dark) | no | — | — | — |
| `renderer` | enum(svg | canvas | auto) | no | — | — | — |
| `class` | string | no | — | — | — |
| `interactive` | string | no | — | — | — |
| `fullDomain` | string | no | — | — | — |
| `visibleDomain` | string | no | — | — | — |
| `annotations` | string | no | — | — | — |
| `xKind` | enum(linear | category | time) | no | — | — | How x values read: category bands, a linear number scale, or time (x in epoch milliseconds, shown as UTC dates in locale). Omit to infer. |
| `locale` | string | no | — | — | BCP 47 language tag for dates and announced values, such as en-US. |

### Examples

#### Combo chart example (`basic`)

```json
{
  "title": "Revenue and orders",
  "description": "Revenue and orders by month",
  "series": []
}
```

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Donut chart

> A part-to-whole chart with a central opening and data table.

- **id:** `charts-donut`
- **package:** `@texuli/charts`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `content`

### Use when

- Render donut chart from structured content data.

### Don't use when

- Application navigation, account controls or mutations.

### Accessibility

- Provide the required accessible title, description or text alternatives.
- Keep data available in the component-provided text or table alternative.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `title` | string | yes | — | — | — |
| `description` | string | yes | — | — | — |
| `data` | array | yes | — | — | — |
| `labels` | object | yes | — | — | — |
| `size` | number | no | — | — | — |
| `innerRatio` | string | no | — | — | — |
| `padAngle` | string | no | — | — | — |

### Examples

#### Donut chart example (`basic`)

```json
{
  "title": "Tickets by status",
  "description": "Ticket distribution",
  "data": [],
  "labels": {}
}
```

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Funnel chart

> A conversion funnel with step values and accessible table.

- **id:** `charts-funnel`
- **package:** `@texuli/charts`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `content`

### Use when

- Render funnel chart from structured content data.

### Don't use when

- Application navigation, account controls or mutations.

### Accessibility

- Provide the required accessible title, description or text alternatives.
- Keep data available in the component-provided text or table alternative.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `title` | string | yes | — | — | — |
| `description` | string | no | — | — | — |
| `steps` | array | yes | — | — | — |
| `orientation` | enum(vertical | horizontal) | no | — | — | — |
| `width` | number | no | — | — | — |
| `height` | number | no | — | — | — |
| `labels` | object | no | — | — | — |
| `class` | string | no | — | — | — |

### Examples

#### Funnel chart example (`basic`)

```json
{
  "title": "Signup conversion",
  "steps": [
    {
      "id": "visit",
      "label": "Visits",
      "value": 800
    }
  ]
}
```

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Gauge chart

> A radial value gauge with thresholds and an accessible data table.

- **id:** `charts-gauge`
- **package:** `@texuli/charts`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `content`

### Use when

- Render gauge chart from structured content data.

### Don't use when

- Application navigation, account controls or mutations.

### Accessibility

- Provide the required accessible title, description or text alternatives.
- Keep data available in the component-provided text or table alternative.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `label` | string | yes | — | — | — |
| `description` | string | no | — | — | — |
| `value` | number | yes | — | — | — |
| `min` | number | no | — | — | — |
| `max` | number | no | — | — | — |
| `thresholds` | array | no | — | — | — |
| `bandLabels` | array | no | — | — | — |
| `format` | object | no | — | — | — |
| `size` | number | no | — | — | — |
| `thickness` | number | no | — | — | — |
| `labels` | object | no | — | — | — |

### Examples

#### Gauge chart example (`basic`)

```json
{
  "label": "Service health",
  "value": 92,
  "min": 0,
  "max": 100
}
```

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Geographic map

> A tiled geographic choropleth with a tabular data alternative.

- **id:** `charts-geo-map`
- **package:** `@texuli/charts`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `content`

### Use when

- Render geographic map from structured content data.

### Don't use when

- Application navigation, account controls or mutations.

### Accessibility

- Provide the required accessible title, description or text alternatives.
- Keep data available in the component-provided text or table alternative.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `title` | string | yes | — | — | — |
| `description` | string | yes | — | — | — |
| `data` | object | yes | — | — | — |
| `shape` | array | no | — | — | — |
| `labels` | object | no | — | — | — |
| `width` | number | no | — | — | — |
| `height` | number | no | — | — | — |

### Examples

#### Geographic map example (`basic`)

```json
{
  "title": "Orders by region",
  "description": "Regional order totals",
  "data": {}
}
```

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Geographic point map

> Geographic points positioned on a tiled map.

- **id:** `charts-geo-point-map`
- **package:** `@texuli/charts`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `content`

### Use when

- Render geographic point map from structured content data.

### Don't use when

- Application navigation, account controls or mutations.

### Accessibility

- Provide the required accessible title, description or text alternatives.
- Keep data available in the component-provided text or table alternative.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `title` | string | yes | — | — | — |
| `description` | string | yes | — | — | — |
| `points` | array | yes | — | — | — |
| `shape` | array | no | — | — | — |
| `labels` | object | no | — | — | — |
| `width` | number | no | — | — | — |
| `height` | number | no | — | — | — |

### Examples

#### Geographic point map example (`basic`)

```json
{
  "title": "Locations",
  "description": "Sample locations",
  "points": []
}
```

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Heatmap

> A matrix of labeled cells with an accessible data table.

- **id:** `charts-heatmap`
- **package:** `@texuli/charts`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `content`

### Use when

- Render heatmap from structured content data.

### Don't use when

- Application navigation, account controls or mutations.

### Accessibility

- Provide the required accessible title, description or text alternatives.
- Keep data available in the component-provided text or table alternative.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `title` | string | yes | — | — | — |
| `description` | string | yes | — | — | — |
| `cells` | array | yes | — | — | — |
| `mode` | enum(light | dark) | no | — | — | — |
| `interactive` | string | no | — | — | — |
| `class` | string | no | — | — | — |
| `width` | number | no | — | — | — |
| `height` | number | no | — | — | — |
| `annotations` | string | no | — | — | — |

### Examples

#### Heatmap example (`basic`)

```json
{
  "title": "Weekly volume",
  "description": "Volume by day and hour",
  "cells": []
}
```

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Line chart

> A categorical line chart with accessible values.

- **id:** `charts-line`
- **package:** `@texuli/charts`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `content`

### Use when

- Render line chart from structured content data.

### Don't use when

- Application navigation, account controls or mutations.

### Accessibility

- Provide the required accessible title, description or text alternatives.
- Keep data available in the component-provided text or table alternative.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `title` | string | yes | — | — | — |
| `description` | string | yes | — | — | — |
| `series` | array | yes | — | — | — |
| `mode` | enum(light | dark) | no | — | — | — |
| `renderer` | enum(svg | canvas | auto) | no | — | — | — |
| `class` | string | no | — | — | — |
| `interactive` | string | no | — | — | — |
| `fullDomain` | string | no | — | — | — |
| `visibleDomain` | string | no | — | — | — |
| `annotations` | string | no | — | — | — |
| `xKind` | enum(linear | category | time) | no | — | — | How x values read: category bands, a linear number scale, or time (x in epoch milliseconds, shown as UTC dates in locale). Omit to infer. |
| `locale` | string | no | — | — | BCP 47 language tag for dates and announced values, such as en-US. |

### Examples

#### Line chart example (`basic`)

```json
{
  "title": "Weekly activity",
  "description": "Activity by week",
  "series": []
}
```

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Network graph

> A node and connection graph with an accessible table.

- **id:** `charts-network`
- **package:** `@texuli/charts`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `content`

### Use when

- Render network graph from structured content data.

### Don't use when

- Application navigation, account controls or mutations.

### Accessibility

- Provide the required accessible title, description or text alternatives.
- Keep data available in the component-provided text or table alternative.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `title` | string | yes | — | — | — |
| `description` | string | no | — | — | — |
| `nodes` | array | yes | — | — | — |
| `links` | array | yes | — | — | — |
| `width` | number | no | — | — | — |
| `height` | number | no | — | — | — |
| `labels` | object | no | — | — | — |
| `class` | string | no | — | — | — |

### Examples

#### Network graph example (`basic`)

```json
{
  "title": "Team dependencies",
  "nodes": [],
  "links": []
}
```

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Pie chart

> A part-to-whole chart with an accessible data table.

- **id:** `charts-pie`
- **package:** `@texuli/charts`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `content`

### Use when

- Render pie chart from structured content data.

### Don't use when

- Application navigation, account controls or mutations.

### Accessibility

- Provide the required accessible title, description or text alternatives.
- Keep data available in the component-provided text or table alternative.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `title` | string | yes | — | — | — |
| `description` | string | yes | — | — | — |
| `data` | array | yes | — | — | — |
| `labels` | object | yes | — | — | — |
| `size` | number | no | — | — | — |
| `innerRatio` | string | no | — | — | — |
| `padAngle` | string | no | — | — | — |

### Examples

#### Pie chart example (`basic`)

```json
{
  "title": "Tickets by status",
  "description": "Ticket distribution",
  "data": [],
  "labels": {}
}
```

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Progress ring

> A compact radial progress indicator with a data table.

- **id:** `charts-progress-ring`
- **package:** `@texuli/charts`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `content`

### Use when

- Render progress ring from structured content data.

### Don't use when

- Application navigation, account controls or mutations.

### Accessibility

- Provide the required accessible title, description or text alternatives.
- Keep data available in the component-provided text or table alternative.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `label` | string | yes | — | — | — |
| `description` | string | no | — | — | — |
| `value` | number | yes | — | — | — |
| `max` | number | no | — | — | — |
| `format` | object | no | — | — | — |
| `size` | number | no | — | — | — |
| `thickness` | number | no | — | — | — |
| `labels` | object | no | — | — | — |

### Examples

#### Progress ring example (`basic`)

```json
{
  "label": "Tasks complete",
  "value": 8,
  "max": 10
}
```

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Sankey chart

> A weighted flow diagram with an accessible table.

- **id:** `charts-sankey`
- **package:** `@texuli/charts`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `content`

### Use when

- Render sankey chart from structured content data.

### Don't use when

- Application navigation, account controls or mutations.

### Accessibility

- Provide the required accessible title, description or text alternatives.
- Keep data available in the component-provided text or table alternative.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `title` | string | yes | — | — | — |
| `description` | string | no | — | — | — |
| `nodes` | array | yes | — | — | — |
| `links` | array | yes | — | — | — |
| `width` | number | no | — | — | — |
| `height` | number | no | — | — | — |
| `labels` | object | no | — | — | — |
| `class` | string | no | — | — | — |

### Examples

#### Sankey chart example (`basic`)

```json
{
  "title": "Traffic sources",
  "nodes": [],
  "links": []
}
```

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Scatter chart

> A quantitative scatter plot with an accessible data table.

- **id:** `charts-scatter`
- **package:** `@texuli/charts`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `content`

### Use when

- Render scatter chart from structured content data.

### Don't use when

- Application navigation, account controls or mutations.

### Accessibility

- Provide the required accessible title, description or text alternatives.
- Keep data available in the component-provided text or table alternative.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `title` | string | yes | — | — | — |
| `description` | string | yes | — | — | — |
| `points` | array | yes | — | — | — |
| `series` | array | no | — | — | — |
| `mode` | enum(light | dark) | no | — | — | — |
| `interactive` | string | no | — | — | — |
| `class` | string | no | — | — | — |
| `width` | number | no | — | — | — |
| `height` | number | no | — | — | — |
| `annotations` | string | no | — | — | — |

### Examples

#### Scatter chart example (`basic`)

```json
{
  "title": "Usage and reach",
  "description": "Usage compared with reach",
  "points": []
}
```

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Sparkline

> A compact line, area or bar trend chart.

- **id:** `charts-sparkline`
- **package:** `@texuli/charts`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `content`

### Use when

- Render sparkline from structured content data.

### Don't use when

- Application navigation, account controls or mutations.

### Accessibility

- Provide the required accessible title, description or text alternatives.
- Keep data available in the component-provided text or table alternative.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `values` | array | yes | — | — | — |
| `label` | string | yes | — | — | — |
| `description` | string | no | — | — | — |
| `period` | string | no | — | — | — |
| `variant` | enum(line | area | bar) | no | — | `"line"` | — |
| `format` | object | no | — | — | — |
| `height` | number | no | — | — | — |
| `showLast` | boolean | no | — | — | — |
| `labels` | object | no | — | — | — |

### Examples

#### Sparkline example (`basic`)

```json
{
  "label": "Daily active users",
  "values": [
    18,
    21,
    19,
    26
  ]
}
```

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Stacked bar chart

> A categorical stacked bar chart with accessible values.

- **id:** `charts-stacked-bar`
- **package:** `@texuli/charts`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `content`

### Use when

- Render stacked bar chart from structured content data.

### Don't use when

- Application navigation, account controls or mutations.

### Accessibility

- Provide the required accessible title, description or text alternatives.
- Keep data available in the component-provided text or table alternative.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `title` | string | yes | — | — | — |
| `description` | string | yes | — | — | — |
| `series` | array | yes | — | — | — |
| `mode` | enum(light | dark) | no | — | — | — |
| `renderer` | enum(svg | canvas | auto) | no | — | — | — |
| `class` | string | no | — | — | — |
| `interactive` | string | no | — | — | — |
| `fullDomain` | string | no | — | — | — |
| `visibleDomain` | string | no | — | — | — |
| `annotations` | string | no | — | — | — |
| `xKind` | enum(linear | category | time) | no | — | — | How x values read: category bands, a linear number scale, or time (x in epoch milliseconds, shown as UTC dates in locale). Omit to infer. |
| `locale` | string | no | — | — | BCP 47 language tag for dates and announced values, such as en-US. |

### Examples

#### Stacked bar chart example (`basic`)

```json
{
  "title": "Weekly activity",
  "description": "Activity by week",
  "series": []
}
```

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Sunburst chart

> A hierarchical part-to-whole chart with an accessible table.

- **id:** `charts-sunburst`
- **package:** `@texuli/charts`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `content`

### Use when

- Render sunburst chart from structured content data.

### Don't use when

- Application navigation, account controls or mutations.

### Accessibility

- Provide the required accessible title, description or text alternatives.
- Keep data available in the component-provided text or table alternative.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `title` | string | yes | — | — | — |
| `description` | string | yes | — | — | — |
| `root` | object | yes | — | — | — |
| `labels` | object | yes | — | — | — |
| `size` | number | no | — | — | — |
| `innerRatio` | string | no | — | — | — |
| `padAngle` | string | no | — | — | — |

### Examples

#### Sunburst chart example (`basic`)

```json
{
  "title": "Revenue structure",
  "description": "Revenue by product group",
  "root": {
    "id": "root",
    "value": 0
  },
  "labels": {}
}
```

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Treemap chart

> A hierarchical part-to-whole chart with an accessible table.

- **id:** `charts-treemap`
- **package:** `@texuli/charts`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `content`

### Use when

- Render treemap chart from structured content data.

### Don't use when

- Application navigation, account controls or mutations.

### Accessibility

- Provide the required accessible title, description or text alternatives.
- Keep data available in the component-provided text or table alternative.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `title` | string | yes | — | — | — |
| `description` | string | yes | — | — | — |
| `root` | object | yes | — | — | — |
| `labels` | object | yes | — | — | — |
| `width` | number | no | — | — | — |
| `height` | number | no | — | — | — |
| `padding` | number | no | — | — | — |

### Examples

#### Treemap chart example (`basic`)

```json
{
  "title": "Revenue structure",
  "description": "Revenue by product group",
  "root": {
    "id": "root",
    "value": 0
  },
  "labels": {}
}
```

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Chat message

> One display-only chat message: author, role, time, text and block children.

- **id:** `chat-message`
- **package:** `@texuli/chat`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `chat`

### Use when

- Inside chat-thread, one per message

### Don't use when

- Outside a chat-thread
- For a reply box; that is host chrome

### Accessibility

- Renders an article named by author and time; the role is visible text
- Message text is plain text nodes; links pass the untrusted URL policy

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `author` | string | yes | untrusted | — | — |
| `role` | enum(user | agent | system) | yes | — | — | — |
| `at` | string | no | — | — | ISO 8601 time; omitted when it does not parse. |
| `text` | string | no | untrusted | — | Chat inline subset. |
| `children` | slot | no | — | — | blocks-* nodes. |

### Examples

#### Agent reply (`agent-reply`)

```json
{
  "author": "Fictional Agent",
  "role": "agent",
  "at": "2026-10-24T09:00:00Z",
  "text": "Two items are **blocked**."
}
```

### Related

- [`chat-thread`](components/chat-thread.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Chat thread

> Read-only conversation transcript of chat-message nodes, without a composer.

- **id:** `chat-thread`
- **package:** `@texuli/chat`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `chat`

### Use when

- Show a conversation an agent summarized or quoted
- Show a chat transcript inside a report or document

### Don't use when

- The person needs to reply: the host renders its own composer (host chrome)
- The content is not a conversation; use text blocks

### Accessibility

- Renders a labelled section; each message is an article with author and time
- Static: no live region, focus trap or keyboard handling is added

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `label` | string | no | untrusted | — | Accessible name. |
| `children` | slot | no | — | — | chat-message nodes. |

### Examples

#### Stand-up excerpt (`standup`)

```json
{
  "label": "Stand-up thread"
}
```

### Related

- [`chat-message`](components/chat-message.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Checkbox

> A binary or indeterminate checkbox with optional label.

- **id:** `checkbox`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `forms`

### Use when

- Independent on/off choices
- Select-all with indeterminate

### Don't use when

- A single exclusive choice in a set (use radio-group)
- A switch-style setting (use switch)

### Accessibility

- Visible label is wired with for; description uses aria-describedby.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `checked` | boolean | no | — | `false` | — |
| `defaultChecked` | boolean | no | — | `false` | — |
| `indeterminate` | boolean | no | — | `false` | — |
| `defaultIndeterminate` | boolean | no | — | `false` | — |
| `name` | string | no | — | — | — |
| `value` | string | no | — | `"on"` | — |
| `disabled` | boolean | no | — | `false` | — |
| `required` | boolean | no | — | `false` | — |
| `id` | string | no | — | — | — |
| `label` | string | no | — | — | — |
| `description` | string | no | — | — | — |
| `size` | enum(sm | md) | no | — | `"md"` | — |
| `onCheckedChange` | event | no | — | — | — |
| `onIndeterminateChange` | event | no | — | — | — |
| `class` | string | no | — | — | — |

### Examples

#### Labeled checkbox (`labeled`)

```json
{
  "label": "Subscribe to updates"
}
```

#### Indeterminate (`indeterminate`)

```json
{
  "indeterminate": true,
  "label": "Select all"
}
```

### Related

- [`switch`](components/switch.md)
- [`radio-group`](components/radio-group.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Chip

> A toggleable filter chip (pressed state).

- **id:** `chip`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `display`

### Use when

- Filter toggles in a toolbar or facet list

### Don't use when

- Navigation (use a link)
- A one-shot action (use button)

### Accessibility

- Uses aria-pressed for selection; must be a real button.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `label` | string | yes | — | — | — |
| `variant` | enum(default | secondary | outline | success | warning | destructive | info | neutral) | no | — | `"outline"` | — |
| `selected` | boolean | no | — | `false` | — |
| `disabled` | boolean | no | — | `false` | — |
| `type` | enum(button | submit | reset) | no | — | `"button"` | — |
| `class` | string | no | — | — | — |

### Examples

#### Selected chip (`selected`)

```json
{
  "label": "Active",
  "selected": true
}
```

### Related

- [`badge`](components/badge.md)
- [`tag`](components/tag.md)
- [`button`](components/button.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Code

> Inline or block code with escaped text (no HTML).

- **id:** `code`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `display`

### Use when

- Show a short code sample or token

### Don't use when

- A full syntax-highlighted editor

### Accessibility

- Text is always escaped; language is display-only metadata.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `value` | string | no | untrusted | — | Plain source (preferred for agent/user content) |
| `variant` | enum(inline | block) | no | — | `"inline"` | — |
| `language` | string | no | — | — | Optional language hint |
| `class` | string | no | — | — | — |

### Examples

#### TypeScript block (`block-ts`)

```json
{
  "variant": "block",
  "language": "ts",
  "value": "const n = 1;"
}
```

### Related

- [`kbd`](components/kbd.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# CodeField

> An editable, syntax-highlighted code textarea.

- **id:** `code-field`
- **package:** `@texuli/blocks`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `forms`

### Use when

- Edit a snippet or query

### Don't use when

- Read-only code (use blocks-code)

### Accessibility

- A real textarea; Tab indents, Escape then Tab leaves.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `value` | string | no | untrusted | — | — |
| `language` | string | no | — | — | ts, python, yml… |
| `label` | string | no | — | — | — |
| `labels` | object | no | — | — | — |
| `placeholder` | string | no | — | — | — |
| `name` | string | no | — | — | — |
| `readonly` | boolean | no | — | `false` | — |
| `disabled` | boolean | no | — | `false` | — |
| `rows` | number | no | — | `4` | — |
| `wrap` | boolean | no | — | `false` | — |
| `tabSize` | number | no | — | `2` | — |
| `indentWith` | enum(spaces | tab) | no | — | `"spaces"` | — |
| `lineNumbers` | boolean | no | — | `false` | — |
| `highlightLimit` | number | no | — | — | — |
| `showKeyboardHint` | boolean | no | — | `false` | — |
| `onValueChange` | event | no | — | — | — |
| `class` | string | no | — | — | — |

### Examples

#### SQL (`sql`)

```json
{
  "language": "sql",
  "value": "select 1;"
}
```

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Color swatch

> A chip of a closed palette, role or data-viz color with contrast ink from tokens. Never free CSS.

- **id:** `color-swatch`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `display`

### Use when

- Show a named token or series color in a legend, key or palette

### Don't use when

- A status label (use badge)
- A long-form color name in a sentence (use text)

### Accessibility

- Pair the fill with a text label; never convey the color by fill alone.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `color` | enum(chart-1 | chart-2 | chart-3 | chart-4 | chart-5 | chart-6 | chart-7 | chart-8 | primary | secondary | success | warning | destructive | info | neutral) | no | — | `"primary"` | Closed color reference (chart-1…8 or a role token) |
| `size` | enum(sm | md | lg) | no | — | `"md"` | — |
| `label` | string | no | — | — | Plain-text label, escaped |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | Rich label content; replaced by a non-empty label |

### Examples

#### Primary swatch (`primary`)

```json
{
  "color": "primary",
  "label": "Primary"
}
```

#### Chart series (`series`)

```json
{
  "color": "chart-1",
  "size": "md",
  "label": "North"
}
```

### Related

- [`badge`](components/badge.md)
- [`box`](components/box.md)
- [`text`](components/text.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Combobox

> A text input that filters a list of options, for one value or several.

- **id:** `combobox`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `forms`

### Use when

- Pick from a long list by typing to filter
- Options loaded from a server as the user types

### Don't use when

- A short closed list (use select or radio-group)
- Several values shown as chips (use multi-select)

### Accessibility

- The input keeps focus; aria-activedescendant tracks the highlighted option
- Arrow keys move, Enter selects, Escape closes; empty, loading and error states are announced
- With required, a rejected form moves focus to the input

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `value` | unknown | no | — | — | Selected value (a string, or a string array when multiple) |
| `defaultValue` | unknown | no | — | — | Starting selection; a form reset restores it |
| `inputValue` | string | no | — | — | Text in the input (bindable) |
| `defaultInputValue` | string | no | — | `""` | — |
| `items` | array | no | — | — | Options as { value, label, disabled? } |
| `loadOptions` | unknown | no | — | — | Function prop the host passes: (query, signal) => Promise<items> for remote options. Not agent-emittable (functions are not data). |
| `filter` | unknown | no | — | — | Function prop the host passes: (item, query) => boolean. Replaces the default match (label contains the query, ignoring case); runs on the trimmed, non-empty query; unused with loadOptions. createFoldedFilter builds an accent-insensitive one. Not agent-emittable (functions are not data). |
| `multiple` | boolean | no | — | `false` | — |
| `disabled` | boolean | no | — | `false` | Not interactive, not submitted, not validated |
| `name` | string | no | — | — | Form field name: submits the value (one entry per value when multiple) |
| `required` | boolean | no | — | `false` | Blocks form submission until a value is selected |
| `requiredMessage` | string | no | — | — | Translated message when required blocks submission (default: the browser message) |
| `form` | string | no | — | — | Associated form id |
| `open` | boolean | no | — | `false` | — |
| `size` | enum(sm | md | lg) | no | — | `"md"` | — |
| `variant` | enum(outline | soft) | no | — | `"outline"` | — |
| `class` | string | no | — | — | — |
| `onValueChange` | event | no | — | — | — |
| `onInputValueChange` | event | no | — | — | — |
| `onOpenChange` | event | no | — | — | — |
| `children` | slot | no | — | — | — |

### Examples

#### Required form field (`form-field`)

```json
{
  "name": "city",
  "required": true,
  "requiredMessage": "Choose a city.",
  "size": "md"
}
```

### Related

- [`multi-select`](components/multi-select.md)
- [`select`](components/select.md)
- [`field`](components/field.md)
- [`form`](components/form.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# CommandPalette

> Dialog-hosted command palette with search and recent items.

- **id:** `command-palette`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `overlays`

### Use when

- App-wide jump-to and actions (⌘K)

### Don't use when

- Simple select lists (use select or combobox)

### Accessibility

- Dialog title/description; listbox keyboard for results.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `open` | boolean | no | — | `false` | — |
| `onOpenChange` | event | no | — | — | — |
| `search` | unknown | no | — | — | Sync or async search function |
| `onSelect` | event | no | — | — | — |
| `recentItems` | array | no | — | — | — |
| `debounceMs` | number | no | — | — | — |
| `placeholder` | string | no | — | — | — |
| `shortcut` | boolean | no | — | `true` | — |
| `recentLabel` | string | no | — | — | — |
| `title` | string | no | — | — | — |
| `searchLabel` | string | no | — | — | Accessible name of the search combobox and its results; defaults to title |
| `description` | string | no | — | — | — |
| `emptyLabel` | string | no | — | — | — |
| `recentEmptyLabel` | string | no | — | — | — |
| `loadingLabel` | string | no | — | — | — |
| `errorLabel` | string | no | — | — | — |
| `size` | enum(sm | md | lg) | no | — | `"md"` | — |
| `variant` | enum(outline | soft) | no | — | `"outline"` | — |
| `class` | string | no | — | — | — |

### Examples

#### Open palette (`palette`)

```json
{
  "open": true,
  "title": "Command palette",
  "placeholder": "Search…"
}
```

### Related

- [`dialog`](components/dialog.md)
- [`dropdown-menu`](components/dropdown-menu.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Composer

> The host reply box for a chat thread. Host chrome; agents never emit it.

- **id:** `composer`
- **package:** `@texuli/chat`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `chat`

### Use when

- The person replies in a live chat the host owns

### Don't use when

- A read-only transcript (use chat-thread)
- A form (use action-form or schema-form)

### Accessibility

- The field is labelled; Enter sends and Escape stops a stream
- Pending send is announced; the send control stays named while streaming

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `value` | string | no | untrusted | — | Draft text. |
| `onSubmit` | event | yes | — | — | Send the draft. |
| `disabled` | boolean | no | — | `false` | — |
| `sending` | boolean | no | — | `false` | — |
| `maxRows` | number | no | — | `6` | — |
| `maxLength` | number | no | — | — | — |
| `streaming` | boolean | no | — | `false` | — |
| `onStop` | event | no | — | — | Stop a streaming reply. |
| `layout` | enum(stack | row) | no | — | `"stack"` | — |
| `sendButton` | enum(label | icon) | no | — | `"label"` | — |
| `class` | string | no | — | — | — |

### Examples

#### Reply box (`reply`)

```json
{
  "layout": "stack"
}
```

### Related

- [`chat-thread`](components/chat-thread.md)
- [`chat-message`](components/chat-message.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# ContentLayout

> Shared docs/blog/editorial reading frame with optional TOC.

- **id:** `content-layout`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `layouts`

### Use when

- Long-form content with a table of contents

### Don't use when

- App chrome shells

### Accessibility

- Main landmark holds the article
- TOC links are in-page anchors

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `kind` | enum(docs | blog | editorial) | yes | — | — | — |
| `mountScreen` | event | yes | — | — | Host callback that mounts the stable routed screen node |
| `nav` | object | no | — | — | NavModel for chrome links |
| `path` | string | no | — | — | Current hash path |
| `options` | object | no | — | — | Flat data-only layout knobs |
| `storageKey` | string | no | — | — | Scope for persisted UI flags |
| `aside` | slot | no | — | — | Optional context panel |
| `class` | string | no | — | — | — |

### Examples

#### Docs (`docs`)

```json
{
  "kind": "docs",
  "options": {
    "title": "Guides"
  }
}
```

### Related

- [`layout-docs`](components/layout-docs.md)
- [`layout-blog`](components/layout-blog.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# ContextMenu

> Pointer-anchored menu (right-click, long-press, Menu key).

- **id:** `context-menu`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `overlays`

### Use when

- Actions on a canvas or list row via context click

### Don't use when

- A visible button trigger (use dropdown-menu)

### Accessibility

- Opens at the pointer; keyboard Menu/Shift+F10 supported on the region.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `open` | boolean | no | — | `false` | — |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | — |

### Examples

#### Context region (`region`)

```json
{}
```

### Related

- [`dropdown-menu`](components/dropdown-menu.md)
- [`context-menu-trigger`](components/context-menu-trigger.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# ContextMenu.Trigger

> Region that opens the context menu.

- **id:** `context-menu-trigger`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `overlays`

### Use when

- Define the hit target for a context menu

### Don't use when

- Button menus

### Accessibility

- Region text names the menu; long-press suppresses iOS callout.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | — |
| `disabled` | boolean | no | — | `false` | — |

### Examples

#### Canvas region (`canvas`)

```json
{}
```

### Related

- [`context-menu`](components/context-menu.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Choice control

> A segmented choice that sets an enum state variable to one of its values.

- **id:** `control-choice`
- **package:** `@texuli/player`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `state`

### Use when

- Switch between a few views or ranges, such as this week or last week

### Don't use when

- Submitting, saving or sending anything: controls only set local state
- Navigating: use a link

### Accessibility

- A radiogroup of radio buttons; arrows, Home and End move and select (roving tabindex)

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `state` | string | yes | — | — | The declared local-state variable this control sets. |
| `label` | string | yes | untrusted | — | Visible label and accessible name. |

### Examples

#### Week (`range`)

```json
{
  "state": "week",
  "label": "Week"
}
```

### Related

- [`control-toggle`](components/control-toggle.md)
- [`control-slider`](components/control-slider.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Filter control

> A text field that sets a string state variable, capped at its declared length.

- **id:** `control-filter`
- **package:** `@texuli/player`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `state`

### Use when

- Type a filter that other nodes read through a binding

### Don't use when

- Submitting, saving or sending anything: controls only set local state
- Navigating: use a link

### Accessibility

- A native search input with a visible label; Enter never submits

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `state` | string | yes | — | — | The declared local-state variable this control sets. |
| `label` | string | yes | untrusted | — | Visible label and accessible name. |
| `placeholder` | string | no | untrusted | — | — |

### Examples

#### Filter (`query`)

```json
{
  "state": "query",
  "label": "Filter tickets"
}
```

### Related

- [`control-toggle`](components/control-toggle.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Slider control

> A range input that sets a number state variable within its declared min and max.

- **id:** `control-slider`
- **package:** `@texuli/player`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `state`

### Use when

- Adjust a threshold or a count within a bounded range

### Don't use when

- Submitting, saving or sending anything: controls only set local state
- Navigating: use a link

### Accessibility

- A native range input with a visible label and value

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `state` | string | yes | — | — | The declared local-state variable this control sets. |
| `label` | string | yes | untrusted | — | Visible label and accessible name. |
| `step` | number | no | — | — | Increment; default 1. |

### Examples

#### Limit (`limit`)

```json
{
  "state": "limit",
  "label": "Items shown",
  "step": 1
}
```

### Related

- [`control-choice`](components/control-choice.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Toggle control

> A switch that sets a boolean state variable.

- **id:** `control-toggle`
- **package:** `@texuli/player`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `state`

### Use when

- Show or hide details, include or exclude a series

### Don't use when

- Submitting, saving or sending anything: controls only set local state
- Navigating: use a link

### Accessibility

- A button with role="switch" and aria-checked; Space or Enter flips it

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `state` | string | yes | — | — | The declared local-state variable this control sets. |
| `label` | string | yes | untrusted | — | Visible label and accessible name. |

### Examples

#### Show details (`details`)

```json
{
  "state": "details",
  "label": "Show details"
}
```

### Related

- [`control-choice`](components/control-choice.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Board

> A kanban board: cards in columns (and optional swimlanes), moved by drag, keyboard or a move menu, with work-in-progress limits.

- **id:** `data-board`
- **package:** `@texuli/data`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `data`

### Use when

- Show work items by status and let people move them between columns

### Don't use when

- One ordered list: use sortable-list
- Read-only status counts: use kpi or a chart

### Accessibility

- Columns are labelled lists; each card has a drag handle button and a "Move to…" menu (the non-drag path)
- Moves are announced politely with column and position; locked cards refuse moves with a reason

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `label` | string | yes | untrusted | — | Accessible name of the view. |
| `columns` | array | yes | — | — | — |
| `items` | array | yes | — | — | Cards: each names its column (and lane); rank orders cards within a cell. |
| `lanes` | array | no | — | — | — |
| `density` | enum(comfortable | compact) | no | — | `"comfortable"` | — |

### Examples

#### Sprint board (`sprint`)

```json
{
  "label": "Sprint 12",
  "columns": [
    {
      "id": "todo",
      "title": "To do"
    },
    {
      "id": "doing",
      "title": "In progress",
      "wipSoft": 2
    },
    {
      "id": "done",
      "title": "Done"
    }
  ],
  "items": [
    {
      "id": "t1",
      "title": "Draft the release notes",
      "column": "todo",
      "rank": "a0"
    },
    {
      "id": "t2",
      "title": "Review the onboarding flow",
      "column": "doing",
      "rank": "a0"
    }
  ]
}
```

### Related

- [`sortable-list`](components/sortable-list.md)
- [`data-tree-view`](components/data-tree-view.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Calendar

> Events on a month, week, day or agenda view; people open, and when allowed move, events.

- **id:** `data-calendar`
- **package:** `@texuli/data`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `data`

### Use when

- Show scheduled events or availability over days and weeks

### Don't use when

- Task durations and dependencies: use data-timeline
- One date: use text

### Accessibility

- A labelled grid with roving focus; every event is a button with its time and title
- Moving an event has a keyboard path; changes are announced politely

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `label` | string | yes | untrusted | — | Accessible name of the view. |
| `events` | array | yes | — | — | — |
| `view` | enum(month | week | day | agenda) | no | — | `"week"` | — |
| `anchor` | string | no | — | — | The ISO date the view opens on. |
| `timeZone` | string | no | — | `"UTC"` | — |
| `locale` | string | no | — | `"en-US"` | — |
| `readOnly` | boolean | no | — | `false` | — |

### Examples

#### Team week (`week`)

```json
{
  "label": "Team calendar",
  "view": "week",
  "anchor": "2026-10-26",
  "events": [
    {
      "id": "e1",
      "title": "Planning",
      "start": "2026-10-26T09:00:00Z",
      "end": "2026-10-26T10:00:00Z"
    },
    {
      "id": "e2",
      "title": "Offsite",
      "start": "2026-10-29",
      "end": "2026-10-30",
      "allDay": true
    }
  ]
}
```

### Related

- [`data-timeline`](components/data-timeline.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Cohort table

> A retention table: one row per cohort, one column per period after it started, as rates or counts, with optional heat tints and an averages row.

- **id:** `data-cohort-table`
- **package:** `@texuli/data`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `data`

### Use when

- Show how groups that started at different times keep going, period by period

### Don't use when

- One trend over time: use a line chart
- Records people sort and search: use data-grid

### Accessibility

- A real table: a caption, period column headers and cohort row headers with scope
- Heat tints are decorative and contrast-safe; the number stays the cell content

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `caption` | string | yes | untrusted | — | The table caption and accessible name: what is measured and how. |
| `rows` | array | yes | — | — | Cohorts, one row each: a label, an optional size and one value per period reached (rates from 0 to 1, or counts). incomplete marks the last value as a period still in progress. |
| `periods` | array | no | — | — | Period column headers ("Month 0", "Month 1"…); missing ones are numbered. |
| `captionHidden` | boolean | no | — | `false` | — |
| `valueKind` | enum(rate | count) | no | — | `"rate"` | — |
| `heat` | boolean | no | — | `false` | — |
| `max` | number | no | — | — | Top of the heat scale (default: 1 for rates, the largest cell for counts). |
| `average` | boolean | no | — | `false` | Adds an averages row, weighted by cohort size when every cohort has one. |
| `density` | enum(compact | default | comfortable) | no | — | `"compact"` | — |
| `locale` | string | no | — | `"en-US"` | — |

### Examples

#### Monthly retention (`monthly-retention`)

```json
{
  "caption": "Share of accounts active each month after signup",
  "periods": [
    "Month 0",
    "Month 1",
    "Month 2"
  ],
  "heat": true,
  "average": true,
  "rows": [
    {
      "label": "Aug 2026",
      "size": 420,
      "cells": [
        1,
        0.62,
        0.48
      ]
    },
    {
      "label": "Sep 2026",
      "size": 380,
      "cells": [
        1,
        0.58,
        0.51
      ],
      "incomplete": true
    },
    {
      "label": "Oct 2026",
      "size": 455,
      "cells": [
        1,
        0.66
      ],
      "incomplete": true
    }
  ]
}
```

### Related

- [`data-grid`](components/data-grid.md)
- [`charts-heatmap`](components/charts-heatmap.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Dashboard

> A widget grid people can rearrange: data-dashboard-widget children on columns and rows, moved and resized by drag or keyboard, reflowing on narrow screens.

- **id:** `data-dashboard`
- **package:** `@texuli/data`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `data`

### Use when

- An overview of several views (KPIs, charts, grids bound to host data sources) people arrange themselves
- A home or operations screen whose layout should persist per person

### Don't use when

- A fixed grid of cards: use layout-grid
- One chart or one table: paint it on its own

### Accessibility

- A named region whose widgets are a list in reading order (row, then column), whatever order they were written in
- Each widget has a move handle and a resize handle: Space or Enter picks up, arrows move or resize one column or row, Space or Enter drops, Escape cancels; every step is announced with its column, row and size
- A click on a handle opens an arrange toolbar, so nothing needs a drag (WCAG 2.5.7); handles are at least 24 by 24 px
- Widgets glide to their new cell only when motion is allowed; reduced motion commits at once

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `label` | string | yes | untrusted | — | Accessible name of the view. |
| `columns` | number | no | — | `12` | Columns of the widest grid (1 to 24). Narrower screens reflow onto at most 6 columns from 640 px and one column below. |
| `density` | enum(compact | default | comfortable) | no | — | `"default"` | — |
| `gap` | enum(none | small | medium | large) | no | — | — | — |
| `editable` | boolean | no | — | `false` | Shows the move and resize handles. |
| `compaction` | enum(vertical | none) | no | — | `"vertical"` | "vertical" floats widgets up to close gaps; "none" keeps gaps. |
| `layout` | array | no | — | — | The saved layout of the widest grid: one {id, x, y, w, h} per widget, id matching a widget's widgetId. Bind it to a list state, or read it from a host data source, to persist what people arrange; without it the widgets' own place props lay out the grid. |
| `children` | slot | no | — | — | data-dashboard-widget nodes only (at most 200). |

### Examples

#### Operations overview (`operations`)

```json
{
  "label": "Operations",
  "columns": 12,
  "editable": true
}
```

### Related

- [`data-dashboard-widget`](components/data-dashboard-widget.md)
- [`layout-grid`](components/layout-grid.md)
- [`data-grid`](components/data-grid.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Dashboard widget

> One titled widget of a data-dashboard, placed on the grid; its child is any content node, such as a chart, a KPI or a grid bound to a host data source.

- **id:** `data-dashboard-widget`
- **package:** `@texuli/data`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `data`

### Use when

- A tile of a data-dashboard

### Don't use when

- Anywhere outside a data-dashboard: use layout-card

### Accessibility

- Its title is a heading, and it names the widget's move and resize handles
- Its content is ordinary catalog nodes: no HTML, and data only from host-registered sources

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `widgetId` | string | yes | — | — | Stable id, unique in the dashboard: letters, digits, "-" and "_", at most 64 characters. The key of this widget in every saved layout. |
| `title` | string | yes | untrusted | — | Visible title; also names the handles. |
| `place` | object | no | — | — | Where the widget starts on the widest grid when the dashboard has no saved layout for it: {x, y, w, h} in columns and rows, with optional minW, minH, maxW, maxH and locked. Without x and y it takes the first free slot. |
| `children` | slot | no | — | — | The widget content. |

### Examples

#### Revenue tile (`revenue`)

```json
{
  "widgetId": "revenue",
  "title": "Revenue",
  "place": {
    "x": 0,
    "y": 0,
    "w": 4,
    "h": 2
  }
}
```

### Related

- [`data-dashboard`](components/data-dashboard.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# File browser

> Folders and files in a grid or list with breadcrumbs, selection and type previews.

- **id:** `data-files`
- **package:** `@texuli/data`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `data`

### Use when

- Show a folder structure people browse and select from

### Don't use when

- Uploading files: that is host chrome (file-upload)

### Accessibility

- A labelled grid or list with roving focus; folders open with Enter, Backspace goes up
- Selection is exposed per item; previews are decorative

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `label` | string | yes | untrusted | — | Accessible name of the view. |
| `entries` | array | yes | — | — | Files and folders; parent names the folder (none for the root). |
| `layout` | enum(grid | list) | no | — | `"grid"` | — |
| `density` | enum(comfortable | compact) | no | — | `"comfortable"` | — |

### Examples

#### Shared drive (`shared`)

```json
{
  "label": "Shared drive",
  "entries": [
    {
      "id": "f1",
      "name": "Reports",
      "kind": "folder"
    },
    {
      "id": "f2",
      "name": "Q3 summary.pdf",
      "kind": "file",
      "parent": "f1",
      "type": "application/pdf",
      "size": 48213
    }
  ]
}
```

### Related

- [`data-tree-view`](components/data-tree-view.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Filter builder

> Nested and/or groups of conditions (field, operator by field type, value) that people add, edit and remove.

- **id:** `data-filter-builder`
- **package:** `@texuli/data`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `data`

### Use when

- Let people compose a structured filter, such as "status is open and total over 100"

### Don't use when

- One text filter that other nodes read: use control-filter
- A fixed choice between a few views: use control-choice

### Accessibility

- Native selects and inputs, every one labelled; each group is a labelled fieldset
- Adding and removing conditions moves focus to the next control and is announced politely

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `label` | string | yes | untrusted | — | Accessible name of the view. |
| `fields` | array | yes | — | — | The fields a condition can test; options list the values of an enum field, and optionLabels maps a value to the text its menus show (the value otherwise). |
| `value` | object | no | — | — | The starting filter: {type:"group", op:"and"\|"or", children:[{type:"condition", field, operator, value}…]}. It is checked against fields (at most 6 levels and 200 nodes); one that does not fit starts empty. |
| `maxDepth` | number | no | — | `3` | Deepest group level offered (the root is 1), capped at 5. |
| `issues` | array | no | — | — | Problems to show on conditions: each message appears under the condition at path (child indexes from the root) and marks its value control invalid. Paths that are not a condition are ignored. |
| `disabled` | boolean | no | — | `false` | — |

### Examples

#### Open orders (`open-orders`)

```json
{
  "label": "Order filter",
  "fields": [
    {
      "key": "status",
      "header": "Status",
      "type": "enum",
      "options": [
        "open",
        "closed"
      ]
    },
    {
      "key": "total",
      "header": "Total",
      "type": "number"
    }
  ],
  "value": {
    "type": "group",
    "op": "and",
    "children": [
      {
        "type": "condition",
        "field": "status",
        "operator": "eq",
        "value": "open"
      }
    ]
  }
}
```

### Related

- [`data-grid`](components/data-grid.md)
- [`control-filter`](components/control-filter.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Data grid

> A sortable, searchable grid of rows and typed columns; virtualized for long lists.

- **id:** `data-grid`
- **package:** `@texuli/data`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `data`

### Use when

- Show many records people sort, search and select

### Don't use when

- A small static table in a document: use table or blocks-data

### Accessibility

- A WAI-ARIA grid with a caption, sortable column headers and roving cell focus
- Sort and search changes are announced; selection is exposed per row

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `caption` | string | yes | untrusted | — | The grid caption and accessible name. |
| `columns` | array | yes | — | — | — |
| `rows` | array | yes | — | — | Rows: an id and one display string per column id (the column kind sorts it). |
| `searchable` | boolean | no | — | `false` | — |
| `selectable` | boolean | no | — | `false` | — |
| `density` | enum(compact | default | comfortable) | no | — | `"default"` | — |

### Examples

#### Orders (`orders`)

```json
{
  "caption": "Open orders",
  "columns": [
    {
      "id": "customer",
      "header": "Customer"
    },
    {
      "id": "total",
      "header": "Total",
      "kind": "number",
      "align": "end",
      "sortable": true
    }
  ],
  "rows": [
    {
      "id": "o1",
      "cells": {
        "customer": "Northwind Example",
        "total": "1240"
      }
    },
    {
      "id": "o2",
      "cells": {
        "customer": "Contoso Example",
        "total": "310"
      }
    }
  ]
}
```

### Related

- [`table`](components/table.md)
- [`blocks-data`](components/blocks-data.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Map

> Places as markers on an offline vector basemap, clustered when close, with a place list beside it.

- **id:** `data-map`
- **package:** `@texuli/data`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `data`

### Use when

- Show where things are: stores, deliveries, sites

### Don't use when

- Values per region: use charts-geo-map
- One address: use text

### Accessibility

- Every marker is also an item in a labelled place list (the non-map path)
- The map pans and zooms by keyboard; selection is announced

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `label` | string | yes | untrusted | — | Accessible name of the view. |
| `markers` | array | yes | — | — | — |
| `listPlacement` | enum(side | below) | no | — | `"side"` | — |

### Examples

#### Sites (`sites`)

```json
{
  "label": "Warehouses",
  "markers": [
    {
      "id": "w1",
      "label": "North hub",
      "lat": 59.33,
      "lng": 18.07
    },
    {
      "id": "w2",
      "label": "South hub",
      "lat": 41.39,
      "lng": 2.17,
      "tone": "warning"
    }
  ]
}
```

### Related

- [`charts-geo-point-map`](components/charts-geo-point-map.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Notification inbox

> Notifications, newest first, with unread state, mark read and unread, mark all read and an unread view.

- **id:** `data-notification-inbox`
- **package:** `@texuli/data`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `data`

### Use when

- List updates someone should catch up on, such as mentions or review requests

### Don't use when

- A short-lived confirmation: that is a host toast
- A history of changes without read state: use timeline

### Accessibility

- A section named by its heading; the unread count is read after it
- Every item has a read toggle named with its title; new unread items are announced politely

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `items` | array | yes | untrusted | — | Notifications, newest first. href passes the untrusted URL policy (https, mailto and #fragments); read changes stay in view. |
| `filter` | enum(all | unread) | no | — | `"all"` | — |
| `now` | string | no | — | — | The ISO instant the time labels count from (default: when it paints). |
| `timeZone` | string | no | — | `"UTC"` | — |
| `locale` | string | no | — | `"en-US"` | — |
| `markReadOnOpen` | boolean | no | — | `true` | Opening an unread item marks it read. |
| `headingLevel` | number | no | — | `2` | Level of the inbox heading, 2 to 6. |

### Examples

#### Mentions (`mentions`)

```json
{
  "now": "2026-10-27T12:00:00Z",
  "items": [
    {
      "id": "n1",
      "title": "Ana Example mentioned you in Launch plan",
      "body": "Can you check the timeline before Friday?",
      "at": "2026-10-27T11:40:00Z",
      "read": false,
      "href": "https://example.com/docs/launch-plan"
    },
    {
      "id": "n2",
      "title": "Weekly report is ready",
      "at": "2026-10-26T09:00:00Z",
      "read": true
    }
  ]
}
```

### Related

- [`timeline`](components/timeline.md)
- [`chat-thread`](components/chat-thread.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Project timeline

> Tasks as bars over days, weeks, months or quarters, with dependencies and progress.

- **id:** `data-timeline`
- **package:** `@texuli/data`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `data`

### Use when

- Show a schedule of tasks with durations and dependencies

### Don't use when

- Point-in-time events: use timeline or data-calendar

### Accessibility

- A labelled grid of rows; every bar is a button with its dates and progress
- Rescheduling has a keyboard path; dependencies are listed as text

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `label` | string | yes | untrusted | — | Accessible name of the view. |
| `tasks` | array | yes | — | — | — |
| `dependencies` | array | no | — | — | — |
| `zoom` | enum(day | week | month | quarter) | no | — | `"week"` | — |
| `locale` | string | no | — | `"en"` | — |
| `groups` | array | no | untrusted | — | Headers by task group, with optional bands. |
| `collapsed` | array | no | — | — | — |
| `selectedRow` | string | no | — | — | Selected task id; when set, rows are selectable. |
| `markers` | array | no | untrusted | — | — |

### Examples

#### Launch plan (`launch`)

```json
{
  "label": "Launch",
  "zoom": "week",
  "tasks": [
    {
      "id": "d",
      "title": "Design",
      "start": "2026-11-02",
      "end": "2026-11-13",
      "progress": 0.5
    },
    {
      "id": "b",
      "title": "Build",
      "start": "2026-11-16",
      "end": "2026-12-04"
    }
  ],
  "dependencies": [
    {
      "from": "d",
      "to": "b",
      "type": "FS"
    }
  ]
}
```

### Related

- [`data-calendar`](components/data-calendar.md)
- [`timeline`](components/timeline.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Tree view

> A hierarchy of items people expand, select and reorder or re-parent by drag or keyboard.

- **id:** `data-tree-view`
- **package:** `@texuli/data`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `data`

### Use when

- Show nested items such as folders, outlines or org charts

### Don't use when

- A flat list: use list or sortable-list
- Files with previews: use data-files

### Accessibility

- A WAI-ARIA tree with roving focus, typeahead and expand/collapse on arrows
- Moves have a keyboard path and are announced; selection uses checkboxes when enabled

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `label` | string | yes | untrusted | — | Accessible name of the view. |
| `items` | array | yes | — | — | Flat items; parent names the parent item (none for a root). |
| `checkboxes` | boolean | no | — | `true` | — |
| `density` | enum(comfortable | compact) | no | — | `"comfortable"` | — |

### Examples

#### Project outline (`outline`)

```json
{
  "label": "Launch plan",
  "items": [
    {
      "id": "plan",
      "label": "Plan"
    },
    {
      "id": "scope",
      "label": "Scope",
      "parent": "plan"
    },
    {
      "id": "ship",
      "label": "Ship"
    }
  ]
}
```

### Related

- [`data-files`](components/data-files.md)
- [`data-board`](components/data-board.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Virtual list view

> A windowed list of any length: only the visible rows are in the page, measured as they render, and each is announced with its position.

- **id:** `data-virtual-list`
- **package:** `@texuli/data`
- **tier:** `content`
- **agent emittable:** no
- **emit:** 
- **group:** `data`

### Use when

- Show a long feed whose rows hold their own buttons, links or inputs, with mode="feed" (hundreds to tens of thousands of rows)
- Let people pick one row from a long log or result list by keyboard (the default listbox mode)

### Don't use when

- Rows with columns: use data-grid
- A short list: use list
- Rows with their own buttons, links or inputs in the default listbox mode: an option holds no controls, so use mode="feed"

### Accessibility

- Listbox mode: a WAI-ARIA listbox with one tab stop; aria-activedescendant names the active row
- Every row carries aria-setsize and aria-posinset, so its position in the full list is announced
- Listbox mode: Arrow keys, Home, End, Page Up and Page Down move; Enter, Space or a click selects (selectable false: no selection)
- Feed mode: a WAI-ARIA feed of focusable articles without selection; Page Down and Page Up move focus between articles
- Feed mode: every article is named by aria-labelledby (the row label, or the row heading id) or, failing that, aria-label
- Keys pressed in a row control (an input, a button) stay with that control

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `label` | string | yes | untrusted | — | Accessible name of the view. |
| `items` | array | yes | — | — | The rows; a row snippet in host code may render any item shape. |
| `size` | enum(sm | md | lg | fill) | no | — | `"md"` | Viewport height: sm, md or lg, or fill to take the parent height. |
| `density` | enum(compact | default | comfortable) | no | — | `"default"` | — |
| `mode` | enum(listbox | feed) | no | — | `"listbox"` | listbox: rows are options to pick. feed: an APG feed of articles that may hold their own controls; no selection. |
| `selectable` | boolean | no | — | `true` | Listbox mode: false never selects or paints a row (select still fires) and drops the option chrome. |
| `surface` | enum(box | plain) | no | — | `"box"` | box: the viewport has a border, radius and surface. plain: none of them, so a feed of cards sits on the page. |
| `estimateSize` | number | no | — | `40` | Row height in px used until a row has been measured. |
| `overscan` | number | no | — | `3` | Rows rendered before and after the viewport (at most 50). |
| `selected` | string | no | — | — | The selected row id. |
| `emptyLabel` | string | no | untrusted | `"No items"` | — |

### Examples

#### Team feed (`feed`)

```json
{
  "label": "Team feed",
  "items": [
    {
      "id": "u1",
      "label": "Release notes drafted",
      "description": "Docs team, example.com"
    },
    {
      "id": "u2",
      "label": "Onboarding flow reviewed"
    },
    {
      "id": "u3",
      "label": "Quarterly plan shared",
      "description": "Planning, example.com"
    }
  ]
}
```

### Related

- [`data-grid`](components/data-grid.md)
- [`data-notification-inbox`](components/data-notification-inbox.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Deck slide

> One slide in a deck: a title, content blocks and speaker notes.

- **id:** `deck-slide`
- **package:** `texuli`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `layouts`

### Use when

- Compose deck slide structure in agent-authored trees

### Don't use when

- App chrome shells (sidebar, top-nav, dialogs)

### Accessibility

- Structure is semantic regions the host maps to real layout components
- No HTML strings; children are nested catalog nodes

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `slideId` | string | yes | — | — | Stable slide id (lowercase letters, digits and hyphens) |
| `title` | string | no | untrusted | — | — |
| `notes` | string | no | untrusted | — | Plain-text speaker notes |
| `master` | enum(title | section | content | two-column | media-left | media-right | quote | closing) | no | — | — | — |
| `layout` | string | no | — | — | Catalog layout id, free, component or custom (model v2) |
| `transition` | enum(none | fade | fade-up | slide | zoom | morph) | no | — | — | — |
| `themeRef` | unknown | no | — | — | Overrides the deck theme for this slide |
| `background` | unknown | no | — | — | Slide background preset or spec (model v2) |
| `steps` | array | no | — | — | Optional step labels (names steps 1…) |
| `props` | object | no | — | — | Layout props when layout is a catalog layout id |
| `component` | object | no | — | — | Component slide payload when layout is component |
| `children` | slot | no | — | — | — |
| `class` | string | no | — | — | — |

### Examples

#### Deck slide (`basic`)

```json
{
  "slideId": "opening",
  "title": "Opening"
}
```

### Related

- [`layout-page`](components/layout-page.md)
- [`layout-doc`](components/layout-doc.md)
- [`layout-grid`](components/layout-grid.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Description

> Help text associated with a field control.

- **id:** `description`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `forms`

### Use when

- Short guidance under a label

### Don't use when

- An error message (use field-error)

### Accessibility

- Wire via aria-describedby from Field or the host.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | — |

### Examples

#### Help text (`help`)

```json
{}
```

### Related

- [`field`](components/field.md)
- [`label`](components/label.md)
- [`field-error`](components/field-error.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# DetailPanel

> Non-modal detail panel alongside content.

- **id:** `detail-panel`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `overlays`

### Use when

- Inspect a selected row without leaving the list

### Don't use when

- Full-page blocking flows (use dialog)

### Accessibility

- Keep a visible heading; do not trap focus unless modal.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | enum(sm | md | lg | xl) | no | — | `"md"` | — |
| `side` | enum(top | right | bottom | left | start | end | center) | no | — | `"end"` | — |
| `dismissOutside` | boolean | no | — | `false` | Non-modal only: close on a press or focus outside (never on the trigger) |
| `closeOnEscape` | boolean | no | — | `false` | Non-modal only: close on Escape anywhere, not just from inside |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | — |

### Examples

#### End panel (`end`)

```json
{
  "side": "end"
}
```

### Related

- [`sheet`](components/sheet.md)
- [`drawer`](components/drawer.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Dialog

> Modal dialog with title, optional description, body and footer.

- **id:** `dialog`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `overlays`

### Use when

- Confirm multi-step flows
- Show focused detail without leaving the page

### Don't use when

- A destructive confirm that must trap attention (use alert-dialog)
- Non-modal hints (use popover or tooltip)

### Accessibility

- Focus moves into the dialog and returns on close
- Title is required; Escape dismisses unless prevented

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `open` | boolean | no | — | `false` | — |
| `title` | string | yes | — | — | Accessible dialog title |
| `description` | string | no | — | — | — |
| `size` | enum(sm | md | lg | xl) | no | — | `"md"` | — |
| `trigger` | slot | no | — | — | Trigger snippet receiving { props } |
| `footer` | slot | no | — | — | — |
| `children` | slot | no | — | — | — |
| `hideClose` | boolean | no | — | `false` | — |
| `closeLabel` | string | no | — | `"Close"` | — |
| `onOpenChange` | event | no | — | — | — |
| `class` | string | no | — | — | — |

### Examples

#### Basic dialog (`basic`)

```json
{
  "title": "Edit note",
  "description": "Harbor Notes settings",
  "open": true
}
```

### Related

- [`alert-dialog`](components/alert-dialog.md)
- [`sheet`](components/sheet.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Document

> A block document (a brief, a report, notes or a page) as data: headings, paragraphs, lists, callouts, columns, content blocks and embedded components.

- **id:** `document`
- **package:** `@texuli/pages`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `documents`

### Use when

- Write a document people read, export (Markdown, DOCX, PDF) or keep editing
- Edit an existing document with a bounded patch (patchDocument) instead of rewriting it

### Don't use when

- An interface with controls, state or flows: use layout-page or layout-doc with catalog nodes
- A slide presentation: use layout-deck

### Accessibility

- Painted as an article named by the document title, with anchored headings and an outline
- Text is data, never HTML; links and media pass the URL policy at the host tier
- Embedded components are validated again as catalog nodes at the same tier

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `doc` | object | yes | — | — | A Texuli document: { format: "texuli-document", formatVersion: 1, meta: { title }, blocks }. Blocks: paragraph, heading, code, list, quote, divider, media, callout, toggle, columns, page-link, block ({ family, block, props }: a @texuli/blocks block) and embed ({ kind: "component", inline: { id, props } }: one catalog node). |
| `label` | string | no | untrusted | — | Accessible name; defaults to the document title. |
| `outline` | boolean | no | — | `true` | Show the "On this page" outline when the document has two or more headings. |

### Examples

#### Project brief (`brief`)

```json
{
  "doc": {
    "format": "texuli-document",
    "formatVersion": 1,
    "meta": {
      "title": "Project brief",
      "locale": "en"
    },
    "blocks": [
      {
        "id": "title",
        "type": "heading",
        "level": 1,
        "content": [
          {
            "type": "text",
            "text": "Project brief",
            "marks": []
          }
        ]
      },
      {
        "id": "intro",
        "type": "paragraph",
        "content": [
          {
            "type": "text",
            "text": "A fictional plan for the example.com launch.",
            "marks": []
          }
        ]
      },
      {
        "id": "risk",
        "type": "callout",
        "tone": "warning",
        "blocks": [
          {
            "id": "risk-text",
            "type": "paragraph",
            "content": [
              {
                "type": "text",
                "text": "The beta ends on Friday.",
                "marks": []
              }
            ]
          }
        ]
      }
    ]
  }
}
```

### Related

- [`layout-doc`](components/layout-doc.md)
- [`layout-page`](components/layout-page.md)
- [`blocks-text`](components/blocks-text.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Drawer

> Bottom or edge drawer with optional drag dismiss.

- **id:** `drawer`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `overlays`

### Use when

- Mobile sheets that feel like drawers

### Don't use when

- Desktop side navigation (use sidebar)

### Accessibility

- Same focus model as sheet; prefer labelled titles.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | enum(sm | md | lg | xl) | no | — | `"md"` | — |
| `side` | enum(top | right | bottom | left | start | end | center) | no | — | `"bottom"` | — |
| `dismissOutside` | boolean | no | — | `false` | Non-modal panels only; a Drawer is modal and always dismisses outside |
| `closeOnEscape` | boolean | no | — | `false` | Non-modal panels only; a Drawer is modal and always closes on Escape |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | — |

### Examples

#### Bottom drawer (`bottom`)

```json
{
  "side": "bottom"
}
```

### Related

- [`sheet`](components/sheet.md)
- [`responsive-modal`](components/responsive-modal.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# DropdownMenu

> Menu button pattern with items, checkboxes, radios and submenus.

- **id:** `dropdown-menu`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `overlays`

### Use when

- Actions behind a button trigger
- Menus with keyboard typeahead

### Don't use when

- Top-level app menus (use menubar)
- Pointer-anchored region menus (use context-menu)

### Accessibility

- APG menu button: arrow keys, typeahead, Escape closes and restores focus.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `open` | boolean | no | — | `false` | — |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | — |

### Examples

#### Actions menu (`actions`)

```json
{
  "open": true
}
```

### Related

- [`context-menu`](components/context-menu.md)
- [`menubar`](components/menubar.md)
- [`dropdown-menu-item`](components/dropdown-menu-item.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# DropdownMenu.Content

> Floating menu surface for dropdown items.

- **id:** `dropdown-menu-content`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `overlays`

### Use when

- Host menu items under a dropdown trigger

### Don't use when

- Non-menu floating panels (use popover)

### Accessibility

- role=menu; labelled by the trigger.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | enum(sm | md | lg) | no | — | `"md"` | — |
| `variant` | enum(default | soft) | no | — | `"default"` | — |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | — |
| `side` | enum(top | right | bottom | left) | no | — | `"bottom"` | — |
| `align` | enum(start | center | end) | no | — | `"start"` | — |
| `sideOffset` | number | no | — | `4` | — |

### Examples

#### Content (`panel`)

```json
{
  "size": "md"
}
```

### Related

- [`dropdown-menu`](components/dropdown-menu.md)
- [`dropdown-menu-item`](components/dropdown-menu-item.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# DropdownMenu.Item

> Menu item with optional icon and shortcut chrome.

- **id:** `dropdown-menu-item`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `overlays`

### Use when

- A single actionable row inside a menu

### Don't use when

- Standalone buttons outside a menu

### Accessibility

- role=menuitem; shortcuts are visual only.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `disabled` | boolean | no | — | `false` | — |
| `textValue` | string | no | — | — | Typeahead text override |
| `onSelect` | event | no | — | — | — |
| `closeOnSelect` | boolean | no | — | `true` | — |
| `icon` | slot | no | — | — | — |
| `shortcut` | string | no | — | — | Displayed keyboard hint |
| `inset` | boolean | no | — | `false` | — |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | — |

### Examples

#### Item with shortcut (`with-shortcut`)

```json
{
  "shortcut": "⌘N"
}
```

### Related

- [`dropdown-menu`](components/dropdown-menu.md)
- [`context-menu`](components/context-menu.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# DropdownMenu.Trigger

> Styled button that opens a dropdown menu.

- **id:** `dropdown-menu-trigger`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `overlays`

### Use when

- Label the control that opens DropdownMenu

### Don't use when

- Context or menubar triggers

### Accessibility

- aria-haspopup=menu and aria-expanded track open state.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | enum(sm | md | lg) | no | — | `"md"` | — |
| `variant` | enum(default | soft) | no | — | `"default"` | — |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | — |

### Examples

#### Trigger (`default`)

```json
{
  "variant": "default"
}
```

### Related

- [`dropdown-menu`](components/dropdown-menu.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Empty state

> Placeholder when a list or panel has nothing to show yet.

- **id:** `empty-state`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `display`

### Use when

- First-run or filtered-empty lists

### Don't use when

- A failure after a request (use error-state)

### Accessibility

- Title is required text; illustration is decorative (aria-hidden).

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `title` | string | yes | — | — | — |
| `description` | string | no | — | — | — |
| `illustration` | slot | no | — | — | — |
| `action` | slot | no | — | — | — |
| `size` | enum(sm | md) | no | — | `"md"` | — |
| `class` | string | no | — | — | — |

### Examples

#### No orders (`no-orders`)

```json
{
  "title": "No orders yet",
  "description": "Create an order to get started.",
  "size": "md"
}
```

### Related

- [`error-state`](components/error-state.md)
- [`table`](components/table.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Error state

> Full-panel failure with optional retry.

- **id:** `error-state`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `display`

### Use when

- A view failed to load and the user can retry

### Don't use when

- A soft warning inline (use alert)

### Accessibility

- Uses role=alert; retry is a real button with pending support.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `title` | string | no | — | `"Something went wrong"` | — |
| `message` | string | no | — | — | — |
| `onRetry` | event | no | — | — | — |
| `retryLabel` | string | no | — | `"Try again"` | — |
| `action` | slot | no | — | — | — |
| `class` | string | no | — | — | — |

### Examples

#### Retry error (`retry`)

```json
{
  "title": "Could not load orders",
  "message": "Check your connection.",
  "retryLabel": "Retry"
}
```

### Related

- [`empty-state`](components/empty-state.md)
- [`alert`](components/alert.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Field

> Label, description and error wiring for a single control.

- **id:** `field`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `forms`

### Use when

- Compose a labeled control with optional help and error text

### Don't use when

- Standalone chrome without a form control

### Accessibility

- Generates id and aria-describedby for the control snippet
- Marks aria-invalid when error is present
- hideLabel keeps the label available to assistive tech

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `label` | string | yes | — | — | — |
| `description` | string | no | — | — | — |
| `error` | string | no | — | — | Error message; marks the control invalid |
| `required` | boolean | no | — | `false` | — |
| `disabled` | boolean | no | — | `false` | — |
| `id` | string | no | — | — | — |
| `hideLabel` | boolean | no | — | `false` | — |
| `orientation` | enum(vertical | horizontal) | no | — | `"vertical"` | — |
| `class` | string | no | — | — | — |
| `children` | slot | yes | — | — | Control snippet receiving FieldControl |

### Examples

#### Vertical field (`vertical`)

```json
{
  "label": "Email",
  "description": "Work address",
  "required": true
}
```

### Related

- [`label`](components/label.md)
- [`description`](components/description.md)
- [`field-error`](components/field-error.md)
- [`form`](components/form.md)
- [`input`](components/input.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# FieldError

> An alert-role error message for a field.

- **id:** `field-error`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `forms`

### Use when

- Surface a validation error next to a control

### Don't use when

- Help text that is not an error (use description)

### Accessibility

- role=alert; show=false renders nothing while the host keeps aria wiring.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `show` | boolean | no | — | `true` | — |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | — |

### Examples

#### Error message (`message`)

```json
{
  "show": true
}
```

### Related

- [`field`](components/field.md)
- [`form`](components/form.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# FileUpload

> A labelled drop zone and file list for choosing local files.

- **id:** `file-upload`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `forms`

### Use when

- The person attaches files to a form the host owns

### Don't use when

- Remote media the agent names as URLs (use media-image)

### Accessibility

- A real file input; the drop zone is named; rejected files are listed with a reason.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `files` | array | no | — | — | Accepted files (bind:files) |
| `accept` | string | no | — | — | A native accept filter, e.g. image/* |
| `maxSize` | number | no | — | — | Largest file in bytes |
| `maxFiles` | number | no | — | — | — |
| `multiple` | boolean | no | — | `true` | — |
| `disabled` | boolean | no | — | `false` | — |
| `required` | boolean | no | — | `false` | — |
| `name` | string | no | — | — | — |
| `variant` | enum(default | compact) | no | — | `"default"` | — |
| `showPreviews` | boolean | no | — | `true` | — |
| `labels` | object | no | — | — | — |
| `onFilesAdd` | event | no | — | — | — |
| `onFileRemove` | event | no | — | — | — |
| `class` | string | no | — | — | — |

### Examples

#### Images (`images`)

```json
{
  "accept": "image/*",
  "multiple": true
}
```

### Related

- [`field`](components/field.md)
- [`form`](components/form.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Flow action

> A button that fires one declared flow event, such as next or back.

- **id:** `flow-action`
- **package:** `@texuli/player`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `state`

### Use when

- Move between the views of a declared flow

### Don't use when

- Submitting or navigating away: actions only change the local view

### Accessibility

- A type="button"; aria-disabled when no transition applies from the current view

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `event` | string | yes | — | — | A declared event. |
| `label` | string | yes | untrusted | — | — |

### Examples

#### Next (`next`)

```json
{
  "event": "next",
  "label": "Next"
}
```

### Related

- [`flow-view`](components/flow-view.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Flow view

> One named view of a multi-step flow; only the current view paints.

- **id:** `flow-view`
- **package:** `@texuli/player`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `state`

### Use when

- Split a wizard or a multi-step report into named steps

### Don't use when

- Content that should always show

### Accessibility

- A labelled region; focus moves to it when an action brings it into view

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `name` | string | yes | — | — | A declared view. |
| `label` | string | no | untrusted | — | — |
| `children` | slot | no | — | — | — |

### Examples

#### Review step (`step`)

```json
{
  "name": "review",
  "label": "Review"
}
```

### Related

- [`flow-action`](components/flow-action.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Form

> A form shell with layout, validation hook and error map.

- **id:** `form`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `forms`

### Use when

- Collect and validate a set of fields before submit

### Don't use when

- A single control with no submit (use field alone)

### Accessibility

- Native constraint validation runs unless noValidate is set
- Field errors map back onto controls after onValidate

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `layout` | enum(stack | grid) | no | — | `"stack"` | — |
| `noValidate` | boolean | no | — | `false` | — |
| `onValidate` | event | no | — | — | Return a field→message map (or Promise) to block submit |
| `onSubmitValues` | event | no | — | — | Called after validation succeeds with FormData values |
| `errors` | object | no | — | — | Controlled field→message map (bind:errors) |
| `onErrorsChange` | event | no | — | — | — |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | — |
| `formError` | slot | no | — | — | Form-level error snippet (e.g. _form message) |

### Examples

#### Stacked form (`stack`)

```json
{
  "layout": "stack"
}
```

### Related

- [`field`](components/field.md)
- [`button`](components/button.md)
- [`input`](components/input.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Form field

> A named, validated field bound to a declared local-state variable.

- **id:** `form-field`
- **package:** `@texuli/player`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `state`

### Use when

- Collect one value for an action

### Don't use when

- Passwords, card numbers or one-time codes: never in a blueprint

### Accessibility

- A visible label; required and invalid states are exposed; errors are linked

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `name` | string | yes | — | — | The key in the action values. |
| `state` | string | yes | — | — | The declared variable it binds. |
| `label` | string | yes | untrusted | — | — |
| `kind` | enum(text | email | tel | number | multiline) | no | — | `"text"` | — |
| `required` | boolean | no | — | — | — |
| `autocomplete` | enum(off | name | given-name | family-name | nickname | email | tel | organization | organization-title | street-address | address-level1 | address-level2 | postal-code | country-name | language | url) | no | — | — | — |
| `pattern` | enum(email | phone | postal-code | digits | slug) | no | — | — | — |
| `minLength` | number | no | — | — | — |
| `maxLength` | number | no | — | — | — |
| `min` | number | no | — | — | — |
| `max` | number | no | — | — | — |
| `placeholder` | string | no | untrusted | — | — |

### Examples

#### Email (`email`)

```json
{
  "name": "email",
  "state": "email",
  "label": "Email",
  "kind": "email",
  "required": true
}
```

### Related

- [`action-form`](components/action-form.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Form submit

> Proposes the form's action with its fields' values; disabled while a receipt is pending.

- **id:** `form-submit`
- **package:** `@texuli/player`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `state`

### Use when

- The one primary action of an action-form

### Don't use when

- Navigation or local view changes: use flow-action

### Accessibility

- A submit button inside the form; Enter in a field submits too

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `label` | string | yes | untrusted | — | — |

### Examples

#### Send (`send`)

```json
{
  "label": "Send request"
}
```

### Related

- [`action-form`](components/action-form.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Heading

> A page title or section heading: a semantic h1–h6 with a size from the type scale.

- **id:** `heading`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `display`

### Use when

- Title a page, a section or a panel
- Keep visual hierarchy in a locked prototype, where typography utilities are refused

### Don't use when

- Body copy, labels or captions (use text)
- Long-form content (use prose)

### Accessibility

- Renders the semantic heading element for its level; pick levels in document order.
- size changes only the look, never the level announced to assistive technology.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `level` | number | no | — | `2` | The semantic level, 1 to 6: renders <h1>…<h6> |
| `size` | enum(display | 4xl | 3xl | 2xl | xl | lg | md | sm | xs) | no | — | `"lg"` | Visual size, independent of the level (default from the level: 1 xl, 2 lg, 3 md, 4–6 sm); xs is ~0.875rem for small card titles; 2xl–4xl sit between xl and display |
| `responsive` | boolean | no | — | `false` | Scale the size down on narrow screens: fluid from two scale steps below up to the size |
| `tracking` | enum(default | tight) | no | — | `"default"` | Letter spacing: the role's own, or tight (--tx-letter-spacing-tight) |
| `tone` | enum(default | muted) | no | — | `"default"` | — |
| `truncate` | boolean | no | — | `false` | One line with an ellipsis |
| `label` | string | no | — | — | Plain-text heading, escaped; replaces children when both are given |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | The heading text |

### Examples

#### Page title (`page-title`)

```json
{
  "level": 1,
  "size": "xl",
  "label": "Quarterly report"
}
```

#### Muted section heading (`section`)

```json
{
  "level": 2,
  "size": "md",
  "tone": "muted",
  "label": "Details"
}
```

#### Responsive hero title (`hero`)

```json
{
  "level": 1,
  "size": "4xl",
  "responsive": true,
  "tracking": "tight",
  "label": "Plan the quarter"
}
```

#### Small card title (`card-title`)

```json
{
  "level": 3,
  "size": "xs",
  "label": "Open tasks"
}
```

### Related

- [`text`](components/text.md)
- [`prose`](components/prose.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Host region

> Reserves a named place where the host app mounts its own component.

- **id:** `host-region`
- **package:** `@texuli/player`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `state`

### Use when

- A step that needs sensitive input the agent must never emit (payment, sign-in)
- A place for host chrome that lives inside the document flow

### Don't use when

- Content the agent can describe itself: use a content block
- Card numbers, passwords or one-time codes as props: those never appear in a blueprint

### Accessibility

- The host component sits in a labelled group named by the label
- A region the host does not provide shows the label as visible text, not an empty box

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `name` | string | yes | — | — | The region the host provides, such as "payment" (lowercase, digits, hyphens). |
| `label` | string | yes | untrusted | — | What the region is for; its accessible name and its placeholder text. |

### Examples

#### Payment step (`payment`)

```json
{
  "name": "payment",
  "label": "Payment details"
}
```

### Related

- [`layout-stack`](components/layout-stack.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# HoverCard

> Preview panel that opens on hover or focus.

- **id:** `hover-card`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `overlays`

### Use when

- Rich previews without a click

### Don't use when

- Required interactions (use popover or dialog)

### Accessibility

- Opens on focus as well as hover; dismissible.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `open` | boolean | no | — | `false` | — |
| `children` | slot | no | — | — | — |

### Examples

#### Preview (`preview`)

```json
{}
```

### Related

- [`popover`](components/popover.md)
- [`tooltip`](components/tooltip.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# HoverCard.Content

> Styled hover-card surface.

- **id:** `hover-card-content`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `overlays`

### Use when

- Body of a hover card

### Don't use when

- Click-toggled panels (use popover-content)

### Accessibility

- Same surface tokens as popover for contrast.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `variant` | enum(elevated | flat) | no | — | `"elevated"` | — |
| `size` | enum(sm | md | lg) | no | — | `"md"` | — |
| `arrow` | boolean | no | — | `true` | — |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | — |

### Examples

#### Content (`body`)

```json
{}
```

### Related

- [`hover-card`](components/hover-card.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Icon

> A glyph by name or Lucide component; allowing icon allows every icon set.

- **id:** `icon`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `display`

### Use when

- A decorative or labelled glyph next to a control or a list row

### Don't use when

- A pressable control (use icon-button)
- Navigation chrome (use nav-icon)

### Accessibility

- With a label it is an image; without a label it is decorative (aria-hidden).
- Unknown names render nothing.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `icon` | string | no | — | — | Built-in name, registered name, or a Lucide component |
| `size` | enum(xs | sm | md | lg) | no | — | `"md"` | — |
| `tone` | enum(default | primary | success | warning | destructive | info | neutral) | no | — | `"default"` | — |
| `label` | string | no | — | — | Accessible name; omit for decorative |
| `class` | string | no | — | — | — |

### Examples

#### Search glyph (`search`)

```json
{
  "icon": "search",
  "label": "Search"
}
```

#### Muted chevron (`muted`)

```json
{
  "icon": "chevron-down",
  "tone": "neutral"
}
```

### Related

- [`icon-button`](components/icon-button.md)
- [`nav-icon`](components/nav-icon.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# IconButton

> An icon-only button that requires an accessible name.

- **id:** `icon-button`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `forms`

### Use when

- Toolbar and dense chrome actions that are icon-only

### Don't use when

- Actions with a visible text label (use button)

### Accessibility

- label is required and becomes aria-label on the control.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `label` | string | yes | — | — | Accessible name |
| `variant` | enum(default | secondary | outline | ghost | destructive | link) | no | — | `"ghost"` | — |
| `href` | string | no | developer | — | — |
| `loading` | boolean | no | — | `false` | — |
| `autoLoading` | boolean | no | — | `true` | — |
| `disabled` | boolean | no | — | `false` | — |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | Icon content |

### Examples

#### Close icon button (`close`)

```json
{
  "label": "Close"
}
```

### Related

- [`button`](components/button.md)
- [`button-group`](components/button-group.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Inline text

> A plain text run for the slot of a slot-only component (button, label, badge).

- **id:** `inline-text`
- **package:** `@texuli/catalog`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `display`

### Use when

- Give a form label, description, field error or menu trigger its visible text
- Text for a button, badge or kbd when the tree prefers a child to the label prop
- Any slot that needs a short phrase rather than a block

### Don't use when

- A paragraph, heading or list (use blocks-text)
- Text that needs formatting or links (use blocks-text)
- A component that already has a label or title prop (set that prop)

### Accessibility

- Painted as one escaped text node, so it names the parent control (a button label)
- A leaf: children are dropped

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `text` | string | yes | — | — | Plain text; the renderer refuses markup-like strings |

### Examples

#### Button label (`button-label`)

```json
{
  "text": "Save changes"
}
```

#### Badge word (`badge-word`)

```json
{
  "text": "Shipped"
}
```

### Related

- [`button`](components/button.md)
- [`label`](components/label.md)
- [`badge`](components/badge.md)
- [`kbd`](components/kbd.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Input

> A single-line text (or file) control with optional clear.

- **id:** `input`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `forms`

### Use when

- Short free-text fields
- Native file selection

### Don't use when

- Multi-line text (use textarea)
- A labeled field with description and error (wrap in field)

### Accessibility

- Pair with Field or an external label via id/for
- Clear control has an accessible name when clearable

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `type` | string | no | — | `"text"` | Native input type |
| `value` | string | no | — | — | Controlled value (bind:value) |
| `files` | unknown | no | — | — | FileList when type=file (bind:files) |
| `ref` | unknown | no | — | — | Element ref for the native input |
| `clearable` | boolean | no | — | `false` | — |
| `clearLabel` | string | no | — | `"Clear"` | — |
| `disabled` | boolean | no | — | `false` | — |
| `readonly` | boolean | no | — | `false` | — |
| `onValueChange` | event | no | — | — | — |
| `onClear` | event | no | — | — | — |
| `appearance` | enum(default | plain) | no | — | `"default"` | plain drops the control chrome for inline-edit text; focus stays visible |
| `textSize` | enum(control | xs | sm | md | lg | xl | 2xl | 3xl | 4xl | display) | no | — | `"control"` | control (form-control size) or a type-scale size for inline-edit titles and bodies |
| `class` | string | no | — | — | — |

### Examples

#### Text input (`text`)

```json
{
  "type": "text",
  "clearable": true
}
```

#### Email input (`email`)

```json
{
  "type": "email"
}
```

#### Inline-edit title (`inline-title`)

```json
{
  "appearance": "plain",
  "textSize": "xl"
}
```

### Related

- [`input-group`](components/input-group.md)
- [`textarea`](components/textarea.md)
- [`field`](components/field.md)
- [`text-counter`](components/text-counter.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# InputGroup

> An input with start/end adornments and optional clear.

- **id:** `input-group`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `forms`

### Use when

- Inputs with a unit, icon or trailing action

### Don't use when

- A bare input with no adornment (use input)

### Accessibility

- Invalid state marks the control aria-invalid; clear has an accessible name.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `start` | slot | no | — | — | Start adornment |
| `end` | slot | no | — | — | End adornment |
| `inputProps` | object | no | — | — | Native attributes for the inner input |
| `value` | string | no | — | — | — |
| `ref` | unknown | no | — | — | — |
| `disabled` | boolean | no | — | `false` | — |
| `readonly` | boolean | no | — | `false` | — |
| `invalid` | boolean | no | — | `false` | — |
| `clearable` | boolean | no | — | `false` | — |
| `clearLabel` | string | no | — | `"Clear"` | — |
| `onValueChange` | event | no | — | — | — |
| `onClear` | event | no | — | — | — |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | — |

### Examples

#### Search group (`search`)

```json
{
  "clearable": true
}
```

### Related

- [`input`](components/input.md)
- [`field`](components/field.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Kbd

> Inline keyboard key affordance.

- **id:** `kbd`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `display`

### Use when

- Document a shortcut next to a control

### Don't use when

- Multi-line code (use code with variant block)

### Accessibility

- Rendered as a real kbd element; text is escaped.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `label` | string | no | — | — | Plain-text key name, escaped; replaces children when both are given |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | The key name (an inline-text node in a tree) |

### Examples

#### Save shortcut (`save`)

```json
{}
```

#### Labelled key (`labelled`)

```json
{
  "label": "Ctrl"
}
```

### Related

- [`code`](components/code.md)
- [`inline-text`](components/inline-text.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# KPI

> A formatted metric with unit, previous-period delta and optional link.

- **id:** `kpi`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `display`

### Use when

- Show a numeric KPI with unit formatting and comparison

### Don't use when

- A free-form already-formatted string (use stat)

### Accessibility

- Loading and empty states are announced; linked tiles use real anchors after URL policy.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `label` | string | yes | — | — | — |
| `value` | number | no | — | — | Current numeric value (nullable) |
| `unit` | enum(number | compact | cents | percent) | no | — | `"number"` | — |
| `currency` | string | no | — | — | ISO currency when unit is cents |
| `previous` | number | no | — | — | — |
| `comparisonLabel` | string | no | — | — | — |
| `positive` | enum(up | down) | no | — | `"up"` | — |
| `sparkline` | slot | no | — | — | — |
| `href` | string | no | developer | — | — |
| `hrefTrust` | enum(developer | untrusted) | no | — | `"developer"` | — |
| `loading` | boolean | no | — | `false` | — |
| `empty` | unknown | no | — | — | true or empty message string |
| `variant` | enum(elevated | flat) | no | — | `"elevated"` | — |
| `class` | string | no | — | — | — |

### Examples

#### Orders KPI (`orders`)

```json
{
  "label": "Orders",
  "value": 1280,
  "unit": "compact",
  "previous": 1100,
  "comparisonLabel": "vs last week"
}
```

### Related

- [`stat`](components/stat.md)
- [`card`](components/card.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Label

> A form label with optional required marker and sr-only mode.

- **id:** `label`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `forms`

### Use when

- Label a control outside Field

### Don't use when

- A full field stack (use field)

### Accessibility

- srOnly keeps the label for assistive tech while hiding it visually.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `required` | boolean | no | — | `false` | — |
| `size` | enum(sm | md) | no | — | `"md"` | — |
| `srOnly` | boolean | no | — | `false` | — |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | The label text (an inline-text node in a tree) |

### Examples

#### Required label (`required`)

```json
{
  "required": true
}
```

### Related

- [`field`](components/field.md)
- [`description`](components/description.md)
- [`inline-text`](components/inline-text.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Auth split layout

> Sign-in form column plus brand panel.

- **id:** `layout-auth-split`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `layouts`

### Use when

- Sign-in and account entry pages

### Don't use when

- Post-auth app chrome

### Accessibility

- Form and brand panels are labelled
- Brand copy is author-provided

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `form` | slot | no | — | — | — |
| `mountScreen` | event | no | — | — | — |
| `brand` | slot | no | — | — | — |
| `panel` | slot | no | — | — | — |
| `brandTitle` | string | no | — | — | — |
| `brandDescription` | string | no | — | — | — |
| `brandEyebrow` | string | no | — | — | — |
| `formLabel` | string | no | — | — | — |
| `panelLabel` | string | no | — | — | — |
| `class` | string | no | — | — | — |

### Examples

#### Sign in (`sign-in`)

```json
{
  "brandTitle": "Harbor",
  "formLabel": "Sign in"
}
```

### Related

- [`layout-wizard`](components/layout-wizard.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Blog layout

> Blog/post reading layout (content-layout kind blog).

- **id:** `layout-blog`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `layouts`

### Use when

- Blog posts and field notes

### Don't use when

- Settings shells

### Accessibility

- Skip link targets main when chrome is present
- Primary navigation is a labelled landmark

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `mountScreen` | event | yes | — | — | Host callback that mounts the stable routed screen node |
| `nav` | object | no | — | — | NavModel for chrome links |
| `path` | string | no | — | — | Current hash path |
| `options` | object | no | — | — | Flat data-only layout knobs |
| `storageKey` | string | no | — | — | Scope for persisted UI flags |
| `aside` | slot | no | — | — | Optional context panel |
| `class` | string | no | — | — | — |

### Examples

#### Blog layout (`default`)

```json
{
  "options": {
    "title": "Field notes",
    "author": "Ada Example"
  }
}
```

### Related

- [`layout-host`](components/layout-host.md)
- [`layout-chrome`](components/layout-chrome.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Card layout

> Content card frame for grouped agent-authored blocks.

- **id:** `layout-card`
- **package:** `texuli`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `layouts`

### Use when

- Compose card layout structure in agent-authored trees

### Don't use when

- App chrome shells (sidebar, top-nav, dialogs)

### Accessibility

- Structure is semantic regions the host maps to real layout components
- No HTML strings; children are nested catalog nodes

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `title` | string | no | untrusted | — | — |
| `children` | slot | no | — | — | — |
| `class` | string | no | — | — | — |

### Examples

#### Card layout (`basic`)

```json
{
  "title": "Summary"
}
```

### Related

- [`layout-page`](components/layout-page.md)
- [`layout-doc`](components/layout-doc.md)
- [`layout-grid`](components/layout-grid.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# LayoutChrome

> Shared brand, actions, user and skip-link chrome for desktop layouts.

- **id:** `layout-chrome`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `layouts`

### Use when

- Layout frames that share brand and user chrome

### Don't use when

- Standalone navigation without a layout host

### Accessibility

- Skip link targets the main region
- Every href passes the URL policy

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `part` | enum(skip | brand | actions | user) | yes | — | — | — |
| `nav` | object | no | — | — | NavModel for chrome links |
| `mainId` | string | no | — | — | Main region id for the skip link |
| `compact` | boolean | no | — | `false` | — |
| `hrefTrust` | enum(developer | untrusted) | no | developer | `"developer"` | — |
| `skipLabel` | string | no | — | `"Skip to content"` | — |
| `class` | string | no | — | — | — |

### Examples

#### Brand chrome (`brand`)

```json
{
  "part": "brand"
}
```

### Related

- [`layout-host`](components/layout-host.md)
- [`nav-icon`](components/nav-icon.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Dashboard grid layout

> Top chrome plus container-query widget grid.

- **id:** `layout-dashboard-grid`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `layouts`

### Use when

- Analytics and operations dashboards

### Don't use when

- Long-form reading

### Accessibility

- Skip link targets main when chrome is present
- Primary navigation is a labelled landmark

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `mountScreen` | event | yes | — | — | Host callback that mounts the stable routed screen node |
| `nav` | object | no | — | — | NavModel for chrome links |
| `path` | string | no | — | — | Current hash path |
| `options` | object | no | — | — | Flat data-only layout knobs |
| `storageKey` | string | no | — | — | Scope for persisted UI flags |
| `aside` | slot | no | — | — | Optional context panel |
| `class` | string | no | — | — | — |
| `hrefTrust` | enum(developer | untrusted) | no | developer | `"developer"` | — |

### Examples

#### Dashboard grid layout (`default`)

```json
{
  "options": {
    "title": "Overview",
    "dense": false
  }
}
```

### Related

- [`layout-host`](components/layout-host.md)
- [`layout-chrome`](components/layout-chrome.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Deck layout

> Slide deck frame for sequenced content.

- **id:** `layout-deck`
- **package:** `texuli`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `layouts`

### Use when

- Compose deck layout structure in agent-authored trees

### Don't use when

- App chrome shells (sidebar, top-nav, dialogs)

### Accessibility

- Structure is semantic regions the host maps to real layout components
- No HTML strings; children are nested catalog nodes

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `title` | string | no | untrusted | — | — |
| `description` | string | no | untrusted | — | — |
| `locale` | string | no | — | — | Language tag such as en or en-GB |
| `aspect` | enum(16:9 | 4:3 | 9:16 | 1:1) | no | — | `"16:9"` | — |
| `themeRef` | unknown | no | — | — | Catalog theme id, or a catalog or embedded theme reference object |
| `masters` | array | no | — | — | Built-in slide master ids the slides may use |
| `settings` | object | no | — | — | startIndex, loop, showProgress and defaultTransition |
| `slides` | array | no | — | — | Structured slide objects (@texuli/deck model v2 grammar); prefer deck-slide children |
| `transition` | enum(none | fade | fade-up | slide | zoom | morph) | no | — | — | Default slide transition (model v2) |
| `motion` | enum(full | subtle | none) | no | — | — | Motion ceiling for the deck |
| `navigation` | object | no | — | — | loop, start slide id, autoSlideMs |
| `outline` | object | no | — | — | Sections and vertical stacks (model v2 outline) |
| `children` | slot | no | — | — | — |
| `class` | string | no | — | — | — |

### Examples

#### Deck layout (`basic`)

```json
{
  "title": "Pitch",
  "aspect": "16:9"
}
```

### Related

- [`layout-page`](components/layout-page.md)
- [`layout-doc`](components/layout-doc.md)
- [`layout-grid`](components/layout-grid.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Doc layout

> Document frame with optional table of contents.

- **id:** `layout-doc`
- **package:** `texuli`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `layouts`

### Use when

- Compose doc layout structure in agent-authored trees

### Don't use when

- App chrome shells (sidebar, top-nav, dialogs)

### Accessibility

- Structure is semantic regions the host maps to real layout components
- No HTML strings; children are nested catalog nodes

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `title` | string | no | untrusted | — | — |
| `toc` | boolean | no | — | `true` | — |
| `children` | slot | no | — | — | — |
| `class` | string | no | — | — | — |

### Examples

#### Doc layout (`basic`)

```json
{
  "title": "Guide",
  "toc": true
}
```

### Related

- [`layout-page`](components/layout-page.md)
- [`layout-grid`](components/layout-grid.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Docs layout

> Documentation reading layout (content-layout kind docs).

- **id:** `layout-docs`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `layouts`

### Use when

- Product docs and guides

### Don't use when

- App dashboards

### Accessibility

- Skip link targets main when chrome is present
- Primary navigation is a labelled landmark

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `mountScreen` | event | yes | — | — | Host callback that mounts the stable routed screen node |
| `nav` | object | no | — | — | NavModel for chrome links |
| `path` | string | no | — | — | Current hash path |
| `options` | object | no | — | — | Flat data-only layout knobs |
| `storageKey` | string | no | — | — | Scope for persisted UI flags |
| `aside` | slot | no | — | — | Optional context panel |
| `class` | string | no | — | — | — |

### Examples

#### Docs layout (`default`)

```json
{
  "options": {
    "title": "Guides"
  }
}
```

### Related

- [`layout-host`](components/layout-host.md)
- [`layout-chrome`](components/layout-chrome.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# LayoutDrawer

> Mobile navigation drawer built on the dialog primitive.

- **id:** `layout-drawer`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `layouts`

### Use when

- Narrow layouts that hide primary nav behind a menu

### Don't use when

- Desktop-only sidebars

### Accessibility

- Drawer is a labelled dialog
- Close control is named

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `open` | boolean | no | — | `false` | — |
| `label` | string | yes | — | — | Accessible drawer name |
| `closeLabel` | string | no | — | `"Close navigation"` | — |
| `children` | slot | no | — | — | — |

### Examples

#### Open drawer (`open`)

```json
{
  "open": true,
  "label": "Navigation"
}
```

### Related

- [`layout-sidebar`](components/layout-sidebar.md)
- [`dialog`](components/dialog.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Dual sidebar layout

> Primary nav plus optional context aside.

- **id:** `layout-dual-sidebar`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `layouts`

### Use when

- Tools that need nav and a context rail

### Don't use when

- Single-column reading layouts

### Accessibility

- Skip link targets main when chrome is present
- Primary navigation is a labelled landmark

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `mountScreen` | event | yes | — | — | Host callback that mounts the stable routed screen node |
| `nav` | object | no | — | — | NavModel for chrome links |
| `path` | string | no | — | — | Current hash path |
| `options` | object | no | — | — | Flat data-only layout knobs |
| `storageKey` | string | no | — | — | Scope for persisted UI flags |
| `aside` | slot | no | — | — | Optional context panel |
| `class` | string | no | — | — | — |
| `skipLabel` | string | no | — | — | — |
| `menuLabel` | string | no | — | — | — |
| `closeLabel` | string | no | — | — | — |

### Examples

#### Dual sidebar layout (`default`)

```json
{}
```

### Related

- [`layout-host`](components/layout-host.md)
- [`layout-chrome`](components/layout-chrome.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Editorial layout

> Long-read editorial layout (content-layout kind editorial).

- **id:** `layout-editorial`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `layouts`

### Use when

- Magazine-style long reads

### Don't use when

- Dense data grids

### Accessibility

- Skip link targets main when chrome is present
- Primary navigation is a labelled landmark

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `mountScreen` | event | yes | — | — | Host callback that mounts the stable routed screen node |
| `nav` | object | no | — | — | NavModel for chrome links |
| `path` | string | no | — | — | Current hash path |
| `options` | object | no | — | — | Flat data-only layout knobs |
| `storageKey` | string | no | — | — | Scope for persisted UI flags |
| `aside` | slot | no | — | — | Optional context panel |
| `class` | string | no | — | — | — |

### Examples

#### Editorial layout (`default`)

```json
{
  "options": {
    "title": "The long read"
  }
}
```

### Related

- [`layout-host`](components/layout-host.md)
- [`layout-chrome`](components/layout-chrome.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Grid layout

> Responsive content grid for agent-authored tiles.

- **id:** `layout-grid`
- **package:** `texuli`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `layouts`

### Use when

- Compose grid layout structure in agent-authored trees

### Don't use when

- App chrome shells (sidebar, top-nav, dialogs)

### Accessibility

- Structure is semantic regions the host maps to real layout components
- No HTML strings; children are nested catalog nodes

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `columns` | number | no | — | `2` | — |
| `gap` | string | no | — | `"1rem"` | — |
| `children` | slot | no | — | — | — |
| `class` | string | no | — | — | — |

### Examples

#### Grid layout (`basic`)

```json
{
  "columns": 2,
  "gap": "1rem"
}
```

### Related

- [`layout-page`](components/layout-page.md)
- [`layout-doc`](components/layout-doc.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# LayoutHost

> Resolves a layout id, applies width fallbacks, and keeps one stable screen outlet.

- **id:** `layout-host`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `layouts`

### Use when

- Apps that switch between shared layouts without remounting the screen

### Don't use when

- A single fixed page frame with no layout catalog

### Accessibility

- Loading state is named for assistive tech
- Screen outlet stays stable across layout switches

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `layout` | enum(sidebar | rail | top-nav | dual-sidebar | master-detail | dashboard-grid | docs | blog | editorial | marketing | mobile-tabs | mobile-drawer | wizard | auth-split | custom) | yes | — | — | Layout catalog id |
| `children` | slot | yes | — | — | Screen content |
| `nav` | object | no | — | — | NavModel for chrome links |
| `path` | string | no | — | — | Current hash path |
| `options` | object | no | — | — | Flat data-only layout knobs |
| `storageKey` | string | no | — | — | Scope for persisted UI flags |
| `aside` | slot | no | — | — | Optional context panel |
| `dir` | enum(ltr | rtl) | no | — | — | Document direction |
| `loadingLabel` | string | no | — | `"Loading layout"` | — |
| `class` | string | no | — | — | — |

### Examples

#### Sidebar host (`sidebar`)

```json
{
  "layout": "sidebar"
}
```

### Related

- [`layout-sidebar`](components/layout-sidebar.md)
- [`layout-chrome`](components/layout-chrome.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Landing layout

> Standalone marketing landing composition.

- **id:** `layout-landing`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `layouts`

### Use when

- Static landing pages without LayoutHost

### Don't use when

- Routed app shells

### Accessibility

- Author-provided landmarks; no default product copy.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `brand` | slot | no | — | — | — |
| `navigation` | slot | no | — | — | — |
| `actions` | slot | no | — | — | — |
| `hero` | slot | no | — | — | — |
| `sections` | slot | no | — | — | — |
| `footer` | slot | no | — | — | — |
| `class` | string | no | — | — | — |

### Examples

#### Landing (`basic`)

```json
{}
```

### Related

- [`layout-marketing`](components/layout-marketing.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Marketing layout

> Marketing page frame with hero, sections and footer slots.

- **id:** `layout-marketing`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `layouts`

### Use when

- Landing and product marketing pages

### Don't use when

- Authenticated app chrome

### Accessibility

- Hero and content regions can be labelled
- Navigation is a landmark

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `mountScreen` | event | no | — | — | Optional LayoutHost screen mount |
| `nav` | object | no | — | — | NavModel for chrome links |
| `path` | string | no | — | — | Current hash path |
| `options` | object | no | — | — | Flat data-only layout knobs |
| `storageKey` | string | no | — | — | Scope for persisted UI flags |
| `aside` | slot | no | — | — | Optional context panel |
| `brand` | slot | no | — | — | — |
| `navigation` | slot | no | — | — | — |
| `actions` | slot | no | — | — | — |
| `hero` | slot | no | — | — | — |
| `sections` | slot | no | — | — | — |
| `footer` | slot | no | — | — | — |
| `navigationLabel` | string | no | — | — | — |
| `heroLabel` | string | no | — | — | — |
| `contentLabel` | string | no | — | — | — |
| `class` | string | no | — | — | — |

### Examples

#### Marketing (`landing`)

```json
{}
```

### Related

- [`layout-landing`](components/layout-landing.md)
- [`layout-pricing`](components/layout-pricing.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Page layout

> Full page content frame for agent-authored documents.

- **id:** `layout-page`
- **package:** `texuli`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `layouts`

### Use when

- Compose page layout structure in agent-authored trees

### Don't use when

- App chrome shells (sidebar, top-nav, dialogs)

### Accessibility

- Structure is semantic regions the host maps to real layout components
- No HTML strings; children are nested catalog nodes

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `title` | string | no | untrusted | — | — |
| `description` | string | no | untrusted | — | — |
| `children` | slot | no | — | — | — |
| `class` | string | no | — | — | — |

### Examples

#### Page layout (`basic`)

```json
{
  "title": "Overview",
  "description": "Quarterly update"
}
```

### Related

- [`layout-doc`](components/layout-doc.md)
- [`layout-grid`](components/layout-grid.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Pricing layout

> Pricing plans grid with title and footnote.

- **id:** `layout-pricing`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `layouts`

### Use when

- Pricing tables on marketing pages

### Don't use when

- In-app billing settings (use settings layout)

### Accessibility

- Plans are a list of cards; title names the section.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `title` | string | no | — | — | — |
| `description` | string | no | — | — | — |
| `plans` | array | no | — | — | Plan cards data |
| `footnote` | string | no | — | — | — |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | — |

### Examples

#### Three plans (`plans`)

```json
{
  "title": "Plans",
  "plans": [
    {
      "id": "free",
      "name": "Free"
    }
  ]
}
```

### Related

- [`layout-marketing`](components/layout-marketing.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Row layout

> Children side by side, wrapping onto new lines when space runs out.

- **id:** `layout-row`
- **package:** `texuli`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `composition`

### Use when

- Place a few items next to each other, such as KPIs or actions

### Don't use when

- App chrome shells (sidebar, top-nav, dialogs)

### Accessibility

- DOM order stays reading order; the layout never reorders children visually
- Logical properties only, so right-to-left content mirrors

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `gap` | enum(none | small | medium | large) | no | — | — | Space between children. |
| `align` | enum(start | center | end | stretch) | no | — | — | — |
| `wrap` | boolean | no | — | `true` | — |
| `children` | slot | no | — | — | — |

### Examples

#### Row (`basic`)

```json
{
  "gap": "small",
  "align": "center"
}
```

### Related

- [`layout-stack`](components/layout-stack.md)
- [`layout-grid`](components/layout-grid.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Settings layout

> Settings section list plus detail pane.

- **id:** `layout-settings`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `layouts`

### Use when

- Account and workspace settings

### Don't use when

- Primary app navigation

### Accessibility

- Section list is labelled
- Phone back control is named

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `title` | string | no | — | `"Settings"` | — |
| `description` | string | no | — | — | — |
| `sections` | array | yes | — | — | — |
| `active` | string | no | — | — | — |
| `onSelect` | event | no | — | — | — |
| `startWithList` | boolean | no | — | — | — |
| `children` | slot | no | — | — | — |
| `mountScreen` | event | no | — | — | — |
| `navLabel` | string | no | — | — | — |
| `backLabel` | string | no | — | — | — |
| `class` | string | no | — | — | — |

### Examples

#### Account settings (`account`)

```json
{
  "sections": [
    {
      "id": "profile",
      "label": "Profile"
    }
  ],
  "active": "profile"
}
```

### Related

- [`layout-wizard`](components/layout-wizard.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Sidebar layout

> App sidebar column with responsive drawer fallback.

- **id:** `layout-sidebar`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `layouts`

### Use when

- Desktop apps with persistent primary navigation

### Don't use when

- Marketing landing pages

### Accessibility

- Skip link targets main when chrome is present
- Primary navigation is a labelled landmark

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `mountScreen` | event | yes | — | — | Host callback that mounts the stable routed screen node |
| `nav` | object | no | — | — | NavModel for chrome links |
| `path` | string | no | — | — | Current hash path |
| `options` | object | no | — | — | Flat data-only layout knobs |
| `storageKey` | string | no | — | — | Scope for persisted UI flags |
| `aside` | slot | no | — | — | Optional context panel |
| `class` | string | no | — | — | — |
| `skipLabel` | string | no | — | — | — |
| `menuLabel` | string | no | — | — | — |
| `closeLabel` | string | no | — | — | — |

### Examples

#### Sidebar layout (`default`)

```json
{}
```

### Related

- [`layout-host`](components/layout-host.md)
- [`layout-chrome`](components/layout-chrome.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Split layout

> Two panes side by side at a fixed ratio, stacked on narrow screens.

- **id:** `layout-split`
- **package:** `texuli`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `composition`

### Use when

- Show a primary pane with a supporting pane, such as text beside a chart

### Don't use when

- App chrome shells (sidebar, top-nav, dialogs)

### Accessibility

- DOM order stays reading order; the layout never reorders children visually
- Logical properties only, so right-to-left content mirrors

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `ratio` | enum(1:1 | 1:2 | 2:1 | 1:3 | 3:1) | no | — | `"1:1"` | — |
| `gap` | enum(none | small | medium | large) | no | — | — | Space between children. |
| `children` | slot | no | — | — | — |

### Examples

#### Split (`basic`)

```json
{
  "ratio": "2:1"
}
```

### Related

- [`layout-row`](components/layout-row.md)
- [`layout-grid`](components/layout-grid.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Stack layout

> Children in one column, in reading order, with a fixed gap.

- **id:** `layout-stack`
- **package:** `texuli`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `composition`

### Use when

- Group content vertically with consistent spacing

### Don't use when

- App chrome shells (sidebar, top-nav, dialogs)

### Accessibility

- DOM order stays reading order; the layout never reorders children visually
- Logical properties only, so right-to-left content mirrors

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `gap` | enum(none | small | medium | large) | no | — | — | Space between children. |
| `children` | slot | no | — | — | — |

### Examples

#### Stack (`basic`)

```json
{
  "gap": "medium"
}
```

### Related

- [`layout-row`](components/layout-row.md)
- [`layout-split`](components/layout-split.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Grid tile

> A titled tile inside layout-grid that can span several columns or rows.

- **id:** `layout-tile`
- **package:** `texuli`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `composition`

### Use when

- Make one dashboard tile wider or taller than its neighbors

### Don't use when

- App chrome shells (sidebar, top-nav, dialogs)

### Accessibility

- DOM order stays reading order; the layout never reorders children visually
- Logical properties only, so right-to-left content mirrors

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `title` | string | no | untrusted | — | — |
| `span` | number | no | — | `1` | Columns, 1 to 4. |
| `rowSpan` | number | no | — | `1` | Rows, 1 or 2. |
| `children` | slot | no | — | — | — |

### Examples

#### Wide tile (`wide`)

```json
{
  "title": "Trend",
  "span": 2
}
```

### Related

- [`layout-grid`](components/layout-grid.md)
- [`layout-card`](components/layout-card.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Top navigation layout

> Horizontal top navigation with optional mobile menu.

- **id:** `layout-top-nav`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `layouts`

### Use when

- Product shells with a top bar

### Don't use when

- Dense multi-section sidebars

### Accessibility

- Skip link targets main when chrome is present
- Primary navigation is a labelled landmark

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `mountScreen` | event | yes | — | — | Host callback that mounts the stable routed screen node |
| `nav` | object | no | — | — | NavModel for chrome links |
| `path` | string | no | — | — | Current hash path |
| `options` | object | no | — | — | Flat data-only layout knobs |
| `storageKey` | string | no | — | — | Scope for persisted UI flags |
| `aside` | slot | no | — | — | Optional context panel |
| `class` | string | no | — | — | — |
| `skipLabel` | string | no | — | — | — |
| `menuLabel` | string | no | — | — | — |
| `closeLabel` | string | no | — | — | — |

### Examples

#### Top navigation layout (`default`)

```json
{}
```

### Related

- [`layout-host`](components/layout-host.md)
- [`layout-chrome`](components/layout-chrome.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Wizard layout

> Centered onboarding wizard frame with steps.

- **id:** `layout-wizard`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `layouts`

### Use when

- Multi-step setup and onboarding

### Don't use when

- Single-page forms

### Accessibility

- Steps expose current position
- Back and next controls are named

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `steps` | array | no | — | — | — |
| `content` | slot | no | — | — | — |
| `mountScreen` | event | no | — | — | — |
| `current` | number | no | — | `0` | — |
| `title` | string | no | — | — | — |
| `description` | string | no | — | — | — |
| `canAdvance` | event | no | — | — | — |
| `validate` | event | no | — | — | — |
| `onFinish` | event | no | — | — | — |
| `onStepChange` | event | no | — | — | — |
| `backLabel` | string | no | — | — | — |
| `nextLabel` | string | no | — | — | — |
| `finishLabel` | string | no | — | — | — |
| `secondaryActions` | slot | no | — | — | — |
| `brand` | slot | no | — | — | — |
| `class` | string | no | — | — | — |

### Examples

#### Onboarding (`onboarding`)

```json
{
  "title": "Welcome",
  "steps": [
    {
      "id": "profile",
      "label": "Profile"
    }
  ],
  "current": 0
}
```

### Related

- [`layout-auth-split`](components/layout-auth-split.md)
- [`layout-settings`](components/layout-settings.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Link

> An inline sentence link. Underline and color come from link tokens; href is filtered by the URL policy.

- **id:** `link`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `display`

### Use when

- A word or phrase inside a sentence that navigates

### Don't use when

- A button-shaped control (use button with href)
- A whole card (use card with href)

### Accessibility

- Renders one real link that wraps in the line
- http(s) destinations, external, and target=_blank add rel=noopener noreferrer
- A refused href renders as text, never a dead link

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `href` | string | yes | developer | — | Destination (URL policy) |
| `hrefTrust` | enum(developer | untrusted) | no | — | `"developer"` | — |
| `external` | boolean | no | — | `false` | Adds rel=noopener noreferrer (also added for http(s) and target=_blank) |
| `target` | string | no | — | — | Link target; _blank always adds noopener noreferrer |
| `rel` | string | no | — | — | Extra rel tokens; noopener/noreferrer are merged when needed |
| `label` | string | no | — | — | Plain-text label, escaped |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | Rich link text; replaced by a non-empty label |

### Examples

#### Inline sentence link (`inline`)

```json
{
  "href": "https://example.com/guide",
  "label": "the harbor guide"
}
```

#### External link (`external`)

```json
{
  "href": "https://example.com/docs",
  "external": true,
  "label": "Docs"
}
```

### Related

- [`button`](components/button.md)
- [`prose`](components/prose.md)
- [`text`](components/text.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# List

> A list of ListItem rows; divided draws a token hairline between them.

- **id:** `list`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `display`

### Use when

- A stack of settings, inbox or navigation rows

### Don't use when

- A data table (use table)
- Prose lists (use prose)

### Accessibility

- A ul of listitems. Dividers are decorative.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `divided` | boolean | no | — | `false` | — |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | ListItem rows |

### Examples

#### Divided inbox (`inbox`)

```json
{
  "divided": true
}
```

### Related

- [`list-item`](components/list-item.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# ListItem

> A list row with a title, optional description, icon and trailing meta.

- **id:** `list-item`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `display`

### Use when

- A settings row, an inbox row, or a navigation list of links

### Don't use when

- A data table (use table)
- A kanban card (use data-board)

### Accessibility

- A listitem; with href it is a link, with onSelect a button. Trailing controls sit outside the main control.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `title` | string | no | untrusted | — | — |
| `description` | string | no | untrusted | — | — |
| `meta` | string | no | untrusted | — | — |
| `icon` | string | no | — | — | Built-in or registered icon name |
| `href` | string | no | untrusted | — | — |
| `hrefTrust` | enum(developer | untrusted) | no | — | `"developer"` | — |
| `current` | boolean | no | — | `false` | — |
| `disabled` | boolean | no | — | `false` | — |
| `divided` | boolean | no | — | `false` | Hairline under this row |
| `class` | string | no | — | — | — |

### Examples

#### Inbox row (`inbox`)

```json
{
  "title": "Quarterly notes",
  "description": "Ada Example",
  "meta": "2h",
  "icon": "info"
}
```

### Related

- [`icon`](components/icon.md)
- [`avatar`](components/avatar.md)
- [`list`](components/list.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Mark

> An inline highlight for search results, from role soft tokens.

- **id:** `mark`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `display`

### Use when

- Highlight a search match inside a title or body

### Don't use when

- A status badge (use badge)
- Struck text (use text strikethrough)

### Accessibility

- A real mark element; the words still say the match. Forced colors use Highlight.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `tone` | enum(warning | primary | success | info) | no | — | `"warning"` | — |
| `label` | string | no | — | — | Plain text, escaped |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | — |

### Examples

#### Search hit (`search`)

```json
{
  "tone": "warning",
  "label": "quarter"
}
```

### Related

- [`text`](components/text.md)
- [`heading`](components/heading.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Canvas composition

> A validated layered composition rendered to a canvas.

- **id:** `media-composition-canvas`
- **package:** `@texuli/media`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `content`

### Use when

- Render canvas composition from structured content data.

### Don't use when

- Application navigation, account controls or mutations.

### Accessibility

- Provide the required accessible title, description or text alternatives.
- Keep data available in the component-provided text or table alternative.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `composition` | object | yes | — | — | — |
| `trust` | enum(developer | untrusted) | no | — | — | — |
| `label` | string | no | — | — | — |
| `labels` | object | no | — | — | — |
| `pixelRatio` | number | no | — | — | — |
| `dir` | enum(ltr | rtl) | no | — | — | — |
| `fontFamily` | string | no | — | — | — |
| `background` | string | no | — | — | — |
| `loadImage` | event | no | — | — | Host-provided callback; omit when no host behavior is needed. |
| `onrender` | event | no | — | — | Host-provided callback; omit when no host behavior is needed. |

### Examples

#### Canvas composition example (`basic`)

```json
{
  "composition": {
    "width": 320,
    "height": 180,
    "layers": []
  }
}
```

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# SVG composition

> A validated, structured vector composition.

- **id:** `media-composition-svg`
- **package:** `@texuli/media`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `content`

### Use when

- Render svg composition from structured content data.

### Don't use when

- Application navigation, account controls or mutations.

### Accessibility

- Provide the required accessible title, description or text alternatives.
- Keep data available in the component-provided text or table alternative.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `composition` | object | yes | — | — | — |
| `trust` | enum(developer | untrusted) | no | — | — | — |
| `title` | string | no | — | — | — |
| `description` | string | no | — | — | — |
| `validate` | boolean | no | — | — | — |
| `focusable` | boolean | no | — | — | — |
| `className` | string | no | — | — | — |
| `class` | string | no | — | — | — |

### Examples

#### SVG composition example (`basic`)

```json
{
  "composition": {
    "width": 320,
    "height": 180,
    "layers": []
  }
}
```

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Responsive image

> A responsive image with URL validation, loading states and actions.

- **id:** `media-image`
- **package:** `@texuli/media`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `content`

### Use when

- Render responsive image from structured content data.

### Don't use when

- Application navigation, account controls or mutations.

### Accessibility

- Provide the required accessible title, description or text alternatives.
- Keep data available in the component-provided text or table alternative.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `src` | string | yes | untrusted | — | URL input is checked by the package URL policy. |
| `srcDark` | string | no | untrusted | — | URL input is checked by the package URL policy. |
| `darkMode` | enum(theme | system) | no | — | — | — |
| `srcset` | string | no | — | — | — |
| `sizes` | string | no | — | — | — |
| `widths` | array | no | — | — | — |
| `loader` | event | no | — | — | Host-provided callback; omit when no host behavior is needed. |
| `alt` | string | yes | — | — | — |
| `width` | number | no | — | — | — |
| `height` | number | no | — | — | — |
| `fit` | enum(cover | contain | fill | none | scale-down) | no | — | — | — |
| `focalPoint` | object | no | — | — | — |
| `placeholder` | object | no | — | — | — |
| `loading` | enum(eager | lazy) | no | — | — | — |
| `fetchPriority` | enum(high | low | auto) | no | — | — | — |
| `trust` | enum(developer | untrusted) | no | — | — | — |
| `href` | string | no | untrusted | — | URL input is checked by the package URL policy. |
| `onactivate` | event | no | — | — | Host-provided callback; omit when no host behavior is needed. |
| `actionLabel` | string | no | — | — | — |
| `labels` | object | no | — | — | — |
| `onload` | event | no | — | — | Host-provided callback; omit when no host behavior is needed. |
| `onerror` | event | no | — | — | Host-provided callback; omit when no host behavior is needed. |
| `onstatus` | event | no | — | — | Host-provided callback; omit when no host behavior is needed. |
| `class` | string | no | — | — | — |

### Examples

#### Responsive image example (`basic`)

```json
{
  "src": "images/team.webp",
  "alt": "A team planning together"
}
```

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Menubar

> Application menubar with roving top-level items.

- **id:** `menubar`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `overlays`

### Use when

- Desktop-style File/Edit/View bars

### Don't use when

- A single actions button (use dropdown-menu)

### Accessibility

- role=menubar; one Tab stop; arrows move between menus.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `value` | string | no | — | — | Open menu value or empty |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | — |
| `loop` | boolean | no | — | `true` | — |
| `dir` | enum(ltr | rtl) | no | — | — | — |

### Examples

#### Application bar (`app`)

```json
{
  "value": "file"
}
```

### Related

- [`menubar-trigger`](components/menubar-trigger.md)
- [`dropdown-menu`](components/dropdown-menu.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Menubar.Trigger

> Top-level menubar item that opens a menu.

- **id:** `menubar-trigger`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `overlays`

### Use when

- Label a menubar menu

### Don't use when

- Dropdown button triggers

### Accessibility

- role=menuitem with aria-haspopup=menu.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | enum(sm | md | lg) | no | — | `"md"` | — |
| `variant` | enum(default | soft) | no | — | `"default"` | — |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | — |
| `disabled` | boolean | no | — | `false` | — |

### Examples

#### File (`file`)

```json
{}
```

### Related

- [`menubar`](components/menubar.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# MobileAppFrame

> A phone-sized app frame: skip link, header, scrolling screen, optional footer and bottom nav. Host chrome; agents never emit it.

- **id:** `mobile-app-frame`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `layouts`

### Use when

- The host shell of a phone-sized app

### Don't use when

- In-page content (use layout-page)
- Desktop chrome (use layout-sidebar)

### Accessibility

- A skip link to the screen; the screen is a main landmark unless nested.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `skipLabel` | string | no | — | — | — |
| `mainId` | string | no | — | — | — |
| `mainElement` | enum(main | div) | no | — | `"main"` | — |
| `resetScrollOnNavigate` | boolean | no | — | `true` | — |
| `stickyFooterUnstyled` | boolean | no | — | `false` | — |
| `class` | string | no | — | — | — |

### Examples

#### Phone frame (`phone`)

```json
{
  "mainId": "screen"
}
```

### Related

- [`bottom-nav`](components/bottom-nav.md)
- [`mobile-header`](components/mobile-header.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# MobileHeader

> A mobile stack header with back, title and actions. Host chrome; agents never emit it.

- **id:** `mobile-header`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `layouts`

### Use when

- The top of a phone-sized screen that can go back

### Don't use when

- Desktop app chrome (use layout-top-nav or layout-sidebar)

### Accessibility

- The title is a heading by default; Back and Close are named.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `title` | string | yes | — | — | — |
| `eyebrow` | string | no | — | — | — |
| `subtitle` | string | no | — | — | — |
| `titleAs` | enum(h1 | h2 | p | div) | no | — | `"h1"` | — |
| `backHref` | string | no | developer | — | — |
| `onBack` | event | no | — | — | — |
| `backLabel` | string | no | — | — | — |
| `backTarget` | string | no | — | — | — |
| `hrefTrust` | enum(developer | untrusted) | no | — | `"developer"` | — |
| `closeHref` | string | no | developer | — | — |
| `onClose` | event | no | — | — | — |
| `closeLabel` | string | no | — | — | — |
| `sticky` | boolean | no | — | `true` | — |
| `class` | string | no | — | — | — |

### Examples

#### Inbox header (`inbox`)

```json
{
  "title": "Inbox",
  "backHref": "/home"
}
```

### Related

- [`bottom-nav`](components/bottom-nav.md)
- [`mobile-app-frame`](components/mobile-app-frame.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# MultiSelect

> A combobox for several values, shown as removable chips.

- **id:** `multi-select`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `forms`

### Use when

- Choose several values from a long list by typing

### Don't use when

- One value (use combobox or select)
- A few independent options (use checkbox)

### Accessibility

- Chips can be removed with their button or Backspace from an empty input
- Submits one form entry per selected value

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `value` | unknown | no | — | — | Selected value (a string, or a string array when multiple) |
| `defaultValue` | unknown | no | — | — | Starting selection; a form reset restores it |
| `inputValue` | string | no | — | — | Text in the input (bindable) |
| `defaultInputValue` | string | no | — | `""` | — |
| `items` | array | no | — | — | Options as { value, label, disabled? } |
| `loadOptions` | unknown | no | — | — | Function prop the host passes: (query, signal) => Promise<items> for remote options. Not agent-emittable (functions are not data). |
| `filter` | unknown | no | — | — | Function prop the host passes: (item, query) => boolean. Replaces the default match (label contains the query, ignoring case); runs on the trimmed, non-empty query; unused with loadOptions. createFoldedFilter builds an accent-insensitive one. Not agent-emittable (functions are not data). |
| `disabled` | boolean | no | — | `false` | Not interactive, not submitted, not validated |
| `name` | string | no | — | — | Form field name: submits the value (one entry per value when multiple) |
| `required` | boolean | no | — | `false` | Blocks form submission until a value is selected |
| `requiredMessage` | string | no | — | — | Translated message when required blocks submission (default: the browser message) |
| `form` | string | no | — | — | Associated form id |
| `open` | boolean | no | — | `false` | — |
| `size` | enum(sm | md | lg) | no | — | `"md"` | — |
| `variant` | enum(outline | soft) | no | — | `"outline"` | — |
| `class` | string | no | — | — | — |
| `onValueChange` | event | no | — | — | — |
| `onInputValueChange` | event | no | — | — | — |
| `onOpenChange` | event | no | — | — | — |
| `children` | slot | no | — | — | — |

### Examples

#### Tags field (`tags`)

```json
{
  "name": "tags",
  "variant": "outline",
  "size": "md"
}
```

### Related

- [`combobox`](components/combobox.md)
- [`checkbox`](components/checkbox.md)
- [`field`](components/field.md)
- [`form`](components/form.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# NavIcon

> Renders a nav model icon by name or component.

- **id:** `nav-icon`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `layouts`

### Use when

- Layout chrome needs a consistent nav icon

### Don't use when

- Arbitrary illustration outside nav

### Accessibility

- Decorative by default; pass label when the icon is the only name.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `icon` | string | yes | — | — | Icon name (hosts may also pass a component in code) |
| `class` | string | no | — | — | — |
| `label` | string | no | — | — | — |

### Examples

#### Home icon (`home`)

```json
{
  "icon": "home"
}
```

### Related

- [`layout-chrome`](components/layout-chrome.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# NavigationMenu

> Site or app navigation with expandable triggers and links.

- **id:** `navigation-menu`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `overlays`

### Use when

- Primary site navigation with flyouts

### Don't use when

- In-page tabs (use tabs)
- App menubar (use menubar)

### Accessibility

- Landmarks and link semantics; triggers expose expanded state.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `value` | string | no | — | — | — |
| `orientation` | enum(horizontal | vertical) | no | — | `"horizontal"` | — |
| `dir` | enum(ltr | rtl) | no | — | — | — |
| `delayDuration` | number | no | — | — | — |
| `onValueChange` | event | no | — | — | — |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | — |

### Examples

#### Main nav (`main`)

```json
{
  "orientation": "horizontal"
}
```

### Related

- [`menubar`](components/menubar.md)
- [`breadcrumb`](components/breadcrumb.md)
- [`sidebar`](components/sidebar.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# NumberField

> A numeric value with optional steppers, min, max and locale formatting.

- **id:** `number-field`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `forms`

### Use when

- A quantity, amount or count the person types or steps

### Don't use when

- A time of day (use time-field)
- A PIN or code (use pin-input)

### Accessibility

- A labelled spinbutton; steppers are named Increment and Decrement.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `value` | number | no | — | — | The value, or null when empty (bind:value) |
| `min` | number | no | — | — | — |
| `max` | number | no | — | — | — |
| `step` | number | no | — | `1` | — |
| `disabled` | boolean | no | — | `false` | — |
| `readOnly` | boolean | no | — | `false` | — |
| `required` | boolean | no | — | `false` | — |
| `name` | string | no | — | — | — |
| `size` | enum(sm | md | lg) | no | — | `"md"` | — |
| `display` | enum(input | output) | no | — | `"input"` | — |
| `commit` | enum(enter | blur | input) | no | — | `"enter"` | When typed text commits: Enter and blur, blur only, or every keystroke |
| `onValueChange` | event | no | — | — | — |
| `class` | string | no | — | — | — |

### Examples

#### Quantity (`quantity`)

```json
{
  "value": 2,
  "min": 0,
  "max": 99,
  "name": "qty"
}
```

### Related

- [`field`](components/field.md)
- [`input`](components/input.md)
- [`pin-input`](components/pin-input.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Pagination

> Page controls for long lists.

- **id:** `pagination`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `overlays`

### Use when

- Paging tables or search results

### Don't use when

- Infinite scroll only feeds

### Accessibility

- Named navigation; previous/next buttons disabled at ends.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `page` | number | no | — | `1` | — |
| `pageCount` | number | yes | — | — | — |
| `size` | enum(sm | md | lg) | no | — | `"md"` | — |
| `variant` | enum(outline | soft) | no | — | `"outline"` | — |
| `onPageChange` | event | no | — | — | — |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | — |
| `label` | string | no | — | — | — |

### Examples

#### Twelve pages (`pages`)

```json
{
  "page": 1,
  "pageCount": 12
}
```

### Related

- [`breadcrumb`](components/breadcrumb.md)
- [`table`](components/table.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# PinInput

> A one-time code of fixed length, one cell per character.

- **id:** `pin-input`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `forms`

### Use when

- A short confirmation or PIN the person types

### Don't use when

- A free numeric quantity (use number-field)

### Accessibility

- One real input; cells are presentational. Paste fills every cell.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `value` | string | no | — | — | The code so far (bind:value) |
| `maxlength` | number | no | — | `4` | — |
| `mask` | boolean | no | — | `false` | — |
| `disabled` | boolean | no | — | `false` | — |
| `size` | enum(sm | md | lg) | no | — | `"md"` | — |
| `onValueChange` | event | no | — | — | — |
| `onComplete` | event | no | — | — | — |
| `class` | string | no | — | — | — |

### Examples

#### One-time code (`otp`)

```json
{
  "maxlength": 6
}
```

### Related

- [`field`](components/field.md)
- [`input`](components/input.md)
- [`number-field`](components/number-field.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Popover

> Non-modal floating panel anchored to a trigger.

- **id:** `popover`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `overlays`

### Use when

- Lightweight detail next to a control
- Pickers that are not full dialogs

### Don't use when

- Modal workflows (use dialog)
- Single-line hints (use tooltip)

### Accessibility

- Focus can move into the panel; Escape dismisses.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `open` | boolean | no | — | `false` | — |
| `onOpenChange` | event | no | — | — | — |
| `children` | slot | no | — | — | — |

### Examples

#### Open popover (`open`)

```json
{
  "open": true
}
```

### Related

- [`hover-card`](components/hover-card.md)
- [`tooltip`](components/tooltip.md)
- [`dialog`](components/dialog.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Popover.Content

> Styled popover surface with optional arrow.

- **id:** `popover-content`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `overlays`

### Use when

- Body of a popover

### Don't use when

- Menu lists (use dropdown-menu-content)

### Accessibility

- Provide a visible heading or aria-label when needed.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `variant` | enum(elevated | flat) | no | — | `"elevated"` | — |
| `size` | enum(sm | md | lg) | no | — | `"md"` | — |
| `arrow` | boolean | no | — | `true` | — |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | — |
| `side` | enum(top | right | bottom | left) | no | — | `"bottom"` | — |
| `align` | enum(start | center | end) | no | — | `"center"` | — |
| `sideOffset` | number | no | — | `8` | — |
| `initialFocus` | unknown | no | — | — | An element inside the content, or a function returning one, to focus on open (for example the selected date). Falls back to the first control, else the content. Host-only: not agent-emittable (elements and functions are not data). |

### Examples

#### Elevated (`elevated`)

```json
{
  "variant": "elevated"
}
```

### Related

- [`popover`](components/popover.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Progress

> A linear or circular progress bar, determinate or indeterminate.

- **id:** `progress`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `display`

### Use when

- Show how far a task has gone, or that it is still running

### Don't use when

- A short wait with no value (use spinner)

### Accessibility

- A progressbar named by label or ariaLabel; null value is indeterminate.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `value` | number | no | — | `0` | Current value; omit or null while unknown |
| `max` | number | no | — | `100` | — |
| `min` | number | no | — | `0` | — |
| `label` | string | no | — | — | — |
| `ariaLabel` | string | no | — | — | — |
| `showValue` | boolean | no | — | `false` | — |
| `tone` | enum(primary | success | warning | destructive | info | neutral) | no | — | `"primary"` | — |
| `size` | enum(sm | md | lg) | no | — | `"md"` | — |
| `shape` | enum(linear | circular) | no | — | `"linear"` | — |
| `loadingLabel` | string | no | — | — | — |
| `class` | string | no | — | — | — |

### Examples

#### Upload (`upload`)

```json
{
  "value": 40,
  "label": "Upload",
  "showValue": true
}
```

### Related

- [`spinner`](components/spinner.md)
- [`skeleton`](components/skeleton.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Prose

> Long-form text with the design system's reading rhythm: measure, spacing, headings, lists.

- **id:** `prose`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `display`

### Use when

- Articles, docs, descriptions and other long text written as markup

### Don't use when

- One line or a short label (use text)
- A block document (use document)

### Accessibility

- Keeps the host markup and its semantics; a 65ch measure keeps lines readable.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `as` | enum(div | article | section) | no | — | `"div"` | — |
| `size` | enum(md | lg) | no | — | `"md"` | — |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | The long-form markup (paragraphs, headings, lists) |

### Examples

#### Article body (`article`)

```json
{
  "as": "article",
  "size": "md"
}
```

### Related

- [`heading`](components/heading.md)
- [`text`](components/text.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Radio

> One option inside a RadioGroup.

- **id:** `radio`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `forms`

### Use when

- A single exclusive option inside radio-group

### Don't use when

- Independent toggles (use checkbox or switch)

### Accessibility

- value is required; card layout keeps the label associated with the control.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `value` | string | yes | — | — | — |
| `disabled` | boolean | no | — | `false` | — |
| `id` | string | no | — | — | — |
| `label` | string | no | — | — | — |
| `description` | string | no | — | — | — |
| `size` | enum(sm | md) | no | — | `"md"` | — |
| `card` | boolean | no | — | `false` | — |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | — |

### Examples

#### Radio option (`option`)

```json
{
  "value": "mail",
  "label": "Email"
}
```

### Related

- [`radio-group`](components/radio-group.md)
- [`checkbox`](components/checkbox.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# RadioGroup

> A set of exclusive radio options with keyboard roving.

- **id:** `radio-group`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `forms`

### Use when

- Pick exactly one option from a short closed set

### Don't use when

- Many options with search (use select or combobox)
- Independent toggles

### Accessibility

- Arrow keys move focus; Space selects; loop wraps at the ends.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `value` | string | no | — | — | — |
| `onValueChange` | event | no | — | — | — |
| `name` | string | no | — | — | — |
| `required` | boolean | no | — | `false` | — |
| `disabled` | boolean | no | — | `false` | — |
| `readonly` | boolean | no | — | `false` | — |
| `orientation` | enum(vertical | horizontal) | no | — | `"vertical"` | — |
| `variant` | enum(default | card) | no | — | `"default"` | — |
| `size` | enum(sm | md) | no | — | `"md"` | — |
| `items` | array | no | — | — | Convenience option list; use children with Radio for custom layouts |
| `loop` | boolean | no | — | `true` | — |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | — |

### Examples

#### Vertical group (`vertical`)

```json
{
  "orientation": "vertical",
  "items": [
    {
      "value": "mail",
      "label": "Email"
    },
    {
      "value": "sms",
      "label": "SMS"
    }
  ]
}
```

### Related

- [`radio`](components/radio.md)
- [`select`](components/select.md)
- [`checkbox`](components/checkbox.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Rating

> A star rating the person sets, or a read-only average.

- **id:** `rating`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `forms`

### Use when

- A score out of five (or up to ten) stars

### Don't use when

- A binary like/unlike (use a toggle)

### Accessibility

- A labelled radio group; arrows move and select. Display mode is a named image.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `value` | number | no | — | `0` | — |
| `max` | number | no | — | `5` | — |
| `allowHalf` | boolean | no | — | `false` | — |
| `display` | boolean | no | — | `false` | — |
| `clearable` | boolean | no | — | `false` | — |
| `readonly` | boolean | no | — | `false` | — |
| `disabled` | boolean | no | — | `false` | — |
| `required` | boolean | no | — | `false` | — |
| `name` | string | no | — | — | — |
| `size` | enum(sm | md | lg) | no | — | `"md"` | — |
| `tone` | enum(warning | primary | neutral) | no | — | `"warning"` | — |
| `showValue` | boolean | no | — | `false` | — |
| `labels` | object | no | — | — | — |
| `onValueChange` | event | no | — | — | — |
| `class` | string | no | — | — | — |

### Examples

#### Review (`review`)

```json
{
  "value": 4,
  "max": 5,
  "name": "rating"
}
```

### Related

- [`field`](components/field.md)
- [`radio-group`](components/radio-group.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# ResponsiveModal

> Dialog on large screens, drawer/sheet on small screens.

- **id:** `responsive-modal`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `overlays`

### Use when

- One flow that should adapt across breakpoints

### Don't use when

- Fixed desktop-only dialogs

### Accessibility

- Preserves dialog semantics on large viewports.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | enum(sm | md | lg | xl) | no | — | `"md"` | — |
| `side` | enum(top | right | bottom | left | start | end | center) | no | — | `"bottom"` | — |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | — |

### Examples

#### Adaptive (`adaptive`)

```json
{
  "size": "md"
}
```

### Related

- [`dialog`](components/dialog.md)
- [`drawer`](components/drawer.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Schema form

> A whole form as data: typed fields in sections or steps, conditional logic, named formats and cross-field rules, painted with texuli controls; submitting proposes one action intent to the host.

- **id:** `schema-form`
- **package:** `@texuli/forms`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `schema-forms`

### Use when

- Collect structured answers: registrations, requests, surveys, intake and settings
- A multi-step flow with per-step validation, or fields that appear, become required or become editable from earlier answers

### Don't use when

- One or two values for an action: use action-form with form-field
- Payment: use a host-region. Password and one-time-code (otp) fields only where the host allows credential fields
- A filter bar over data: use control-filter or data-filter-builder

### Accessibility

- A form landmark named by its title; every control is a texuli control with a visible label, its description and its error linked
- Errors are announced, an error summary takes focus and links to each field; each new step heading takes focus and is announced
- Keyboard-complete: native order, Enter moves to the next step or submits; reduced motion makes step transitions instant

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `schema` | object | yes | — | — | The form: { title, description?, submitLabel?, fields \| sections \| steps, rules? }. Field types: text, textarea, number, email, url (protocols: ["https"] by default, ["http", "https"] to allow http), date, time, datetime (YYYY-MM-DDTHH:MM), select (clearable: an empty choice, on by default while optional), multiselect, checkbox, radio, switch, slider, file (host-handled), tags, color (#hex), password and otp (credential fields, refused unless the host allows them), and custom (painted by the host: kind must be a kind the host registered, config holds scalar settings). Rules: required, minLength, maxLength, min, max, step, minItems, maxItems, a named format (email, url, phone, postal-code…, never a pattern) and validator (a name the host registered). when.show / require / enable are expressions over earlier fields; rules[] are cross-field expressions that fail when false. |
| `action` | string | yes | — | — | The action name the host receives with the submitted values. |
| `label` | string | no | untrusted | — | Accessible name; defaults to the form title. |

### Examples

#### Access request (`request`)

```json
{
  "action": "request-access",
  "schema": {
    "title": "Request access",
    "submitLabel": "Send request",
    "fields": [
      {
        "name": "email",
        "type": "email",
        "label": "Work email",
        "required": true
      },
      {
        "name": "team",
        "type": "select",
        "label": "Team",
        "required": true,
        "options": [
          {
            "value": "design",
            "label": "Design"
          },
          {
            "value": "engineering",
            "label": "Engineering"
          }
        ]
      },
      {
        "name": "reason",
        "type": "textarea",
        "label": "Why do you need access?",
        "maxLength": 500,
        "when": {
          "require": {
            "op": "eq",
            "left": {
              "op": "field",
              "name": "team"
            },
            "right": {
              "op": "str",
              "value": "engineering"
            }
          }
        }
      }
    ]
  }
}
```

### Related

- [`action-form`](components/action-form.md)
- [`form-field`](components/form-field.md)
- [`layout-wizard`](components/layout-wizard.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# ScreenOutlet

> Stable screen mount point that survives layout switches.

- **id:** `screen-outlet`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `layouts`

### Use when

- LayoutHost needs a durable screen node

### Don't use when

- Static pages without layout switching

### Accessibility

- Outlet is a plain region; screen content supplies its own landmarks.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `children` | slot | yes | — | — | — |
| `onready` | event | no | — | — | Fires with the outlet element |

### Examples

#### Outlet (`basic`)

```json
{}
```

### Related

- [`layout-host`](components/layout-host.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Select

> A single-value select root with size and variant chrome.

- **id:** `select`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `forms`

### Use when

- Pick one value from a moderate closed list

### Don't use when

- A short exclusive set that fits on the page (use radio-group)
- Free text with suggestions (use combobox)

### Accessibility

- Trigger is a real button; listbox opens on ArrowDown/Enter/Space
- Typeahead highlights matching items; Escape closes and restores focus

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `open` | boolean | no | — | `false` | — |
| `value` | string | no | — | — | — |
| `defaultValue` | string | no | — | — | — |
| `name` | string | no | — | — | — |
| `disabled` | boolean | no | — | `false` | — |
| `required` | boolean | no | — | `false` | — |
| `form` | string | no | — | — | Associated form id |
| `type` | enum(single) | no | — | `"single"` | — |
| `items` | array | no | — | — | Optional value/label catalog when items are not registered by Select.Item |
| `sideOffset` | number | no | — | `4` | — |
| `positioning` | boolean | no | — | `true` | — |
| `size` | enum(sm | md | lg) | no | — | `"md"` | — |
| `variant` | enum(outline | soft) | no | — | `"outline"` | — |
| `onOpenChange` | event | no | — | — | — |
| `onValueChange` | event | no | — | — | — |
| `children` | slot | no | — | — | — |

### Examples

#### Outline select (`outline`)

```json
{
  "size": "md",
  "variant": "outline",
  "defaultValue": ""
}
```

### Related

- [`select-trigger`](components/select-trigger.md)
- [`select-value`](components/select-value.md)
- [`select-content`](components/select-content.md)
- [`select-item`](components/select-item.md)
- [`radio-group`](components/radio-group.md)
- [`field`](components/field.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Select.Content

> The positioned listbox surface for Select items.

- **id:** `select-content`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `forms`

### Use when

- Wrap Select items and groups

### Don't use when

- A free-floating popover (use popover)

### Accessibility

- role=listbox; focus stays in the trigger while the list is open.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | enum(sm | md | lg) | no | — | `"md"` | — |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | — |

### Examples

#### Medium content (`md`)

```json
{
  "size": "md"
}
```

### Related

- [`select`](components/select.md)
- [`select-item`](components/select-item.md)
- [`select-viewport`](components/select-viewport.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Select.Group

> Groups related Select items under an optional label.

- **id:** `select-group`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `forms`

### Use when

- Cluster related options inside a long Select

### Don't use when

- A single flat list of options

### Accessibility

- role=group; pair with Select.Label for an accessible name.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | — |

### Examples

#### Group (`group`)

```json
{}
```

### Related

- [`select-label`](components/select-label.md)
- [`select-item`](components/select-item.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Select.Item

> One selectable option inside Select.Content.

- **id:** `select-item`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `forms`

### Use when

- Declare a Select option with value and label

### Don't use when

- A radio option outside Select (use radio)

### Accessibility

- role=option; disabled items are skipped by keyboard.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `value` | string | yes | — | — | — |
| `label` | string | no | — | — | Accessible and display label when children omitted |
| `disabled` | boolean | no | — | `false` | — |
| `icon` | slot | no | — | — | — |
| `description` | string | no | — | — | — |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | — |

### Examples

#### Option (`option`)

```json
{
  "value": "pro",
  "label": "Pro",
  "description": "For growing teams"
}
```

### Related

- [`select`](components/select.md)
- [`select-content`](components/select-content.md)
- [`select-group`](components/select-group.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Select.Label

> A non-interactive heading inside a Select group.

- **id:** `select-label`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `forms`

### Use when

- Name a Select.Group

### Don't use when

- A selectable option (use select-item)

### Accessibility

- Not focusable; provides visible structure only.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | — |

### Examples

#### Group label (`label`)

```json
{}
```

### Related

- [`select-group`](components/select-group.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Select.Portal

> Portals Select.Content out of overflow-clipped ancestors.

- **id:** `select-portal`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `forms`

### Use when

- Select must escape a scroll or overflow container

### Don't use when

- Inline content that fits in-flow

### Accessibility

- Does not change roles; children keep listbox semantics.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `children` | slot | no | — | — | — |

### Examples

#### Portal (`portal`)

```json
{}
```

### Related

- [`select-content`](components/select-content.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Select.Separator

> A visual divider between Select groups or items.

- **id:** `select-separator`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `forms`

### Use when

- Separate option clusters inside Select

### Don't use when

- Page-level section breaks

### Accessibility

- Decorative separator; not in the tab order.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `class` | string | no | — | — | — |

### Examples

#### Divider (`divider`)

```json
{}
```

### Related

- [`select-group`](components/select-group.md)
- [`select-content`](components/select-content.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Select.Trigger

> The button that opens a Select listbox.

- **id:** `select-trigger`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `forms`

### Use when

- Compose a Select with custom trigger content

### Don't use when

- A standalone button outside Select

### Accessibility

- aria-haspopup=listbox and aria-expanded reflect open state.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | enum(sm | md | lg) | no | — | `"md"` | — |
| `variant` | enum(outline | soft) | no | — | `"outline"` | — |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | — |

### Examples

#### Default trigger (`default`)

```json
{
  "size": "md",
  "variant": "outline"
}
```

### Related

- [`select`](components/select.md)
- [`select-value`](components/select-value.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Select.Value

> Shows the selected label or a placeholder inside the trigger.

- **id:** `select-value`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `forms`

### Use when

- Display the current Select value

### Don't use when

- Static text outside Select

### Accessibility

- Placeholder is visible text inside the trigger name.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `placeholder` | string | no | — | `"Select…"` | — |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | — |

### Examples

#### Placeholder (`placeholder`)

```json
{
  "placeholder": "Choose a plan"
}
```

### Related

- [`select`](components/select.md)
- [`select-trigger`](components/select-trigger.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Select.Viewport

> Scrollable viewport inside Select.Content.

- **id:** `select-viewport`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `forms`

### Use when

- Long option lists that need an internal scroll region

### Don't use when

- Short lists that fit without scrolling

### Accessibility

- Keeps option focus management inside the listbox.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | — |

### Examples

#### Viewport (`viewport`)

```json
{}
```

### Related

- [`select-content`](components/select-content.md)
- [`select-item`](components/select-item.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Separator

> A horizontal or vertical divider on the token scale.

- **id:** `separator`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `display`

### Use when

- Split two blocks of content visually

### Don't use when

- A menu divider (use the menu separator)
- A list item (use list-item)

### Accessibility

- Decorative by default (hidden from assistive technology); set decorative false for a semantic boundary.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `orientation` | enum(horizontal | vertical) | no | — | `"horizontal"` | — |
| `decorative` | boolean | no | — | `true` | — |
| `variant` | enum(default | subtle | strong) | no | — | `"default"` | — |
| `class` | string | no | — | — | — |

### Examples

#### Horizontal rule (`rule`)

```json
{
  "variant": "subtle"
}
```

### Related

- [`box`](components/box.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Sheet

> Edge-anchored modal panel (drawer-like sheet).

- **id:** `sheet`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `overlays`

### Use when

- Mobile filters, detail rails, edge panels

### Don't use when

- Centered modal forms (use dialog)

### Accessibility

- Focus trapped while open; Escape dismisses.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | enum(sm | md | lg | xl) | no | — | `"md"` | — |
| `side` | enum(top | right | bottom | left | start | end | center) | no | — | `"start"` | — |
| `modal` | boolean | no | — | `true` | false: a non-modal panel (no focus trap, inert or scroll lock) |
| `dismissOutside` | boolean | no | — | `false` | Non-modal only: close on a press or focus outside (never on the trigger) |
| `closeOnEscape` | boolean | no | — | `false` | Non-modal only: close on Escape anywhere, not just from inside |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | — |

### Examples

#### Start edge (`start`)

```json
{
  "side": "start",
  "size": "md"
}
```

### Related

- [`drawer`](components/drawer.md)
- [`dialog`](components/dialog.md)
- [`sidebar`](components/sidebar.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Sidebar

> Collapsible app rail with sections, badges and safe links.

- **id:** `sidebar`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `overlays`

### Use when

- Primary app navigation rail

### Don't use when

- Marketing site nav (use navigation-menu)

### Accessibility

- nav landmark; collapsed items keep accessible names via tooltips.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `items` | array | no | — | — | — |
| `sections` | array | no | — | — | — |
| `collapsed` | boolean | no | — | `false` | — |
| `collapsible` | boolean | no | — | `true` | — |
| `drawer` | boolean | no | — | `false` | — |
| `variant` | enum(default | inset) | no | — | `"default"` | — |
| `header` | slot | no | — | — | — |
| `footer` | slot | no | — | — | — |
| `itemIcon` | slot | no | — | — | — |
| `label` | string | no | — | `"Main"` | — |
| `collapseLabel` | string | no | — | — | — |
| `expandLabel` | string | no | — | — | — |
| `hrefTrust` | enum(developer | untrusted) | no | developer | `"developer"` | — |
| `class` | string | no | — | — | — |

### Examples

#### Workspace rail (`workspace`)

```json
{
  "label": "Main",
  "sections": [
    {
      "label": "Workspace",
      "items": [
        {
          "label": "Inbox",
          "href": "https://example.com/inbox",
          "active": true
        }
      ]
    }
  ]
}
```

### Related

- [`app-nav`](components/app-nav.md)
- [`navigation-menu`](components/navigation-menu.md)
- [`sheet`](components/sheet.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Skeleton

> A placeholder bar or circle while content loads.

- **id:** `skeleton`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `display`

### Use when

- Reserve space for text or an avatar that has not arrived yet

### Don't use when

- A determinate load (use progress)
- A live status (use spinner)

### Accessibility

- Decorative (aria-hidden); pair it with a live status elsewhere if the wait matters.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `size` | enum(sm | md | lg) | no | — | `"md"` | — |
| `circle` | boolean | no | — | `false` | — |
| `class` | string | no | — | — | — |

### Examples

#### Text line (`line`)

```json
{
  "size": "md"
}
```

#### Avatar placeholder (`face`)

```json
{
  "size": "md",
  "circle": true
}
```

### Related

- [`spinner`](components/spinner.md)
- [`progress`](components/progress.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Sortable list

> A list whose items are a bound list variable; people reorder it by drag or keyboard, and lists sharing a group exchange items.

- **id:** `sortable-list`
- **package:** `@texuli/player`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `state`

### Use when

- Let people rank, reorder or move items between lists (priorities, backlog columns)
- Drag as data: the order is the list variable, so other nodes read it

### Don't use when

- A read-only list: use blocks-structure
- Cards between board columns with work-in-progress limits: use data-board

### Accessibility

- A labelled list of items, each with a drag handle button; Space or Enter picks up, arrows move, Space or Enter drops, Escape cancels
- Every move has a non-drag path (keyboard) and is announced politely; reduced motion disables the move animation

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `label` | string | yes | untrusted | — | Accessible name. |
| `reorder` | object | yes | — | — | Drag as data: bind (a $state list), axis, group, accepts, locked, pull and disabled. |
| `itemLabel` | string | no | — | `"label"` | The item field shown as each item’s text. |
| `itemDetail` | string | no | — | — | An item field shown as secondary text. |

### Examples

#### Priorities (`priorities`)

```json
{
  "label": "This week",
  "reorder": {
    "bind": {
      "$state": "priorities"
    },
    "axis": "vertical"
  }
}
```

### Related

- [`data-board`](components/data-board.md)
- [`blocks-structure`](components/blocks-structure.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Spinner

> An indeterminate wait indicator, labelled or decorative.

- **id:** `spinner`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `display`

### Use when

- Show that a short action is in progress

### Don't use when

- A known percent (use progress)
- A layout placeholder (use skeleton)

### Accessibility

- With a label it is a live status; without a label it is decorative.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `label` | string | no | — | — | — |
| `size` | enum(sm | md | lg) | no | — | `"md"` | — |
| `tone` | enum(primary | success | warning | destructive | info | neutral) | no | — | `"primary"` | — |
| `class` | string | no | — | — | — |

### Examples

#### Saving (`saving`)

```json
{
  "label": "Saving",
  "size": "sm"
}
```

### Related

- [`progress`](components/progress.md)
- [`skeleton`](components/skeleton.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# SplitView

> Master-detail split with list and detail panes.

- **id:** `split-view`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `layouts`

### Use when

- List/detail workflows on wide screens

### Don't use when

- Single-stream feeds

### Accessibility

- List and detail regions are labelled
- Narrow containers show one pane at a time

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `list` | slot | yes | — | — | — |
| `detail` | slot | no | — | — | — |
| `empty` | slot | no | — | — | — |
| `listLabel` | string | no | — | `"List"` | — |
| `detailLabel` | string | no | — | `"Details"` | — |
| `detailActive` | boolean | no | — | `false` | — |
| `class` | string | no | — | — | — |

### Examples

#### Split (`basic`)

```json
{
  "listLabel": "Inbox"
}
```

### Related

- [`layout-dual-sidebar`](components/layout-dual-sidebar.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Spreadsheet

> A spreadsheet as data: tabs of cells holding numbers, text, booleans and formulas that recalculate.

- **id:** `spreadsheet`
- **package:** `@texuli/sheets`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `sheets`

### Use when

- A budget, an estimate, a price list or a tracker whose totals people keep editing
- Numbers that depend on other numbers through formulas (SUM, IF, VLOOKUP, DATE…)

### Don't use when

- Read-only records with typed columns, sorting and search: use data-grid
- A chart of values: use a chart family
- A form people fill in once: use schema-form

### Accessibility

- Painted as an APG grid with column letters, row numbers and one tab stop
- Values are text, never HTML; formulas are a closed language with no references built from text and no network
- A formula error shows its code in the cell (#DIV/0!, #REF!, #CYCLE!…)

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `sheet` | object | yes | — | — | A Texuli sheet: { format: "texuli-sheet", formatVersion: 1, meta: { title }, sheets: [{ id, name, rows, columns, cells }] }. cells maps A1 addresses ("B3") to a number, a boolean, text, or a formula that starts with "=" ("=SUM(B1:B2)", "=IF(C2>100, \"high\", \"low\")", "=Rates!A1*B2"). About 50 functions: SUM, AVERAGE, MIN, MAX, COUNT, COUNTA, ROUND, SUMIF, COUNTIF, IF, IFS, AND, OR, IFERROR, CONCAT, LEFT, TEXT, INDEX, MATCH, VLOOKUP, XLOOKUP, DATE, TODAY and more. No INDIRECT, OFFSET or RAND. Dates are "YYYY-MM-DD" text. Text that must start with "=" is written "'=…". At most 16 sheets, 10,000 rows, 256 columns and 100,000 cells. |
| `label` | string | no | untrusted | — | Accessible name; defaults to the sheet title. |

### Examples

#### Team offsite budget (`budget`)

```json
{
  "sheet": {
    "format": "texuli-sheet",
    "formatVersion": 1,
    "meta": {
      "title": "Team offsite budget"
    },
    "sheets": [
      {
        "id": "costs",
        "name": "Costs",
        "rows": 8,
        "columns": 4,
        "cells": {
          "A1": "Item",
          "B1": "Unit cost",
          "C1": "Quantity",
          "D1": "Total",
          "A2": "Venue",
          "B2": 1200,
          "C2": 1,
          "D2": "=B2*C2",
          "A3": "Lunch",
          "B3": 18.5,
          "C3": 24,
          "D3": "=B3*C3",
          "A4": "Coffee",
          "B4": 3.25,
          "C4": 48,
          "D4": "=B4*C4",
          "A6": "Total",
          "D6": "=SUM(D2:D4)",
          "A7": "Over budget?",
          "D7": "=IF(D6>2000, \"yes\", \"no\")"
        }
      }
    ]
  }
}
```

### Related

- [`data-grid`](components/data-grid.md)
- [`document`](components/document.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Stat

> A single metric with optional delta, trend and sparkline slot.

- **id:** `stat`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `display`

### Use when

- Show one KPI with a human-formatted value

### Don't use when

- A currency/percent KPI with previous period math (use kpi)

### Accessibility

- Label and value are text; trend has a spoken word, not color alone.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `label` | string | yes | — | — | — |
| `value` | string | yes | — | — | The formatted value as display text, such as "$12.4k" or "98%". |
| `delta` | string | no | — | — | The formatted change as display text, such as "+4%". |
| `trend` | enum(up | down | neutral) | no | — | — | — |
| `positive` | enum(up | down) | no | — | `"up"` | Which direction is good |
| `hint` | string | no | — | — | — |
| `icon` | slot | no | — | — | — |
| `sparkline` | slot | no | — | — | — |
| `variant` | enum(elevated | flat) | no | — | `"elevated"` | — |
| `class` | string | no | — | — | — |

### Examples

#### Revenue up (`revenue`)

```json
{
  "label": "Revenue",
  "value": "$12.4k",
  "delta": "+8%",
  "trend": "up"
}
```

### Related

- [`kpi`](components/kpi.md)
- [`card`](components/card.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Stepper

> Horizontal or vertical progress through ordered steps.

- **id:** `stepper`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `display`

### Use when

- Show multi-step onboarding or checkout progress

### Don't use when

- A chronological event log (use timeline)

### Accessibility

- nav with an accessible name; current step is announced; completed steps may be activatable.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `steps` | array | yes | — | — | Array of { id, label, description? } |
| `current` | number | yes | — | — | 0-based active index |
| `completed` | array | no | — | — | Ids of completed steps |
| `orientation` | enum(horizontal | vertical) | no | — | `"horizontal"` | — |
| `onStepClick` | event | no | — | — | — |
| `label` | string | no | — | `"Progress"` | — |
| `class` | string | no | — | — | — |

### Examples

#### Checkout steps (`checkout`)

```json
{
  "current": 1,
  "orientation": "horizontal",
  "steps": [
    {
      "id": "cart",
      "label": "Cart"
    },
    {
      "id": "ship",
      "label": "Shipping"
    },
    {
      "id": "pay",
      "label": "Payment"
    }
  ]
}
```

### Related

- [`timeline`](components/timeline.md)
- [`layout-wizard`](components/layout-wizard.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Switch

> An immediate on/off setting control.

- **id:** `switch`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `forms`

### Use when

- Settings that take effect immediately

### Don't use when

- A form agreement that must be submitted (use checkbox)

### Accessibility

- role=switch with aria-checked; label wires the accessible name.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `checked` | boolean | no | — | `false` | — |
| `defaultChecked` | boolean | no | — | `false` | — |
| `name` | string | no | — | — | — |
| `value` | string | no | — | `"on"` | — |
| `disabled` | boolean | no | — | `false` | — |
| `required` | boolean | no | — | `false` | — |
| `id` | string | no | — | — | — |
| `label` | string | no | — | — | — |
| `description` | string | no | — | — | — |
| `size` | enum(sm | md) | no | — | `"md"` | — |
| `onCheckedChange` | event | no | — | — | — |
| `class` | string | no | — | — | — |

### Examples

#### Labeled switch (`labeled`)

```json
{
  "label": "Dark mode",
  "checked": true
}
```

### Related

- [`checkbox`](components/checkbox.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Table

> A responsive data table with density, stacking and sticky header options.

- **id:** `table`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `display`

### Use when

- Tabular comparison of many rows and columns

### Don't use when

- A single metric (use stat or kpi)
- A free-form card layout

### Accessibility

- Real table markup with caption or label for the scroll region
- Stacked mode keeps labels associated with cells
- busy sets aria-busy on the table

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `variant` | enum(plain | striped | grid) | no | — | `"plain"` | — |
| `density` | enum(compact | default | comfortable) | no | — | `"default"` | — |
| `stack` | enum(never | sm | md) | no | — | `"never"` | Stack rows into labelled cards when the container is narrow |
| `stickyHeader` | boolean | no | — | `false` | — |
| `maxBlockSize` | string | no | — | — | CSS length capping height so the body scrolls |
| `label` | string | no | — | — | Accessible name for the scroll area |
| `busy` | boolean | no | — | `false` | — |
| `wrapperClass` | string | no | — | — | — |
| `class` | string | no | — | — | — |

### Examples

#### Striped sticky header (`striped-sticky`)

```json
{
  "variant": "striped",
  "stickyHeader": true,
  "stack": "sm",
  "label": "Orders"
}
```

### Related

- [`stat`](components/stat.md)
- [`empty-state`](components/empty-state.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Tabs

> A tab list that shows one panel at a time.

- **id:** `tabs`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `display`

### Use when

- Switch between peer views of the same page

### Don't use when

- A sequence of steps (use stepper or wizard)
- Mobile app destinations (use bottom-nav)

### Accessibility

- Tab list is labelled; arrow keys move among tabs; the selected tab is aria-selected
- Each tab names its panel

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `items` | array | yes | — | — | Tabs: value, label, optional badge and panel |
| `value` | string | no | — | — | The selected tab value |
| `onValueChange` | event | no | — | — | Selected tab changed |
| `label` | string | no | — | — | Accessible name of the tab list |
| `variant` | enum(line | pills | enclosed) | no | — | `"line"` | — |
| `orientation` | enum(horizontal | vertical) | no | — | `"horizontal"` | — |
| `activationMode` | enum(automatic | manual) | no | — | `"automatic"` | — |
| `loop` | boolean | no | — | `false` | — |
| `disabled` | boolean | no | — | `false` | — |
| `class` | string | no | — | — | — |
| `content` | slot | no | — | — | Panel body for each item |

### Examples

#### Line tabs (`line`)

```json
{
  "variant": "line",
  "items": [
    {
      "value": "overview",
      "label": "Overview"
    },
    {
      "value": "activity",
      "label": "Activity"
    }
  ],
  "value": "overview"
}
```

### Related

- [`accordion`](components/accordion.md)
- [`stepper`](components/stepper.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Tag

> A labeled chip that can be removed.

- **id:** `tag`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `display`

### Use when

- Show a selected filter or category the user can remove

### Don't use when

- Static status (use badge)
- A pressed filter control (use chip)

### Accessibility

- Remove control has an accessible name; pending remove is disabled.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `label` | string | yes | — | — | Visible label |
| `variant` | enum(default | secondary | outline | success | warning | destructive | info | neutral) | no | — | `"secondary"` | — |
| `color` | enum(none | chart-1 | chart-2 | chart-3 | chart-4 | chart-5 | chart-6 | chart-7 | chart-8) | no | — | `"none"` | — |
| `removeLabel` | string | no | — | `"Remove"` | — |
| `onRemove` | event | no | — | — | Called when remove is activated |
| `disabled` | boolean | no | — | `false` | — |
| `class` | string | no | — | — | — |

### Examples

#### Removable tag (`removable`)

```json
{
  "label": "Logistics",
  "variant": "info"
}
```

### Related

- [`badge`](components/badge.md)
- [`chip`](components/chip.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# TagsInput

> A list of tags the person types, pastes or removes.

- **id:** `tags-input`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `forms`

### Use when

- A short list of labels or keywords

### Don't use when

- A single choice from a closed list (use select or combobox)

### Accessibility

- A labelled group; the text input is named. Remove buttons are named.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `value` | array | no | — | — | The tags (bind:value) |
| `delimiter` | string | no | — | `","` | — |
| `max` | number | no | — | — | — |
| `disabled` | boolean | no | — | `false` | — |
| `readonly` | boolean | no | — | `false` | — |
| `required` | boolean | no | — | `false` | — |
| `name` | string | no | — | — | — |
| `label` | string | no | — | — | — |
| `placeholder` | string | no | — | — | — |
| `onValueChange` | event | no | — | — | — |
| `class` | string | no | — | — | — |

### Examples

#### Topics (`topics`)

```json
{
  "value": [
    "design",
    "tokens"
  ],
  "label": "Topics"
}
```

### Related

- [`field`](components/field.md)
- [`combobox`](components/combobox.md)
- [`multi-select`](components/multi-select.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Text

> Body copy, labels and small print with a size, tone and weight from the design system.

- **id:** `text`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `display`

### Use when

- Body text, helper text, captions, muted or small print
- Text with a status ink (success, warning, destructive, info) next to a word that says it

### Don't use when

- A title or section heading (use heading)
- Long-form content (use prose)

### Accessibility

- Never renders a heading element: as is p, span, div, label, small or strong.
- A tone never carries meaning alone; the words say it.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `as` | enum(p | span | div | label | small | strong) | no | — | `"p"` | — |
| `size` | enum(figure | lg | md | sm | xs | inherit) | no | — | `"md"` | figure is a large number outside stat (the title size of the type scale); inherit takes the parent's size and line height |
| `tone` | enum(default | muted | subtle | primary | success | warning | destructive | info | inherit) | no | — | `"default"` | — |
| `weight` | enum(regular | medium | semibold) | no | — | `"regular"` | — |
| `truncate` | boolean | no | — | `false` | One line with an ellipsis |
| `lineClamp` | number | no | — | — | Clamp to 1 to 10 lines with an ellipsis |
| `align` | enum(start | center | end) | no | — | `"start"` | — |
| `mono` | boolean | no | — | `false` | The design system's code family |
| `tabular` | boolean | no | — | `false` | Tabular figures (font-variant-numeric: tabular-nums) for numbers that line up |
| `transform` | enum(none | uppercase | lowercase | capitalize) | no | — | `"none"` | — |
| `tracking` | enum(normal | wide) | no | — | `"normal"` | Letter spacing; wide is the eyebrow tracking (--tx-letter-spacing-wide) |
| `italic` | boolean | no | — | `false` | — |
| `strikethrough` | boolean | no | — | `false` | Line-through |
| `for` | string | no | — | — | With as="label": the id of the labelled control |
| `label` | string | no | — | — | Plain text, escaped; replaces children when both are given |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | The text |

### Examples

#### Muted helper text (`muted`)

```json
{
  "size": "sm",
  "tone": "muted",
  "label": "Updated an hour ago"
}
```

#### Small print (`caption`)

```json
{
  "as": "small",
  "size": "xs",
  "tone": "subtle",
  "label": "Prices exclude tax."
}
```

#### Eyebrow (overline) (`eyebrow`)

```json
{
  "as": "span",
  "size": "xs",
  "tone": "muted",
  "transform": "uppercase",
  "tracking": "wide",
  "label": "Revenue"
}
```

#### Large figure (`figure`)

```json
{
  "as": "span",
  "size": "figure",
  "tabular": true,
  "label": "1,284"
}
```

#### Nested text that inherits (`inherit`)

```json
{
  "as": "span",
  "size": "inherit",
  "tone": "inherit",
  "weight": "semibold",
  "label": "Pro"
}
```

#### Struck price (`struck`)

```json
{
  "as": "span",
  "strikethrough": true,
  "tone": "muted",
  "label": "$48"
}
```

### Related

- [`heading`](components/heading.md)
- [`prose`](components/prose.md)
- [`inline-text`](components/inline-text.md)
- [`mark`](components/mark.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# TextCounter

> An input or textarea that shows remaining characters near the limit.

- **id:** `text-counter`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `forms`

### Use when

- Bounded free-text with a visible remaining count

### Don't use when

- Unbounded text without a max length

### Accessibility

- Remaining count is exposed via aria-describedby while focused near the limit.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `value` | string | no | — | — | — |
| `tag` | enum(input | textarea) | no | — | `"input"` | — |
| `type` | string | no | — | `"text"` | — |
| `id` | string | no | — | — | — |
| `name` | string | no | — | — | — |
| `label` | string | no | — | — | — |
| `placeholder` | string | no | — | — | — |
| `maxlength` | number | no | — | `256` | — |
| `showAfter` | number | no | — | `20` | Show the count once this many characters remain |
| `rows` | number | no | — | `3` | — |
| `disabled` | boolean | no | — | `false` | — |
| `readonly` | boolean | no | — | `false` | — |
| `required` | boolean | no | — | `false` | — |
| `invalid` | boolean | no | — | `false` | — |
| `autosize` | boolean | no | — | `false` | — |
| `remainingLabel` | string | no | — | `"characters left"` | — |
| `onValueChange` | event | no | — | — | — |
| `class` | string | no | — | — | — |

### Examples

#### Near limit (`near-limit`)

```json
{
  "maxlength": 80,
  "showAfter": 20,
  "label": "Summary"
}
```

### Related

- [`input`](components/input.md)
- [`textarea`](components/textarea.md)
- [`field`](components/field.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Textarea

> A multi-line text control with optional autosize.

- **id:** `textarea`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `forms`

### Use when

- Longer free-text fields (notes, comments, descriptions)

### Don't use when

- A single-line value (use input)

### Accessibility

- Pair with Field or an external label; autosize disables manual resize.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `value` | string | no | — | — | — |
| `ref` | unknown | no | — | — | — |
| `autosize` | boolean | no | — | `false` | — |
| `disabled` | boolean | no | — | `false` | — |
| `readonly` | boolean | no | — | `false` | — |
| `rows` | number | no | — | `3` | — |
| `onValueChange` | event | no | — | — | — |
| `appearance` | enum(default | plain) | no | — | `"default"` | plain drops the control chrome for inline-edit text; focus stays visible |
| `textSize` | enum(control | xs | sm | md | lg | xl | 2xl | 3xl | 4xl | display) | no | — | `"control"` | control (form-control size) or a type-scale size for inline-edit titles and bodies |
| `class` | string | no | — | — | — |

### Examples

#### Autosize textarea (`autosize`)

```json
{
  "autosize": true,
  "rows": 3
}
```

### Related

- [`input`](components/input.md)
- [`text-counter`](components/text-counter.md)
- [`field`](components/field.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# TimeField

> A labelled time of day typed or stepped by segment (hour, minute, AM/PM), with a 24-hour HH:mm value.

- **id:** `time-field`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `forms`

### Use when

- A time of day on its own, such as a reminder or an opening hour

### Don't use when

- A date, or a date and time (use the date pickers)
- A duration (use a number field)

### Accessibility

- A labelled group of native number inputs (hour, minute) and an AM/PM select; arrows step the segments
- Description and error are linked to the group; an error marks it invalid

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `label` | string | yes | — | — | Visible label and accessible name |
| `description` | string | no | — | — | Help text under the field |
| `error` | string | no | — | — | Error text; also marks the field invalid |
| `value` | string | no | — | — | The time as HH:mm (24-hour), or null when empty (bind:value) |
| `onValueChange` | event | no | — | — | — |
| `locale` | string | no | — | `"en-US"` | — |
| `hourCycle` | number | no | — | — | 12 shows AM/PM, 24 does not; default the locale cycle |
| `minuteStep` | number | no | — | `1` | Minutes the arrow keys move on the minute segment |
| `disabled` | boolean | no | — | `false` | — |
| `required` | boolean | no | — | `false` | — |
| `name` | string | no | — | — | Form field name: submits the value |
| `size` | enum(sm | md) | no | — | `"md"` | — |
| `labels` | object | no | — | — | Segment names (hour, minute, dayPeriod) for translation |
| `class` | string | no | — | — | — |

### Examples

#### Reminder time (`reminder`)

```json
{
  "label": "Reminder",
  "value": "09:30",
  "minuteStep": 15,
  "name": "reminder"
}
```

### Related

- [`field`](components/field.md)
- [`input`](components/input.md)
- [`form`](components/form.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Timeline

> Vertical or horizontal chronological list of events.

- **id:** `timeline`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `display`

### Use when

- Show a sequence of events with status

### Don't use when

- A Gantt schedule with dependencies (use @texuli/data/timeline)

### Accessibility

- Ordered list with an accessible name
- Status has a spoken word and marker shape, not color alone
- Item links pass the URL policy

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `items` | array | no | — | — | Data-driven items (or compose TimelineItem children) |
| `orientation` | enum(vertical | horizontal) | no | — | `"vertical"` | — |
| `label` | string | no | — | — | — |
| `messages` | object | no | — | — | Localized label/status words |
| `hrefTrust` | enum(developer | untrusted) | no | — | `"developer"` | — |
| `item` | slot | no | — | — | Extra content under each data item |
| `class` | string | no | — | — | — |

### Examples

#### Shipment timeline (`shipment`)

```json
{
  "orientation": "vertical",
  "items": [
    {
      "id": "1",
      "title": "Packed",
      "time": "Mon",
      "status": "complete"
    },
    {
      "id": "2",
      "title": "In transit",
      "time": "Tue",
      "status": "current"
    },
    {
      "id": "3",
      "title": "Delivered",
      "time": "Wed",
      "status": "upcoming"
    }
  ]
}
```

### Related

- [`stepper`](components/stepper.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Toaster

> Live region that renders toast notifications from the shared store.

- **id:** `toaster`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `overlays`

### Use when

- Transient success/error feedback after an action

### Don't use when

- Blocking errors that need a decision (use alert-dialog)

### Accessibility

- role=region with polite live updates; dismiss controls are labelled.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `label` | string | no | — | `"Notifications"` | — |
| `position` | enum(top-start | top-center | top-end | bottom-start | bottom-center | bottom-end) | no | — | `"bottom-end"` | Block edge and logical inline position; narrow screens center the stack |
| `offset` | string | no | — | — | CSS length or px number from the stack edge |
| `store` | unknown | no | — | — | Optional ToastStore inject (tests) |
| `dismissLabel` | string | no | — | `"Dismiss notification"` | — |
| `class` | string | no | — | — | — |

### Examples

#### Toaster region (`region`)

```json
{
  "label": "Notifications"
}
```

### Related

- [`alert-dialog`](components/alert-dialog.md)
- [`banner`](components/banner.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# ToggleGroup

> A group of toggle buttons: one value, or several.

- **id:** `toggle-group`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `forms`

### Use when

- A small closed set of filters or views the person toggles

### Don't use when

- A single on/off (use switch or toggle)
- A long list of options (use checkbox)

### Accessibility

- A labelled toolbar of toggle buttons; arrows move, Space presses.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `type` | enum(single | multiple) | no | — | `"single"` | — |
| `value` | string | no | — | — | Pressed value, or an array when type is multiple |
| `disabled` | boolean | no | — | `false` | — |
| `orientation` | enum(horizontal | vertical) | no | — | `"horizontal"` | — |
| `variant` | enum(default | outline) | no | — | `"default"` | — |
| `size` | enum(sm | md | lg) | no | — | `"md"` | — |
| `name` | string | no | — | — | — |
| `onValueChange` | event | no | — | — | — |
| `class` | string | no | — | — | — |
| `children` | slot | no | — | — | — |

### Examples

#### Alignment (`align`)

```json
{
  "type": "single",
  "value": "start"
}
```

### Related

- [`button-group`](components/button-group.md)
- [`radio-group`](components/radio-group.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Tooltip

> Short delayed hint on hover or focus.

- **id:** `tooltip`
- **package:** `texuli`
- **tier:** `app`
- **agent emittable:** no
- **emit:** 
- **group:** `overlays`

### Use when

- Icon-only controls need a name
- Optional keyboard shortcut hints

### Don't use when

- Essential instructions (put them in visible copy)

### Accessibility

- Shows on focus; content is plain text or a snippet, never a sink.

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `content` | string | yes | — | — | Hint text or rich snippet |
| `children` | slot | yes | — | — | Trigger snippet { props } |
| `shortcut` | string | no | — | — | Shortcut string or list shown as Kbd |
| `side` | enum(top | right | bottom | left) | no | — | `"top"` | — |
| `align` | enum(start | center | end) | no | — | `"center"` | — |
| `sideOffset` | number | no | — | `6` | — |
| `delayDuration` | number | no | — | `300` | — |
| `disabled` | boolean | no | — | `false` | — |
| `open` | boolean | no | — | `false` | — |
| `class` | string | no | — | — | — |

### Examples

#### Basic tooltip (`basic`)

```json
{
  "content": "Save note",
  "side": "top"
}
```

### Related

- [`popover`](components/popover.md)
- [`hover-card`](components/hover-card.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---

# Workflow graph

> A workflow of typed nodes and edges (automations, pipelines, approvals, state diagrams), read-only or editable.

- **id:** `workflow-graph`
- **package:** `@texuli/workflows`
- **tier:** `content`
- **agent emittable:** yes
- **emit:** developer, untrusted
- **group:** `workflows`

### Use when

- Show how a process flows from step to step
- Let people build or change a workflow, bound to a workflow state variable

### Don't use when

- A static diagram in a document: use blocks-diagram
- Quantities flowing between stages: use charts-sankey

### Accessibility

- View mode: a figure whose nodes are a list that says where each one leads
- Edit mode: focusable nodes with spatial arrow keys, keyboard connect mode on ports, and a treegrid outline that edits without the canvas
- Labels are text; links and images pass the untrusted URL policy

### Props

| Name | Kind | Required | Trust | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `label` | string | yes | untrusted | — | Accessible name. |
| `graph` | object | yes | — | — | A spec WorkflowGraph (version 1): nodeTypes, nodes, edges, groups, cycles. |
| `mode` | enum(view | edit) | no | — | `"view"` | — |
| `flow` | enum(LR | TB) | no | — | `"LR"` | — |

### Examples

#### Expense approval (`approval`)

```json
{
  "label": "Expense approval",
  "mode": "view",
  "graph": {
    "version": 1,
    "cycles": "forbid",
    "nodeTypes": [
      {
        "id": "step",
        "label": "Step",
        "ports": [
          {
            "id": "in",
            "direction": "in"
          },
          {
            "id": "out",
            "direction": "out",
            "multiple": true
          }
        ]
      }
    ],
    "nodes": [
      {
        "id": "ask",
        "type": "step",
        "label": "Request",
        "position": {
          "x": 0,
          "y": 0
        }
      },
      {
        "id": "review",
        "type": "step",
        "label": "Review",
        "position": {
          "x": 260,
          "y": 0
        }
      },
      {
        "id": "paid",
        "type": "step",
        "label": "Paid",
        "position": {
          "x": 520,
          "y": 0
        }
      }
    ],
    "edges": [
      {
        "id": "e1",
        "from": {
          "node": "ask",
          "port": "out"
        },
        "to": {
          "node": "review",
          "port": "in"
        }
      },
      {
        "id": "e2",
        "from": {
          "node": "review",
          "port": "out"
        },
        "to": {
          "node": "paid",
          "port": "in"
        }
      }
    ]
  }
}
```

### Related

- [`blocks-diagram`](components/blocks-diagram.md)
- [`charts-sankey`](components/charts-sankey.md)

---

_Generated from the Texuli catalog manifest. Do not hand-edit; regenerate with `@texuli/tools/llms`._

---