# DreamLake — Full documentation

> DreamLake uikit is the React component library and design contract — surfaces, ink, semantic color, type, geometry, and the zebra-list patterns shared by every DreamLake page.

Generated from https://uikit.dreamlake.ai. 55 pages.

---

Source: https://uikit.dreamlake.ai

# DreamLake UIkit

Single source of truth for surfaces, ink, semantic color, type, geometry, and the
zebra-list patterns shared by every DreamLake page — `ml-dash`, `dreamlake`,
`dreamlake-pipelines`, `dreamlake-profile`, `dreamlake-timetravel`, `notebook`.

These docs are the design contract: tokens that paint surfaces, six hues that color
domain concepts, two typefaces that split identity from narrative, a fixed spacing
and radius scale, layered shadows and z-index, and the zebra-list pattern every
DreamLake list page reuses.

## Install

```bash file="terminal"
npm install @dreamlake/uikit
# or
pnpm add @dreamlake/uikit
```

## Style guide

The complete contract on one page: [Style guide](/style-guide.md). Eight sections —
Color, Typography, Spacing & layout, Iconography, Elevation & depth, Border &
radius, Motion, and the Zebra-list four-band model — sourced from the same
`staging/dreamlake-design-guide.html` and `staging/design.md` references.

## Components

- [Button](/components/button.md) — primary + ghost variants, four states.

The full atom catalog (Chip, Avatar, Status, Kbd, Dropdown, Panel, etc.) lives in the
eventual `@dreamlake/uikit` npm package — not duplicated here.

> **Note:** Every section in the style guide cites its design-guide reference
>   (`staging/dreamlake-design-guide.html`) and any cross-referenced reasoning
>   (`staging/design.md`, `staging/zebra-list-style-guide.md`). What you see is what
>   `@dreamlake/uikit` ships.

---

Source: https://uikit.dreamlake.ai/components/avatar

# Avatar

A square avatar. Pass `image` to show a photo; without it (or if the image fails
to load) the component shows initials taken from `name` (`"Ge Yang"` → `"GY"`,
`"MIT CSAIL"` → `"MC"`), so callers pass the display name rather than
precomputing initials. Color, font, and surface follow the design tokens and
flip with the theme.

## Sizes

Five sizes showing how the initials scale up and down with the avatar.

## Custom radius

Pass `radius` (px) to override the simple form's default `3` (rounded square).
Use `size / 2` for a perfect circle.

## Image

Pass `image` to render a photo, cropped to fill the avatar and clipped to its
radius. If the URL is missing or fails to load, the avatar falls back to
initials — so `name` is always required as the fallback.

## Composed form

You can also compose `` and `` as children. The
image is hidden until it loads; if it's missing or errors, the fallback
(usually initials) shows instead. This form defaults to a circle — pass
`radius` to change it.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` | — | Display name (simple form). Initials are derived automatically; used as the fallback when `image` is absent or fails to load. Optional when using the composed form. |
| `image` | `string` | — | Avatar image URL. Cropped to fill the avatar; falls back to initials on missing/error. |
| `size` | `number` | `32` / `24` | Avatar size in px. Defaults to `32` for the simple form and `24` for the composed form. The initials scale with the size. |
| `radius` | `number` | `3` / circle | Border radius in px. The simple form defaults to `3` (rounded square); the composed form defaults to a circle. Use `size / 2` for a circle in the simple form. |
| `className` | `string` | — | Extra classes on the root `<span>`. |

### Composed sub-components

| Component | Props | Description |
| --- | --- | --- |
| `AvatarImage` | native `<img>` attributes (`src`, `alt`, …) | Image inside a composed ``. Hidden until it loads; on error the sibling `` takes over. |
| `AvatarFallback` | native `<span>` attributes | Fallback content (usually initials) shown until the image loads. |

---

Source: https://uikit.dreamlake.ai/style-guide

# Style Guide

The complete design contract: surfaces and ink, the six-hue semantic palette, the
type pairing, the spacing scale and page grid, the icon catalog, the shadow +
z-index ladder, the radius scale and hairline weight, the motion vocabulary, and
the zebra-list four-band model. Every DreamLake page reads from this contract.

---

Source: https://uikit.dreamlake.ai/components/breadcrumb-tree

# BreadcrumbTree

A breadcrumb-style picker that opens a Finder-style Miller-column panel,
anchored to the breadcrumb. The panel floats above any clipping ancestor.
Children are fetched on demand with pagination, results are reused when you
revisit a node, and the columns auto-scroll to the deepest level.

## Demo

Click the chevron to open the panel. Drill into nodes by clicking rows. Click a
breadcrumb item to navigate back (the panel closes).

## rootPath and fetchChildren

When `rootPath` is provided (e.g. `"my-project"`), the component prepends it to
every `fetchChildren` call:

| Column depth | `path` argument to `fetchChildren` |
| --- | --- |
| Root | `"my-project"` |
| After selecting "datasets" | `"my-project/datasets"` |
| After selecting "droid-2024" | `"my-project/datasets/droid-2024"` |

Without `rootPath`, the root call uses `""` (empty string) and sub-calls use
`"datasets"`, `"datasets/droid-2024"`, etc.

Results are reused when you drill into the same node twice, so revisiting a
folder does not trigger a second request.

## Pagination

Each column loads its first page on open. Scrolling to the bottom of a column
loads the next page automatically.

## Floating panel

The panel floats above the content, so it is not clipped by `overflow: hidden`,
`transform`, or sticky containers. It tracks the trigger as the page scrolls or
resizes.

> **Controlled path** — `BreadcrumbTree` is fully controlled. Row clicks call
> `onNavigate(node, newPath)`; the caller updates `path`. The panel stays open
> after a row click and closes when a breadcrumb item is clicked.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `path` | `BreadcrumbNode[]` | — | Controlled path from root to the selected node. Empty array = root. |
| `onNavigate` | `(node, newPath) => void` | — | Fires on row click (panel stays open) and breadcrumb click (panel closes). Update `path` here. |
| `fetchChildren` | `(path, page, limit) => Promise` | — | Async loader. `path` is slash-separated. Prepended with `rootPath` when set. |
| `rootPath` | `string` | — | Root prefix shown as the first breadcrumb item. |
| `renderEmpty` | `(parentNode) => ReactNode` | `"No items"` | Custom empty-state per column. Receives the parent node (`null` at root). |
| `refreshKey` | `number` | `0` | Increment to re-fetch the deepest visible column. |
| `refreshToken` | `number` | `0` | Increment to drop the whole cache after a host mutation (delete/rename). Open columns re-fetch immediately; otherwise they re-fetch fresh on next open. |
| `placeholder` | `string` | `"Select folder"` | Shown when `path` is empty and `rootPath` is unset. |
| `className` | `string` | — | Extra classes on the wrapper. |

### Types

```ts
interface BreadcrumbNode {
  id: string
  name: string
  /** When false, hides the chevron — signals no sub-children exist. */
  hasChildren?: boolean
}

interface FetchChildrenResult {
  items: BreadcrumbNode[]
  totalPages: number
}

// Per-column state, also exported for callers that inspect column status.
interface ColumnData {
  items: BreadcrumbNode[]
  page: number
  totalPages: number
  hasMore: boolean
  loading: boolean
  error: Error | null
}
```

---

Source: https://uikit.dreamlake.ai/llm-readable

# LLM-Readable Docs

These docs are built to be read by agents as easily as by people. Every page
has a markdown twin, and the whole corpus is published in the formats LLM
tooling already looks for — so you can point Claude (or any agent) at DreamLake
uikit and have it answer accurately.

## Fetch a single page

Append `.md` to any docs URL to get the raw markdown — no nav, no chrome:

```bash
curl https://uikit.dreamlake.ai/style-guide.md
```

Every page also advertises its markdown twin in the HTML head:

```html
<link rel="alternate" type="text/markdown" href="/style-guide.md" />
```

## The whole site, two ways

- **[`/llms.txt`](https://uikit.dreamlake.ai/llms.txt)** — a short, linked index
  of every page ([llmstxt.org](https://llmstxt.org) standard). The entry point
  an agent reads first to decide what to fetch.
- **[`/llms-full.txt`](https://uikit.dreamlake.ai/llms-full.txt)** — every page
  concatenated into one markdown file. Drop the entire library into a context
  window in a single request.

## Import it as a skill

The docs are also packaged as an [Agent Skill](https://uikit.dreamlake.ai/skills/dreamlake-uikit.zip)
— a `SKILL.md` plus one markdown reference file per page. Install it so your
agent loads DreamLake uikit knowledge on demand:

```bash
# Claude Code: drop it into your project (or ~/.claude) skills directory
curl -L https://uikit.dreamlake.ai/skills/dreamlake-uikit.zip -o dreamlake-uikit.zip
unzip dreamlake-uikit.zip -d .claude/skills/
```

> **Note:** **Always current.** Every surface above — the `.md` pages, both `llms` files,
> and the skill — is generated from the same source on each deploy, so none of
> them can drift from what you read on the site.

---

Source: https://uikit.dreamlake.ai/components/button

# Button

A button for primary actions and form submits. Wraps a native `<button>` (so it
accepts `type`, `onClick`, and the rest of the button attributes) and adds
variants, sizes and a loading state.

## Variants

`primary` is an inverted (ink-on-background) fill for the main action;
`secondary` is a bordered neutral button; `ghost` is transparent with a hover
tint (for low-emphasis / list actions); `danger` is for destructive actions;
`link` renders as inline underlined text with no padding.

## Sizes & states

Three sizes (`sm`, `md`, `lg`). `loading` shows a spinner and disables the
button; `disabled` greys it out and blocks clicks.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `'primary' \| 'secondary' \| 'ghost' \| 'danger' \| 'link'` | `'primary'` | Visual style. `'destructive'` is also accepted as an alias for `'danger'`. |
| `size` | `'sm' \| 'md' \| 'lg'` | `'sm'` | Padding/text scale. |
| `loading` | `boolean` | `false` | Shows a spinner and disables the button. |
| `leftIcon` | `ReactNode` | — | Icon rendered before the label. |
| `icon` | `boolean` | `false` | Square icon-button padding (for a button whose content is a single icon). |
| `value` | `boolean` | `false` | Active/selected state — renders the label and icon in the accent color. |
| `asChild` | `boolean` | `false` | Render the single child element with the button styling instead of a `<button>` (merging classes and forwarding props). |
| `disabled` | `boolean` | `false` | Disables interaction. |
| `type` | `'button' \| 'submit' \| 'reset'` | `'button'` | Native button type. |
| `className` | `string` | — | Extra classes on the button. |

Any other native `<button>` attributes (`onClick`, `aria-*`, …) are forwarded.

### `buttonVariants`

`buttonVariants(options)` returns the composed class string for a button
without rendering one. Accepts `variant`, `size`, `icon`, `value`, and
`className`, and is useful for styling a non-button element (like a link) to
match the button set.

---

Source: https://uikit.dreamlake.ai/components/dialog

# Dialog

A modal primitive: dimmed backdrop, centered panel with header / body / footer
slots, Esc and backdrop-click dismissal, and body-scroll lock while open. It
floats above the rest of the page, unaffected by any clipping ancestor.

## Basic

A simple confirm dialog with title, eyebrow, body text, and an action footer.

## Publish dataset

A real-world form: a text input for the dataset family name, a radio list of
source bindrs, and a primary publish action. Demonstrates building form fields
inside the dialog body using design tokens — uppercase mono labels, underlined
inputs, custom radio dots that fill with `var(--uikit-accent)` when picked.

## Behavior

- **Floats above the page** — the dialog appears above all other content and is
  never clipped by an overflow-hidden, transformed, or sticky ancestor.
- **Body scroll lock** — the page behind the dialog can't scroll while it's
  open; scrolling is restored on close.
- **Esc + backdrop dismissal** — both routes call the same `onClose` handler.
  Caller controls whether to honor the dismissal (e.g. confirm before closing
  if there are unsaved edits).
- **Theme-aware** — the backdrop dims the page and the panel uses the surface
  and shadow tokens, so it flips automatically in dark mode.

> **No focus trap shipped** — the panel does not steal or trap focus. If you
> need keyboard-only flow within the dialog (e.g. a multi-step form), wire up
> your own focus management on the body content.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | — | **Required.** Controlled open state. |
| `onClose` | `() => void` | — | **Required.** Fires when the user dismisses the dialog (Esc key, backdrop click, or any explicit close affordance the caller renders). Caller must flip `open` to false. |
| `title` | `ReactNode` | — | Heading rendered top-left of the panel. 17px semibold ink. |
| `eyebrow` | `string` | — | Small uppercase mono label rendered next to the title. |
| `footer` | `ReactNode` | — | Footer content. Typically a row of action buttons aligned right. |
| `width` | `number` | `480` | Panel width in px. |
| `showEscHint` | `boolean` | `true` | Show the muted "esc" hint in the header. Clicking it also calls `onClose`. |
| `dismissOnBackdropClick` | `boolean` | `true` | Dismiss when the user clicks the dimmed backdrop. |
| `dismissOnEsc` | `boolean` | `true` | Dismiss when the user presses Escape. |
| `className` | `string` | — | Extra classes on the panel element. |
| `children` | `ReactNode` | — | Body content — typically form fields, message text, or a custom layout. |

---

Source: https://uikit.dreamlake.ai/components/field

# Field

A labelled wrapper for a single form control. Renders the label (with an
optional required marker), the control (its `children` — usually a
[TextField](/components/text-field.md) or [Select](/components/select.md)), and a
hint or error line below.

## Label & hint

## Error

When `error` is set it replaces the hint and renders in the danger tone. Pair it
with the control's own `invalid` flag for the red border.

## Props

| Prop | Type | Description |
| --- | --- | --- |
| `label` | `ReactNode` | Field label (rendered above the control). |
| `hint` | `ReactNode` | Helper text shown below when there is no error. |
| `error` | `ReactNode` | Error message; replaces the hint, shown in danger tone. |
| `required` | `boolean` | Appends a danger `*` to the label. |
| `htmlFor` | `string` | Associates the label with a control `id`. |
| `className` | `string` | Extra classes on the wrapper. |
| `children` | `ReactNode` | The control to wrap. |

---

Source: https://uikit.dreamlake.ai/components/filter-bar

# FilterBar

A compact toolbar that combines filter chips, a search input, and an optional
sort dropdown. When the user starts typing with a non-`"all"` filter active,
the chip row collapses and the active filter appears as a dismissible token
inside the search field.

## Demo

Filter chips on the left slide an animated underline to the active chip. When
`query` is non-empty and a non-`"all"` filter is selected, the chips are
replaced by a token pill inside the search field. Pressing Backspace on an
empty input removes the token. Filter chips can carry a state color via
`accent` — see the `FilterOption.accent` prop below.

## Search only

Omit `filters` and `sortOptions` to render just the search input.

## Props

### FilterBarProps

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `query` | `string` | — | Current search query (controlled). |
| `onQueryChange` | `(q: string) => void` | — | Called when the user types or clears the input. |
| `filters` | `FilterOption[]` | — | Filter chips rendered on the left. First option is treated as "all". Omit to hide chips. |
| `filterValue` | `string` | — | Active filter value (controlled). |
| `onFilterChange` | `(value: string) => void` | — | Called when a chip is clicked or the token is dismissed. |
| `placeholder` | `string` | `'search'` | Placeholder text for the search input. |
| `searchRef` | `RefObject` | — | Forward ref to the underlying input element. |
| `sortOptions` | `{ value: string; label: string }[]` | — | Options for the sort dropdown. Omit to hide the dropdown. |
| `sortValue` | `string` | — | Active sort value (controlled). |
| `onSortChange` | `(value: string) => void` | — | Called when the sort selection changes. |
| `className` | `string` | — | Extra classes on the root wrapper. |

### FilterOption

| Field | Type | Description |
| --- | --- | --- |
| `value` | `string` | Unique identifier for this filter. |
| `label` | `string` | Display text shown in the chip and as the token label. |
| `count` | `number` | Item count shown as a superscript next to the label. |
| `accent` | `string` | Tint color applied when `count > 0`. Prefer palette tones — `var(--tone-green)` (running/ok), `var(--tone-red)` (failed/error). |

---

Source: https://uikit.dreamlake.ai/components/menu

# Menu

A trigger-anchored dropdown. The panel floats above any clipping ancestor and
follows the trigger as the page scrolls or resizes. The trigger is rendered via
a render-prop so it can react to the open state — typical use is a tinted
background or a rotated chevron while the menu is open.

## Minimal

A minimal action menu — three items and a destructive divider.

## Workspace switcher

A workspace switcher example: a two-line trigger (eyebrow + brand
wordmark with rotating chevron), `personal` and `organizations` sections of
account rows, three actions, and a destructive sign-out at the bottom. The
`MenuItem` `disabled` flag is wired to "Manage members" — only valid for
organizations.

The account row itself is composed by the caller (avatar + name + handle +
"current" marker) — the library doesn't ship a dedicated `MenuAccountRow`
because the row is highly app-specific and it would force a shared `Avatar`
decision before that's been made.

## Behavior

- **Floats above clipping ancestors** — the panel is not clipped by
  `overflow: hidden`, `transform`, or sticky containers, and follows the
  trigger as the page scrolls or resizes.
- **Esc + outside-click dismiss** — pressing Escape or clicking outside both the
  trigger and the panel closes the menu.
- **Controlled or uncontrolled** — pass `open` + `onOpenChange` for full
  control, or rely on `defaultOpen` and let the menu manage its own state.

> **No keyboard navigation shipped** — the menu doesn't intercept
> ↑/↓/Enter to walk through items. If you need full keyboard flow, layer it on
> top by managing `open` yourself and adding listeners to the trigger / items.

## Props

### Menu

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `trigger` | `(open: boolean) => ReactNode` | — | Render-prop for the trigger element. Receives the current open state. |
| `align` | `'left' \| 'right'` | `'left'` | Panel horizontal alignment relative to the trigger. |
| `width` | `number` | `240` | Panel min-width in px. |
| `open` | `boolean` | — | Controlled open state. Omit for uncontrolled mode. |
| `onOpenChange` | `(open: boolean) => void` | — | Fires when the menu wants to open or close. Required when controlled. |
| `defaultOpen` | `boolean` | `false` | Initial open state in uncontrolled mode. |
| `dismissOnEsc` | `boolean` | `true` | Dismiss when the user presses Escape. |
| `dismissOnOutsideClick` | `boolean` | `true` | Dismiss when the user clicks outside both the trigger and panel. |
| `className` | `string` | — | Extra classes on the panel element. |
| `children` | `ReactNode` | — | Panel content — typically `MenuSection`, `MenuItem`, `MenuDivider`. |

### MenuSection

| Prop | Type | Description |
| --- | --- | --- |
| `label` | `string` | Uppercase mono label rendered above the section's items. |
| `children` | `ReactNode` | Section content. |

### MenuItem

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` | `ReactNode` | — | Optional icon rendered before the label. |
| `label` | `ReactNode` | — | Item label. |
| `danger` | `boolean` | `false` | Use the design's semantic error color and a tinted-red hover. |
| `disabled` | `boolean` | `false` | Visually muted, non-clickable, no hover effect. |
| `onClick` | `() => void` | — | Click handler. Suppressed when disabled. |

### MenuDivider

No props. Renders a 1px `var(--faint)` separator with `4px` margin top and bottom.

---

Source: https://uikit.dreamlake.ai/components/profile-card

# ProfileCard

A bordered card for a resource row — title, optional tag, right-aligned meta,
description, and a footer stats line. Optional hover-revealed slots reveal
controls (edit/delete top-right, or fork/open bottom-right) without
displacing the layout.

Each slot has default typography baked in so callers can pass plain strings
without any style code. Override by wrapping content in a styled element.

## Basic

All five content slots: `title`, `tag`, `titleRight`, `description`, `footer`.

## Hover actions

`hoverActions` is revealed on pointer-enter and anchored to the bottom-right of
the card. Clicks on it do not bubble to `onClick`.

## Top-right actions + footer-right

`topRightActions` reveals controls in the card's top-right on hover (the
edit/delete pattern). When this slot is provided, `titleRight` auto-fades on
hover so the meta (timestamp) doesn't visually collide with the action
cluster.

`footerRight` adds a right-aligned cluster next to the footer — typically
ACL chips, member avatars, or status badges that should sit on the same row
as the left-side stats.

## Props

| Prop | Type | Description |
| --- | --- | --- |
| `title` | `ReactNode` | Primary name in the header. Default: 14px medium. |
| `tag` | `ReactNode` | Small badge immediately after the title. Default: mono 10.5px, 80% opacity. |
| `titleRight` | `ReactNode` | Right-aligned header meta — timestamp, version, etc. Default: mono 11px, 65% opacity. Auto-fades on hover when `topRightActions` is also set. |
| `description` | `ReactNode` | Optional body paragraph. Default: 13px, 75% opacity, 1.5 line-height. |
| `footer` | `ReactNode` | Optional stats/meta row at the bottom-left. Default: mono 11px, 75% opacity, truncates. |
| `footerRight` | `ReactNode` | Right-aligned cluster next to `footer` (ACL chips, badges). Shares the footer row. |
| `tags` | `ReactNode` | Final row inside the card body — a horizontal, wrapping row of `` chips (the "Pipelines tab" pattern). Pass an array of nodes or any flex-wrap-friendly subtree. |
| `topRightActions` | `ReactNode` | Controls anchored top-right, revealed on hover. Used for the edit/delete pattern. Clicks do not bubble to `onClick`. |
| `hoverActions` | `ReactNode` | Controls anchored bottom-right, revealed on hover. Clicks do not bubble to `onClick`. |
| `onClick` | `() => void` | Makes the card clickable. Adds pointer cursor. |
| `className` | `string` | Extra classes on the card root. |

---

Source: https://uikit.dreamlake.ai/components/profile-layout

# ProfileLayout

A full-page profile layout: sticky top bar with animated tabs, a fixed left
rail with personal info, and a scrollable main column. The top bar gains
frosted-glass styling and reveals the tab strip on scroll.

## Layout zones

```
┌──────────────────────────────────────────────────────────────┐
│ [logo]         [tabs — revealed on scroll]       [actions]   │  sticky top bar
├─────────────┬────────────────────────────────────────────────┤
│             │ [TabStrip]              [cols toggle]          │  sticky
│  HeroRail   ├────────────────────────────────────────────────┤
│  sticky     │                                                │
│             │  active tab content                            │
│             │                                                │
└─────────────┴────────────────────────────────────────────────┘
```

The HeroRail and TabStrip both stick just below the top bar. Once the page
scrolls far enough, the TabStrip hides and the top bar reveals its own tab strip
with a slide-in animation.

## Demo

Scroll inside the preview to see the sticky topbar and tab-reveal animation.
Toggle to dark mode to see the frosted-glass topbar.

## Avatar image

By default the HeroRail renders a monogram derived from `profile.name`. Pass
`profile.image` to render an actual image instead — `1:1 aspect-ratio` with
`object-cover`, falling back to the monogram if the URL is omitted:

```tsx
const profile: ProfileLayoutProfile = {
  name: 'MIT CSAIL',
  handle: 'mit-csail',
  kind: 'org',
  image: '/avatars/mit-csail.png',  // ← when set, an <img> replaces the monogram
  // …
}
```

## Editable avatar

Pass `profile.onAvatarChange` to make the rail avatar interactive. Hovering
reveals a "change avatar" scrim and clicking opens a built-in upload sheet
(drag-and-drop, file picker, live preview, optional remove). The callback
fires with the chosen `File` on save, or `null` when the user clicked the
in-sheet "remove avatar" affordance before saving. It may return a Promise;
the sheet keeps itself open with a spinner while it resolves, and surfaces
a generic error if it rejects.

```tsx
const profile: ProfileLayoutProfile = {
  // …
  image: avatarUrl,
  onAvatarChange: async (file) => {
    if (file === null) {
      await deleteAvatar()
      setAvatarUrl(null)
      return
    }
    const { picture } = await uploadAvatar(file)
    setAvatarUrl(picture)
  },
}
```

## Editable name

`profile.onEditClick` adds a pencil button next to the name in the rail.
The pencil only materialises on group-hover of the name row, matching the
source design's restraint. The callback is fired-and-forgotten — the
component does not own any edit dialog; the caller decides what happens
next (typically a Dialog with its own validation, since profile-edit
flows tend to be app-specific):

```tsx
const profile: ProfileLayoutProfile = {
  // …
  onEditClick: () => setShowProfileSheet(true),
}
```

## Name accessory slot

`profile.nameAccessory` is a render slot anchored to the right of the
name row. The library stays content-agnostic — pass any React node
(theme-toggle pill, status badge, settings shortcut, etc.). The slot
stays visible regardless of hover so the accessory is always reachable
without opening a menu.

```tsx
const profile: ProfileLayoutProfile = {
  // …
  nameAccessory: ,
}
```

## Controlled tabs

By default `ProfileLayout` manages its own active tab — pass `defaultTab` for
the initial value and the layout takes it from there. For deep-linking,
in-page navigation, or any case where the active tab needs to live in external
state, switch to controlled mode by passing `tab` + `onTabChange` together:

```tsx
function MyProfilePage() {
  const [tab, setTab] = useState('overview')

  return (
    
  )
}
```

`tab` wins when both `tab` and `defaultTab` are present.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `profile` | `ProfileLayoutProfile` | — | Profile data rendered in the left rail. |
| `tabs` | `ProfileLayoutTab[]` | — | Tab descriptors with render functions. |
| `defaultTab` | `string` | `tabs[0]` | Initial tab in uncontrolled mode. Ignored when `tab` is provided. |
| `tab` | `string` | — | Controlled active tab. Pass alongside `onTabChange` to drive tab selection from outside. |
| `onTabChange` | `(tab: string) => void` | — | Fires when a tab change is requested. Required when using `tab`. |
| `logo` | `ReactNode` | — | Slot rendered top-left. Animates vertical position on scroll. |
| `actions` | `ReactNode` | — | Slot rendered top-right (e.g. account switcher). |
| `scrollContainerRef` | `RefObject` | `window` | Override scroll source. Pass a ref when embedding inside a bounded div. |
| `className` | `string` | — | Extra classes on the root element. |

### ProfileLayoutProfile

| Field | Type | Description |
| --- | --- | --- |
| `name` | `string` | Display name. Initials derive for the monogram fallback. |
| `handle` | `string` | Username shown as `@handle` below the name. |
| `kind` | `'user' \| 'org'` | Org accounts show a members section in the rail. |
| `image` | `string?` | Avatar image URL. When provided, the HeroRail renders an `<img>` (1:1, object-cover); when omitted, falls back to a monogram. |
| `bio` | `string?` | Optional bio paragraph. |
| `facts` | `ProfileLayoutFact[]?` | Key–value pairs in the facts grid (label column, value fills). |
| `members` | `ProfileLayoutMember[]?` | Org only. Avatar strip capped at 12 with `+N` overflow. |
| `onAvatarChange` | `(file: File \| null) => Promise<void> \| void` ? | When set, avatar becomes clickable — hover scrim + built-in upload sheet (drag-drop, preview, remove). Receives the chosen `File` (or `null` for remove) on save. May return a Promise; the sheet stays open with a spinner while it resolves and surfaces a generic error on reject. |
| `onEditClick` | `() => void` ? | When set, the name row shows a pencil button on group-hover. Caller owns the resulting edit dialog. |
| `nameAccessory` | `ReactNode` ? | Slot rendered right of the pencil on the name row. Stays visible regardless of hover. Library stays content-agnostic — pass any node (theme toggle, status badge, etc.). |

### ProfileLayoutTab

| Field | Type | Description |
| --- | --- | --- |
| `value` | `string` | Unique tab identifier. |
| `label` | `string` | Tab label text. |
| `count` | `number \| null?` | Optional count badge. The current design omits tab counts — pass nothing to match. |
| `showColsToggle` | `boolean?` | Show the 1/2-col layout toggle for this tab. |
| `render` | `(cols: 1 \| 2, scrolled: boolean) => ReactNode` | Renders tab content. For sticky elements inside the tab, offset by the exported `TOPBAR_H_SMALL` constant (the collapsed top-bar height) using the `scrolled` flag. |

`TOPBAR_H_SMALL` is exported alongside `ProfileLayout` — use it to position
sticky elements in a tab's `render` output relative to the collapsed top bar.

### ProfileLayoutFact

| Field | Type | Description |
| --- | --- | --- |
| `label` | `string` | Key label in the left column (uppercase mono). |
| `value` | `string` | Value displayed in the right column. |

### ProfileLayoutMember

| Field | Type | Description |
| --- | --- | --- |
| `id` | `string` | Unique member identifier (used as React key). |
| `name` | `string` | Display name. Initials derive for the avatar chip. |

---

Source: https://uikit.dreamlake.ai/components/resizable-layout

# ResizableLayout

A three-column drag-to-resize layout. Column widths are proportional
(flex-based) by default so the layout responds to any container size, but the
left and middle columns can each opt into a fixed pixel mode via `leftFixedPx`
and `middleFixedPx`. Widths are persisted to `localStorage` via `storageKey`.
Each divider reveals a cursor-following frosted pill on hover/drag.

## Demo

Drag the dividers to resize. All three columns are resizable by default. Hover
a divider to see the pill track the cursor.

## Without divider indicator

`showDivider={false}` hides the pill entirely. The drag area remains active —
hover and drag work as before.

## Custom gap

`gap` controls the visual space between columns in pixels (default `24`).
With `gap={0}` columns sit flush; the divider's hit area stays at least
`20px` wide so the resize handle is always grabbable.

## Hidden columns + fullscreen

`leftHidden`, `middleHidden`, and `rightHidden` each collapse a column to
zero width with an opacity fade. To make one column take the full viewport
("fullscreen"), hide the other two together — there's no dedicated
fullscreen prop because two hidden columns already express the intent.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `left` | `ReactNode` | — | Content for the left column. |
| `middle` | `ReactNode` | — | Content for the middle column. |
| `right` | `ReactNode` | — | Content for the right column. |
| `top` | `ReactNode` | — | Optional content rendered above all columns (e.g. a toolbar). |
| `showDivider` | `boolean` | `true` | Show the cursor-following pill on dividers. The drag area is always active. |
| `gap` | `number` | `24` | Visual width of the space between columns in px. The divider's interactive hit area stays at least 20px wide even when `gap` is smaller, so the resize handle is always grabbable. |
| `padding` | `number` | `12` | Outer padding from the layout's container edges in px. Set to `0` for designs where the layout sits flush with the viewport. |
| `defaultWidths` | `{ left?: number; middle?: number; right?: number }` | `2/3/5` | Initial flex weights for each column. Ignored for any column that opts into a fixed-px mode (`leftFixedPx`, `middleFixedPx`). |
| `minWidths` | `{ left?: number; middle?: number; right?: number }` | `80px` | Minimum pixel width per column, enforced during drag-resize. |
| `leftFixedPx` | `number` | — | Pin the left column to a fixed pixel width. The column ignores its flex ratio and never grows with the viewport. |
| `middleFixedPx` | `number` | — | Pin the middle column to a fixed-but-resize-adjustable pixel width. The middle-right drag mutates the value 1:1 (clamped by `minWidths.middle`); the right column takes the remaining width. Pair with `storageKey` to persist the px value. |
| `storageKey` | `string` | — | `localStorage` key to persist column widths across sessions. |
| `leftHidden` | `boolean` | `false` | Collapse the left column. |
| `middleHidden` | `boolean` | `false` | Collapse the middle column. |
| `rightHidden` | `boolean` | `false` | Collapse the right column. |
| `leftResizable` | `boolean` | `true` | Enable drag-to-resize on the left divider. |
| `rightResizable` | `boolean` | `true` | Enable drag-to-resize on the right divider. |
| `className` | `string` | — | Extra classes on the root element. |

---

Source: https://uikit.dreamlake.ai/components/select

# Select

A composable single-select with the kit's compact mono trigger. Compose
`SelectTrigger` (wrapping a `SelectValue`) with a `SelectContent` of
`SelectItem`s, optionally grouped via `SelectGroup` / `SelectLabel`. The panel
flips and shifts to stay within the viewport, supports keyboard list navigation
and typeahead, and matches the trigger width.

## Props

### `Select`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | — | Controlled selected value. |
| `defaultValue` | `string` | — | Initial value when uncontrolled. |
| `onValueChange` | `(value: string) => void` | — | Fired when the selection changes. |
| `open` / `onOpenChange` | — | — | Controlled open state. |
| `defaultOpen` | `boolean` | `false` | Initial open state when uncontrolled. |

`SelectValue` takes a `placeholder`. `SelectItem` takes `value` and `disabled`.
`SelectTrigger` accepts `asChild` and an `icon` (a leading `ReactNode` rendered
before the value).

---

Source: https://uikit.dreamlake.ai/components/side-nav

# SideNav

A sidebar shell with a pinned header, a pinned footer, and a scrollable body
divided into titled groups. Group titles stick to the top of the scroll
container as the user scrolls. The shell paints `var(--rail-bg)` as its
background, so it follows the active theme automatically.

## Demo

Scroll inside the panel to see group titles stick. Click a dataset to see the
active state.

## Props

### SideNav

| Prop | Type | Description |
| --- | --- | --- |
| `header` | `ReactNode` | Pinned top area — logo, workspace label, collapse button, etc. |
| `footer` | `ReactNode` | Pinned bottom area — shortcuts, upload queue, account row, etc. |
| `children` | `ReactNode` | Scrollable content, typically `SideNavGroup` elements. |
| `className` | `string` | Extra classes on the root. Background defaults to `var(--rail-bg)`. |

### SideNavGroup

| Prop | Type | Description |
| --- | --- | --- |
| `title` | `string` | Group label — uppercase mono. Sticks to the top of the scroll container when scrolled past. |
| `action` | `ReactNode` | Node rendered to the right of the title — typically a small icon button. |
| `children` | `ReactNode` | Group content — fully up to the caller. |
| `className` | `string` | Extra classes on the group wrapper. |

> **Opaque group headers** — group headers stay opaque as rows scroll beneath
> them, so pinned titles never show the content passing underneath.

---

Source: https://uikit.dreamlake.ai/components/tabs

# Tabs

An animated tab switcher with two visual variants. Both share the same
controlled / uncontrolled API — only the appearance changes. Content rendering
is left to the caller.

## Underline (default)

The default `underline` variant: a sliding bottom indicator under the active
tab.

## Controlled

## Count badges

Add `count` to any tab to show a pill badge. Badge opacity and background
respond to active and hover state.

## Small size

Use `size="sm"` for a compact 12px tab bar.

## Segment variant

A classic segmented control: tinted container background, active tab gets a
raised pill matching the page background. `label` accepts any `ReactNode` —
pass icons or text.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tabs` | `Tab[]` | — | Array of tab descriptors. |
| `variant` | `'underline' \| 'segment'` | `'underline'` | Visual style. |
| `value` | `string` | — | Controlled active tab value. |
| `defaultValue` | `string` | `tabs[0]` | Initial tab in uncontrolled mode. |
| `onChange` | `(value: string) => void` | — | Called when the user clicks a tab. |
| `onValueChange` | `(value: string) => void` | — | Alias for `onChange`. |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Controls text size and button dimensions across all variants. |
| `indicatorHeight` | `number` | `4` | Indicator thickness in px. `underline` variant only. |
| `className` | `string` | — | Extra classes on the container. |

### Tab

| Field | Type | Description |
| --- | --- | --- |
| `value` | `string` | Unique identifier for the tab. |
| `label` | `ReactNode` | Content rendered inside the tab — string, icon, or any element. |
| `count` | `number` | Count badge shown next to the label. `underline` variant only. |
| `title` | `string` | Tooltip text. Useful for icon-only segment tabs. |

## Compound API

Instead of the data-driven `tabs` prop, you can compose the tab bar and its
panels from sub-components. Pass `value` / `defaultValue` and
`onValueChange` (or `onChange`) to `Tabs`, then place `TabsList` /
`TabsTrigger` / `TabsContent` as children. Each `TabsContent` renders only
when its `value` matches the active tab.

```tsx

  
    Overview
    Activity
  
  …
  …

```

### `TabsList`

Row container for the triggers. Accepts any `<div>` props plus `className`.

### `TabsTrigger`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | — | Identifier this trigger activates. Required. |
| `className` | `string` | — | Extra classes on the button. |

Also forwards native `<button>` attributes (`onClick`, `disabled`, …).

### `TabsContent`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | — | Panel is shown only when this matches the active tab. Required. |
| `className` | `string` | — | Extra classes on the panel. |

---

Source: https://uikit.dreamlake.ai/components/tag

# Tag

Two tag styles in one component. Pick `variant` by the role the tag plays:

- **`variant="tag"` (default)** — hashtag presentation. `#name` with an
  underline when active. Used in experiment metadata, dataset bindrs, profile
  project footers.
- **`variant="pill"`** — boxed pill with a hairline border, fills with accent
  when active. Used for filter chips, single-select tag pickers.

## Removable tags

Hover any tag to reveal the × button. Clicking × calls `onRemove` — wire it
to delete from your state. Hovering the × turns the row red and adds a
strikethrough preview.

## Active state and accent override

`active` underlines the label. By default, hover and the active underline both
use `var(--uikit-accent)`. Pass `accent` to override — accepts a palette tone name
(`'green'`, `'red'`, …) or any CSS color string. The static text stays
`var(--ink)` — only hover and the active underline pick up the accent.

## Tone (palette colors)

`tone` constrains the tag to one of the design's six palette buckets and sets
BOTH the static text color AND the default accent (hover/active). Use it for
status-colored labels — `#failed`, `#running`, `#stale`. For the rare case
where you want the static color to differ from hover, override `accent`
independently.

## Pill variant

A single-select chip row. The active pill fills with `accent`, others show a
hairline ring.

## Color resolution

| Props | Static text | Hover / active |
| --- | --- | --- |
| `` | `var(--ink)` | `var(--uikit-accent)` |
| `` | `var(--ink)` | `green` tone |
| `` | `var(--ink)` | `#abc123` |
| `` | `red` tone | `red` tone |
| `` | `red` tone | `amber` tone |
| `` | `red` tone | `#abc123` |

> **Confirmation flows** — `Tag` fires `onRemove` immediately on × click. If
> you want a "are you sure?" step or a "don't ask for the next 10 minutes"
> suppression window, wrap the call in `Dialog` / your own confirmation logic.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `name` | `string` | — | Tag label text. |
| `variant` | `'tag' \| 'pill'` | `'tag'` | Visual style — hashtag with underline, or boxed pill. |
| `active` | `boolean` | `false` | Pill fills with accent; tag underlines. |
| `removable` | `boolean` | `false` | Show a × button on hover that calls `onRemove`. |
| `tone` | `TagTone` | — | Constrain the tag to one of 6 palette buckets. Sets both static text color and default accent. |
| `accent` | `TagTone \| string` | — | Override the hover/active color. Accepts a palette tone name or any CSS color. |
| `light` | `boolean` | `false` | Reduce font weight to 400. |
| `compact` | `boolean` | `false` | Reduce font size by ~1.5px. |
| `onClick` | `() => void` | — | Click handler for the tag body. |
| `onRemove` | `() => void` | — | Called when the user clicks the × button (only when `removable`). |
| `className` | `string` | — | Extra classes on the root span. |

### TagTone

Six semantic-palette buckets per `design.md`. Pick by **function**, not vibe.

| Tone | Description |
| --- | --- |
| `'blue'` | Active / running / accent. Also the library's `--accent` token. |
| `'green'` | Ok / source / success. "passed", "ingest", "draft release". |
| `'amber'` | Stale / scheduled / filter. "Needs review", warnings. |
| `'red'` | Error / sink / quarantine. Failed states, destructive actions. |
| `'purple'` | Model / merge / human-authored. PRs, tags, code authorship. |
| `'warmGray'` | Idle / queued / placeholder. Neutral chips, "noop". |

---

Source: https://uikit.dreamlake.ai/components/text-field

# TextField

A controlled text input. `onChange` receives the raw string value (not the
event), so it drops straight into form libraries — e.g. a react-hook-form
`Controller`'s `field`. Use it inside [Field](/components/field.md) for a label,
hint and error.

## Basic

## Prefix, invalid & multiline

`prefix` renders a leading adornment (e.g. `/` for slugs); `mono` switches to
the monospace face; `invalid` paints a danger border; `multiline` renders a
`<textarea>` (`rows` controls its height).

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | — | Current value (controlled). |
| `onChange` | `(value: string) => void` | — | Called with the new string value. |
| `prefix` | `ReactNode` | — | Leading adornment inside the field. |
| `multiline` | `boolean` | `false` | Render a `<textarea>` instead of `<input>`. |
| `rows` | `number` | `4` | Textarea row count (when `multiline`). |
| `invalid` | `boolean` | `false` | Danger border + `aria-invalid`. |
| `mono` | `boolean` | `false` | Use the monospace face. |
| `disabled` | `boolean` | `false` | Disables input. |
| `className` | `string` | — | Extra classes on the field shell. |

Other native `<input>` attributes (`placeholder`, `type`, `onBlur`, `autoFocus`,
`maxLength`, …) are forwarded.

---

Source: https://uikit.dreamlake.ai/components/virtual-list

# VirtualList

Renders only the visible slice of a large list. Supports fixed item heights,
dynamic (content-driven) heights, and infinite scroll.

## Fixed height

Pass `itemHeight` as a number (px).

## Dynamic height

Pass `itemHeight="dynamic"` for content-driven heights. Each item is measured
after it renders. Use `estimatedItemHeight` to set the initial layout estimate.

## Infinite scroll

Pass `hasMore`, `loadingMore`, and `onLoadMore`. The callback fires when the
scroll position is within `loadMoreThreshold` px (default `80`) of the bottom.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `T[]` | — | Array of items to render. |
| `itemHeight` | `number \| "dynamic"` | — | Fixed height in px, or `"dynamic"` for content-driven heights. |
| `estimatedItemHeight` | `number` | `40` | Initial height estimate used in dynamic mode. |
| `height` | `number \| string` | `"100%"` | Container height. |
| `overscan` | `number` | `3` | Extra items rendered outside the visible area. |
| `getItemKey` | `(item, index) => string \| number` | `index` | Returns a stable key for each item. |
| `children` | `(item, index, style) => ReactNode` | — | Render function. Must apply `style` to the item root element. |
| `hasMore` | `boolean` | `false` | Whether more items can be loaded. |
| `loadingMore` | `boolean` | `false` | Shows a loading indicator at the bottom while true. |
| `onLoadMore` | `() => void` | — | Called when scroll reaches the load-more threshold. |
| `loadMoreThreshold` | `number` | `80` | Px from bottom that triggers `onLoadMore`. |
| `renderLoadingMore` | `ReactNode` | `"Loading more…"` | Custom content shown while `loadingMore` is true. |
| `onScroll` | `(scrollTop: number) => void` | — | Fires on scroll with the current `scrollTop` value. |
| `onRangeChange` | `(start, end) => void` | — | Fires when the visible index range changes. |
| `stickyHeader` | `ReactNode` | — | Header rendered inside the scroll container with `position: sticky`. Only shown when `stickyHeaderHeight` is greater than `0`. |
| `stickyHeaderHeight` | `number` | `0` | Height of `stickyHeader`. Subtracted from visible-area calculations so items don't render under it. |
| `className` | `string` | — | Extra classes on the container. |

---

Source: https://uikit.dreamlake.ai/components/virtual-list-flow

# VirtualListFlow

Same external API as [`VirtualList`](./virtual-list), but items render in
**CSS normal flow** instead of being taken out of flow and positioned
individually. Use this variant when virtualization needs to coexist with
`position: sticky` inside items, CSS `gap`, or any other layout rule that
depends on items participating in the document's flow.

## Why a second variant

In the original `VirtualList`, items don't participate in the document's
normal flow, so layout rules that depend on flow behave differently:
`position: sticky` inside an item pins to that item rather than the outer
scroll container, and CSS `gap` / `margin` between items has to be baked
into each item's own padding.

`VirtualListFlow` keeps the same windowing behavior but renders items in
normal flow, so `sticky`, `gap`, and browser scroll anchoring work the
way they do in a non-virtual list. The trade-off is a slightly heavier
repositioning cost on scroll — usually well worth it for lists of cards
or sections with layered structure inside them.

## When to pick which

| | `VirtualList` (absolute) | `VirtualListFlow` (flow) |
| --- | --- | --- |
| Sticky inside an item | Pinned to item, not scroll container | Pinned to scroll container ✓ |
| CSS `gap` / `margin` between items | Bake into item padding | Works natively ✓ |
| Compositing layers | One per visible item | None per item ✓ |
| Repositioning cost on scroll | Compositor only (cheap) | Layout (cheap, but heavier than compositor) |
| Async height-change scroll drift | Possible | Browser scroll anchoring keeps stable ✓ |

If a list doesn't need any of the flow-side wins, `VirtualList` is
fine and slightly cheaper. For any list of cards, sections, or items
with sticky/layered structure inside them, prefer `VirtualListFlow`.

## Fixed height

Pass `itemHeight` as a number (px).

## Dynamic height

Pass `itemHeight="dynamic"` for content-driven heights. Each item is
measured after it renders. Use `estimatedItemHeight` to set the initial
layout estimate; the scroll position stays stable when measured heights
replace estimates.

## Infinite scroll

Pass `hasMore`, `loadingMore`, and `onLoadMore`. The callback fires when
the scroll position is within `loadMoreThreshold` px (default `80`) of
the bottom.

## Props

`VirtualListFlow` re-exports the same `VirtualListProps` type as
`VirtualList`, so callers can swap one for the other without rewriting
JSX. The `style` argument passed to the `children` render fn is just
`{ width: '100%' }` (plus `height` in fixed mode) — no positioning
information, because items are in normal flow and don't need any.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `T[]` | — | Array of items to render. |
| `itemHeight` | `number \| "dynamic"` | — | Fixed height in px, or `"dynamic"` for content-driven heights. |
| `estimatedItemHeight` | `number` | `40` | Initial height estimate used in dynamic mode. |
| `height` | `number \| string` | `"100%"` | Container height. |
| `overscan` | `number` | `3` | Extra items rendered outside the visible area. |
| `getItemKey` | `(item, index) => string \| number` | `index` | Returns a stable key for each item. |
| `children` | `(item, index, style) => ReactNode` | — | Render function. Applying `style` is optional in flow mode — only `width` (and `height` in fixed mode) are set. |
| `hasMore` | `boolean` | `false` | Whether more items can be loaded. |
| `loadingMore` | `boolean` | `false` | Shows a loading indicator at the bottom while true. |
| `onLoadMore` | `() => void` | — | Called when scroll reaches the load-more threshold. |
| `loadMoreThreshold` | `number` | `80` | Px from bottom that triggers `onLoadMore`. |
| `renderLoadingMore` | `ReactNode` | `"Loading more…"` | Custom content shown while `loadingMore` is true. |
| `onScroll` | `(scrollTop: number) => void` | — | Fires on scroll with the current `scrollTop` value. |
| `onRangeChange` | `(start, end) => void` | — | Fires when the visible index range changes. |
| `stickyHeader` | `ReactNode` | — | Header rendered inside the scroll container with `position: sticky`. |
| `stickyHeaderHeight` | `number` | `0` | Height of `stickyHeader`. Subtracted from visible-area calculations so items don't render under it. |
| `className` | `string` | — | Extra classes on the container. |

---

Source: https://uikit.dreamlake.ai/components/video-annotator

# VideoAnnotator

A video player with an **editable, contiguous segment timeline** — the labeling
surface for splitting a clip into consecutive phases and captioning each one.
It owns the `<video>` element, a transport bar (frame-step, boundary jump,
play/pause, playback speed) and a percentage-positioned timeline strip with
drag-to-move boundaries and click-to-scrub. Segments always tile the whole clip
with no gaps or overlaps (`end === next.start`); any structural edit resets the
`verified` flag on the affected segments.

The component is **controlled** on `segments` + `selectedIndex`: it runs the
split/merge/boundary invariants internally and hands the host a fresh array via
`onSegmentsChange`, so the host owns state and persistence.

## Demo

Drag a boundary to move it, double-click a boundary to merge, click a segment to
select it, drag anywhere on the track to scrub. Keyboard: `Space` play/pause,
`←`/`→` step frame (`Shift` = 1s, `Alt` = jump boundary), `,`/`.` prev/next
boundary, `s` split, `Backspace` merge, `j`/`k` prev/next phase, `a` approve.

## Driving it from a ref

Set `enableKeyboard={false}` and drive the widget through its imperative handle
(`split`, `merge`, `stepFrame`, `gotoBoundary`, `play`, `pause`, `toggleApprove`)
when the host owns its own transport chrome or a global shortcut scheme.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `videoUrl` | `string \| null` | — | Video source URL. Empty shows a placeholder in the stage. |
| `videoTitle` | `string` | — | Title shown in a header row above the video (e.g. the clip name). |
| `videoSubtitle` | `string` | — | Monospace subtitle beside the title (e.g. the file path). |
| `headerLeading` | `ReactNode` | — | Element at the start of the header row (e.g. a "show list" button). |
| `showDescription` | `boolean` | `false` | Render the boxed description editor for the selected segment below the timeline. |
| `onDescriptionChange` | `(index: number, value: string) => void` | — | Fired when the description editor changes. Required for it to be interactive. |
| `segments` | `Segment[]` | — | Controlled segment list. The component enforces the contiguous invariant. |
| `selectedIndex` | `number` | — | Controlled index of the active segment. |
| `onSegmentsChange` | `(next: Segment[]) => void` | — | Fired after any structural edit (split / merge / boundary drag). |
| `onSelectedChange` | `(index: number) => void` | — | Fired when the active segment changes. |
| `onApproveToggle` | `(index: number, verified: boolean) => void` | — | Fired when the user toggles verification (`a`). |
| `duration` | `number` | — | Authoritative clip duration (s). Falls back to the video's `loadedmetadata` duration, then the largest segment end. |
| `extractFps` | `number \| null` | `30` | Frames-per-second for frame-stepping granularity (`←`/`→`). |
| `srcFps` | `number \| null` | `30` | Source fps for the "· fN" frame readout. |
| `loop` | `boolean` | `true` | Loop playback within the selected segment. |
| `speeds` | `number[]` | `[0.25,0.5,1,1.5,2]` | Playback-speed options for the speed dropdown. |
| `enableKeyboard` | `boolean` | `true` | Install the document-level keyboard shortcuts. Set `false` to drive only via the ref. |
| `className` | `string` | — | Extra classes on the root element. |

### Segment

| Field | Type | Description |
| --- | --- | --- |
| `start` | `number` | Segment start time in seconds. |
| `end` | `number` | Segment end time in seconds (`= next.start` after normalization). |
| `description` | `string` | Free-text caption for the phase. |
| `verified` | `boolean` | Human-confirmed flag; reset by structural edits. |

---

Source: https://uikit.dreamlake.ai/components/spinner

# Spinner

An indeterminate loading indicator: two out-of-phase expanding circles drawn as
an inline SVG. It renders inline (use it inside buttons, list rows, or empty
states) and defaults to the muted token so it sits quietly until content loads.

## Sizes

`size` sets the diameter in px (default `24`). The SVG scales crisply at any
size.

## Color

The stroke is `currentColor`. By default it tints to `--muted`; pass any
`text-*` utility (or set `color` on a parent) to recolor it — useful for tinting
a spinner to a tone while an action runs.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `number \| string` | `24` | Diameter in px. |
| `className` | `string` | — | Extra classes (e.g. a `text-*` color). |

Any other native `<svg>` attributes (`style`, `aria-*`, …) are forwarded.

---

Source: https://uikit.dreamlake.ai/components/skeleton

# Skeleton

A low-emphasis placeholder shown while content is loading. It's just a tinted,
pulsing `<div>` — you size and shape it with width/height and border-radius to
mirror the real content's layout.

## Text lines

Stack a few with varied widths to stand in for a paragraph or list row.

## Composed placeholder

Combine differently sized skeletons to mirror a card (avatar + two text lines).

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | — | Sizing/shape utilities (width, height, rounding). |

Any other native `<div>` attributes (`style`, `aria-*`, …) are forwarded. The
block is a subtle pulsing placeholder; override the background via `className`
if you need a different surface.

---

Source: https://uikit.dreamlake.ai/components/switch

# Switch

A binary on/off toggle for settings. It's a `role="switch"` button (keyboard
and screen-reader friendly) that fills with the accent token when on. Use it for
instant-apply preferences; for form submits prefer a checkbox.

## States

Off, on, and disabled in both positions.

## Controlled

Drive it from state with `checked` + `onCheckedChange`. Omit `checked` and pass
`defaultChecked` to let the switch manage its own state.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` | `boolean` | — | Controlled state. Omit for uncontrolled. |
| `defaultChecked` | `boolean` | `false` | Initial state when uncontrolled. |
| `onCheckedChange` | `(checked: boolean) => void` | — | Fired with the next state on toggle. |
| `disabled` | `boolean` | `false` | Disables interaction. |
| `className` | `string` | — | Extra classes on the track. |
| `thumbClassName` | `string` | — | Extra classes on the moving thumb. |

Any other native `<button>` attributes (`aria-*`, `id`, …) are forwarded.

---

Source: https://uikit.dreamlake.ai/components/badge

# Badge

A compact inline badge for counts and statuses. Filled variants map onto the
6-color semantic palette; `secondary`/`outline` stay neutral.

> Related: [Tag](/components/tag.md) is the hashtag/pill primitive for filter chips
> and categorical labels. Reach for **Badge** for counts and short status
> markers, **Tag** for selectable/removable category pills.

## Variants

## Shapes

`type` switches the shape: `default` (label pill), `circle` (square-ish single
glyph / count), and `dot` (a bare colored indicator with no label).

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `'default' \| 'secondary' \| 'outline' \| 'success' \| 'warning' \| 'destructive' \| 'purple' \| 'neutral'` | `'default'` | Color/fill (covers the full 6-tone palette). |
| `type` | `'default' \| 'circle' \| 'dot'` | `'default'` | Shape. |
| `asChild` | `boolean` | `false` | Render the single child element instead of a `<span>`, merging classes. |
| `className` | `string` | — | Extra classes. |

`badgeVariants({ variant, type, className })` is also exported — it returns the
composed class string for hand-built badge-styled elements.

---

Source: https://uikit.dreamlake.ai/components/collapsible

# Collapsible

A region that expands and collapses. Compose three parts: `Collapsible` (state
owner), `CollapsibleTrigger` (toggles it), and `CollapsibleContent` (the
animated-height body).

Open state can be controlled (`open` + `onOpenChange`) or uncontrolled
(`defaultOpen`). The trigger accepts `asChild` to reuse your own button/element.

## Props

### `Collapsible`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | — | Controlled open state. Omit for uncontrolled. |
| `defaultOpen` | `boolean` | `false` | Initial state when uncontrolled. |
| `onOpenChange` | `(open: boolean) => void` | — | Fired with the next state on toggle. |
| `disabled` | `boolean` | `false` | Blocks toggling. |

### `CollapsibleTrigger`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `asChild` | `boolean` | `false` | Render the single child as the trigger, merging handlers/classes. |

### `CollapsibleContent`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | — | Classes on the inner content element. |

---

Source: https://uikit.dreamlake.ai/components/card

# Card

A content container on a panel surface with a hairline border and token-scaled
padding. Compose it from `CardHeader`, `CardTitle`, `CardDescription`,
`CardAction`, `CardContent`, and `CardFooter`.

## Basic

`size` (`sm` / `md` / `lg` / `xl`, default `lg`) sets the padding scale.

## Collapsible

Set `collapsible` and provide `collapsedContent` (shown in place of the body
when collapsed). `defaultCollapsed` controls the initial state.

## Props

### `Card`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `'sm' \| 'md' \| 'lg' \| 'xl'` | `'lg'` | Padding scale. |
| `collapsible` | `boolean` | `false` | Enable the collapse toggle. |
| `collapsedContent` | `ReactNode` | — | Shown in place of the body while collapsed. |
| `defaultCollapsed` | `boolean` | `false` | Initial collapsed state. |
| `className` | `string` | — | Extra classes. |

Subcomponents (`CardHeader`, `CardTitle`, `CardDescription`, `CardAction`,
`CardContent`, `CardFooter`) accept `className` and native `<div>` attributes.
`CardHeader` also takes a `size` matching the card.

---

Source: https://uikit.dreamlake.ai/components/alert-dialog

# Alert Dialog

A modal dialog that interrupts the user to confirm a consequential action.
Unlike a plain [Dialog](/components/dialog.md), it **does not** dismiss on backdrop
click — the user must choose `AlertDialogAction` or `AlertDialogCancel` (Esc also
cancels).

Compose `AlertDialogTrigger` + `AlertDialogContent` (with `AlertDialogHeader`,
`AlertDialogTitle`, `AlertDialogDescription`, `AlertDialogFooter`, and the
`AlertDialogAction` / `AlertDialogCancel` buttons). Open state can be controlled
(`open` + `onOpenChange`) or uncontrolled.

## Props

### `AlertDialog`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | — | Controlled open state. Omit for uncontrolled. |
| `defaultOpen` | `boolean` | `false` | Initial state when uncontrolled. |
| `onOpenChange` | `(open: boolean) => void` | — | Fired when open state changes. |

`AlertDialogTrigger`, `AlertDialogAction`, and `AlertDialogCancel` each accept
`asChild` to render your own button. `Action`/`Cancel` close the dialog after
their `onClick` runs (call `preventDefault()` to keep it open).

---

Source: https://uikit.dreamlake.ai/components/drawer

# Drawer

A panel anchored to a screen edge — for filters, details, or mobile menus.
Compose `DrawerTrigger` + `DrawerContent` (with `DrawerHeader`, `DrawerTitle`,
`DrawerDescription`, `DrawerFooter`) and an optional `DrawerClose`. Closes on Esc
and backdrop click.

`direction` (`top` / `bottom` / `left` / `right`, default `bottom`) sets the
edge. Open state can be controlled (`open` + `onOpenChange`) or uncontrolled.

## Props

### `Drawer`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `direction` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'bottom'` | Edge to anchor to. |
| `open` | `boolean` | — | Controlled open state. Omit for uncontrolled. |
| `defaultOpen` | `boolean` | `false` | Initial state when uncontrolled. |
| `onOpenChange` | `(open: boolean) => void` | — | Fired when open state changes. |

`DrawerTrigger` and `DrawerClose` accept `asChild` to render your own element.

---

Source: https://uikit.dreamlake.ai/components/toast

# Toast

Transient, non-blocking notifications. Mount `` **once** near the app
root, then call the imperative `toast()` API from anywhere.

```tsx

// at the app root:

// anywhere:
toast('Saved')
toast.success('Published')
toast.error('Upload failed', { description: 'Network error.' })
toast.promise(upload(), { loading: 'Uploading…', success: 'Done', error: 'Failed' })
```

## API

| Call | Description |
| --- | --- |
| `toast(message, opts?)` | Neutral toast. |
| `toast.message(message, opts?)` | Neutral toast — alias for `toast()`. |
| `toast.success / error / info / warning(message, opts?)` | Typed toasts with a colored indicator dot. |
| `toast.loading(message, opts?)` | Sticky toast with a spinner (until dismissed/updated). |
| `toast.promise(p, { loading, success, error })` | Shows loading, then resolves to success/error. |
| `toast.dismiss(id?)` | Dismiss one toast (or all when `id` omitted). |

`opts`: `{ id?, description?, duration?, action? }`. Pass an existing `id` to
reuse and replace that toast in place (a new toast is created when the id is
new). Auto-dismiss defaults to the Toaster's `duration` (4000ms); pass
`duration: Infinity` to keep a toast until dismissed.

`toast.promise` also accepts a function that returns the promise (called
immediately), and its `success` / `error` can be functions — they receive the
resolved value or the error and return the message to show.

## `Toaster` props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `position` | `'top-left' \| 'top-center' \| 'top-right' \| 'bottom-left' \| 'bottom-center' \| 'bottom-right'` | `'bottom-right'` | Stack anchor. |
| `duration` | `number` | `4000` | Default auto-dismiss (ms). |

---

Source: https://uikit.dreamlake.ai/components/uikit-badge

# UIKit Badge

A small two-chip badge that shows the kit's package name and version —
`[ uikit | v0.1.6 ]` — handy in galleries, footers, and dev tools. The version
reflects the installed package; when consumed from source it shows as `dev`.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `package` | `boolean` | `false` | Show the short package-name chip. |
| `version` | `boolean` | `false` | Show the version chip. |
| `prefix` | `boolean` | `false` | Prefix the version with `v`. |
| `hash` | `boolean` | `false` | Show the git-hash chip. No git hash is currently injected, so this chip does not render. |
| `linkable` | `boolean` | `false` | Link the chips to npm / GitHub. |
| `className` | `string` | — | Extra classes. |

The lower-level `PackageBadge` (fully prop-driven) and the `PACKAGE_NAME` /
`PACKAGE_VERSION` constants are also exported.

---

Source: https://uikit.dreamlake.ai/pipeline-view/pipeline-graph

# Pipeline Graph

`PipelineGraph` draws a DreamLake **pipeline** as an interactive flow-chart. It's
purely presentational: you hand it one JSON object and it renders the DAG —
dotted canvas, status-tinted node cards, orthogonal edges, live flow animation —
with **no data fetching of its own**. `PipelineSource` is the paired read-only
source inspector.

If you just want to render a graph, this page is the whole story. For the exact
data shape see [Pipeline Graph JSON](/pipeline-view/pipeline-graph-json.md); for a
field-by-field visual map see [Anatomy](/pipeline-view/anatomy.md); for how the
component is built and what's coming, see
[Architecture & Roadmap](/pipeline-view/architecture.md).

## Background — what this renders and why

DreamLake runs an **AI auto-labeling + human-review** loop: models propose
labels, reviewers gate them, accepted rows land in a dataset and the rest go
back for rework. That loop is written as a **pipeline** — a plain Python
`@dl.pipeline` function whose stages are `@ls.udf` functions.

You never draw this graph by hand. The `dl_trace` tracer reads the pipeline's
Python **statically** (no import, no execution) and derives the node/edge graph
from its dataflow. So:

- **The graph is a derived view of code.** Change the `.py`, re-trace, the graph
  updates. There is no separate diagram to keep in sync.
- **Placeholder bodies (`...`) trace like real ones**, so a graph renders long
  before any stage is implemented.
- **This component only draws.** Tracing happens elsewhere (a Python service);
  the runtime status that animates the graph streams in separately.

**Who this is for:** anyone rendering a traced pipeline in a UI — a Studio view,
a dashboard, a docs page. You supply the traced JSON (and optionally a live
status overlay); the component owns the canvas.

## One stage, three faces

The thing that makes the data model click: **a node is one stage seen three
ways.** You write a Python UDF; the tracer emits a JSON node; the component
draws a card. They are the same object.

**① The Python you write** — a `@ls.udf` stage. Its parameters become input
ports; its return columns become the result schema:

```python
@ls.udf
def detect_objects(images: Tensor["N", "H", "W", 3]) -> Tuple["boxes", "classes", "confidence"]:
    """Detect objects in each image; one row per box."""
    ...
```

**② The node you see, ③ the JSON in between** — flip between the rendered card
(**Preview**), the render call (**Source**), and the tracer's node JSON
(**Data**). The card *is* the JSON: the kind dot ← `kind`, the title ← `title`,
the `1→1` meta ← `inputs`/`outputs` lengths, the edge dots ← the `inputs` /
`outputs` ports.

The return columns (`boxes`, `classes`, `confidence`) live in `columns` — the
result's schema, **not** extra ports. A UDF returns one table; passing it
downstream passes the whole table. See [Anatomy](/pipeline-view/anatomy.md) for the
full field-to-pixel map.

## Basic

A freshly-traced graph is entirely `idle`. **Drag** nodes to rearrange, **scroll**
(or two-finger drag) to pan, **⌘/ctrl-scroll or pinch** to zoom, **click** a node
to select it. Once the canvas is focused, **arrow keys** walk the selection —
**↑ / ↓** step through the pipeline in topological order, **← / →** jump to the
upstream / downstream neighbour, **Esc** clears — and the selected node pans into
view. Edges come in two kinds — `data` (solid) and `mask` (dashed gate); the
[Anatomy](/pipeline-view/anatomy.md) page shows both.

## Graph + source, linked

The design layout is a canvas with a source **right rail**. The two share one
selection: click a node and its source shows on the right; click the background
to clear. Both components are controlled — you own the `selectedNodeId` state.

## Live status — a runnable pipeline

Edges carry **no** stored style. Each edge's visual *flow* is derived from the
`status` of its two endpoint nodes, so animating a running pipeline is just a
matter of feeding node statuses in via the `statusById` overlay. The six flow
states, and how each is derived, are catalogued in
[Anatomy → Connector states](/pipeline-view/anatomy.md#connector-states).

The demo below is a tiny in-browser "runner". Each node, when it finishes,
settles to a **random** outcome — mostly `ok`, occasionally `stale` or `error`.
A node only starts once all its upstreams have settled **and none errored**, so
a failure **blocks** everything downstream (those nodes never run and stay
idle), exactly like a real pipeline. Nothing real executes — it only drives
`statusById`. Press **Run** (each run re-rolls): `running` edges flow blue, `ok`
edges go green, a `stale` node's edges turn amber, an `error` node's edges turn
red, and nodes blocked by an upstream failure stay idle.

## Props

### `PipelineGraph`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `graph` | `PipelineGraphData` | — | The traced graph JSON. |
| `statusById` | `StatusOverlay` | — | Live per-node `{ status, progress, ... }`, merged onto the graph. |
| `selectedNodeId` | `string \| null` | — | Controlled selection. Omit for uncontrolled. |
| `onSelectNode` | `(id: string \| null) => void` | — | Selection change (also fires on background click). |
| `className` | `string` | — | Extra classes on the canvas. |

### `PipelineSource`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `graph` | `PipelineGraphData` | — | The traced graph JSON. |
| `selectedNodeId` | `string \| null` | — | Which node's source to show (else the whole `.py`). |
| `onSelectNode` | `(id: string \| null) => void` | — | Fired by the `pipeline.py` tab to clear the selection. |
| `className` | `string` | — | Extra classes. |

Both are theme-aware (uikit tone tokens) and load `@dreamlake/uikit/styles.css`
for their colours.

---

**Next:** [Anatomy](/pipeline-view/anatomy.md) maps every field to a pixel ·
[Pipeline Graph JSON](/pipeline-view/pipeline-graph-json.md) is the data-model
reference · [Architecture & Roadmap](/pipeline-view/architecture.md) covers the
internals and what's next.

---

Source: https://uikit.dreamlake.ai/pipeline-view/anatomy

# Anatomy

The data model, shown **next to what it draws** — never in isolation. Each block
below is one thing (a node, a connector tag, a connector state) rendered live,
with its **TypeScript** (the render call) and its **JSON** (the tracer's output)
one tab away. Flip the `Preview` / `Source` / `Data` tabs to line the three up.

For the prose reference of the same shapes, see
[Pipeline Graph JSON](/pipeline-view/pipeline-graph-json.md).

## The node card

A node is one stage — a `@ls.udf` — as a `156 × 72` card. Everything on it comes
straight from the node JSON; nothing is styled by hand.

| On the card | JSON field | Notes |
| --- | --- | --- |
| Kind dot (top-left square) | `kind` | Tints by category — `source` green, `transform` blue, `model`/`review` purple, `filter` amber, `merge` grey, `sink` red. |
| Title | `title` | The UDF name. `id` is the stable key (may differ on fan-out: `semantic_match_2`). |
| Meta line `transform · 1→1` | `kind` · `inputs.length`→`outputs.length` | The `→` is port **counts**, not columns. |
| Left dots | `inputs` | One input port per UDF parameter. |
| Right dot | `outputs` | A UDF returns **one** table → a single `["out"]` port. A sink has none (`[]`). |
| Status dot + label (footer) | `status` | `idle` here; drives tint + the pulse when `running`. |
| _(not drawn on the card)_ | `columns` | The result **schema** — `boxes`, `classes`, `confidence`. Surfaced in the source inspector, not as ports. |

**Ports vs columns** is the one thing to internalise: `inputs` are ports (one
per parameter), `outputs` is a single port (the whole result table), and the
return column names live in `columns` — a schema, not more ports.

## Connector tags

An edge carries exactly one structural tag, `kind`, decided by the tracer. It's
the only style an edge stores; everything else about an edge is
[derived from status](#connector-states).

### `data` — the value flows through (solid)

The default. The source's result table is consumed by the target.

### `mask` — the source gates the target (dashed)

A gate, not data flow. The source (a review veto or a confidence/consensus mask)
only decides **which rows** of the target survive. In Python this is
`labels[consensus]` — a boolean selector — so it reads as a gate without adding a
filter node. Rendered dashed and slightly fainter in the settled states.

| Tag | Meaning | Look | Produced by |
| --- | --- | --- | --- |
| `data` | source result flows into target | solid | passing a UDF result as an argument |
| `mask` | source only filters/gates target | dashed, fainter | a boolean mask used as a selector (`labels[mask]`) |

## Connector states

An edge stores **no** colour, width, or animation. Its *flow* — how it looks
right now — is **derived** at render time from the `status` of its two endpoint
nodes, via one shared function:

```ts
edgeFlow(src: NodeStatus, dst: NodeStatus):
  'running' | 'queued' | 'stalled' | 'error' | 'ok' | 'idle'
```

Six states, one derived value. Below, each swatch is the real
`FLOW[state]` styling, next to the status pair that produces it (this board is
built straight from the exported `edgeFlow` + `FLOW`, so it can't drift from the
component):

| Flow | Derived when | Look |
| --- | --- | --- |
| `running` | src running, or (src ok & dst running) | blue, marching dashes |
| `queued` | src ok, dst still idle | grey, slow drift |
| `stalled` | src `stale` | amber, gentle breath |
| `error` | either endpoint errored | red, tight dashes |
| `ok` | src ok & dst ok | green, solid |
| `idle` | anything else | faint, solid |

Note the spelling: a node's status is **`stale`**, but the edge flow it derives
is **`stalled`**. Because flow is derived, you never store or diff it — keep node
`status` live (via `statusById`) and every edge restyles itself. That single
source of truth is what makes the [live runner](/pipeline-view/pipeline-graph.md#live-status--a-runnable-pipeline)
cheap.

---

**Next:** [Pipeline Graph JSON](/pipeline-view/pipeline-graph-json.md) is the full
data-model reference · [Architecture & Roadmap](/pipeline-view/architecture.md)
covers the internals and what's planned.

---

Source: https://uikit.dreamlake.ai/pipeline-view/pipeline-graph-json

# Pipeline Graph JSON

For the same shapes shown **next to what they draw**, see
[Anatomy](/pipeline-view/anatomy.md). This page is the prose reference.

`PipelineGraph` renders one JSON object: a **traced pipeline**. The Python
tracer (`dl_trace`) is the source of truth — it reads a `@dl.pipeline` function
and emits this shape statically (no import, no execution), so placeholder
bodies trace exactly like real ones. The TypeScript types
(`PipelineGraphData`, `GraphNode`, `GraphEdge`) mirror it 1:1 and ship from
`@dreamlake/uikit`.

The shape mirrors the DreamLake Studio design prototype's pipeline data model.
Its guiding principle: **the graph is a derived view of code, and an edge's
runtime look is a derived view of node status.** Nothing visual is hand-authored
or stored twice.

## The whole object

```jsonc
{
  "id": "image_object_annotation",     // stable id (the pipeline function name)
  "title": "image_object_annotation",
  "subtitle": "Annotate the objects in this image.", // docstring
  "nodeCount": 5,
  "code": "\"\"\"…\"\"\"\nimport dreamlake as dl\n…",  // the whole pipeline.py (canonical source)
  "nodes": {
    "load_images":    { /* GraphNode — a kind:"source" udf */ },
    "detect_objects": { /* … */ },
    "review_boxes":   { /* … */ },
    "save_dataset":   { /* a kind:"sink" udf */ },
    "rework":         { /* a kind:"sink" udf */ }
  },
  "edges": [
    { "from": "load_images",    "fromPort": "out", "to": "detect_objects", "toPort": "images", "kind": "data" },
    { "from": "detect_objects", "fromPort": "out", "to": "review_boxes",   "toPort": "labels", "kind": "data" },
    { "from": "detect_objects", "fromPort": "out", "to": "save_dataset",   "toPort": "rows",   "kind": "data" },
    { "from": "review_boxes",   "fromPort": "out", "to": "save_dataset",   "toPort": "rows",   "kind": "mask" }
    // …
  ]
}
```

`nodes` is keyed by node **id** (not an array) so a status overlay or a
selection can address a node in O(1). `code` is the canonical pipeline source —
the graph is derived from it, so it's kept alongside for the source inspector.

## A node

```jsonc
{
  // —— static (the tracer always fills these) ——
  "id": "detect_objects",
  "title": "detect_objects",
  "kind": "transform",                 // source | transform | model | filter | merge | sink | review
  "inputs": ["images"],                // input ports  = the udf's parameters
  "outputs": ["out"],                  // ONE output port (the result table); [] for a sink
  "columns": ["boxes", "classes", "confidence"],  // the result's schema (return columns)
  "code": "@ls.udf\ndef detect_objects(...): ...",  // this stage's own source
  "config": {},                        // decorator kwargs, e.g. { "kind": "review" }
  "pos": { "x": 380, "y": 60 },        // auto-laid-out (longest-path layering)
  "status": "idle",                    // idle | running | ok | error | stale

  // —— runtime (optional; the tracer omits them, a runner fills them) ——
  "progress": 0.62,                    // 0..1 while running
  "duration": 4.2,                     // seconds, last run
  "rows": 612,                         // output row count
  "output": { /* preview payload */ }
}
```

Two groups of fields:

- **Static** — everything derivable from the code alone. The tracer emits these
  and sets every `status` to `idle`.
- **Runtime** — optional, filled while (or after) the pipeline runs. The card
  renders them when present (progress %, duration) and ignores them when absent.

`kind` tints the card's kind dot and is declared by the udf's decorator
(`@ls.udf(kind="source")`, `kind="sink"`, `kind="review"`) or inferred. There
are **no synthetic nodes** — the `source` and `sink` nodes are real udfs the
pipeline calls (a `kind="source"` loader and `kind="sink"` writers), so they
have real `code`. A sink udf just has no output port (nothing to return).

**Ports vs columns.** `inputs` are ports — one per parameter. `outputs` is a
single port (`["out"]`) because a UDF returns **one** table; passing it
downstream passes the whole table. The return column names live in `columns`
(the result's schema), not as separate ports. The card subline shows
`inputs.length → outputs.length` (e.g. `2 → 1`).

### The output artifact

`output` is a runtime field: a **discriminated union** on `kind` describing what
the stage produced last run, for a preview pane. The tracer never emits it; a
runner fills it, and the (planned) node inspector renders it — see
[Architecture & Roadmap](/pipeline-view/architecture.md#roadmap).

```ts
type NodeOutput =
  | { kind: 'idle' }                                        // never run
  | { kind: 'pending'; browsable?: 'frame' }               // running now
  | { kind: 'stale'; upstream: string }                    // an upstream changed
  | { kind: 'table'; schema: string[]; preview: unknown[][] }   // tabular preview
  | { kind: 'image-grid'; count: number; sampleSize: number }   // frame thumbnails
  | { kind: 'text-grid'; count: number; browsable?: 'clip' | 'episode';
      preview: { ts?: number; ep?: number; text: string }[] }   // label previews
```

The three "empty" kinds (`idle` / `pending` / `stale`) drive placeholder
messaging; `table` / `image-grid` / `text-grid` carry an actual preview payload.
This union mirrors the design prototype's `PipeOutputTab`.

## An edge

```jsonc
{ "from": "detect_objects", "fromPort": "out", "to": "to_dataset", "toPort": "in", "kind": "data" }
```

A port-to-port connection plus one tag, `kind`:

- **`data`** — the source's result flows into the target (rendered solid).
- **`mask`** — the source only *gates/filters* the target: a review veto, or a
  confidence/consensus mask used as a boolean selector (rendered dashed +
  fainter in the settled states). This is how the σ-algebra "which rows survive"
  edges read as gates rather than data flow, without adding filter nodes.

There is still no colour, width, or animation stored — those are derived from
status (below). `kind` is the one structural tag, decided by the tracer.

### Why edges store no style

An edge's runtime look — its *flow* — is **derived** from the `status` of its
two endpoint nodes, at render time:

```ts
edgeFlow(src, dst): 'running' | 'queued' | 'stalled' | 'error' | 'ok' | 'idle'
```

| Flow | Derived when |
| --- | --- |
| `running` | src running, or (src ok & dst running) |
| `queued` | src ok, dst still idle |
| `stalled` | src stale |
| `error` | either endpoint errored |
| `ok` | src ok & dst ok |
| `idle` | anything else |

So there is exactly one source of truth for runtime state — `node.status` — and
the edges follow. This is what makes live updates cheap: you never diff or
restyle edges, you just push new node statuses.

## Live updates — the status overlay

The static graph is produced once (at trace time) and rarely changes — it only
changes when the `.py` changes. Runtime state is a **separate, lightweight
overlay**, keyed by node id:

```ts
type StatusOverlay = Record<
  string,
  { status?: NodeStatus; progress?: number | null; duration?: number | null; rows?: number | null }
>
```

Pass it as `statusById`; the component merges it onto the nodes and re-derives
every edge's flow. A remote runner streams these (over SSE / WebSocket) as jobs
progress:

```tsx

```

Structure stays static; status streams live; edges animate — with no re-tracing.

## Producing it

```bash
python -m dl_trace pipelines/image_object_annotation.py --pretty   # -> stdout
python -m dl_trace pipelines/image_object_annotation.py -o graph.json
```

The tracer **trusts the pipeline**: every function it calls must be a decorated
udf. Calling a `@ls.udf` makes a node with an edge from each argument's producer;
the pipeline gets its input from a `kind="source"` udf and writes out via
`kind="sink"` udfs (framework helpers like `to_dataset` / `requeue` are wrapped
inside those). Method calls, subscripts, and boolean-mask operators pass data
through without adding nodes — so consensus / rework mask algebra doesn't clutter
the graph. An **undecorated call raises**. See the
[Pipeline Graph](/pipeline-view/pipeline-graph.md) component for rendering.

---

Source: https://uikit.dreamlake.ai/pipeline-view/architecture

# Architecture & Roadmap

How the component is put together, why it's shaped that way, and where it's
going. If you only render graphs you don't need this — start at
[Pipeline Graph](/pipeline-view/pipeline-graph.md).

## Design principles

Four rules the whole component follows:

1. **Purely presentational.** `PipelineGraph` fetches nothing and traces
   nothing. Input is JSON (from the `dl_trace` service) plus an optional live
   status overlay; output is pixels. This keeps it trivially embeddable and
   testable.
2. **The graph is a derived view of code.** Structure comes from the tracer, not
   from the UI. The component never mutates the graph — node drags are a local
   position overlay, not edits to the data.
3. **Runtime look is derived from one source of truth.** An edge stores no
   colour/width/animation; its *flow* is a pure function of its endpoints'
   `status`. Push new statuses and every edge restyles itself — no edge diffing.
4. **Selection is controlled or uncontrolled.** Pass `selectedNodeId` +
   `onSelectNode` to own it (and sync the graph with `PipelineSource`), or omit
   both and the component tracks selection internally.

## The file split

The component is five small modules, each with one job:

| Module | Responsibility |
| --- | --- |
| `types.ts` | The data model — `PipelineGraphData`, `GraphNode`, `GraphEdge`, `NodeStatus`, `StatusOverlay`. Mirrors the tracer's JSON 1:1. |
| `flow.ts` | The **visual language** — `kindColor`, `STATUS`, `FLOW`, and the derivations `edgeFlow(src, dst)` + `portPos` / `portAlong`. Colours are uikit tone tokens, so light/dark is automatic. |
| `edge-path.ts` | Pure geometry — `buildEdgePath` routes a rounded orthogonal (Manhattan) edge that **detours around** intervening node boxes, falling back to a curve when endpoints are near-colinear. |
| `PipelineGraph.tsx` | The canvas — pan/zoom, node drag, selection, and the SVG edge + card render. |
| `PipelineSource.tsx` | The paired read-only source inspector (pipeline `.py` ↔ selected node source). |

`flow.ts` is the shared vocabulary: `edgeFlow` and `FLOW` are **exported** from
`@dreamlake/uikit`, so a legend, a docs board, or a custom overlay can reuse the
exact same rules the canvas does — no reimplementation, no drift.

## The render pipeline

One render of `PipelineGraph`, end to end:

1. **Merge overlays.** Each node is combined with its `statusById` entry (live
   `status` / `progress` / `duration`) and any local drag `posOverride`. The
   static graph is never mutated.
2. **Size the world.** Node positions set the scroll bounds; one
   `translate()+scale()` transform on the content layer drives the nodes and the
   SVG edge layer together (so they never drift apart under pan/zoom).
3. **Draw edges.** For each edge: `portPos` resolves the `out` and `in` port
   coordinates → `buildEdgePath` routes around obstacles → `edgeFlow(src, dst)`
   picks a flow → `FLOW[flow]` gives colour/width/dash/anim. A `mask` edge stays
   dashed in the settled states so a gate always reads as a gate; a selected
   edge switches to the single accent colour.
4. **Draw nodes.** Absolutely-positioned cards, tinted by `status`, with a kind
   dot, the `inputs→outputs` meta, a status footer (pulsing when `running`), and
   port dots on the edges.
5. **Legend.** Bottom-right, the flow states — rendered from the same `FLOW`.

**Interaction:** background drag pans; ⌘/ctrl-wheel or pinch zooms about the
cursor; plain wheel / two-finger drag pans; a node drag writes to `posOverride`
(cleared when `graph.id` changes); a click without a drag toggles selection.

## What it deliberately leaves out

Faithful to the design prototype's *look*, but intentionally simpler than its
full canvas — these are conscious omissions, not bugs:

- **No per-edge label chips.** The prototype floats a draggable flow-label chip
  at each edge's midpoint; here the legend carries that vocabulary instead.
- **No draggable edge bends, no auto-fit, no vertical layout mode.** Positions
  come from the tracer's layout; the user pans/zooms/drags nodes.
- **No vim marks** (the `a`–`z` jump labels). Arrow/`hjkl` selection navigation
  *is* supported — see Current stage.
- **No node inspector yet** — `PipelineSource` shows source only. That's the
  headline roadmap item below.

## Current stage

Shipping today:

- ✅ Pure, theme-aware renderer — dotted canvas, status-tinted cards, obstacle-
  routed edges, pan/zoom/drag, controlled or uncontrolled selection.
- ✅ **Keyboard navigation** (focus-scoped) — ↑/↓ (or k/j) step the selection in
  topological order, ←/→ (or h/l) hop to the upstream/downstream neighbour, Esc
  clears; the selected node pans into view.
- ✅ **Connector tags** (`data` / `mask`) and **connector states** (the six
  derived flows), catalogued in [Anatomy](/pipeline-view/anatomy.md).
- ✅ Live animation from a `statusById` overlay — structure stays static, status
  streams in, edges re-derive their flow.
- ✅ `PipelineSource` — the pipeline `.py` ↔ selected-node source inspector.

## Roadmap

### Selected-node inspector — status + output (next)

Today `PipelineSource` shows **source** only. The next step is to grow it (or a
sibling panel) into the design prototype's three-tab inspector for the selected
node:

- **Details** — a status row (status label + colour, live `progress`,
  `duration`, `rows`, and a **Run** action), plus the node's resolved
  inputs/outputs and its `config`.
- **Code** — what `PipelineSource` shows now.
- **Output** — render the node's [`output` artifact](/pipeline-view/pipeline-graph-json.md#the-output-artifact):
  a `table` preview (schema + rows), an `image-grid` of frame thumbnails, a
  `text-grid` of label previews, or an empty/stale/pending placeholder.

This makes the graph a live console: click a running node and watch its rows and
preview fill in. The `output` union is already specified in the
[JSON reference](/pipeline-view/pipeline-graph-json.md#the-output-artifact) so the
data contract is settled ahead of the UI.

### Further out

- **Edge inspector** — click an edge for its flow, throughput (`rows` /
  `duration`), and, on `error`, the failing stage's traceback.
- **Edge midpoint labels**, draggable bends, and label collision avoidance
  (parity with the prototype canvas).
- **Auto-fit** on mount/resize and a **vertical** layout direction.
- **Job / fleet views** — the running-jobs and compute-fleet panels that pair
  with the graph in Studio.

---

**Back to:** [Pipeline Graph](/pipeline-view/pipeline-graph.md) ·
[Anatomy](/pipeline-view/anatomy.md) ·
[Pipeline Graph JSON](/pipeline-view/pipeline-graph-json.md).

---

Source: https://uikit.dreamlake.ai/components/use-is-mobile

# useIsMobile

A hook that returns `true` when the viewport is narrower than `768px`. It
updates as the viewport changes and is SSR-safe (returns `false` until mounted,
so the server and first client render agree).

```tsx

function Nav() {
  const isMobile = useIsMobile()
  return isMobile ?  : 
}
```

## Returns

| Type | Description |
| --- | --- |
| `boolean` | `true` when `window.innerWidth < 768`. |

---

Source: https://uikit.dreamlake.ai/components/label

# Label

A text label for form controls. Render a native `<label htmlFor="…">` (or wrap
the control) so clicks focus the input. `size` picks the type scale; `hint` also
mutes the color for helper text.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `'xs' \| 'sm' \| 'lg' \| 'hint'` | `'sm'` | Type scale (`hint` is muted). |
| `className` | `string` | — | Extra classes. |

All native `<label>` attributes (`htmlFor`, …) are forwarded.

---

Source: https://uikit.dreamlake.ai/components/toggle

# Toggle

A button with a pressed / not-pressed state — for inline formatting and similar
on/off affordances. Controlled (`pressed` + `onPressedChange`) or uncontrolled
(`defaultPressed`).

## Sizes

`size` scales the padding, text and icon together — `sm`, `base` (default), `lg`.

## ToggleButtons (segmented)

`ToggleButtons` is a single-select segmented control: a sliding highlight
animates to the active `ToggleButton`. Drive it with `value` + `onValueChange`.

## Props

### `Toggle`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `pressed` | `boolean` | — | Controlled state. Omit for uncontrolled. |
| `defaultPressed` | `boolean` | `false` | Initial state when uncontrolled. |
| `onPressedChange` | `(pressed: boolean) => void` | — | Fired on toggle. |
| `variant` | `'primary' \| 'secondary'` | `'primary'` | Active fill style. |
| `size` | `'sm' \| 'base' \| 'lg'` | `'base'` | Padding/text scale. |

### `ToggleButtons` / `ToggleButton`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | — | Selected value (`ToggleButtons`). |
| `onValueChange` | `(value: string) => void` | — | Fired on select. |
| `variant` | `'primary' \| 'secondary' \| 'ghost'` | `'primary'` | Highlight style. |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Item size. |
| `padding` | `boolean` | `true` | Frame padding around the segments. Set `false` for a tighter, edge-to-edge group. |
| `value` (item) | `string` | — | This button's value. |
| `icon` (item) | `boolean` | `false` | Square icon-only sizing. |
| `asChild` (item) | `boolean` | `false` | Render the single child instead of a `<button>`, forwarding the ref, selected state, and click. |

---

Source: https://uikit.dreamlake.ai/components/toolbar

# Toolbar

A horizontal bar for grouped actions. Wrap related buttons in `ToolbarGroup` and
divide groups with `ToolbarSeparator`. The `floating` variant adds a soft shadow
for overlay toolbars.

## Floating studio toolbar

A faithful rebuild of the Vuer studio's floating top toolbar: a segmented
`ToggleButtons` for the select modes, a standalone `Toggle` for the
world/local coordinate mode, a ghost button for the scene editor, a separator,
then the Add action. `variant="floating"` adds the overlay shadow for a bar
that floats over the 3D canvas.

## Props

### `Toolbar`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `'default' \| 'floating'` | `'default'` | `floating` adds a shadow. |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Only `lg` enlarges the padding and corner radius; `sm` and `md` are identical. |
| `className` | `string` | — | Extra classes. |

`ToolbarGroup` and `ToolbarSeparator` accept `className` and native `<div>`
attributes.

---

Source: https://uikit.dreamlake.ai/components/modal

# Modal

A general-purpose modal. Compose `ModalTrigger` + `ModalContent` (with
`ModalHeader`, `ModalTitle`, `ModalDescription`, `ModalFooter`). It closes on Esc
and backdrop click and shows a close button by default.

For a confirmation prompt that must **not** dismiss on outside click, use
[Alert Dialog](/components/alert-dialog.md) instead. For a fully controlled,
trigger-less panel see [Dialog](/components/dialog.md).

## Props

### `Modal`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | — | Controlled open state. Omit for uncontrolled. |
| `defaultOpen` | `boolean` | `false` | Initial state when uncontrolled. |
| `onOpenChange` | `(open: boolean) => void` | — | Fired when open state changes. |

### `ModalContent`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `showCloseButton` | `boolean` | `true` | Show the corner close button. |

`ModalTrigger` and `ModalClose` accept `asChild` to render your own element.

---

Source: https://uikit.dreamlake.ai/components/form-layout

# Form Layout

A small wrapper that pairs a label with a control. `orientation="label-top"
` (default) stacks them; `label-left` puts the label in a column beside the
control. Pass exactly two children — `[label, control]`.

## Alignment

With `label-left`, `align` controls how the label sits against a control that's
taller than one line.

## Any control, and `asChild`

The control can be anything — input, switch, number field. With `asChild` the
layout classes land on the single child element instead of a wrapper `<div>`.
Make that child a `<label>` if you want clicking it to focus the control.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `orientation` | `'label-top' \| 'label-left'` | `'label-top'` | Stacked vs side-by-side. |
| `align` | `'start' \| 'center' \| 'end' \| 'baseline'` | `'center'` | Cross-axis alignment. |
| `asChild` | `boolean` | `false` | Render the single child instead of a wrapper. |
| `className` | `string` | — | Extra classes. |

---

Source: https://uikit.dreamlake.ai/components/input

# Input

A styled text field. `InputRoot` (also exported as `Input`) is the container +
input; drop `InputSlot`s inside for icons, prefixes, or suffixes. Clicking a slot
focuses the input and places the caret at the matching end.

## Props

### `InputRoot`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Height/text scale. |
| `state` | `'default' \| 'error'` | `'default'` | Error tints the surface. |
| `side` | `'left' \| 'right' \| 'center'` | — | Text alignment of the input. |
| `inputClassName` | `string` | — | Classes on the inner `<input>`. |

All native `<input>` attributes (`placeholder`, `value`, `onChange`, `disabled`,
…) are forwarded.

### `InputSlot`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `side` | `'left' \| 'right'` | `'left'` | Which end of the input the slot sits at. |

Native `<div>` attributes are forwarded.

---

Source: https://uikit.dreamlake.ai/components/mouse-cursor

# Mouse Cursor Icons

Two small cursor-pointer glyphs — `MouseCursorIcon` (outline) and
`MouseCursorAltIcon` (filled). They render at 16×16, inherit `currentColor`, and
take an optional `strokeWidth`. Used for collaborator/presence cursors.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `strokeWidth` | `number` | `2.25` | Stroke width of the glyph. |

---

Source: https://uikit.dreamlake.ai/components/tooltip

# Tooltip

A small label shown on hover or keyboard focus. Compose `TooltipTrigger`
(use `asChild` to wrap your own control) + `TooltipContent`. Positioning is
anchored to the trigger and flips or shifts to stay within the viewport. Wrap a
subtree in `TooltipProvider` to share an open delay.

## Props

### `Tooltip`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'top'` | Preferred side. |
| `sideOffset` | `number` | `6` | Gap from the trigger (px). |
| `delayDuration` | `number` | `200` | Hover open delay (ms). |
| `open` / `defaultOpen` / `onOpenChange` | — | — | Controlled / uncontrolled open state. |

`TooltipTrigger` accepts `asChild`. `TooltipContent` accepts a `side` that
overrides the `Tooltip`'s placement. `TooltipProvider` takes `delayDuration`.

---

Source: https://uikit.dreamlake.ai/components/popover

# Popover

A floating panel opened by clicking its trigger — for quick settings, filters,
or detail cards. Compose `PopoverTrigger` + `PopoverContent`, with an optional
`PopoverClose`. The panel anchors to its trigger and flips or shifts to stay
within the viewport, moves focus into itself while open, and dismisses on
outside-click or Esc.

## Props

### `Popover`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'bottom'` | Preferred side. |
| `align` | `'start' \| 'center' \| 'end'` | `'center'` | Alignment along the side. |
| `sideOffset` | `number` | `6` | Gap from the trigger (px). |
| `open` / `defaultOpen` / `onOpenChange` | — | — | Controlled / uncontrolled open state. |

`PopoverTrigger` and `PopoverClose` accept `asChild`.

---

Source: https://uikit.dreamlake.ai/components/dropdown-menu

# Dropdown Menu

A menu of actions opened from a trigger. Compose `DropdownMenuTrigger` +
`DropdownMenuContent` with `DropdownMenuItem`, `DropdownMenuLabel`,
`DropdownMenuSeparator`, radio items (`DropdownMenuRadioGroup` /
`DropdownMenuRadioItem`), and nested submenus (`DropdownMenuSub` /
`DropdownMenuSubTrigger` / `DropdownMenuSubContent`). The menu anchors to its
trigger and flips or shifts to stay within the viewport, supports keyboard list
navigation, and dismisses on outside-click or Esc; submenus open on hover.

## Props

### `DropdownMenu`

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'bottom'` | Preferred side. |
| `align` | `'start' \| 'center' \| 'end'` | `'start'` | Alignment along the side. |
| `open` / `defaultOpen` / `onOpenChange` | — | — | Controlled / uncontrolled open state. |

### Items

`DropdownMenuItem` takes `onSelect` (fired on activation; the menu then closes),
`disabled`, and `asChild` (render through to a single child element instead of a
`<div>`). `DropdownMenuRadioGroup` takes `value` + `onValueChange`;
`DropdownMenuRadioItem` takes `value`. `DropdownMenuTrigger` accepts `asChild`.
`DropdownMenuShortcut` renders a right-aligned keyboard hint (e.g. ⌘C) inside an
item.

---

Source: https://uikit.dreamlake.ai/components/theme

# Theme

The theme system persists a base theme (`light` / `dark` / `system`) plus an
optional `liquid` flag, resolves the active theme, and reflects it on
`html[data-theme]` — the attribute the kit's tokens key off.

> Live toggles drive `html[data-theme]` for the whole page, so this page documents
> them with code rather than an embedded demo (which would fight the docs site's
> own theme switch).

## Setup

Wrap your app once in `ThemeProvider`, and import the kit's stylesheet at the
root so the tokens are present:

```tsx

<header>
  
  
</header>
```

## `useTheme`

Read or drive the theme from anywhere under the provider:

```tsx

function Example() {
  const { baseTheme, setBaseTheme, isLiquid, toggleLiquid, computedTheme } = useTheme()
  return <button onClick={() => setBaseTheme('dark')}>Now: {computedTheme}</button>
}
```

| Member | Type | Description |
| --- | --- | --- |
| `baseTheme` | `'light' \| 'dark' \| 'system'` | The stored base theme. |
| `setBaseTheme` | `(t: BaseTheme) => void` | Set + persist the base theme. |
| `isLiquid` | `boolean` | Liquid flag. |
| `toggleLiquid` | `() => void` | Flip the liquid flag. |
| `computedTheme` | `'light' \| 'dark' \| 'liquid-light' \| 'liquid-dark'` | Resolved active theme. |
| `resolvedTheme` | `'light' \| 'dark' \| 'liquid-light' \| 'liquid-dark'` | Alias of `computedTheme`. |
| `systemTheme` | `'light' \| 'dark' \| undefined` | OS preference (when `system`). |
| `storageKey` | `string` | The localStorage key prefix in use. |

### `ThemeProvider` props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `defaultBaseTheme` | `BaseTheme` | `'system'` (or `'light'` if system disabled) | Initial base theme. |
| `defaultIsLiquid` | `boolean` | `false` | Initial liquid flag. |
| `enableSystem` | `boolean` | `true` | Track the OS color-scheme preference. |
| `storageKey` | `string` | `'dl-theme'` | localStorage key prefix. |

---

Source: https://uikit.dreamlake.ai/components/tree-view

# Tree View

A hierarchical tree for scene graphs, file trees, and outlines. You supply a
flat array of `TreeDataItem` nodes (each pointing at its `parentId`); the
`useTreeState` hook derives the visible rows — with indent and guideline
metadata — and manages expand-collapse state. Icons and label rendering are
left to the caller. For trees with thousands of nodes, swap `TreeView` for
`VirtualTreeView` — it shares the same props plus a `height`.

## Basic

Pass the `visibleData` from `useTreeState` to `data`, and wire `expandedItems`,
`onToggleItem`, and `hasDescendants` so collapsible folders get a chevron.
`getIcon` returns whatever node icon you want, with the expanded flag for
folder-open states.

## Selectable

Set `isSelectable` and control selection with `selectedItemIds` /
`onSelectionChange`. With the default `selectionMode="multi"`, Cmd/Ctrl-click
toggles individual rows and Shift-click selects a range; selecting a parent
implicitly covers its descendants.

## Searchable

`TreeSearchBar` is a controlled input with case-sensitive and regex toggles.
Feed its state into `useTreeSearch`, which returns the `filteredData` (matches
plus their ancestor paths) and a `renderLabel` that highlights the matched
substring. Pass `filteredData` back through `useTreeState` and hand
`renderLabel` to the `TreeView`.

## Quiet rows

Three opt-outs tune the tree for dense sidebars (the Dream Studio repos list
uses all three). `chevronPosition="trailing"` moves a smaller, dimmed expand
chevron to sit right after the label text — collapsed it points left, toward
the label it reveals under. `hoverSubtree={false}` limits the hover wash to
the row under the cursor instead of highlighting the whole subtree as one
block. `loneSelectionStyle="ring"` draws a lone selected row with the same
accent ring group selections use, leaving the row background transparent
instead of the solid fill. A fourth, `groupSelection="row"`, changes what
selecting a group MEANS: only the clicked row is marked — descendants are
untouched, and a selected group renders like any lone selection instead of
a ring around its whole subtree.

## Props

### `TreeView` / `VirtualTreeView`

| Prop                 | Type                                           | Default       | Description                                                                                      |
| -------------------- | ---------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------ |
| `data`               | `TreeDataItemWithMeta[]`                    | —             | Flattened rows with metadata — pass `visibleData` from `useTreeState`.                           |
| `getIcon`            | `(item: T, expanded?: boolean) => ReactNode`   | —             | Icon for each node. Receives the expanded flag for folder-open states.                           |
| `expandedItems`      | `Set<string>`                                  | —             | IDs of expanded collapsible nodes.                                                               |
| `onToggleItem`       | `(id: string) => void`                         | —             | Called when a chevron is clicked.                                                                |
| `onItemHover`        | `(id: string \| null) => void`                 | —             | Called on row mouse enter / leave.                                                               |
| `hoveredId`          | `string \| null`                               | —             | Controlled hovered row id.                                                                       |
| `isSelectable`       | `boolean`                                      | `false`       | Enables row selection.                                                                           |
| `selectedItemIds`    | `Set<string>`                                  | —             | Controlled set of selected node ids.                                                             |
| `onSelectionChange`  | `(ids: Set<string>) => void`                   | —             | Called when the selection changes.                                                               |
| `selectionMode`      | `'single' \| 'multi'`                          | `'multi'`     | `multi` enables Cmd/Ctrl-click toggle and Shift-click range.                                     |
| `hideExpand`         | `boolean`                                      | `false`       | Hide expand chevrons entirely.                                                                   |
| `hasDescendants`     | `(id: string) => boolean`                      | `() => false` | Whether a node has children — pass the helper from `useTreeState`.                               |
| `renderLabel`        | `(label: string, itemId: string) => ReactNode` | identity      | Custom label rendering — pass `renderLabel` from `useTreeSearch` for highlights.                 |
| `renderContextMenu`  | `(item: T) => ReactNode`                       | —             | Right-click menu content for a row.                                                              |
| `hoverSubtree`       | `boolean`                                      | `true`        | Hovering a group also highlights its whole subtree as one block. Set `false` for row-only hover. |
| `loneSelectionStyle` | `'fill' \| 'ring'`                             | `'fill'`      | Lone selected row: solid fill, or the accent ring group selections use (transparent background). |
| `chevronPosition`    | `'leading' \| 'trailing'`                      | `'leading'`   | `trailing` renders a smaller, dimmed chevron after the label text; collapsed points left.        |
| `groupSelection`     | `'subtree' \| 'row'`                           | `'subtree'`   | `'row'` = selecting a group marks only that row; descendants stay unmarked.                      |
| `className`          | `string`                                       | —             | Extra classes on the container.                                                                  |
| `height`             | `number \| string`                             | `'100%'`      | **`VirtualTreeView` only** — container height for virtualization.                                |
| `overscan`           | `number`                                       | `5`           | **`VirtualTreeView` only** — extra rows rendered outside the viewport.                           |

### `TreeDataItem`

| Field           | Type             | Description                                    |
| --------------- | ---------------- | ---------------------------------------------- |
| `id`            | `string`         | Unique node identifier.                        |
| `parentId`      | `string \| null` | Parent id, or `null` for roots.                |
| `label`         | `string`         | Display text (also the search target).         |
| `isCollapsible` | `boolean`        | Marks a node as an expandable folder.          |
| `actions`       | `ReactNode`      | Trailing action content shown on the row.      |
| `disable`       | `boolean`        | Dim and disable interaction for the row.       |
| `selectable`    | `boolean`        | Set `false` to exclude the row from selection. |

### `TreeSearchBar`

| Prop                 | Type                                                       | Description                                                |
| -------------------- | ---------------------------------------------------------- | ---------------------------------------------------------- |
| `searchQuery`        | `string`                                                   | Current query text.                                        |
| `setSearchQuery`     | `(query: string) => void`                                  | Updates the query.                                         |
| `isCaseSensitive`    | `boolean`                                                  | Case-sensitive toggle state.                               |
| `setIsCaseSensitive` | `(value: boolean \| ((prev: boolean) => boolean)) => void` | Toggles case sensitivity.                                  |
| `isRegex`            | `boolean`                                                  | Regex toggle state.                                        |
| `setIsRegex`         | `(value: boolean \| ((prev: boolean) => boolean)) => void` | Toggles regex mode.                                        |
| `isRegexValid`       | `boolean`                                                  | Whether the current regex compiles — from `useTreeSearch`. |
| `searchResultsCount` | `number`                                                   | Number of direct matches — from `useTreeSearch`.           |
| `className`          | `string`                                                   | Extra classes on the container.                            |

### `useTreeState({ data, defaultExpanded?, expandedItems?, onToggleItem? })`

| Returns          | Type                        | Description                                                                      |
| ---------------- | --------------------------- | -------------------------------------------------------------------------------- |
| `visibleData`    | `TreeDataItemWithMeta[]` | Flattened, metadata-tagged rows with collapsed subtrees hidden — pass to `data`. |
| `dataWithMeta`   | `TreeDataItemWithMeta[]` | All rows with metadata, ignoring collapse state.                                 |
| `expandedItems`  | `Set<string>`               | Currently expanded node ids.                                                     |
| `toggleItem`     | `(id: string) => void`      | Toggle one node's expanded state.                                                |
| `expandAll`      | `() => void`                | Expand every collapsible node.                                                   |
| `collapseAll`    | `() => void`                | Collapse every node.                                                             |
| `hasDescendants` | `(id: string) => boolean`   | Whether a node has children.                                                     |

### `useTreeSearch({ data, searchQuery, isCaseSensitive?, isRegex? })`

| Returns              | Type                                           | Description                                                             |
| -------------------- | ---------------------------------------------- | ----------------------------------------------------------------------- |
| `filteredData`       | `T[]`                                          | Matching nodes plus their ancestor paths — feed into `useTreeState`.    |
| `searchResultsCount` | `number`                                       | Count of direct label matches.                                          |
| `isRegexValid`       | `boolean`                                      | `false` when `isRegex` is on and the query is not a valid pattern.      |
| `renderLabel`        | `(label: string, itemId: string) => ReactNode` | Label renderer that highlights matched substrings — pass to `TreeView`. |
| `hasActiveSearch`    | `boolean`                                      | Whether a non-empty query is active.                                    |

---

Source: https://uikit.dreamlake.ai/components/context-menu

# Context Menu

A right-click menu built by composition. Wrap a `ContextMenuTrigger` area and a
`ContextMenuContent` list inside `ContextMenu`. The menu anchors to the cursor
position, closes on dismiss, and supports full keyboard navigation. Item
selection is handled per-item via `onSelect`.

## Basic

Right-click the area below to open the menu. Items run their `onSelect`
callback and close the menu; a `ContextMenuSeparator` divides routine actions
from the destructive `danger` item, and `disabled` items are skipped by
keyboard navigation.

## Labels, groups & shortcuts

Use `ContextMenuLabel` for section captions, `ContextMenuGroup` to cluster
related items, and `ContextMenuShortcut` to right-align a keyboard hint inside
an item.

## Props

### ContextMenuItem

| Prop       | Type                         | Default     | Description                                                           |
| ---------- | ---------------------------- | ----------- | --------------------------------------------------------------------- |
| `onSelect` | `() => void`                 | —           | Called when the item is chosen; the menu closes afterward.            |
| `danger`   | `boolean`                    | `false`     | Renders the item in the danger (destructive) tone.                    |
| `variant`  | `'default' \| 'destructive'` | `'default'` | `'destructive'` renders the item in the danger tone.                  |
| `disabled` | `boolean`                    | `false`     | Dims the item and removes it from pointer and keyboard interaction.   |
| `asChild`  | `boolean`                    | `false`     | Render through to a single child element instead of a wrapping `div`. |

### Sub-components

| Component              | Description                                                                          |
| ---------------------- | ------------------------------------------------------------------------------------ |
| `ContextMenu`          | Root provider. Accepts `onOpenChange` and composes the trigger + content.            |
| `ContextMenuTrigger`   | The area whose right-click opens the menu. Pass `asChild` to use your own element.   |
| `ContextMenuContent`   | The floating menu panel that holds the items.                                        |
| `ContextMenuItem`      | An actionable row. See the props table above.                                        |
| `ContextMenuLabel`     | Uppercase section caption; non-interactive.                                          |
| `ContextMenuGroup`     | Wraps related items for spacing and `role="group"` semantics.                        |
| `ContextMenuSeparator` | A horizontal divider between sections.                                               |
| `ContextMenuShortcut`  | Right-aligned keyboard-hint text rendered inside an item.                            |
| `ContextMenuPortal`    | No-op wrapper; the content portals itself, so wrapping it is optional. |

---

Source: https://uikit.dreamlake.ai/components/dial

# Dial

The Dial system turns a flat array of control descriptors — the **schemas** —
into a rendered panel of typed inputs. Each schema has a `name` and a `dtype`;
the `dtype` decides which input is drawn (a slider, a color picker, a vector3
field, a button, and so on). You write the data shape, not the widgets.

Two pieces work together:

- **`DialProvider`** owns the values. It holds state, exposes `getValue` /
  `setValue` through context, and supports both controlled and uncontrolled
  modes. Inputs read and write through it — they never talk to each other
  directly.
- **`DialPanel`** reads the same `schemas` and renders the matching inputs,
  optionally arranging them into groups.

## Controlled value flow

In **controlled** mode you pass `values` and an `onValueChange` callback to
`DialProvider`. Every edit fires `onValueChange(name, value)` and you store the
result yourself, feeding it back through `values` — exactly like a controlled
`<input>`, but for the whole panel. Omit `values` to run the panel
**uncontrolled**, where the provider keeps its own internal state seeded from
each schema's `value` (or `initialValues`).

The example below covers several `dtype`s and mirrors the live values as JSON.

## Grouping

Tag any schema with `grouping` to file it under a section header. Pass a
matching `groups` config to `DialPanel` to control each section's layout — grid
column count, flex wrapping, and so on. A group named `transform` always sorts
first; the rest follow alphabetically.

## DialProvider props

| Prop            | Type                                     | Default | Description                                                                                                         |
| --------------- | ---------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
| `schemas`       | `DialSchema[]`                           | —       | The control descriptors. Used to seed defaults and supply context to the inputs.                                    |
| `values`        | `Record<string, unknown>`                | —       | Controlled value map keyed by schema `name`. Passing a non-empty object switches the provider into controlled mode. |
| `initialValues` | `Record<string, unknown>`                | `{}`    | Initial values for uncontrolled mode; falls back to each schema's `value`.                                          |
| `onValueChange` | `(name: string, value: unknown) => void` | —       | Called on every edit. Required to persist changes in controlled mode.                                               |
| `children`      | `ReactNode`                              | —       | Typically a `DialPanel`, but any consumer of the Dial context works.                                                |

## DialPanel props

| Prop          | Type             | Default | Description                                                                                           |
| ------------- | ---------------- | ------- | ----------------------------------------------------------------------------------------------------- |
| `schemas`     | `DialSchema[]`   | —       | The controls to render. Usually the same array passed to `DialProvider`.                              |
| `groups`      | `GroupSchema[]`  | —       | Per-group layout config, matched to schemas by `grouping` / group `name`.                             |
| `labelLayout` | `LabelPositionT` | —       | Default label position for inputs (`"left"`, `"top"`, or `"inline"`). Overridden per-schema by `labelPosition`. |

## DialSchema fields

Every control is one `DialSchema`. The most commonly used fields:

| Field                 | Type                                                             | Description                                                                      |
| --------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `name`                | `string`                                                         | Unique key. Also the key used in the values map.                                 |
| `dtype`               | `DialDtype`                                                      | Selects the input to render (see below).                                         |
| `label`               | `string`                                                         | Display label. Defaults to a capitalized `name`.                                 |
| `value`               | `unknown`                                                        | Seed value used for uncontrolled defaults.                                       |
| `grouping`            | `string`                                                         | Section tag; matches a `GroupSchema.name`.                                       |
| `min` / `max`         | `number`                                                         | Bounds for numeric inputs. For `number`, supplying both renders a bounded field. |
| `step`                | `number`                                                         | Increment for numeric / vector / euler inputs.                                   |
| `options`             | `string[]`                                                       | Choices for `select` / string inputs (renders a dropdown).                       |
| `placeholder`         | `string`                                                         | Placeholder for text inputs.                                                     |
| `icon`                | `string`                                                         | Optional leading icon name.                                                      |
| `onClick`             | `() => void`                                                     | Click handler for `button` controls.                                             |
| `variant`             | `'primary' \| 'secondary' \| 'ghost' \| 'destructive' \| 'link'` | Style for `button` controls.                                                     |
| `disabled`            | `boolean`                                                        | Disables a `button` control.                                                     |
| `colSpan` / `rowSpan` | `number`                                                         | Grid span when laid out inside a group.                                          |

### Supported `dtype` values

| `dtype`                                          | Renders                                                                                           |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
| `number`                                         | Number field; a slider when both `min` and `max` are set, or a dropdown when `options` are given. |
| `number-int`                                     | Integer stepper.                                                                                  |
| `number-slider`                                  | Always a slider.                                                                                  |
| `number-rad`                                     | Radian value displayed in degrees.                                                                |
| `boolean`                                        | Toggle.                                                                                           |
| `color`                                          | Color picker (hex).                                                                               |
| `string` / `text` / `select`                     | Text field, or a dropdown when `options` are present.                                             |
| `vector3`                                        | Three-component (x, y, z) numeric input.                                                          |
| `vector` / `vector-6` / `number-group`           | Generic N-component numeric input.                                                                |
| `euler` / `euler-rad` / `euler-deg` / `euler-pi` | Euler-angle inputs in radians, degrees, or π units.                                               |
| `array`                                          | List of primitive values (`arrayElementType`).                                                    |
| `tuple` / `interface` / `object`                 | Nested composite inputs driven by `typeDefinition`.                                               |
| `button`                                         | Action button (`onClick`, `variant`, `disabled`).                                                 |
| `custom`                                         | Caller-provided `render` function or `children`.                                                  |

---

Source: https://uikit.dreamlake.ai/components/waterfall

# Waterfall

A timeline waterfall for run traces and profiling data. The component splits
into two synced panes: a searchable **tree** of events on the left, and a
zoomable **time axis** on the right. Each row is positioned against the same
clock, so parent/child timing and overlap read at a glance.

Rows come in two shapes, decided by their fields:

- **Duration bars** — rows with `startTime` + `duration` render as a bar
  spanning that interval.
- **Instant events** — rows with a bare `time` render as a single dot on the
  axis.

The hierarchy is built from `parentId` (a root row has `parentId: null`).
Collapsible parents can be expanded and collapsed in the tree; the search bar
at the top of the left pane filters rows by `label` (with case-sensitive and
regex toggles).

## Interaction

The time axis manages its own viewport, so the whole timeline is navigable
without any external state:

- **Zoom** — `Shift`/`Alt` + mouse wheel zooms the time axis in and out around
  the cursor. Tune the feel with `zoomFactor`, and clamp the range with
  `minWindow` / `maxWindow`.
- **Pan** — drag horizontally (or use the navigation controls at the bottom)
  to scroll through time while staying at the current zoom.
- **Mark** — click anywhere on a bar or the axis to drop a temporal marker
  (`T1`, `T2`, …) for measuring against. Click a marker again to remove it.
- **Hover** — hovering a row in either pane highlights its counterpart in the
  other.

## Example

A small agent run trace: a root task, two attempts, and the steps inside each.
Duration bars use varied `color` tones; the halt, checkpoint, and completion
rows are instant `time` events. `getIcon` returns a small
[lucide](https://lucide.dev) icon per row based on its `etype`.

The `` fills its container, so wrap it in a fixed-height element
(here `360px`).

## Props — `WaterfallProps`

| Prop                     | Type                               | Default         | Description                                                         |
| ------------------------ | ---------------------------------- | --------------- | ------------------------------------------------------------------- |
| `logData`                | `LogItemType[]`                    | —               | Rows to render. Hierarchy comes from each row's `parentId`.         |
| `getIcon`                | `(item: LogItemType) => ReactNode` | —               | Returns the icon shown for a row in the tree.                       |
| `panelWidth`             | `number`                           | `300`           | Width of the left list/tree pane, in px.                            |
| `temporalCursor`         | `number`                           | —               | Controlled time position of the interactive cursor.                 |
| `onTemporalCursorChange` | `(time: number) => void`           | —               | Called as the cursor moves over the axis.                           |
| `hoveredId`              | `string \| null`                   | —               | Controlled hovered row id. Falls back to internal state if omitted. |
| `onItemHover`            | `(id: string \| null) => void`     | —               | Called when the hovered row changes.                                |
| `minWindow`              | `number`                           | `0.01`          | Minimum zoom window duration, in seconds.                           |
| `maxWindow`              | `number`                           | `duration * 10` | Maximum zoom window duration, in seconds.                           |
| `zoomFactor`             | `number`                           | `1.1`           | Multiplier applied per wheel-zoom step.                             |
| `enabled`                | `boolean`                          | `true`          | Enable wheel pan/zoom handling.                                     |
| `children`               | `ReactNode`                        | —               | Extra content rendered inside the timeline (e.g. custom overlays).  |
| `className`              | `string`                           | —               | Extra classes on the outer wrapper.                                 |

## Row shape — `LogItemType`

A row is either an instant event (`time`) or a duration bar
(`startTime` + `duration`). It extends the shared `TreeDataItem`, so `id`,
`parentId`, and `label` come from there.

| Field           | Type                                                                         | Description                                                     |
| --------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `id`            | `string`                                                                     | Unique row id. Referenced by children via `parentId`.           |
| `parentId`      | `string \| null`                                                             | Parent row id, or `null` for a root row.                        |
| `label`         | `string`                                                                     | Text shown in the tree and used by search.                      |
| `etype`         | `'task' \| 'attempt' \| 'info' \| 'step'`                                    | Row category — handy for choosing an icon.                      |
| `icon`          | `'history' \| 'file-code' \| 'bot' \| 'check-circle' \| 'pause-circle'`      | Optional built-in icon hint.                                    |
| `startTime`     | `number`                                                                     | Bar start time, in seconds. Pair with `duration`.               |
| `duration`      | `number`                                                                     | Bar length, in seconds. Pair with `startTime`.                  |
| `time`          | `number`                                                                     | Instant-event time, in seconds. Renders a dot instead of a bar. |
| `createTime`    | `number`                                                                     | Optional creation timestamp metadata.                           |
| `color`         | `'blue' \| 'green' \| 'orange' \| 'gray-light' \| 'gray-medium' \| 'purple'` | Bar / dot tone.                                                 |
| `isCollapsible` | `boolean`                                                                    | Whether the row can be collapsed in the tree.                   |
| `hasStripes`    | `boolean`                                                                    | Render the bar with a striped fill.                             |
| `isHaltedStep`  | `boolean`                                                                    | Mark a row as a halted step (e.g. error / rate-limit stop).     |

---

Source: https://uikit.dreamlake.ai/components/slider

# Slider

A horizontal slider with one or more thumbs. `value` is always a `number[]`,
so a single-thumb slider holds one entry and a range holds two. Pointer drag
and arrow-key stepping are built in.

## Basic

A single-thumb controlled slider. Pass `value` and `onValueChange` to drive it
from state.

## Range

Provide two entries in `value` for a two-thumb range. Thumbs stay ordered, so
they never cross.

## Steps

Set `step` to a coarser interval and pass `showStep` to draw tick markers along
the track. Values snap to the nearest step.

## Props

| Prop            | Type                        | Default | Description                                   |
| --------------- | --------------------------- | ------- | --------------------------------------------- |
| `value`         | `number[]`                  | —       | Controlled thumb values. One entry per thumb. |
| `defaultValue`  | `number[]`                  | `[min]` | Initial values in uncontrolled mode.          |
| `onValueChange` | `(value: number[]) => void` | —       | Called when a thumb moves.                    |
| `min`           | `number`                    | `0`     | Minimum value of the track.                   |
| `max`           | `number`                    | `100`   | Maximum value of the track.                   |
| `step`          | `number`                    | `1`     | Snap interval for thumb values.               |
| `disabled`      | `boolean`                   | `false` | Disable pointer and keyboard interaction.     |
| `showStep`      | `boolean`                   | `false` | Draw step tick markers along the track.       |
| `className`     | `string`                    | —       | Extra classes on the container.               |

---

Source: https://uikit.dreamlake.ai/components/number-inputs

# Number Inputs

A family of compact, drag-to-scrub inputs built on the shared `InputNumbers`
base. Every numeric field supports the same gesture grammar:

- **Drag horizontally** over a field to scrub its value. Velocity scales the
  step — flick fast to cover ground, ease off for fine control.
- **Drag vertically** across stacked fields to extend a selection, then scrub
  them all at once.
- **Hold `Shift`** while dragging for a 5× step, **`Alt`** for a 1/5× step.
- **Click to focus** and type an exact value, or use the **arrow keys** to nudge
  by one `step`.

The unit wrappers (`Vec3Input`, `IntInput`, `DegInput`, `RadInput`,
`EulerInput`, `QuaternionInput`, …) are thin presets over `InputNumbers` /
`VectorInput` — they fix the labels, suffix, and step so callers only deal in
the value they care about.

## Vector (Vec3Input)

`Vec3Input` renders three labelled fields (`x` / `y` / `z`) and emits a tuple
through `onValuesChange`. Drag any single field, or drag down across the stack
to scrub several axes together.

## Scalars with units

`IntInput` rounds to whole numbers, while `DegInput` and `RadInput` append a
unit suffix. Each takes a single `value` and reports through `onChange`.
`RadInput` stores radians internally but can `display` them as `deg`, `pi`, or
`rad`.

## Color (ColorInput)

`ColorInput` pairs a native swatch with a hex field. It accepts hex strings,
`0x`-prefixed strings, numeric hex values, or CSS color names, and reports the
normalized hex (without `#`) through `onValueChange`.

## Text (TextInput)

`TextInput` is the string sibling — a plain text field with optional `prefix`
and `suffix` slots. It reports the raw string through `onChange`.

## Props

### InputNumbers

The base used by every numeric wrapper. Renders one field per entry in `value`.

| Prop                  | Type                          | Default | Description                                                           |
| --------------------- | ----------------------------- | ------- | --------------------------------------------------------------------- |
| `value`               | `number[]`                    | —       | Current values, one field per entry. Must be non-empty.               |
| `onValuesChange`      | `(value: number[]) => void`   | —       | Called with the full array whenever any field changes.                |
| `step`                | `number \| number[]`          | `0.1`   | Drag/arrow increment, shared or per-field.                            |
| `min`                 | `number \| number[]`          | —       | Lower clamp, shared or per-field.                                     |
| `max`                 | `number \| number[]`          | —       | Upper clamp, shared or per-field.                                     |
| `prefix`              | `ReactNode[]`                 | —       | Left slot content per field (axis labels, icons).                     |
| `suffix`              | `ReactNode[]`                 | —       | Right slot content per field (unit glyphs).                           |
| `disabledItems`       | `boolean[]`                   | —       | Per-field disabled state.                                             |
| `size`                | `'sm' \| 'md' \| 'lg'`        | `'md'`  | Field height and text size.                                           |
| `gridAutoFlow`        | `'column' \| 'row'`           | `'row'` | Grid flow direction for multi-field layouts.                          |
| `columns`             | `number`                      | —       | Fixed column count (switches to grid layout).                         |
| `rows`                | `number`                      | —       | Fixed row count (switches to grid layout).                            |
| `onSuffixBatchAction` | `(indices: number[]) => void` | —       | Fires when the suffix area is clicked/dragged, with affected indices. |

### VectorInput

Extends `InputNumbers`; swaps `prefix` for the friendlier `labels`.

| Prop             | Type                        | Default | Description                                 |
| ---------------- | --------------------------- | ------- | ------------------------------------------- |
| `value`          | `number[]`                  | —       | Current vector values.                      |
| `onValuesChange` | `(value: number[]) => void` | —       | Called with the full vector on change.      |
| `labels`         | `ReactNode[]`               | —       | Per-field labels rendered in the left slot. |
| `step`           | `number \| number[]`        | `0.1`   | Drag/arrow increment, shared or per-field.  |

### Unit wrappers

Single-scalar presets. They take one `value` and report through `onChange`.

| Component         | Value type                         | Reports                 | Extra props                                                                |
| ----------------- | ---------------------------------- | ----------------------- | -------------------------------------------------------------------------- |
| `IntInput`        | `number`                           | `onChange(value)`       | Rounds to the nearest integer; `step` defaults to `1`.                     |
| `DegInput`        | `number`                           | `onChange(value)`       | Appends a `°` suffix.                                                      |
| `RadInput`        | `number`                           | `onChange(value)`       | Stores radians; `display` (`'deg' \| 'pi' \| 'rad'`, default `'rad'`) picks the shown unit. |
| `CmInput`         | `number`                           | `onChange(value)`       | Appends a `cm` suffix.                                                     |
| `InchInput`       | `number`                           | `onChange(value)`       | Appends an `in` suffix.                                                    |
| `TimeInput`       | `number`                           | `onChange(value)`       | Appends an `s` suffix.                                                     |
| `Vec3Input`       | `[number, number, number]`         | `onValuesChange(tuple)` | Fixed `x` / `y` / `z` labels.                                              |
| `EulerInput`      | `[number, number, number]`         | `onValuesChange(tuple)` | `unit` (`'deg' \| 'rad'`, default `'deg'`) sets the label suffix.          |
| `EulerDegInput`   | `[number, number, number]`         | `onValuesChange(tuple)` | `EulerInput` locked to `deg` labels.                                       |
| `EulerRadInput`   | `[number, number, number]`         | `onValuesChange(tuple)` | Stores radians; `display` (`'deg' \| 'pi' \| 'rad'`, default `'rad'`) picks the shown unit. |
| `QuaternionInput` | `[number, number, number, number]` | `onValuesChange(tuple)` | Fixed `w` / `x` / `y` / `z` labels.                                        |
| `KVectorInput`    | `number[]`                         | `onValuesChange(array)` | N-component vector; labels `0…k-1`. `dimensions` sets `k` (defaults to `value.length`). |

### ColorInput

| Prop            | Type                         | Default | Description                                              |
| --------------- | ---------------------------- | ------- | -------------------------------------------------------- |
| `value`         | `string \| number`           | —       | Hex string, `0x`-string, numeric hex, or CSS color name.       |
| `onValueChange` | `(hexColor: string) => void` | —       | Called with the normalized hex string (without `#`).           |

The hex field is fixed at the `sm` size; `ColorInput` does not take a `size`
prop.

### Preset pickers

Scalar fields paired with quick-set buttons. Each button jumps the value to one
of the supplied `presets`.

| Component         | Value type | Reports           | Extra props                                                                              |
| ----------------- | ---------- | ----------------- | ---------------------------------------------------------------------------------------- |
| `PresetsInput`    | `number`   | `onChange(value)` | `presets` — three quick-set values shown as buttons below the field.                     |
| `PresetsRadInput` | `number`   | `onChange(value)` | Radian variant; `presets` in radians, `display` (`'deg' \| 'pi' \| 'rad'`, default `'rad'`) formats both the field and the buttons. |

### TextInput

| Prop          | Type                      | Default | Description                           |
| ------------- | ------------------------- | ------- | ------------------------------------- |
| `value`       | `string`                  | `''`    | Current text value.                   |
| `onChange`    | `(value: string) => void` | —       | Called with the raw string on change. |
| `placeholder` | `string`                  | —       | Placeholder text.                     |
| `prefix`      | `string`                  | —       | Left slot content.                    |
| `suffix`      | `string`                  | —       | Right slot content.                   |
| `maxLength`   | `number`                  | —       | Maximum character length.             |
| `size`        | `'sm' \| 'md' \| 'lg'`    | `'md'`  | Field height and text size.           |

---

Source: https://uikit.dreamlake.ai/components/layout

# Layout

Two studio layout shells, each a single `*View` component that arranges center
content with optional `left` / `right` / `top` / `bottom` slots. Every slot
accepts any `ReactNode` — pass your own panels, toolbars, or controls. Both
fill their parent (`height: 100%`), so constrain the height of the wrapping
element.

## Switching layouts

Both shells share the same slot API, so swapping between them is a one-line
change (`const View = liquid ? LiquidLayoutView : DockLayoutView`). Click the
button to switch the live example: the **dock** layout docks the same cards onto
solid full-height rails — cards go flat (no border or shadow) since they share
the rail's surface — while the **liquid** layout floats them over the
pointer-transparent center content.

## Dock layout

`DockLayoutView` docks panels to the edges: left and right panels are full-height
columns, the top slot floats centered near the top, and the bottom slot spans the
full width. Panel surfaces use the DreamLake panel token. The center content sits
behind the docked panels and scrolls independently.

## Liquid layout

`LiquidLayoutView` is a 3-column grid whose gutters are pointer-transparent, so a
3D canvas rendered as the content stays interactive behind the floating panels.
Each slot wrapper re-enables pointer events only on its own children. Left and
right panels are capped to a readable max width and scroll vertically.

## DockLayoutView props

| Prop               | Type        | Default | Description                                                                      |
| ------------------ | ----------- | ------- | -------------------------------------------------------------------------------- |
| `children`         | `ReactNode` | —       | Center content. Rendered behind the docked panels and scrolls independently.     |
| `left`             | `ReactNode` | —       | Full-height panel docked to the left edge. Omitted if unset.                     |
| `right`            | `ReactNode` | —       | Full-height panel docked to the right edge. Omitted if unset.                    |
| `top`              | `ReactNode` | —       | Slot floated centered near the top edge. Omitted if unset.                       |
| `bottom`           | `ReactNode` | —       | Full-width slot docked to the bottom edge. Omitted if unset.                     |
| `hideUI`           | `boolean`   | `false` | Hides all panels (keeps content) by making the UI invisible and non-interactive. |
| `className`        | `string`    | —       | Extra classes on the root container.                                             |
| `leftClassName`    | `string`    | —       | Extra classes on the left panel wrapper.                                         |
| `rightClassName`   | `string`    | —       | Extra classes on the right panel wrapper.                                        |
| `topClassName`     | `string`    | —       | Extra classes on the top slot wrapper.                                           |
| `bottomClassName`  | `string`    | —       | Extra classes on the bottom slot wrapper.                                        |
| `contentClassName` | `string`    | —       | Extra classes on the center content wrapper.                                     |

## LiquidLayoutView props

| Prop               | Type        | Default | Description                                                                                              |
| ------------------ | ----------- | ------- | -------------------------------------------------------------------------------------------------------- |
| `children`         | `ReactNode` | —       | Center content (e.g. a 3D canvas). Stays interactive behind the floating panels.                         |
| `left`             | `ReactNode` | —       | Floating panel in the left grid column. Capped to a max width and scrolls vertically. Omitted if unset.  |
| `right`            | `ReactNode` | —       | Floating panel in the right grid column. Capped to a max width and scrolls vertically. Omitted if unset. |
| `top`              | `ReactNode` | —       | Floating slot centered in the top grid row. Omitted if unset.                                            |
| `bottom`           | `ReactNode` | —       | Floating slot spanning the bottom grid row. Omitted if unset.                                            |
| `hideUI`           | `boolean`   | `false` | Hides all floating panels (keeps content) by making the UI invisible and non-interactive.                |
| `className`        | `string`    | —       | Extra classes on the root grid container.                                                                |
| `leftClassName`    | `string`    | —       | Extra classes on the left panel wrapper.                                                                 |
| `rightClassName`   | `string`    | —       | Extra classes on the right panel wrapper.                                                                |
| `topClassName`     | `string`    | —       | Extra classes on the top slot wrapper.                                                                   |
| `bottomClassName`  | `string`    | —       | Extra classes on the bottom slot wrapper.                                                                |
| `contentClassName` | `string`    | —       | Extra classes on the center content wrapper.                                                             |

## Composable sub-components

`DockLayoutView` and `LiquidLayoutView` are opinionated compositions of a set of
lower-level slot primitives. Reach for these directly when you need finer control
over ordering, nesting, or which slots render. Each accepts the standard `div`
props; several of the edge slots also accept `asChild` to merge onto your own
single child element instead of rendering a wrapper `div`.

| Dock                 | Liquid                 | Role                                                       |
| -------------------- | ---------------------- | ---------------------------------------------------------- |
| `DockLayout`         | `LiquidLayout`         | Root container establishing the shell layout.              |
| `DockLayoutContent`  | `LiquidLayoutContent`  | Center content region.                                     |
| `DockLayoutLeft`     | `LiquidLayoutLeft`     | Left slot wrapper.                                         |
| `DockLayoutRight`    | `LiquidLayoutRight`    | Right slot wrapper.                                        |
| `DockLayoutTop`      | `LiquidLayoutTop`      | Top slot wrapper.                                          |
| `DockLayoutBottom`   | `LiquidLayoutBottom`   | Bottom slot wrapper.                                       |

---

Source: https://uikit.dreamlake.ai/components/sync-scroll

# Sync Scroll

Keep several scroll containers locked to the same position. A
`SyncScrollProvider` registers every pane mounted beneath it; a **master**
broadcasts its `scrollTop` / `scrollLeft` to all the **slaves**, so scrolling
one moves the others in lockstep. Slaves never drive the group — they only
follow — which keeps the sync loop one-directional and free of feedback.

Each pane is a plain `div` you style yourself: give it a fixed height (or
width) and an `overflow` so it actually scrolls. The components just attach the
right ref and event listener.

## Master / slave panes

Two side-by-side panes inside one provider. The left pane is the `SyncScroll`
master; the right is a `SyncScrollSlave`. Scroll the master and the slave
tracks it. By default sync is vertical.

## Drag to scroll

`SyncDragX` / `SyncDragY` (and `SyncDrag` for both axes) add click-and-drag
panning and act as a master, so paired `SyncDragSlave*` panes follow along.
Drag either track below horizontally.

## Exports

| Export               | Kind      | Role                                                                                                              |
| -------------------- | --------- | ----------------------------------------------------------------------------------------------------------------- |
| `SyncScrollProvider` | Component | Context boundary that registers panes and relays the master's scroll position to slaves. Wrap every group in one. |
| `SyncScroll`         | Component | Master pane (`overflow-y-auto`). Its scroll position drives all slaves in the group.                              |
| `SyncScrollSlave`    | Component | Slave pane (`overflow-y-auto`). Follows the master; its own scrolling does not drive others.                      |
| `SyncDrag`           | Component | Drag-to-scroll master on both axes. Behaves like a master for syncing.                                            |
| `SyncDragX`          | Component | Horizontal-only drag-to-scroll master.                                                                            |
| `SyncDragY`          | Component | Vertical-only drag-to-scroll master.                                                                              |
| `SyncDragSlave`      | Component | Drag-to-scroll slave on both axes. Follows a master.                                                              |
| `SyncDragSlaveX`     | Component | Horizontal-only drag-to-scroll slave.                                                                             |
| `useSyncScroll`      | Hook      | Returns a ref registering the element as a `master`. Backs `SyncScroll`.                                          |
| `useScrollSlave`     | Hook      | Returns a ref registering the element as a `slave`. Backs the slave components.                                   |
| `useSyncDrag`        | Hook      | Returns a ref registering the element with the `drag` role (acts as a master). Backs the drag components.         |

All components accept the standard `div` props plus `asChild` — pass `asChild`
to merge the scroll ref onto your own single child element instead of rendering
a wrapper `div`.

### Hook options

The hooks accept an options object:

| Option    | Type                                   | Default      | Description                                               |
| --------- | -------------------------------------- | ------------ | --------------------------------------------------------- |
| `enabled` | `boolean`                              | `true`       | Toggle registration and listeners off without unmounting. |
| `axis`    | `'vertical' \| 'horizontal' \| 'both'` | `'vertical'` | Which scroll axes are tracked and synced.                 |
| `ref`     | `RefObject`            | —            | Provide your own element ref instead of the internal one. |