# Adaptive Card Designer
URL: /docs/web/components/adaptive-card-designer

Visual drag-and-drop designer for Microsoft Adaptive Cards 1.5 / 1.6 payloads. Three-pane editor (toolbox · canvas · structure / properties) with paired JSON editors, live preview, undo / redo, and theme / width controls — backed by the in-repo Adaptive Card renderer.

**Demo:**

```tsx
'use client';

import { useState } from 'react';

import { AdaptiveCardDesigner } from '@docyrus/ui/components/adaptive-card-designer';
import { type AdaptiveCardPayload } from '@docyrus/ui/components/adaptive-card';
import { Button } from '@docyrus/ui/primitives/ui/button';
import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogHeader,
  DialogTitle
} from '@docyrus/ui/primitives/ui/dialog';
import { LayoutTemplate, Plus } from 'lucide-react';

const STARTER: AdaptiveCardPayload = {
  type: 'AdaptiveCard',
  version: '1.5',
  body: [
    {
      type: 'TextBlock',
      text: '**Welcome to the Adaptive Card Designer**',
      size: 'large',
      weight: 'bolder'
    },
    {
      type: 'TextBlock',
      text: 'Pick elements from the toolbox on the left, or edit the JSON below. The canvas updates live.',
      wrap: true,
      isSubtle: true
    },
    {
      type: 'FactSet',
      facts: [{ title: 'Status', value: 'Draft' }, { title: 'Owner', value: '${user.name}' }]
    }
  ],
  actions: [{ type: 'Action.OpenUrl', title: 'Adaptive Cards spec', url: 'https://adaptivecards.io/' }]
};

const STARTER_DATA = {
  user: { name: 'Alice', role: 'Admin' }
};

export function AdaptiveCardDesignerDemo() {
  const [open, setOpen] = useState(false);
  const [mode, setMode] = useState<'sample' | 'blank'>('sample');

  const openDesigner = (next: 'sample' | 'blank') => {
    setMode(next);
    setOpen(true);
  };

  return (
    <div className="flex flex-wrap items-center gap-2">
      
      

      
            
          

          <div className="min-h-0 flex-1">
            
          </div>
        
      
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-adaptive-card-designer
```

**Dependencies:**
- [@dnd-kit/core](https://www.npmjs.com/package/@dnd-kit/core)
- [@monaco-editor/react](https://www.npmjs.com/package/@monaco-editor/react)
- [lucide-react](https://www.npmjs.com/package/lucide-react)

The designer renders its canvas with the [`AdaptiveCard`](/docs/web/components/adaptive-card) renderer, which is installed automatically as a registry dependency.

## Overview

`AdaptiveCardDesigner` is a full visual authoring surface for [Adaptive Cards](https://adaptivecards.io/) payloads. Where [`AdaptiveCard`](/docs/web/components/adaptive-card) only *renders* a payload, the designer lets users *build* one — dragging elements from a toolbox, reordering and reparenting them in a structure tree, editing element properties in a side panel, and watching the result render live. The raw payload and the templating sample-data are both editable as JSON at the bottom, and the two views stay in sync.

Typical use cases:

- **Internal card authoring** — a no-code surface for ops / support teams to compose Teams-style cards and agent UI without hand-writing JSON.
- **Template tooling** — author the payload that an LLM agent or automation later fills with `${...}` bindings, previewed against sample data.
- **Embedded editors** — drop the designer into an automation-node config or a CMS, read the emitted payload back via `onChange`.

The designer works on its own normalized node tree internally (stable per-node ids, uniform child *slots*) and serializes back to a standard `AdaptiveCardPayload` on every edit.

## Layout

The designer is a three-pane layout with a toolbar above and paired JSON editors below:

| Region | Purpose |
|--------|---------|
| **Toolbar** | New / undo / redo / copy, theme (light / dark / auto), canvas width (standard / wide / full), preview toggle. Buttons are individually hideable via `hideToolbarButtons`. |
| **Toolbox** (left) | Draggable element / input / action types grouped into `elements`, `inputs`, `actions`, `advanced`. Append your own via `extraToolboxItems`. |
| **Canvas** (center) | Live render of the card via `<AdaptiveCard>`. Click an element to select it; drop toolbox items directly onto it. |
| **Structure** (right, top) | Collapsible tree of the card. Reorder / reparent by drag, select to edit. |
| **Properties** (right, bottom) | Type-aware property editors for the selected node. |
| **Payload editor** (bottom) | The live `AdaptiveCardPayload` JSON (Monaco). |
| **Sample-data editor** (bottom) | The templating data JSON used to resolve `${...}` bindings in preview. |

## Usage

### Uncontrolled

```tsx
import { AdaptiveCardDesigner } from '@docyrus/ui/components/adaptive-card-designer';
import { type AdaptiveCardPayload } from '@docyrus/ui/components/adaptive-card';

const starter: AdaptiveCardPayload = {
  type: 'AdaptiveCard',
  version: '1.5',
  body: [{ type: 'TextBlock', text: 'Hello, **Adaptive Cards**!', weight: 'bolder' }]
};

<AdaptiveCardDesigner
  defaultPayload={starter}
  defaultSampleData={{ user: { name: 'Alice' } }}
  onChange={({ payload, sampleData }) => console.log(payload, sampleData)} />
```

### Controlled

Pass `payload` / `sampleData` to drive the designer from outside. `onChange` fires after every edit:

```tsx
const [payload, setPayload] = useState<AdaptiveCardPayload>(starter);
const [data, setData] = useState<unknown>({});

<AdaptiveCardDesigner
  payload={payload}
  sampleData={data}
  onChange={next => { setPayload(next.payload); setData(next.sampleData); }} />
```

### Read-only inspection

`readOnly` disables every mutation — toolbox drag, drop zones, property edits, JSON edits, undo / redo / new, and keyboard shortcuts. Theme / width / preview / copy stay active, and selection remains enabled so users can click through the tree and inspect properties:

```tsx

```

### Custom toolbox items

Append your own draggable types alongside the built-ins. Each item supplies a `factory` that returns a fresh node on every drop:

```tsx
import { Sparkles } from 'lucide-react';
import { type ToolboxItem } from '@docyrus/ui/components/adaptive-card-designer';

const extras: ToolboxItem[] = [
  {
    id: 'Docyrus.UserChip',
    type: 'Docyrus.UserChip',
    label: 'User Chip',
    icon: Sparkles,
    group: 'advanced',
    keywords: ['user', 'chip', 'avatar'],
    factory: () => ({
      __designerId: crypto.randomUUID(),
      type: 'Docyrus.UserChip',
      props: { userId: '' },
      slots: {}
    })
  }
];

<AdaptiveCardDesigner
  extraToolboxItems={extras}
  customElements={{ 'Docyrus.UserChip': ({ element }) =>  }} />
```

Pair `extraToolboxItems` (authoring) with `customElements` (rendering) so the canvas knows how to draw the type you just added. `customElements` and `hostConfig` are forwarded straight to the inner `<AdaptiveCard>`.

### Trimming the toolbar

```tsx

```

## API Reference

### `AdaptiveCardDesignerProps`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `payload` | `AdaptiveCardPayload` | — | Current card payload (controlled). |
| `defaultPayload` | `AdaptiveCardPayload` | — | Initial payload when uncontrolled. |
| `sampleData` | `unknown` | — | Templating data resolved into the preview canvas (controlled). |
| `defaultSampleData` | `unknown` | — | Initial sample data when uncontrolled. |
| `onChange` | `(next: { payload: AdaptiveCardPayload; sampleData: unknown }) => void` | — | Fires after every payload or sample-data edit. |
| `hostConfig` | `AdaptiveCardHostConfigOverride` | — | Forwarded to the inner ``. |
| `customElements` | `Record<string, ElementRenderer>` | `{}` | Forwarded to the inner ``. Pair with `extraToolboxItems` to author custom types. |
| `defaultPreview` | `boolean` | `false` | Start in preview (render-only) mode rather than edit mode. |
| `defaultTheme` | `DesignerTheme` | `'light'` | Initial canvas theme — `'light' \| 'dark' \| 'auto'`. |
| `defaultWidth` | `DesignerWidth` | `'standard'` | Initial canvas width — `'standard' \| 'wide' \| 'full'`. |
| `hideToolbarButtons` | `ToolbarButtonKey[]` | — | Hide specific toolbar buttons — `'new' \| 'theme' \| 'width' \| 'undo' \| 'redo' \| 'copy' \| 'preview'`. |
| `extraToolboxItems` | `ToolboxItem[]` | — | Append additional toolbox items alongside the built-ins. |
| `height` | `string` | `'70vh'` | Designer chrome height. |
| `className` | `string` | — | Forwarded to the root element. |
| `readOnly` | `boolean` | `false` | Disable all mutations. Theme / width / preview / copy and selection stay active. |
| `aiAssistantOpen` | `boolean` | — | Controlled open state for the AI Assistant drawer. When provided the designer stops managing the open state internally — pair with `onAiAssistantOpenChange`. |
| `onAiAssistantOpenChange` | `(open: boolean) => void` | — | Fired when the AI Assistant toolbar button toggles the drawer. |
| `renderAiAssistant` | `(ctx: IAdaptiveCardAiAssistantRenderContext) => ReactNode` | — | Mounts a custom AI Assistant drawer body on the left of the designer. When set, the toolbar shows a Bot toggle that opens/closes the drawer; this render fn supplies the body (typically a `<DocyrusAgent>` or `<EditorAgent>` wrapper). Without it the AI button is hidden. |
| `aiAssistantWidth` | `number` | `380` | Width in pixels the drawer animates to when open. |

## EditorAgent integration

Pair `useApplyAdaptiveCard` with `renderAiAssistant` to let an LLM author Adaptive Card payloads. The hook owns the designer's controlled `payload` + `sampleData` and exposes an `applyAdaptiveCard` tool that the agent calls to commit a new payload. The tool rejects primitives / arrays / null and requires `type: "AdaptiveCard"` at the root so a malformed call cannot crash the designer.

```tsx
import { EditorAgent } from '@docyrus/ui/components/editor-agent';
import { AdaptiveCardDesigner, useApplyAdaptiveCard } from '@docyrus/ui/components/adaptive-card-designer';

export function AdaptiveCardPlayground({ client, user, agentId }) {
  const adaptiveCard = useApplyAdaptiveCard();
  const [aiOpen, setAiOpen] = useState(false);

  return (
    <AdaptiveCardDesigner
      payload={adaptiveCard.payload ?? undefined}
      sampleData={adaptiveCard.sampleData}
      onChange={(next) => {
        adaptiveCard.setPayload(next.payload);
        adaptiveCard.setSampleData(next.sampleData);
      }}
      aiAssistantOpen={aiOpen}
      onAiAssistantOpenChange={setAiOpen}
      renderAiAssistant={({ open, onClose }) => (
        
      )}
    />
  );
}
```

The matching backend agent must register a tool named `applyAdaptiveCard` whose input schema mirrors `{ payload: object (required), sampleData?: any, explanation?: string }`.

## Composition

The default `AdaptiveCardDesigner` is a single component that composes a provider + the panes. For custom layouts you can assemble the pieces yourself:

| Export | Purpose |
|--------|---------|
| `DesignerProvider` | Holds reducer state + history. Wrap your own panel composition in it. |
| `useDesignerContext()` | Read `state` + `dispatch` inside a custom panel. |
| `useApplyAdaptiveCard()` | Owns the controlled `payload` + `sampleData` state and ships the `applyAdaptiveCard` client-side tool for `<EditorAgent>`. See **EditorAgent integration** above. |

## Helpers

The component also exports its tree model utilities for advanced integrations (custom serializers, programmatic edits, validation):

| Export | Purpose |
|--------|---------|
| `cardToTree(payload)` / `treeToCard(node)` | Convert between an `AdaptiveCardPayload` and the designer's `DesignerNode` tree. |
| `normalizeForRoundTrip(payload)` | Normalize a payload so tree → card → tree is lossless. |
| `slotsFor(type)` / `SLOT_MAP` | The slot names (`items`, `columns`, `actions`, …) a given element type accepts. |
| `isLeafType(type)` | Whether a type accepts no children. |
| `createDefaultNode(type)` / `defaultChildType(type)` | Factory helpers for new nodes. |
| `createDesignerId()` | Generate a stable internal node id. |
| `findNode`, `findLocation`, `insertNode`, `removeNode`, `moveNode`, `updateNode`, `isAncestor`, `collectIds`, `countNodes` | Tree traversal + mutation utilities. |

## Type Exports

| Type | Description |
|------|-------------|
| `AdaptiveCardDesignerProps` | Component props. |
| `DesignerProviderProps` | Props for `DesignerProvider`. |
| `DesignerNode` | A node in the designer's normalized tree — `{ __designerId, type, props, slots }`. |
| `DesignerState` / `DesignerAction` | Reducer state + action union. |
| `DesignerTheme` | `'light' \| 'dark' \| 'auto'`. |
| `DesignerWidth` | `'standard' \| 'wide' \| 'full'`. |
| `DesignerFocus` | Which editor was last focused — `'canvas' \| 'payload' \| 'data'`. |
| `DesignerDiagnostic` | A validation diagnostic — `{ level, message, nodeId? }`. |
| `HistorySnapshot` | An undo / redo history entry. |
| `ToolboxItem` / `ToolboxGroup` | A toolbox entry and its group key. |
| `ToolbarButtonKey` | Keys accepted by `hideToolbarButtons`. |
| `DesignerRootType` | The `'__root'` discriminant for the card root node. |
| `IAdaptiveCardAiAssistantRenderContext` | Argument passed to `renderAiAssistant` — `{ open, width, onClose, payload, sampleData }`. |
| `IUseApplyAdaptiveCardResult` | Return shape of `useApplyAdaptiveCard` — `{ payload, setPayload, sampleData, setSampleData, tools }`. |

## Related

- [`AdaptiveCard`](/docs/web/components/adaptive-card) — the renderer the designer canvas is built on.
- [`useAdaptiveCard`](/docs/web/hooks/use-adaptive-card) — the hook behind the renderer.

---

# Adaptive Card
URL: /docs/web/components/adaptive-card

Renderer for Microsoft's Adaptive Cards 1.5 schema. Surfaces LLM-generated and Microsoft Teams payloads as native Docyrus UI with stateful inputs, validation, nested ShowCards, and action dispatch.

**Demo:**

```tsx
'use client';

import { useMemo, useState } from 'react';

import {
  AdaptiveCard,
  type AdaptiveCardActionEvent,
  type AdaptiveCardPayload
} from '@docyrus/ui/components/adaptive-card';
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue
} from '@docyrus/ui/primitives/ui/select';
import { cn } from '@docyrus/ui/primitives/lib/utils';

import {
  DEMO_AGENT_MESSAGE,
  DEMO_FLIGHT_CARD,
  DEMO_FORM_CARD
} from '@/data/adaptive-card-data';

const DEMOS = {
  flight: { label: 'Flight status', payload: DEMO_FLIGHT_CARD },
  form: { label: 'Form card', payload: DEMO_FORM_CARD },
  agent: { label: 'Agent message', payload: DEMO_AGENT_MESSAGE }
} as const satisfies Record<string, { label: string; payload: AdaptiveCardPayload }>;

export function AdaptiveCardDemo() {
  const [selected, setSelected] = useState<keyof typeof DEMOS>('flight');
  const [open, setOpen] = useState(false);
  const [lastEvent, setLastEvent] = useState
                  
                    ))}
                  
                
              </div>
            </div>
          </div>
        </div>
      </div>
      <div className="rounded-lg border border-border bg-muted/30 p-4">
        
      </div>
      {lastEvent ? (
        <pre className="mt-3 max-h-32 overflow-auto rounded bg-muted/50 p-2 font-mono text-xs">
          {JSON.stringify(lastEvent, (_k, v) => v instanceof Object && 'card' in v ? { ...v, card: '<…>' } : v, 2)}
        </pre>
      ) : null}
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-adaptive-card
```

**Dependencies:**
- [lucide-react](https://www.npmjs.com/package/lucide-react)
- [react-markdown](https://www.npmjs.com/package/react-markdown)
- [remark-gfm](https://www.npmjs.com/package/remark-gfm)

## Overview

`AdaptiveCard` consumes Microsoft's [Adaptive Cards 1.5 JSON schema](https://adaptivecards.io/schemas/1.5.0/adaptive-card.json) and renders it using Docyrus primitives (shadcn). The two primary use cases are:

- **Agent-native UI** — Adaptive Cards are a JSON structure LLM agents already understand and emit reliably. Use the renderer to surface agent output as actionable UI.
- **Microsoft Teams interop** — the same payload a Teams Bot returns can render directly inside Docyrus messages, comments, and notifications.

The component is a thin wrapper around [`useAdaptiveCard`](/docs/web/hooks/use-adaptive-card). Drop in a payload, get a fully interactive card back. For advanced flows (server-driven validation, custom toolbars), use the hook directly.

## Usage

### Basic render

```tsx
import { AdaptiveCard, type AdaptiveCardPayload } from '@docyrus/ui/components/adaptive-card';

const payload: AdaptiveCardPayload = {
  type: 'AdaptiveCard',
  version: '1.5',
  body: [
    { type: 'TextBlock', text: 'Hello, **Adaptive Cards**!', size: 'large', weight: 'bolder' }
  ],
  actions: [
    { type: 'Action.OpenUrl', title: 'Open docs', url: 'https://adaptivecards.io/' }
  ]
};

<AdaptiveCard payload={payload} onAction={event => console.log(event)} />
```

### Handling submit / execute

```tsx
<AdaptiveCard
  payload={formPayload}
  onAction={async (event) => {
    if (event.type === 'submit') {
      await fetch('/api/forms', { method: 'POST', body: JSON.stringify(event.data) });
    } else if (event.type === 'execute') {
      // event.verb identifies the bot action
      await invokeBot(event.verb, event.data);
    }
  }} />
```

`onAction` fires for **every** action the user triggers — `submit`, `execute`, `openUrl`, `toggleVisibility`, `showCard` — so consumers can log analytics, persist drafts, or route Teams `Action.Execute` calls.

### Host config override

The renderer maps Adaptive Cards' abstract enums (`Good`, `Attention`, `Bleed`, `Medium`) to concrete colors/spacing/sizes via a host config. `defaultHostConfig` reads from the repo's CSS-variable tokens, so dark mode is automatic. Pass `hostConfig` to deep-merge overrides:

```tsx

```

### Custom element types

Register a renderer for an unknown `type` string via `customElements`:

```tsx
<AdaptiveCard
  payload={payload}
  customElements={{
    'Docyrus.UserChip': ({ element }) => 
  }} />
```

Custom renderers take precedence over the built-in registry. The unknown-type fallback continues to honor the schema's `fallback` chain otherwise.

### Hook-driven flow

For advanced cases (custom toolbar, programmatic submit, server-side validation), consume the hook directly:

```tsx
import { AdaptiveCardView, useAdaptiveCard } from '@docyrus/ui/components/adaptive-card';

function CustomFlow({ payload }) {
  const adaptive = useAdaptiveCard(payload, { onAction });

  return (
    <>
      <button onClick={() => adaptive.controls.validateAll()}>Pre-validate</button>
      
    </>
  );
}
```

See [`useAdaptiveCard`](/docs/web/hooks/use-adaptive-card) for the full hook surface.

## Schema coverage

The renderer ships **complete coverage** of the Adaptive Cards 1.5 schema:

| Category | Elements |
|----------|----------|
| Text & media | `TextBlock`, `RichTextBlock` (with `TextRun` inlines), `Image`, `ImageSet`, `Media` |
| Containers | `Container`, `ColumnSet` (`Column` children), `FactSet`, `Table` (`TableRow`, `TableCell`), `ActionSet` |
| Inputs | `Input.Text` (single + multiline + `inlineAction`), `Input.Number`, `Input.Date`, `Input.Time`, `Input.Toggle`, `Input.ChoiceSet` (compact / expanded / filtered × single / multi) |
| Actions | `Action.Submit`, `Action.Execute`, `Action.OpenUrl`, `Action.ShowCard` (nested cards), `Action.ToggleVisibility` |
| Cross-cutting | `selectAction` on containers/columns/images/text-runs/table cells/root card, `requires` capability gating, `fallback` chains, `isVisible` defaults + toggle overrides, `spacing` + `separator`, markdown in `TextBlock` + `FactSet` values, `backgroundImage` (with safe-URL guard), validation (`isRequired`, `regex`, `min`/`max`, error messages) |

Out of scope in v1: live `refresh` polling, server-side `Action.Execute` transport (we hand `verb` + `data` to `onAction`), `authentication` block rendering.

## Action dispatch

Every action emits a typed event through `onAction`:

| Event `type` | Fields | Triggered by |
|--------------|--------|--------------|
| `'submit'` | `data`, `action`, `card` | `Action.Submit` (after validation passes) |
| `'execute'` | `verb`, `data`, `action`, `card` | `Action.Execute` (after validation passes) |
| `'openUrl'` | `url`, `action`, `card` | `Action.OpenUrl` (also navigates the browser via the embedded `<a>`) |
| `'toggleVisibility'` | `action`, `card` | `Action.ToggleVisibility` |
| `'showCard'` | `isOpen`, `action`, `card` | `Action.ShowCard` (fires for both open and close) |

`data` follows the spec's `associatedInputs` contract: `'auto'` (default) collects every visible input in the current scope; `'none'` ships only `action.data`. For `Action.ShowCard` submits, the nested card's inputs merge into the parent's.

## API Reference

### `AdaptiveCardProps`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `payload` | `AdaptiveCardPayload` | — | The card JSON. Must have `type: 'AdaptiveCard'` and a `version`. |
| `onAction` | `(event: AdaptiveCardActionEvent) => void \| Promise<void>` | — | Fires for every dispatched action. |
| `hostConfig` | `AdaptiveCardHostConfigOverride` (deep partial of `AdaptiveCardHostConfig`) | `defaultHostConfig` | Override colors, spacing, sizes, container styles, or action layout. Deep-merged over the default. |
| `customElements` | `Record<string, ElementRenderer>` | `{}` | Renderers for element types unknown to the spec. Take precedence over the built-in registry. |
| `className` | `string` | — | Forwarded to the root `<Card>`. |

### `AdaptiveCardViewProps`

`AdaptiveCardView` is the presentational layer that the hook drives. Use it when you call `useAdaptiveCard` yourself.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `cardProps` | `AdaptiveCardContextValue` | — | The `cardProps` projection returned by `useAdaptiveCard`. |
| `className` | `string` | — | Forwarded to the root `<Card>`. |

## Components

| Component | Description |
|-----------|-------------|
| `AdaptiveCard` | High-level component. Composes `useAdaptiveCard` + `AdaptiveCardView`. |
| `AdaptiveCardView` | Presentational layer. Consumes `cardProps` from `useAdaptiveCard`. Use this when wiring the hook manually. |
| `ElementNode` / `ElementList` | Recursive renderer. The `customElements` extension point routes through these. |
| `ActionBar` | Renders an action list with overflow menu + ShowCard panels. |

## Helpers

| Export | Purpose |
|--------|---------|
| `defaultHostConfig` | The token-driven host config used when no override is passed. |
| `mergeHostConfig(base, override)` | Deep-merge a partial override onto a base config. |
| `parseAdaptiveCard(payload)` | Validate + normalize an unknown payload. Returns `null` for invalid input. |
| `isAdaptiveCard(value)` | Type guard for `AdaptiveCardPayload`. |
| `isSafeBackgroundUrl(url)` | Refuses `javascript:` and `data:text/html` URIs; allows `https:`, `http:`, `data:image/*`. |
| `validateInput(input, value)` / `validateInputs(inputs, values)` | The same validators the hook runs on submit. |
| `collectInputs(elements, visibilityOverrides)` | Walks an element tree for `associatedInputs: 'auto'` collection. |
| `buildSubmitData(action, card, values, overrides)` | Assemble the `data` payload for a `Submit` / `Execute` action. |
| `registerElement(type, renderer)` | Register a globally-available element renderer. Prefer the per-instance `customElements` prop when possible. |

## Type Exports

| Type | Description |
|------|-------------|
| `AdaptiveCardPayload` | Card root. |
| `AdaptiveCardElement` | Discriminated union of every known element type. |
| `AdaptiveCardCustomElement` | Open `type: string` shape for renderer extensions. Not in the main union to keep narrowing tight. |
| `AdaptiveCardAction` | Discriminated union of every action type. |
| `AdaptiveCardSelectAction` | Subset of actions legal as `selectAction` (no `ShowCard`). |
| `AdaptiveCardInput` | Discriminated union of every input type. |
| `AdaptiveCardActionEvent` | The union of events emitted to `onAction`. |
| `AdaptiveCardSubmitEvent`, `AdaptiveCardExecuteEvent`, `AdaptiveCardOpenUrlEvent`, `AdaptiveCardToggleVisibilityEvent`, `AdaptiveCardShowCardEvent` | Individual event shapes. |
| `AdaptiveCardHostConfig` / `AdaptiveCardHostConfigOverride` | Host config + deep-partial override. |
| `AdaptiveCardInputValue` | `string \| Array<string> \| boolean \| number \| null` — the runtime value an `Input.*` can hold. |
| `ElementRenderer<T>` | `(props: { element: T }) => ReactNode`. |
| `AdaptiveCardProps` / `AdaptiveCardViewProps` | Component props. |

## Security notes

- **No raw HTML** — markdown in `TextBlock` / `FactSet` is rendered with `react-markdown` + `remark-gfm` and the default raw-HTML-disabled config. Card payloads that arrive from LLMs or external bots cannot inject `<script>`.
- **Background-image URL allowlist** — `parseAdaptiveCard` rejects `javascript:` and `data:text/html` URIs in `backgroundImage`. Only `https:`, `http:`, and `data:image/*` resolve.
- **External links** — `Action.OpenUrl` opens in a new tab with `rel="noopener noreferrer"`.

---

# Avatar Select
URL: /docs/web/components/avatar-select

Avatar Select component with multiple variants and sizes.

**Demo:**

```tsx
'use client';

import { useState } from 'react';

import { AvatarSelect } from '@docyrus/ui/components/avatar-select';
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue
} from '@docyrus/ui/primitives/ui/select';
import { Switch } from '@docyrus/ui/primitives/ui/switch';
import { cn } from '@docyrus/ui/primitives/lib/utils';

export function AvatarSelectDemo() {
  type EditorDisplay = 'inline' | 'popover';
  const [editorDisplay, setEditorDisplay] = useState
                  
                    
                  
                
              </div>
              <label className="flex items-center gap-2">
                
                <span className="text-xs">disabled</span>
              </label>
            </div>
          </div>
        </div>
      </div>
      
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-avatar-select
```

**Dependencies:**
- [class-variance-authority](https://www.npmjs.com/package/class-variance-authority)
- [lucide-react](https://www.npmjs.com/package/lucide-react)

## Usage

```tsx
import {
  AvatarSelect
} from "@docyrus/ui/components/avatar-select";

<AvatarSelect
  editorDisplay="inline"
  value={...}
  disabled
  uploadImage={() => {}}
  onChange={() => {}}
  onCommit={() => {}}
/>
```

## EditorDisplay

| EditorDisplay | Description |
|---------------|-------------|
| `inline` | Inline — `space-y-3` |
| `popover` | Popover — `inline-flex` |

## API Reference

| Prop | Type | Default |
|------|------|---------|
| `editorDisplay` | `"inline"` \| `"popover"` | `"default"` |
| `value` | `Partial<AvatarFieldValue> \| null` | — |
| `disabled` | `boolean` | — |
| `uploadImage` | `(file: File) => Promise<AvatarImageValue>` | — |
| `onChange` | `(value: AvatarFieldValue, payload: Record<string, unknown>) => void` | — |
| `onCommit` | `(value: AvatarFieldValue, payload: Record<string, unknown>) => void` | — |
| `className` | `string` | — |

---

# Avatar Thumbnail
URL: /docs/web/components/avatar-thumbnail

Avatar Thumbnail component with multiple variants and sizes.

**Demo:**

```tsx
'use client';
// @custom-demo

import { useState } from 'react';

import { AvatarThumbnail } from '@docyrus/ui/components/avatar-thumbnail';
import { Input } from '@docyrus/ui/primitives/ui/input';
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue
} from '@docyrus/ui/primitives/ui/select';
import { cn } from '@docyrus/ui/primitives/lib/utils';

type Shape = 'rounded' | 'circle' | 'square';

const PRESET_ICONS = [
  { value: 'fal star', label: 'Star' },
  { value: 'fal user', label: 'User' },
  { value: 'fal heart', label: 'Heart' },
  { value: 'fal building', label: 'Building' },
  { value: '🎉', label: 'Emoji: Party' },
  { value: '🚀', label: 'Emoji: Rocket' },
  { value: '', label: 'None (fallback)' }
];

const PRESET_COLORS = [
  { value: '#3b82f6', label: 'Blue' },
  { value: '#10b981', label: 'Green' },
  { value: '#f59e0b', label: 'Amber' },
  { value: '#ef4444', label: 'Red' },
  { value: '#6366f1', label: 'Indigo' },
  { value: '#ec4899', label: 'Pink' },
  { value: '', label: 'None' }
];

export function AvatarThumbnailDemo() {
  const [shape, setShape] = useState
                  
                    
                    
                  
                
              </div>
              <div className="space-y-1.5">
                <span className="text-xs font-medium">Size</span>
                
                  
                    
                    
                    
                    
                  
                
              </div>
              <div className="space-y-1.5">
                <span className="text-xs font-medium">Icon</span>
                
                  
                    ))}
                  
                
              </div>
              <div className="space-y-1.5">
                <span className="text-xs font-medium">Color</span>
                <div className="flex items-center gap-2">
                  <input
                    type="color"
                    value={color || '#000000'}
                    onChange={e => setColor(e.target.value)}
                    className="h-8 w-8 cursor-pointer rounded border border-border" />
                  
                    
                      ))}
                    
                  
                </div>
              </div>
              <div className="space-y-1.5">
                <span className="text-xs font-medium">Image URL</span>
                <Input
                  value={imageUrl}
                  onChange={e => setImageUrl(e.target.value)}
                  placeholder="https://..."
                  className="h-8 w-48 text-xs" />
              </div>
            </div>
          </div>
        </div>
      </div>
      <div className="flex items-center justify-center py-6">
        
      </div>
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-avatar-thumbnail
```

**Dependencies:**
- [class-variance-authority](https://www.npmjs.com/package/class-variance-authority)

## Usage

```tsx
import {
  AvatarThumbnail
} from "@docyrus/ui/components/avatar-thumbnail";

```

## Shape

| Shape | Description |
|-------|-------------|
| `rounded` | Rounded — `rounded-md` |
| `circle` | Circle — `rounded-full` |
| `square` | Square — `rounded-none` |

## API Reference

| Prop | Type | Default |
|------|------|---------|
| `shape` | `"rounded"` \| `"circle"` \| `"square"` | `"default"` |
| `ref` | `Ref<HTMLDivElement>` | — |
| `icon` | `string \| null` | — |
| `color` | `string \| null` | — |
| `image` | `{ signed_url?: string \| null; file_name?: string } \| null` | — |
| `className` | `string` | — |

---

# Awesome Card
URL: /docs/web/components/awesome-card

A card with a hatched-stripe header and an inset content area, perfect for displaying stats and metrics.

**Demo:**

```tsx
'use client';
// @custom-demo

import {
  AwesomeCard,
  AwesomeCardBody,
  AwesomeCardExpandedBody,
  AwesomeCardHeader,
  AwesomeCardIcon,
  AwesomeCardTitle,
  AwesomeCardTrend,
  AwesomeCardValue
} from '@docyrus/ui/components/awesome-card';

import {
  Activity, DollarSign, ShoppingCart, Users
} from 'lucide-react';

export function AwesomeCardDemo() {
  return (
    <div className="grid w-full gap-4 sm:grid-cols-2 lg:grid-cols-3">
      
          
        
        
          
        
      

      
          
        
        
          
        
      

      
          
        
        
          
        
      

      <div className="self-start">
        
            
          
          
            
          
        
      </div>

      
          
        
        
          
        
        
      

      
          
        
        
          
        
        
      
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-awesome-card
```

## Usage

```tsx
import {
  AwesomeCard,
  AwesomeCardHeader,
  AwesomeCardTitle,
  AwesomeCardIcon,
  AwesomeCardBody,
  AwesomeCardValue,
  AwesomeCardTrend
} from "@docyrus/ui/components/awesome-card";

    
  
  
    
  

```

## Components

| Component | Description |
|-----------|-------------|
| `AwesomeCard` | Root container with diagonal stripe background |
| `AwesomeCardHeader` | Header section with flex layout |
| `AwesomeCardTitle` | Title text element |
| `AwesomeCardIcon` | Icon container in the header |
| `AwesomeCardBody` | Inset content area with card background |
| `AwesomeCardValue` | Large value display (e.g. metrics, stats) |
| `AwesomeCardTrend` | Trend indicator with positive/negative coloring |

## API Reference

### AwesomeCardTrend

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `positive` | `boolean` | — | When `true`, text is green. When `false`, text is red. When `undefined`, uses muted color. |
| `className` | `string` | — | Additional CSS classes |

---

# Awesome Dialog
URL: /docs/web/components/awesome-dialog

Awesome Dialog component.

**Demo:**

```tsx
'use client';
// @custom-demo

import {
  type ReactNode,
  useCallback,
  useState
} from 'react';

import {
  type ToolbarMenuItem,
  AwesomeDialog,
  AwesomeDialogBody,
  AwesomeDialogFooter,
  AwesomeDialogHeader,
  AwesomeDialogToolbar,
  GlobalDialogBar,
  GlobalDialogProvider
} from '@docyrus/ui/components/awesome-dialog';
import { type EnumOption } from '@docyrus/ui/components/form-fields';
import {
  EditableRecordDetail,
  EditableRecordDetailField,
  type FieldChange,
  type RecordDetailField
} from '@docyrus/ui/components/editable-record-detail';

import { Button } from '@docyrus/ui/primitives/ui/button';
import { Badge } from '@docyrus/ui/primitives/ui/badge';
import { Input } from '@docyrus/ui/primitives/ui/input';
import { Label } from '@docyrus/ui/primitives/ui/label';
import { Textarea } from '@docyrus/ui/primitives/ui/textarea';
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue
} from '@docyrus/ui/primitives/ui/select';
import { Switch } from '@docyrus/ui/primitives/ui/switch';

type ContainerType = 'modal' | 'sheet' | 'drawer';
type SideType = 'left' | 'right' | 'top' | 'bottom';
type SizeType = 'sm' | 'default' | 'lg' | 'xl' | 'full';
type PatternType = 'stripes' | 'dots' | 'grid' | 'crosshatch' | 'zigzag';

const toolbarMenus: ToolbarMenuItem[] = [
  {
    label: 'File',
    items: [
      { label: 'New', shortcut: '⌘N', onClick: () => {} },
      { label: 'Open', shortcut: '⌘O', onClick: () => {} },
      { label: 'Save', shortcut: '⌘S', onClick: () => {} },
      { separator: true, label: '' },
      { label: 'Export as PDF', onClick: () => {} },
      { label: 'Print', shortcut: '⌘P', onClick: () => {} }
    ]
  },
  {
    label: 'Edit',
    items: [
      { label: 'Undo', shortcut: '⌘Z', onClick: () => {} },
      { label: 'Redo', shortcut: '⇧⌘Z', onClick: () => {} },
      { separator: true, label: '' },
      { label: 'Cut', shortcut: '⌘X', onClick: () => {} },
      { label: 'Copy', shortcut: '⌘C', onClick: () => {} },
      { label: 'Paste', shortcut: '⌘V', onClick: () => {} }
    ]
  },
  {
    label: 'View',
    items: [
      { label: 'Zoom In', shortcut: '⌘+', onClick: () => {} },
      { label: 'Zoom Out', shortcut: '⌘-', onClick: () => {} },
      { separator: true, label: '' },
      { label: 'Toggle Sidebar', shortcut: '⌘B', onClick: () => {} },
      { label: 'Full Screen', shortcut: '⌘⇧F', onClick: () => {} }
    ]
  }
];

const RECORD_PRIORITY_OPTIONS: Array
          
        </div>
        <div className="space-y-2">
          
          
        </div>
      </div>
      <div className="space-y-2">
        
        
          
            
            
            
          
        
      </div>
      <div className="space-y-2">
        
        
          
            
            
            
            
          
        
      </div>
      <div className="space-y-2">
        
        
      </div>
      <div className="flex items-center gap-2">
        
        
      </div>
    </div>
  );
}

function SectionHeader({ children }: { children: ReactNode }) {
  return (
    <div className="col-span-full">
      <h3 className="text-base font-semibold tracking-tight">{children}</h3>
      <div className="mt-1 h-px bg-border" />
    </div>
  );
}

function DialogButton({
  label,
  container,
  side,
  size,
  patternStyle,
  pattern = true,
  fullscreenable = false,
  withToolbar = false,
  withFooter = true,
  headerProps
}: {
  label: string;
  container?: ContainerType;
  side?: SideType;
  size?: SizeType;
  patternStyle?: PatternType;
  pattern?: boolean;
  fullscreenable?: boolean;
  withToolbar?: boolean;
  withFooter?: boolean;
  headerProps?: {
    title?: string;
    description?: string;
    icon?: string;
    avatar?: { name?: string; color?: string };
    headerButtons?: ReactNode;
  };
}) {
  const [open, setOpen] = useState(false);

  return (
    <>
      
      
        {withFooter && (
          
            
          
        )}
      
    </>
  );
}

function WithFormDialogButton({
  label,
  container,
  side,
  size,
  patternStyle,
  headerProps
}: {
  label: string;
  container?: ContainerType;
  side?: SideType;
  size?: SizeType;
  patternStyle?: PatternType;
  headerProps?: {
    title?: string;
    description?: string;
    icon?: string;
  };
}) {
  const [open, setOpen] = useState(false);

  return (
    <>
      
      
        
          
        
      
    </>
  );
}

function EditableRecordDetailDrawerButton() {
  const [open, setOpen] = useState(false);
  const [record, setRecord] = useState(INITIAL_RECORD);

  const handleSave = useCallback(
    (_: Array
      } />
        
        
      
    </>
  );
}

export function AwesomeDialogDemo() {
  const [globalSettingsOpen, setGlobalSettingsOpen] = useState(false);
  const [globalHelpOpen, setGlobalHelpOpen] = useState(false);

  return (
    <div className="grid w-full gap-6">

      {/* --- Container Types --- */}
      
      <div className="grid gap-3 sm:grid-cols-2 lg:grid-cols-3">
        
        
        
        
        
        
        
      </div>

      {/* --- Sizes --- */}
      
      <div className="grid gap-3 sm:grid-cols-2 lg:grid-cols-3">
        
        
        
        
        
      </div>

      {/* --- Pattern Styles --- */}
      
      <div className="grid gap-3 sm:grid-cols-2 lg:grid-cols-3">
        
        
        
        
        
        
      </div>

      {/* --- Header, Footer, & Toolbar --- */}
      
      <div className="grid gap-3 sm:grid-cols-2 lg:grid-cols-3">
        
        
        
                
              </div>
            )
          }} />
        
        
        
          }} />
      </div>

      {/* --- With Form --- */}
      
      <div className="grid gap-3 sm:grid-cols-2 lg:grid-cols-3">
        
        
        
      </div>

      
      <div className="grid gap-3 sm:grid-cols-2 lg:grid-cols-3">
        
      </div>

      {/* --- Fullscreen --- */}
      
      <div className="grid gap-3 sm:grid-cols-2 lg:grid-cols-3">
        
        
      </div>

      {/* --- Global Dialog Provider (Minimizable) --- */}
      
      
          
        </div>

        
          
            
          
        

        
        

        
      

    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-awesome-dialog
```

**Dependencies:**
- [lucide-react](https://www.npmjs.com/package/lucide-react)
- [radix-ui](https://www.npmjs.com/package/radix-ui)
- [@types/react](https://www.npmjs.com/package/@types/react)
- [@types/react-dom](https://www.npmjs.com/package/@types/react-dom)
- [vaul](https://www.npmjs.com/package/vaul)

## Usage

```tsx
import {
  AwesomeDialog
} from "@docyrus/ui/components/awesome-dialog";
import type {
  AwesomeDialogProps,
  AwesomeDialogHeaderProps,
  AwesomeDialogBodyProps,
  AwesomeDialogFooterProps,
  AwesomeDialogToolbarProps,
  DialogContainer,
  DialogSide,
  DialogSize,
  DialogState,
  GlobalDialogContextValue,
  GlobalDialogProviderProps,
  ToolbarMenuItem,
  ToolbarMenuAction
} from "@docyrus/ui/components/awesome-dialog";

```

## API Reference

| Prop | Type | Default |
|------|------|---------|
| `className` | `string` | — |

## Components

| Component | Description |
|-----------|-------------|
| `AwesomeDialog` | Public export |
| `AwesomeDialogBody` | Internal — `awesome-dialog-body.tsx` |
| `AwesomeDialogContent` | Internal — `awesome-dialog-content.tsx` |
| `AwesomeDialogFooter` | Internal — `awesome-dialog-footer.tsx` |
| `AwesomeDialogHeader` | Internal — `awesome-dialog-header.tsx` |
| `AwesomeDialogToolbar` | Internal — `awesome-dialog-toolbar.tsx` |
| `GlobalDialogBar` | Internal — `global-dialog-bar.tsx` |
| `DrawerContainer` | Internal — `containers/drawer-container.tsx` |
| `ModalContainer` | Internal — `containers/modal-container.tsx` |
| `SheetContainer` | Internal — `containers/sheet-container.tsx` |
| `AwesomeDialogProvider` | Internal — `contexts/dialog-context.tsx` |
| `GlobalDialogProvider` | Internal — `contexts/global-dialog-context.tsx` |

## Type Exports

| Type | Description |
|------|-------------|
| `AwesomeDialogProps` | — |
| `AwesomeDialogHeaderProps` | — |
| `AwesomeDialogBodyProps` | — |
| `AwesomeDialogFooterProps` | — |
| `AwesomeDialogToolbarProps` | — |
| `DialogContainer` | — |
| `DialogSide` | — |
| `DialogSize` | — |
| `DialogState` | — |
| `GlobalDialogContextValue` | — |
| `GlobalDialogProviderProps` | — |
| `ToolbarMenuItem` | — |
| `ToolbarMenuAction` | — |

## Type Reference

### AwesomeDialogProps

| Field | Type | Description |
|-------|------|-------------|
| `open` | `boolean` | — |
| `onOpenChange` | `(open: boolean) => void` | — |
| `children` | `ReactNode` | — |
| `container` | `DialogContainer` | — |
| `side` | `DialogSide` | — |
| `size` | `DialogSize` | — |
| `pattern` | `boolean` | — |
| `patternStyle` | `PatternStyle` | — |
| `resizable` | `boolean` | — |
| `fullscreenable` | `boolean` | — |
| `defaultFullscreen` | `boolean` | — |
| `minimizable` | `boolean` | — |
| `preventOutsideClose` | `boolean` | — |
| `dialogId` | `string` | — |
| `className` | `string` | — |

### AwesomeDialogHeaderProps

| Field | Type | Description |
|-------|------|-------------|
| `children` | `ReactNode` | — |
| `className` | `string` | — |
| `title` | `string` | — |
| `description` | `string` | — |
| `icon` | `string` | — |
| `iconLib` | `string` | — |
| `name` | `string` | — |
| `color` | `string` | — |
| `icon` | `string` | — |
| `image` | `string` | — |
| `closable` | `boolean` | — |
| `headerButtons` | `ReactNode` | — |
| `onClose` | `() => void` | — |

### AwesomeDialogBodyProps

| Field | Type | Description |
|-------|------|-------------|
| `children` | `ReactNode` | — |
| `className` | `string` | — |

### AwesomeDialogFooterProps

| Field | Type | Description |
|-------|------|-------------|
| `children` | `ReactNode` | — |
| `className` | `string` | — |

### AwesomeDialogToolbarProps

| Field | Type | Description |
|-------|------|-------------|
| `menus` | `ToolbarMenuItem[]` | — |
| `children` | `ReactNode` | — |
| `className` | `string` | — |

### DialogContainer

`"modal"` | `"sheet"` | `"drawer"`

### DialogSide

`"left"` | `"right"` | `"top"` | `"bottom"`

### DialogSize

`"sm"` | `"default"` | `"lg"` | `"xl"` | `"full"`

### DialogState

| Field | Type | Description |
|-------|------|-------------|
| `dialogId` | `string` | — |
| `minimized` | `boolean` | — |
| `fullscreen` | `boolean` | — |
| `zIndex` | `number` | — |
| `title` | `string` | — |
| `icon` | `string` | — |

### GlobalDialogContextValue

| Field | Type | Description |
|-------|------|-------------|
| `dialogs` | `Map<string, DialogState>` | — |
| `register` | `(id: string, meta: { title?: string; icon?: string }) => void` | — |
| `unregister` | `(id: string) => void` | — |
| `minimize` | `(id: string) => void` | — |
| `restore` | `(id: string) => void` | — |
| `bringToFront` | `(id: string) => void` | — |
| `toggleFullscreen` | `(id: string) => void` | — |
| `getZIndex` | `(id: string) => number` | — |
| `isMinimized` | `(id: string) => boolean` | — |
| `isFullscreen` | `(id: string) => boolean` | — |
| `minimizedDialogs` | `DialogState[]` | — |

### GlobalDialogProviderProps

| Field | Type | Description |
|-------|------|-------------|
| `children` | `ReactNode` | — |
| `persist` | `boolean` | — |
| `storageKey` | `string` | — |

### ToolbarMenuItem

| Field | Type | Description |
|-------|------|-------------|
| `label` | `string` | — |
| `items` | `ToolbarMenuAction[]` | — |

### ToolbarMenuAction

| Field | Type | Description |
|-------|------|-------------|
| `label` | `string` | — |
| `shortcut` | `string` | — |
| `disabled` | `boolean` | — |
| `separator` | `boolean` | — |
| `onClick` | `() => void` | — |

---

# Awesome Stats
URL: /docs/web/components/awesome-stats

Data-driven metric cards with grid, flex, and animated tabs layouts.

**Demo:**

```tsx
'use client';
// @custom-demo

import { useState } from 'react';

import {
  AwesomeStats,
  type AwesomeStatItem,
  type AwesomeStatsLayout
} from '@docyrus/ui/components/awesome-stats';
import { Button } from '@docyrus/ui/primitives/ui/button';

import {
  DollarSign,
  Package,
  Users
} from 'lucide-react';

type LayoutMode = 'grid' | 'scroll' | 'tabs';
type ClickMode = 'off' | 'card' | 'title';

const DEMO_ITEMS: AwesomeStatItem[] = [
  {
    id: 'revenue',
    eyebrow: 'Growth',
    title: 'Monthly revenue',
    subtitle: 'Closed won across all active pipelines',
    icon: ,
    color: 'emerald-500',
    value: 2840000,
    format: {
      style: 'currency',
      currency: 'USD',
      notation: 'compact',
      maximumFractionDigits: 1
    },
    comparison: {
      previousValue: 2470000,
      period: 'last-month'
    },
    menuItems: [
      {
        id: 'inspect',
        label: 'Inspect revenue',
        onSelect: stat => console.info('Inspect stat', stat)
      },
      {
        id: 'pin',
        label: 'Pin card',
        onSelect: stat => console.info('Pin stat', stat)
      }
    ],
    miniChart: {
      type: 'area',
      data: [
        1.72,
        1.98,
        2.14,
        2.08,
        2.31,
        2.54,
        2.84
      ],
      dataKey: 'value',
      position: 'right'
    }
  },
  {
    id: 'accounts',
    eyebrow: 'Pipeline',
    title: 'Active accounts',
    subtitle: 'Paying customers with usage in the last 30 days',
    icon: ,
    color: 'blue-500',
    value: 1284,
    format: {
      notation: 'compact',
      maximumFractionDigits: 1
    },
    comparison: {
      previousValue: 1198,
      period: 'last-week'
    },
    miniChart: {
      type: 'sparkline',
      data: [
        920,
        980,
        1015,
        1090,
        1160,
        1210,
        1284
      ],
      position: 'right'
    }
  },
  {
    id: 'returns',
    eyebrow: 'Health',
    title: 'Return rate',
    subtitle: 'Lower is better for this metric',
    icon: 'fal rotate-left',
    color: 'rose-500',
    value: 3.4,
    format: {
      style: 'percent',
      maximumFractionDigits: 1
    },
    comparison: {
      previousValue: 4.2,
      period: 'last-month',
      positiveDirection: 'down'
    },
    menuItems: [
      {
        id: 'benchmark',
        label: 'Open benchmark',
        onSelect: stat => console.info('Benchmark stat', stat)
      },
      {
        id: 'archive',
        label: 'Archive card',
        variant: 'destructive',
        onSelect: stat => console.info('Archive stat', stat)
      }
    ],
    miniChart: {
      type: 'area',
      data: [
        5.1,
        4.7,
        4.4,
        4.2,
        4.1,
        3.8,
        3.4
      ],
      position: 'bottom'
    }
  },
  {
    id: 'orders',
    eyebrow: 'Ops',
    title: 'Fulfilled orders',
    subtitle: 'Shipped successfully this week',
    icon: ,
    color: 'amber-500',
    value: 8492,
    format: {
      notation: 'compact'
    },
    unitLabel: 'orders',
    comparison: {
      previousValue: 7784,
      period: 'yesterday'
    },
    miniChart: {
      type: 'bar',
      data: [
        5.8,
        6.1,
        6.4,
        6.2,
        7.0,
        7.6,
        8.49
      ],
      position: 'right'
    }
  }
];

export function AwesomeStatsDemo() {
  const [layoutMode, setLayoutMode] = useState
          
          
        </div>

        <div className="flex flex-wrap items-center gap-2">
          <span className="text-xs font-medium tracking-[0.14em] text-muted-foreground uppercase">
            Card shell
          </span>
          
          
        </div>

        <div className="flex flex-wrap items-center gap-2">
          <span className="text-xs font-medium tracking-[0.14em] text-muted-foreground uppercase">
            Click target
          </span>
          
          
          
        </div>
      </div>

      {lastClicked ? (
        <div className="rounded-lg border bg-muted/30 px-3 py-2 text-sm text-muted-foreground">
          Last clicked: <span className="font-medium text-foreground">{lastClicked}</span>
        </div>
      ) : null}

      <AwesomeStats
        className="w-full min-w-0"
        items={DEMO_ITEMS}
        layout={layout}
        cardVariant={cardVariant}
        sortable
        clickTarget={clickMode === 'off' ? undefined : clickMode}
        onItemClick={clickMode === 'off' ? undefined : item => setLastClicked(typeof item.title === 'string' ? item.title : item.id)}
        awesomeCardProps={cardVariant === 'awesome' ? {
          pattern: true,
          patternStyle: 'stripes'
        } : undefined} />
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-awesome-stats
```

## Usage

```tsx
import { AwesomeStats } from '@docyrus/ui/components/awesome-stats';

const items = [
  {
    id: 'revenue',
    eyebrow: 'Growth',
    title: 'Monthly revenue',
    value: 2840000,
    format: {
      style: 'currency',
      currency: 'USD',
      notation: 'compact',
      maximumFractionDigits: 1
    },
    comparison: {
      previousValue: 2470000,
      period: 'last-month'
    },
    miniChart: {
      type: 'area',
      data: [1.72, 1.98, 2.14, 2.08, 2.31, 2.54, 2.84],
      position: 'right'
    }
  },
  {
    id: 'returns',
    title: 'Return rate',
    value: 3.4,
    format: { style: 'percent', maximumFractionDigits: 1 },
    comparison: {
      previousValue: 4.2,
      period: 'last-month',
      positiveDirection: 'down'
    },
    miniChart: {
      type: 'bar',
      data: [5.1, 4.7, 4.4, 4.2, 4.1, 3.8, 3.4],
      position: 'bottom'
    }
  }
];

```

## Layouts

| Layout | Config | Use when |
|--------|--------|----------|
| `grid` | `columns`, optional `maxCardWidth`, optional `gap` | You want a responsive dashboard-style stat grid. |
| `flex` | `cardWidth`, `behavior`, optional `gap` | You need fixed-width cards that either wrap or scroll horizontally. |
| `tabs` | optional `defaultTabId` | You want multiple stats to share a single card surface with animated tab switching. |

## Card Features

| Prop | Purpose |
|------|---------|
| `eyebrow` | Small light label above the title. |
| `icon` | Supports either a React node or a Docyrus icon string such as `"fal chart-line"`. |
| `color` | Tailwind-style color token or raw CSS color used for icon and chart accents. |
| `comparison` | Computes the delta against a previous period and styles it as positive or negative. |
| `miniChart` | Renders `sparkline`, `bar`, or `area` charts at the right edge or docked to the bottom. |
| `unitLabel` | Appends a small unit label next to the formatted value. |
| `sortable` | Enables drag-and-drop reordering for cards and tab items. |
| `onClick` | Per-item click handler. Takes precedence over the top-level `onItemClick`. |

## Awesome Card Mode

Set `cardVariant="awesome"` to render every stat with `AwesomeCard`. Use `awesomeCardProps` for the safe shared subset:

```tsx

```

## Clickable Cards

Pass `onItemClick` to make every card actionable, or set a per-item `onClick` for individual handlers (per-item wins when both are present). Use `clickTarget` to choose what the user clicks:

| `clickTarget` | Behavior |
|---------------|----------|
| `card` (default) | The entire card is clickable — `cursor-pointer` over the whole surface, keyboard-focusable (Enter / Space activate it). |
| `title` | Only the title is clickable and underlines on hover. |

```tsx
<AwesomeStats
  items={items}
  clickTarget="card"
  onItemClick={(item) => router.push(`/metrics/${item.id}`)}
  layout={{ type: 'grid', columns: 2 }}
/>

// Or per-item handlers with a title-only target:
const items = [
  {
    id: 'revenue',
    title: 'Monthly revenue',
    value: 2840000,
    onClick: (item) => openDrawer(item.id)
  }
];

```

The card menu button and drag handle stop propagation, so they never trigger the card/title click handler.

---

# Calendar
URL: /docs/web/components/calendar

Calendar component.

**Demo:**

```tsx
'use client';
// @custom-demo

import { lazy, useMemo, useState } from 'react';

import { type TCalendarView } from '@docyrus/ui/components/calendar';
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue
} from '@docyrus/ui/primitives/ui/select';
import { Switch } from '@docyrus/ui/primitives/ui/switch';
import { cn } from '@docyrus/ui/primitives/lib/utils';

import { PropControls } from '@/components/prop-controls';
import { useDemoData } from '@/data/calendar-data';

const Calendar = lazy(() => import('@docyrus/ui/components/calendar').then(m => ({ default: m.Calendar })));

export function CalendarDemo() {
  type Variant = 'default' | 'bordered' | 'compact';
  const [variant, setVariant] = useState
                  
                    
                    
                  
                
              </div>
              <div className="space-y-1.5">
                <span className="text-xs font-medium">Size</span>
                
                  
                    
                    
                  
                
              </div>
              <div className="space-y-1.5">
                <span className="text-xs font-medium">defaultView</span>
                
                  
                    
                    
                    
                    
                  
                
              </div>
              <label className="flex items-center gap-2">
                
                <span className="text-xs">visibleViews (month/week/day only)</span>
              </label>
              
            </div>
          </div>
        </div>
      </div>
      
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-calendar
```

**Dependencies:**
- [motion](https://www.npmjs.com/package/motion)
- [@emotion/is-prop-valid](https://www.npmjs.com/package/@emotion/is-prop-valid)
- [date-fns](https://www.npmjs.com/package/date-fns)
- [class-variance-authority](https://www.npmjs.com/package/class-variance-authority)
- [sonner](https://www.npmjs.com/package/sonner)
- [@hookform/resolvers](https://www.npmjs.com/package/@hookform/resolvers)
- [react-hook-form](https://www.npmjs.com/package/react-hook-form)
- [lucide-react](https://www.npmjs.com/package/lucide-react)
- [re-resizable](https://www.npmjs.com/package/re-resizable)
- [zod](https://www.npmjs.com/package/zod)

## Usage

```tsx
import {
  Calendar
} from "@docyrus/ui/components/calendar";
import type {
  CalendarProps,
  CalendarProviderProps,
  TCalendarView,
  TEventColor,
  IEvent,
  IUser,
  ICalendarCell,
  CalendarFilterItem
} from "@docyrus/ui/components/calendar";

<Calendar
  variant="default"
  size="sm"
  ref={...}
  events={[]}
  users={[]}
  defaultView="month"
  onCreateEvent={() => {}}
  onEventCreate={() => {}}
  onEventUpdate={() => {}}
  onEventDelete={() => {}}
  onEventClick={() => {}}
  onDaySelect={() => {}}
  onSlotClick={() => {}}
  onVisibleRangeChange={() => {}}
  onEventDrop={() => {}}
  hideAddButton
  hideHeaderAddButton
  hideCellAddButton
  hideUserSelect
  hideSettings
  hideFilter
  addButtonLabel="..."
  hideEventCount
  eventCountLabel="..."
  visibleViews="day"
  filterItems={CalendarFilterItem[]}
  onFilterChange={() => {}}
  renderFilterSelect={() => {}}
  sidebarContent={...}
  renderEventBadge={() => {}}
  searchPlaceholder="..."
  weekStartsOn={...}
  cellMinHeight={...}
  cellMinWidth={...}
  hourSlotHeight={...}
  startHour={0}
  endHour={0}
  disableHoverHighlight
  hoverHighlightClassName="..."
/>
```

## Variants

| Variant | Description |
|---------|-------------|
| `default` | Default style |
| `bordered` | Bordered — `border-2` |
| `compact` | Compact — `text-xs` |

## Sizes

| Size | Description |
|------|-------------|
| `sm` | Small — `max-w-3xl mx-auto` |
| `default` | Default — `max-w-6xl mx-auto` |
| `lg` | Large |

## API Reference

| Prop | Type | Default |
|------|------|---------|
| `variant` | `"default"` \| `"bordered"` \| `"compact"` | `"default"` |
| `size` | `"sm"` \| `"default"` \| `"lg"` | `"default"` |
| `ref` | `Ref<HTMLDivElement>` | — |
| `events` | `Array<IEvent>` | `[]` |
| `users` | `Array<IUser>` | `[]` |
| `isLoading` | `boolean` | `false` |
| `defaultView` | `TCalendarView` | `'month'` |
| `onCreateEvent` | `(date: Date) => void` | — |
| `onEventCreate` | `(event: IEvent) => void` | — |
| `onEventUpdate` | `(event: IEvent) => void` | — |
| `onEventDelete` | `(eventId: number) => void` | — |
| `onEventClick` | `(event: IEvent) => void` | — |
| `onDaySelect` | `(date: Date) => void` | — |
| `onSlotClick` | `(start: Date, end: Date) => void` | — |
| `onVisibleRangeChange` | `(range: { start: Date; end: Date }, view: TCalendarView) => void` | — |
| `onEventDrop` | `(event: IEvent, newStart: Date, newEnd: Date) => void` | — |
| `hideAddButton` | `boolean` | — |
| `hideHeaderAddButton` | `boolean` | — |
| `hideCellAddButton` | `boolean` | — |
| `hideUserSelect` | `boolean` | — |
| `hideSettings` | `boolean` | — |
| `hideFilter` | `boolean` | — |
| `addButtonLabel` | `string` | — |
| `hideEventCount` | `boolean` | — |
| `eventCountLabel` | `string` | — |
| `visibleViews` | `Array<TCalendarView>` | — |
| `filterItems` | `Array<CalendarFilterItem>` | — |
| `onFilterChange` | `(id: string) => void` | — |
| `renderFilterSelect` | `(context: any) => ReactNode` | — |
| `sidebarContent` | `ReactNode` | — |
| `renderEventBadge` | `(event: IEvent, defaultBadge: ReactNode) => ReactNode` | — |
| `searchPlaceholder` | `string` | — |
| `weekStartsOn` | `TWeekStartsOn` | — |
| `cellMinHeight` | `number \| string` | — |
| `cellMinWidth` | `number \| string` | — |
| `hourSlotHeight` | `number \| string` | — |
| `startHour` | `number` | — |
| `endHour` | `number` | — |
| `disableHoverHighlight` | `boolean` | — |
| `hoverHighlightClassName` | `string` | — |
| `className` | `string` | — |

## Components

| Component | Description |
|-----------|-------------|
| `Calendar` | Public export |
| `CalendarBody` | Internal — `calendar-body.tsx` |
| `CalendarSidebar` | Internal — `calendar-sidebar.tsx` |
| `CalendarProvider` | Internal — `contexts/calendar-context.tsx` |
| `DndProvider` | Internal — `contexts/dnd-context.tsx` |
| `AddEditEventDialog` | Internal — `dialogs/add-edit-event-dialog.tsx` |
| `EventDetailsDialog` | Internal — `dialogs/event-details-dialog.tsx` |
| `EventListDialog` | Internal — `dialogs/events-list-dialog.tsx` |
| `DraggableEvent` | Internal — `dnd/draggable-event.tsx` |
| `DroppableArea` | Internal — `dnd/droppable-area.tsx` |
| `ResizableEvent` | Internal — `dnd/resizable-event.tsx` |
| `CalendarHeader` | Internal — `header/calendar-header.tsx` |
| `DateNavigator` | Internal — `header/date-navigator.tsx` |
| `TodayButton` | Internal — `header/today-button.tsx` |
| `UserSelect` | Internal — `header/user-select.tsx` |
| `Settings` | Internal — `settings/settings.tsx` |
| `CalendarHeaderSkeleton` | Internal — `skeletons/calendar-header-skeleton.tsx` |
| `CalendarSkeleton` | Internal — `skeletons/calendar-skeleton.tsx` |
| `DayViewSkeleton` | Internal — `skeletons/day-view-skeleton.tsx` |
| `MonthViewSkeleton` | Internal — `skeletons/month-view-skeleton.tsx` |
| `WeekViewSkeleton` | Internal — `skeletons/week-view-skeleton.tsx` |
| `YearViewSkeleton` | Internal — `skeletons/year-view-skeleton.tsx` |

## Type Exports

| Type | Description |
|------|-------------|
| `CalendarProps` | — |
| `CalendarProviderProps` | — |
| `TCalendarView` | — |
| `TEventColor` | — |
| `IEvent` | — |
| `IUser` | — |
| `ICalendarCell` | — |
| `CalendarFilterItem` | — |

## Type Reference

### CalendarProps

| Field | Type | Description |
|-------|------|-------------|
| `ref` | `Ref<HTMLDivElement>` | — |
| `events` | `Array<IEvent>` | — |
| `users` | `Array<IUser>` | — |
| `isLoading` | `boolean` | — |
| `defaultView` | `TCalendarView` | — |
| `variant` | `'default' \| 'bordered' \| 'compact'` | — |
| `size` | `'sm' \| 'default' \| 'lg'` | — |
| `onCreateEvent` | `(date: Date) => void` | — |
| `onEventCreate` | `(event: IEvent) => void` | — |
| `onEventUpdate` | `(event: IEvent) => void` | — |
| `onEventDelete` | `(eventId: number) => void` | — |
| `onEventClick` | `(event: IEvent) => void` | — |
| `onDaySelect` | `(date: Date) => void` | — |
| `onSlotClick` | `(start: Date, end: Date) => void` | — |
| `onVisibleRangeChange` | `(range: { start: Date; end: Date }, view: TCalendarView) => void` | — |
| `onEventDrop` | `(event: IEvent, newStart: Date, newEnd: Date) => void` | — |
| `hideAddButton` | `boolean` | — |
| `hideHeaderAddButton` | `boolean` | — |
| `hideCellAddButton` | `boolean` | — |
| `hideUserSelect` | `boolean` | — |
| `hideSettings` | `boolean` | — |
| `hideFilter` | `boolean` | — |
| `addButtonLabel` | `string` | — |
| `hideEventCount` | `boolean` | — |
| `eventCountLabel` | `string` | — |
| `visibleViews` | `Array<TCalendarView>` | — |
| `filterItems` | `Array<CalendarFilterItem>` | — |
| `onFilterChange` | `(id: string) => void` | — |
| `renderFilterSelect` | `(context: any) => ReactNode` | — |
| `sidebarContent` | `ReactNode` | — |
| `renderEventBadge` | `(event: IEvent, defaultBadge: ReactNode) => ReactNode` | — |
| `searchPlaceholder` | `string` | — |
| `weekStartsOn` | `TWeekStartsOn` | — |
| `cellMinHeight` | `number \| string` | — |
| `cellMinWidth` | `number \| string` | — |
| `hourSlotHeight` | `number \| string` | — |
| `startHour` | `number` | — |
| `endHour` | `number` | — |
| `disableHoverHighlight` | `boolean` | — |
| `hoverHighlightClassName` | `string` | — |

### TCalendarView

`"day"` | `"week"` | `"month"` | `"year"` | `"agenda"`

### TEventColor

`"blue"`

### IEvent

| Field | Type | Description |
|-------|------|-------------|
| `id` | `number` | — |
| `startDate` | `string` | — |
| `endDate` | `string` | — |
| `title` | `string` | — |
| `color` | `TEventColor` | — |
| `description` | `string` | — |
| `user` | `IUser` | — |

### IUser

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | — |
| `name` | `string` | — |
| `picturePath` | `string \| null` | — |

### ICalendarCell

| Field | Type | Description |
|-------|------|-------------|
| `day` | `number` | — |
| `currentMonth` | `boolean` | — |
| `date` | `Date` | — |

### CalendarFilterItem

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | — |
| `label` | `string` | — |
| `image` | `string \| null` | — |

---

# Comments Panel
URL: /docs/web/components/comments-panel

Comments Panel component.

**Demo:**

```tsx
'use client';
// @custom-demo

import { useState } from 'react';

import { CommentsPanel } from '@docyrus/ui/components/comments-panel';
import { Button } from '@docyrus/ui/primitives/ui/button';
import { cn } from '@docyrus/ui/primitives/lib/utils';

import { PropControls } from '@/components/prop-controls';
import { useDemoData } from '@/data/comments-panel-data';

export function CommentsPanelDemo() {
  const { props, controls, actions } = useDemoData();
  const [open, setOpen] = useState(false);

  return (
    <div className="w-full">
      <div className="mb-3 flex justify-end">
        <button
          type="button"
          className="inline-flex items-center gap-1.5 rounded-md border border-border bg-background px-3 py-1.5 text-sm font-medium transition-colors hover:bg-accent"
          onClick={() => setOpen(prev => !prev)}>
          <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M12.22 2h-.44a2 2 0 0 0-2 2v.18a2 2 0 0 1-1 1.73l-.43.25a2 2 0 0 1-2 0l-.15-.08a2 2 0 0 0-2.73.73l-.22.38a2 2 0 0 0 .73 2.73l.15.1a2 2 0 0 1 1 1.72v.51a2 2 0 0 1-1 1.74l-.15.09a2 2 0 0 0-.73 2.73l.22.38a2 2 0 0 0 2.73.73l.15-.08a2 2 0 0 1 2 0l.43.25a2 2 0 0 1 1 1.73V20a2 2 0 0 0 2 2h.44a2 2 0 0 0 2-2v-.18a2 2 0 0 1 1-1.73l.43-.25a2 2 0 0 1 2 0l.15.08a2 2 0 0 0 2.73-.73l.22-.39a2 2 0 0 0-.73-2.73l-.15-.08a2 2 0 0 1-1-1.74v-.5a2 2 0 0 1 1-1.74l.15-.09a2 2 0 0 0 .73-2.73l-.22-.38a2 2 0 0 0-2.73-.73l-.15.08a2 2 0 0 1-2 0l-.43-.25a2 2 0 0 1-1-1.73V4a2 2 0 0 0-2-2z" /><circle cx="12" cy="12" r="3" /></svg>
          Configure
          <svg xmlns="http://www.w3.org/2000/svg" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" className={cn('transition-transform duration-200', open && 'rotate-180')}><path d="m6 9 6 6 6-6" /></svg>
        </button>
      </div>
      <div
        className={cn(
          'grid transition-[grid-template-rows] duration-300 ease-in-out',
          open ? 'grid-rows-[1fr]' : 'grid-rows-[0fr]'
        )}>
        <div className="overflow-hidden">
          <div className="mb-4 rounded-lg border border-border bg-muted/30 p-4 grid gap-6">
            
            <div className="mt-3 flex flex-wrap gap-2">
              
              
              
            </div>
          </div>
        </div>
      </div>
      
    </div>
  );
}
```

The composer supports **`@` user mentions**, an **emoji picker**, and a **rich-formatting toggle** (a plain textarea by default, switching to the markdown editor on demand — Teams-style). Comments are stored and rendered as markdown regardless of which mode authored them, so mentions and emoji round-trip everywhere.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-comments-panel
```

**Dependencies:**
- [react-markdown](https://www.npmjs.com/package/react-markdown)
- [remark-gfm](https://www.npmjs.com/package/remark-gfm)
- [date-fns](https://www.npmjs.com/package/date-fns)
- [lucide-react](https://www.npmjs.com/package/lucide-react)

Composes the [Emoji Picker](/docs/web/components/emoji-picker) and Simple Markdown Editor components — the CLI installs them automatically as registry dependencies.

## Usage

```tsx
import { CommentsPanel } from "@docyrus/ui/components/comments-panel";
import type { CommentsPanelProps } from "@docyrus/ui/components/comments-panel";

const comments: CommentsPanelProps['comments'] = [
  { id: "c-1", message: "Looks good to me.", attachments: null, created_on: "2025-12-17T10:00:00Z", last_modified_on: "2025-12-17T10:00:00Z", created_by: "u-alice", record_id: "rec-1", parent_id: null }
];

function Demo() {
  return (
    <CommentsPanel
      comments={comments}
      currentUser={{ id: "u-alice", firstname: "Alice", lastname: "Johnson" }}
      users={[
        { id: "u-alice", firstname: "Alice", lastname: "Johnson" },
        { id: "u-bob", firstname: "Bob", lastname: "Smith" }
      ]}
      onCreateComment={({ message, mentions }) => console.log(message, mentions)}
      onUpdateComment={(id, message, mentions) => console.log(id, message, mentions)}
      onDeleteComment={(id) => console.log("delete", id)}
    />
  );
}
```

## Mentions, emoji & rich formatting

- **`@` mentions** — typing `@` opens a user picker sourced from the `users` prop. The selected user is stored inline as a markdown link (`[@Name](mention://<userId>)`) and rendered as a highlighted chip. `onCreateComment` / `onUpdateComment` receive the referenced user ids in `mentions`. Disable with `enableMentions={false}`.
- **Emoji** — the composer's emoji button inserts native unicode at the caret in both plain and rich modes. Disable with `enableEmoji={false}`.
- **Rich formatting** — a plain textarea by default; the `Aa` toggle switches to the markdown editor. The mode is authoring-only — the stored value is always markdown and always rendered as markdown, so a comment written in plain mode and one written in rich mode display identically. Control availability with `enableRichFormatting`, the initial mode with `defaultRichFormatting`, or persist the user's choice with the controlled `richFormatting` / `onRichFormattingChange` pair.

## API Reference

| Prop | Type | Default |
|------|------|---------|
| `comments` | `DocyrusComment[]` | — |
| `currentUser` | `CommentUser` | — |
| `users` | `CommentUser[]` | — |
| `title` | `string` | `"Comments"` |
| `editable` | `boolean` | `true` |
| `isLoading` | `boolean` | `false` |
| `maxHeight` | `number \| string` | `'24rem'` |
| `onCreateComment` | `({ message, parentId?, attachments?, mentions? }) => void \| Promise<void>` | — |
| `onUpdateComment` | `(id: string, message: string, mentions?: string[]) => void \| Promise<void>` | — |
| `onDeleteComment` | `(id: string) => void \| Promise<void>` | — |
| `onUploadFile` | `(file: File) => Promise<CommentAttachment>` | — |
| `isCreatePending` | `boolean` | `false` |
| `isDeletePending` | `boolean` | `false` |
| `enableRichFormatting` | `boolean` | `true` |
| `defaultRichFormatting` | `boolean` | `false` |
| `richFormatting` | `boolean` | — (controlled) |
| `onRichFormattingChange` | `(rich: boolean) => void` | — |
| `enableEmoji` | `boolean` | `true` |
| `enableMentions` | `boolean` | `true` |
| `className` | `string` | — |

## Components

| Component | Description |
|-----------|-------------|
| `CommentsPanel` | Public export |
| `CommentComposer` | Internal — `comment-composer.tsx` (create / reply / edit) |
| `CommentEmptyState` | Internal — `comment-empty-state.tsx` |
| `CommentItem` | Internal — `comment-item.tsx` |
| `CommentThread` | Internal — `comment-thread.tsx` |
| `MentionList` | Internal — `mention-list.tsx` |
| `useCommentMention` | Internal — `use-comment-mention.tsx` |

## Type Exports

| Type | Description |
|------|-------------|
| `CommentsPanelProps` | — |
| `DocyrusComment` | — |
| `CommentThread` | — |
| `CommentAttachment` | — |
| `CommentUser` | — |

## Type Reference

### DocyrusComment

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | — |
| `message` | `string` | — |
| `attachments` | `Array<CommentAttachment> \| null` | — |
| `created_on` | `string` | ISO date string |
| `last_modified_on` | `string` | ISO date string |
| `created_by` | `string` | user id |
| `record_id` | `string \| null` | — |
| `parent_id` | `string \| null` | reply to |

### CommentAttachment

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | — |
| `file_name` | `string` | — |
| `file_type` | `string` | MIME type |
| `file_size` | `number` | bytes |
| `signed_url` | `string \| null` | download URL |

### CommentUser

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | — |
| `firstname` | `string \| null` | — |
| `lastname` | `string \| null` | — |
| `photo` | `string \| null` | avatar image URL (mention list + comment avatars) |

### CommentThread

| Field | Type | Description |
|-------|------|-------------|
| `comment` | `DocyrusComment` | — |
| `replies` | `Array<DocyrusComment>` | — |

---

# Confirmation Button
URL: /docs/web/components/confirmation-button

Confirmation Button component with multiple variants and sizes.

**Demo:**

```tsx
'use client';
// @custom-demo

import { useState } from 'react';

import { ConfirmationButton } from '@docyrus/ui/components/confirmation-button';

function wait(ms: number): Promise<void> {
  return new Promise((resolve) => {
    window.setTimeout(resolve, ms);
  });
}

export function ConfirmationButtonDemo() {
  const [status, setStatus] = useState('Waiting for action');

  return (
    <div className="mx-auto flex h-72 w-full max-w-sm flex-col items-center justify-end gap-3 py-4">
      

      <p className="text-xs text-muted-foreground">Status: {status}</p>
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-confirmation-button
```

**Dependencies:**
- [lucide-react](https://www.npmjs.com/package/lucide-react)

## Usage

```tsx
import {
  ConfirmationButton
} from "@docyrus/ui/components/confirmation-button";

<ConfirmationButton
  onConfirm={() => {}}
  confirmationTitle={Are you sure?}
  confirmationMessage={Please confirm before this action is executed.}
  confirmLabel="Confirm"
  cancelLabel="Cancel"
  countdownSeconds={DEFAULT_COUNTDOWN_SECONDS}
  onCancel={() => {}}
  onTimeout={() => {}}
  triggerClassName="..."
  contentClassName="..."
  side="top"
  sideOffset={0}
  contentWidth={320}
  triggerSize={0}
  triggerWidth={0}
  triggerHeight={0}
  triggerRadius={0}
  speed={0}
  bgClassName="..."
  buttonVariant="destructive"
  buttonSize="default"
/>
```

## API Reference

| Prop | Type | Default |
|------|------|---------|
| `onConfirm` | `() => void \| Promise<void>` | — |
| `confirmationTitle` | `ReactNode` | `'Are you sure?'` |
| `confirmationMessage` | `ReactNode` | `'Please confirm before this action is executed.'` |
| `confirmLabel` | `string` | `'Confirm'` |
| `cancelLabel` | `string` | `'Cancel'` |
| `countdownSeconds` | `number` | `DEFAULT_COUNTDOWN_SECONDS` |
| `disabled` | `boolean` | `false` |
| `onCancel` | `() => void` | — |
| `onTimeout` | `() => void` | — |
| `triggerClassName` | `string` | — |
| `contentClassName` | `string` | — |
| `side` | `'top' \| 'bottom'` | `'top'` |
| `sideOffset` | `number` | — |
| `contentWidth` | `number` | `320` |
| `triggerSize` | `number` | — |
| `triggerWidth` | `number` | — |
| `triggerHeight` | `number` | — |
| `triggerRadius` | `number` | — |
| `speed` | `number` | — |
| `bgClassName` | `string` | — |
| `buttonVariant` | `ButtonVariant` | `'destructive'` |
| `buttonSize` | `ButtonSize` | `'default'` |
| `className` | `string` | — |

---

# Contact Activity Panel
URL: /docs/web/components/contact-activity-panel

A presentational record-activity timeline. Pair it with useDocyrusContactActivity to wire it to the Docyrus backend.

**Demo:**

```tsx
'use client';
// @custom-demo

import { useState } from 'react';

import { ContactActivityPanel } from '@docyrus/ui/components/contact-activity-panel';
import { Button } from '@docyrus/ui/primitives/ui/button';
import { cn } from '@docyrus/ui/primitives/lib/utils';

import { PropControls } from '@/components/prop-controls';
import { useDemoData } from '@/data/contact-activity-panel-data';

export function ContactActivityPanelDemo() {
  const { props, controls, actions } = useDemoData();
  const [open, setOpen] = useState(false);

  return (
    <div className="w-full">
      <div className="mb-3 flex justify-end">
        <button
          type="button"
          className="inline-flex items-center gap-1.5 rounded-md border border-border bg-background px-3 py-1.5 text-sm font-medium transition-colors hover:bg-accent"
          onClick={() => setOpen(prev => !prev)}>
          <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M12.22 2h-.44a2 2 0 0 0-2 2v.18a2 2 0 0 1-1 1.73l-.43.25a2 2 0 0 1-2 0l-.15-.08a2 2 0 0 0-2.73.73l-.22.38a2 2 0 0 0 .73 2.73l.15.1a2 2 0 0 1 1 1.72v.51a2 2 0 0 1-1 1.74l-.15.09a2 2 0 0 0-.73 2.73l.22.38a2 2 0 0 0 2.73.73l.15-.08a2 2 0 0 1 2 0l.43.25a2 2 0 0 1 1 1.73V20a2 2 0 0 0 2 2h.44a2 2 0 0 0 2-2v-.18a2 2 0 0 1 1-1.73l.43-.25a2 2 0 0 1 2 0l.15.08a2 2 0 0 0 2.73-.73l.22-.39a2 2 0 0 0-.73-2.73l-.15-.08a2 2 0 0 1-1-1.74v-.5a2 2 0 0 1 1-1.74l.15-.09a2 2 0 0 0 .73-2.73l-.22-.38a2 2 0 0 0-2.73-.73l-.15.08a2 2 0 0 1-2 0l-.43-.25a2 2 0 0 1-1-1.73V4a2 2 0 0 0-2-2z" /><circle cx="12" cy="12" r="3" /></svg>
          Configure
          <svg xmlns="http://www.w3.org/2000/svg" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" className={cn('transition-transform duration-200', open && 'rotate-180')}><path d="m6 9 6 6 6-6" /></svg>
        </button>
      </div>
      <div
        className={cn(
          'grid transition-[grid-template-rows] duration-300 ease-in-out',
          open ? 'grid-rows-[1fr]' : 'grid-rows-[0fr]'
        )}>
        <div className="overflow-hidden">
          <div className="mb-4 grid gap-6 rounded-lg border border-border bg-muted/30 p-4">
            
            <div className="mt-3 flex flex-wrap gap-2">
              
              
              
            </div>
          </div>
        </div>
      </div>
      
    </div>
  );
}
```

## Backend wiring

`ContactActivityPanel` is **presentational** — it renders the timeline and emits callbacks, but owns no
network I/O. For Docyrus-backed apps, drive it with [`useDocyrusContactActivity`](/docs/web/hooks/use-docyrus-contact-activity),
which merges the record's audit log, threaded comments, related events, tasks, and status updates into
one feed and returns a `panelProps` bag you spread straight onto the panel:

```tsx
const activity = useDocyrusContactActivity({ client, appSlug, dataSourceSlug, recordId, relationSlug: 'contact' });

```

The barrel also re-exports the hook and its types from `@docyrus/ui/components/contact-activity-panel`.
To compose a timeline **and** a "log activity" composer on the same record, pair it with
[`LogActivityForm`](/docs/web/components/log-activity-form) (wired via `useDocyrusLogActivity`).

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-contact-activity-panel
```

**Dependencies:**
- [lucide-react](https://www.npmjs.com/package/lucide-react)

## Usage

```tsx
import {
  ContactActivityPanel
} from "@docyrus/ui/components/contact-activity-panel";
import type {
  ContactActivity,
  ContactActivityPanelProps,
  ActivityType,
  ActivityCategory,
  UpcomingActivity,
  RelationshipSummary,
  ContactActivityContact,
  AddActivityAction,
  ChatUser,
  ChatPost,
  PostAttachment,
  PostReaction,
  CreatePostPayload,
  ActivityTypeConfig
} from "@docyrus/ui/components/contact-activity-panel";

<ContactActivityPanel
  contact={{ name: "John Smith", org: "Acme Corp" }}
  activities={activities}
  upcoming={upcoming}
  relationshipSummary={{ lastContactedAt, nextActivityAt, openTaskCount: 1 }}
  width="panel"
  iconStyle="color"
  addActions={addActions}
  onAddActivity={(type) => openComposer(type)}
  renderAiAssistant={({ open, onOpenChange }) => }
/>
```

## Redesign (v2)

The panel is a **typed activity timeline**: primary rows (calls, meetings, emails, chats,
notes, comments) render as clickable cards that open a detail modal; secondary rows (status
changes, files, form submissions, record updates, workflow traces) render as compact
one-liners on a shared rail. A category tab bar (All / Communication / Tasks / Updates) plus a
grouped type-filter popover scope the feed. Optional regions — a **contact header**, a
**relationship-summary + Add + Ask Docy** row, and a collapsible **Upcoming** list — light up
when their props are supplied. Ask Docy and the Add menu are **slots/emit-only**: the panel
owns no AI wiring and never opens a composer itself — supply `renderAiAssistant` /
`onAddActivity`. View controls (`width`, `iconStyle`, `showHeader`) are props; dark mode comes
from the global `DocyThemeProvider`.

## Components

| Component | Description |
|-----------|-------------|
| `ContactActivityPanel` | Public export |
| `ContactActivityHeader` | Internal — contact header (region 1) |
| `ContactActivityToolbar` | Internal — category tabs + filter popover (region 2) |
| `ContactActivitySummary` | Internal — relationship summary + Add + Ask Docy (region 3) |
| `ContactActivityUpcoming` | Internal — collapsible Upcoming list (region 4) |
| `ActivityTimeline` | Internal — day-grouped timeline + rail |
| `ActivityTimelineItem` | Internal — primary/secondary dispatch + rail chip |
| `ActivityPrimaryCard` | Internal — clickable activity card |
| `ActivitySecondaryRow` | Internal — compact one-liner |
| `ActivityAvatars` | Internal — participant avatar stack |
| `ActivityAddMenu` | Internal — Add dropdown (emit-only) |
| `ActivityDetailDialog` | Internal — activity detail modal (region 6) |
| `ActivityEmptyState` | Internal — `activity-empty-state.tsx` |
| `ActivityLoadingSkeleton` | Internal — `activity-skeleton.tsx` |
| `ContactActivityProvider` | Internal — `contact-activity-context.tsx` |

## Type Exports

| Type | Description |
|------|-------------|
| `ContactActivity` | A single timeline entry (see fields below) |
| `ContactActivityPanelProps` | Panel props |
| `ActivityType` | Union of activity kinds |
| `ActivityCategory` | `"communication" \| "tasks" \| "updates"` |
| `UpcomingActivity` | A future task/meeting (Upcoming section) |
| `RelationshipSummary` | Last-contact / next-activity / open-task summary |
| `ContactActivityContact` | Header identity |
| `AddActivityAction` | An Add-menu entry |
| `ChatUser` | — |
| `ChatPost` | — |
| `PostAttachment` | — |
| `PostReaction` | — |
| `CreatePostPayload` | — |
| `ActivityTypeConfig` | — |

## Type Reference

### ContactActivity

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | — |
| `type` | `ActivityType` | — |
| `subject` | `string` | — |
| `description` | `string` | — |
| `metadata` | `Record<string, unknown>` | — |
| `attachments` | `Array<PostAttachment> \| null` | — |
| `reactions` | `Array<PostReaction>` | — |
| `title` | `string` | Display title; falls back to `subject` |
| `preview` | `string` | One-line body preview; falls back to first line of `description` |
| `participants` | `Array<string>` | User ids for the avatar stack (beyond `created_by`) |
| `timeRange` | `{ start: string; end?: string }` | Start/end for a "14:00–14:45" chip |
| `dueDate` | `string` | Task due date |
| `actorLabel` | `string` | Actor label on secondary rows |
| `summary` | `string` | Detail-modal summary (consumer-supplied) |
| `keyPoints` | `Array<string>` | Detail-modal key points (consumer-supplied) |
| `followUps` | `Array<{ id: string; text: string; done?: boolean }>` | Detail-modal follow-ups (consumer-supplied) |
| `related` | `Array<{ id?: string; label: string }>` | Related-record chips (consumer-supplied) |
| `primaryAction` | `{ label: string; onClick?: () => void }` | Detail-modal primary action |

### ContactActivityPanelProps

| Field | Type | Description |
|-------|------|-------------|
| `activities` | `Array<ContactActivity>` | Timeline entries |
| `currentUser` | `ChatUser` | — |
| `users` | `Array<ChatUser>` | Resolves participant avatars |
| `contact` | `ContactActivityContact` | Header identity (region 1) |
| `showHeader` | `boolean` | Toggle the contact header (default `true`) |
| `headerActions` | `ReactNode` | Header ⋯ menu slot |
| `width` | `"panel" \| "wide"` | Layout width (default `"panel"`) |
| `iconStyle` | `"color" \| "mono"` | Chip tone (default `"color"`) |
| `relationshipSummary` | `RelationshipSummary` | Summary line (region 3) |
| `upcoming` | `Array<UpcomingActivity>` | Upcoming section (region 4) |
| `onToggleUpcomingTask` | `(id: string) => void \| Promise<void>` | Upcoming task check toggle |
| `addActions` | `Array<AddActivityAction>` | Add-menu entries (region 3) |
| `onAddActivity` | `(type: string) => void` | Emitted when an Add entry is picked |
| `onActivityClick` | `(activity: ContactActivity) => void` | Override the built-in detail modal |
| `renderActivityDetail` | `(activity: ContactActivity) => ReactNode` | Custom detail-modal body |
| `onToggleFollowUp` | `(activityId: string, followUpId: string) => void \| Promise<void>` | Follow-up check toggle |
| `renderAiAssistant` | `(ctx: { open: boolean; onOpenChange: (open: boolean) => void }) => ReactNode` | Ask Docy slot (region 7) |
| `aiAssistantOpen` | `boolean` | Controlled Ask Docy open state |
| `onAiAssistantOpenChange` | `(open: boolean) => void` | Ask Docy open-state change |
| `isLoading` | `boolean` | — |
| `isCreatePending` | `boolean` | — |
| `isDeletePending` | `boolean` | — |
| `onDeleteActivity` | `(activityId: string) => void \| Promise<void>` | — |
| `onCreateComment` | `(payload: CreatePostPayload) => void \| Promise<void>` | Comment reply create (detail modal) |
| `onDeleteComment` | `(commentId: string) => void \| Promise<void>` | Comment delete |
| `onLoadReplies` | `(activityId: string) => Promise<Array<ChatPost>>` | Loads a comment's replies (detail modal) |
| `dataSources` | `Array<DataSourceOption>` | — |
| `onSearchEntity` | `(dataSourceId: string, query: string) => Promise<Array<EntitySearchResult>>` | — |
| `activityTypes` | `Array<ActivityType>` | Restrict the filterable types |
| `maxHeight` | `number \| string` | — |
| `className` | `string` | — |

### ActivityType

`"call" \| "meeting" \| "email" \| "chat" \| "sms" \| "whatsapp" \| "linkedin" \| "note" \| "comment" \| "task" \| "status_update" \| "status" \| "file" \| "form" \| "record" \| "trace" \| "record_create" \| "record_update"`

### ActivityTypeConfig

| Field | Type | Description |
|-------|------|-------------|
| `icon` | `LucideIcon` | — |
| `label` | `string` | — |
| `colorClass` | `string` | — |
| `bgClass` | `string` | — |
| `category` | `ActivityCategory` | Tab-bar grouping |
| `colorHex` | `{ light: string; dark: string }` | Colored-chip tint (absent → monochrome) |
| `primary` | `boolean` | `true` → card row; else secondary one-liner |
| `compact` | `boolean` | Legacy record-row flag |

---

# Contact Channels Field
URL: /docs/web/components/contact-channels-field

A backend-agnostic, fully controlled editor for a record's contact channels, their consent cache and validation status.

`ContactChannelsField` is a **compact, read-at-a-glance summary** of a record's **contact channels** —
the primary email / phone / messaging / social entry per kind (with a `+N` badge for the rest) plus a
per-brand **consent** grid. A **Details** link opens a dialog with the full
[`ContactChannelsManager`](#comprehensive-editor) for adding, editing and removing channels and
editing consent & validation. It mirrors the snake_case shape of the Contact Channels & Consent API,
so the same `ContactChannel[]` round-trips with the Docyrus-backed
[Contact Channels Panel](/docs/web/docyrus/contact-channels-panel) — but the field itself needs
**no backend**: give it `value` + `onChange` and it works in any form.

**Demo:**

```tsx
'use client';

import { useState } from 'react';

import {
  ContactChannelsField,
  type ContactBrand,
  type ContactChannel
} from '@docyrus/ui/components/contact-channels-field';

const BRANDS: ContactBrand[] = [{ id: '0190aaaa', name: 'Acme', color_primary: 'indigo-500' }, { id: '0190bbbb', name: 'Globex', color_primary: 'emerald-500' }];

const SEED: ContactChannel[] = [
  {
    id: '1',
    channel_kind: 'email',
    channel_type: 'email',
    value: 'ada@example.com',
    value_raw: 'ada@example.com',
    label: 'work',
    is_primary: true,
    is_verified: true,
    validation_status: 'valid',
    validated_on: '2026-06-01T08:00:00Z',
    consent: {
      _default: { _default: { transactional: { status: 'opted_in', source: 'default' } } },
      '0190aaaa': { email: { marketing: { status: 'opted_in', on: '2026-06-10T09:00:00Z', source: 'web_form' } } }
    }
  },
  {
    id: '2',
    channel_kind: 'phone',
    channel_type: 'mobile',
    value: '+905551112233',
    value_raw: '+90 555 111 22 33',
    country: 'TR',
    label: 'personal',
    is_primary: true
  },
  {
    id: '3',
    channel_kind: 'social',
    channel_type: 'linkedin',
    value: 'in/ada-lovelace',
    value_raw: 'in/ada-lovelace'
  }
];

export function ContactChannelsFieldDemo() {
  const [channels, setChannels] = useState<ContactChannel[]>(SEED);

  return (
    <div className="w-full max-w-xl">
      
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-contact-channels-field
```

**Dependencies:**
- [lucide-react](https://www.npmjs.com/package/lucide-react)

## Usage

```tsx
import { useState } from 'react';
import {
  ContactChannelsField,
  type ContactChannel
} from '@docyrus/ui/components/contact-channels-field';

function Example() {
  const [channels, setChannels] = useState<ContactChannel[]>([]);

  return ;
}
```

### Opening the Docyrus panel from Details

Pass `onDetailsClick` to take over the Details link — typically to open the backend-backed
[`ContactChannelsPanel`](/docs/web/docyrus/contact-channels-panel) as a dialog instead of the
built-in editor:

```tsx
const [open, setOpen] = useState(false);

<ContactChannelsField value={channels} brands={brands} readOnly onDetailsClick={() => setOpen(true)} />

```

### Comprehensive editor

`ContactChannelsManager` is the full backend-agnostic editor rendered inside the Details dialog —
use it directly (inline) when you don't want the summary chrome:

```tsx
import { ContactChannelsManager } from '@docyrus/ui/components/contact-channels-field';

```

### Inside a TanStack form

Use the `ContactChannelsFormField` wrapper to bind the channel array to a form field. It edits inline
with `ContactChannelsManager` and surfaces validation errors.

```tsx
import { ContactChannelsFormField } from '@docyrus/ui/components/form-fields';

```

## Channel & consent model

Each channel carries a `channel_kind` (`email` · `phone` · `messaging` · `social` · `web`) and a
`channel_type` (`email`, `mobile`, `whatsapp`, `linkedin`, …). At most one channel per kind is
`is_primary`. The consent cache is a three-level map keyed **brand → medium → purpose**; the field's
inline consent editor only offers mediums that are valid for the channel type (e.g. a `mobile`
channel exposes `call` and `sms`, an `email` channel exposes `email`), matching the medium ↔
channel-type rules the API enforces server-side. A new channel defaults to
`transactional` consent `opted_in` at the organization-wide / medium-agnostic level.

## API Reference

### ContactChannelsField (summary)

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `ContactChannel[]` | — | Controlled list of channels. |
| `onChange` | `(next: ContactChannel[]) => void` | — | Emitted when channels are edited in the Details dialog. |
| `brands` | `ContactBrand[]` | — | Brands for the consent summary (one row each); omit for a single organization-wide row. |
| `title` | `string` | `'Contact Points'` | Summary heading. |
| `hideDetails` | `boolean` | `false` | Hide the Details link. |
| `detailsLabel` | `string` | `'Details'` | Label for the Details link. |
| `onDetailsClick` | `() => void` | — | When set, Details calls this instead of opening the built-in dialog. |
| `showConsent` | `boolean` | `true` | Show the consent summary section. |
| `disabled` | `boolean` | `false` | Disable editing in the built-in dialog. |
| `readOnly` | `boolean` | `false` | Render the built-in dialog read-only. |
| `emptyText` | `string` | `'No contact points yet.'` | Placeholder when there are no channels. |
| `className` | `string` | — | Additional class on the root. |

### ContactChannelsManager (full editor)

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `ContactChannel[]` | — | Controlled list of channels. |
| `onChange` | `(next: ContactChannel[]) => void` | — | Emitted on any add / edit / remove / make-primary. |
| `brands` | `ContactBrand[]` | — | Brands for labelling / scoping consent. |
| `disabled` | `boolean` | `false` | Disable every interaction. |
| `readOnly` | `boolean` | `false` | Render read-only (hides editors and action menus). |
| `enableConsent` | `boolean` | `true` | Show the inline consent editor per channel. |
| `enableValidation` | `boolean` | `true` | Show validation status chips. |
| `groupByKind` | `boolean` | `true` | Group channels under kind headers. |
| `emptyText` | `string` | `'No contact channels yet.'` | Placeholder when there are no channels. |

### ContactChannelsFormField

Extends the standard Docyrus form-field props (`field`, `form`, `disabled`, `required`, `className`)
with `brands`, `enableConsent`, `enableValidation` and `groupByKind`. Edits inline with
`ContactChannelsManager`.

## Exports

| Export | Description |
|--------|-------------|
| `ContactChannelsField` | The compact summary + Details dialog. |
| `ContactChannelsManager` | The full backend-agnostic editor (rendered in the Details dialog). |
| `ChannelEditor` | Backend-agnostic single-channel attribute editor. |
| `ConsentMatrix` | Consent-cache editor (medium × purpose) for one channel. |
| `ConsentStatusBadge` / `ValidationStatusBadge` / `VerifiedBadge` | Status chips. |
| `normalizeChannelValue` / `validateChannelValue` | Value helpers (email lower-casing, format checks). |
| `flattenConsent` / `readConsent` / `summarizeBrandConsent` | Consent-cache readers. |
| `CHANNEL_TYPES_BY_KIND` / `MEDIUMS_BY_CHANNEL_TYPE` / `allowedMediums` | Enum + compatibility maps. |

## Type Exports

| Type | Description |
|------|-------------|
| `ContactChannel` | A channel row (snake_case, mirrors the API response). |
| `ContactBrand` | Brand lookup (`id`, `name`, `logo_url`, `color_primary`). |
| `ConsentCache` | `brand → medium → purpose` consent map. |
| `ConsentRecord` / `ValidationRecord` | Ledger rows (used by the panel). |
| `ChannelKind` / `ChannelType` / `ConsentPurpose` / `ConsentMedium` / `ConsentStatus` / `ValidationStatus` | Enumerations. |

---

# Create Record Dialog
URL: /docs/web/components/create-record-dialog

Create Record Dialog component with multiple variants and sizes.

**Demo:**

```tsx
'use client';
// @custom-demo

import { useState } from 'react';

import {
  CreateRecordDialog,
  type SelectorFieldConfig,
  type MentionTriggerConfig,
  type AiAction
} from '@docyrus/ui/components/create-record-dialog';
import {
  AtSignIcon, CalendarIcon, FolderIcon,
  GlobeIcon, HashIcon, SparklesIcon,
  UserIcon
} from 'lucide-react';

import { Button } from '@docyrus/ui/primitives/ui/button';

// ─── Sample Data ─────────────────────────────────────────────

const PROJECTS = [
  { id: 'p1', label: 'Marketing Campaign', color: '#3b82f6' },
  { id: 'p2', label: 'Product Launch', color: '#8b5cf6' },
  { id: 'p3', label: 'Engineering Sprint', color: '#10b981' },
  { id: 'p4', label: 'Design System', color: '#f59e0b' }
];

const SECTIONS: Record<string, Array<{ id: string; label: string }>> = {
  p1: [{ id: 's1', label: 'Social Media' }, { id: 's2', label: 'Email Campaigns' }],
  p2: [{ id: 's4', label: 'Beta Testing' }, { id: 's5', label: 'Launch Prep' }],
  p3: [{ id: 's6', label: 'Sprint 14' }, { id: 's7', label: 'Sprint 15' }],
  p4: [{ id: 's8', label: 'Components' }, { id: 's9', label: 'Tokens' }]
};

const USERS = [
  { id: 'u1', label: 'Alice Johnson' },
  { id: 'u2', label: 'Bob Smith' },
  { id: 'u3', label: 'Carol Williams' },
  { id: 'u4', label: 'David Brown' },
  { id: 'u5', label: 'Eve Davis' }
];

const PRIORITIES = [
  { id: 'low', label: 'Low', color: '#94a3b8' },
  { id: 'medium', label: 'Medium', color: '#f59e0b' },
  { id: 'high', label: 'High', color: '#ef4444' },
  { id: 'urgent', label: 'Urgent', color: '#dc2626' }
];

export function CreateRecordDialogDemo() {
  const [projectId, setProjectId] = useState<string | null>(null);

  const headerFields: SelectorFieldConfig[] = [
    {
      key: 'project',
      label: 'Project',
      placeholder: 'Select project',
      options: PROJECTS,
      value: projectId,
      clearsFields: ['section'],
      onChange: val => setProjectId(val)
    }
  ];

  if (projectId) {
    headerFields.push({
      key: 'section',
      label: 'Section',
      placeholder: 'Section',
      options: SECTIONS[projectId] ?? []
    });
  }

  const userTrigger: MentionTriggerConfig = {
    trigger: '@',
    options: USERS.map(u => ({
      id: u.id,
      label: u.label,
      icon: 
    })),
    searchPlaceholder: 'Search users...',
    emptyText: 'No users found.'
  };

  const projectTrigger: MentionTriggerConfig = {
    trigger: '#',
    options: PROJECTS.map(p => ({
      id: p.id,
      label: p.label,
      icon: 
    })),
    searchPlaceholder: 'Search projects...',
    emptyText: 'No projects found.'
  };

  const aiActions: AiAction[] = [
    {
      id: 'rephrase',
      label: 'Rephrase',
      icon: ,
      onAction: () => {}
    },
    {
      id: 'translate',
      label: 'Translate',
      icon: ,
      onAction: () => {}
    }
  ];

  return (
    }
      headerLabel="Create task on"
      headerFields={headerFields}
      subjectPlaceholder="Task name"
      descriptionPlaceholder="Add task description..."
      footerFields={[
        {
          key: 'dueDate',
          label: 'Due date',
          placeholder: 'Due date',
          icon: ,
          options: [{ id: 'today', label: 'Today' }, { id: 'tomorrow', label: 'Tomorrow' }, { id: 'next_week', label: 'Next week' }]
        },
        {
          key: 'assignee',
          label: 'Assignee',
          placeholder: 'Assignee',
          icon: ,
          options: USERS,
          searchPlaceholder: 'Search users...'
        },
        {
          key: 'priority',
          label: 'Priority',
          placeholder: 'Priority',
          icon: <span className="text-xs">!</span>,
          options: PRIORITIES
        }
      ]}
      footerToggles={[{ key: 'backlog', label: 'Backlog' }]}
      mentionTriggers={[userTrigger, projectTrigger]}
      aiActions={aiActions}
      enableCreateMore
      onSubmit={(data) => {
        console.info('Submitted:', data);

        return new Promise<void>(resolve => setTimeout(resolve, 800));
      }}>
      
    
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-create-record-dialog
```

**Dependencies:**
- [lucide-react](https://www.npmjs.com/package/lucide-react)
- [radix-ui](https://www.npmjs.com/package/radix-ui)
- [@types/react](https://www.npmjs.com/package/@types/react)
- [@types/react-dom](https://www.npmjs.com/package/@types/react-dom)

## Usage

```tsx
import {
  CreateRecordDialog
} from "@docyrus/ui/components/create-record-dialog";

<CreateRecordDialog
  open
  onOpenChange={() => {}}
  headerIcon={...}
  headerLabel="..."
  headerFields={SelectorFieldConfig[]}
  subjectPlaceholder="..."
  descriptionPlaceholder="..."
  descriptionExpanded
  footerFields={SelectorFieldConfig[]}
  footerToggles={FooterToggleConfig[]}
  mentionTriggers={MentionTriggerConfig[]}
  onMentionSelect={() => {}}
  aiActions={AiAction[]}
  enableCreateMore
  createMoreResetKeys={string[]}
  onSubmit={() => {}}
  isPending
  saveLabel="..."
  cancelLabel="..."
  createMoreLabel="..."
  addDescriptionLabel="..."
  dialogTitle="..."
/>
```

## API Reference

| Prop | Type | Default |
|------|------|---------|
| `open` | `boolean` | — |
| `onOpenChange` | `(open: boolean) => void` | — |
| `headerIcon` | `ReactNode` | — |
| `headerLabel` | `string` | — |
| `headerFields` | `SelectorFieldConfig[]` | — |
| `subjectPlaceholder` | `string` | — |
| `descriptionPlaceholder` | `string` | — |
| `descriptionExpanded` | `boolean` | — |
| `footerFields` | `SelectorFieldConfig[]` | — |
| `footerToggles` | `FooterToggleConfig[]` | — |
| `mentionTriggers` | `MentionTriggerConfig[]` | — |
| `onMentionSelect` | `(selection: MentionSelection) => void` | — |
| `aiActions` | `AiAction[]` | — |
| `enableCreateMore` | `boolean` | — |
| `createMoreResetKeys` | `string[]` | — |
| `onSubmit` | `(data: CreateRecordFormData) => void \| Promise<void>` | — |
| `isPending` | `boolean` | — |
| `saveLabel` | `string` | — |
| `cancelLabel` | `string` | — |
| `createMoreLabel` | `string` | — |
| `addDescriptionLabel` | `string` | — |
| `dialogTitle` | `string` | — |
| `className` | `string` | — |

---

# Data Gallery
URL: /docs/web/components/data-gallery

A standalone, virtualized card gallery view for record lists. Toolbar-driven card design (variant, cover style, density, field bindings) plus full TanStack Table integration for sorting, filtering, grouping, and saved views.

**Demo:**

```tsx
'use client';
// @custom-demo

import { useCallback, useState } from 'react';

import {
  DataGallery,
  DataGalleryToolbar,
  useDataGallery,
  type DataGalleryCardConfigSerializable
} from '@docyrus/ui/components/data-gallery';
import { getDataGridSelectColumn } from '@docyrus/ui/components/data-grid';
import { Badge } from '@docyrus/ui/primitives/ui/badge';
import { TooltipProvider } from '@docyrus/ui/primitives/ui/tooltip';

import { useGalleryData } from '@/data/data-gallery-data';

const DEFAULT_CARD_CONFIG: DataGalleryCardConfigSerializable = {
  titleField: 'name',
  descriptionField: 'tagline',
  coverImageField: 'cover',
  badgeField: 'status',
  avatarField: 'owner',
  timelineField: 'launchDate',
  bodyFields: ['price', 'rating', 'inventory'],
  footerFields: ['category']
};

function DataGalleryDemoInner() {
  const { data, columns: columnDefs } = useGalleryData();

  type Row = typeof data[number];

  const columns = [getDataGridSelectColumn
            );
          }
        }}
        actions={[
          {
            key: 'archive',
            label: 'Archive',
            onAction: (rows) => {
              // eslint-disable-next-line no-console -- demo
              console.log('Archive', rows);
            }
          },
          {
            key: 'delete',
            label: 'Delete',
            variant: 'destructive',
            onAction: (rows) => {
              // eslint-disable-next-line no-console -- demo
              console.log('Delete', rows);
            }
          }
        ]}
        onCardClick={(record) => {
          // eslint-disable-next-line no-console -- demo
          console.log('Open detail', record);
        }}
        height={680} />
    </div>
  );
}

export function DataGalleryDemo() {
  return (
    
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-data-gallery
```

**Dependencies:**
- [lucide-react](https://www.npmjs.com/package/lucide-react)
- [@tanstack/react-table](https://www.npmjs.com/package/@tanstack/react-table)
- [@tanstack/react-virtual](https://www.npmjs.com/package/@tanstack/react-virtual)
- [react-querybuilder](https://www.npmjs.com/package/react-querybuilder)

## Usage

```tsx
import {
  DataGallery,
  DataGalleryToolbar,
  useDataGallery
} from '@docyrus/ui/components/data-gallery';
import type {
  ColumnDef
} from '@docyrus/ui/components/data-grid';
import type {
  DataGalleryCardConfigSerializable
} from '@docyrus/ui/components/data-gallery';

const columns: ColumnDef<Product>[] = [
  { accessorKey: 'name', meta: { label: 'Name', cell: { variant: 'short-text' } } },
  { accessorKey: 'cover', meta: { label: 'Cover', cell: { variant: 'image' } } },
  { accessorKey: 'status', meta: {
    label: 'Status',
    cell: { variant: 'status', options: statusOptions }
  } }
  // ...
];

function MyGallery() {
  const [cardConfig, setCardConfig] = useState<DataGalleryCardConfigSerializable>({
    titleField: 'name',
    descriptionField: 'tagline',
    coverImageField: 'cover',
    badgeField: 'status'
  });

  const galleryProps = useDataGallery({
    data,
    columns,
    enableSearch: true,
    enableGrouping: true,
    displayConfig: {
      cardVariant: 'detailed',
      coverStyle: 'top-md',
      columnCount: 'flex'
    }
  });

  const {
    table, displayConfig, setDisplayConfig, searchQuery, setSearchQuery
  } = galleryProps;

  return (
    <div className="flex flex-col gap-3">
      

      
    </div>
  );
}
```

## Card Variants

The card variant controls the default layout. Each variant ships with sensible defaults that the display menu can still override. Pick the variant via `displayConfig.cardVariant` or per-card via `cardConfig.variant`. The demo above exposes the variant picker in its **Display** toolbar menu — try switching between them live.

| Variant | Use case | Defaults |
|---------|----------|----------|
| `detailed` | Records with field labels (CRM, inventory) | top-md cover, comfortable density, labels on |
| `compact` | Dense grids with many items | top-sm cover, compact density, labels off |
| `media` | Image-led catalogs | top-lg cover, minimal text |
| `profile` | People / contacts | No cover, centered avatar + name |
| `product` | E-commerce catalogs | top-md cover, footer chip enabled |

## Card Slots

Each card composes from a fixed set of slots. Bind a column ID to a slot via `cardConfig`, or supply a custom renderer (`renderAvatar`, `renderCover`, `renderBadge`, `renderTimeline`, `renderActions`). For complete control, return your own JSX from `renderCard`.

| Slot | Field property | Custom renderer |
|------|---------------|-----------------|
| Title | `titleField` | — |
| Description | `descriptionField` / `subtitleField` | — |
| Avatar | `avatarField` | `renderAvatar` |
| Cover image | `coverImageField` | `renderCover` |
| Badge (corner chip) | `badgeField` | `renderBadge` |
| Timeline (footer date) | `timelineField` | `renderTimeline` |
| Actions menu (header) | — | `renderActions` |
| Body fields | `bodyFields` | — (uses cell renderer) |
| Footer fields | `footerFields` | — (uses cell renderer) |

`bodyFields` defaults to every visible column the table exposes minus the ones already bound to a dedicated slot.

### Cover & avatar value resolution

`coverImageField` and `avatarField` read from `row.original[slug]` directly rather than through TanStack's `accessorFn`. Docyrus columns run a `normalizeFieldValue` step inside the accessor that flattens `field-image` arrays (`[{ signed_url, … }]`) to a JSON string and `field-userSelect` objects (`{ id, name, avatar_url }`) to a UUID — both lose the URL the card needs. The raw read keeps the original shape so:

- **Cover images** resolve through `resolveImageUrl`, which walks array → object → first usable URL key (`signed_url`, `signedUrl`, `url`, `src`, `image_url`, `thumb_url`).
- **Avatars** resolve through `resolveAvatarUrlAndLabel`. When the bound column has `cellOpts.variant === 'user'`, the helper looks the row's user id up in `cellOpts.options` (the tenant-wide users list `useDocyrusDataGrid` injects), picking the avatar URL + display name from the option entry — so users still get their real photos even when the expanded row payload only carries `{ id, name }`.

### Avatar / cover duplicate guard

When `avatarField` and `coverImageField` are bound to the same column (typically from an old auto-detect or saved view that picked `company_logo` for both), the avatar slot is suppressed automatically. The cover already carries the image; rendering a thumbnail of it next to the checkbox just doubles the visual.

### Layout lockstep

`coverStyle: 'left'` and `layoutOrientation: 'horizontal'` are coupled — picking one auto-promotes the other via `resolveCardLayout`. Setting `coverStyle: 'top-md'` together with `layoutOrientation: 'horizontal'` falls back to `'vertical'` so the cover doesn't stretch awkwardly alongside the body.

## Display Config

The `displayConfig` object is owned by `useDataGallery` and mutated by the toolbar's display menu. Pass `displayConfig` as the initial state; the hook re-syncs only when you swap the prop identity (e.g. switching saved views).

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `columnCount` | `'flex' \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` | `'flex'` | Auto-fits cards to container when `'flex'`. |
| `cardSize` | `'full' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| '3xl' \| '4xl'` | `'full'` | Caps individual card max width. |
| `density` | `'compact' \| 'comfortable'` | `'comfortable'` | Padding + font size. |
| `coverStyle` | `'none' \| 'top-sm' \| 'top-md' \| 'top-lg' \| 'left'` | `'top-md'` | Position + height of the cover image. |
| `layoutOrientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Card-internal layout. Auto-promoted to `horizontal` when `coverStyle === 'left'`. |
| `showFieldLabels` | `boolean` | `true` | Show field name next to each body value. |
| `showCardHeader` | `boolean` | `true` | Show the title / avatar / badge header. |
| `showCardFooter` | `boolean` | `false` | Show the timeline + footer fields strip. |
| `cardVariant` | `DataGalleryCardVariant` | `'detailed'` | Preset selector. |

### Variant changes are preset applications

Picking a new `cardVariant` from the display menu batch-updates every display field defined in `VARIANT_DISPLAY_PRESETS` (cover style, density, label visibility, footer toggle, …) rather than just renaming the variant. After application the display config stays the single source of truth — `cardVariant` is a "last preset applied" label rather than a runtime override. The variant additionally drives non-display visual details (avatar / title sizing) via `VARIANT_VISUAL_DEFAULTS` at render time.

### Dynamic card height

Cards size themselves to their content; the virtualizer reads each row's real height after mount via `measureElement` and updates row positions in place. `estimatedCardHeight` is just the initial guess used for the first paint — undershoot is fine, the measured value replaces it once the row renders. This keeps tall content (extra body fields, wrapped descriptions, large covers) from getting clipped inside a fixed-height row band.

## Color treatment

Every option-backed chip — status, select, enum, multi-select, tag-select, relation — renders with the same neutral surface: shared border, transparent background, plain foreground text. The option's color appears only as a small dot before the label, run through `humanizeColor()` (a `color-mix` in OKLab that pulls Tailwind-500 defaults toward an earthy warm-neutral so cards don't pick up a "designer palette" of saturated greens / purples / cyans). It's the Linear / Notion / Tana pattern — the hue identity survives, but it doesn't dominate.

## Toolbar

The toolbar is a thin orchestrator over the standalone menu components. Enable each section via a feature flag.

| Section | Flag | Notes |
|---------|------|-------|
| Search | `enableSearch` | Renders `DataGallerySearch` (debounced) when `onSearchQueryChange` is provided. |
| Filter | `enableFilter` | Reuses `DataGridFilterMenu` — same filter UX as the data grid. |
| Sort | `enableSort` | Reuses `DataGridSortMenu`. |
| Group | `enableGroup` | Reuses `DataGridGroupMenu`. |
| Display | `enableDisplay` | Gallery-specific menu (variant, columns, cover style, density). |
| Card fields | `enableCardConfig` | Gallery-specific menu for slot bindings. |
| Saved views | `enableView` | Reuses `DataGridViewMenu` (grid + gallery storage is shared). |

The `<DataGalleryToolbar>` also supports `startContent` and `endContent` slots for custom controls, plus an `onAdd` handler that renders a primary `Add` button on the right edge.

## Selection & Actions

Set `enableRowSelection` on `useDataGallery` (TanStack default applies). Each card shows a hover-revealed checkbox; multi-selection raises an `ActionBar`. Pass actions via the `actions` prop on `<DataGallery>`:

```tsx
<DataGallery
  {...galleryProps}
  actions={[
    { key: 'archive', label: 'Archive', onAction: rows => archive(rows) },
    { key: 'delete', label: 'Delete', variant: 'destructive', onAction: rows => deleteAll(rows) }
  ]} />
```

## Pagination

Set `pagingMode: 'standard'` to enable a paginated footer instead of virtual scrolling:

```tsx
const galleryProps = useDataGallery({
  data,
  columns,
  pagingMode: 'standard',
  pageSize: 24
});
```

## API Reference

### `useDataGallery(options)`

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `data` | `Array<TData>` | — | Records to render. |
| `columns` | `Array<ColumnDef<TData>>` | — | TanStack column defs. Cell variants are read from `meta.cell`. |
| `displayConfig` | `Partial<DataGalleryDisplayConfig>` | — | Initial display config (the hook owns it after mount). |
| `onDisplayConfigChange` | `(config) => void` | — | Fires whenever the display config changes. |
| `enableGrouping` | `boolean` | `false` | Adds the grouped row model so the group menu can group cards. |
| `enableSearch` | `boolean` | `false` | Enables the TanStack global filter pipeline for the toolbar search input. |
| `onSearch` | `(query) => void` | — | Side-channel for server-side keyword search. |
| `minCardWidth` | `number` | `260` | Min width used by the `'flex'` column count auto-fit. |
| `estimatedCardHeight` | `number` | `360` | Initial virtualizer estimate. Replaced per-row by `measureElement` after first render — undershoot is preferred to overshoot. |
| `overscan` | `number` | `3` | Virtualizer overscan rows. |
| `pagingMode` | `'virtual-scroll' \| 'standard'` | `'virtual-scroll'` | Standard adds a paging footer (see `DataGridPaginationFooter`). |
| `pageSize` | `number` | `24` | Initial page size for standard pagination. |
| `dir` | `'ltr' \| 'rtl'` | — | Direction override. Defaults to the package's `useDirection`. |

### ``

Accepts the spread return of `useDataGallery` plus:

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `cardConfig` | `DataGalleryCardConfig<TData>` | — | Field bindings + custom renderers. |
| `actions` | `Array<DataGalleryAction<TData>>` | — | Multi-select action bar buttons. |
| `onCardClick` | `(record, index) => void` | — | Fires when the card is activated (click / Enter / Space). Checkbox clicks are filtered out automatically. |
| `onAdd` | `() => void` | — | Renders an "Add card" tile at the end of the grid. |
| `addLabel` | `string` | `Add card` | Label for the add tile. |
| `isReloading` | `boolean` | `false` | Shows a translucent overlay + spinner over the body. |
| `height` | `number \| 'auto'` | `600` | Fixed pixel height or stretch to container. |
| `startContent` | `ReactNode` | — | Rendered before the body (e.g. pivot filters). |
| `endContent` | `ReactNode` | — | Rendered after the body. |

### ``

| Prop | Type | Description |
|------|------|-------------|
| `table` | `Table<TData>` | TanStack table from `useDataGallery`. |
| `displayConfig` | `DataGalleryDisplayConfig` | Current display config. |
| `onDisplayConfigChange` | `(updater) => void` | Setter from `useDataGallery`. |
| `cardConfig` | `DataGalleryCardConfigSerializable` | Current card bindings (when `enableCardConfig`). |
| `onCardConfigChange` | `(updater) => void` | Card config setter. |
| `searchQuery` | `string` | Current search value. |
| `onSearchQueryChange` | `(value) => void` | Search setter from `useDataGallery`. |
| `enableSearch` | `boolean` | Toggle search input. |
| `enableFilter` | `boolean` | Toggle filter menu. |
| `enableSort` | `boolean` | Toggle sort menu. |
| `enableGroup` | `boolean` | Toggle group menu. |
| `enableDisplay` | `boolean` | Toggle gallery display menu. |
| `enableCardConfig` | `boolean` | Toggle card config menu. |
| `enableView` | `boolean` | Toggle saved views menu. |
| `viewStorageKey` | `string` | LocalStorage key for saved views. |
| `onAdd` | `() => void` | Primary "Add" button handler. |
| `addLabel` | `string` | Add button label. |
| `startContent` | `ReactNode` | Rendered before the data manipulation group. |
| `endContent` | `ReactNode` | Rendered before the add button. |

## Type Exports

| Type | Description |
|------|-------------|
| `DataGalleryCardConfig<TData>` | Card configuration including non-serializable render hooks. |
| `DataGalleryCardConfigSerializable` | Serializable subset of `DataGalleryCardConfig` (no functions). Safe for saved views. |
| `DataGalleryDisplayConfig` | Toolbar-driven display settings. |
| `DataGalleryCardVariant` | `'detailed' \| 'compact' \| 'media' \| 'profile' \| 'product'` |
| `DataGalleryCoverStyle` | `'none' \| 'top-sm' \| 'top-md' \| 'top-lg' \| 'left'` |
| `DataGalleryCardSize` | `'full' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| '3xl' \| '4xl'` |
| `DataGalleryColumnCount` | `'flex' \| 1 \| 2 \| 3 \| 4 \| 5 \| 6` |
| `DataGalleryDensity` | `'compact' \| 'comfortable'` |
| `DataGalleryLayoutOrientation` | `'vertical' \| 'horizontal'` |
| `DataGalleryAction<TData>` | Action bar button definition. |
| `SavedDataGalleryView` | Saved view payload (icon, filters, display + card config). |

## Components

| Component | Description |
|-----------|-------------|
| `DataGallery` | Main virtualized card grid. |
| `DataGalleryCard` | Single card renderer (variant + slot composition). |
| `DataGalleryToolbar` | Orchestrator for search / filter / sort / group / display / card config menus. |
| `DataGallerySearch` | Standalone debounced search input. |
| `DataGalleryDisplayMenu` | Gallery-specific display options popover. |
| `DataGalleryCardConfigMenu` | Field-binding popover (title/description/avatar/cover/badge/timeline). |
| `DataGallerySkeleton`, `DataGallerySkeletonGrid`, `DataGallerySkeletonToolbar` | Loading skeletons. |
| `useDataGallery` | Hook that owns table state + display config + virtualization. |

## Helper Exports

Re-exported from `@docyrus/ui/components/data-gallery`:

| Export | Description |
|--------|-------------|
| `resolveColumnsPerRow({ columnCount, containerWidth, minCardWidth })` | Pure helper for the responsive column-count math. Returns the largest column count whose cards still satisfy `minCardWidth`. |
| `resolveImageUrl(value)` | Walks Docyrus image payloads (string URL, file array, `{ signed_url, … }` object) and returns the first usable URL. |
| `getCardSizePx(size)` | Maps a `DataGalleryCardSize` enum to its pixel cap (`null` for `'full'`). |
| `getCoverHeightPx(style)` | Maps `'top-sm' \| 'top-md' \| 'top-lg'` → pixel heights used by the cover slot. |
| `VARIANT_DISPLAY_PRESETS` | Per-variant display-config snapshot applied when the user picks a new variant. |
| `VARIANT_VISUAL_DEFAULTS` | Per-variant render-time settings (avatar size, title size). |
| `resolveCardLayout({ layoutOrientation, coverStyle })` | Keeps `coverStyle === 'left'` and `layoutOrientation === 'horizontal'` in lockstep — picking one auto-promotes the other. |
| `DEFAULT_GAP`, `DEFAULT_MIN_CARD_WIDTH` | Layout constants. |

Re-exported from `@docyrus/ui/components/data-gallery/lib/data-gallery`:

| Export | Description |
|--------|-------------|
| `getCellValue(row, table, columnId)` | Safe `row.getValue` wrapper that returns `undefined` for columns the table doesn't expose. |
| `getRawCellValue(row, columnId)` | Reads from `row.original[columnId]` directly, bypassing TanStack's `accessorFn`. Used for cover / avatar slots whose full object/array shape would be flattened by Docyrus's `normalizeFieldValue`. |
| `resolveBodyFields({ table, bodyFields, reservedColumnIds })` | Default body-field resolver. |

---

# Data Grid View Select
URL: /docs/web/components/data-grid-view-select

A view selector with integrated view editor for DataGrid. Supports dropdown, horizontal-tabs, and vertical-tabs variants with full CRUD operations on saved views.

**Demo:**

```tsx
'use client';
// @custom-demo

import { useCallback, useState } from 'react';

import {
  DataGrid,
  type ColumnDef,
  type SavedDataGridView,
  applyViewToTable,
  getDataGridSelectColumn,
  getGeneratedViewId,
  useDataGrid

} from '@docyrus/ui/components/data-grid';
import {
  DataGridViewSelect,
  type DataGridViewSelectVariant
} from '@docyrus/ui/components/data-grid-view-select';
import { useMounted } from '@docyrus/ui/primitives/hooks/use-mounted';
import { cn } from '@docyrus/ui/primitives/lib/utils';
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue
} from '@docyrus/ui/primitives/ui/select';
import { Switch } from '@docyrus/ui/primitives/ui/switch';
import { TooltipProvider } from '@docyrus/ui/primitives/ui/tooltip';

type Task = {
  id: number;
  title: string;
  assignee: string;
  status: 'Todo' | 'In Progress' | 'Done';
  priority: 'Low' | 'Medium' | 'High';
  dueDate: string;
  projectName: string;
  projectPhase: 'Discovery' | 'Development' | 'Testing' | 'Shipped';
};

const STATUS_OPTIONS = [{ value: 'Todo', label: 'Todo', color: '#94a3b8' }, { value: 'In Progress', label: 'In Progress', color: '#3b82f6' }, { value: 'Done', label: 'Done', color: '#22c55e' }];

const PRIORITY_OPTIONS = [{ value: 'Low', label: 'Low', color: '#94a3b8' }, { value: 'Medium', label: 'Medium', color: '#f59e0b' }, { value: 'High', label: 'High', color: '#f97316' }];

const PHASE_OPTIONS = [
  { value: 'Discovery', label: 'Discovery', color: '#a78bfa' },
  { value: 'Development', label: 'Development', color: '#3b82f6' },
  { value: 'Testing', label: 'Testing', color: '#f59e0b' },
  { value: 'Shipped', label: 'Shipped', color: '#22c55e' }
];

const TASKS: Task[] = [
  {
    id: 1, title: 'Fix login page crash', assignee: 'Alice', status: 'In Progress', priority: 'High', dueDate: '2026-02-15', projectName: 'Web App', projectPhase: 'Development'
  },
  {
    id: 2, title: 'Add dark mode toggle', assignee: 'Bob', status: 'Todo', priority: 'Medium', dueDate: '2026-03-01', projectName: 'Web App', projectPhase: 'Discovery'
  },
  {
    id: 3, title: 'Update API docs', assignee: 'Carol', status: 'Done', priority: 'Low', dueDate: '2026-01-20', projectName: 'Documentation', projectPhase: 'Shipped'
  },
  {
    id: 4, title: 'Improve search speed', assignee: 'David', status: 'In Progress', priority: 'High', dueDate: '2026-02-28', projectName: 'Backend API', projectPhase: 'Testing'
  },
  {
    id: 5, title: 'Write unit tests', assignee: 'Eve', status: 'Todo', priority: 'Medium', dueDate: '2026-03-10', projectName: 'Backend API', projectPhase: 'Development'
  },
  {
    id: 6, title: 'Design settings page', assignee: 'Alice', status: 'Todo', priority: 'Low', dueDate: '2026-03-20', projectName: 'Web App', projectPhase: 'Discovery'
  }
];

const columns: ColumnDef
                  
                    
                    
                  
                
              </div>
              <label className="flex items-center gap-2">
                
                <span className="text-xs">editable</span>
              </label>
            </div>
          </div>
        </div>
      </div>

      <div className="space-y-3">
        <div className="flex flex-wrap items-center gap-2">
          
        </div>

        
      </div>
    </div>
  );
}

export function DataGridViewSelectDemo() {
  const mounted = useMounted();

  if (!mounted) {
    return (
      <div className="flex h-80 w-full items-center justify-center rounded-lg border border-border bg-muted/30">
        <span className="text-sm text-muted-foreground">Loading...</span>
      </div>
    );
  }

  return (
    
  );
}
```

## Overview

`DataGridViewSelect` combines a view selector and a view editor into a single component. Users can switch between saved views to instantly apply column visibility, ordering, pinning, sorting, grouping, and filter configurations to a `@tanstack/react-table` instance.

When `editable` is enabled, users get full view management: create new views, edit existing ones via a dialog with a dual-box column picker, rename, reorder, delete, and hide/unhide views through a context menu.

The `DataGridViewEditor` sub-component is also exported separately for standalone use outside of the view selector.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-data-grid-view-select
```

**Dependencies:**
- [@tanstack/react-table](https://www.npmjs.com/package/@tanstack/react-table)
- [lucide-react](https://www.npmjs.com/package/lucide-react)
- [react-querybuilder](https://www.npmjs.com/package/react-querybuilder)

## Usage

```tsx
import {
  DataGridViewSelect,
  DataGridViewEditor
} from "@docyrus/ui/components/data-grid-view-select";
import type {
  DataGridViewSelectProps,
  DataGridViewSelectVariant,
  DataGridViewEditorProps
} from "@docyrus/ui/components/data-grid-view-select";
import type { SavedDataGridView } from "@docyrus/ui/components/data-grid";

}
/>
```

## API Reference

### DataGridViewSelectProps

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `table` | `Table<TData>` | -- | TanStack Table instance. Required for reading column definitions. |
| `variant` | `"dropdown" \| "horizontal-tabs" \| "vertical-tabs"` | `"dropdown"` | Visual style of the view selector. |
| `views` | `Array<SavedDataGridView>` | -- | List of saved views to display. |
| `activeViewId` | `string` | -- | Controlled active view ID. |
| `defaultActiveViewId` | `string` | -- | Uncontrolled initial active view ID. |
| `onViewChange` | `(view: SavedDataGridView) => void` | -- | Called when the user selects a different view. |
| `onViewSave` | `(view: SavedDataGridView) => void` | -- | Called when a view is saved (edited) via the editor dialog. |
| `onViewDelete` | `(viewId: string) => void` | -- | Called when a view is deleted via context menu or editor. |
| `onViewCreate` | `(view: SavedDataGridView, position?: { afterViewId?: string; beforeViewId?: string }) => void` | -- | Called when a new view is created. Includes optional position hint. |
| `onViewHide` | `(viewId: string) => void` | -- | Called when a view is hidden via context menu. |
| `onViewUnhide` | `(viewId: string) => void` | -- | Called when a hidden view is unhidden. |
| `hiddenViewIds` | `Array<string>` | -- | List of view IDs that should be marked as hidden. |
| `fields` | `Array<FullField>` | -- | Field definitions for the filter section in the view editor. When provided, enables the filter builder. |
| `editable` | `boolean` | `false` | Enables view CRUD operations (add, edit, delete, hide/unhide, context menu). |
| `disabled` | `boolean` | -- | Disables the entire selector. |
| `placeholder` | `string` | -- | Placeholder text for the dropdown variant when no view is selected. |
| `className` | `string` | -- | Additional CSS class names. |

### DataGridViewEditorProps

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `table` | `Table<TData>` | -- | TanStack Table instance. |
| `open` | `boolean` | -- | Controlled open state. |
| `onOpenChange` | `(open: boolean) => void` | -- | Called when dialog open state changes. |
| `value` | `SavedDataGridView` | -- | The view to edit. When undefined, creates a new view. |
| `views` | `Array<SavedDataGridView>` | -- | List of all views (used for the view switcher inside the dialog). |
| `onSave` | `(view: SavedDataGridView) => void` | -- | Called when the user saves the view. |
| `onDelete` | `(viewId: string) => void` | -- | Called when the user deletes the view. |
| `onCancel` | `() => void` | -- | Called when the user cancels editing. |
| `onViewSwitch` | `(viewId: string) => void` | -- | Called when the user switches to another view from inside the dialog. |
| `fields` | `Array<FullField>` | -- | Field definitions for the filter section. |
| `disabled` | `boolean` | -- | Disables all form controls inside the editor. |
| `showDelete` | `boolean` | -- | Whether to show the delete button. |
| `trigger` | `ReactNode` | -- | Custom trigger element for the dialog. |

---

# Data Grid
URL: /docs/web/components/data-grid

A virtualized, editable spreadsheet-like data grid with sorting, filtering, grouping, cell selection, and keyboard navigation.

**Demo:**

```tsx
'use client';
// @custom-demo

import {
  useCallback, useMemo, useState
} from 'react';

import {
  DataGrid,
  DataGridDisplayMenu,
  DataGridFilterMenu,
  DataGridGroupMenu,
  DataGridKeyboardShortcuts,
  DataGridRowHeightMenu,
  DataGridSortMenu,
  DataGridViewMenu,
  type ColumnDef,
  type RowChange, getDataGridActionsColumn, getDataGridSelectColumn, useDataGrid
} from '@docyrus/ui/components/data-grid';
import { SearchInput } from '@docyrus/ui/components/search-input';
import { useMounted } from '@docyrus/ui/primitives/hooks/use-mounted';
import { Button } from '@docyrus/ui/primitives/ui/button';
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuSeparator,
  DropdownMenuTrigger
} from '@docyrus/ui/primitives/ui/dropdown-menu';
import { TooltipProvider } from '@docyrus/ui/primitives/ui/tooltip';
import { cn } from '@docyrus/ui/primitives/lib/utils';
import { DocyrusIcon } from '@docyrus/ui/components/docyrus-icon';
import {
  Copy, MoreHorizontal, Pencil, Trash2
} from 'lucide-react';

import { PropControls } from '@/components/prop-controls';
import { useDemoData } from '@/data/data-grid-data';

function DataGridDemoInner() {
  const {
    data, columns: columnDefs, props: extraProps, controls
  } = useDemoData();
  const [open, setOpen] = useState(false);
  const [keyword, setKeyword] = useState('');

  type Row = typeof data[number];

  const actionColumn = useMemo
          
            
            
              
              
              
            
          
        </div>
      )
    }),
    [extraProps]
  );

  const columns = [getDataGridSelectColumn
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-data-grid
```

**Dependencies:**
- [lucide-react](https://www.npmjs.com/package/lucide-react)
- [sonner](https://www.npmjs.com/package/sonner)
- [@tanstack/react-table](https://www.npmjs.com/package/@tanstack/react-table)
- [@radix-ui/react-direction](https://www.npmjs.com/package/@radix-ui/react-direction)
- [@types/react](https://www.npmjs.com/package/@types/react)
- [@tanstack/react-virtual](https://www.npmjs.com/package/@tanstack/react-virtual)

## Usage

```tsx
import {
  DataGrid,
  DataGridFieldsMenu,
  DataGridFilterMenu,
  DataGridGroupMenu,
  DataGridKeyboardShortcuts,
  DataGridRowHeightMenu,
  DataGridSortMenu,
  DataGridViewMenu,
  getDataGridSelectColumn,
  useDataGrid
} from '@docyrus/ui/components/data-grid';
import type { ColumnDef, DataGridAction } from '@docyrus/ui/components/data-grid';

const columns: ColumnDef
      
        
        
          
          
        
      
    </div>
  )
});

const columns = [
  getDataGridSelectColumn
  )
});
```

### Bulk Actions

Show action buttons in a floating bar when rows are selected. The bar appears at the bottom of the grid with a count of selected rows and a dismiss button that clears the selection.

```tsx
const actions: DataGridAction
```

## Views

Use `DataGridViewSelect` and `DataGridViewEditor` to let users switch between saved views and create or edit custom ones. Views control column visibility, order, pinning, and sorting.

```tsx
import { applyViewToTable, type SavedDataGridView } from '@docyrus/ui/components/data-grid';
import { DataGridViewSelect } from '@docyrus/ui/components/data-grid-view-select';
import { DataGridViewEditor } from '@docyrus/ui/components/data-grid-view-select';

const [views, setViews] = useState
  )
});
const columns = [getDataGridSelectColumn<Person>(), actionColumn, ...yourColumns];
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `actionCount` | `number` | `2` | Number of inline action buttons. Used to auto-calculate column width when `size` is not provided. |
| `visibleOnHover` | `boolean` | `true` | Hide cell content until row hover on non-touch screens. Uses CSS `@media (hover: hover)` with `transition-opacity`. |
| `size` | `number` | auto | Column width in pixels. If omitted, calculated as `actionCount × 28 + (actionCount − 1) × 2 + 12`. |
| `enableHiding` | `boolean` | `false` | Whether the column can be hidden via view menu |
| `enableResizing` | `boolean` | `false` | Whether the column width can be resized |
| `enableSorting` | `boolean` | `false` | Whether the column is sortable |

The `cell` prop must be provided by the user. Any additional `ColumnDef` props (except `id`, `header`, `meta`) are passed through.

---

## Type Reference

### ColumnDef

Re-exported from `@tanstack/react-table`. Extended with `meta` fields for cell variant configuration and display behavior.

```tsx
{
  accessorKey: string;
  header: string | (() => ReactNode);
  size?: number;
  meta?: {
    label?: string;
    group?: string;
    cell?: CellOpts;
    visibleOnHover?: boolean;
    format?: (value: TValue, row: TData) => string;
  };
}
```

| Meta Field | Type | Description |
|------------|------|-------------|
| `label` | `string` | Display name used in menus, change tracking popover, and filter/sort/group UIs |
| `group` | `string` | Column grouping category |
| `cell` | `CellOpts` | Cell variant and its configuration |
| `visibleOnHover` | `boolean` | Hide cell content until row hover on non-touch screens |
| `format` | `(value: TValue, row: TData) => string` | Custom formatter for cell display and export |

### CellOpts

A discriminated union defining the cell variant and its configuration. Set via `meta.cell` on column definitions.

| Variant | Additional Props | Data Type | Description |
|---------|-----------------|-----------|-------------|
| `short-text` | — | `string` | Single-line text input |
| `long-text` | — | `string` | Multi-line text with expand |
| `email` | — | `string` | Email with mailto link |
| `phone` | — | `string` | Phone number with tel link |
| `number` | `min?`, `max?`, `step?`, `decimalPrecision?`, `thousandSeparator?` | `number` | Numeric input with constraints. Pass `decimalPrecision: 0` + `thousandSeparator: ''` to render identifier-like values (e.g. autonumber: `394` instead of `394.00`). `useDocyrusFieldComponent` applies these defaults for `field-autonumber` automatically. |
| `currency` | `currency?`, `min?`, `max?`, `step?`, `decimalPrecision?`, `thousandSeparator?` | `number` | Formatted currency value. Precision/grouping overrides override the locale defaults. |
| `percent` | `min?`, `max?`, `step?`, `decimalPrecision?`, `thousandSeparator?` | `number` | Percentage display (0-1 range). |
| `url` | — | `string` | Clickable URL link |
| `checkbox` | — | `boolean` | Boolean checkbox |
| `switch` | — | `boolean` | Boolean toggle switch |
| `select` | `options: CellSelectOption[]`, `display?` | `string` | Single-select dropdown. `display: 'text'` renders as plain text instead of badge |
| `status` | `options: CellSelectOption[]`, `display?` | `string` | Color-coded status. `display: 'text'` renders as plain text instead of badge |
| `enum` | `appSlug`, `dataSourceSlug`, `fieldSlug`, `options?`, `display?` | `string` | Backend-driven enum. `display: 'text'` renders as plain text instead of badge |
| `user` | `options: CellUserOption[]` | `string` | User avatar + name select |
| `multi-select` | `options: CellSelectOption[]` | `string` | Multi-value select with badges |
| `tag-select` | `options: CellSelectOption[]` | `string` | Colored tag chips |
| `date` | — | `string` | Date picker (YYYY-MM-DD) |
| `datetime` | — | `string` | Date + time picker (ISO 8601) |
| `time` | — | `string` | Time-only picker (HH:mm) |
| `duration` | — | `string` | Duration display (HH:mm:ss) |
| `date-range` | — | `string` | Date range (start,end) |
| `color` | — | `string` | Color swatch + hex picker |
| `icon` | — | `string` | Icon name selector |
| `currency-code` | — | `string` | ISO currency code (USD, EUR, etc.) |
| `file` | `maxFileSize?`, `maxFiles?`, `accept?`, `multiple?` | `FileCellData[]` | File upload cell |
| `image` | `maxFileSize?`, `accept?` | `string` | Image preview + upload |
| `relation` | `dataSourceId`, `displayField?` | `string` | Related record lookup (requires Docyrus) |
| `rating` | `max?` | `number` | Star rating (default max: 5) |
| `user-multi-select` | `options: CellUserOption[]` | `string` | Multi-user select with avatars |
| `chart` | `chartType?`, `dataKey?`, `color?`, `expandedCellContent?` | `number[]` or `object[]` | Mini sparkline or bar chart (read-only) |

### CellSelectOption

Option definition for `select`, `status`, `multi-select`, and `tag-select` variants.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `label` | `string` | Yes | Display label |
| `value` | `string` | Yes | Internal value |
| `icon` | `FC<SVGProps>` | No | Custom icon component |
| `iconStr` | `string` | No | Icon name string |
| `color` | `string` | No | Badge/tag color (hex) |
| `count` | `number` | No | Faceted count |

### CellUserOption

Extends `CellSelectOption` with user-specific fields.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `...CellSelectOption` | — | — | All select option fields |
| `avatarUrl` | `string` | No | User avatar image URL |
| `initials` | `string` | No | Fallback initials (e.g. "AJ") |

### DataGridAction

Action button definition for the bulk action bar (shown when rows are selected).

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `label` | `string` | Yes | Action button label |
| `icon` | `ReactNode` | No | Action icon |
| `variant` | `'default' \| 'destructive'` | No | Button variant |
| `onAction` | `(selectedRows: Array<TData>) => void` | Yes | Action callback with selected rows |

### CellChange

Represents a single cell's change within a row.

| Field | Type | Description |
|-------|------|-------------|
| `columnId` | `string` | Column ID of the changed cell |
| `originalValue` | `unknown` | Value before editing |
| `newValue` | `unknown` | Current edited value |

### RowChange

Represents all changes in a single row. Passed to `onChangesSave` as an array.

| Field | Type | Description |
|-------|------|-------------|
| `rowId` | `string` | Row identifier |
| `rowIndex` | `number` | Row index in the data array |
| `changes` | `Map<string, CellChange>` | Map of column ID → cell change |

### RowHeightValue

```tsx
type RowHeightValue = 'short' | 'medium' | 'tall' | 'extra-tall';
```

### CellUpdate

Used in paste and data update operations.

| Field | Type | Description |
|-------|------|-------------|
| `rowIndex` | `number` | Target row index |
| `columnId` | `string` | Target column ID |
| `value` | `unknown` | New cell value |

### CellPosition

| Field | Type | Description |
|-------|------|-------------|
| `rowIndex` | `number` | Row index |
| `columnId` | `string` | Column ID |

### FileCellData

Data shape for files in `file` and `image` cell variants.

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | Unique file ID |
| `name` | `string` | File name |
| `size` | `number` | File size in bytes |
| `type` | `string` | MIME type |
| `url` | `string?` | Download/preview URL |

### Direction

```tsx
type Direction = 'ltr' | 'rtl';
```

---

## Keyboard Shortcuts

| Shortcut | Action |
|----------|--------|
| `Arrow Keys` | Navigate between cells |
| `Tab` / `Shift+Tab` | Move to next/previous cell |
| `Enter` | Start editing / Confirm edit |
| `Escape` | Cancel edit / Clear selection |
| `Ctrl+F` | Open search |
| `Ctrl+C` | Copy selected cells |
| `Ctrl+X` | Cut selected cells |
| `Ctrl+V` | Paste from clipboard |
| `Ctrl+A` | Select all cells |
| `Delete` / `Backspace` | Clear selected cells |
| `Home` / `End` | Jump to first/last cell in row |
| `Ctrl+Home` / `Ctrl+End` | Jump to first/last cell in grid |
| `Page Up` / `Page Down` | Scroll up/down by page |
| `Shift+Click` | Range selection |
| `Ctrl+Click` | Toggle cell in selection |

---

# Data Import Wizard
URL: /docs/web/components/data-import-wizard

Multi-step modal wizard that turns an Excel/CSV upload into Docyrus data source records — drag-drop, auto-mapped column→field assignment, per-type config, value-renderer preview, and a result summary.

**Demo:**

```tsx
'use client';

import { useState } from 'react';

import { Button } from '@docyrus/ui/primitives/ui/button';
import {
  DataImportWizard,
  type AnalysedFile,
  type ImportWizardStep,
  type WizardMappingMap, buildAutoMapping
} from '@docyrus/ui/components/data-import-wizard';

const MOCK_FIELDS = [
  {
    id: '1', slug: 'name', name: 'Name', type: 'field-text'
  },
  {
    id: '2', slug: 'email', name: 'Email', type: 'field-email'
  },
  {
    id: '3', slug: 'phone', name: 'Phone', type: 'field-phone'
  },
  {
    id: '4', slug: 'company', name: 'Company', type: 'field-text'
  },
  {
    id: '5',
    slug: 'status',
    name: 'Status',
    type: 'field-status',
    enums: [
      {
        id: 's-active', name: 'Active', color: 'emerald-500', slug: 'active'
      },
      {
        id: 's-lead', name: 'Lead', color: 'blue-500', slug: 'lead'
      },
      {
        id: 's-cold', name: 'Cold', color: 'slate-500', slug: 'cold'
      }
    ]
  },
  {
    id: '6', slug: 'last_contacted', name: 'Last contacted', type: 'field-date'
  }
] as const;

const MOCK_ANALYSED: AnalysedFile = {
  fileName: 'demo-contacts.xlsx',
  columns: [
    'Full Name',
    'Email Address',
    'Phone',
    'Company',
    'Stage',
    'Last Touch'
  ],
  rows: [
    {
      'Full Name': 'Ada Lovelace',
      'Email Address': 'ada@analytical.engine',
      Phone: '5551112233',
      Company: 'Analytical Engine',
      Stage: 'Active',
      'Last Touch': '2026-01-12'
    },
    {
      'Full Name': 'Alan Turing',
      'Email Address': 'alan@bletchley.uk',
      Phone: '5550005555',
      Company: 'Bletchley Park',
      Stage: 'Lead',
      'Last Touch': '2026-02-04'
    },
    {
      'Full Name': 'Grace Hopper',
      'Email Address': 'grace@nhc.mil',
      Phone: '5557778888',
      Company: 'Naval History Command',
      Stage: 'Cold',
      'Last Touch': '2025-11-30'
    }
  ],
  uniqueFieldIds: [],
  uniqueFieldSlugs: ['email']
};

export function DataImportWizardDemo() {
  const [open, setOpen] = useState(false);
  const [step, setStep] = useState
      </div>

      
      {wizard}
    </>
  );
}
```

## Wizard Steps

| Step | Purpose |
|------|---------|
| **Upload** | Drag-drop / file picker. Validates extension + size client-side, then chains `upload → analyse` mutations. |
| **Map fields** | One card per source column. Per type: relation `reference_key`, phone country code, date format, money/phone companion column. Auto-maps obvious matches. |
| **Options** | Toggle "Update existing records on unique-key match" (`upsertUniqueFields`). Summary tiles for row, column, and unique-field counts. |
| **Preview** | Renders the first N rows using `useDocyrusFieldComponent(field.type, 'value-renderer')` so every cell looks like it does in `<DataGrid>`. |
| **Result** | Tiles for successful records, warnings, duplicates, and errors. Per-row error list. "Import another file" / "Done" actions. |

## API Reference

### `<DataImportWizard>`

The dumb component. Drive every prop from your own state — typically through `useDocyrusDataImportWizard`, which already wires every prop. Only reach for the component directly when you need a custom state machine (e.g. a server-component wrapper).

| Prop | Type | Description |
|------|------|-------------|
| `open` / `onOpenChange` | `boolean` / `(open: boolean) => void` | Modal open state. |
| `step` / `onStepChange` | `ImportWizardStep` / `(step) => void` | Current step + setter. Steps: `upload`, `mapping`, `options`, `preview`, `progress`, `result`. |
| `targetFields` | `ReadonlyArray<DocyrusFieldLike>` | Fields the user can map to. Supplied by the hook from `useDocyrusDataViewSelect`. |
| `requiredFieldSlugs` | `ReadonlyArray<string>` | Slugs that must be mapped before leaving the mapping step. |
| `uniqueFieldSlugs` | `ReadonlyArray<string>` | Slugs covered by unique indexes (drives the upsert toggle). |
| `file` / `uploadedFile` / `analysedFile` / `importResult` | various | Snapshots of each phase's payload. |
| `mapping` / `onMappingChange` | `WizardMappingMap` / `(next) => void` | Per-source-column mapping state. |
| `upsertUniqueFields` / `onUpsertChange` | `boolean` / `(next) => void` | Upsert toggle. |
| `isUploading` / `isAnalysing` / `isImporting` | `boolean` | Mutation pending flags. |
| `uploadError` / `analyseError` / `importError` | `Error \| null` | Per-phase errors surfaced in the relevant step's banner. |
| `onPickFile` / `onAnalyse` / `onConfirmMapping` / `onConfirmOptions` / `onStartImport` / `onReset` / `onClose` | callbacks | Hook into each step's primary action. |
| `title` / `description` / `icon` | `ReactNode` / `ReactNode` / `string` | Header customization (defaults are translated). |
| `previewRowCount` | `number` | Default `10`. |
| `maxFileSizeBytes` | `number` | Default `20 * 1024 * 1024` (20 MB). |
| `acceptedExtensions` | `ReadonlyArray<string>` | Default `['xlsx', 'xls', 'csv']`. |
| `className` | `string` | Extra class for the dialog body. |

## Components

| Component | Description |
|-----------|-------------|
| `DataImportWizard` | Top-level shell — composes `AwesomeDialog` + `Stepper` + step bodies + footer. |
| `UploadStep` | Step 1 — drag-drop + file picker + spinners. |
| `MappingStep` | Step 2 — per-column target select + per-type sub-config. |
| `OptionsStep` | Step 3 — upsert toggle + summary tiles. |
| `PreviewStep` | Step 4 — value-renderer-driven preview table. |
| `ProgressStep` | Steps 5/6 — progress UI + result summary tiles. |

Each step component is exported individually so consumers can rearrange or replace them in custom flows.

## Helpers

| Helper | Description |
|--------|-------------|
| `buildAutoMapping(columns, fields)` | Greedy slug + name + token-Jaccard matcher. Returns a `WizardMappingMap`. |
| `inferFieldOptions(field)` | Default `fieldOptions` for `field-relation`, `field-phone`, and `field-date*` (matches the import API contract). |
| `validateMapping(mapping, requiredSlugs)` | Returns `{ valid, missing, duplicateTargets }`. |
| `buildImportOptions(mapping, fields, upsert, uniqueData?)` | Converts UI state to the `{ fieldMapping, fieldOptions, uniqueData, upsertUniqueFields }` POST body. |
| `collectUniqueDataLookups(mapping, fields, analysedFile)` | Identifies columns that benefit from `uniqueData` pre-resolution. |
| `buildUniqueDataPayload(specs, resolved)` | Merges pre-resolved `matchedId` maps with the lookup specs into the final payload entry. |
| `getSecondarySlug(fieldType)` | Returns `'__amount_currency'` / `'__phone_country'` for composite field types. |
| `slugify(value)` / `normalizeKey(value)` | Lowercase / kebab-case helpers used by the auto-mapper. |

## Type Exports

| Type | Description |
|------|-------------|
| `DataImportWizardProps` | Props for the top-level component. |
| `ImportWizardStep` | `'upload' \| 'mapping' \| 'options' \| 'preview' \| 'progress' \| 'result'`. |
| `WizardMappingMap` | `Record<sourceColumn, ColumnMappingState>`. |
| `ColumnMappingState` | Per-source-column UI mapping: target slug, optional companion column, type-specific `fieldOptions`. |
| `UploadedFileInfo` | Shape returned by the upload endpoint. |
| `AnalysedFile` | Shape returned by the analyse endpoint (rows, columns, unique-field hints). |
| `ImportPayloadOptions` | Body posted to the import endpoint. |
| `ImportResultPayload` | Result returned by the import endpoint (success count, errors, duplicates). |
| `MappingValidationResult` | `{ valid, missing, duplicateTargets }`. |
| `ReservedTargetSlug` | `'name' \| 'description' \| 'created_on' \| 'autonumber_id'`. |
| `UniqueDataLookupSpec` | Helper type produced by `collectUniqueDataLookups`. |

## Field-Type Awareness

Like `useDocyrusDataGrid`, every field type is handled automatically:

| Field type | Mapping-step extras | Preview |
|------------|---------------------|---------|
| `field-relation`, `field-relatedField`, `field-userSelect`, `field-userMultiSelect` | `reference_key` text input (defaults to `'name'`). | Relation chip via `RelationValue`. |
| `field-phone` | Default country code input (`+90` default) + companion column for `__phone_country`. | Phone display. |
| `field-money` | Companion column select for `__amount_currency`. | Currency formatter. |
| `field-date`, `field-dateTime`, `field-dateRange` | DAY/MONTH/YEAR ordering select. | Tenant-aware date formatter. |
| `field-enum`, `field-status`, `field-select`, `field-radioGroup`, `field-multiSelect`, `field-tagSelect` | Auto-mapped to the matching slug. | Color-coded enum chip. |
| Reserved (`name`, `description`, `created_on`, `autonumber_id`) | Surfaced in the **System** group. | Plain text. |

## See Also

- [`useDocyrusDataImportWizard`](/docs/web/hooks/use-docyrus-data-import-wizard) — smart hook that wires the wizard to a Docyrus data source in one call.
- [`useDocyrusFieldComponent`](/docs/web/hooks/use-docyrus-field-component) — the registry that powers the preview-step value renderers.
- [`useDocyrusDataGrid`](/docs/web/hooks/use-docyrus-data-grid) — companion hook for displaying the imported records in a grid.

---

# Data Table Filter
URL: /docs/web/components/data-table-filter

A composable filter bar for data tables with text, number, date, option, and multi-option column types.

**Demo:**

```tsx
'use client';
// @custom-demo

import { useState } from 'react';

import { DataTableFilter, useDataTableFilters } from '@docyrus/ui/components/data-table-filter';
import { cn } from '@docyrus/ui/primitives/lib/utils';

import { PropControls } from '@/components/prop-controls';
import { useDemoData } from '@/data/data-table-filter-data';

export function DataTableFilterDemo() {
  const {
    data, columnsConfig, props: extraProps, controls
  } = useDemoData();
  const [open, setOpen] = useState(false);

  const {
    columns, filters, actions, strategy
  } = useDataTableFilters({
    strategy: extraProps.strategy,
    data,
    columnsConfig
  });

  return (
    <div className="w-full">
      <div className="mb-3 flex justify-end">
        <button
          type="button"
          className="inline-flex items-center gap-1.5 rounded-md border border-border bg-background px-3 py-1.5 text-sm font-medium transition-colors hover:bg-accent"
          onClick={() => setOpen(prev => !prev)}>
          <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M12.22 2h-.44a2 2 0 0 0-2 2v.18a2 2 0 0 1-1 1.73l-.43.25a2 2 0 0 1-2 0l-.15-.08a2 2 0 0 0-2.73.73l-.22.38a2 2 0 0 0 .73 2.73l.15.1a2 2 0 0 1 1 1.72v.51a2 2 0 0 1-1 1.74l-.15.09a2 2 0 0 0-.73 2.73l.22.38a2 2 0 0 0 2.73.73l.15-.08a2 2 0 0 1 2 0l.43.25a2 2 0 0 1 1 1.73V20a2 2 0 0 0 2 2h.44a2 2 0 0 0 2-2v-.18a2 2 0 0 1 1-1.73l.43-.25a2 2 0 0 1 2 0l.15.08a2 2 0 0 0 2.73-.73l.22-.39a2 2 0 0 0-.73-2.73l-.15-.08a2 2 0 0 1-1-1.74v-.5a2 2 0 0 1 1-1.74l.15-.09a2 2 0 0 0 .73-2.73l-.22-.38a2 2 0 0 0-2.73-.73l-.15.08a2 2 0 0 1-2 0l-.43-.25a2 2 0 0 1-1-1.73V4a2 2 0 0 0-2-2z" /><circle cx="12" cy="12" r="3" /></svg>
          Configure
          <svg xmlns="http://www.w3.org/2000/svg" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" className={cn('transition-transform duration-200', open && 'rotate-180')}><path d="m6 9 6 6 6-6" /></svg>
        </button>
      </div>
      <div
        className={cn(
          'grid transition-[grid-template-rows] duration-300 ease-in-out',
          open ? 'grid-rows-[1fr]' : 'grid-rows-[0fr]'
        )}>
        <div className="overflow-hidden">
          <div className="mb-4 rounded-lg border border-border bg-muted/30 p-4 grid gap-6">
            <div className="flex flex-wrap items-center gap-4">
              
            </div>
          </div>
        </div>
      </div>
      
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-data-table-filter
```

## Usage

```tsx
import {
  DataTableFilter,
  useDataTableFilters
} from '@docyrus/ui/components/data-table-filter';

const columnsConfig = [
  {
    id: 'title',
    displayName: 'Title',
    icon: TextIcon,
    type: 'text' as const,
    accessor: (row: Task) => row.title
  },
  {
    id: 'status',
    displayName: 'Status',
    icon: CircleIcon,
    type: 'option' as const,
    accessor: (row: Task) => row.status,
    options: [
      { label: 'Todo', value: 'todo' },
      { label: 'Done', value: 'done' }
    ]
  },
  {
    id: 'effort',
    displayName: 'Effort',
    icon: HashIcon,
    type: 'number' as const,
    accessor: (row: Task) => row.effort,
    min: 0,
    max: 100
  },
  {
    id: 'createdAt',
    displayName: 'Created',
    icon: CalendarIcon,
    type: 'date' as const,
    accessor: (row: Task) => row.createdAt
  }
] as const;

function MyFilters() {
  const { columns, filters, actions, strategy } = useDataTableFilters({
    strategy: 'client',
    data: myData,
    columnsConfig
  });

  return (
    
  );
}
```

## Features

- **5 column data types** — text, number, date, option, multiOption
- **Client & server strategies** — Client-side filtering with automatic option counting, or server-side with external filter state
- **Rich operators** — Type-specific operators (contains, is between, is any of, etc.)
- **i18n support** — Built-in locales: English, French, Dutch, German, Chinese (Simplified & Traditional)
- **Faceted counts** — Option counts with visual indicators
- **Keyboard friendly** — Full keyboard navigation through filter controls
- **Mobile responsive** — Adapts layout for mobile viewports
- **Controlled & uncontrolled** — Use internal state or manage filters externally

---

## API Reference

### useDataTableFilters

The main hook that creates columns, manages filter state, and returns action handlers.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `strategy` | `'client' \| 'server'` | — | Filter strategy |
| `data` | `Array<TData>` | — | Row data array |
| `columnsConfig` | `ReadonlyArray<ColumnConfig<TData>>` | — | Column configuration array |
| `defaultFilters` | `FiltersState` | — | Initial filter values (uncontrolled) |
| `filters` | `FiltersState` | — | External filter state (controlled) |
| `onFiltersChange` | `Dispatch<SetStateAction<FiltersState>>` | — | Filter state setter (controlled) |
| `options` | `Partial<Record<OptionColumnIds, ColumnOption[]>>` | — | Server-provided options for option columns |
| `faceted` | `Partial<Record<...>>` | — | Server-provided faceted counts and min/max values |

**Returns:**

| Field | Type | Description |
|-------|------|-------------|
| `columns` | `Array<Column<TData>>` | Enriched column objects with properties |
| `filters` | `FiltersState` | Current filter state |
| `actions` | `DataTableFilterActions` | Filter action handlers |
| `strategy` | `FilterStrategy` | Active strategy |

### DataTableFilter

The rendered filter bar component.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `columns` | `Array<Column<TData>>` | — | Columns from `useDataTableFilters` |
| `filters` | `FiltersState` | — | Filter state from `useDataTableFilters` |
| `actions` | `DataTableFilterActions` | — | Actions from `useDataTableFilters` |
| `strategy` | `FilterStrategy` | — | Strategy from `useDataTableFilters` |
| `locale` | `Locale` | `'en'` | Display locale |

---

## Type Reference

### ColumnConfig

Configuration for a single filterable column.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | `string` | Yes | Unique column identifier |
| `accessor` | `(row: TData) => TVal` | Yes | Function to extract value from row data |
| `displayName` | `string` | Yes | Display label for the filter UI |
| `icon` | `LucideIcon` | Yes | Icon component shown next to the label |
| `type` | `ColumnDataType` | Yes | Column data type |
| `options` | `Array<ColumnOption>` | For option/multiOption | Available options for selection |
| `facetedOptions` | `Map<string, number>` | No | Pre-computed faceted option counts |
| `min` | `number` | For number | Minimum value constraint |
| `max` | `number` | For number | Maximum value constraint |
| `transformOptionFn` | `(value) => ColumnOption` | No | Transform raw values to options |
| `orderFn` | `(a, b) => number` | No | Custom sort order for options |

### ColumnDataType

```tsx
type ColumnDataType = 'text' | 'number' | 'date' | 'option' | 'multiOption';
```

| Type | Native Value | Description |
|------|-------------|-------------|
| `text` | `string` | Searchable text column |
| `number` | `number` | Numeric column with range support |
| `date` | `Date` | Date column with range support |
| `option` | `string` | Single-value from a list of options |
| `multiOption` | `Array<string>` | Zero or more values from a list of options |

### ColumnOption

Option item for `option` and `multiOption` columns.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `label` | `string` | Yes | Display label |
| `value` | `string` | Yes | Internal value |
| `icon` | `ReactElement \| ElementType` | No | Icon component or element |

### FilterStrategy

```tsx
type FilterStrategy = 'client' | 'server';
```

- **`client`** — Hook computes options, faceted counts, and min/max from the provided data array automatically.
- **`server`** — You provide options and faceted counts externally. The hook only manages filter state.

### FilterModel

Represents a single active filter.

| Field | Type | Description |
|-------|------|-------------|
| `columnId` | `string` | Column being filtered |
| `type` | `ColumnDataType` | Column data type |
| `operator` | `FilterOperators[type]` | Active operator |
| `values` | `FilterValues<type>` | Filter values |

### FiltersState

```tsx
type FiltersState = Array<FilterModel>;
```

### DataTableFilterActions

| Method | Signature | Description |
|--------|-----------|-------------|
| `addFilterValue` | `(column, values) => void` | Add values to an option/multiOption filter |
| `removeFilterValue` | `(column, values) => void` | Remove values from an option/multiOption filter |
| `setFilterValue` | `(column, values) => void` | Set filter values (any type) |
| `setFilterOperator` | `(columnId, operator) => void` | Change filter operator |
| `removeFilter` | `(columnId) => void` | Remove a single filter |
| `removeAllFilters` | `() => void` | Clear all active filters |

### Locale

```tsx
type Locale = 'en' | 'fr' | 'nl' | 'zh_CN' | 'zh_TW' | 'de';
```

---

## Filter Operators

### Text Operators

| Operator | Description |
|----------|-------------|
| `contains` | Value contains the search text |
| `does not contain` | Value does not contain the search text |

### Number Operators

| Operator | Description |
|----------|-------------|
| `is` | Equals the value |
| `is not` | Does not equal the value |
| `is less than` | Less than the value |
| `is less than or equal to` | Less than or equal |
| `is greater than` | Greater than the value |
| `is greater than or equal to` | Greater than or equal |
| `is between` | Between two values (inclusive) |
| `is not between` | Outside the range |

### Date Operators

| Operator | Description |
|----------|-------------|
| `is` | Exact date match |
| `is not` | Not this date |
| `is before` | Before the date |
| `is on or before` | On or before the date |
| `is after` | After the date |
| `is on or after` | On or after the date |
| `is between` | Between two dates |
| `is not between` | Outside the date range |

### Option Operators

| Operator | Description |
|----------|-------------|
| `is` | Matches the selected option |
| `is not` | Does not match |
| `is any of` | Matches any of the selected options |
| `is none of` | Matches none of the selected options |

### Multi-Option Operators

| Operator | Description |
|----------|-------------|
| `include` | Includes the selected value |
| `exclude` | Excludes the selected value |
| `include any of` | Includes any of the selected values |
| `include all of` | Includes all selected values |
| `exclude if any of` | Excludes if any of the values match |
| `exclude if all` | Excludes if all values match |

---

# Data Table Side Filters
URL: /docs/web/components/data-table-side-filters

An always-visible side filter panel for e-commerce-style listings — covers every Docyrus field type and emits the same RuleGroupType JSON as the Query Builder.

**Demo:**

```tsx
'use client';
// @custom-demo

import { useMemo } from 'react';

import { DataTableSideFilters, useDataTableSideFilters } from '@docyrus/ui/components/data-table-side-filters';

import {
  getBrandLabel,
  getCategoryMeta,
  getVendorLabel,
  useSideFilterDemoData
} from '@/data/data-table-side-filters-data';

interface Product {
  id: string;
  name: string;
  category: string;
  brand: string;
  tags: Array<string>;
  vendorId: string;
  price: number;
  rating: number;
  inStock: boolean;
  freeShipping: boolean;
  releasedAt: Date;
}

export function DataTableSideFiltersDemo() {
  const {
    data, columnsConfig, query, setQuery
  } = useSideFilterDemoData();

  const {
    columns, filters, actions, strategy
  } = useDataTableSideFilters({
    strategy: 'client',
    data,
    columnsConfig: columnsConfig as never,
    query,
    onQueryChange: setQuery
  });

  const filtered = useMemo(() => {
    if (filters.length === 0) return data as Array<Product>;

    return (data as Array<Product>).filter((row) => {
      return filters.every((filter) => {
        const cell = (row as unknown as Record<string, unknown>)[filter.columnId];

        return matchesFilter(cell, filter);
      });
    });
  }, [data, filters]);

  return (
    <div className="grid gap-4 lg:grid-cols-[280px_1fr]">
      <div className="lg:sticky lg:top-4 lg:self-start">
        
      </div>

      <div className="flex flex-col gap-4 min-w-0">
        <header className="flex items-center justify-between gap-2">
          <p className="text-sm text-muted-foreground">
            <span className="font-medium text-foreground">{filtered.length}</span>
            {' of '}
            <span className="tabular-nums">{data.length}</span>
            {' products'}
          </p>
        </header>

        <div className="grid gap-3 sm:grid-cols-2 xl:grid-cols-3">
          {filtered.slice(0, 12).map(product => (
            
          ))}
          {filtered.length === 0 && (
            <div className="col-span-full rounded-md border border-dashed p-8 text-center text-sm text-muted-foreground">
              No products match the selected filters.
            </div>
          )}
        </div>

        <details className="rounded-md border bg-muted/30 p-3 text-xs">
          <summary className="cursor-pointer select-none font-medium">
            Emitted query (RuleGroupType — same JSON the QueryBuilder consumes)
          </summary>
          <pre className="mt-2 overflow-auto whitespace-pre-wrap text-[11px] leading-relaxed text-muted-foreground">
            {JSON.stringify(query, jsonReplacer, 2)}
          </pre>
        </details>
      </div>
    </div>
  );
}

function ProductCard({ product }: { product: Product }) {
  const meta = getCategoryMeta(product.category);

  return (
    <article className="flex flex-col gap-2 rounded-lg border bg-card p-3 text-sm shadow-sm">
      <div className="flex items-center gap-2 text-xs text-muted-foreground">
        <meta.Icon className="size-3.5" />
        <span>{meta.label}</span>
        <span aria-hidden>·</span>
        <span>{getBrandLabel(product.brand)}</span>
      </div>
      <h4 className="font-medium leading-tight">{product.name}</h4>
      <p className="text-xs text-muted-foreground">
        Vendor: {getVendorLabel(product.vendorId)}
      </p>
      <div className="mt-1 flex items-center justify-between gap-2">
        <span className="text-base font-semibold tabular-nums">${product.price}</span>
        <span className="rounded-full bg-amber-100 px-2 py-0.5 text-[11px] font-medium text-amber-900 dark:bg-amber-500/15 dark:text-amber-300">
          {product.rating.toFixed(1)} ★
        </span>
      </div>
      <div className="flex flex-wrap gap-1 text-[10px] uppercase tracking-wide text-muted-foreground">
        {product.inStock ? <span className="rounded bg-emerald-100 px-1.5 py-0.5 text-emerald-900 dark:bg-emerald-500/15 dark:text-emerald-300">In stock</span> : <span className="rounded bg-red-100 px-1.5 py-0.5 text-red-900 dark:bg-red-500/15 dark:text-red-300">Out</span>}
        {product.freeShipping && (
          <span className="rounded bg-sky-100 px-1.5 py-0.5 text-sky-900 dark:bg-sky-500/15 dark:text-sky-300">Free ship</span>
        )}
      </div>
    </article>
  );
}

function jsonReplacer(_: string, value: unknown) {
  if (value instanceof Date) return value.toISOString();

  return value;
}

function matchesFilter(cell: unknown, filter: { type: string; operator: string; values: Array<unknown> }): boolean {
  if (filter.values.length === 0) return true;
  switch (filter.type) {
    case 'text': {
      const needle = String(filter.values[0] ?? '').toLowerCase();

      return String(cell ?? '').toLowerCase().includes(needle);
    }

    case 'option': {
      return filter.values.includes(cell);
    }

    case 'multiOption': {
      const cellArr = Array.isArray(cell) ? cell : [cell];

      return filter.values.some(v => cellArr.includes(v));
    }

    case 'number': {
      const n = Number(cell);

      if (filter.operator === 'is between' || filter.operator === 'is not between') {
        const min = Number(filter.values[0]);
        const max = Number(filter.values[1]);
        const inside = n >= min && n <= max;

        return filter.operator === 'is between' ? inside : !inside;
      }

      return n === Number(filter.values[0]);
    }

    case 'date': {
      if (!(cell instanceof Date)) return false;
      const t = cell.getTime();
      const from = filter.values[0] instanceof Date ? (filter.values[0] as Date).getTime() : Number.NEGATIVE_INFINITY;
      const to = filter.values[1] instanceof Date ? (filter.values[1] as Date).getTime() : from;

      return t >= from && t <= to;
    }

    case 'boolean': {
      return cell === filter.values[0];
    }

    default:
      return true;
  }
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-data-table-side-filters
```

## Usage

`DataTableSideFilters` is built on top of the same `ColumnConfig` schema used by `DataTableFilter`, so a single column definition can power both the popover-style filter bar **and** the persistent side panel. The side panel emits its filter state as a `RuleGroupType` (the JSON shape `react-querybuilder` expects), so the same payload feeds the Query Builder, your saved-views layer, and your back end.

```tsx
import {
  DataTableSideFilters,
  useDataTableSideFilters
} from '@docyrus/ui/components/data-table-side-filters';

const columnsConfig = [
  {
    id: 'category',
    displayName: 'Category',
    icon: ShoppingBagIcon,
    type: 'option' as const,
    accessor: (row: Product) => row.category,
    options: categoryOptions
  },
  {
    id: 'tags',
    displayName: 'Features',
    icon: StarIcon,
    type: 'multiOption' as const,
    accessor: (row: Product) => row.tags,
    options: tagOptions
  },
  {
    id: 'vendorId',
    displayName: 'Vendor',
    icon: UserIcon,
    type: 'multiOption' as const,
    accessor: (row: Product) => [row.vendorId],
    asyncOptions: {
      load: async ({ search, page, pageSize, signal }) => {
        const res = await fetch(`/api/vendors?q=${search}&page=${page}&size=${pageSize}`, { signal });
        return res.json(); // → { items: ColumnOption[], hasMore: boolean }
      }
    }
  },
  {
    id: 'price',
    displayName: 'Price',
    icon: DollarSignIcon,
    type: 'number' as const,
    accessor: (row: Product) => row.price,
    min: 0,
    max: 500
  },
  {
    id: 'releasedAt',
    displayName: 'Released',
    icon: CalendarIcon,
    type: 'date' as const,
    accessor: (row: Product) => row.releasedAt
  },
  {
    id: 'inStock',
    displayName: 'In stock',
    icon: CircleCheckIcon,
    type: 'boolean' as const,
    accessor: (row: Product) => row.inStock
  }
] as const;

function ProductFilters({ products }: { products: Array<Product> }) {
  const [query, setQuery] = useState<RuleGroupType>({ combinator: 'and', rules: [] });

  const { columns, filters, actions, strategy } = useDataTableSideFilters({
    strategy: 'client',
    data: products,
    columnsConfig,
    query,
    onQueryChange: setQuery
  });

  return (
    
  );
}
```

## Render mode resolution

Each column picks its UI by `column.type`, with overrides via the `defaults` prop:

| Column type | Default render mode | Notes |
|-------------|---------------------|-------|
| `text` | Text input | Debounced; auto-applies the `contains` operator |
| `number` | Slider + Min/Max inputs | Validates `min ≤ max`, clamps to column `min`/`max` |
| `date` | Date range picker | Quick presets (Today / Last 7 days / This month / etc.) |
| `boolean` | Tri-state row (Any / True / False) | "Any" removes the filter |
| `option` (≤ threshold) | Inline checkbox list | Shows faceted counts inline |
| `option` (large list) | Inline checkbox list with **Show more** | Selected items stay pinned above the fold |
| `multiOption` | Same as `option` | Add to/remove from the value list |
| `option` / `multiOption` with `asyncOptions` | Dropdown popover with chips | Debounced server search + paginated load |

Set `defaults[columnId].mode = 'dropdown-chips'` to force a long `option` list into a popover with a chip strip below the trigger — useful for `select`-style fields with many values that you don't want to inline.

## Sections, sticky filters & Show more

Group filters into named sections with the `sections` prop, and pin "always-visible" filters above other sections via `defaults[id].sticky`:

```tsx

```

## Query JSON output

Whenever the user changes a value, the panel emits a `RuleGroupType` like:

```json
{
  "combinator": "and",
  "rules": [
    { "field": "category", "operator": "in", "value": ["audio", "wearables"] },
    { "field": "price", "operator": "between", "value": [50, 250] },
    { "field": "tags", "operator": "containsAll", "value": ["wireless", "noise-cancelling"] },
    { "field": "vendorId", "operator": "in", "value": ["v-1", "v-3"] },
    { "field": "releasedAt", "operator": "between", "value": ["2024-01-01T00:00:00Z", "2024-12-31T23:59:59Z"] },
    { "field": "inStock", "operator": "=", "value": true }
  ]
}
```

This is the exact shape the [Query Builder](/docs/web/docyrus/query-builder) consumes. You can wire both components to the same `query` / `setQuery` state and let the user switch between e-commerce-style facet picking and rule-builder editing without translating data.

Override the operator vocabulary with the `operatorMap` option if your back end expects different operator strings:

```tsx
useDataTableSideFilters({
  // ...
  operatorMap: {
    ...DEFAULT_OPERATOR_MAP,
    text: { contains: 'ilike', 'does not contain': 'not_ilike' }
  }
});
```

## Features

- **Field-aware UI** — text, number range, date range, boolean, options, multi-options, and async relations all render with the right control.
- **Show-more pattern** — long option lists collapse to a configurable threshold; selected items stay pinned so they're never hidden.
- **Chip strips for chosen values** — every popover-driven filter (relation, async, or large select) renders selected values as removable chips below the trigger.
- **Built-in search input** — pass `searchable` to surface a debounced text search at the top of the panel.
- **Sticky / collapsible / hidden sections** — fine-grained control via the `defaults` prop.
- **Active-chip strip & clear actions** — global "Clear all" plus per-section "Clear" out of the box.
- **QueryBuilder-compatible JSON** — emits `RuleGroupType` with operator translation; reverse translator rehydrates a side-panel from any saved query.
- **Controlled & uncontrolled** — pass `defaultQuery` for uncontrolled, or `query` + `onQueryChange` for full external control.
- **Reuses DataTableFilter operators & faceted helpers** — no duplicate operator metadata or counting logic.

---

## API Reference

### useDataTableSideFilters

The main hook. Manages internal `FiltersState`, translates to/from `RuleGroupType`, and returns the values you pass into `<DataTableSideFilters>`.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `strategy` | `'client' \| 'server'` | — | Filter strategy (mirrors `DataTableFilter`) |
| `data` | `Array<TData>` | — | Row data (used for client-side faceting) |
| `columnsConfig` | `ReadonlyArray<ColumnConfig<TData>>` | — | Column configuration array |
| `defaultQuery` | `RuleGroupType` | — | Initial query (uncontrolled) |
| `query` | `RuleGroupType` | — | Controlled query value |
| `onQueryChange` | `(query: RuleGroupType) => void` | — | Emitted whenever the user changes a filter |
| `combinator` | `'and' \| 'or'` | `'and'` | Top-level combinator on the emitted RuleGroup |
| `operatorMap` | `SideFilterOperatorMap` | `DEFAULT_OPERATOR_MAP` | Override DTF→QB operator mapping |
| `defaults` | `SideFilterDefaults` | — | Per-column UI hints |
| `sections` | `ReadonlyArray<SideFilterSectionGroup>` | — | Optional named groupings |
| `options` | `Partial<Record<...>>` | — | Server-supplied options for `option`/`multiOption` columns |
| `faceted` | `Partial<Record<...>>` | — | Server-supplied faceted counts / min-max tuples |
| `calculateFacets` | `boolean` | `true` | Compute facets from `data` (turn off when supplying server-side) |

**Returns:**

| Field | Type | Description |
|-------|------|-------------|
| `columns` | `Array<Column<TData>>` | Enriched column objects |
| `filters` | `FiltersState` | Internal flat filter state |
| `actions` | `DataTableFilterActions` | Same actions as `useDataTableFilters` |
| `strategy` | `FilterStrategy` | Active strategy |
| `query` | `RuleGroupType` | Currently emitted RuleGroup |
| `defaults` | `SideFilterDefaults \| undefined` | Pass-through for the panel |
| `sections` | `ReadonlyArray<SideFilterSectionGroup> \| undefined` | Pass-through for the panel |
| `reset` | `() => void` | Clear all filters |

### DataTableSideFilters

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `columns` | `Array<Column<TData>>` | — | From `useDataTableSideFilters` |
| `filters` | `FiltersState` | — | From `useDataTableSideFilters` |
| `actions` | `DataTableFilterActions` | — | From `useDataTableSideFilters` |
| `strategy` | `FilterStrategy` | — | From `useDataTableSideFilters` |
| `defaults` | `SideFilterDefaults` | — | Per-column UI hints |
| `sections` | `ReadonlyArray<SideFilterSectionGroup>` | — | Named groupings |
| `locale` | `Locale` | `'en'` | i18n locale (shared with `DataTableFilter`) |
| `title` | `ReactNode` | `'Filters'` | Panel header title |
| `showActiveChips` | `boolean` | `true` | Show the active-filter chip strip |
| `showClearAll` | `boolean` | `true` | Show "Clear all" in the header |
| `searchable` | `boolean \| string` | `false` | Show a search input above the sections; pass a column id to bind to a specific text column |
| `variant` | `'default' \| 'bordered' \| 'compact'` | `'default'` | Visual style |
| `clearAllLabel` | `string` | `'Clear all'` | Label for the global clear button |
| `clearLabel` | `string` | `'Clear'` | Label for per-section clear |
| `className` | `string` | — | Extra classes on the panel root |

### SideFilterColumnDefaults

| Field | Type | Description |
|-------|------|-------------|
| `mode` | `'auto' \| 'text-input' \| 'inline-checkbox' \| 'dropdown-chips' \| 'date' \| 'date-range' \| 'numeric-range' \| 'boolean'` | Force a specific render mode |
| `showMoreThreshold` | `number` | Collapse inline checkbox list above N items (default `8`) |
| `collapsed` | `boolean` | Section starts collapsed |
| `sticky` | `boolean` | Pin section above all unpinned sections |
| `title` | `ReactNode` | Override the section title (defaults to `column.displayName`) |
| `hidden` | `boolean` | Hide the column from the panel completely |

### SideFilterSectionGroup

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | Unique group id |
| `title` | `ReactNode` | Group heading |
| `columnIds` | `ReadonlyArray<string>` | Column ids that belong to this group, in render order |
| `withDivider` | `boolean` | Render a divider above the group title (default `true`) |

---

## Translator helpers

Standalone utilities exposed for advanced use (e.g. saved-views, hydrating from URL):

| Export | Signature | Description |
|--------|-----------|-------------|
| `filtersStateToRuleGroup` | `(state: FiltersState, combinator?, operatorMap?) => RuleGroupType` | Convert internal filters to a QueryBuilder rule group |
| `ruleGroupToFiltersState` | `(group: RuleGroupType, columns, operatorMap?) => FiltersState` | Reverse: parse a rule group into internal filters (drops rules whose `field` doesn't match a known column) |
| `DEFAULT_OPERATOR_MAP` | `SideFilterOperatorMap` | The default DTF → QB operator mapping (`contains`, `=`, `between`, `in`, etc.) |

---

## Sub-components

The panel is composed of building blocks you can reach for directly when you need a custom layout. They're all exported from the same entry point:

| Component | Description |
|-----------|-------------|
| `SideFilterSection` | Collapsible section wrapper used per column |
| `SideFilterActiveChips` | Active-filter chip strip with per-chip remove |
| `SideFilterSearch` | Debounced text-search bound to a specific text column |
| `SideFilterClear` | "Clear all" button (shows count) |
| `SideFilterText` | Single-column text input controller |
| `SideFilterCheckboxList` | Inline checkbox list with "Show more" |
| `SideFilterOptionsDropdown` | Static-options dropdown with chips |
| `SideFilterAsyncOptions` | Async-loaded dropdown with chips |
| `SideFilterDateRange` | Date-range picker with presets |
| `SideFilterNumericRange` | Numeric range slider + min/max inputs with validation |
| `SideFilterBoolean` | Tri-state radio (Any / True / False) |

---

## Type Exports

| Type | Description |
|------|-------------|
| `DataTableSideFiltersProps` | Props for `<DataTableSideFilters>` |
| `DataTableSideFiltersOptions` | Options for `useDataTableSideFilters()` |
| `UseDataTableSideFiltersReturn` | Return type of `useDataTableSideFilters()` |
| `SideFilterColumnDefaults` | Per-column UI overrides |
| `SideFilterDefaults` | `Record<string, SideFilterColumnDefaults>` |
| `SideFilterSectionGroup` | Section grouping descriptor |
| `SideFilterRenderMode` | All render-mode strings |
| `SideFilterCombinator` | `'and' \| 'or'` |
| `SideFilterOperatorMap` | DTF → QB operator override map |

---

# Data Table
URL: /docs/web/components/data-table

A lightweight, read-only TanStack table for Docyrus data sources with value renderers, row selection, grouping, and optional pagination.

**Demo:**

```tsx
'use client';
// @custom-demo

import { useMemo, useState } from 'react';

import {
  getCoreRowModel,
  getExpandedRowModel,
  getFilteredRowModel,
  getGroupedRowModel,
  getPaginationRowModel,
  getSortedRowModel,
  useReactTable,
  type ColumnDef,
  type ExpandedState,
  type GroupingState,
  type PaginationState,
  type RowSelectionState,
  type SortingState
} from '@tanstack/react-table';
import {
  Building2,
  Mail,
  MoreHorizontal,
  Phone,
  Pencil,
  Plus,
  Trash2
} from 'lucide-react';

import {
  DataGridGroupMenu,
  DataGridSortMenu
} from '@docyrus/ui/components/data-grid';
import { DataTable, getDataTableSelectColumn } from '@docyrus/ui/components/data-table';
import { IdentityValue } from '@docyrus/ui/components/value-renderers/identity-value';
import { StatusValue } from '@docyrus/ui/components/value-renderers/status-value';
import { TextValue } from '@docyrus/ui/components/value-renderers/text-value';
import { UserValue } from '@docyrus/ui/components/value-renderers/user-value';
import { Button } from '@docyrus/ui/primitives/ui/button';
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuSeparator,
  DropdownMenuTrigger
} from '@docyrus/ui/primitives/ui/dropdown-menu';
import { Input } from '@docyrus/ui/primitives/ui/input';
import { TooltipProvider } from '@docyrus/ui/primitives/ui/tooltip';
import { cn } from '@docyrus/ui/primitives/lib/utils';

import { PropControls, type PropControl } from '@/components/prop-controls';

type CompanyRow = {
  id: string;
  name: string;
  owner: string;
  ownerAvatar?: string;
  ownerInitials?: string;
  status: 'active' | 'onboarding' | 'paused';
  phone: string;
  email: string;
  city: string;
  segment: string;
};

const ROWS: Array
          
          
            
            
          
        
      )
    }
  ], [enableRowNumbers]);

  const filteredData = useMemo(() => {
    const needle = keyword.trim().toLowerCase();

    if (!needle) return ROWS;

    return ROWS.filter(row => [
      row.name,
      row.owner,
      row.email,
      row.city,
      row.segment,
      row.status
    ].some(value => value.toLowerCase().includes(needle)));
  }, [keyword]);

  const table = useReactTable({
    data: filteredData,
    columns,
    state: {
      sorting,
      rowSelection,
      grouping,
      expanded,
      pagination: enablePagination ? pagination : {
        pageIndex: 0,
        pageSize: Number.MAX_SAFE_INTEGER
      }
    },
    onSortingChange: setSorting,
    onRowSelectionChange: setRowSelection,
    onGroupingChange: setGrouping,
    onExpandedChange: setExpanded,
    onPaginationChange: setPagination,
    getCoreRowModel: getCoreRowModel(),
    getSortedRowModel: getSortedRowModel(),
    getFilteredRowModel: getFilteredRowModel(),
    getGroupedRowModel: getGroupedRowModel(),
    getExpandedRowModel: getExpandedRowModel(),
    getPaginationRowModel: getPaginationRowModel(),
    enableRowSelection: true,
    autoResetPageIndex: false
  });

  const controls: Array
      </div>

      <div className="mb-4 rounded-lg border border-border bg-muted/30 p-4">
        
      </div>

      
  );
}
```

## When To Use

Use `DataTable` when you want the Docyrus field rendering layer and saved-view ergonomics without the heavier editable spreadsheet behavior of `DataGrid`.

- Read-only rendering only
- Standard HTML table layout using the shadcn `Table` primitive
- Works with TanStack sorting, grouping, selection, and pagination
- Lets app developers compose their own toolbar and surrounding UI freely

`DataTable` intentionally does **not** provide editable cells, display mode switching, row-height controls, paste support, or grid-style keyboard navigation.

## Usage

```tsx
import {
  DataTable,
  getDataTableSelectColumn
} from '@docyrus/ui/components/data-table';
import {
  DataGridGroupMenu,
  DataGridSortMenu
} from '@docyrus/ui/components/data-grid';
import {
  getCoreRowModel,
  getExpandedRowModel,
  getGroupedRowModel,
  getPaginationRowModel,
  getSortedRowModel,
  useReactTable,
  type ColumnDef
} from '@tanstack/react-table';

const columns: Array<ColumnDef<Row>> = [
  getDataTableSelectColumn<Row>({ enableRowNumbers: true }),
  {
    accessorKey: 'name',
    header: 'Company'
  },
  {
    accessorKey: 'status',
    header: 'Status',
    meta: { groupable: true }
  }
];

function MyTable({ data }: { data: Array<Row> }) {
  const table = useReactTable({
    data,
    columns,
    getCoreRowModel: getCoreRowModel(),
    getSortedRowModel: getSortedRowModel(),
    getGroupedRowModel: getGroupedRowModel(),
    getExpandedRowModel: getExpandedRowModel(),
    getPaginationRowModel: getPaginationRowModel()
  });

  return (
    <div className="space-y-3">
      <div className="flex items-center gap-2">
        
        
      </div>
      
    </div>
  );
}
```

## `useDocyrusDataTable`

For Docyrus data-source screens, use the hook to combine field metadata, value renderers, saved views, remote loading, and toolbar controls.

```tsx
import { DataTable } from '@docyrus/ui/components/data-table';
import { useDocyrusDataTable } from '@docyrus/ui/hooks/use-docyrus-data-table';

function OrganizationsTable() {
  const {
    table,
    tableProps,
    toolbar,
    sidePanel
  } = useDocyrusDataTable({
    client,
    appSlug: 'base',
    dataSourceSlug: 'organization',
    collection,
    users
  });

  return (
    <div className="flex gap-4">
      {sidePanel}
      <div className="min-w-0 flex-1 space-y-3">
        {toolbar}
        
      </div>
    </div>
  );
}
```

## Features

- `getDataTableSelectColumn()` supports checkbox selection and optional row numbers in the select column.
- Grouped rows render inline with expand/collapse controls and group counts.
- Identity values can render in compact UUID mode with tooltip + copy affordance.
- `useDocyrusDataTable()` reuses Docyrus saved views, search, filter, sort, grouping, export, and paging behavior.

## API Notes

### `DataTable`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `table` | `Table<TData>` | — | TanStack table instance |
| `emptyText` | `string` | `'No results.'` | Empty state label |
| `isLoading` | `boolean` | `false` | Shows loading row state |
| `pagination` | `boolean` | `false` | Renders the standard pagination footer |
| `containerClassName` | `string` | — | Wrapper border/container styling |
| `rowClassName` | `string \| (row) => string` | — | Per-row styling hook |

### `getDataTableSelectColumn`

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enableRowNumbers` | `boolean` | `false` | Shows row numbers when the row is not selected |
| `size` | `number` | `44` | Fixed select-column width |

### `useDocyrusDataTable`

The hook mirrors the lightweight table workflow:

- returns `table`, `tableProps`, `toolbar`, `sidePanel`, `items`, `resolvedListParams`, `pagingMode`, and `reload`
- supports `mapColumn`, `extraColumns`, `actionsColumn`, `showSelectColumn`, `enableRowNumbers`, and toolbar content slots
- stays read-only by design

---

# Date Time Picker
URL: /docs/web/components/date-time-picker

Date Time Picker component with multiple variants and sizes.

**Demo:**

```tsx
'use client';
// @custom-demo

import { useState } from 'react';

import { useForm } from 'react-hook-form';

import { DateTimePicker } from '@docyrus/ui/components/date-time-picker';
import { Button } from '@docyrus/ui/primitives/ui/button';
import {
  Form,
  FormField
} from '@docyrus/ui/primitives/ui/form';

export function DateTimePickerDemo() {
  const [submitted, setSubmitted] = useState<string | null>(null);
  const [defaultValues] = useState(() => ({
    startDate: new Date(),
    endDate: new Date(Date.now() + 60 * 60 * 1000)
  }));

  const form = useForm({
    defaultValues
  });

  const onSubmit = (values: { startDate: Date; endDate: Date }) => {
    setSubmitted(JSON.stringify(values, null, 2));
  };

  return (
    <div className="w-full max-w-md space-y-4">
      
        </form>
      
      {submitted && (
        <pre className="rounded-lg border bg-muted/30 p-3 text-xs">
          {submitted}
        </pre>
      )}
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-date-time-picker
```

**Dependencies:**
- [class-variance-authority](https://www.npmjs.com/package/class-variance-authority)
- [react-hook-form](https://www.npmjs.com/package/react-hook-form)
- [lucide-react](https://www.npmjs.com/package/lucide-react)
- [date-fns](https://www.npmjs.com/package/date-fns)

## Usage

```tsx
import {
  DateTimePicker
} from "@docyrus/ui/components/date-time-picker";

```

## Sizes

| Size | Description |
|------|-------------|
| `sm` | Small — `gap-1 text-sm` |
| `default` | Default — `gap-1.5` |
| `lg` | Large — `gap-2 text-lg` |

## API Reference

| Prop | Type | Default |
|------|------|---------|
| `size` | `"sm"` \| `"default"` \| `"lg"` | `"default"` |
| `className` | `string` | — |

---

# Date Time Range Picker
URL: /docs/web/components/date-time-range-picker

Date Time Range Picker component with multiple variants and sizes.

**Demo:**

```tsx
'use client';
// @custom-demo

import { useState } from 'react';

import { useForm } from 'react-hook-form';

import { DateTimeRangePicker } from '@docyrus/ui/components/date-time-range-picker';
import { Button } from '@docyrus/ui/primitives/ui/button';
import {
  Form,
  FormField
} from '@docyrus/ui/primitives/ui/form';

type ScheduleValues = { startDate: Date | null; endDate: Date | null };

export function DateTimeRangePickerDemo() {
  const [submitted, setSubmitted] = useState<string | null>(null);

  const form = useForm
        </form>
      
      {submitted && (
        <pre className="rounded-lg border bg-muted/30 p-3 text-xs">
          {submitted}
        </pre>
      )}
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-date-time-range-picker
```

**Dependencies:**
- [class-variance-authority](https://www.npmjs.com/package/class-variance-authority)
- [react-hook-form](https://www.npmjs.com/package/react-hook-form)
- [lucide-react](https://www.npmjs.com/package/lucide-react)
- [date-fns](https://www.npmjs.com/package/date-fns)

## Usage

```tsx
import {
  DateTimeRangePicker
} from "@docyrus/ui/components/date-time-range-picker";

```

## Sizes

| Size | Description |
|------|-------------|
| `sm` | Small — `gap-1 text-sm` |
| `default` | Default — `gap-1.5` |
| `lg` | Large — `gap-2 text-lg` |

## API Reference

| Prop | Type | Default |
|------|------|---------|
| `size` | `"sm"` \| `"default"` \| `"lg"` | `"default"` |
| `className` | `string` | — |

---

# Day Picker
URL: /docs/web/components/day-picker

Day Picker component with multiple variants and sizes.

**Demo:**

```tsx
'use client';
// @custom-demo

import { useState } from 'react';

import { DayPicker } from '@docyrus/ui/components/day-picker';
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue
} from '@docyrus/ui/primitives/ui/select';
import { cn } from '@docyrus/ui/primitives/lib/utils';

export function DayPickerDemo() {
  type Variant = 'default' | 'outline' | 'ghost';
  const [variant, setVariant] = useState
                  
                    
                    
                  
                
              </div>
              <div className="space-y-1.5">
                <span className="text-xs font-medium">Size</span>
                
                  
                    
                    
                  
                
              </div>
            </div>
          </div>
        </div>
      </div>
      
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-day-picker
```

**Dependencies:**
- [class-variance-authority](https://www.npmjs.com/package/class-variance-authority)
- [lucide-react](https://www.npmjs.com/package/lucide-react)
- [react-day-picker](https://www.npmjs.com/package/react-day-picker)

## Usage

```tsx
import {
  DayPicker
} from "@docyrus/ui/components/day-picker";

```

## Variants

| Variant | Description |
|---------|-------------|
| `default` | Default style |
| `outline` | Outline — `border border-border rounded-xl` |
| `ghost` | Ghost — `bg-transparent` |

## Sizes

| Size | Description |
|------|-------------|
| `default` | Default — `[--cell-size:36px] text-sm` |
| `sm` | Small — `[--cell-size:28px] p-2 text-xs` |
| `lg` | Large — `[--cell-size:44px] p-4 text-base` |

## API Reference

| Prop | Type | Default |
|------|------|---------|
| `variant` | `"default"` \| `"outline"` \| `"ghost"` | `"default"` |
| `size` | `"default"` \| `"sm"` \| `"lg"` | `"default"` |
| `showOutsideDays` | `boolean` | `true` |
| `fixedWeeks` | `boolean` | — |
| `numberOfMonths` | `number` | — |
| `captionLayout` | `'label' \| 'dropdown' \| 'dropdown-months' \| 'dropdown-years'` | — |
| `className` | `string` | — |

---

# Delete Confirm Dialog
URL: /docs/web/components/delete-confirm-dialog

Delete Confirm Dialog component with multiple variants and sizes.

**Demo:**

```tsx
'use client';
// @custom-demo

import { useState } from 'react';

import { DeleteConfirmDialog } from '@docyrus/ui/components/delete-confirm-dialog';
import { Button } from '@docyrus/ui/primitives/ui/button';

export function DeleteConfirmDialogDemo() {
  const [open, setOpen] = useState(false);

  return (
    <div className="flex flex-wrap items-center gap-3">
      
      <DeleteConfirmDialog
        open={open}
        onOpenChange={setOpen}
        objectName="item"
        count={3}
        onConfirm={() => setOpen(false)} />
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-delete-confirm-dialog
```

## Usage

```tsx
import {
  DeleteConfirmDialog
} from "@docyrus/ui/components/delete-confirm-dialog";

<DeleteConfirmDialog
  open
  onOpenChange={() => {}}
  objectName="..."
  count={0}
  onConfirm={() => {}}
  isPending
/>
```

## API Reference

| Prop | Type | Default |
|------|------|---------|
| `open` | `boolean` | — |
| `onOpenChange` | `(open: boolean) => void` | — |
| `objectName` | `string` | — |
| `count` | `number` | — |
| `onConfirm` | `() => void \| Promise<void>` | — |
| `isPending` | `boolean` | — |
| `className` | `string` | — |

---

# Docyrus Data Source Picker
URL: /docs/web/components/docyrus-data-source-picker

Docyrus Data Source Picker component with multiple variants and sizes.

**Demo:**

```tsx
'use client';

import { Database, FileJson, ServerCog } from 'lucide-react';

export function DocyrusDataSourcePickerDemo() {
  return (
    <div className="flex w-full flex-col gap-4 rounded-lg border border-dashed bg-muted/20 p-6">
      <div className="flex items-center gap-3">
        <div className="flex size-9 items-center justify-center rounded-lg bg-primary/10 text-primary">
          
        </div>
        <div className="flex flex-col">
          <span className="text-sm font-semibold">DocyrusDataSourcePicker</span>
          <span className="text-xs text-muted-foreground">
            Render-prop wrapper — pairs an apps → data sources tree with a record picker dialog.
          </span>
        </div>
      </div>

      <div className="grid gap-2 text-xs">
        <div className="flex items-center gap-2 rounded-md border bg-background px-3 py-2">
          
          <span className="font-mono">TreeSelect</span>
          <span className="text-muted-foreground">— pick an app / data source</span>
        </div>
        <div className="flex items-center gap-2 rounded-md border bg-background px-3 py-2">
          
          <span className="font-mono">Select record</span>
          <span className="text-muted-foreground">— opens a record picker backed by useDocyrusDataTable</span>
        </div>
      </div>

      <p className="text-[11px] leading-relaxed text-muted-foreground">
        Requires a Docyrus
        {' '}
        <code className="rounded bg-muted px-1">RestApiClient</code>
        {' '}
        — see the JSONata / Handlebars / Adaptive Card editor pages in the playground for live usage.
      </p>
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-docyrus-data-source-picker
```

**Dependencies:**
- [lucide-react](https://www.npmjs.com/package/lucide-react)

## Usage

```tsx
import {
  DocyrusDataSourcePicker
} from "@docyrus/ui/components/docyrus-data-source-picker";

```

## API Reference

| Prop | Type | Default |
|------|------|---------|
| `schema` | `JsonSchema \| null` | — |
| `selectedDataSource` | `DataSource \| null` | — |
| `jsonataContextPaths` | `Array<ContextPath>` | — |
| `handlebarsContextPaths` | `Array<ContextPath>` | — |
| `selectedRecord` | `Record<string, unknown> \| null` | — |
| `recordText` | `string` | — |
| `hasSelection` | `boolean` | — |
| `className` | `string` | — |

---

# Docyrus Icon
URL: /docs/web/components/docyrus-icon

Docyrus Icon component with multiple variants and sizes.

**Demo:**

```tsx
'use client';
// @custom-demo

import { useState } from 'react';

import { DocyrusIcon } from '@docyrus/ui/components/docyrus-icon';
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue
} from '@docyrus/ui/primitives/ui/select';
import { cn } from '@docyrus/ui/primitives/lib/utils';

export function DocyrusIconDemo() {
  type Size = 'xs' | 'sm' | 'default' | 'lg' | 'xl';
  const [size, setSize] = useState
                  
                    
                    
                    
                    
                  
                
              </div>
              <div className="space-y-1.5">
                <span className="text-xs font-medium">Animation</span>
                
                  
                    
                    
                    
                    
                  
                
              </div>
            </div>
          </div>
        </div>
      </div>
      
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-docyrus-icon
```

**Dependencies:**
- [react-inlinesvg](https://www.npmjs.com/package/react-inlinesvg)
- [class-variance-authority](https://www.npmjs.com/package/class-variance-authority)

## Usage

```tsx
import {
  DocyrusIcon
} from "@docyrus/ui/components/docyrus-icon";

```

## Sizes

| Size | Description |
|------|-------------|
| `xs` | Extra small — `size-3` |
| `sm` | Small — `size-4` |
| `default` | Default — `size-5` |
| `lg` | Large — `size-6` |
| `xl` | Extra large — `size-8` |

## Animation

| Animation | Description |
|-----------|-------------|
| `none` | Default (no animation) |
| `spin` | Spin — `animate-spin` |
| `pulse` | Pulse — `animate-pulse` |
| `bounce` | Bounce — `animate-bounce` |
| `ping` | Ping — `animate-ping` |

## API Reference

| Prop | Type | Default |
|------|------|---------|
| `size` | `"xs"` \| `"sm"` \| `"default"` \| `"lg"` \| `"xl"` | `"default"` |
| `animation` | `"none"` \| `"spin"` \| `"pulse"` \| `"bounce"` \| `"ping"` | `"default"` |
| `icon` | `string` | — |
| `lib` | `string` | — |
| `group` | `string \| null` | — |
| `className` | `string` | — |

---

# Dummy Data Generator
URL: /docs/web/components/dummy-data-generator

Multi-step modal wizard that generates Docyrus-compatible sample records — per-field strategies (text/number/date/enum/relation), value-renderer preview, and an opt-in batch save to the data source.

**Demo:**

```tsx
'use client';

import { useMemo, useState } from 'react';

import {
  DummyDataGenerator,
  type DummyDataGeneratorStep,
  type DummyGenerationResult,
  type DummyStrategyMap,
  buildInitialStrategyMap,
  generateDummyRows

} from '@docyrus/ui/components/dummy-data-generator';

const MOCK_FIELDS = [
  {
    id: '1', slug: 'name', name: 'Name', type: 'field-text'
  },
  {
    id: '2', slug: 'email', name: 'Email', type: 'field-email'
  },
  {
    id: '3', slug: 'phone', name: 'Phone', type: 'field-phone'
  },
  {
    id: '4', slug: 'company', name: 'Company', type: 'field-text'
  },
  {
    id: '5',
    slug: 'status',
    name: 'Status',
    type: 'field-status',
    enums: [
      {
        id: 's-active', name: 'Active', color: 'emerald-500', slug: 'active'
      },
      {
        id: 's-lead', name: 'Lead', color: 'blue-500', slug: 'lead'
      },
      {
        id: 's-cold', name: 'Cold', color: 'slate-500', slug: 'cold'
      }
    ]
  },
  {
    id: '6', slug: 'rating', name: 'Rating', type: 'field-rating'
  },
  {
    id: '7', slug: 'amount', name: 'Amount', type: 'field-money'
  },
  {
    id: '8', slug: 'created_on', name: 'Created on', type: 'field-dateTime'
  }
] as const;

export function DummyDataGeneratorDemo() {
  const [step, setStep] = useState
    
    
  </>
);
```

## Wizard Steps

| Step | Purpose |
|------|---------|
| **Configure** | Pick how many records to generate, then tune each field individually. Strategies are pre-filled per field type (text shape, number range, date window, enum subset, etc.). Read-only or unsupported fields are auto-skipped. |
| **Preview** | Renders the first N rows using `useDocyrusFieldComponent(field.type, 'value-renderer')` so every cell looks the same as it does in `<DataGrid>`. "Regenerate sample" reseeds the PRNG. |
| **Progress** | One spinner while the hook walks each row through `collection.create` (or `client.post('…/items', row)`). |
| **Result** | Tiles for created / failed / total rows. Per-row error list when inserts fail. |

## Field-Type Strategies

| Field type | Default strategy | Configurable |
|------------|------------------|--------------|
| `field-text`, `field-textarea`, `field-code` | Slug-aware sentence/full-name/company/job-title detection. | Text shape (word, sentence, paragraph, full name, company, job title, static). |
| `field-email`, `field-url`, `field-color`, `field-icon`, `field-currency` | Random pick from a bundled pool. | — |
| `field-phone` | Random number with default country code. | Country code (e.g. `+90`). |
| `field-number`, `field-money`, `field-percent`, `field-duration`, `field-rating` | Random integer in a sensible range. | Mode (`random` / `sequence` / `fixed`), min / max, integer toggle. |
| `field-money` | Adds the companion `__<slug>_currency` value automatically. | Plus currency code (e.g. `USD`). |
| `field-checkbox`, `field-switch` | 50/50 boolean. | Truth ratio slider. |
| `field-date`, `field-dateTime` | Random date within last 30 days. | Mode (`recent` / `past` / `future` / `random` / `now`), days window. |
| `field-dateRange` | Pair of dates with a random span. | Same plus max span in days. |
| `field-time` | Random `HH:mm`. | — |
| `field-select`, `field-radioGroup`, `field-status`, `field-enum`, `field-systemEnum` | Random pick from `field.enums` / `field.options`. | Subset of allowed option ids. |
| `field-multiSelect`, `field-tagSelect` | 1–3 random picks. | Subset of option ids, items-per-row range. |
| `field-userSelect`, `field-userMultiSelect` | Random pick from the `users` array passed to the hook. | Subset of user ids. |
| `field-relation` | Random pick from the `relationOptionsByFieldSlug[slug]` pool. Skipped if the pool isn't supplied. | Subset of relation ids. |
| `field-json` | Generates `{ sample, generated, index }`. | — |
| `field-formula`, `field-relatedField`, `field-identity`, `field-autonumber`, files, images, html / doc editors, location select, query builder, schema repeater, … | **Skipped automatically.** | — |

The deterministic seed (Mulberry32) means the preview matches the rows that get inserted — pressing **Regenerate sample** reseeds and re-renders.

## API Reference

### `<DummyDataGenerator>`

The component renders as an inline panel (header + stepper + step body + footer). Wrap it in your own dialog / drawer / sheet if you want modal behavior.

| Prop | Type | Description |
|------|------|-------------|
| `step` / `onStepChange` | `DummyDataGeneratorStep` / `(step) => void` | Current step + setter. Steps: `configure`, `preview`, `progress`, `result`. |
| `targetFields` | `ReadonlyArray<DocyrusFieldLike>` | Fields the user can populate. Supplied by the hook from `useDocyrusDataViewSelect`. |
| `requiredFieldSlugs` | `ReadonlyArray<string>` | Slugs locked to `enabled: true`. |
| `count` / `onCountChange` | `number` / `(next) => void` | Number of records to generate. |
| `maxCount` | `number` | UI hard cap. Default `1000`. |
| `strategies` / `onStrategiesChange` | `DummyStrategyMap` / `(next) => void` | Per-field generation knobs keyed by slug. |
| `generatedRows` / `onRegenerate` | `Array<Record<string, unknown>>` / `() => void` | Generated rows (preview + insert) and a "reseed" callback. |
| `isGenerating` / `isCreating` | `boolean` | Internal pending flags surfaced in the spinner / footer. |
| `generationError` / `result` | `Error \| null` / `DummyGenerationResult \| null` | Final-step state. |
| `previewOnly` | `boolean` | When `true` the preview-step CTA is "Finish" — the hook never POSTs. |
| `users` | `ReadonlyArray<DummyUserOption>` | Tenant users used by user-select strategies (and shown in the configure step). |
| `onConfirmConfigure` / `onStartGeneration` / `onReset` | callbacks | Hook into each step's primary action. |
| `previewRowCount` | `number` | Default `10`. |
| `exportFileName` | `string` | File name (without extension) for CSV / XLSX downloads. Default `'dummy-data'`. |
| `title` / `description` / `icon` | `ReactNode` / `ReactNode` / `string` | Header customization (defaults are translated). |
| `className` | `string` | Extra class for the panel root. |

## Components

| Component | Description |
|-----------|-------------|
| `DummyDataGenerator` | Top-level shell — composes `AwesomeDialog` + `Stepper` + step bodies + footer. |
| `ConfigureStep` | Step 1 — count slider + per-field strategy controls. |
| `PreviewStep` | Step 2 — value-renderer-driven preview table + reseed button. |
| `ProgressStep` | Steps 3/4 — progress spinner + result tiles + per-row error list. |

## Helpers

| Helper | Description |
|--------|-------------|
| `buildInitialStrategyMap(fields, existing?)` | Per-slug strategy map seeded from `inferStrategyForField`. Reuses any existing user overrides. |
| `inferStrategyForField(field)` | Default strategy for a single field. |
| `isSupportedFieldType(type)` | `false` for read-only, file, html-editor, location, formula, etc. |
| `generateDummyRows(ctx)` | Pure deterministic generator. Returns `count` rows of slug → value pairs. |
| `createRng(seed)` | Mulberry32 PRNG used internally — exported for tests. |

## Type Exports

| Type | Description |
|------|-------------|
| `DummyDataGeneratorProps` | Props for the top-level component. |
| `DummyDataGeneratorStep` | `'configure' \| 'preview' \| 'progress' \| 'result'`. |
| `DummyStrategyMap` | `Record<fieldSlug, DummyFieldStrategy>`. |
| `DummyFieldStrategy` | Per-field generation knobs (`enabled`, `textMode`, `min`, `max`, `dateMode`, `selectedOptionIds`, …). |
| `DummyGenerationContext` | Pure-generator input (`fields`, `strategies`, `count`, `seed`, `users?`, `relationOptionsByFieldSlug?`). |
| `DummyGenerationResult` | `{ totalGenerated, totalCreated, totalFailed, errors }`. |
| `DummyUserOption` | User pool entry shape (`id`, `name?`, `display_name?`, `email?`, `avatar_url?`). |
| `DummyRelationOption` | Relation pool entry shape (`id`, `name`). |

## See Also

- [`useDocyrusDummyDataGeneratorWizard`](/docs/web/hooks/use-docyrus-dummy-data-generator-wizard) — smart hook that wires the wizard to a Docyrus data source in one call.
- [`useDocyrusDataImportWizard`](/docs/web/hooks/use-docyrus-data-import-wizard) — companion wizard for ingesting real spreadsheets.
- [`useDocyrusFieldComponent`](/docs/web/hooks/use-docyrus-field-component) — the registry that powers the preview-step value renderers.

---

# Duration Select
URL: /docs/web/components/duration-select

Duration Select component with multiple variants and sizes.

**Demo:**

```tsx
'use client';
// @custom-demo

import { useState } from 'react';

import { DurationSelect, type DurationFormat } from '@docyrus/ui/components/duration-select';
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue
} from '@docyrus/ui/primitives/ui/select';
import { Switch } from '@docyrus/ui/primitives/ui/switch';
import { cn } from '@docyrus/ui/primitives/lib/utils';

export function DurationSelectDemo() {
  const [value, setValue] = useState<number | null>(3900);
  const [format, setFormat] = useState
                  
                    
                    
                  
                
              </div>
              <label className="flex items-center gap-2">
                
                <span className="text-xs">Disabled</span>
              </label>
            </div>
          </div>
        </div>
      </div>
      <div className="mx-auto max-w-xs">
        
      </div>
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-duration-select
```

**Dependencies:**
- [lucide-react](https://www.npmjs.com/package/lucide-react)

## Usage

```tsx
import {
  DurationSelect
} from "@docyrus/ui/components/duration-select";

<DurationSelect
  value={...}
  onChange={() => {}}
  format="compact"
  minuteIncrement={5}
  maxHours={8}
  placeholder="..."
/>
```

## API Reference

| Prop | Type | Default |
|------|------|---------|
| `value` | `number \| null \| undefined` | — |
| `onChange` | `(seconds: number \| null) => void` | — |
| `format` | `DurationFormat` | `'compact'` |
| `minuteIncrement` | `number` | `5` |
| `maxHours` | `number` | `8` |
| `disabled` | `boolean` | `false` |
| `invalid` | `boolean` | `false` |
| `placeholder` | `string` | — |
| `className` | `string` | — |

---

# Editable Record Detail
URL: /docs/web/components/editable-record-detail

Inline record editing with change tracking, validation, hidden fields, and a floating action bar.

**Demo:**

```tsx
'use client';

import { useCallback, useState } from 'react';

import { type EnumOption } from '@docyrus/ui/components/form-fields';

import {
  EditableRecordDetail,
  EditableRecordDetailField,
  type FieldChange,
  type RecordDetailField
} from '@docyrus/ui/components/editable-record-detail';
import { cn } from '@docyrus/ui/primitives/lib/utils';
import { Switch } from '@docyrus/ui/primitives/ui/switch';

// ── Field configs ──────────────────────────────────────────

const PRIORITY_OPTIONS: Array
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-editable-record-detail
```

**Dependencies:**
- [lucide-react](https://www.npmjs.com/package/lucide-react)

## Usage

```tsx
import {
  EditableRecordDetail,
  EditableRecordDetailField,
  useEditableRecordDetail
} from "@docyrus/ui/components/editable-record-detail";

```

## API Reference

### EditableRecordDetailProps

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `fields` | `Array<RecordDetailField>` | — | Field configurations |
| `record` | `Record<string, unknown>` | — | Current record values keyed by field slug |
| `onSave` | `(changes: Array<FieldChange>, values: Record<string, unknown>) => void \| Promise<void>` | — | Called when save is triggered |
| `onCancel` | `() => void` | — | Called when cancel is triggered |
| `form` | `any` | — | External TanStack Form instance (skips internal macro-form) |
| `readOnly` | `boolean` | `false` | Whether all fields are read-only |
| `disabled` | `boolean` | `false` | Whether all fields are disabled |
| `trackChanges` | `boolean` | `true` | Whether changed fields should be visually highlighted |
| `actionBarSideOffset` | `number` | — | Side offset for the floating action bar |
| `children` | `ReactNode` | — | Content (EditableRecordDetailField components) |
| `className` | `string` | — | Additional CSS class |

### RecordDetailField

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `field` | `IField` | — | Field configuration object |
| `enumOptions` | `Array<EnumOption>` | — | Enum options for select-based fields |
| `readOnly` | `boolean` | — | Whether this field is read-only |
| `required` | `boolean \| ((values: Record<string, unknown>) => boolean)` | — | Whether the field is required. Supports a callback for computed required based on other field values |
| `hidden` | `boolean \| ((values: Record<string, unknown>) => boolean)` | — | Whether the field should be hidden. Supports a callback for computed visibility based on other field values. Hidden fields are excluded from validation |
| `appSlug` | `string` | — | App slug for dynamic enum loading |
| `dataSourceSlug` | `string` | — | Data source slug for dynamic enum loading |

### EditableRecordDetailFieldProps

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `slug` | `string` | — | Field slug (looks up config from context) |
| `label` | `ReactNode` | — | Optional label override |
| `showLabel` | `boolean` | `true` | Render label + value row |
| `className` | `string` | — | Additional CSS class |

### useEditableRecordDetail

Hook to access the EditableRecordDetail context from within the provider.

| Return | Type | Description |
|--------|------|-------------|
| `form` | `any` | The form instance (internal macro-form or external) |
| `values` | `Record<string, unknown>` | Current record values |
| `changedFields` | `Set<string>` | Set of changed field slugs |
| `changedFieldCount` | `number` | Number of changed fields |
| `valuesVersion` | `number` | Counter that increments on every field value change. Use to trigger re-renders for cross-field reactivity |
| `isFieldChanged` | `(slug: string) => boolean` | Check if a specific field has changed |
| `getFieldValue` | `(slug: string) => unknown` | Get the current value of a field |
| `setFieldValue` | `(slug: string, value: unknown) => void` | Programmatically set a field value and trigger re-render |
| `getChanges` | `() => Array<FieldChange>` | Get all pending changes |
| `handleSave` | `() => Promise<void>` | Trigger save with validation |
| `handleCancel` | `() => void` | Discard all changes and reset to original values |
| `isSaving` | `boolean` | Whether a save is in progress |

### FieldChange

| Property | Type | Description |
|----------|------|-------------|
| `fieldSlug` | `string` | Field slug |
| `fieldName` | `string` | Field display name |
| `originalValue` | `unknown` | Value before change |
| `newValue` | `unknown` | Current value |

---

# Editable Value
URL: /docs/web/components/editable-value

Inline editable field with display/edit mode switching, popover auto-open, and change tracking.

**Demo:**

```tsx
'use client';

import { useState } from 'react';

import { type EnumOption, type IField } from '@docyrus/ui/components/form-fields';

import { EditableValue } from '@docyrus/ui/components/editable-value';
import { cn } from '@docyrus/ui/primitives/lib/utils';
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue
} from '@docyrus/ui/primitives/ui/select';
import { Switch } from '@docyrus/ui/primitives/ui/switch';

// ── Field configs ──────────────────────────────────────────

const FIELDS = {
  text: {
    id: '1', name: 'Company Name', slug: 'company_name', type: 'field-text'
  },
  number: {
    id: '2', name: 'Revenue', slug: 'revenue', type: 'field-number'
  },
  email: {
    id: '3', name: 'Email', slug: 'email', type: 'field-email'
  },
  url: {
    id: '4', name: 'Website', slug: 'website', type: 'field-url'
  },
  phone: {
    id: '5', name: 'Phone', slug: 'phone', type: 'field-phone'
  },
  money: {
    id: '6', name: 'Budget', slug: 'budget', type: 'field-money'
  },
  percent: {
    id: '7', name: 'Completion', slug: 'completion', type: 'field-percent'
  },
  duration: {
    id: '8', name: 'Duration', slug: 'duration', type: 'field-duration'
  },
  currency: {
    id: '9', name: 'Currency', slug: 'currency_code', type: 'field-currency'
  },
  checkbox: {
    id: '10', name: 'Active', slug: 'active', type: 'field-checkbox'
  },
  switchField: {
    id: '11', name: 'Notifications', slug: 'notifications', type: 'field-switch'
  },
  rating: {
    id: '12', name: 'Rating', slug: 'rating', type: 'field-rating'
  },
  select: {
    id: '13', name: 'Priority', slug: 'priority', type: 'field-select'
  },
  status: {
    id: '14', name: 'Status', slug: 'status', type: 'field-status'
  },
  radioGroup: {
    id: '15', name: 'Type', slug: 'type', type: 'field-radioGroup'
  },
  enumField: {
    id: '16', name: 'Category', slug: 'category', type: 'field-enum'
  },
  multiSelect: {
    id: '17', name: 'Tags', slug: 'tags', type: 'field-multiSelect'
  },
  tagSelect: {
    id: '18', name: 'Labels', slug: 'labels', type: 'field-tagSelect'
  },
  date: {
    id: '19', name: 'Founded Date', slug: 'founded_date', type: 'field-date'
  },
  dateTime: {
    id: '20', name: 'Last Login', slug: 'last_login', type: 'field-dateTime'
  },
  time: {
    id: '21', name: 'Start Time', slug: 'start_time', type: 'field-time'
  },
  dateRange: {
    id: '22', name: 'Sprint Dates', slug: 'sprint_dates', type: 'field-dateRange'
  },
  color: {
    id: '23', name: 'Brand Color', slug: 'brand_color', type: 'field-color'
  },
  icon: {
    id: '24', name: 'Icon', slug: 'icon', type: 'field-icon'
  },
  approvalStatus: {
    id: '25',
    name: 'Approval',
    slug: 'approval',
    type: 'field-approvalStatus',
    options: {
      placeholder: 'Add approval comment...',
      canRespond: true,
      currentUser: {
        userId: 'u2',
        name: 'Bob Smith'
      }
    }
  }
} satisfies Record<string, IField>;

const PRIORITY_OPTIONS: Array
                  
                    
                  
                
              </div>
              <div className="space-y-1.5">
                <span className="text-xs font-medium">Size</span>
                
                  
                    
                    
                  
                
              </div>
              <label className="flex items-center gap-2">
                
                <span className="text-xs">Show Actions</span>
              </label>
              <label className="flex items-center gap-2">
                
                <span className="text-xs">Explicit Save</span>
              </label>
              <label className="flex items-center gap-2">
                
                <span className="text-xs">Disabled</span>
              </label>
            </div>
          </div>
        </div>
      </div>
      <div className="mx-auto max-w-lg space-y-6 rounded-lg border bg-background p-6">
        {/* Inline Fields */}
        <section>
          <h4 className="mb-3 text-xs font-semibold uppercase tracking-wider text-muted-foreground">Inline Fields</h4>
          <div className="flex flex-col gap-3">
            
            
            
            
            <Row label="Phone" field={FIELDS.phone} value={phone} onValueChange={setPhone} record={phoneRecord} onCompanionChange={changes => setPhoneRecord(prev => ({ ...prev, ...changes }))} {...shared} />
            <Row label="Money" field={FIELDS.money} value={money} onValueChange={setMoney} record={moneyRecord} onCompanionChange={changes => setMoneyRecord(prev => ({ ...prev, ...changes }))} {...shared} />
            
            
            
            
            
            
          </div>
        </section>

        {/* Popover / Select Fields */}
        <section>
          <h4 className="mb-3 text-xs font-semibold uppercase tracking-wider text-muted-foreground">Popover / Select Fields</h4>
          <div className="flex flex-col gap-3">
            
            
            
            
            
            
            
          </div>
        </section>

        {/* Date / Time Fields */}
        <section>
          <h4 className="mb-3 text-xs font-semibold uppercase tracking-wider text-muted-foreground">Date / Time Fields</h4>
          <div className="flex flex-col gap-3">
            
            
            
            
          </div>
        </section>

        {/* Visual Fields */}
        <section>
          <h4 className="mb-3 text-xs font-semibold uppercase tracking-wider text-muted-foreground">Visual Fields</h4>
          <div className="flex flex-col gap-3">
            
            
          </div>
        </section>
      </div>
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-editable-value
```

**Dependencies:**
- [class-variance-authority](https://www.npmjs.com/package/class-variance-authority)
- [lucide-react](https://www.npmjs.com/package/lucide-react)

## Usage

```tsx
import {
  EditableValue
} from "@docyrus/ui/components/editable-value";

<EditableValue
  variant="default"
  size="sm"
  field={...}
  value={...}
  onValueChange={() => {}}
  onCompanionChange={() => {}}
  record={...}
  enumOptions={EnumOption[]}
  form={...}
  disabled
  readOnly
  showActions
  explicitSave
  editing
  onEditingChange={() => {}}
  trackChanges
  changed
  appSlug="..."
  dataSourceSlug="..."
/>
```

## Variants

| Variant | Description |
|---------|-------------|
| `default` | Default style |
| `ghost` | Ghost variant |

## Sizes

| Size | Description |
|------|-------------|
| `sm` | Small — `min-h-7 px-1.5 py-0.5 text-xs` |
| `default` | Default — `min-h-9 px-2 py-1 text-sm` |
| `lg` | Large — `min-h-11 px-3 py-1.5 text-base` |

## API Reference

| Prop | Type | Default |
|------|------|---------|
| `variant` | `"default"` \| `"ghost"` | `"default"` |
| `size` | `"sm"` \| `"default"` \| `"lg"` | `"default"` |
| `field` | `IField` | — |
| `value` | `unknown` | — |
| `onValueChange` | `(value: unknown) => void` | — |
| `onCompanionChange` | `(changes: Record<string, unknown>) => void` | — |
| `record` | `Record<string, unknown>` | — |
| `enumOptions` | `Array<EnumOption>` | — |
| `form` | `any` | — |
| `disabled` | `boolean` | — |
| `readOnly` | `boolean` | — |
| `showActions` | `boolean` | — |
| `explicitSave` | `boolean` | — |
| `editing` | `boolean` | — |
| `onEditingChange` | `(editing: boolean) => void` | — |
| `trackChanges` | `boolean` | — |
| `changed` | `boolean` | — |
| `editHint` | `"progressive"` \| `"visible"` | `"progressive"` |
| `appSlug` | `string` | — |
| `dataSourceSlug` | `string` | — |
| `className` | `string` | — |

---

# Editor Agent
URL: /docs/web/components/editor-agent

Editor Agent component.

**Demo:**

```tsx
'use client';

import { useEffect, useMemo, useState } from 'react';

import {
  type EditorAgentClient,
  EditorAgent
} from '@docyrus/ui/components/editor-agent';
import { Button } from '@docyrus/ui/primitives/ui/button';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { Bot } from 'lucide-react';

/*
 * EditorAgent is auth-aware — it needs an authenticated REST `client`, the
 * current `user`, an `apiBaseUrl`, and a `getAccessToken` callback. The docs
 * site has none of those, so this demo wires a no-op client that satisfies
 * the type contract and returns empty payloads. The drawer renders, threads
 * load empty, and `sendMessage` is a noop — perfect for visual exploration.
 *
 * For real wiring (auth + chat), see the docyrus-client integration in
 * `developer-tools-ai-assistant.tsx` (project repo) where `@docyrus/signin`
 * supplies `client`, `user`, and `getAccessToken`.
 */
const DEMO_API_BASE = 'https://api.docyrus.example/v1';
const DEMO_CHAT_URL = `${DEMO_API_BASE}/ai/agents/demo-agent-id/chat`;

const DEMO_AGENT_ENVELOPE = {
  id: 'demo-agent-id',
  name: 'Docyrus AI',
  description: 'Your intelligent document assistant',
  avatar: { name: 'Docyrus AI', color: '#6366f1' }
};

const DEMO_ASSISTANT_REPLY = 'This is a simulated response. In a real application, this would be powered by a language model via the Vercel AI SDK `useChat` hook.';

function buildMockChatStream(): Response {
  const encoder = new TextEncoder();
  const id = 'demo-msg';
  const events = [
    { type: 'start' },
    { type: 'start-step' },
    { type: 'text-start', id },
    { type: 'text-delta', id, delta: DEMO_ASSISTANT_REPLY },
    { type: 'text-end', id },
    { type: 'finish-step' },
    { type: 'finish' }
  ];

  const stream = new ReadableStream
  );
}

function EditorAgentDemoInner() {
  const [open, setOpen] = useState(false);
  const client = useStubClient();

  useMockChatFetch();

  return (
    <div className="relative h-150 w-full overflow-hidden rounded-lg border bg-background">
      <div className="absolute right-3 top-3 z-20">
        
      </div>

      <div className="flex h-full items-center justify-center px-6 text-center">
        <div className="max-w-md space-y-2">
          <h3 className="text-base font-semibold">Editor canvas</h3>
          <p className="text-sm text-muted-foreground">
            Imagine a JSONata expression editor, a Handlebars template, or a
            Query Builder rendered here. The assistant slides in from the left
            and shares the same surface area.
          </p>
        </div>
      </div>

      <EditorAgent
        agentId="demo-agent-id"
        apiBaseUrl={DEMO_API_BASE}
        client={client}
        getAccessToken={() => null}
        open={open}
        senderNameFallback="Docs Visitor"
        user={null}
        width={420}
        onClose={() => setOpen(false)} />
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-editor-agent
```

**Dependencies:**
- [@ai-sdk/react](https://www.npmjs.com/package/@ai-sdk/react)
- [ai](https://www.npmjs.com/package/ai)
- [zod](https://www.npmjs.com/package/zod)
- [lucide-react](https://www.npmjs.com/package/lucide-react)

## Usage

```tsx
import {
  type EditorAgentClient,
  type EditorAgentProps,
  type EditorAgentUser,
  type IEditorAgentClientTool,
  EditorAgent
} from "@docyrus/ui/components/editor-agent";

<type EditorAgentClient
  agentId="..."
  open
  onClose={() => {}}
  client={...}
  user={...}
  apiBaseUrl="..."
  getAccessToken={() => {}}
  width={DEFAULT_WIDTH_PX}
  acceptFileTypes="DEFAULT_ACCEPT_FILE_TYPES"
  allowAttachments={true}
  dataSourceId={...}
  extraBody={() => {}}
  clientTools={ReadonlyIEditorAgentClientTool[]}
  editorContext={() => {}}
  senderNameFallback="Editor"
/>
```

## API Reference

| Prop | Type | Default |
|------|------|---------|
| `agentId` | `string` | — |
| `open` | `boolean` | — |
| `onClose` | `() => void` | — |
| `client` | `EditorAgentClient \| null \| undefined` | — |
| `user` | `EditorAgentUser \| null` | — |
| `apiBaseUrl` | `string` | — |
| `getAccessToken` | `() => string \| null \| Promise<string \| null>` | — |
| `width` | `number` | `DEFAULT_WIDTH_PX` |
| `acceptFileTypes` | `string` | `DEFAULT_ACCEPT_FILE_TYPES` |
| `allowAttachments` | `boolean` | `true` |
| `dataSourceId` | `string \| null` | — |
| `extraBody` | `() => Record<string, unknown> \| null \| undefined` | — |
| `clientTools` | `ReadonlyArray<IEditorAgentClientTool>` | — |
| `editorContext` | `() => string \| null \| undefined` | — |
| `senderNameFallback` | `string` | `'Editor'` |
| `className` | `string` | — |

## Components

| Component | Description |
|-----------|-------------|
| `type EditorAgentClient` | Public export |
| `type EditorAgentProps` | Public export |
| `type EditorAgentUser` | Public export |
| `type IEditorAgentClientTool` | Public export |
| `EditorAgent` | Public export |
| `CodyAgentToggle` | Internal — `cody-agent-toggle.tsx` |

---

# Email Composer
URL: /docs/web/components/email-composer

Rich text email composer with sender-account picker, formatting toolbar, recipients, attachments, and i18n support.

**Demo:**

```tsx
'use client';

import {
  useCallback, useMemo, useState
} from 'react';

import { CalendarDays, FileText } from 'lucide-react';

import {
  EmailComposer,
  type EmailAttachment,
  type EmailComposerMentionUser,
  type EmailComposerSize,
  type EmailComposerSlashCommand,
  type EmailComposerSlashCommandContext,
  type EmailComposerVariant
} from '@docyrus/ui/components/email-composer';
import { Button } from '@docyrus/ui/primitives/ui/button';
import {
  Dialog,
  DialogContent,
  DialogFooter,
  DialogHeader,
  DialogTitle
} from '@docyrus/ui/primitives/ui/dialog';
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue
} from '@docyrus/ui/primitives/ui/select';
import { Switch } from '@docyrus/ui/primitives/ui/switch';
import { Textarea } from '@docyrus/ui/primitives/ui/textarea';
import { cn } from '@docyrus/ui/primitives/lib/utils';

const MENTION_USERS: EmailComposerMentionUser[] = [
  {
    id: '1', firstname: 'Alex', lastname: 'Johnson', email: 'alex@docyrus.com'
  },
  {
    id: '2', firstname: 'Maria', lastname: 'Garcia', email: 'maria@docyrus.com'
  },
  {
    id: '3', firstname: 'James', lastname: 'Smith', email: 'james@docyrus.com'
  },
  {
    id: '4', firstname: 'Yuki', lastname: 'Tanaka', email: 'yuki@docyrus.com'
  },
  {
    id: '5', firstname: 'Fatma', lastname: 'Yilmaz', email: 'fatma@docyrus.com'
  }
];

/**
 * Developer-drawn dialog for the `/template` slash command — the demo owns the
 * whole dialog (shell + Cancel / Send buttons) and only calls
 * `context.insert(html)` / `context.cancel()`.
 */
function TemplateSlashDialog({ context }: { context: EmailComposerSlashCommandContext }) {
  const [text, setText] = useState('Hi,\n\nThanks for reaching out — here is the summary we discussed.');

  const handleInsert = useCallback(() => {
    const html = text
      .split('\n')
      .map(line => (line.trim() ? `<p>${line}</p>` : '<br>'))
      .join('');

    context.insert(html);
  }, [context, text]);

  return (
    
        
        
          
        
      
    
  );
}

export function EmailComposerDemo() {
  const [variant, setVariant] = useState
                  
                    
                    
                  
                
              </div>
              <div className="space-y-1.5">
                <span className="text-xs font-medium">Size</span>
                
                  
                    
                    
                  
                
              </div>
              <label className="flex items-center gap-2">
                
                <span className="text-xs">Toolbar</span>
              </label>
              <label className="flex items-center gap-2">
                
                <span className="text-xs">Disabled</span>
              </label>
              <label className="flex items-center gap-2">
                
                <span className="text-xs">Signature</span>
              </label>
            </div>
          </div>
        </div>
      </div>
      <div className="mx-auto max-w-2xl">
        
      </div>
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-email-composer
```

**Dependencies:**
- [lucide-react](https://www.npmjs.com/package/lucide-react)
- [class-variance-authority](https://www.npmjs.com/package/class-variance-authority)

## Usage

```tsx
import {
  EmailComposer
} from "@docyrus/ui/components/email-composer";

          
        
      
    
  );
}
```

Notes:

- The insertion position is saved when the command is picked, so the dialog can stay open as long as needed — `insert` lands the HTML exactly where the `/` was typed (falling back to the end of the body if that position no longer exists).
- Render whatever dialog implementation you like (the `Dialog` primitive, a custom modal, a drawer) — the returned node is rendered inside the composer, and portal-based dialogs work as expected.
- Inserted HTML is delivered to recipients as-is: use inline styles for any formatting, the app's stylesheet does not exist in email clients.
- Omit `slashCommands` (or pass an empty array) to disable the feature entirely.

## Variants

| Variant | Description |
|---------|-------------|
| `default` | Default style |
| `outline` | Outline — `border-border` |
| `minimal` | Minimal — `border-transparent shadow-none` |

## Sizes

| Size | Description |
|------|-------------|
| `sm` | Small — `text-xs` |
| `default` | Default — `text-sm` |
| `lg` | Large — `text-base` |

## API Reference

| Prop | Type | Default |
|------|------|---------|
| `variant` | `"default"` \| `"outline"` \| `"minimal"` | `"default"` |
| `size` | `"sm"` \| `"default"` \| `"lg"` | `"default"` |
| `accounts` | `EmailComposerAccount[]` | — | Sender accounts surfaced in the From dropdown. Hides the row when omitted. |
| `selectedAccountId` | `string \| null` | — | Currently selected account id. |
| `onSelectedAccountChange` | `(accountId: string) => void` | — | Called when the user picks a different account from the dropdown. |
| `to` | `string[]` | — |
| `onToChange` | `(to: string[]) => void` | — |
| `cc` | `string[]` | — |
| `onCcChange` | `(cc: string[]) => void` | — |
| `bcc` | `string[]` | — |
| `onBccChange` | `(bcc: string[]) => void` | — |
| `subject` | `string` | — |
| `onSubjectChange` | `(subject: string) => void` | — |
| `body` | `string` | — | HTML body content (rich text via contentEditable) |
| `onBodyChange` | `(body: string) => void` | — | Called with HTML string on body change |
| `mentionUsers` | `EmailComposerMentionUser[]` | — | Users offered by the body editor's `@` mention autocomplete. Omit to disable mentions. |
| `slashCommands` | `EmailComposerSlashCommand[]` | — | Developer-defined commands offered by the body editor's `/` autocomplete. Omit to disable slash commands. |
| `onSend` | `() => void` | — |
| `onAttach` | `() => void` | — |
| `onDiscard` | `() => void` | — |
| `sending` | `boolean` | — |
| `disabled` | `boolean` | — |
| `attachments` | `EmailAttachment[]` | — |
| `onRemoveAttachment` | `(index: number) => void` | — |
| `showToolbar` | `boolean` | `true` |
| `signature` | `string` | — | HTML content of the email signature |
| `onSignatureChange` | `(signature: string) => void` | — | Called when signature content changes. When provided, the signature area becomes editable |
| `signatureVisible` | `boolean` | `true` | Whether the signature is visible (when signature is provided) |
| `onSignatureVisibleChange` | `(visible: boolean) => void` | — | Called when the user toggles signature visibility |
| `className` | `string` | — |

## Type Exports

| Type | Description |
|------|-------------|
| `EmailComposerAccount` | `{ id; name; senderEmail; senderName?; kind?: 'tenant' \| 'user'; provider?: string \| null; isUserAccessible? }` — minimum shape consumed by the From dropdown. `provider` drives the brand icon (Google / Microsoft / AWS, else a generic mail icon). The Docyrus-backed account DTO (`DocyrusEmailAccount`) extends this. |
| `EmailAttachment` | `{ name; size }` — local attachment metadata for display. |
| `EmailComposerMentionUser` | `{ id; firstname?; lastname?; email?; photo? }` — user entry consumed by the `@` mention autocomplete. `email` powers the chip's `mailto:` link, `photo` the list avatar. |
| `EmailComposerSlashCommand` | `{ id; label; description?; icon?; keywords?; getContent?; renderDialog? }` — a `/` command definition. `getContent` returns HTML to insert (async supported); `renderDialog` renders a fully developer-owned dialog instead. |
| `EmailComposerSlashCommandContext` | `{ query; insert(html); cancel() }` — bridge API handed to `renderDialog`. `insert` injects at the trigger position and closes; `cancel` closes without inserting. |
| `EmailComposerVariant` | `'default' \| 'outline' \| 'minimal'`. |
| `EmailComposerSize` | `'sm' \| 'default' \| 'lg'`. |

---

# Email Template Editor
URL: /docs/web/components/email-template-editor

A standalone, beehiiv-style email template editor built on PlateJS. A rich block canvas with a "+"/slash insert palette and merge-tag chips, a full Theme panel (Basic + Advanced) that live-styles every part of the email via CSS variables, email-safe HTML serialization, and a multi-provider preview simulator (Gmail / Outlook / Apple Mail / Mobile / Dark).

**Demo:**

```tsx
'use client';

import {
  cloneDefaultTheme,
  EmailTemplateEditor,
  type EmailDocument
} from '@docyrus/ui/components/email-template-editor';

/*
 * Rich sample that exercises the editor-renderable blocks + inlines so every
 * Theme-panel control has something visible to affect (headings H1-H6, marks,
 * links, bulleted + numbered lists, blockquote, content break, table, merge
 * tags). The footer preview reflects the Email Footer theme section.
 */
const SAMPLE_DOC: EmailDocument = {
  blocks: [
    {
      type: 'h1',
      children: [{ text: 'Welcome, ' }, { type: 'merge_tag', name: 'first_name', children: [{ text: '' }] }, { text: '!' }]
    },
    {
      type: 'p',
      children: [
        { text: 'Your weekly product update — open the ' },
        { text: 'Theme', bold: true },
        { text: ' tab and watch every block restyle live, then check ' },
        { text: 'Preview', bold: true },
        { text: ' to see it across Gmail, Outlook, Apple Mail and mobile.' }
      ]
    },
    {
      type: 'p',
      children: [
        { text: 'Marks: ' },
        { text: 'bold', bold: true },
        { text: ', ' },
        { text: 'italic', italic: true },
        { text: ', ' },
        { text: 'underline', underline: true },
        { text: ', a ' },
        { type: 'a', url: 'https://example.com', children: [{ text: 'themed link' }] },
        { text: '.' }
      ]
    },
    { type: 'h2', children: [{ text: 'This week' }] },
    {
      type: 'p', indent: 1, listStyleType: 'disc', children: [{ text: 'Faster load times' }]
    },
    {
      type: 'p', indent: 1, listStyleType: 'disc', children: [{ text: 'Redesigned dashboard' }]
    },
    {
      type: 'p', indent: 1, listStyleType: 'disc', children: [{ text: 'New export options' }]
    },
    {
      type: 'blockquote',
      children: [{ type: 'p', children: [{ text: 'Design is not just what it looks like. Design is how it works.' }] }]
    },
    { type: 'hr', children: [{ text: '' }] },
    {
      type: 'table',
      colSizes: [233, 233, 234],
      children: [
        {
          type: 'tr',
          children: [{ type: 'th', children: [{ type: 'p', children: [{ text: 'Plan' }] }] }, { type: 'th', children: [{ type: 'p', children: [{ text: 'Price' }] }] }, { type: 'th', children: [{ type: 'p', children: [{ text: 'Seats' }] }] }]
        },
        {
          type: 'tr',
          children: [{ type: 'td', children: [{ type: 'p', children: [{ text: 'Starter' }] }] }, { type: 'td', children: [{ type: 'p', children: [{ text: '$9/mo' }] }] }, { type: 'td', children: [{ type: 'p', children: [{ text: '3' }] }] }]
        },
        {
          type: 'tr',
          children: [{ type: 'td', children: [{ type: 'p', children: [{ text: 'Pro' }] }] }, { type: 'td', children: [{ type: 'p', children: [{ text: '$29/mo' }] }] }, { type: 'td', children: [{ type: 'p', children: [{ text: '10' }] }] }]
        }
      ]
    },
    { type: 'p', children: [{ text: 'See you next week!' }] }
  ] as unknown as EmailDocument['blocks'],
  theme: cloneDefaultTheme(),
  settings: { preheader: 'Your weekly update is here', subject: 'Weekly Update' }
};

export function EmailTemplateEditorDemo() {
  return (
    <div className="flex h-[720px] w-full flex-col overflow-hidden rounded-lg border border-fd-border">
      {/* The editor owns its own Expand button (top bar) — no external wrapper needed. */}
      
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-email-template-editor
```

**Dependencies:**
- [platejs](https://www.npmjs.com/package/platejs)

## Overview

`EmailTemplateEditor` is a self-contained email authoring surface (no API client or auth required). The top bar has three modes plus two right-docked toggles:

- **Write** — the block canvas: a clean, Notion/beehiiv-style writing column with a rich toolbar (including dedicated **Variables** and **Blocks** insert buttons), a left `+` gutter affordance, a `/` slash menu, and merge-tag chips.
- **Preview** — a multi-provider simulator that renders the **email-safe HTML** across Gmail, Outlook (Word-engine approximation), Apple Mail and Mobile, with a light/dark toggle and a live size badge.
- **Code** — a read-only CodeMirror view of the serialized **email-safe HTML** with an in-panel **Copy HTML** button (mirrors the HTML Template Editor's Code tab).
- **Theme** (right-docked toggle, **not** a mode) — expands / collapses a right-side panel that styles every part of the email (colors, typography, spacing, borders, background, headings, links, lists, blockquote, tables, footer). Changes apply **live** to the canvas and stay open across Write / Preview / Code.
- **Expand** (right-docked toggle) — the editor's own fullscreen overlay; no host wiring needed (hidden in the `dialog` variant, which is already fullscreen).

The document model is a plain, serializable object — `EmailDocument = { blocks, theme, settings? }` — where `blocks` is the Plate value and `theme` is fully decoupled from the content, so persistence is a straight `JSON.stringify`.

## Usage

```tsx
import { useState } from 'react';
import {
  cloneDefaultTheme,
  EmailTemplateEditor,
  serializeEmail,
  type EmailDocument
} from '@docyrus/ui/components/email-template-editor';

const initial: EmailDocument = {
  blocks: [{ type: 'h1', children: [{ text: 'Welcome, ' }, { type: 'merge_tag', name: 'first_name', children: [{ text: '' }] }, { text: '!' }] }],
  theme: cloneDefaultTheme()
};

export function MyEmailEditor() {
  const [doc, setDoc] = useState<EmailDocument>(initial);

  return (
    <EmailTemplateEditor
      defaultValue={initial}
      onChange={setDoc}
      onExportHtml={(html) => console.log(serializeEmail(doc))}
    />
  );
}
```

### Mounting modes

`variant="page"` (default) fills its container (`h-full`). `variant="dialog"` opens the same editor inside a fullscreen Radix dialog, controlled via `open` / `onOpenChange`:

```tsx
const [open, setOpen] = useState(false);

```

### Exporting HTML

The **Code** mode's **Copy HTML** button (and the `onExportHtml` callback) return the full **email-safe HTML** — table-based layout, inlined CSS, a Cerberus/goodemailcode reset shell, `<meta color-scheme>`, a hidden preheader, and the themed footer. Call `serializeEmail(doc)` directly to get the same string headlessly.

```tsx
import { serializeEmail } from '@docyrus/ui/components/email-template-editor';

const html = serializeEmail(doc);            // literal {{merge_tags}}
const preview = serializeEmail(doc, { preview: true, mergeTags }); // sample values substituted
```

## API Reference

### `EmailTemplateEditorProps`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `variant` | `'page' \| 'dialog'` | `'page'` | Full-page (fills container) or fullscreen dialog shell |
| `open` | `boolean` | — | Dialog open state (dialog variant, controlled) |
| `onOpenChange` | `(open: boolean) => void` | — | Dialog open-state change handler |
| `defaultValue` | `EmailDocument` | empty doc | Uncontrolled initial document (blocks + theme) |
| `value` | `EmailDocument` | — | Controlled document (optional) |
| `onChange` | `(doc: EmailDocument) => void` | — | Fires on every content or theme change |
| `mergeTags` | `MergeTagDef[]` | `DEFAULT_MERGE_TAGS` | Merge-tag catalog for the `{{ }}` chips + insert menu |
| `onImageUpload` | `(file: File) => Promise<string>` | — | Image upload handler (UI wired; network app-owned) |
| `onExportHtml` | `(html: string) => void` | — | Fires with the email-safe HTML on **Copy HTML** (Code mode) |
| `readOnly` | `boolean` | `false` | Disables editing (canvas becomes read-only) |
| `title` | `string` | `'Email Template Editor'` | Dialog title (dialog variant, screen-reader label) |
| `className` | `string` | — | Class applied to the editor shell |

## Type Exports

| Type | Description |
|------|-------------|
| `EmailDocument` | `{ blocks: Value; theme: EmailTheme; settings?: { preheader?; subject? } }` — the full serializable document |
| `EmailTheme` | The complete theme object (mirrors beehiiv's Basic + Advanced Style panel) |
| `MergeTagDef` | `{ id: string; label: string; group?: string; sample?: string }` — a merge-tag definition |
| `Align` | `'left' \| 'center' \| 'right'` |
| `Spacing` | `number \| { t; r; b; l }` — all-sides or per-side spacing |
| `FontWeight` | `100 … 900` |
| `EmailTemplateEditorProps` | Props for the component |

### `EmailTheme` shape

```ts
interface EmailTheme {
  colors: { outsideBackground; postBackground; textOnBackground; primary; textOnPrimary; secondary; links };
  typography: { heading: { family; weight }; paragraph: { family; weight } };
  spacing: { margin: number; padding: number };
  borders: { cornerRadius: number; thickness: number };
  background: { color: { canvas; post; postBorder }; margin; padding; radius; borderThickness };
  emailHeader: { title; subtitle; image; byline; alignment; padding; code };
  body: { text: { family; weight; size; lineHeight; color; gap }; headings: Record<'h1'…'h6', {...}> };
  widgets: { links; buttons; breaks; lists; images; tables; blockquote };
  emailFooter: { backgroundColor; textColor; family; border; margin; padding; copyright; address; alignment };
}
```

## Exports

| Export | Description |
|--------|-------------|
| `EmailTemplateEditor` | The component |
| `serializeEmail(doc, options?)` | `EmailDocument` → full email-safe HTML string (`{ preview?, mergeTags? }`) |
| `serializeEmailContent(blocks, theme)` | Serialize just the body content (no shell) |
| `themeToCssVars(theme)` | `EmailTheme` → `--et-*` CSS custom-property map (canvas styling path) |
| `cloneDefaultTheme()` / `DEFAULT_EMAIL_THEME` | The default beehiiv-derived theme |
| `DEFAULT_MERGE_TAGS` | The default merge-tag catalog |
| `CLIENT_PROFILES` | The preview render profiles (Gmail / Outlook / Apple Mail / Mobile) |
| `EmailEditorProvider` / `useEmailEditorContext` | Low-level state provider + hook (advanced) |

## Blocks & inserts

Blocks are inserted from the toolbar **Blocks** button (a 3-column palette), the on-canvas left **`+`** gutter (combined blocks + variables), or the **`/`** slash menu. Merge-tag variables are inserted from the toolbar **Variables** button or by typing `{{ field | fallback }}` (auto-converts to a chip).

| Group | Blocks |
|-------|--------|
| Basics | Paragraph, Bulleted / Numbered / To-do list, Blockquote, Code block, Table, Content break (divider), Columns |
| Headings | Heading 1–6 |
| Dynamic | Merge tags (`{{ }}`) |
| Marks | Bold, Italic, Underline, Strikethrough, Inline code, Font color, Alignment, Link |

## Theming engine

One `EmailTheme`, two render targets kept in lockstep:

- **Live canvas** — `themeToCssVars(theme)` produces `--et-*` CSS custom properties applied to the writing surface, so slider/color edits restyle instantly with no re-serialization.
- **Email output** — `serializeEmail` folds the same theme values into **inline styles** on a table-based, client-hardened HTML document.

The **Theme** panel is split into **Basic** (Colors, Typography, Spacing, Borders) and **Advanced** (Background, Email Header, Body H1–H6, Widgets, Email Footer). Basic controls write through to the Advanced fields the renderer reads, so simplified edits still change the output.

## Multi-provider preview

The **Preview** mode renders the serialized email-safe HTML in a sandboxed `<iframe srcDoc>` per client, applying a per-client CSS reset/quirk layer and a width frame:

| Profile | Notes |
|---------|-------|
| Apple Mail | Most faithful; honors `prefers-color-scheme` |
| Gmail | Inline-CSS baseline (Gmail strips `<style>`/drops it over ~8 KB) |
| Outlook (Windows) | Word-engine **approximation** — no rounded corners / shadows / bg-image, serif fallback |
| Outlook.com | Chromium; `[data-ogsc]`/`[data-ogsb]` dark hooks |
| Mobile | 375px viewport; responsive media queries fire |

A light/dark toggle applies each profile's dark behavior, and a size badge warns past Gmail's ~102 KB clipping threshold. Every non-Apple-Mail tab is an **approximation** — for pixel-accurate QA use a render farm.

## Limitations

This is the first phase. The following are intentionally not shipped yet:

- **Custom blocks** — Button/CTA, Subscriber Break, Cash Tags, and provider-specific embeds (YouTube / Twitter / Instagram / …) are not authored in the canvas yet, so the **Buttons** / **Images** / **Email Header** theme sections have no on-canvas target.
- **Persistence** — no backend/theme-preset saving; the document lives in memory (wire `value` / `onChange` for your own store).
- **Preview fidelity** — the in-browser simulator approximates clients (especially Outlook's Word engine); it is not a substitute for a render farm.

---

# Emoji Picker
URL: /docs/web/components/emoji-picker

A searchable, category-tabbed emoji picker with skin-tone selection and recently-used memory, built on the emoji-mart dataset.

**Demo:**

```tsx
'use client';
// @custom-demo

import { useRef, useState } from 'react';

import { Smile } from 'lucide-react';

import { EmojiPicker, type SelectedEmoji } from '@docyrus/ui/components/emoji-picker';
import { Button } from '@docyrus/ui/primitives/ui/button';

export function EmojiPickerDemo() {
  const [text, setText] = useState('Ship it ');
  const ref = useRef
      
    </div>
  );
}
```

The `EmojiPicker` wraps a trigger of your choice in a popover. It is fully self-contained — search, category tabs, a skin-tone selector, and a recently-used strip (persisted to `localStorage`) — and returns the chosen emoji as native unicode so it drops straight into any text input, `contentEditable`, or message body. It powers the comment composer, email composer, and instant-message composer.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-emoji-picker
```

**Dependencies:**
- [lucide-react](https://www.npmjs.com/package/lucide-react)
- [@emoji-mart/data](https://www.npmjs.com/package/@emoji-mart/data)

## Usage

```tsx
import { EmojiPicker, type SelectedEmoji } from "@docyrus/ui/components/emoji-picker";
import { Button } from "@docyrus/ui/primitives/ui/button";
import { Smile } from "lucide-react";

function Composer() {
  const insert = (emoji: SelectedEmoji) => {
    console.log(emoji.native);   // "😄"
    console.log(emoji.shortcode); // ":smile:"
  };

  return (
    
    
  );
}
```

The single child is the trigger (rendered via Radix `asChild`, so pass one focusable element). `onSelect` fires with the emoji already resolved for the active skin tone.

### Bare panel

Use `EmojiPickerPanel` to embed the picker without the popover — e.g. inside your own dropdown or a fixed side panel:

```tsx
import { EmojiPickerPanel } from "@docyrus/ui/components/emoji-picker";

<EmojiPickerPanel onSelect={(emoji) => insert(emoji.native)} perLine={9} />
```

## Features

| Feature | Notes |
|---------|-------|
| Search | Matches emoji id, name, keywords, emoticons, and aliases (AND across terms). |
| Category tabs | Only the active category renders, so the popover stays light even across ~1,870 emoji. |
| Skin tone | Six-tone selector; the choice persists to `localStorage` (`docyrus:emoji-skin-tone`). |
| Recently used | Most-recent-first strip, persisted to `localStorage` (`docyrus:emoji-recents`). |
| Native output | `onSelect` returns unicode (`native`) plus the `:shortcode:` — no sprite sheet needed. |

## API Reference

### EmojiPicker

| Prop | Type | Default |
|------|------|---------|
| `children` | `ReactNode` | — (the trigger, `asChild`) |
| `onSelect` | `(emoji: SelectedEmoji) => void` | — |
| `defaultSkinTone` | `number` | `0` |
| `perLine` | `number` | `8` |
| `closeOnSelect` | `boolean` | `true` |
| `align` | `'start' \| 'center' \| 'end'` | `'start'` |
| `side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'top'` |
| `open` | `boolean` | — (controlled) |
| `onOpenChange` | `(open: boolean) => void` | — |
| `contentClassName` | `string` | — |

### EmojiPickerPanel

| Prop | Type | Default |
|------|------|---------|
| `onSelect` | `(emoji: SelectedEmoji) => void` | — |
| `defaultSkinTone` | `number` | `0` |
| `perLine` | `number` | `8` |
| `className` | `string` | — |

## Type Exports

| Type | Description |
|------|-------------|
| `EmojiPickerProps` | Props for `EmojiPicker` |
| `EmojiPickerPanelProps` | Props for `EmojiPickerPanel` |
| `SelectedEmoji` | `{ id, native, shortcode }` — the value passed to `onSelect` |

### SelectedEmoji

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | emoji-mart id, e.g. `"smile"` |
| `native` | `string` | rendered unicode character (respects skin tone) |
| `shortcode` | `string` | shortcode form, e.g. `":smile:"` |

## Helpers

The component also re-exports a few pure helpers from the emoji dataset:

| Export | Signature | Description |
|--------|-----------|-------------|
| `searchEmojis` | `(query: string, limit?: number) => string[]` | Emoji ids matching a query |
| `resolveNative` | `(id: string, skinTone: number) => string` | Unicode char for an id + tone |
| `getShortcode` | `(id: string) => string` | `":<id>:"` |

---

# Enum Option Editor
URL: /docs/web/components/enum-option-editor

Enum Option Editor component.

**Demo:**

```tsx
'use client';

import { useState } from 'react';

import {
  EnumOptionEditor,
  type EnumEditorOption,
  type EnumOptionInput
} from '@docyrus/ui/components/enum-option-editor';

const INITIAL_OPTIONS: Array<EnumEditorOption> = [
  {
    id: '1', name: 'Open', color: 'emerald-500', origin: 'custom'
  },
  {
    id: '2', name: 'In Progress', color: 'amber-500', origin: 'custom'
  },
  {
    id: '3', name: 'On Hold', color: 'slate-400', origin: 'custom'
  },
  {
    id: '4', name: 'Closed', color: 'red-500', origin: 'custom'
  }
];

/**
 * Backend-agnostic demo — the editor is live/optimistic, so the callbacks just
 * mutate local state. Wire `DocyrusEnumOptionEditor` for real Docyrus CRUD.
 */
export function EnumOptionEditorDemo() {
  const [options, setOptions] = useState<Array<EnumEditorOption>>(INITIAL_OPTIONS);
  const [nextId, setNextId] = useState(INITIAL_OPTIONS.length + 1);

  return (
    <div className="w-full max-w-md">
      <EnumOptionEditor
        options={options}
        onCreateOption={async (input: EnumOptionInput) => {
          const created: EnumEditorOption = { id: `opt-${nextId}`, origin: 'custom', ...input };

          setNextId(id => id + 1);
          setOptions(prev => [...prev, created]);

          return created;
        }}
        onUpdateOption={async (id, patch) => {
          setOptions(prev => prev.map(option => (option.id === id ? { ...option, ...patch } : option)));
        }}
        onDeleteOption={async (id) => {
          setOptions(prev => prev.filter(option => option.id !== id));
        }}
        onReorder={async (ids) => {
          setOptions((prev) => {
            const byId = new Map(prev.map(option => [option.id, option]));

            return ids
              .map(id => byId.get(id))
              .filter((option): option is EnumEditorOption => Boolean(option));
          });
        }} />
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-enum-option-editor
```

**Dependencies:**
- [@tanstack/react-query](https://www.npmjs.com/package/@tanstack/react-query)
- [lucide-react](https://www.npmjs.com/package/lucide-react)

## Usage

```tsx
import {
  EnumOptionEditor,
  EnumOptionEditorDialog
} from "@docyrus/ui/components/enum-option-editor";
import type {
  EnumEditorOption,
  EnumOptionOrigin,
  EnumOptionInput,
  EnumOptionEditorProps,
  EnumOptionEditorDialogProps,
  DocyrusEnumOptionEditorProps,
  UseDocyrusEnumEditorPermissionOptions
} from "@docyrus/ui/components/enum-option-editor";

<EnumOptionEditor
  value={...}
  disabled
  onChange={() => {}}
/>
```

## API Reference

| Prop | Type | Default |
|------|------|---------|
| `value` | `string \| undefined` | — |
| `disabled` | `boolean` | — |
| `onChange` | `(value: string \| undefined) => void` | — |
| `className` | `string` | — |

## Components

| Component | Description |
|-----------|-------------|
| `EnumOptionEditor` | Public export |
| `EnumOptionEditorDialog` | Public export |
| `ADMIN` | Internal — `docyrus-enum-option-editor.tsx` |
| `ARCHITECT` | Internal — `docyrus-enum-option-editor.tsx` |
| `DocyrusEnumOptionEditor` | Internal — `docyrus-enum-option-editor.tsx` |

## Type Exports

| Type | Description |
|------|-------------|
| `EnumEditorOption` | — |
| `EnumOptionOrigin` | — |
| `EnumOptionInput` | — |
| `EnumOptionEditorProps` | — |
| `EnumOptionEditorDialogProps` | — |
| `DocyrusEnumOptionEditorProps` | — |
| `UseDocyrusEnumEditorPermissionOptions` | — |

## Type Reference

### EnumEditorOption

| Field | Type | Description |
|-------|------|-------------|
| `origin` | `EnumOptionOrigin` | — |
| `isCustomized` | `boolean` | — |

### EnumOptionOrigin

`"custom"` | `"inherited"`

### EnumOptionInput

| Field | Type | Description |
|-------|------|-------------|
| `name` | `string` | — |
| `slug` | `string` | — |
| `color` | `string` | — |
| `icon` | `string` | — |
| `description` | `string` | — |
| `active` | `boolean` | — |
| `parent` | `string` | — |

### EnumOptionEditorProps

| Field | Type | Description |
|-------|------|-------------|
| `options` | `EnumEditorOption[]` | — |
| `onCreateOption` | `(input: EnumOptionInput) => Promise<EnumEditorOption> \| EnumEditorOption` | — |
| `onUpdateOption` | `(id: string, patch: Partial<EnumOptionInput>) => Promise<void> \| void` | — |
| `onDeleteOption` | `(id: string) => Promise<void> \| void` | — |
| `onRevertOption` | `(id: string) => Promise<void> \| void` | — |
| `onReorder` | `(orderedIds: string[]) => Promise<void> \| void` | — |
| `readOnly` | `boolean` | — |
| `allowCreate` | `boolean` | — |
| `allowDelete` | `boolean` | — |
| `allowReorder` | `boolean` | — |
| `noticeText` | `string` | — |
| `emptyText` | `string` | — |
| `className` | `string` | — |

### EnumOptionEditorDialogProps

| Field | Type | Description |
|-------|------|-------------|
| `trigger` | `ReactNode` | — |
| `open` | `boolean` | — |
| `onOpenChange` | `(open: boolean) => void` | — |
| `title` | `string` | — |
| `description` | `string` | — |
| `disabled` | `boolean` | — |

### DocyrusEnumOptionEditorProps

| Field | Type | Description |
|-------|------|-------------|
| `client` | `RestApiClient` | — |
| `appId` | `string` | — |
| `dataSourceId` | `string` | — |
| `fieldId` | `string` | — |
| `fieldName` | `string` | — |
| `trigger` | `ReactNode` | — |
| `open` | `boolean` | — |
| `onOpenChange` | `(open: boolean) => void` | — |
| `onChanged` | `() => void` | — |
| `disabled` | `boolean` | — |
| `title` | `string` | — |

### UseDocyrusEnumEditorPermissionOptions

| Field | Type | Description |
|-------|------|-------------|
| `enabled` | `boolean` | — |
| `adminRoleIds` | `Array<string>` | — |
| `meEndpoint` | `string` | — |

---

# File Attachment Panel
URL: /docs/web/components/file-attachment-panel

File Attachment Panel component.

**Demo:**

```tsx
'use client';
// @custom-demo

import { useState } from 'react';

import { FileAttachmentPanel } from '@docyrus/ui/components/file-attachment-panel';
import { Button } from '@docyrus/ui/primitives/ui/button';
import { cn } from '@docyrus/ui/primitives/lib/utils';

import { PropControls } from '@/components/prop-controls';
import { useDemoData } from '@/data/file-attachment-panel-data';

export function FileAttachmentPanelDemo() {
  const { props, controls, actions } = useDemoData();
  const [open, setOpen] = useState(false);

  return (
    <div className="w-full">
      <div className="mb-3 flex justify-end">
        <button
          type="button"
          className="inline-flex items-center gap-1.5 rounded-md border border-border bg-background px-3 py-1.5 text-sm font-medium transition-colors hover:bg-accent"
          onClick={() => setOpen(prev => !prev)}>
          <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M12.22 2h-.44a2 2 0 0 0-2 2v.18a2 2 0 0 1-1 1.73l-.43.25a2 2 0 0 1-2 0l-.15-.08a2 2 0 0 0-2.73.73l-.22.38a2 2 0 0 0 .73 2.73l.15.1a2 2 0 0 1 1 1.72v.51a2 2 0 0 1-1 1.74l-.15.09a2 2 0 0 0-.73 2.73l.22.38a2 2 0 0 0 2.73.73l.15-.08a2 2 0 0 1 2 0l.43.25a2 2 0 0 1 1 1.73V20a2 2 0 0 0 2 2h.44a2 2 0 0 0 2-2v-.18a2 2 0 0 1 1-1.73l.43-.25a2 2 0 0 1 2 0l.15.08a2 2 0 0 0 2.73-.73l.22-.39a2 2 0 0 0-.73-2.73l-.15-.08a2 2 0 0 1-1-1.74v-.5a2 2 0 0 1 1-1.74l.15-.09a2 2 0 0 0 .73-2.73l-.22-.38a2 2 0 0 0-2.73-.73l-.15.08a2 2 0 0 1-2 0l-.43-.25a2 2 0 0 1-1-1.73V4a2 2 0 0 0-2-2z" /><circle cx="12" cy="12" r="3" /></svg>
          Configure
          <svg xmlns="http://www.w3.org/2000/svg" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" className={cn('transition-transform duration-200', open && 'rotate-180')}><path d="m6 9 6 6 6-6" /></svg>
        </button>
      </div>
      <div
        className={cn(
          'grid transition-[grid-template-rows] duration-300 ease-in-out',
          open ? 'grid-rows-[1fr]' : 'grid-rows-[0fr]'
        )}>
        <div className="overflow-hidden">
          <div className="mb-4 rounded-lg border border-border bg-muted/30 p-4 grid gap-6">
            
            <div className="mt-3 flex flex-wrap gap-2">
              
              
              
              
            </div>
          </div>
        </div>
      </div>
      
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-file-attachment-panel
```

## Usage

```tsx
import { FileAttachmentPanel } from "@docyrus/ui/components/file-attachment-panel";
import type { FileAttachmentPanelProps } from "@docyrus/ui/components/file-attachment-panel";

const files: FileAttachmentPanelProps['files'] = [
  {
    id: "f-1",
    file_name: "design-review.png",
    file_type: "image/png",
    file_size: 120000,
    signed_url: "https://images.unsplash.com/photo-1581291518857-4e27b48ff24e?w=640&q=80",
    source: "local",
    file_data: null,
    created_on: new Date().toISOString(),
    record_id: "rec-1"
  }
];

function Demo() {
  return (
    <FileAttachmentPanel
      files={files}
      onUploadFile={(file) => Promise.resolve({
        ...files[0],
        id: crypto.randomUUID(),
        file_name: file.name,
        file_type: file.type,
        file_size: file.size,
        signed_url: URL.createObjectURL(file)
      })}
      onDeleteFile={(id) => console.log("delete", id)}
    />
  );
}
```

## API Reference

| Prop | Type | Default |
|------|------|---------|
| `files` | `DocyrusFile[]` | — |
| `title` | `string` | `"Attachments"` |
| `editable` | `boolean` | `true` |
| `isLoading` | `boolean` | `false` |
| `maxFileSize` | `number` | `50 * 1024 * 1024` |
| `accept` | `string` | — |
| `maxFiles` | `number` | — |
| `onUploadFile` | `(file: File) => Promise<DocyrusFile>` | — |
| `onDeleteFile` | `(fileId: string) => void \| Promise<void>` | — |
| `onInsertExternalFiles` | `(files: ExternalFilePayload[]) => void \| Promise<void>` | — |
| `onFileOpen` | `(file: DocyrusFile) => void` | — |
| `isDeletePending` | `boolean` | `false` |
| `className` | `string` | — |
| `oneDriveConfig` | `OneDrivePickerConfig` | — |
| `googleDriveConfig` | `GoogleDrivePickerConfig` | — |

## Components

| Component | Description |
|-----------|-------------|
| `FileAttachmentPanel` | Public export |
| `FileEmptyState` | Internal — `file-empty-state.tsx` |
| `FileGrid` | Internal — `file-grid.tsx` |
| `FileItem` | Internal — `file-item.tsx` |
| `FileList` | Internal — `file-list.tsx` |
| `FileSourceMenu` | Internal — `file-source-menu.tsx` |
| `FileUploadProgress` | Internal — `file-upload-progress.tsx` |
| `FileUploadZone` | Internal — `file-upload-zone.tsx` |
| `DocyrusIcon` | Internal — `docyrus-icon.tsx` |

## Type Exports

| Type | Description |
|------|-------------|
| `FileAttachmentPanelProps` | — |
| `ViewMode` | — |
| `DocyrusFile` | — |
| `ExternalFilePayload` | — |
| `OneDrivePickerConfig` | Config for OneDrive integration |
| `GoogleDrivePickerConfig` | Config for Google Drive integration |

## Type Reference

### ViewMode

`"list"` | `"grid"`

### DocyrusFile

| Field | Type |
|-------|------|
| `id` | `string` |
| `file_name` | `string` |
| `file_type` | `string` |
| `file_size` | `number` |
| `signed_url` | `string \| null` |
| `source` | `"local" \| "microsoft_onedrive" \| "google_drive"` |
| `file_data` | `Record<string, unknown> \| null` |
| `created_on` | `string` |
| `record_id` | `string \| null` |

### ExternalFilePayload

| Field | Type |
|-------|------|
| `source` | `"microsoft_onedrive" \| "google_drive"` |
| `file_name` | `string` |
| `file_type` | `string` |
| `signed_url` | `string` |
| `file_data` | `Record<string, unknown> \| undefined` |
| `expire_in` | `number \| undefined` |

### OneDrivePickerConfig

| Field | Type | Description |
|-------|------|-------------|
| `clientId` | `string` | Microsoft OAuth2 Client ID |
| `redirectUri` | `string \| undefined` | OAuth2 redirect URI (defaults to `window.location.origin`) |

### GoogleDrivePickerConfig

| Field | Type | Description |
|-------|------|-------------|
| `clientId` | `string` | Google OAuth2 Client ID |
| `apiKey` | `string` | Google API key for the Picker API |
| `appId` | `string \| undefined` | Google Cloud project / app ID |

---

# Form Builder
URL: /docs/web/components/form-builder

A drag-and-drop form designer with a field palette, canvas, properties panel, live preview and code export for TanStack Form, React Hook Form, Zod and raw useState.

**Demo:**

```tsx
'use client';

import { FormBuilder } from '@docyrus/ui/components/form-builder';

export function FormBuilderDemo() {
  return (
    <div className="h-[720px] w-full overflow-hidden rounded-lg border bg-background">
      
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-form-builder
```

**Dependencies:**
- [@dnd-kit/core](https://www.npmjs.com/package/@dnd-kit/core)
- [@dnd-kit/sortable](https://www.npmjs.com/package/@dnd-kit/sortable)
- [lucide-react](https://www.npmjs.com/package/lucide-react)
- [nanoid](https://www.npmjs.com/package/nanoid)

## Usage

```tsx
import { FormBuilder } from "@docyrus/ui/components/form-builder";

export function FormBuilderPage() {
  return (
    <div className="h-[720px]">
      
    </div>
  );
}
```

The component fills its parent (`flex h-full flex-col`), so wrap it in a sized container or pass a `className` with explicit dimensions.

### Reading builder state

`useBuilderContext` is exposed for consumers that want to render their own toolbar, persist drafts, or react to selection. It must be used inside a `<BuilderProvider>`, which `<FormBuilder>` already renders internally — to read state from outside the default UI, render `<BuilderProvider>` yourself and place `<FormBuilder>` (or its sub-components) underneath.

```tsx
import {
  BuilderProvider,
  useBuilderContext
} from "@docyrus/ui/components/form-builder";

function FieldCount() {
  const { state } = useBuilderContext();

  return <span>{state.fields.length} fields</span>;
}
```

## Built-in field types

The palette ships with **9 categories** covering 30+ field types from the Docyrus form-fields library. Each type maps to a `DynamicFormField` renderer, so what users build in the canvas is exactly what they get at runtime.

| Category | Field types |
|----------|-------------|
| Text & Input | `field-text`, `field-textarea`, `field-email`, `field-url`, `field-phone`, `field-color` |
| Numbers | `field-number`, `field-money`, `field-percent`, `field-rating`, `field-duration`, `field-currency` |
| Selection | `field-select`, `field-multiSelect`, `field-tagSelect`, `field-radioGroup`, `field-enum`, `field-status`, `field-approvalStatus` |
| Date & Time | `field-date`, `field-dateTime`, `field-time`, `field-dateRange` |
| Toggle | `field-switch`, `field-checkbox` |
| Visual & Media | `field-icon`, `field-avatar`, `field-file`, `field-image` |
| Relation & User | `field-userSelect`, `field-userMultiSelect`, `field-relation`, `field-locationSelect` |
| Rich Content | `field-htmlEditor`, `field-codeEditor`, `field-docEditor`, `field-emailEditor` |
| Data Structure | `field-taskList`, `field-schemaRepeater`, `field-queryBuilder` |

## Code export

Switch the toolbar's view mode to **Code** to render generated TSX for the current form. Four templates are available:

| Template | Output |
|----------|--------|
| `tanstack` | `useForm` from `@tanstack/react-form` driving `DynamicFormField` |
| `rhf` | `useForm` from `react-hook-form` with native inputs |
| `zod` | `react-hook-form` + `zodResolver` and a generated `z.object` schema |
| `raw` | `useState` per field, plain `<input>` markup |

The generated code uses user-project import paths (`@/components/docyrus/form-fields`, `@/components/ui/button`) so it drops straight into a project that has installed `@docyrus/ui-form-fields` and the matching shadcn primitives. Adjust the prefix if your project uses a different alias.

## API Reference

### `<FormBuilder>`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `className` | `string` | `flex h-full flex-col` | Override the root container classes. Useful for setting an explicit height or max width. |

### `useBuilderContext()`

Returns the live builder state and dispatchers. Throws if called outside a `<BuilderProvider>`.

| Property | Type | Description |
|----------|------|-------------|
| `state` | `BuilderState` | The full reducer state (fields, selection, view mode, grid columns, form title). |
| `dispatch` | `Dispatch<BuilderAction>` | Low-level dispatcher for every reducer action (including undo/redo, reorder, clear). |
| `selectedField` | `BuilderField \| null` | The currently focused field, or `null` when nothing is selected. |
| `addField` | `(componentType: string, index?: number) => void` | Append (or insert at `index`) a new field of the given palette type. |
| `removeField` | `(id: string) => void` | Remove a field by id. |
| `duplicateField` | `(id: string) => void` | Clone a field by id and insert it directly after the source. |
| `selectField` | `(id: string \| null) => void` | Update the selection. |
| `canUndo` | `boolean` | `true` when there is at least one entry in the undo stack. |
| `canRedo` | `boolean` | `true` when there is at least one entry in the redo stack. |

### `<BuilderProvider>`

Wraps children in the builder reducer and history. Accepts only `children`; rendered automatically by `<FormBuilder>`.

## Components

| Component | Description |
|-----------|-------------|
| `FormBuilder` | The full builder experience (toolbar, palette, canvas, properties panel, preview, code export). The properties panel has four tabs — **General**, **Options** (enum fields only), **Validation**, and **Actions**. The **Validation** tab supports required toggle, min/max/pattern constraints, and **Custom Validations** — JSONata-based rules evaluated on submit. Each custom validation rule has an `expression` (returns `true` to pass) and a `message` shown on failure. Supported field types: `text`, `textarea`, `email`, `url`, `phone`, `number`, `money`, `percent`, `duration`, `date`, `dateTime`, `rating`. |
| `BuilderProvider` | Reducer + 50-step undo/redo history provider. |
| `useBuilderContext` | Hook for reading builder state and triggering actions. |
| `generateCode` | Standalone helper that turns a `BuilderState` into a TSX string for any of the four templates. |

## Type Exports

| Type | Description |
|------|-------------|
| `FormBuilderProps` | Props for `<FormBuilder>` (`className?`). |
| `BuilderField` | A single field on the canvas: id, component type, `IField` config, optional enum options and `colSpan`. |
| `BuilderState` | Top-level reducer state — `fields`, `selectedFieldId`, `viewMode`, `formTitle`, `formDescription`, `gridColumns`. |
| `BuilderAction` | Union of every dispatchable action (add/remove/reorder/duplicate/update/select/undo/redo/clear/set-meta/set-view-mode). |
| `PaletteCategory` | A palette section (id, label, icon, items). |
| `PaletteItem` | A single palette entry (component type, label, icon, default field type, search tags). |
| `PropertySchema` | Metadata for one editable property in the right-hand properties panel. |
| `CodeTemplate` | `'tanstack' \| 'rhf' \| 'zod' \| 'raw'` — accepted by `generateCode`. |
| `FieldAction` | Trigger + ordered blocks definition stored on `BuilderField.field.fieldActions`. Authored through the **Actions** tab in the properties panel. |
| `FieldActionBlock` | Named block with if / else-if / else branches and unconditional steps. |
| `FieldActionStep` | Discriminated union of imperative commands: value writes, visibility, required, disabled, readOnly. |

---

# Form Fields
URL: /docs/web/components/form-fields

Dynamic form field system powered by TanStack Form. 49 field types with automatic dispatch via DynamicFormField.

**Demo:**

```tsx
'use client';
// @custom-demo

import { lazy } from 'react';

import { ApprovalStatusFormField } from '@docyrus/ui/components/form-fields/approval-status-form-field';
import { AvatarField } from '@docyrus/ui/components/form-fields/avatar-field';
import { CheckboxFormField } from '@docyrus/ui/components/form-fields/checkbox-form-field';
import { CheckboxGroupFormField } from '@docyrus/ui/components/form-fields/checkbox-group-form-field';
import { CodeEditorFormField } from '@docyrus/ui/components/form-fields/code-editor-form-field';
import { ColorFormField } from '@docyrus/ui/components/form-fields/color-form-field';
import { CurrencyCodeFormField } from '@docyrus/ui/components/form-fields/currency-code-form-field';
import { DateFormField } from '@docyrus/ui/components/form-fields/date-form-field';
import { DateRangeFormField } from '@docyrus/ui/components/form-fields/date-range-form-field';
import { DateTimeFormField } from '@docyrus/ui/components/form-fields/datetime-form-field';
import { DurationFormField } from '@docyrus/ui/components/form-fields/duration-form-field';
import { EmailFormField } from '@docyrus/ui/components/form-fields/email-form-field';
import { EnumFormField } from '@docyrus/ui/components/form-fields/enum-form-field';
import { FieldMappingFormField } from '@docyrus/ui/components/form-fields/field-mapping-form-field';
import { FileFormField } from '@docyrus/ui/components/form-fields/file-form-field';
import { AdaptiveCardFormField } from '@docyrus/ui/components/form-fields/adaptive-card-form-field';
import { HandlebarsFormField } from '@docyrus/ui/components/form-fields/handlebars-form-field';
import { IconFormField } from '@docyrus/ui/components/form-fields/icon-form-field';
import { ImageFormField } from '@docyrus/ui/components/form-fields/image-form-field';
import { JsonSchemaFormField } from '@docyrus/ui/components/form-fields/json-schema-form-field';
import { JsonataFormField } from '@docyrus/ui/components/form-fields/jsonata-form-field';
import { LocationSelectFormField } from '@docyrus/ui/components/form-fields/location-select-form-field';
import { MarkdownEditorFormField } from '@docyrus/ui/components/form-fields/markdown-editor-form-field';
import { MoneyFormField } from '@docyrus/ui/components/form-fields/money-form-field';
import { MultiSelectFormField } from '@docyrus/ui/components/form-fields/multi-select-form-field';
import { NumberFormField } from '@docyrus/ui/components/form-fields/number-form-field';
import { PasswordFormField } from '@docyrus/ui/components/form-fields/password-form-field';
import { PercentFormField } from '@docyrus/ui/components/form-fields/percent-form-field';
import { PhoneFormField } from '@docyrus/ui/components/form-fields/phone-form-field';
import { RadioGroupFormField } from '@docyrus/ui/components/form-fields/radio-group-form-field';
import { RatingFormField } from '@docyrus/ui/components/form-fields/rating-form-field';
import { RelationFormField } from '@docyrus/ui/components/form-fields/relation-form-field';
import { SchemaRepeaterFormField } from '@docyrus/ui/components/form-fields/schema-repeater-form-field';
import { SelectFormField } from '@docyrus/ui/components/form-fields/select-form-field';
import { StatusFormField } from '@docyrus/ui/components/form-fields/status-form-field';
import { SwitchFormField } from '@docyrus/ui/components/form-fields/switch-form-field';
import { TagSelectFormField } from '@docyrus/ui/components/form-fields/tag-select-form-field';
import { TreeSelectFormField } from '@docyrus/ui/components/form-fields/tree-select-form-field';
import { TaskListFormField } from '@docyrus/ui/components/form-fields/task-list-form-field';
import { TextFormField } from '@docyrus/ui/components/form-fields/text-form-field';
import { TextareaFormField } from '@docyrus/ui/components/form-fields/textarea-form-field';
import { TimeFormField } from '@docyrus/ui/components/form-fields/time-form-field';
import { UrlFormField } from '@docyrus/ui/components/form-fields/url-form-field';
import { UserMultiSelectFormField } from '@docyrus/ui/components/form-fields/user-multi-select-form-field';
import { UserSelectFormField } from '@docyrus/ui/components/form-fields/user-select-form-field';

const DocEditorFormField = lazy(() => import('@docyrus/ui/components/form-fields/doc-editor-form-field').then(m => ({ default: m.DocEditorFormField })));

const HtmlEditorFormField = lazy(() => import('@docyrus/ui/components/form-fields/html-editor-form-field').then(m => ({ default: m.HtmlEditorFormField })));

import { QueryBuilderFormField } from '@docyrus/ui/components/form-fields/query-builder-form-field';

import {
  APPROVAL_OPTIONS,
  AVAILABLE_FIELDS_SCHEMA,
  CATEGORY_OPTIONS,
  DEMO_FIELDS,
  DEPARTMENT_OPTIONS,
  NESTED_LOCATION_OPTIONS,
  PRIORITY_OPTIONS,
  QUERY_BUILDER_FIELD_OPTIONS,
  RELATION_OPTIONS,
  SKILL_OPTIONS,
  STATUS_OPTIONS,
  TAG_OPTIONS,
  USER_OPTIONS,
  mockForm
} from '@/data/form-fields-data';

function SectionHeader({ children }: { children: string }) {
  return (
    <h3 className="border-b pb-1.5 text-sm font-semibold tracking-wide text-muted-foreground uppercase">
      {children}
    </h3>
  );
}

export function FormFieldsDemo() {
  return (
    <div className="w-full space-y-8">
      {/* Text & Content */}
      <section className="space-y-4">
        
        <div className="grid grid-cols-1 gap-4 sm:grid-cols-2">
          
          
          
          
          
          
          
        </div>
        
      </section>

      {/* Numbers */}
      <section className="space-y-4">
        
        <div className="grid grid-cols-1 gap-4 sm:grid-cols-2">
          
          
          
          
          
          
        </div>
      </section>

      {/* Selection */}
      <section className="space-y-4">
        
        <div className="grid grid-cols-1 gap-4 sm:grid-cols-2">
          
          
          
          
          
          
          
          
          
        </div>
        
        
      </section>

      {/* Date & Time */}
      <section className="space-y-4">
        
        <div className="grid grid-cols-1 gap-4 sm:grid-cols-2">
          
          
          
          
        </div>
      </section>

      {/* Toggle */}
      <section className="space-y-4">
        
        <div className="grid grid-cols-1 gap-4 sm:grid-cols-2">
          
          
        </div>
      </section>

      {/* Relation & Users */}
      <section className="space-y-4">
        
        <div className="grid grid-cols-1 gap-4 sm:grid-cols-2">
          
          
          
          
        </div>
      </section>

      {/* File & Media */}
      <section className="space-y-4">
        
        <div className="grid grid-cols-1 gap-4 sm:grid-cols-2">
          
          
          
        </div>
        
      </section>

      {/* Rich Content */}
      <section className="space-y-4">
        
        
        
        
        
        {/* EmailEditorFormField temporarily disabled — react-email-editor ESM issue */}
        
      </section>

      {/* Data Structure */}
      <section className="space-y-4">
        
        
        
        
        
        
        
      </section>

      {/* Dynamic Values */}
      <section className="space-y-4">
        
        <p className="text-sm text-muted-foreground">
          Wrap any form field with <code className="rounded bg-muted px-1">FieldMappingFormField</code> to offer four value sources: fixed, field mapping (recursive tree picker over a shared <code className="rounded bg-muted px-1">schema</code>), template (Handlebars), and formula (JSONata). The same <code className="rounded bg-muted px-1">schema</code> drives autocomplete inside both editors — try <code className="rounded bg-muted px-1">customer.address.city</code> or <code className="rounded bg-muted px-1">orders[0].product</code>.
        </p>
        
      </section>
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-form-fields
```

**Dependencies:**
- [@tanstack/react-form](https://www.npmjs.com/package/@tanstack/react-form)
- [lucide-react](https://www.npmjs.com/package/lucide-react)
- [date-fns](https://www.npmjs.com/package/date-fns)
- [react-day-picker](https://www.npmjs.com/package/react-day-picker)
- [platejs](https://www.npmjs.com/package/platejs)
- [react-email-editor](https://www.npmjs.com/package/react-email-editor)
- [react-querybuilder](https://www.npmjs.com/package/react-querybuilder)
- [@uiw/react-codemirror](https://www.npmjs.com/package/@uiw/react-codemirror)
- [@uiw/codemirror-extensions-langs](https://www.npmjs.com/package/@uiw/codemirror-extensions-langs)

## Usage

```tsx
import { useForm } from '@tanstack/react-form';
import { DynamicFormField } from '@docyrus/ui/components/form-fields';
import type { IField, EnumOption } from '@docyrus/ui/components/form-fields';

const fields: IField[] = [
  { id: '1', name: 'Full Name', slug: 'full_name', type: 'field-text' },
  { id: '2', name: 'Priority', slug: 'priority', type: 'field-select' },
  { id: '3', name: 'Active', slug: 'is_active', type: 'field-switch' },
];

const enumOptions: EnumOption[] = [
  { id: 'low', name: 'Low', color: '#22c55e' },
  { id: 'medium', name: 'Medium', color: '#f59e0b' },
  { id: 'high', name: 'High', color: '#ef4444' },
];

function MyForm() {
  const form = useForm({
    defaultValues: { full_name: '', priority: '', is_active: false },
    onSubmit: ({ value }) => console.log(value),
  });

  return (
    <form onSubmit={(e) => { e.preventDefault(); form.handleSubmit(); }}>
      {fields.map((field) => (
        
      ))}
    </form>
  );
}
```

### Individual Field Import

You can import individual field components to reduce bundle size:

```tsx
import { TextFormField } from '@docyrus/ui/components/form-fields/text-form-field';
import { SelectFormField } from '@docyrus/ui/components/form-fields/select-form-field';
import { SwitchFormField } from '@docyrus/ui/components/form-fields/switch-form-field';
```

## Field Types

### Text & Content

| Type | Component | Description |
|------|-----------|-------------|
| `field-text` | `TextFormField` | Single-line text input |
| `field-textarea` | `TextareaFormField` | Multi-line text area |
| `field-email` | `EmailFormField` | Email input with validation |
| `field-url` | `UrlFormField` | URL input with `https://` placeholder |
| `field-phone` | `PhoneFormField` | Phone number with mask input |
| `field-color` | `ColorFormField` | Color picker with hex input |
| `field-icon` | `IconFormField` | Icon picker (Docyrus icon set) |

### Numbers

| Type | Component | Description |
|------|-----------|-------------|
| `field-number` | `NumberFormField` | Numeric input |
| `field-money` | `MoneyFormField` | Money input with currency symbol |
| `field-percent` | `PercentFormField` | Percentage input (0-100) |
| `field-duration` | `DurationFormField` | Duration picker grid via [Duration Select](/docs/web/components/duration-select) |
| `field-rating` | `RatingFormField` | Star rating (1-5) |
| `field-currency` | `CurrencyCodeFormField` | Currency code selector |

### Selection

| Type | Component | Description |
|------|-----------|-------------|
| `field-select` | `SelectFormField` | Single select with color/icon indicators |
| `field-multiSelect` | `MultiSelectFormField` | Multi-value select |
| `field-tagSelect` | `TagSelectFormField` | Tag-based multi-select |
| `field-radioGroup` | `RadioGroupFormField` | Radio button group |
| — | `CheckboxGroupFormField` | Inline multi-select with radio-group visuals — array value, `default` and `card` variants, `columnCount` 1–4 |
| `field-enum` | `EnumFormField` | Enum dropdown (slug-based values) |
| `field-status` | `StatusFormField` | Status select with description + follow-up |
| `field-approvalStatus` | `ApprovalStatusFormField` | Approval workflow status |

### Date & Time

| Type | Component | Description |
|------|-----------|-------------|
| `field-date` | `DateFormField` | Date picker with calendar popover |
| `field-dateTime` | `DateTimeFormField` | Combined date and time picker |
| `field-time` | `TimeFormField` | Time picker |
| `field-dateRange` | `DateRangeFormField` | Date range with start/end |

### Toggle

| Type | Component | Description |
|------|-----------|-------------|
| `field-checkbox` | `CheckboxFormField` | Checkbox with horizontal layout |
| `field-switch` | `SwitchFormField` | Toggle switch with horizontal layout |

### Relation & Users

| Type | Component | Description |
|------|-----------|-------------|
| `field-relation` | `RelationFormField` | Related record lookup |
| `field-userSelect` | `UserSelectFormField` | Single user selector |
| `field-userMultiSelect` | `UserMultiSelectFormField` | Multi-user selector |
| `field-locationSelect` | `LocationSelectFormField` | Location/address picker with Google Maps when `VITE_GOOGLE_MAPS_API_KEY` is configured |

### Rich Content

> `LocationSelectFormField` automatically upgrades to the map-based picker in Vite apps when `VITE_GOOGLE_MAPS_API_KEY` is available. Without that variable, it falls back to manual address and coordinate inputs.

| Type | Component | Description |
|------|-----------|-------------|
| `field-docEditor` | `DocEditorFormField` | Rich text editor (Plate.js) with preset-based plugin system |
| `field-htmlEditor` | `HtmlEditorFormField` | WYSIWYG HTML editor (Plate.js) with export/import support |
| `field-emailEditor` | `EmailEditorFormField` | Email template editor (Unlayer) |
| `field-codeEditor` | `CodeEditorFormField` | Code editor (CodeMirror 6) with syntax highlighting and dark/light theme |
| `field-adaptiveCard` | `AdaptiveCardFormField` | Dialog-based [Adaptive Card Designer](/docs/web/components/adaptive-card-designer) — visual authoring of Microsoft Adaptive Card payloads |

### Data & Structure

| Type | Component | Description |
|------|-----------|-------------|
| `field-file` | `FileFormField` | File upload |
| `field-image` | `ImageFormField` | Image upload with preview |
| `field-avatar` | `AvatarField` | Avatar selector |
| `field-taskList` | `TaskListFormField` | Checklist / task list |
| `field-schemaRepeater` | `SchemaRepeaterFormField` | Repeater with drag & drop, collapsible rows, schema or key-value mode |
| `field-jsonSchema` | `JsonSchemaFormField` | Dialog-based [JSON Schema Designer](/docs/web/components/json-schema-designer) — drag-and-drop tree + JSON tab |
| `field-jsonata` | `JsonataFormField` | Dialog-based [JSONata Editor](/docs/web/components/jsonata-editor) — write, autocomplete and live-test a JSONata expression |
| `field-queryBuilder` | `QueryBuilderFormField` | Query builder |
| `field-dynamic` | `DynamicConfigFormField` | Dynamic configuration field |

## API Reference

### DynamicFormField

Dispatcher component that renders the correct field based on `field.type`.

```tsx

```

### DocEditorFormField

Rich text editor with preset-based plugin and toolbar system.

```tsx
import { DocEditorFormField } from '@docyrus/ui/components/form-fields/doc-editor-form-field';
import type { DocEditorPreset } from '@docyrus/ui/components/form-fields/doc-editor-form-field';

```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `preset` | `DocEditorPreset` | `'default'` | Editor preset level |

#### Presets

| Preset | Plugins | Toolbar |
|--------|---------|---------|
| `default` | Paragraphs, headings, lists, inline marks, link, autoformat | Floating only (marks + turn into + link) |
| `rich` | + table, code block, callout, toggle, emoji, font, align | Fixed + Floating |
| `full` | + columns, math, date, ToC, comments, suggestions, DnD, block menu | Fixed + Floating (all buttons) |

#### Preset Dependencies

Each preset requires additional packages beyond the base `platejs` dependency:

| Preset | Additional Packages |
|--------|-------------------|
| `default` | `@platejs/autoformat` `@platejs/link` `@platejs/floating` `@platejs/list` |
| `rich` | + `@platejs/code-block` `@platejs/table` `@platejs/callout` `@platejs/toggle` `@platejs/basic-styles` `@platejs/emoji` `@platejs/indent` `@emoji-mart/data` `lowlight` |
| `full` | + `@platejs/layout` `@platejs/math` `@platejs/date` `@platejs/toc` `@platejs/comment` `@platejs/suggestion` `@platejs/selection` `@platejs/dnd` `react-dnd` `react-dnd-html5-backend` |

### HtmlEditorFormField

WYSIWYG HTML editor powered by Plate.js that stores value as an HTML string. Includes the same rich formatting toolbar as DocEditorFormField (bold, italic, headings, lists, tables, etc.) plus built-in export and import buttons.

```tsx
import { HtmlEditorFormField } from '@docyrus/ui/components/form-fields/html-editor-form-field';

```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `field` | `IField` | — | Field configuration |
| `form` | `any` | — | TanStack Form instance |
| `disabled` | `boolean` | `false` | Disable editing |
| `className` | `string` | — | Additional CSS class |
| `preset` | `DocEditorPreset` | `'rich'` | Plate.js preset level |

**Data format:** Unlike DocEditorFormField (which stores Plate JSON), HtmlEditorFormField stores the value as an HTML string. Plate content is serialized to HTML via `serializeHtml` and deserialized back via `editor.api.html.deserialize`.

**Export:** Built-in export toolbar button supports HTML, PDF, Image, and Markdown formats.

**Import:** Built-in import toolbar button supports HTML and Markdown file import.

### CodeEditorFormField

Code editor powered by CodeMirror 6 with syntax highlighting, bracket matching, and autocompletion. Supports dark/light theme via `useDocyTheme`.

```tsx
import { CodeEditorFormField } from '@docyrus/ui/components/form-fields/code-editor-form-field';

```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `field` | `IField` | — | Field configuration |
| `form` | `any` | — | TanStack Form instance |
| `disabled` | `boolean` | `false` | Disable editing |
| `className` | `string` | — | Additional CSS class |
| `language` | `LanguageName` | `'tsx'` | CodeMirror language (`'tsx'`, `'python'`, `'json'`, `'css'`, `'sql'`, `'go'`, `'rust'`, etc.) |
| `basicSetup` | `BasicSetupOptions` | See below | CodeMirror basicSetup overrides |
| `minHeight` | `string` | `'200px'` | Editor minimum height |

**Default basicSetup:** Line numbers, fold gutter, bracket matching, close brackets, autocompletion, active line highlight, selection match highlight, tab size 2.

**Language support:** 50+ languages via `@uiw/codemirror-extensions-langs`. Dark/light theme auto-detected via `useDocyTheme`.

### SchemaRepeaterFormField

Repeatable form rows with drag & drop reordering, collapsible items, and dual mode support. Inspired by [Filament Repeater](https://filamentphp.com/docs/3.x/forms/fields/repeater).

**Schema mode** — pass `schema` prop with `IField[]` to render sub-fields per row:

```tsx
import { SchemaRepeaterFormField } from '@docyrus/ui/components/form-fields/schema-repeater-form-field';

```

**Key-value mode** — omit `schema` prop for simple key-value pairs:

```tsx

```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `field` | `IField` | — | Field configuration |
| `form` | `any` | — | TanStack Form instance |
| `disabled` | `boolean` | `false` | Disable editing |
| `className` | `string` | — | Additional CSS class |
| `schema` | `IField[]` | — | Sub-field definitions. If omitted, key-value mode. |
| `schemaEnumOptions` | `Record<string, EnumOption[]>` | — | Enum options keyed by sub-field slug |
| `maxItems` | `number` | — | Maximum number of items |
| `minItems` | `number` | `0` | Minimum number of items |
| `collapsible` | `boolean` | `true` | Whether items can be collapsed |
| `defaultCollapsed` | `boolean` | `false` | Whether items start collapsed |
| `addLabel` | `string` | `'Add item'` | Add button label |
| `cloneable` | `boolean` | `false` | Whether items can be cloned |
| `itemLabel` | `(item, index) => string` | `#index` | Dynamic item label |

### FieldMappingFormField

Wrapper that provides four value sources for any form field: **fixed**, **field mapping**, **template** (with `@mention`), and **formula**. The active tab is auto-detected from the stored value prefix. If only one tab is enabled via `modes`, the wrapper renders without the tab chrome.

```tsx
import { FieldMappingFormField } from '@docyrus/ui/components/form-fields/field-mapping-form-field';
import type { AvailableField } from '@docyrus/ui/components/form-fields/field-mapping-form-field';

const availableFields: AvailableField[] = [
  { name: 'user.name', label: 'User Name', type: 'text' },
  { name: 'user.email', label: 'User Email', type: 'email' },
  { name: 'project.title', label: 'Project Title', type: 'text' }
];

```

**Value format** — the wrapper encodes the active mode as a prefix in the form value:

| Mode | Prefix | Example value |
|------|--------|---------------|
| `fixed` | *(none)* | `Hello world` |
| `field-mapping` | `#FIELD=` | `#FIELD=user.name` |
| `template` | `#TEMPLATE=` | `#TEMPLATE=Hello @user.name!` |
| `formula` | `#FORMULA=` | `#FORMULA=user.age > 18 ? "adult" : "minor"` |

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `field` | `IField` | — | Field configuration |
| `form` | `any` | — | TanStack Form instance |
| `disabled` | `boolean` | `false` | Disable all tabs |
| `required` | `boolean` | `false` | Show required indicator on label |
| `className` | `string` | — | Additional CSS class |
| `availableFields` | `AvailableField[]` | `[]` | Selectable fields for mapping/template/formula tabs |
| `modes` | `MappingTab[]` | `['fixed', 'field-mapping', 'template', 'formula']` | Which tabs to show |
| `children` | `ReactNode` | — | Form field component rendered in the Fixed tab |

**AvailableField:**

| Field | Type | Description |
|-------|------|-------------|
| `name` | `string` | Slug used in the encoded value (e.g. `user.name`) |
| `label` | `string` | Human-readable label shown in dropdowns and mention spans |
| `type` | `string` | Field data type |
| `icon` | `string` | Optional icon name |

**Template mentions** — inside the Template tab, type `@` to open a searchable picker. Inserted mentions render as styled spans with `data-field-name` attributes. The editor uses strict allowlist parsing (text, `<br>`, and `data-field-name` spans only) to prevent XSS when reloading stored HTML.

### CheckboxGroupFormField

Inline multi-select that shares its visual language with `RadioGroupFormField` (square checkbox indicators) and stores the selected option ids as a `string[]` like `TagSelectFormField`. Good fit for a small, fixed set of options where the dropdown popover of TagSelect would feel heavy.

```tsx
import { CheckboxGroupFormField } from '@docyrus/ui/components/form-fields/checkbox-group-form-field';

```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `field` | `IField` | — | Field configuration. The form value at `field.slug` must be `string[]`. |
| `form` | `any` | — | TanStack Form instance |
| `enumOptions` | `EnumOption[]` | `[]` | Selectable options. Supports `icon`, `color`, and `description`. |
| `variant` | `'dropdown' \| 'card'` | — | `'card'` renders bordered cards with description support. Any other value renders the compact inline layout. |
| `columnCount` | `1 \| 2 \| 3 \| 4` | `1` | Number of grid columns, responsive at `sm` / `lg` breakpoints. |
| `disabled` | `boolean` | `false` | Disable all options |
| `required` | `boolean` | `false` | Show red asterisk on label |
| `className` | `string` | — | Additional CSS class on the outer `Field` |

**Visual variants**

| Variant | Layout | Use case |
|---------|--------|----------|
| *default* | Compact inline checkbox + label, aligns with `RadioGroup` default | Short labels, dense layouts |
| `card` | Bordered card with icon/color + label + description, highlights on check | Rich choices with descriptions or imagery |

### DocyrusFormFieldProps

All form field components share this interface:

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `field` | `IField` | — | Field configuration from the data source |
| `form` | `any` | — | TanStack Form instance (`useForm()` result) |
| `disabled` | `boolean` | `false` | Whether the field is disabled |
| `required` | `boolean` | `false` | Show red asterisk on label |
| `className` | `string` | — | Additional CSS class |
| `enumOptions` | `EnumOption[]` | `[]` | Options for select-based fields |
| `appSlug` | `string` | — | App slug for dynamic enum loading |
| `dataSourceSlug` | `string` | — | Data source slug for dynamic enum loading |

### IField

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | Unique field identifier |
| `name` | `string` | Display label |
| `slug` | `string` | Form value key (used as `form.Field` name) |
| `type` | `IFieldType` | Field type — determines which component renders |
| `defaultValue` | `string \| null` | Default value |
| `validations` | `string[] \| null` | Validation rules |
| `readOnly` | `boolean \| null` | Read-only flag |
| `fieldActions` | `FieldAction[] \| null` | Imperative actions triggered when this field's value changes. Evaluated by `useDocyrusFormView`'s field-actions engine. |
| `customValidations` | `CustomValidationRule[] \| null` | JSONata-based validation rules evaluated on submit. Each rule has `expression` (must return `true` to pass) and `message` (shown on failure). Rules are evaluated in order — first failure wins. Can also be injected at runtime via `fieldLayout[slug].customValidations`. |

### EnumOption

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | Option identifier |
| `name` | `string` | Display label |
| `color` | `string` | Color indicator (hex) |
| `icon` | `string` | Docyrus icon name |
| `slug` | `string` | Slug value (used by EnumFormField) |
| `sort_order` | `number` | Display order |

## Field Action Types

These types define the imperative action system used by `useDocyrusFormView` to react to field-value changes.

| Type | Description |
|------|-------------|
| `FieldAction` | A named trigger with `triggerType: 'onFieldChange'` and an ordered list of `FieldActionBlock[]`. |
| `FieldActionBlock` | A named block with if / else-if / else branches (`conditionalItems`, `elseActions`) and `unconditionalActions` that always run. |
| `FieldActionBlockItem` | One conditional branch: a `condition` (JSONata string or QB rule group) and the `actions` to run when it matches. |
| `FieldActionCondition` | Same format as `ComputedBooleanFormula` — JSONata string, QB `RuleGroupType`, or `null` (always-true). |
| `FieldActionStep` | Discriminated union of imperative commands: `setFieldValue`, `setFieldValues`, `clearFieldValue`, `showField`, `hideField`, `setFieldRequired`, `setFieldDisabled`, `setFieldReadOnly`. |
| `FieldActionPropertyOverrides` | Accumulated per-field overrides produced by action execution: `hidden`, `required`, `disabled`, `readOnly`. |

---

# Gantt
URL: /docs/web/components/gantt

A Gantt chart component with drag-and-drop task scheduling, timeline zoom, custom markers, and sidebar navigation.

**Demo:**

```tsx
'use client';

import { useCallback, useState } from 'react';

import {
  type GanttFeature, type GanttStatus, type Range,
  GanttProvider,
  GanttSidebar,
  GanttSidebarGroup,
  GanttSidebarItem,
  GanttTimeline,
  GanttHeader,
  GanttToday,
  GanttFeatureList,
  GanttFeatureListGroup,
  GanttFeatureRow
} from '@docyrus/ui/components/gantt';

import { addDays } from 'date-fns';

import { PropControls, type PropControl } from '@/components/prop-controls';

// ─── Statuses ─────────────────────────────────────────────────────────────────

const STATUSES = {
  planned: { id: 'planned', name: 'Planned', color: '#6b7280' },
  'in-progress': { id: 'in-progress', name: 'In Progress', color: '#3b82f6' },
  review: { id: 'review', name: 'Review', color: '#a855f7' },
  done: { id: 'done', name: 'Done', color: '#22c55e' }
} satisfies Record<string, GanttStatus>;

// ─── Initial Features ─────────────────────────────────────────────────────────

const today = new Date();

const INITIAL_FEATURES: GanttFeature[] = [
  {
    id: 'f1',
    name: 'Design system audit',
    startAt: addDays(today, -10),
    endAt: addDays(today, -3),
    status: STATUSES.done
  },
  {
    id: 'f2',
    name: 'Component library setup',
    startAt: addDays(today, -5),
    endAt: addDays(today, 2),
    status: STATUSES['in-progress']
  },
  {
    id: 'f3',
    name: 'Authentication flow',
    startAt: addDays(today, 1),
    endAt: addDays(today, 12),
    status: STATUSES['in-progress']
  },
  {
    id: 'f4',
    name: 'Dashboard layout',
    startAt: addDays(today, 5),
    endAt: addDays(today, 15),
    status: STATUSES.planned
  },
  {
    id: 'f5',
    name: 'API integration',
    startAt: addDays(today, 8),
    endAt: addDays(today, 22),
    status: STATUSES.planned
  },
  {
    id: 'f6',
    name: 'Code review and QA',
    startAt: addDays(today, 18),
    endAt: addDays(today, 25),
    status: STATUSES.review
  },
  {
    id: 'f7',
    name: 'Performance optimization',
    startAt: addDays(today, 20),
    endAt: addDays(today, 28),
    status: STATUSES.planned
  },
  {
    id: 'f8',
    name: 'User testing',
    startAt: addDays(today, 26),
    endAt: addDays(today, 32),
    status: STATUSES.planned
  }
];

// ─── Group Helper ─────────────────────────────────────────────────────────────

type FeatureGroup = {
  name: string;
  features: GanttFeature[];
};

function groupFeatures(features: GanttFeature[]): FeatureGroup[] {
  const groups: Record<string, GanttFeature[]> = {};

  for (const feature of features) {
    const statusName = feature.status.name;
    const group = groups[statusName];

    if (!group) {
      groups[statusName] = [feature];
    } else {
      group.push(feature);
    }
  }

  return Object.entries(groups).map(([name, items]) => ({
    name,
    features: items
  }));
}

// ─── GanttDemo ────────────────────────────────────────────────────────────────

export function GanttDemo() {
  const [features, setFeatures] = useState
            ))}
          

          
                  ))}
                
              ))}
            
          
        
      </div>
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-gantt
```

**Dependencies:**
- [@dnd-kit/core](https://www.npmjs.com/package/@dnd-kit/core)
- [@dnd-kit/modifiers](https://www.npmjs.com/package/@dnd-kit/modifiers)
- [date-fns](https://www.npmjs.com/package/date-fns)
- [lodash](https://www.npmjs.com/package/lodash)
- [lucide-react](https://www.npmjs.com/package/lucide-react)

## Usage

```tsx
import {
  GanttProvider,
  GanttSidebar,
  GanttSidebarHeader,
  GanttSidebarGroup,
  GanttSidebarItem,
  GanttHeader,
  GanttContentHeader,
  GanttTimeline,
  GanttFeatureList,
  GanttFeatureListGroup,
  GanttFeatureRow,
  GanttFeatureItem,
  GanttFeatureItemCard,
  GanttFeatureDragHelper,
  GanttColumns,
  GanttColumn,
  GanttAddFeatureHelper,
  GanttToday,
  GanttMarker,
  GanttCreateMarkerTrigger
} from '@docyrus/ui/components/gantt';
import type { GanttFeature, GanttStatus, Range } from '@docyrus/ui/components/gantt';

const statuses: GanttStatus[] = [
  { id: 'todo', name: 'To Do', color: '#3b82f6' },
  { id: 'in-progress', name: 'In Progress', color: '#f59e0b' },
  { id: 'done', name: 'Done', color: '#22c55e' }
];

const features: GanttFeature[] = [
  {
    id: '1',
    name: 'Design system',
    startAt: new Date(2025, 0, 1),
    endAt: new Date(2025, 0, 15),
    status: statuses[0]
  }
];

    
  

  <div className="flex flex-col flex-1">
    

    
      
            
          ))}
        
      
      
    
  </div>

  

```

## Components

| Component | Description |
|-----------|-------------|
| `GanttProvider` | Root context provider. Manages zoom, range, scroll, and drag state. |
| `GanttSidebar` | Left sidebar container for task list navigation. |
| `GanttSidebarHeader` | Sidebar header area. |
| `GanttSidebarGroup` | Named group within the sidebar. |
| `GanttSidebarItem` | Single task row in the sidebar. |
| `GanttHeader` | Top header container area. |
| `GanttContentHeader` | Timeline column headers (year/month/day labels based on range). |
| `GanttTimeline` | Scrollable timeline area with DnD support. |
| `GanttFeatureList` | Container for feature rows. |
| `GanttFeatureListGroup` | Group within the feature list. |
| `GanttFeatureRow` | Row container for a single feature. |
| `GanttFeatureItem` | Draggable feature bar within a row. |
| `GanttFeatureItemCard` | Visual card for the feature (colored by status). |
| `GanttFeatureDragHelper` | Drag preview overlay during drag operations. |
| `GanttColumns` | Background column grid for the timeline. |
| `GanttColumn` | Single column in the grid. |
| `GanttAddFeatureHelper` | Quick-add button that appears on column hover. |
| `GanttToday` | Today marker line on the timeline. |
| `GanttMarker` | Custom timeline marker (milestones, deadlines). |
| `GanttCreateMarkerTrigger` | Button to create a new marker at a date. |

## API Reference

### GanttProvider

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `zoom` | `number` | — | Zoom level controlling column density. |
| `range` | `Range` | — | Timeline granularity (`'daily'`, `'monthly'`, `'quarterly'`). |
| `columnWidth` | `number` | — | Pixel width per column. |
| `sidebarWidth` | `number` | — | Sidebar width in pixels. |
| `headerHeight` | `number` | — | Header height in pixels. |
| `rowHeight` | `number` | — | Row height in pixels. |
| `onAddItem` | `(date: Date) => void` | — | Called when quick-add is triggered. |
| `placeholderLength` | `number` | — | Default duration for new tasks. |
| `timelineData` | `TimelineData` | — | Date structure for timeline columns. |

### GanttSidebarGroup

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `name` | `string` | — | Group label displayed in the sidebar. |
| `className` | `string` | — | Additional CSS classes. |

### GanttSidebarItem

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `feature` | `GanttFeature` | — | Task data to display. |
| `className` | `string` | — | Additional CSS classes. |

### GanttFeatureItem

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `feature` | `GanttFeature` | — | Task data for positioning and drag. |
| `selected` | `boolean` | — | Highlight state. |
| `onSelect` | `(feature: GanttFeature) => void` | — | Selection callback. |
| `onDragEnd` | `(feature: GanttFeature, delta: Date) => void` | — | Called after drag with new date. |

### GanttFeatureItemCard

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `feature` | `GanttFeature` | — | Task data (status color, name). |
| `className` | `string` | — | Additional CSS classes. |

### GanttMarker

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `id` | `string` | — | Unique marker identifier. |
| `date` | `Date` | — | Marker position on the timeline. |
| `label` | `string` | — | Marker label text. |
| `className` | `string` | — | Additional CSS classes. |

## Type Reference

### GanttFeature

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | Unique identifier. |
| `name` | `string` | Task name. |
| `startAt` | `Date` | Task start date. |
| `endAt` | `Date` | Task end date. |
| `status` | `GanttStatus` | Current status with color. |
| `lane` | `string` | Optional lane/swimlane identifier. |

### GanttStatus

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | Unique identifier. |
| `name` | `string` | Display name. |
| `color` | `string` | Hex color for the status. |

### Range

`'daily'` | `'monthly'` | `'quarterly'`

### TimelineData

```tsx
type TimelineData = Array<{
  year: number;
  quarters: Array<{
    months: Array<{ days: number }>;
  }>;
}>;
```

---

# Handlebars Editor
URL: /docs/web/components/handlebars-editor

A three-pane workbench for writing and rendering Handlebars templates — a JSON input pane, a template editor with IntelliSense, and a live output pane with HTML preview.

**Demo:**

```tsx
'use client';

import { useState } from 'react';

import {
  HANDLEBARS_SAMPLES,
  HandlebarsEditor,
  type HandlebarsAIMessageContext,
  type HandlebarsEditorOrientation,
  type HandlebarsOutputMode
} from '@docyrus/ui/components/handlebars-editor';
import { Label } from '@docyrus/ui/primitives/ui/label';
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue
} from '@docyrus/ui/primitives/ui/select';
import { Switch } from '@docyrus/ui/primitives/ui/switch';
import { Settings2 } from 'lucide-react';

/*
 * Demo data with nested objects and an array of objects so the editor's
 * autocomplete surfaces paths like `customer.address.city` and
 * `orders.[0].product` — type `customer.` or open `{{#each orders}}…{{/each}}`
 * to use them.
 */
const DEMO_INPUT = {
  customer: {
    id: 'CUS-4821',
    name: 'Acme Corporation',
    email: 'hello@acme.example',
    isActive: true,
    address: {
      street: '100 Main St',
      city: 'Springfield',
      country: 'USA',
      postalCode: '01234'
    }
  },
  orders: [
    {
      id: 'ORD-1001',
      product: 'Widget Pro',
      quantity: 3,
      price: 29.99,
      tags: ['featured', 'sale']
    },
    {
      id: 'ORD-1002',
      product: 'Gadget Lite',
      quantity: 1,
      price: 79.5,
      tags: ['new']
    },
    {
      id: 'ORD-1003',
      product: 'Sprocket',
      quantity: 5,
      price: 12.25,
      tags: []
    }
  ],
  total: 261.97
};

const DEMO_TEMPLATE = `<h2>Hello, {{customer.name}}!</h2>
<p>Shipping to {{customer.address.city}}, {{customer.address.country}}.</p>
<ul>
  {{#each orders}}
  <li><strong>{{product}}</strong> × {{quantity}} — \${{price}}</li>
  {{/each}}
</ul>
<p>Total: <strong>\${{total}}</strong></p>`;

/** Canned demo replies — wire `onSendMessage` to a real backend in your app. */
async function demoAIReply(message: string, context: HandlebarsAIMessageContext): Promise<string> {
  await new Promise(resolve => setTimeout(resolve, 400));

  return [
    `_(Demo response)_ I'd help you with: **${message}**.`,
    '',
    `Your current template is \`${context.template || '(empty)'}\`.`,
    'Wire `aiAssistant.onSendMessage` to your LLM to get real answers.'
  ].join('\n');
}

export function HandlebarsEditorDemo() {
  const [showPanel, setShowPanel] = useState(false);
  const [orientation, setOrientation] = useState
            
              
                
              
            
          </div>

          <div className="flex flex-col gap-1.5">
            
            
              
                
              
            
          </div>

          <div className="flex items-center justify-between">
            
            
          </div>

          <div className="flex items-center justify-between">
            
            
          </div>

          <div className="flex items-center justify-between">
            
            
          </div>

          <div className="flex items-center justify-between">
            
            
          </div>
        </div>
      )}

      
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-handlebars-editor
```

**Dependencies:**
- [handlebars](https://www.npmjs.com/package/handlebars)
- [@uiw/react-codemirror](https://www.npmjs.com/package/@uiw/react-codemirror)
- [@uiw/codemirror-extensions-langs](https://www.npmjs.com/package/@uiw/codemirror-extensions-langs)
- [@codemirror/autocomplete](https://www.npmjs.com/package/@codemirror/autocomplete)
- [@codemirror/language](https://www.npmjs.com/package/@codemirror/language)
- [@codemirror/lint](https://www.npmjs.com/package/@codemirror/lint)
- [@codemirror/state](https://www.npmjs.com/package/@codemirror/state)
- [@codemirror/view](https://www.npmjs.com/package/@codemirror/view)
- [@lezer/highlight](https://www.npmjs.com/package/@lezer/highlight)
- [lucide-react](https://www.npmjs.com/package/lucide-react)

## Overview

`HandlebarsEditor` is a self-contained workbench for the
[Handlebars](https://handlebarsjs.com) templating language. It has two
tab-panel panes, each using the `variant="line"` style:

| Pane | Tabs |
|------|------|
| **Left pane** | **TEMPLATE** — Handlebars editor with syntax highlighting, helper autocomplete, hover docs and inline parse-error linting<br />**DATA** — JSON context the template renders against |
| **Right pane** | **OUTPUT** — read-only rendered string, with HTML or plain-text highlighting<br />**PREVIEW** — sandboxed iframe rendering the output as a live HTML document |

Rendering happens automatically as you type (debounced). Flip between TEMPLATE
and DATA from the left-pane tabs; flip between OUTPUT and PREVIEW from the
right-pane tabs.

## Features

- **Live rendering** — debounced re-render on every input or template change.
- **IntelliSense** — autocomplete with snippet expansion for Handlebars built-in block helpers (`#if`, `#each`, `#with`, `#unless`), inline helpers (`lookup`, `log`), and common comparison / math / formatting helpers.
- **Context path completion** — paths extracted from the JSON input (e.g. `user.name`, `orders.[0].total`) are surfaced in autocomplete as you type.
- **Hover documentation** — signatures, parameter docs and examples on hover.
- **Inline linting** — parse errors and unmatched block tags are underlined.
- **OUTPUT / PREVIEW tabs** — read the rendered string in CodeMirror, or flip to the PREVIEW tab to see it rendered inside a sandboxed iframe.
- **Custom helpers and partials** — pass `helpers` and `partials` to register your own at render time. Registrations are scoped to a private Handlebars instance so the global one is never mutated.
- **Samples menu** — load ready-made input + template pairs.
- **AI Assistant drawer** — opt-in chat panel built on ai-elements that slides in from the left and wires to your own LLM via `onSendMessage`.
- **Controlled or uncontrolled** — drive `template` / `input` yourself or let the component own them.
- **Flexible layout** — `horizontal` or `vertical`, with the input and output panes individually toggleable.
- **Theme-aware** — follows the Docyrus light / dark theme.

## Usage

```tsx
import { HandlebarsEditor } from "@docyrus/ui/components/handlebars-editor";

export function Example() {
  return (
    <HandlebarsEditor
      defaultTemplate="<p>Hello, {{firstName}} {{lastName}}!</p>"
      defaultInput={{ firstName: "Fred", lastName: "Smith" }}
      onResult={(html) => console.log(html)}
    />
  );
}
```

### Controlled

Drive both panes from your own state:

```tsx
const [template, setTemplate] = useState("");
const [input, setInput] = useState("{}");

```

### Custom helpers

Register additional helpers — they'll be available inside the template **and**
surfaced in the autocomplete dropdown:

```tsx
<HandlebarsEditor
  defaultTemplate="{{formatCurrency total 'USD'}}"
  defaultInput={{ total: 1250 }}
  helpers={{
    formatCurrency: (value, currency) =>
      new Intl.NumberFormat("en-US", {
        style: "currency",
        currency: String(currency ?? "USD")
      }).format(Number(value))
  }}
/>
```

> Memoize the `helpers` / `partials` objects if they're dynamic — the editor
> reads them on each render but does not re-render when only those references
> change.

### Custom partials

Partials let you split a template into reusable fragments:

```tsx
<HandlebarsEditor
  defaultTemplate="{{> greeting }}, welcome back."
  defaultInput={{ name: "Ada" }}
  partials={{
    greeting: "Hello, {{name}}"
  }}
/>
```

### Output rendering

The **OUTPUT** tab highlights the rendered result according to `outputMode`:
HTML syntax highlighting (`outputMode="html"`, the default), Markdown syntax
highlighting (`outputMode="markdown"`), or plain text (`outputMode="text"`).
The **PREVIEW** tab renders the same string as formatted content — an HTML
iframe for `html` / `text`, and formatted Markdown (via the shared
`react-markdown` renderer) for `markdown`:

```tsx
<HandlebarsEditor
  defaultTemplate="<button style='color:white;background:#2563eb;padding:6px 12px;border-radius:4px;border:0'>{{label}}</button>"
  defaultInput={{ label: "Click me" }}
  outputMode="html"
/>
```

### Markdown output

Set `outputMode="markdown"` for templates that render Markdown. The OUTPUT tab
highlights the Markdown source and the PREVIEW tab shows it as formatted content
(headings, lists, tables, blockquotes) using the same renderer that powers
comments and chat — no extra dependency:

```tsx

```

## AI Assistant

Pass an `aiAssistant` config to add an **AI Assistant** button to the toolbar.
Clicking it slides a chat drawer in from the left of the editor, built on
ai-elements (`Conversation`, `Message`). Wire `onSendMessage` to your LLM and
return the reply (sync or async):

```tsx
<HandlebarsEditor
  defaultTemplate="<p>Hello, {{name}}</p>"
  aiAssistant={{
    onSendMessage: async (message, { template, input, history }) => {
      const response = await fetch("/api/chat", {
        method: "POST",
        body: JSON.stringify({ message, template, input, history })
      });
      const { reply } = await response.json();
      return reply;
    },
    suggestions: [
      "Explain this template",
      "Show me an #each example",
      "How do I conditionally render?"
    ]
  }}
/>
```

Pass `aiAssistant={true}` to mount the chat shell without a backend (useful
while wiring one — messages are stored locally but no reply arrives).

## Standalone template editor

`HandlebarsCodeEditor` is the template pane on its own — drop it into a form
or an automation node config when you only need to capture a Handlebars
template.

```tsx
import { HandlebarsCodeEditor } from "@docyrus/ui/components/handlebars-editor";

const [value, setValue] = useState("");

```

`contextPaths` and `helperNames` feed the autocomplete with project-specific
suggestions in addition to the built-ins.

## Headless rendering

`useHandlebars` debounces and renders a template against an already-parsed
context value, with no UI:

```tsx
import { useHandlebars } from "@docyrus/ui/components/handlebars-editor";

function useGreeting(user: unknown) {
  const state = useHandlebars("Hello, {{name}}", user);

  return state.status === "success" ? state.result : "";
}
```

For a one-off render outside React, use `renderHandlebars`:

```tsx
import { renderHandlebars } from "@docyrus/ui/components/handlebars-editor";

const state = renderHandlebars(
  "{{count}} items",
  { count: 3 }
);
// → { status: "success", result: "3 items" }
```

## EditorAgent integration

Pair `useApplyHandlebars` with `renderAiAssistant` to give an LLM a writable template pane. The hook owns the editor's controlled state and ships an `applyHandlebars` tool that the agent calls to commit a new template — the tool also renders against the current input JSON and returns the rendered output preview so the agent can self-correct.

```tsx
import { EditorAgent } from '@docyrus/ui/components/editor-agent';
import { HandlebarsEditor, useApplyHandlebars } from '@docyrus/ui/components/handlebars-editor';

export function HandlebarsPlayground({ client, user, agentId }) {
  const handlebars = useApplyHandlebars();
  const [aiOpen, setAiOpen] = useState(false);

  return (
    <HandlebarsEditor
      template={handlebars.template}
      onTemplateChange={handlebars.setTemplate}
      input={handlebars.input}
      onInputChange={handlebars.setInput}
      aiAssistantOpen={aiOpen}
      onAiAssistantOpenChange={setAiOpen}
      renderAiAssistant={({ open, onClose }) => (
        
      )}
    />
  );
}
```

The matching backend agent must register a tool named `applyHandlebars` whose input schema mirrors `{ template: string (required), input?: any, explanation?: string }`.

## API Reference

### HandlebarsEditor

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `template` | `string` | — | Controlled Handlebars template. |
| `defaultTemplate` | `string` | — | Initial template for uncontrolled usage. |
| `onTemplateChange` | `(template: string) => void` | — | Fired whenever the template changes. |
| `input` | `string \| unknown` | — | Controlled JSON input — a string or any JSON-serializable value. |
| `defaultInput` | `string \| unknown` | — | Initial JSON input for uncontrolled usage. |
| `onInputChange` | `(input: string) => void` | — | Fired whenever the input text changes. |
| `helpers` | `Record<string, HandlebarsHelperFn>` | — | Custom helpers registered before compilation. |
| `partials` | `Record<string, string>` | — | Custom partials registered before compilation. |
| `noEscape` | `boolean` | `false` | Disable HTML-escaping for all interpolations. |
| `onResult` | `(result: string) => void` | — | Fired after a successful render. |
| `onError` | `(error: HandlebarsEvaluationError) => void` | — | Fired when parsing the input or rendering the template fails. |
| `onEvaluate` | `(state: HandlebarsEvaluationState) => void` | — | Fired after every render, regardless of outcome. |
| `samples` | `HandlebarsSample[]` | — | Pre-defined input + template pairs for the samples menu. |
| `aiAssistant` | `boolean \| HandlebarsAIAssistantConfig` | — | When provided, mounts the built-in AI Assistant drawer on the left. Pass `true` for the UI shell only, or a config object with `onSendMessage` to wire a backend. |
| `aiAssistantOpen` | `boolean` | — | Controlled open state for the AI Assistant drawer. When provided the editor stops managing the open state internally — pair with `onAiAssistantOpenChange`. |
| `onAiAssistantOpenChange` | `(open: boolean) => void` | — | Fired when the AI Assistant toolbar button toggles the drawer. |
| `renderAiAssistant` | `(ctx: IHandlebarsAiAssistantRenderContext) => ReactNode` | — | Replaces the built-in drawer body. When set, the toolbar button is shown even if `aiAssistant` is omitted, the drawer animates in as usual, and this render fn supplies the body. Use this to mount a custom agent (e.g. `<EditorAgent>`) inside the drawer. |
| `showInput` | `boolean` | `true` | Show the **DATA** tab inside the left pane. |
| `showResult` | `boolean` | `true` | Show the right **OUTPUT / PREVIEW** pane. |
| `showToolbar` | `boolean` | `true` | Show the header toolbar. |
| `title` | `string` | `'Handlebars'` | Title shown in the toolbar. |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Pane arrangement. |
| `outputMode` | `'text' \| 'html' \| 'markdown'` | `'html'` | How the rendered string is highlighted in the **OUTPUT** tab and rendered in the **PREVIEW** tab. `html` / `text` preview in a sandboxed iframe; `markdown` previews as formatted Markdown. |
| `debounceMs` | `number` | `300` | Debounce before rendering, in ms. |
| `readOnly` | `boolean` | `false` | Disables editing of both panes. |
| `height` | `number \| string` | `'28rem'` | Overall editor height. |
| `placeholder` | `string` | — | Placeholder shown in the empty template pane. |
| `className` | `string` | — | Root element className. |

### HandlebarsCodeEditor

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `string` | — | Current template text. |
| `onChange` | `(value: string) => void` | — | Fired on every edit. |
| `readOnly` | `boolean` | `false` | Disables editing. |
| `placeholder` | `string` | — | Placeholder shown when empty. |
| `autoFocus` | `boolean` | `false` | Focus the editor on mount. |
| `minHeight` | `string` | `'2.5rem'` | Minimum editor height. |
| `maxHeight` | `string` | `'12rem'` | Maximum editor height. |
| `height` | `string` | — | Fixed editor height — overrides `minHeight` / `maxHeight`. |
| `lineNumbers` | `boolean` | `false` | Show line numbers. |
| `lint` | `boolean` | `true` | Enable the parse-error linter. |
| `helperNames` | `string[]` | — | Extra helper names to surface in autocomplete (in addition to built-ins). |
| `contextPaths` | `string[]` | — | Suggest these context paths in autocomplete (e.g. extracted from input). |
| `basicSetup` | `BasicSetupOptions` | — | CodeMirror `basicSetup` overrides. |
| `extensions` | `Extension[]` | — | Extra CodeMirror extensions appended after the Handlebars language. |
| `className` | `string` | — | Wrapper className. |

### useHandlebars

```ts
useHandlebars(template: string, context: unknown, options?: UseHandlebarsOptions): HandlebarsEvaluationState
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `debounceMs` | `number` | `300` | Debounce before rendering, in ms. |
| `enabled` | `boolean` | `true` | When `false`, rendering is paused. |
| `helpers` | `Record<string, HandlebarsHelperFn>` | — | Custom helpers registered before compilation. |
| `partials` | `Record<string, string>` | — | Custom partials registered before compilation. |
| `noEscape` | `boolean` | `false` | Disable HTML-escaping for all interpolations. |
| `strict` | `boolean` | `false` | Treat compile-time warnings as errors. |

## Components

| Component | Description |
|-----------|-------------|
| `HandlebarsEditor` | The three-pane input / template / output workbench. |
| `HandlebarsCodeEditor` | The standalone Handlebars template editor. |
| `useApplyHandlebars` | Hook that owns `template` + `input` state and exposes the `applyHandlebars` client-side tool for `<EditorAgent>` — the tool writes the agent's template AND renders it, returning a rendered-output preview or a categorized error (input-empty / parse / render). See **EditorAgent integration** below. |

## Type Exports

| Type | Description |
|------|-------------|
| `HandlebarsEditorProps` | Props for `HandlebarsEditor`. |
| `HandlebarsCodeEditorProps` | Props for `HandlebarsCodeEditor`. |
| `HandlebarsEditorOrientation` | `'horizontal' \| 'vertical'`. |
| `HandlebarsOutputMode` | `'text' \| 'html' \| 'markdown'`. Controls the OUTPUT tab's highlighting and the PREVIEW tab's rendering. |
| `HandlebarsSample` | A `{ name, description?, input, template }` sample pair. |
| `HandlebarsHelperFn` | Signature for a user-supplied helper function. |
| `HandlebarsRenderOptions` | Options for `renderHandlebars` (`helpers`, `partials`, `noEscape`, `strict`). |
| `HandlebarsAIAssistantConfig` | Config for the AI Assistant drawer — `onSendMessage`, `suggestions`, `title`, `defaultOpen`, `width`, `placeholder`, `emptyStateDescription`. |
| `IHandlebarsAiAssistantRenderContext` | Argument passed to `renderAiAssistant` — `{ open, width, onClose, template, input }`. |
| `IUseApplyHandlebarsResult` | Return shape of `useApplyHandlebars` — `{ template, setTemplate, input, setInput, tools }`. |
| `HandlebarsAIMessageContext` | Context passed to `onSendMessage`: current `template`, `input` and `history`. |
| `HandlebarsChatMessage` | A `{ id, role: 'user' \| 'assistant', content }` chat entry. |
| `HandlebarsEvaluationState` | Discriminated union describing a render outcome. |
| `HandlebarsEvaluationError` | Normalized parse / render error (`phase`, `message`, `code?`, `line?`, `column?`). |
| `HandlebarsErrorPhase` | `'input' \| 'parse' \| 'render'`. |
| `UseHandlebarsOptions` | Options for the `useHandlebars` hook. |
| `HandlebarsHelper` | A built-in helper descriptor used by IntelliSense. |
| `HandlebarsHelperParam` | A single parameter of a `HandlebarsHelper`. |

## Helpers

| Export | Description |
|--------|-------------|
| `useHandlebars` | Headless hook — debounced render against a parsed context. |
| `renderHandlebars` | Compiles and runs a template; never throws. |
| `parseJsonInput` | Parses the JSON input text into a value or an error. |
| `handlebarsExtensions` | CodeMirror extension bundle (language, autocomplete, hover, linter). |
| `handlebarsLanguage` | CodeMirror `LanguageSupport` for Handlebars. |
| `HANDLEBARS_HELPERS` | The built-in helper catalog. |
| `HANDLEBARS_HELPER_MAP` | `Map` of helper name → descriptor. |
| `HANDLEBARS_HELPER_NAMES` | `Set` of built-in helper names. |
| `HANDLEBARS_BLOCK_HELPERS` | `Set` of names that are block helpers (`#if`, `#each`, `#with`, `#unless`). |
| `HANDLEBARS_DATA_VARIABLES` | The `@data` variables surfaced in autocomplete (`@index`, `@key`, `@first`, `@last`, `@root`). |
| `HANDLEBARS_KEYWORDS` | Reserved Handlebars context keywords. |
| `HANDLEBARS_SAMPLES` | Ready-made sample input + template pairs. |

---

# HTML Template Editor
URL: /docs/web/components/html-template-editor

WYSIWYG document editor for authoring Handlebars-aware HTML templates (quotes, invoices, reports). Word-style A4 page surface, four tabs (Visual / Code / Data / Preview), variable & helper chips, slash-style triggers, and a data-driven Table dialog where users discover JSON paths, configure columns, and write free-form sum / aggregate expressions per row.

**Demo:**

```tsx
'use client';

import { useState } from 'react';

import {
  DEFAULT_HELPERS,
  HtmlTemplateEditor,
  numberToWordsTR,
  type HandlebarsVariable
} from '@docyrus/ui/components/html-template-editor';

/*
 * Variables exposed to the side picker + the editor's `{{`-trigger
 * autocomplete. Listing them out gives the user a discoverable surface;
 * arbitrary Handlebars expressions still work without an entry here.
 */
const VARIABLES: HandlebarsVariable[] = [
  { name: 'company.name', label: 'Company Name', category: 'Company' },
  { name: 'company.addressLine1', label: 'Address Line 1', category: 'Company' },
  { name: 'company.addressLine2', label: 'Address Line 2', category: 'Company' },
  { name: 'company.email', label: 'Email', category: 'Company' },
  { name: 'company.phone', label: 'Phone', category: 'Company' },
  { name: 'company.taxId', label: 'Tax ID', category: 'Company' },

  { name: 'customer.name', label: 'Customer Name', category: 'Bill To' },
  { name: 'customer.company', label: 'Customer Company', category: 'Bill To' },
  { name: 'customer.addressLine1', label: 'Address Line 1', category: 'Bill To' },
  { name: 'customer.addressLine2', label: 'Address Line 2', category: 'Bill To' },
  { name: 'customer.email', label: 'Email', category: 'Bill To' },

  { name: 'invoice.number', label: 'Invoice Number', category: 'Invoice' },
  { name: 'invoice.issueDate', label: 'Issue Date (ISO)', category: 'Invoice' },
  { name: 'invoice.dueDate', label: 'Due Date (ISO)', category: 'Invoice' },
  { name: 'invoice.currency', label: 'Currency', category: 'Invoice' },
  { name: 'invoice.poNumber', label: 'PO Number', category: 'Invoice' },
  { name: 'invoice.paymentTerms', label: 'Payment Terms', category: 'Invoice' },
  { name: 'invoice.notes', label: 'Notes', category: 'Invoice' },

  { name: 'payment.bankName', label: 'Bank Name', category: 'Payment' },
  { name: 'payment.iban', label: 'IBAN', category: 'Payment' },
  { name: 'payment.swift', label: 'SWIFT / BIC', category: 'Payment' },

  { name: 'items', label: 'Line items (#each)', category: 'Items' },
  { name: 'name', label: 'Item name (inside #each)', category: 'Items' },
  { name: 'description', label: 'Description (inside #each)', category: 'Items' },
  { name: 'qty', label: 'Qty (inside #each)', category: 'Items' },
  { name: 'unitPrice', label: 'Unit Price (inside #each)', category: 'Items' },
  { name: 'discountPct', label: 'Discount % (inside #each)', category: 'Items' },
  { name: 'taxPct', label: 'Tax % (inside #each)', category: 'Items' },

  { name: 'formatCurrency value invoice.currency', label: 'formatCurrency', category: 'Helpers' },
  { name: 'formatDate invoice.issueDate "DD MMM YYYY"', label: 'formatDate', category: 'Helpers' },
  { name: 'lineNet qty unitPrice discountPct', label: 'lineNet (per row)', category: 'Helpers' },
  { name: 'sumLineNets items', label: 'sumLineNets (subtotal)', category: 'Helpers' },
  { name: 'sumLineTaxes items', label: 'sumLineTaxes (tax)', category: 'Helpers' },
  { name: 'sumGrandTotal items', label: 'sumGrandTotal (total)', category: 'Helpers' },
  { name: 'numberToWordsTR (sumGrandTotal items)', label: 'numberToWordsTR (in words)', category: 'Helpers' }
];

/*
 * Full invoice dataset pre-loaded into the Data tab. Item rows keep the
 * canonical `qty` / `unitPrice` / `discountPct` / `taxPct` keys so the
 * built-in money helpers (`lineNet`, `sumLineNets`, `sumLineTaxes`,
 * `sumGrandTotal`) compute the totals without any extra wiring.
 */
const INITIAL_JSON = JSON.stringify(
  {
    company: {
      name: 'Northwind Studio Ltd.',
      addressLine1: '128 Maple Avenue, Suite 400',
      addressLine2: 'Portland, OR 97204, USA',
      email: 'billing@northwind.studio',
      phone: '+1 (503) 555-0142',
      taxId: 'US-93-1847265'
    },
    customer: {
      name: 'Jordan Avery',
      company: 'Acme Corporation',
      addressLine1: '500 Industrial Parkway',
      addressLine2: 'Austin, TX 78704, USA',
      email: 'accounts@acme.com'
    },
    invoice: {
      number: 'INV-2026-0042',
      issueDate: '2026-05-21',
      dueDate: '2026-06-20',
      currency: 'USD',
      poNumber: 'PO-77810',
      paymentTerms: 'Net 30',
      notes: 'Thank you for your business. Please reference the invoice number with your payment.'
    },
    payment: {
      bankName: 'First National Bank',
      iban: 'US64 FNBK 0000 0123 4567 89',
      swift: 'FNBKUS33'
    },
    items: [
      {
        id: 'r1', name: 'Product Strategy Consulting', description: 'Discovery workshops & roadmap (8 hrs)', qty: 8, unitPrice: 150, discountPct: 0, taxPct: 8.25
      },
      {
        id: 'r2', name: 'Platform Implementation', description: 'Core setup, data migration & QA', qty: 1, unitPrice: 2500, discountPct: 5, taxPct: 8.25
      },
      {
        id: 'r3', name: 'UI Design System', description: 'Component library & design tokens', qty: 1, unitPrice: 1800, discountPct: 0, taxPct: 8.25
      },
      {
        id: 'r4', name: 'Annual Support Plan', description: 'Priority support, 12 months', qty: 12, unitPrice: 200, discountPct: 10, taxPct: 8.25
      }
    ]
  },
  null,
  2
);

/*
 * A simple, self-contained invoice template. Every style is inline so the
 * markup renders identically in the Visual / Preview tabs, the rasterized
 * PDF tab, and any external Handlebars compile (e.g. server-side email/PDF
 * export) without depending on an external stylesheet. The line-item table
 * is driven by `{{#each items}}`; totals use the built-in money helpers.
 */
const INITIAL_TEMPLATE = `<div style="font-family: 'Helvetica Neue', Arial, sans-serif; color: #0f172a; font-size: 13px; line-height: 1.5;">
  <table style="width: 100%; border-collapse: collapse; margin-bottom: 26px;">
    <tr>
      <td style="vertical-align: top; border-top: 0; border-right: 0; border-bottom: 0; border-left: 0;">
        <div style="font-size: 20px; font-weight: 700; color: #0f172a;">{{company.name}}</div>
        <div style="color: #64748b; font-size: 12px;">{{company.addressLine1}}</div>
        <div style="color: #64748b; font-size: 12px;">{{company.addressLine2}}</div>
        <div style="color: #64748b; font-size: 12px;">{{company.email}} &middot; {{company.phone}}</div>
        <div style="color: #94a3b8; font-size: 12px;">Tax ID: {{company.taxId}}</div>
      </td>
      <td style="vertical-align: top; text-align: right; border-top: 0; border-right: 0; border-bottom: 0; border-left: 0;">
        <div style="font-size: 32px; font-weight: 800; letter-spacing: 4px; color: #4f46e5;">INVOICE</div>
        <div style="color: #475569; font-size: 13px; font-weight: 600;">{{invoice.number}}</div>
        <div style="color: #94a3b8; font-size: 12px;">Issued {{formatDate invoice.issueDate "DD MMM YYYY"}}</div>
        <div style="color: #94a3b8; font-size: 12px;">Due {{formatDate invoice.dueDate "DD MMM YYYY"}}</div>
      </td>
    </tr>
  </table>

  <table style="width: 100%; border-collapse: collapse; margin-bottom: 24px;">
    <tr>
      <td style="vertical-align: top; width: 60%; border-top: 0; border-right: 0; border-bottom: 0; border-left: 0;">
        <div style="text-transform: uppercase; font-size: 10px; letter-spacing: 1.5px; color: #94a3b8; font-weight: 700;">Billed To</div>
        <div style="font-weight: 700; font-size: 14px; color: #0f172a;">{{customer.name}}</div>
        <div style="color: #475569; font-size: 12px;">{{customer.company}}</div>
        <div style="color: #475569; font-size: 12px;">{{customer.addressLine1}}</div>
        <div style="color: #475569; font-size: 12px;">{{customer.addressLine2}}</div>
        <div style="color: #475569; font-size: 12px;">{{customer.email}}</div>
      </td>
      <td style="vertical-align: top; text-align: right; border-top: 0; border-right: 0; border-bottom: 0; border-left: 0;">
        <div style="text-transform: uppercase; font-size: 10px; letter-spacing: 1.5px; color: #94a3b8; font-weight: 700;">Details</div>
        <div style="color: #475569; font-size: 12px;">PO {{invoice.poNumber}}</div>
        <div style="color: #475569; font-size: 12px;">Terms: {{invoice.paymentTerms}}</div>
      </td>
    </tr>
  </table>

  <table style="width: 100%; border-collapse: collapse; margin-bottom: 22px;">
    <tr>
      <td style="text-align: left; padding: 11px 14px; font-size: 10px; text-transform: uppercase; letter-spacing: 1px; font-weight: 700; color: #ffffff; background-color: #4f46e5;">Description</td>
      <td style="text-align: right; padding: 11px 14px; font-size: 10px; text-transform: uppercase; letter-spacing: 1px; font-weight: 700; color: #ffffff; background-color: #4f46e5;">Qty</td>
      <td style="text-align: right; padding: 11px 14px; font-size: 10px; text-transform: uppercase; letter-spacing: 1px; font-weight: 700; color: #ffffff; background-color: #4f46e5;">Unit Price</td>
      <td style="text-align: right; padding: 11px 14px; font-size: 10px; text-transform: uppercase; letter-spacing: 1px; font-weight: 700; color: #ffffff; background-color: #4f46e5;">Disc.</td>
      <td style="text-align: right; padding: 11px 14px; font-size: 10px; text-transform: uppercase; letter-spacing: 1px; font-weight: 700; color: #ffffff; background-color: #4f46e5;">Amount</td>
    </tr>
    {{#each items}}
    <tr>
      <td style="padding: 12px 14px; border-bottom: 1px solid #eef2f7;"><div style="font-weight: 600; color: #0f172a;">{{name}}</div><div style="color: #94a3b8; font-size: 11px;">{{description}}</div></td>
      <td style="padding: 12px 14px; text-align: right; color: #475569; border-bottom: 1px solid #eef2f7;">{{qty}}</td>
      <td style="padding: 12px 14px; text-align: right; color: #475569; border-bottom: 1px solid #eef2f7;">{{formatCurrency unitPrice ../invoice.currency}}</td>
      <td style="padding: 12px 14px; text-align: right; color: #475569; border-bottom: 1px solid #eef2f7;">{{discountPct}}%</td>
      <td style="padding: 12px 14px; text-align: right; font-weight: 700; color: #0f172a; border-bottom: 1px solid #eef2f7;">{{formatCurrency (lineNet qty unitPrice discountPct) ../invoice.currency}}</td>
    </tr>
    {{/each}}
  </table>

  <table style="width: 100%; border-collapse: collapse; margin-bottom: 8px;">
    <tr>
      <td style="width: 60%;"></td>
      <td style="padding: 7px 14px; text-align: right; color: #64748b; font-size: 13px;">Subtotal</td>
      <td style="padding: 7px 14px; text-align: right; color: #0f172a; font-size: 13px; width: 150px;">{{formatCurrency (sumLineNets items) invoice.currency}}</td>
    </tr>
    <tr>
      <td></td>
      <td style="padding: 7px 14px; text-align: right; color: #64748b; font-size: 13px;">Tax</td>
      <td style="padding: 7px 14px; text-align: right; color: #0f172a; font-size: 13px;">{{formatCurrency (sumLineTaxes items) invoice.currency}}</td>
    </tr>
    <tr>
      <td></td>
      <td style="padding: 12px 14px; text-align: right; font-weight: 700; font-size: 14px; color: #ffffff; background-color: #4f46e5;">Total Due</td>
      <td style="padding: 12px 14px; text-align: right; font-weight: 800; font-size: 16px; color: #ffffff; background-color: #4f46e5;">{{formatCurrency (sumGrandTotal items) invoice.currency}}</td>
    </tr>
  </table>

  <table style="width: 100%; border-collapse: collapse; margin-top: 26px;">
    <tr>
      <td style="vertical-align: top; background-color: #f8fafc; padding: 16px 18px;">
        <div style="text-transform: uppercase; font-size: 10px; letter-spacing: 1.5px; color: #94a3b8; font-weight: 700;">Payment Details</div>
        <div style="color: #475569; font-size: 12px;">{{payment.bankName}} &middot; IBAN {{payment.iban}} &middot; SWIFT {{payment.swift}}</div>
        <div style="color: #64748b; font-size: 12px; margin-top: 8px;"><strong style="color: #475569;">Notes</strong> &mdash; {{invoice.notes}}</div>
      </td>
    </tr>
  </table>

  <div style="margin-top: 18px; text-align: center; color: #cbd5e1; font-size: 11px; letter-spacing: 0.5px;">Thank you for your business &middot; {{company.name}}</div>
</div>`;

export function HtmlTemplateEditorDemo() {
  const [value, setValue] = useState(INITIAL_TEMPLATE);
  const [data, setData] = useState(INITIAL_JSON);

  return (
    
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-html-template-editor
```

**Dependencies:**
- [platejs](https://www.npmjs.com/package/platejs)
- [handlebars](https://www.npmjs.com/package/handlebars)
- [@uiw/react-codemirror](https://www.npmjs.com/package/@uiw/react-codemirror)
- [@uiw/codemirror-extensions-langs](https://www.npmjs.com/package/@uiw/codemirror-extensions-langs)

## Usage

The editor opens to a Word-style A4 page surface with a sticky toolbar above it. Four tabs across the top let users move between **Visual** (WYSIWYG), **Code** (raw Handlebars HTML), **Data** (JSON sample data) and **Preview** (compiled output).

```tsx
import { useState } from 'react';
import {
  DEFAULT_HELPERS,
  HtmlTemplateEditor,
  type HandlebarsVariable
} from '@docyrus/ui/components/html-template-editor';

const variables: HandlebarsVariable[] = [
  { name: 'customer.name', label: 'Customer Name', category: 'Customer' },
  { name: 'order.total', label: 'Order Total', category: 'Order' }
];

export function MyTemplateEditor() {
  const [html, setHtml] = useState('');
  const [data, setData] = useState('{}');

  return (
    
  );
}
```

### AI Assistant slot

Pass a `renderAiAssistant` callback to mount any agent body inside a left-side drawer. The editor adds a Bot toggle button to the tabs row that opens/closes the drawer; the slot receives live editor state (`html`, `data`) so the agent can read the user's current draft and inject schema-aware context.

The preferred wiring uses `useApplyHtmlTemplate` which owns the controlled state AND ships a fully-formed `applyHtmlTemplate` tool — the tool not only writes the new HTML into the editor but also runs `Handlebars.compile` against the current Data tab JSON and returns the compiled output preview, so the LLM can iterate to a working template without further user input.

```tsx
import { EditorAgent } from '@docyrus/ui/components/editor-agent';
import {
  HtmlTemplateEditor,
  useApplyHtmlTemplate
} from '@docyrus/ui/components/html-template-editor';

export function TemplateEditorWithAi({ client, user, agentId, dataSourceId, schema }) {
  const htmlTemplate = useApplyHtmlTemplate();
  const [aiOpen, setAiOpen] = useState(false);

  return (
    <HtmlTemplateEditor
      value={htmlTemplate.html}
      onChange={htmlTemplate.setHtml}
      data={htmlTemplate.data}
      onDataChange={htmlTemplate.setData}
      aiAssistantOpen={aiOpen}
      onAiAssistantOpenChange={setAiOpen}
      renderAiAssistant={({ open, onClose }) => (
        <EditorAgent
          agentId={agentId}
          dataSourceId={dataSourceId}
          client={client}
          user={user}
          open={open}
          onClose={onClose}
          editorContext={() => buildPromptContext({ schema, data: htmlTemplate.data, html: htmlTemplate.html })}
          clientTools={htmlTemplate.tools}
        />
      )}
    />
  );
}
```

The hook owns the html/data state, so the agent's `applyHtmlTemplate` tool pushes new content into the editor while the user's manual edits still flow through `onChange` / `onDataChange`. `editorContext` is invoked on every send — return a string that snapshots schema + current input + current template so the agent always sees fresh state. The matching backend agent must register a tool named `applyHtmlTemplate` whose input schema mirrors `{ html: string (required), data?: object, explanation?: string }`.

## Features

- **A4 page surface** — Visual + Preview tabs render the document inside a 794×1123 px sheet (210×297 mm at 96 DPI) with proper margins, so the editor matches the final PDF 1:1.
- **Sticky Word-style toolbar** — pinned above the page; follows the user when scrolling long documents.
- **Variable & helper chips** — `{{customer.name}}` renders as a colored inline badge (color is derived from `category`). Block helpers like `{{#if}}`, `{{#each}}`, `{{#with}}`, `{{#unless}}` get their own chips; `{{/helper}}` and `{{else}}` complete the set.
- **`{{`-trigger autocomplete** — type `{{` anywhere to open a filtered picker. `↑↓` navigates, `Enter`/`Tab` inserts. Each variable's `category` becomes a section heading.
- **Auto-convert** — typing a complete `{{var}}`, `{{#helper expr}}`, `{{/helper}}`, or `{{else}}` and closing with `}}` converts the text to the corresponding chip automatically.
- **Click-to-edit chips** — clicking any inserted chip opens an edit popover (above the chip via Radix collision detection). Variable chips swap their `name` from the same variables list. Block-helper chips edit their expression; `{{#each}}` and `{{#with}}` get a path picker built live from the Data tab JSON (array vs. object scan, suffix-match highlights the current selection). Marks (bold/italic/etc.) on the chip survive the swap.
- **Robust table round-trip** — `<table><tbody>{{#each}}<tr>…</tr>{{/each}}</tbody></table>` survives any chip edit. Block markers transport via HTML comments to bypass HTML foster-parenting, get hoisted out of table sections (slate can't hold inline-void as direct child of `<table>`), `<thead>`/`<tbody>`/`<tfoot>` are unwrapped and `colSizes` is pre-seeded so the column count doesn't collapse to one. The serializer pattern-detects `[chip, table, chip]` adjacency and re-injects the chips around the body rows only (first `<tr>` is treated as `<thead>`), so `{{#each}}` never wraps the header.
- **Four tabs**: Visual (WYSIWYG), Code (raw HTML in CodeMirror), Data (JSON sample data in CodeMirror), Preview (Handlebars-compiled output rendered in an A4-sized iframe).
- **Data-driven Table dialog** — the toolbar `Table` button scans the Data tab JSON for array-of-object paths and walks the user through column selection, per-cell styling, per-column aggregate pills (Sum / Avg / Min / Max / Count) and free-form formula expressions like `qty * unitPrice * (1 - discountPct/100)`. Inserted tables stay live: serialization emits `{{#each <path>}}` so the Preview tab iterates over real data.
- **Safe expression evaluator** — `sumLineExpr` evaluates user-typed math via a small recursive-descent parser (no `eval` / `new Function`) so templates can be safely shared between users.
- **Precision-safe currency math** — every financial helper rounds with EPSILON correction (`Math.round((n + Number.EPSILON) * 100) / 100`) so cumulative IEEE-754 drift can't move displayed totals by `0.01`.
- **Default Handlebars helpers** — `formatCurrency`, `formatNumber`, `formatPercent`, `formatDate`, `multiply`, `add`, `subtract`, `divide`, `sumProperty`, `avgProperty`, `minProperty`, `maxProperty`, `countItems`, `lineNet`, `lineTotal`, `sumLineNets`, `sumLineTaxes`, `sumGrandTotal`, `sumLineExpr`, `eq`, `gt`, `lt` are registered at module load.
- **`extraHelpers` prop** — register additional helpers (locale packs, domain formatters) without touching the package.
- **Locale pack: `numberToWordsTR`** — opt-in Turkish number-to-words helper (`Sekiz Yüz Altmış Dokuz Bin Altı Yüz Kırk Türk Lirası`). Pass via `extraHelpers` only when needed.
- **Built-in Plate kits** — Basic blocks, marks, lists, links, alignment, font color & size, columns, native tables, callouts.
- **Read-only mode** — pass `readOnly` to render a non-editable view with chips visible but the toolbar hidden.

## Data-driven tables

Click the toolbar **Table** button to open a configuration dialog backed by the Data tab JSON. The dialog walks the user through four steps; everything is configured by typing or clicking — no schema code required.

### 1. Pick a data path

The dialog enumerates every array-of-objects path found in the Data tab JSON (up to 6 levels deep) and lists them as a tree. For example with this JSON:

```json
{
  "customer": {
    "contacts": [
      { "id": "c1", "name": "Aytekin", "phones": [{ "type": "Work", "number": "..." }] }
    ]
  },
  "items": [{ "qty": 1, "unitPrice": 100, "discountPct": 5 }]
}
```

…the picker surfaces `items`, `customer.contacts`, and `customer.contacts.0.phones` as selectable sources.

### 2. Configure columns

Once a path is selected, the dialog auto-detects fields from the first row and lists them as toggleable rows. Each field carries:

- **Visibility** — `id`-shaped fields default to hidden; the user opts them back in.
- **Format** — `text` / `number` / `currency` / `percent` / `date` / `computed`. Smart inference picks `percent` for `*_pct` / `*_rate` keys, `currency` for `price`, `cost`, `total`-style keys, `date` for `*_at` / `*date*` keys.
- **Alignment, weight, size, text & background color** — per-cell styling that flows into the serialized HTML.

A live preview chip on each row shows what the cell will look like with the first sample row's data.

### 3. Toggle per-column aggregates

Each column row carries pill toggles for the standard aggregates — **Toplam (Sum)**, **Ort. (Avg)**, **Min**, **Max**, **Adet (Count)**. Active pills add a row to the table's `<tfoot>` at serialize time. Currency / number columns get all five pills; text / date columns only get Count.

### 4. Write free-form total formulas

Below the field list is a "Smart total" section where users type compound expressions like `qty * unitPrice * (1 - discountPct/100) * (1 + taxPct/100)` — anything the [expression parser](#expression-syntax) understands. Each saved total has a wide editable label textarea (anything — `×`, `−`, multi-line — goes) and a separate formula textarea. The serializer emits these as a right-aligned 2-column block below the main table, with the canonical net → tax → grand-total order if those shapes are detected.

### Editing inserted tables

Each ad-hoc table renders an **Edit** button in its header. Clicking it re-opens the same dialog with the existing config (path, columns, formulas) pre-filled. Legacy schema-driven tables loaded from older templates also round-trip cleanly.

## Expression syntax

User-typed formulas are evaluated by a small recursive-descent parser that supports:

| Construct | Example |
|-----------|---------|
| Identifier (column key) | `qty`, `unitPrice`, `discountPct` |
| Numeric literal | `100`, `0.5`, `.25` |
| Binary operators | `+ - * / %` |
| Parentheses | `(1 - discountPct/100)` |
| Unary minus | `-amount` |

The evaluator deliberately avoids `eval` / `new Function` — templates can be persisted and shared across users without becoming a code-injection vector. Anything that fails to parse evaluates to `0`, so a typo in the textarea doesn't blow up the preview.

```handlebars
{{formatCurrency (sumLineExpr items "qty * unitPrice * (1 - discountPct/100) * (1 + taxPct/100)") "USD"}}
```

## Bring your own helpers

The editor only registers a small generic helper set by default. Locale-specific or domain-specific helpers should be passed via `extraHelpers`:

```tsx
import {
  HtmlTemplateEditor,
  numberToWordsTR
} from '@docyrus/ui/components/html-template-editor';

```

Helpers are registered on first mount and become available globally via the singleton `Handlebars` import. From the template body:

```handlebars
<p>Total: {{formatCurrency (sumLineExpr items "qty * unitPrice * (1 + taxPct/100)") order.currency}}</p>
<p>In words: {{numberToWordsTR (sumLineExpr items "qty * unitPrice * (1 + taxPct/100)")}}</p>
```

## Compile the template at runtime

The component itself does NOT compile templates — it produces the template HTML. To render it with live data in your app (preview pane, PDF generation, server-side render):

```tsx
import Handlebars from 'handlebars';

const output = Handlebars.compile(html)(data);
```

The Preview tab inside the editor uses this exact pattern against the `data` JSON the user provides.

## Advanced: schema-driven tables (legacy)

For consumer apps that need fully pre-defined tables (e.g. fixed invoice template, hard-coded column compute functions), the editor still accepts a `tableSchemas` prop. Schema-driven `<computed_table>` blocks already present in loaded HTML continue to render and edit; new schemas can be passed without affecting the data-driven Table dialog.

```tsx
import {
  type ComputedRow,
  type ComputedTableSchema
} from '@docyrus/ui/components/html-template-editor';

function netOf(row: ComputedRow): number {
  return (Number(row.qty) || 0) * (Number(row.unitPrice) || 0) * (1 - (Number(row.discountPct) || 0) / 100);
}

const QUOTE_SCHEMA: ComputedTableSchema = {
  id: 'quote-line-items',
  label: 'Line Items',
  defaultCurrency: 'USD',
  columns: [
    { key: 'name', label: 'Description', type: 'text' },
    { key: 'qty', label: 'Qty', type: 'number', defaultValue: 1 },
    { key: 'unitPrice', label: 'Unit Price', type: 'currency', defaultValue: 0 },
    { key: 'discountPct', label: 'Discount', type: 'percent', defaultValue: 0 },
    { key: 'lineTotal', label: 'Total', type: 'computed', compute: netOf }
  ],
  footer: [
    { key: 'subtotal', label: 'Subtotal', compute: rows => rows.reduce((a, r) => a + netOf(r), 0) }
  ]
};

```

Inside the template HTML, instances are stored as `<div data-computed-table="1" data-config="<urlencoded JSON>"></div>` — the editor reconstructs the table from `schemaId` + `rows` on mount.

## Advanced: HandlebarsKit

`HandlebarsKit` is a flat array of the five HBS-related Plate plugins (variable / block-open / block-close / else / normalizer). Use it when you want HBS chip behavior embedded inside a custom Plate editor:

```tsx
import { HandlebarsKit } from '@docyrus/ui/components/html-template-editor';

const editor = usePlateEditor({ plugins: [...myPlugins, ...HandlebarsKit] });
```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `string` | `''` | Initial HBS HTML string |
| `onChange` | `(value: string) => void` | — | Called with serialized HBS HTML on change (debounced 300 ms). After initial mount the editor re-pushes a serialized version so `<div data-computed-table>` shells receive their inner static table HTML. |
| `data` | `string` | `'{\\n  \\n}'` | Initial JSON sample data shown in the Data tab and used by the Preview tab's Handlebars compile. Also scanned by the Table dialog to surface array paths. |
| `onDataChange` | `(data: string) => void` | — | Called when the user edits the JSON data. |
| `variables` | `HandlebarsVariable[]` | `[]` | Variables shown in the side picker and the `{{`-trigger combobox. |
| `helpers` | `HandlebarsBlockHelper[]` | `DEFAULT_HELPERS` | Block helpers shown in the picker and toolbar popover. |
| `tableSchemas` | `ComputedTableSchema[]` | `[]` | Legacy schema-driven table definitions (see [Advanced: schema-driven tables](#advanced-schema-driven-tables-legacy)). |
| `extraHelpers` | `Record<string, (...args: unknown[]) => unknown>` | — | Extra Handlebars helpers to register on mount (e.g. `numberToWordsTR`). |
| `defaultTab` | `'visual' \| 'code' \| 'data' \| 'preview'` | `'visual'` | Tab shown on first render. |
| `readOnly` | `boolean` | `false` | Disables editing; hides toolbar. |
| `className` | `string` | — | Extra class on the root container. |
| `placeholder` | `string` | `'Write your template…'` | Placeholder shown in the empty editor. |
| `minHeight` | `string` | `'240px'` | CSS `min-height` of the editor / code view area. |
| `aiAssistantOpen` | `boolean` | — | Controlled open state for the AI Assistant drawer. When provided the editor stops managing the open state internally — pair with `onAiAssistantOpenChange`. |
| `onAiAssistantOpenChange` | `(open: boolean) => void` | — | Fired when the AI Assistant toolbar button toggles the drawer. |
| `renderAiAssistant` | `(ctx: IHtmlTemplateAiAssistantRenderContext) => ReactNode` | — | Mounts a custom AI Assistant drawer body on the left of the editor. When set, the toolbar shows a Bot toggle that opens/closes the drawer; this render fn supplies the body (typically a `<DocyrusAgent>` or `<EditorAgent>` wrapper). Without it the AI button is hidden. |
| `aiAssistantWidth` | `number` | `380` | Width in pixels the drawer animates to when open. |

## Type Exports

| Type | Description |
|------|-------------|
| `HtmlTemplateEditorProps` | Props for `HtmlTemplateEditor` |
| `HandlebarsVariable` | Variable definition passed to `variables` |
| `HandlebarsBlockHelper` | Helper definition passed to `helpers` |
| `ComputedTableSchema` | Full schema describing a legacy schema-driven table |
| `ComputedColumn` | One column inside a schema |
| `ComputedColumnType` | `'text' \| 'number' \| 'currency' \| 'percent' \| 'computed'` |
| `ComputedColumnContext` | `{ currency, locale, rows, index }` passed to `column.compute` / `column.format` |
| `ComputedFooter` | Footer aggregate row inside a schema |
| `ComputedFooterContext` | `{ currency, locale, rows }` passed to `footer.compute` |
| `ComputedRow` | Open dict `Record<string, unknown> & { id: string }` |
| `ComputedTableLabels` | i18n labels (title / addRow / emptyState / currencyLabel) |
| `ComputedCurrencyOption` | `{ code, label, locale? }` entry for `schema.currencyOptions` |
| `ComputedColumnConfig` | Ad-hoc column definition stored on the Plate node (key + label + format + per-cell styling) |
| `ComputedColumnFormat` | `'text' \| 'number' \| 'currency' \| 'percent' \| 'date' \| 'computed'` |
| `ComputedFooterConfig` | Ad-hoc footer entry: per-column aggregate or free-form `formula` |
| `ComputedAggregate` | `'sum' \| 'average' \| 'count' \| 'min' \| 'max'` |
| `ComputedFontWeight` | `'normal' \| 'bold'` |
| `ComputedFontSize` | `'xs' \| 'sm' \| 'base' \| 'lg' \| 'xl'` |
| `FormulaTerm` | Generic term-chain model `{ op, key }` used by legacy formula DSL |
| `FormulaTermOp` | `'multiply' \| 'divide' \| 'multiply_complement' \| 'multiply_premium' \| 'multiply_pct'` |
| `TComputedTableElement` | Plate element node — extended with `dataPath`, `label`, `columns`, `footer` for ad-hoc mode |
| `ExtraHandlebarsHelper` | Signature for entries in `extraHelpers` |
| `IHtmlTemplateAiAssistantRenderContext` | Argument passed to `renderAiAssistant` — `{ open, width, onClose, html, data }` |
| `IUseApplyHtmlTemplateResult` | Return shape of `useApplyHtmlTemplate` — `{ html, setHtml, data, setData, tools }` |

## Type Reference

### HandlebarsVariable

| Field | Type | Description |
|-------|------|-------------|
| `name` | `string` | Handlebars expression body (e.g. `customer.name`, `formatCurrency total order.currency`) |
| `label` | `string?` | Human-readable label shown in the picker |
| `description` | `string?` | Short description shown below the label |
| `category` | `string?` | Groups variables in the picker popover; also drives chip color |

### HandlebarsBlockHelper

| Field | Type | Description |
|-------|------|-------------|
| `name` | `string` | Helper name (`if`, `each`, …) |
| `label` | `string?` | Human-readable label |
| `description` | `string?` | Short description |
| `defaultExpression` | `string?` | Pre-filled expression when inserting via the toolbar popover |

### ComputedColumnConfig

| Field | Type | Description |
|-------|------|-------------|
| `key` | `string` | Field name on each row in the bound array |
| `label` | `string` | Header cell text |
| `format` | `ComputedColumnFormat` | Cell rendering / formatting type |
| `visible` | `boolean?` | Initial visibility (default `true`; identifier-shaped keys default to `false`) |
| `align` | `'left' \| 'right' \| 'center'?` | Cell alignment |
| `width` | `string?` | CSS width hint |
| `fontWeight` | `'normal' \| 'bold'?` | Text weight |
| `fontSize` | `'xs' \| 'sm' \| 'base' \| 'lg' \| 'xl'?` | Tailwind text-size token |
| `textColor` | `string?` | Tailwind class, hex, or CSS color string |
| `backgroundColor` | `string?` | Tailwind class, hex, or CSS color string |
| `formatPattern` | `string?` | Optional override format string (e.g. `'DD/MM/YYYY'`) |

### ComputedFooterConfig

| Field | Type | Description |
|-------|------|-------------|
| `key` | `string` | Column key the entry sits under (drives cell placement) |
| `label` | `string` | Footer row label cell text |
| `aggregate` | `ComputedAggregate` | Standard aggregate when `formula` is not set |
| `formula` | `string?` | Raw Handlebars sub-expression (`sumLineExpr items "qty * unitPrice"`) — overrides `aggregate` |
| `formulaFormat` | `ComputedColumnFormat?` | Format wrapper hint for the formula output (defaults to the target column's format) |
| `textColor` | `string?` | Optional row text color |
| `backgroundColor` | `string?` | Optional row background color |

### ComputedColumn (legacy schema)

| Field | Type | Description |
|-------|------|-------------|
| `key` | `string` | Field name on each row dict (`qty`, `unitPrice`, …) |
| `label` | `string` | Header cell text |
| `type` | `ComputedColumnType` | One of `text` / `number` / `currency` / `percent` / `computed` |
| `defaultValue` | `unknown?` | Seeded into new rows |
| `width` | `string?` | CSS width hint (`'72px'`, `'20%'`) |
| `align` | `'left' \| 'right' \| 'center'?` | Cell alignment |
| `step` | `number?` | `step` attr for numeric inputs |
| `min` | `number?` | `min` attr for numeric inputs |
| `max` | `number?` | `max` attr for numeric inputs |
| `compute` | `(row, ctx) => number \| string?` | For `computed` columns: derive the value |
| `format` | `(value, row, ctx) => string?` | Override the default formatter |
| `toggleable` | `boolean?` | Show in the column-toggle dropdown |
| `defaultVisible` | `boolean?` | Initial visibility (default `true`) |

### ComputedFooter (legacy schema)

| Field | Type | Description |
|-------|------|-------------|
| `key` | `string` | Stable id (`subtotal`, `tax`, `grandTotal`) |
| `label` | `string` | Footer label cell text |
| `compute` | `(rows, ctx) => number \| string` | Aggregator over all rows |
| `format` | `(value, ctx) => string?` | Display format override (default: currency) |
| `emphasis` | `'normal' \| 'strong'?` | Visual weight (`strong` = bordered grand-total row) |

### IHtmlTemplateAiAssistantRenderContext

| Field | Type | Description |
|-------|------|-------------|
| `open` | `boolean` | Whether the drawer is currently open |
| `width` | `number` | Width in pixels the drawer animates to when open (mirrors `aiAssistantWidth`) |
| `onClose` | `() => void` | Call from inside the slot to close the drawer |
| `html` | `string` | Current template HTML in the editor |
| `data` | `string` | Current JSON input string in the Data tab |

### ComputedTableSchema (legacy schema)

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | Stable id stored in node JSON to look up the schema at render time |
| `label` | `string` | Short label shown in the insert dropdown |
| `columns` | `ComputedColumn[]` | Column definitions |
| `footer` | `ComputedFooter[]?` | Aggregate footer rows |
| `defaultCurrency` | `string?` | Default currency for new instances |
| `defaultLocale` | `string?` | Default locale for formatting |
| `defaultRows` | `ComputedRow[]?` | Initial rows on first insert (else a single empty row) |
| `labels` | `ComputedTableLabels?` | i18n strings (title / addRow / emptyState / currencyLabel) |
| `currencyOptions` | `ComputedCurrencyOption[]?` | Entries for the in-table currency picker (omit to hide the picker) |

## Components

| Component | Description |
|-----------|-------------|
| `HtmlTemplateEditor` | Main editor component |
| `HandlebarsKit` | Array of all HBS Plate plugins for embedding in a custom editor |
| `DEFAULT_HELPERS` | Default `if / unless / each / with` helper definitions |
| `numberToWordsTR` | Optional Turkish number-to-words Handlebars helper (pass via `extraHelpers`) |
| `useApplyHtmlTemplate` | Hook that owns `html` + `data` state and exposes the `applyHtmlTemplate` client-side tool for `<EditorAgent>` — the tool writes the agent's HTML AND compiles it against the current Data tab JSON, returning a compiled-output preview or a categorized error (data-empty / invalid-json / Handlebars compile failure). See the **AI Assistant slot** section above. |

---

# Image Editor
URL: /docs/web/components/image-editor

An image editor with crop, brightness, saturation, contrast, and hue adjustments, supporting rectangle and circle stencils with zoom controls.

**Demo:**

```tsx
'use client';
// @custom-demo

import { useCallback, useState } from 'react';

// next/image removed — using native <img> in Vite

import { type StencilShape, ImageEditor } from '@docyrus/ui/components/image-editor';
import { cn } from '@docyrus/ui/primitives/lib/utils';

import { type PropControl, PropControls } from '@/components/prop-controls';

const GALLERY_IMAGES = [
  'https://images.unsplash.com/photo-1535930749574-1399327ce78f?w=800&h=600&fit=crop',
  'https://images.unsplash.com/photo-1506744038136-46273834b3fb?w=800&h=600&fit=crop',
  'https://images.unsplash.com/photo-1469474968028-56623f02e42e?w=800&h=600&fit=crop',
  'https://images.unsplash.com/photo-1447752875215-b2761acb3c5d?w=800&h=600&fit=crop'
];

export function ImageEditorDemo() {
  const [selectedIndex, setSelectedIndex] = useState(0);
  const [savedImage, setSavedImage] = useState<string | null>(null);
  const [open, setOpen] = useState(false);

  const [stencilShape, setStencilShape] = useState<StencilShape>('rectangle');
  const [variant, setVariant] = useState<'default' | 'compact'>('default');
  const [size, setSize] = useState<'sm' | 'default' | 'lg'>('default');
  const [aspectRatio, setAspectRatio] = useState(0);
  const [disabled, setDisabled] = useState(false);

  const handleSave = useCallback((dataUrl: string) => {
    setSavedImage(dataUrl);
  }, []);

  const controls: PropControl[] = [
    {
      type: 'select',
      name: 'stencilShape',
      label: 'Stencil Shape',
      value: stencilShape,
      onChange: v => setStencilShape(v as StencilShape),
      options: [{ value: 'rectangle', label: 'Rectangle' }, { value: 'circle', label: 'Circle' }]
    },
    {
      type: 'select',
      name: 'variant',
      label: 'Variant',
      value: variant,
      onChange: v => setVariant(v as 'default' | 'compact'),
      options: [{ value: 'default', label: 'Default' }, { value: 'compact', label: 'Compact' }]
    },
    {
      type: 'select',
      name: 'size',
      label: 'Size',
      value: size,
      onChange: v => setSize(v as 'sm' | 'default' | 'lg'),
      options: [{ value: 'sm', label: 'Small' }, { value: 'default', label: 'Default' }, { value: 'lg', label: 'Large' }]
    },
    {
      type: 'number',
      name: 'aspectRatio',
      label: 'Aspect Ratio',
      value: aspectRatio,
      onChange: setAspectRatio,
      min: 0,
      max: 10,
      placeholder: '0 = free'
    },
    {
      type: 'boolean',
      name: 'disabled',
      label: 'Disabled',
      value: disabled,
      onChange: setDisabled
    }
  ];

  return (
    <div className="w-full">
      <div className="mb-3 flex justify-end">
        <button
          type="button"
          className="inline-flex items-center gap-1.5 rounded-md border border-border bg-background px-3 py-1.5 text-sm font-medium transition-colors hover:bg-accent"
          onClick={() => setOpen(prev => !prev)}>
          <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M12.22 2h-.44a2 2 0 0 0-2 2v.18a2 2 0 0 1-1 1.73l-.43.25a2 2 0 0 1-2 0l-.15-.08a2 2 0 0 0-2.73.73l-.22.38a2 2 0 0 0 .73 2.73l.15.1a2 2 0 0 1 1 1.72v.51a2 2 0 0 1-1 1.74l-.15.09a2 2 0 0 0-.73 2.73l.22.38a2 2 0 0 0 2.73.73l.15-.08a2 2 0 0 1 2 0l.43.25a2 2 0 0 1 1 1.73V20a2 2 0 0 0 2 2h.44a2 2 0 0 0 2-2v-.18a2 2 0 0 1 1-1.73l.43-.25a2 2 0 0 1 2 0l.15.08a2 2 0 0 0 2.73-.73l.22-.39a2 2 0 0 0-.73-2.73l-.15-.08a2 2 0 0 1-1-1.74v-.5a2 2 0 0 1 1-1.74l.15-.09a2 2 0 0 0 .73-2.73l-.22-.38a2 2 0 0 0-2.73-.73l-.15.08a2 2 0 0 1-2 0l-.43-.25a2 2 0 0 1-1-1.73V4a2 2 0 0 0-2-2z" /><circle cx="12" cy="12" r="3" /></svg>
          Configure
          <svg xmlns="http://www.w3.org/2000/svg" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" className={cn('transition-transform duration-200', open && 'rotate-180')}><path d="m6 9 6 6 6-6" /></svg>
        </button>
      </div>

      <div
        className={cn(
          'grid transition-[grid-template-rows] duration-300 ease-in-out',
          open ? 'grid-rows-[1fr]' : 'grid-rows-[0fr]'
        )}>
        <div className="overflow-hidden">
          <div className="mb-4 grid gap-6 rounded-lg border border-border bg-muted/30 p-4">
            
          </div>
        </div>
      </div>

      <div className="space-y-4">
        <ImageEditor
          src={GALLERY_IMAGES[selectedIndex]}
          stencilShape={stencilShape}
          variant={variant}
          size={size}
          aspectRatio={aspectRatio > 0 ? aspectRatio : undefined}
          disabled={disabled}
          onSave={handleSave} />

        <div className="flex gap-2 overflow-x-auto pb-1">
          {GALLERY_IMAGES.map((src, i) => (
            <button
              key={src}
              type="button"
              className={cn(
                'relative shrink-0 overflow-hidden rounded-md border-2 transition-all',
                i === selectedIndex ? 'border-primary ring-2 ring-primary/20' : 'border-transparent opacity-60 hover:opacity-100'
              )}
              onClick={() => {
                setSelectedIndex(i);
                setSavedImage(null);
              }}>
              <img
                src={src}
                alt={`Gallery image ${i + 1}`}
                width={80}
                height={60}
                className="h-14 w-20 object-cover" />
            </button>
          ))}
        </div>

        {savedImage ? (
          <div className="space-y-2">
            <p className="text-xs font-medium text-muted-foreground">Saved result:</p>

            <img
              src={savedImage}
              alt="Edited"
              width={256}
              height={256}
              className="max-h-48 rounded-md border object-contain" />
          </div>
        ) : null}
      </div>
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-image-editor
```

**Dependencies:**
- [react-advanced-cropper](https://www.npmjs.com/package/react-advanced-cropper)
- [advanced-cropper](https://www.npmjs.com/package/advanced-cropper)
- [class-variance-authority](https://www.npmjs.com/package/class-variance-authority)
- [lucide-react](https://www.npmjs.com/package/lucide-react)

## Usage

```tsx
import { ImageEditor } from '@docyrus/ui/components/image-editor';

<ImageEditor
  src="/images/photo.jpg"
  onSave={(dataUrl) => {
    // dataUrl is a base64 canvas export
    console.log('Saved:', dataUrl);
  }}
  onUpload={(file) => {
    console.log('Uploaded:', file.name);
  }}
/>
```

### Circle Crop with Aspect Ratio

```tsx

```

### Compact Variant

```tsx

```

## Variants

| Variant | Description |
|---------|-------------|
| `default` | Standard editor with full border and background. |
| `compact` | Reduced visual weight with subtle border and muted background. |

## Sizes

| Size | Description |
|------|-------------|
| `sm` | Cropper height: 300px. |
| `default` | Cropper height: 400px. |
| `lg` | Cropper height: 500px. |

## API Reference

### ImageEditor

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `src` | `string` | — | Initial image URL to edit. |
| `onSave` | `(dataUrl: string) => void` | — | Called with the base64 canvas data URL on save. |
| `onUpload` | `(file: File) => void` | — | Called when a new file is uploaded via the file input. |
| `disabled` | `boolean` | `false` | Disable all editing interactions. |
| `stencilShape` | `'rectangle' \| 'circle'` | `'rectangle'` | Crop area shape. |
| `aspectRatio` | `number` | — | Enforce a fixed aspect ratio for the crop area. |
| `minCropWidth` | `number` | — | Minimum crop width in pixels. |
| `minCropHeight` | `number` | — | Minimum crop height in pixels. |
| `maxCropWidth` | `number` | — | Maximum crop width in pixels. |
| `maxCropHeight` | `number` | — | Maximum crop height in pixels. |
| `variant` | `'default' \| 'compact'` | `'default'` | Visual style. |
| `size` | `'sm' \| 'default' \| 'lg'` | `'default'` | Cropper area height. |
| `className` | `string` | — | Additional CSS classes. |

## Type Reference

### EditorMode

`'crop'` | `'brightness'` | `'saturation'` | `'contrast'` | `'hue'`

The active editing mode. The toolbar switches between crop and adjustment sliders based on this value.

### StencilShape

`'rectangle'` | `'circle'`

Determines the crop stencil shape. Circle mode renders a circular crop area.

### Adjustments

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `brightness` | `number` | `0` | Brightness adjustment (0–100 scale). |
| `saturation` | `number` | `0` | Saturation adjustment (0–100 scale). |
| `hue` | `number` | `0` | Hue rotation (0–100 scale). |
| `contrast` | `number` | `0` | Contrast adjustment (0–100 scale). |

### Editor Controls

| Control | Action |
|---------|--------|
| Crop mode | Drag to select crop area, resize handles to adjust. |
| Adjustment sliders | Drag slider to adjust brightness/saturation/hue/contrast. |
| Zoom in/out | Buttons to zoom the image (1.25x step). |
| Upload | Opens file picker for a new image. |
| Reset | Returns to crop mode with default adjustments. |
| Save | Exports the cropped + adjusted result as a data URL. |

---

# Overview
URL: /docs/web/components

General-purpose UI components built with React, TypeScript, Tailwind CSS v4, and CVA variants.

Browse all available Docyrus UI components.

## Available Components

| Component | Description |
|-----------|-------------|
| [Avatar Select](/docs/web/components/avatar-select) | Avatar Select component with multiple variants and sizes. |
| [Avatar Thumbnail](/docs/web/components/avatar-thumbnail) | Avatar Thumbnail component with multiple variants and sizes. |
| [Awesome Card](/docs/web/components/awesome-card) | A card with a hatched-stripe header and an inset content area, perfect for displaying stats and metrics. |
| [Confirmation Button](/docs/web/components/confirmation-button) | Confirmation Button component with multiple variants and sizes. |
| [Create Record Dialog](/docs/web/components/create-record-dialog) | Create Record Dialog component with multiple variants and sizes. |
| [Data Grid View Select](/docs/web/components/data-grid-view-select) | A view selector with integrated view editor for DataGrid. Supports dropdown, horizontal-tabs, and vertical-tabs variants with full CRUD operations on saved views. |
| [Date Time Picker](/docs/web/components/date-time-picker) | Date Time Picker component with multiple variants and sizes. |
| [Date Time Range Picker](/docs/web/components/date-time-range-picker) | Date Time Range Picker component with multiple variants and sizes. |
| [Day Picker](/docs/web/components/day-picker) | Day Picker component with multiple variants and sizes. |
| [Delete Confirm Dialog](/docs/web/components/delete-confirm-dialog) | Delete Confirm Dialog component with multiple variants and sizes. |
| [Docyrus Data Source Picker](/docs/web/components/docyrus-data-source-picker) | Docyrus Data Source Picker component with multiple variants and sizes. |
| [Duration Select](/docs/web/components/duration-select) | Duration Select component with multiple variants and sizes. |
| [Editable Record Detail](/docs/web/components/editable-record-detail) | Inline record editing with change tracking, validation, hidden fields, and a floating action bar. |
| [Editable Value](/docs/web/components/editable-value) | Inline editable field with display/edit mode switching, popover auto-open, and change tracking. |
| [Instant Message Composer](/docs/web/components/instant-message-composer) | Composer for SMS and WhatsApp with channel switching, recipient chips, attachments, and SMS character counting. |
| [Json Schema Form](/docs/web/components/json-schema-form) | Json Schema Form component with multiple variants and sizes. |
| [Kanban](/docs/web/components/kanban) | A drag-and-drop kanban board with sortable columns and items, column reordering, overlay previews, and final drop zones for archiving or completing tasks. |
| [Map](/docs/web/components/map) | Interactive map component built on Leaflet with SSR-safe lazy loading, theme-aware tiles, marker clustering, drawing tools, custom controls, and geolocation. |
| [Morph Popover](/docs/web/components/morph-popover) | Morph Popover component with multiple variants and sizes. |
| [Notifications Panel](/docs/web/components/notifications-panel) | Notifications Panel component with multiple variants and sizes. |
| [Place Autocomplete](/docs/web/components/place-autocomplete) | Place Autocomplete component with multiple variants and sizes. |
| [Radio Group](/docs/web/components/radio-group) | Radio Group component with multiple variants and sizes. |
| [Schema Repeater](/docs/web/components/schema-repeater) | Schema Repeater component with multiple variants and sizes. |
| [Search Input](/docs/web/components/search-input) | Search Input component with multiple variants and sizes. |
| [Simple Markdown Editor](/docs/web/components/simple-markdown-editor) | Simple Markdown Editor component with multiple variants and sizes. |
| [Timeline](/docs/web/components/timeline) | Vertical timeline with status indicators, alternate layout, animated entrance, and custom content slots. |
| [Tree Select](/docs/web/components/tree-select) | A select dropdown backed by a tree. Single mode renders like Select; multi mode renders like Tag Select. Hierarchical search, expand-all and parent-cascade checking come from the embedded Tree View. |
| [Tree Table](/docs/web/components/tree-table) | Tree Table component with multiple variants and sizes. |
| [Tree View](/docs/web/components/tree-view) | Tree View component with multiple variants and sizes. |
| [Adaptive Card](/docs/web/components/adaptive-card) | Renderer for Microsoft's Adaptive Cards 1.5 schema. Surfaces LLM-generated and Microsoft Teams payloads as native Docyrus UI with stateful inputs, validation, nested ShowCards, and action dispatch. |
| [Adaptive Card Designer](/docs/web/components/adaptive-card-designer) | Visual drag-and-drop designer for Microsoft Adaptive Cards 1.5 / 1.6 payloads. Three-pane editor (toolbox · canvas · structure / properties) with paired JSON editors, live preview, undo / redo, and theme / width controls — backed by the in-repo Adaptive Card renderer. |
| [Awesome Dialog](/docs/web/components/awesome-dialog) | Awesome Dialog component. |
| [Awesome Stats](/docs/web/components/awesome-stats) | Data-driven metric cards with grid, flex, and animated tabs layouts. |
| [Calendar](/docs/web/components/calendar) | Calendar component. |
| [Comments Panel](/docs/web/components/comments-panel) | Comments Panel component. |
| [Contact Activity Panel](/docs/web/components/contact-activity-panel) | A presentational record-activity timeline. Pair it with useDocyrusContactActivity to wire it to the Docyrus backend. |
| [Contact Channels Field](/docs/web/components/contact-channels-field) | A backend-agnostic, fully controlled editor for a record's contact channels, their consent cache and validation status. |
| [Data Gallery](/docs/web/components/data-gallery) | A standalone, virtualized card gallery view for record lists. Toolbar-driven card design (variant, cover style, density, field bindings) plus full TanStack Table integration for sorting, filtering, grouping, and saved views. |
| [Data Grid](/docs/web/components/data-grid) | A virtualized, editable spreadsheet-like data grid with sorting, filtering, grouping, cell selection, and keyboard navigation. |
| [Data Import Wizard](/docs/web/components/data-import-wizard) | Multi-step modal wizard that turns an Excel/CSV upload into Docyrus data source records — drag-drop, auto-mapped column→field assignment, per-type config, value-renderer preview, and a result summary. |
| [Data Table](/docs/web/components/data-table) | A lightweight, read-only TanStack table for Docyrus data sources with value renderers, row selection, grouping, and optional pagination. |
| [Data Table Filter](/docs/web/components/data-table-filter) | A composable filter bar for data tables with text, number, date, option, and multi-option column types. |
| [Data Table Side Filters](/docs/web/components/data-table-side-filters) | An always-visible side filter panel for e-commerce-style listings — covers every Docyrus field type and emits the same RuleGroupType JSON as the Query Builder. |
| [Dummy Data Generator](/docs/web/components/dummy-data-generator) | Multi-step modal wizard that generates Docyrus-compatible sample records — per-field strategies (text/number/date/enum/relation), value-renderer preview, and an opt-in batch save to the data source. |
| [Editor Agent](/docs/web/components/editor-agent) | Editor Agent component. |
| [Email Composer](/docs/web/components/email-composer) | Rich text email composer with sender-account picker, formatting toolbar, recipients, attachments, and i18n support. |
| [Email Template Editor](/docs/web/components/email-template-editor) | A standalone, beehiiv-style email template editor built on PlateJS. A rich block canvas with a "+"/slash insert palette and merge-tag chips, a full Theme panel (Basic + Advanced) that live-styles every part of the email via CSS variables, email-safe HTML serialization, and a multi-provider preview simulator (Gmail / Outlook / Apple Mail / Mobile / Dark). |
| [Emoji Picker](/docs/web/components/emoji-picker) | A searchable, category-tabbed emoji picker with skin-tone selection and recently-used memory, built on the emoji-mart dataset. |
| [Enum Option Editor](/docs/web/components/enum-option-editor) | Enum Option Editor component. |
| [File Attachment Panel](/docs/web/components/file-attachment-panel) | File Attachment Panel component. |
| [Form Builder](/docs/web/components/form-builder) | A drag-and-drop form designer with a field palette, canvas, properties panel, live preview and code export for TanStack Form, React Hook Form, Zod and raw useState. |
| [Form Fields](/docs/web/components/form-fields) | Dynamic form field system powered by TanStack Form. 49 field types with automatic dispatch via DynamicFormField. |
| [Gantt](/docs/web/components/gantt) | A Gantt chart component with drag-and-drop task scheduling, timeline zoom, custom markers, and sidebar navigation. |
| [Handlebars Editor](/docs/web/components/handlebars-editor) | A three-pane workbench for writing and rendering Handlebars templates — a JSON input pane, a template editor with IntelliSense, and a live output pane with HTML preview. |
| [Html Template Editor](/docs/web/components/html-template-editor) | WYSIWYG document editor for authoring Handlebars-aware HTML templates (quotes, invoices, reports). Word-style A4 page surface, four tabs (Visual / Code / Data / Preview), variable & helper chips, slash-style triggers, and a data-driven Table dialog where users discover JSON paths, configure columns, and write free-form sum / aggregate expressions per row. |
| [Image Editor](/docs/web/components/image-editor) | An image editor with crop, brightness, saturation, contrast, and hue adjustments, supporting rectangle and circle stencils with zoom controls. |
| [Json Schema Designer](/docs/web/components/json-schema-designer) | A row-based JSON Schema designer ported from extend-hq's schema-builder. Edit property name, type, description and enum values inline; add children directly from each container; preview the live JSON Schema in the side tab. |
| [Jsonata Editor](/docs/web/components/jsonata-editor) | A three-pane workbench for writing and evaluating JSONata expressions — a JSON input pane, an expression editor with IntelliSense, and a live result pane. |
| [Log Activity Form](/docs/web/components/log-activity-form) | A presentational multi-tab "log activity" composer — comment, email, call, meeting, task, and status — with every tab rendered inline, wired to Docyrus via the useDocyrusLogActivity hook. |
| [Mega Select](/docs/web/components/mega-select) | Mega Select component. |
| [Notification Stack](/docs/web/components/notification-stack) | A stacked notification card system with swipe-to-dismiss gestures, auto-pagination, action buttons, and animated transitions. |
| [Pivot Calendar](/docs/web/components/pivot-calendar) | Calendar component that pivots time-based statistics across four layouts — full month, days of a week, days of a month, or months of a year — with grouping, tooltips, and local or remote aggregation. |
| [Pivot Filter](/docs/web/components/pivot-filter) | Horizontal or vertical strip of count-tagged pills used to quickly slice a list by one dimension — status, user, date bucket, or any other categorical value. |
| [Pivot Grid](/docs/web/components/pivot-grid) | A standalone pivot grid with 3-level row and column hierarchies, subtotals, grand totals, drilldown, pinning, resizing, and export. |
| [Pricing Engine Panel](/docs/web/components/pricing-engine-panel) | Pricing Engine Panel component. |
| [Query Builder](/docs/web/components/query-builder) | Query Builder component. |
| [Record Activity Panel](/docs/web/components/record-activity-panel) | Record Activity Panel component. |
| [Record Delete Confirm Dialog](/docs/web/components/record-delete-confirm-dialog) | Record Delete Confirm Dialog component. |
| [Record Sharing](/docs/web/components/record-sharing) | Record Sharing component. |
| [Resource Scheduler Panel](/docs/web/components/resource-scheduler-panel) | Resource Scheduler Panel component. |
| [Stepper](/docs/web/components/stepper) | A multi-step progress indicator with 6 visual variants, horizontal/vertical orientation, animated transitions, and customizable step icons. |
| [Team Chat Channel](/docs/web/components/team-chat-channel) | Team Chat Channel component. |
| [Time Slot Scheduler](/docs/web/components/time-slot-scheduler) | Time Slot Scheduler component. |
| [Value Renderers](/docs/web/components/value-renderers) | Read-only value display system for table cells, detail views, and kanban cards. 44 renderer types with automatic dispatch via DynamicValue. |

---

# Instant Message Composer
URL: /docs/web/components/instant-message-composer

Composer for SMS and WhatsApp with channel switching, recipient chips, attachments, and SMS character counting.

**Demo:**

```tsx
'use client';

import { useCallback, useState } from 'react';

import {
  InstantMessageComposer,
  type InstantMessageAttachment,
  type InstantMessageChannel,
  type InstantMessageComposerSize,
  type InstantMessageComposerVariant
} from '@docyrus/ui/components/instant-message-composer';
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue
} from '@docyrus/ui/primitives/ui/select';
import { Switch } from '@docyrus/ui/primitives/ui/switch';
import { cn } from '@docyrus/ui/primitives/lib/utils';

const SAMPLE_BODIES: Record
                  
                    
                    
                  
                
              </div>
              <div className="space-y-1.5">
                <span className="text-xs font-medium">Size</span>
                
                  
                    
                    
                  
                
              </div>
              <div className="space-y-1.5">
                <span className="text-xs font-medium">Channel</span>
                
                  
                    
                  
                
              </div>
              <label className="flex items-center gap-2">
                
                <span className="text-xs">Disabled</span>
              </label>
            </div>
          </div>
        </div>
      </div>
      <div className="mx-auto max-w-2xl">
        
      </div>
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-instant-message-composer
```

**Dependencies:**
- [lucide-react](https://www.npmjs.com/package/lucide-react)
- [class-variance-authority](https://www.npmjs.com/package/class-variance-authority)

## Usage

```tsx
import {
  InstantMessageComposer,
  type InstantMessageChannel
} from "@docyrus/ui/components/instant-message-composer";

<InstantMessageComposer
  variant="default"
  size="default"
  channel="sms"
  onChannelChange={(channel) => {}}
  recipients={['+15551234567']}
  onRecipientsChange={(recipients) => {}}
  body="Hello!"
  onBodyChange={(body) => {}}
  onSend={() => {}}
  onAttach={() => {}}
  onDiscard={() => {}}
/>
```

The composer is fully controlled. The send button is enabled once at least one
valid phone number is entered and the body (or an attachment, on WhatsApp) is
non-empty. Phone numbers are validated against a permissive E.164-style regex
(6–18 digits, optional `+` prefix, common separators allowed); invalid chips are
shown with a destructive style so users can correct them before sending.

### Channels

The composer renders a small SMS / WhatsApp segmented switcher above the
recipients row. Pass `availableChannels` to limit the choices, or omit
`onChannelChange` to lock the composer to a single channel.

```tsx
// Lock to WhatsApp only

```

### SMS character counting

When `channel="sms"`, the footer shows a live character counter and segment
estimate (`160 chars · 1 SMS`). Concatenated SMS uses 153 characters per
segment to account for UDH overhead. The body is also clamped to `maxLength`
(default `1600` for SMS, unlimited for WhatsApp). Pass an explicit number to
override, or `null` to remove the limit.

### WhatsApp formatting

WhatsApp messages support inline formatting using their native syntax —
`*bold*`, `_italic_`, `~strike~`, and `` ```mono``` ``. The composer hints
this under the body when the WhatsApp channel is active. Attachments and the
attach button are only shown for the WhatsApp channel.

## Variants

| Variant | Description |
|---------|-------------|
| `default` | Default style with input border and shadow |
| `outline` | Outline border, no shadow |
| `minimal` | No border or shadow — for embedding in other surfaces (dialogs, sheets) |

## Sizes

| Size | Description |
|------|-------------|
| `sm` | Small — compact text and shorter body min-height |
| `default` | Default — comfortable text and 150px min body |
| `lg` | Large — bigger text and taller body min-height |

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `variant` | `"default"` \| `"outline"` \| `"minimal"` | `"default"` | Visual style |
| `size` | `"sm"` \| `"default"` \| `"lg"` | `"default"` | Sizing scale |
| `channel` | `InstantMessageChannel` | — | Active channel: `'sms'` or `'whatsapp'`. Required. |
| `onChannelChange` | `(channel: InstantMessageChannel) => void` | — | Called when the user switches channels. Omit to lock the channel. |
| `availableChannels` | `ReadonlyArray<InstantMessageChannel>` | `['sms', 'whatsapp']` | Channels offered in the segmented switcher |
| `recipients` | `string[]` | — | Recipient phone numbers (chip list). Required. |
| `onRecipientsChange` | `(recipients: string[]) => void` | — | Called when chips are added/removed/pasted |
| `body` | `string` | — | Plain-text message body. Required. |
| `onBodyChange` | `(body: string) => void` | — | Called when the body changes |
| `onSend` | `() => void` | — | Fired when the user clicks Send |
| `onAttach` | `() => void` | — | Fired when the user clicks the paperclip (WhatsApp only) |
| `onDiscard` | `() => void` | — | Fired when the user clicks Cancel |
| `sending` | `boolean` | `false` | Shows a spinner on the send button and disables interactions |
| `disabled` | `boolean` | `false` | Disables all inputs and actions |
| `attachments` | `InstantMessageAttachment[]` | — | List of attached files (WhatsApp only) |
| `onRemoveAttachment` | `(index: number) => void` | — | Called when an attachment chip is removed |
| `maxLength` | `number \| null` | `1600` for SMS, no limit for WhatsApp | Hard cap on body length. Pass `null` to remove the limit. |
| `helper` | `ReactNode` | — | Optional helper rendered between the recipients row and the body |
| `className` | `string` | — | Extra classes for the root |

## Type Exports

| Type | Description |
|------|-------------|
| `InstantMessageComposerProps` | Props for the composer |
| `InstantMessageComposerVariant` | `'default' \| 'outline' \| 'minimal'` |
| `InstantMessageComposerSize` | `'sm' \| 'default' \| 'lg'` |
| `InstantMessageChannel` | `'sms' \| 'whatsapp'` |
| `InstantMessageAttachment` | `{ name: string; size: number }` |

## Recipe: Sending to a contact selection

Pull recipients out of a row selection (data grid, list, etc.) and feed them
into the composer as the initial chip list. Treat the controlled
`recipients` prop as the source of truth so users can still tweak the chips
in the dialog before pressing Send.

```tsx
const selectedContacts = useSelectedContacts();
const phones = useMemo(
  () => Array.from(new Set(
    selectedContacts.map(c => c.mobile?.trim()).filter((p): p is string => Boolean(p))
  )),
  [selectedContacts]
);

const [recipients, setRecipients] = useState(phones);
const [body, setBody] = useState('');
const [channel, setChannel] = useState<InstantMessageChannel>('sms');

return (
  <InstantMessageComposer
    variant="minimal"
    channel={channel}
    onChannelChange={setChannel}
    recipients={recipients}
    onRecipientsChange={setRecipients}
    body={body}
    onBodyChange={setBody}
    onSend={() => sendMessage({ channel, recipients, body })} />
);
```

---

# Json Schema Designer
URL: /docs/web/components/json-schema-designer

A row-based JSON Schema designer ported from extend-hq's schema-builder. Edit property name, type, description and enum values inline; add children directly from each container; preview the live JSON Schema in the side tab.

**Demo:**

```tsx
'use client';

import { useState } from 'react';

import { JsonSchemaDesigner, type JsonSchema } from '@docyrus/ui/components/json-schema-designer';
import { Button } from '@docyrus/ui/primitives/ui/button';
import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogHeader,
  DialogTitle
} from '@docyrus/ui/primitives/ui/dialog';
import { FileJson, Plus } from 'lucide-react';

const SAMPLE_SCHEMA: JsonSchema = {
  $schema: 'https://json-schema.org/draft/2020-12/schema',
  type: 'object',
  title: 'User Profile',
  description: 'A registered platform user.',
  properties: {
    id: { type: 'string', format: 'uuid', description: 'Unique identifier' },
    email: { type: 'string', format: 'email' },
    fullName: { type: 'string', minLength: 1, maxLength: 120 },
    age: { type: 'integer', minimum: 0, maximum: 130 },
    role: {
      type: 'string',
      enum: ['admin', 'editor', 'viewer'],
      default: 'viewer'
    },
    isActive: { type: 'boolean', default: true },
    address: {
      type: 'object',
      properties: {
        street: { type: 'string' },
        city: { type: 'string' },
        postalCode: { type: 'string', pattern: '^[0-9]{5}

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-json-schema-designer
```

**Dependencies:**
- [@dnd-kit/core](https://www.npmjs.com/package/@dnd-kit/core)
- [@dnd-kit/sortable](https://www.npmjs.com/package/@dnd-kit/sortable)
- [@dnd-kit/utilities](https://www.npmjs.com/package/@dnd-kit/utilities)
- [lucide-react](https://www.npmjs.com/package/lucide-react)

## Overview

`JsonSchemaDesigner` is a visual editor for [JSON Schema](https://json-schema.org/)
(Draft 2020-12 / Draft-07 compatible) based on extend-hq's
[schema-builder](https://ui.extend.ai/ui/docs/components/schema-builder)
pattern. The UI is a single-pane editable table — there is no separate
toolbox, no drag-from-palette, no right-side properties inspector.

| Surface | Role |
|---------|------|
| **Form tab** | An inline editable table. Each property is a row with name, type, description and (when relevant) a nested sub-table for object / array / enum content. `+ Add property` lives at the bottom of every container. |
| **JSON tab** | A read-only `<pre>` view of the live JSON Schema output. |
| **Toolbar** | Strict Mode switch, Clear, and an AI Assistant toggle when `renderAiAssistant` is wired. |

It both **renders / edits existing schemas** (pass `value` or `defaultValue`)
and lets you **design new schemas from scratch**.

## Features

- **Row-based editing** — property name, type and description live in the row itself. No popouts.
- **Inline type select** — a dropdown with the scalar JSON types plus `object`, `array` (with a nested type sub-menu) and `enum`.
- **Nested containers** — object properties expand into a sub-table below the row; array `items` (including `array<object>` and `array<enum>`) get the same treatment.
- **Enum editor** — string-with-enum + enum-of-arrays both surface a per-value description list.
- **`+ Add property` everywhere** — at the bottom of the root, of each object, and of each array-of-object.
- **Drag-handle reorder** — within a container, properties can be sorted via the handle on the left of each row (powered by `@dnd-kit`).
- **Strict Mode** — a single toolbar switch flips the output between "no required arrays" and "OpenAI Structured Outputs strict-mode rules" (`additionalProperties: false` + every key in `required[]`).
- **Controlled or uncontrolled** — works with `value` + `onChange` or `defaultValue`.
- **Read-only mode** — turns the designer into a schema viewer.

> **What changed from the previous version**
>
> The legacy three-pane drag-drop UI (left Toolbox, center Tree-View, right
> Item Properties) was replaced. Per-property **required** toggle, type-specific
> validation constraints (`minLength`, `pattern`, `minimum`, …), per-property
> `default` and `format`, and the **Undo / redo** history are no longer
> surfaced — they collapsed into the row-based UX. The `DesignerProvider`,
> `useDesignerContext`, `schemaToTree` and `treeToSchema` exports remain for
> any consumer that built a custom panel on top of the legacy state model.

## Usage

```tsx
import { JsonSchemaDesigner } from "@docyrus/ui/components/json-schema-designer";

export function SchemaPage() {
  return (
    <div className="h-[680px]">
      
    </div>
  );
}
```

The component has a default height of `640px`. Pass a `className` with an
explicit height (e.g. `h-[720px]` or `h-full` inside a sized parent) to
override it.

### Editing an existing schema

Pass `defaultValue` for uncontrolled use — the schema is imported into the tree
once on mount:

```tsx

```

### Controlled mode

Pass `value` + `onChange` to drive the schema from your own state. `onChange`
fires with the full JSON Schema document after every edit:

```tsx
import { useState } from "react";
import {
  JsonSchemaDesigner,
  type JsonSchema
} from "@docyrus/ui/components/json-schema-designer";

function ControlledDesigner() {
  const [schema, setSchema] = useState

      
          
          <div className="min-h-0 flex-1">
            
          </div>
        
      
    </>
  );
}
```

### Conversion helpers

The package exports pure helpers for converting between JSON Schema documents
and the designer's internal node tree — useful for persistence or building a
custom UI on top of `DesignerProvider` / `useDesignerContext`.

```tsx
import {
  schemaToTree,
  treeToSchema,
  treeToJsonString,
  parseJsonToTree
} from "@docyrus/ui/components/json-schema-designer";

const tree = schemaToTree({ type: "object", properties: { id: { type: "string" } } });
const schema = treeToSchema(tree);
const json = treeToJsonString(tree);

const result = parseJsonToTree('{"type":"object"}');
if ("error" in result) console.error(result.error);
else console.log(result.root);
```

## Supported keywords

The new row-based UI is intentionally narrow. It maps onto the subset of
JSON Schema that covers ~90% of agent / LLM authoring scenarios:

| Group | Keywords surfaced in the UI |
|-------|------------------------------|
| Identity | `type`, `description` |
| Object | `properties`, `required` (derived from Strict Mode), `additionalProperties` (derived from Strict Mode) |
| Array | `items` (scalar, object, or enum) |
| Enum | `enum` (always under a `string` carrier), `enumDescriptions` per-value description |

`title`, `default`, `format`, `minLength`/`maxLength`/`pattern`,
`minimum`/`maximum`/`multipleOf`, `minItems`/`maxItems`/`uniqueItems`, and
per-property `required` flags are **not** part of the row UI. Pass a
controlled `value` containing those keywords and they are silently dropped
on the next round-trip (the inbound document parses, the outbound emit only
re-emits what the UI tracks). If you need them, drive the schema externally
and treat the designer as a read-only authoring surface.

## EditorAgent integration

Pair `useApplyJsonSchema` with `renderAiAssistant` to let an LLM author JSON Schema documents. The hook owns the designer's controlled `schema` + `strictMode` state, ships an `applyJsonSchema` tool (which runs strict-mode validation and reports violations for self-correction) AND a `buildEditorContext()` helper that emits the current strict-mode flag plus an authoring hint into the system prompt.

```tsx
import { EditorAgent } from '@docyrus/ui/components/editor-agent';
import { JsonSchemaDesigner, useApplyJsonSchema } from '@docyrus/ui/components/json-schema-designer';

export function JsonSchemaPlayground({ client, user, agentId }) {
  const jsonSchema = useApplyJsonSchema();
  const [aiOpen, setAiOpen] = useState(false);

  return (
    
      

      
            
          

          <div className="min-h-0 flex-1">
            
          </div>
        
      
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-json-schema-designer
```

**Dependencies:**
- [@dnd-kit/core](https://www.npmjs.com/package/@dnd-kit/core)
- [@dnd-kit/sortable](https://www.npmjs.com/package/@dnd-kit/sortable)
- [@dnd-kit/utilities](https://www.npmjs.com/package/@dnd-kit/utilities)
- [lucide-react](https://www.npmjs.com/package/lucide-react)

## Overview

`JsonSchemaDesigner` is a visual editor for [JSON Schema](https://json-schema.org/)
(Draft 2020-12 / Draft-07 compatible) based on extend-hq's
[schema-builder](https://ui.extend.ai/ui/docs/components/schema-builder)
pattern. The UI is a single-pane editable table — there is no separate
toolbox, no drag-from-palette, no right-side properties inspector.

| Surface | Role |
|---------|------|
| **Form tab** | An inline editable table. Each property is a row with name, type, description and (when relevant) a nested sub-table for object / array / enum content. `+ Add property` lives at the bottom of every container. |
| **JSON tab** | A read-only `<pre>` view of the live JSON Schema output. |
| **Toolbar** | Strict Mode switch, Clear, and an AI Assistant toggle when `renderAiAssistant` is wired. |

It both **renders / edits existing schemas** (pass `value` or `defaultValue`)
and lets you **design new schemas from scratch**.

## Features

- **Row-based editing** — property name, type and description live in the row itself. No popouts.
- **Inline type select** — a dropdown with the scalar JSON types plus `object`, `array` (with a nested type sub-menu) and `enum`.
- **Nested containers** — object properties expand into a sub-table below the row; array `items` (including `array<object>` and `array<enum>`) get the same treatment.
- **Enum editor** — string-with-enum + enum-of-arrays both surface a per-value description list.
- **`+ Add property` everywhere** — at the bottom of the root, of each object, and of each array-of-object.
- **Drag-handle reorder** — within a container, properties can be sorted via the handle on the left of each row (powered by `@dnd-kit`).
- **Strict Mode** — a single toolbar switch flips the output between "no required arrays" and "OpenAI Structured Outputs strict-mode rules" (`additionalProperties: false` + every key in `required[]`).
- **Controlled or uncontrolled** — works with `value` + `onChange` or `defaultValue`.
- **Read-only mode** — turns the designer into a schema viewer.

> **What changed from the previous version**
>
> The legacy three-pane drag-drop UI (left Toolbox, center Tree-View, right
> Item Properties) was replaced. Per-property **required** toggle, type-specific
> validation constraints (`minLength`, `pattern`, `minimum`, …), per-property
> `default` and `format`, and the **Undo / redo** history are no longer
> surfaced — they collapsed into the row-based UX. The `DesignerProvider`,
> `useDesignerContext`, `schemaToTree` and `treeToSchema` exports remain for
> any consumer that built a custom panel on top of the legacy state model.

## Usage

```tsx
import { JsonSchemaDesigner } from "@docyrus/ui/components/json-schema-designer";

export function SchemaPage() {
  return (
    <div className="h-[680px]">
      
    </div>
  );
}
```

The component has a default height of `640px`. Pass a `className` with an
explicit height (e.g. `h-[720px]` or `h-full` inside a sized parent) to
override it.

### Editing an existing schema

Pass `defaultValue` for uncontrolled use — the schema is imported into the tree
once on mount:

```tsx

```

### Controlled mode

Pass `value` + `onChange` to drive the schema from your own state. `onChange`
fires with the full JSON Schema document after every edit:

```tsx
import { useState } from "react";
import {
  JsonSchemaDesigner,
  type JsonSchema
} from "@docyrus/ui/components/json-schema-designer";

function ControlledDesigner() {
  const [schema, setSchema] = useState

      
          
          <div className="min-h-0 flex-1">
            
          </div>
        
      
    </>
  );
}
```

### Conversion helpers

The package exports pure helpers for converting between JSON Schema documents
and the designer's internal node tree — useful for persistence or building a
custom UI on top of `DesignerProvider` / `useDesignerContext`.

```tsx
import {
  schemaToTree,
  treeToSchema,
  treeToJsonString,
  parseJsonToTree
} from "@docyrus/ui/components/json-schema-designer";

const tree = schemaToTree({ type: "object", properties: { id: { type: "string" } } });
const schema = treeToSchema(tree);
const json = treeToJsonString(tree);

const result = parseJsonToTree('{"type":"object"}');
if ("error" in result) console.error(result.error);
else console.log(result.root);
```

## Supported keywords

The new row-based UI is intentionally narrow. It maps onto the subset of
JSON Schema that covers ~90% of agent / LLM authoring scenarios:

| Group | Keywords surfaced in the UI |
|-------|------------------------------|
| Identity | `type`, `description` |
| Object | `properties`, `required` (derived from Strict Mode), `additionalProperties` (derived from Strict Mode) |
| Array | `items` (scalar, object, or enum) |
| Enum | `enum` (always under a `string` carrier), `enumDescriptions` per-value description |

`title`, `default`, `format`, `minLength`/`maxLength`/`pattern`,
`minimum`/`maximum`/`multipleOf`, `minItems`/`maxItems`/`uniqueItems`, and
per-property `required` flags are **not** part of the row UI. Pass a
controlled `value` containing those keywords and they are silently dropped
on the next round-trip (the inbound document parses, the outbound emit only
re-emits what the UI tracks). If you need them, drive the schema externally
and treat the designer as a read-only authoring surface.

## EditorAgent integration

Pair `useApplyJsonSchema` with `renderAiAssistant` to let an LLM author JSON Schema documents. The hook owns the designer's controlled `schema` + `strictMode` state, ships an `applyJsonSchema` tool (which runs strict-mode validation and reports violations for self-correction) AND a `buildEditorContext()` helper that emits the current strict-mode flag plus an authoring hint into the system prompt.

```tsx
import { EditorAgent } from '@docyrus/ui/components/editor-agent';
import { JsonSchemaDesigner, useApplyJsonSchema } from '@docyrus/ui/components/json-schema-designer';

export function JsonSchemaPlayground({ client, user, agentId }) {
  const jsonSchema = useApplyJsonSchema();
  const [aiOpen, setAiOpen] = useState(false);

  return (
    <JsonSchemaDesigner
      value={jsonSchema.schema ?? undefined}
      onChange={jsonSchema.setSchema}
      onStrictModeChange={jsonSchema.setStrictMode}
      aiAssistantOpen={aiOpen}
      onAiAssistantOpenChange={setAiOpen}
      renderAiAssistant={({ open, onClose }) => (
        
      )}
    />
  );
}
```

The matching backend agent must register a tool named `applyJsonSchema` whose input schema mirrors `{ schema: object (required), explanation?: string }`.

## API Reference

### JsonSchemaDesigner

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `JsonSchema` | — | Controlled JSON Schema document. Re-imports the tree when it changes externally. |
| `defaultValue` | `JsonSchema` | — | Initial JSON Schema for uncontrolled use. |
| `onChange` | `(schema: JsonSchema) => void` | — | Called with the updated JSON Schema after every edit. |
| `readOnly` | `boolean` | `false` | Disables all editing — the designer becomes a viewer. |
| `defaultStrictMode` | `boolean` | `false` | Initial state of the **Strict Mode** switch (OpenAI Structured Outputs rules). |
| `onStrictModeChange` | `(strictMode: boolean) => void` | — | Fires when the user toggles the **Strict Mode** switch. |
| `title` | `string` | `'JSON Schema'` | Header title. |
| `className` | `string` | — | Extra classes for the root container (overrides the default `640px` height). |
| `aiAssistantOpen` | `boolean` | — | Controlled open state for the AI Assistant drawer. When provided the designer stops managing the open state internally — pair with `onAiAssistantOpenChange`. |
| `onAiAssistantOpenChange` | `(open: boolean) => void` | — | Fired when the AI Assistant toolbar button toggles the drawer. |
| `renderAiAssistant` | `(ctx: IJsonSchemaAiAssistantRenderContext) => ReactNode` | — | Mounts a custom AI Assistant drawer body. When set, the toolbar shows a Bot toggle that opens/closes the drawer; the render fn receives the live schema + strict-mode state. |

### DesignerProvider

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode` | — | Wrapped subtree. |
| `value` | `JsonSchema` | — | Controlled JSON Schema document. |
| `defaultValue` | `JsonSchema` | — | Initial JSON Schema for uncontrolled use. |
| `onChange` | `(schema: JsonSchema) => void` | — | Fired with the updated JSON Schema after every edit. |
| `readOnly` | `boolean` | `false` | Disables editing for all descendants. |
| `defaultStrictMode` | `boolean` | `false` | Initial state of the Strict Mode switch. |

## Exports

| Export | Description |
|--------|-------------|
| `JsonSchemaDesigner` | The row-based designer component. |
| `useApplyJsonSchema` | Owns the controlled `schema` + `strictMode` state and ships the `applyJsonSchema` client-side tool for `<EditorAgent>`. Adds strict-mode validation so the agent can iterate to compliance, and exposes `buildEditorContext()` returning a strict-mode-aware system-prompt snippet. See **EditorAgent integration** below. |
| `DesignerProvider` | Legacy state provider — kept for consumers that built a custom panel on top of `useDesignerContext`. **Not wired** into the new row-based UI; the designer manages its own internal state instead. |
| `useDesignerContext` | Legacy hook to read / mutate the old reducer-backed state inside a `DesignerProvider`. |
| `schemaToTree` | Convert a JSON Schema document into the legacy node tree. |
| `treeToSchema` | Convert a node tree into a JSON Schema document. |
| `treeToJsonString` | Serialize a node tree to a pretty-printed JSON string. |
| `parseJsonToTree` | Parse a JSON string into a node tree (or return an `error`). |
| `DEFAULT_SCHEMA_DIALECT` | The default `$schema` dialect URI. |
| `TOOLBOX_ITEMS` | Legacy palette type entries — no longer surfaced by the row-based UI. |
| `TOOLBOX_CATEGORIES` | Legacy palette category names. |

## Type Exports

| Type | Description |
|------|-------------|
| `JsonSchemaDesignerProps` | Props for the `JsonSchemaDesigner` component. |
| `DesignerProviderProps` | Props for the `DesignerProvider` component. |
| `JsonSchema` | A pragmatic JSON Schema document shape (Draft 2020-12 / Draft-07 compatible). |
| `JsonSchemaType` | `'string' \| 'number' \| 'integer' \| 'boolean' \| 'object' \| 'array' \| 'null'`. |
| `SchemaNode` | A single node in the designer's internal editable tree. |
| `DesignerView` | `'tree' \| 'json'` — the active center-pane tab. |
| `ToolboxItemDef` | Legacy palette entry shape — kept for backward compat with custom panels. |
| `IJsonSchemaAiAssistantRenderContext` | Argument passed to `renderAiAssistant` — `{ open, width, onClose, schema, strictMode }`. The live schema + strict-mode flag are forwarded so the slot can shape its prompts/tools. |
| `IUseApplyJsonSchemaResult` | Return shape of `useApplyJsonSchema` — `{ schema, setSchema, strictMode, setStrictMode, buildEditorContext, tools }`. |

---

# Json Schema Form
URL: /docs/web/components/json-schema-form

Json Schema Form component with multiple variants and sizes.

**Demo:**

```tsx
'use client';
// @custom-demo

import { useState } from 'react';

import { JsonSchemaForm } from '@docyrus/ui/components/json-schema-form';
import { type JsonSchema } from '@docyrus/ui/components/json-schema-designer';
import { cn } from '@docyrus/ui/primitives/lib/utils';
import { Button } from '@docyrus/ui/primitives/ui/button';

const SAMPLE_SCHEMA: JsonSchema = {
  type: 'object',
  title: 'Project Intake',
  description: 'Capture a nested project brief with owners, preferences, and repeating milestones.',
  required: [
    'projectName',
    'priority',
    'owner',
    'milestones'
  ],
  properties: {
    projectName: { type: 'string', minLength: 2 },
    summary: {
      type: 'string',
      format: 'textarea',
      maxLength: 500,
      description: 'A concise overview that explains what the team is shipping.'
    },
    priority: {
      type: 'string',
      enum: [
        'low',
        'medium',
        'high',
        'critical'
      ],
      description: 'Four options or less render as a radio group.'
    },
    stage: {
      type: 'string',
      enum: [
        'discovery',
        'design',
        'build',
        'qa',
        'launch',
        'retrospective'
      ],
      description: 'More than four options automatically switch to a select field.'
    },
    launchDate: { type: 'string', format: 'date' },
    owner: {
      type: 'object',
      required: ['name', 'email'],
      properties: {
        name: { type: 'string' },
        email: { type: 'string', format: 'email' },
        timezone: { type: 'string' }
      }
    },
    milestones: {
      type: 'array',
      minItems: 1,
      items: {
        type: 'object',
        required: ['title', 'dueDate'],
        properties: {
          title: { type: 'string' },
          dueDate: { type: 'string', format: 'date' },
          status: {
            type: 'string',
            enum: ['todo', 'in_progress', 'done']
          }
        }
      }
    },
    tags: {
      type: 'array',
      items: {
        type: 'string'
      },
      description: 'Primitive arrays also use SchemaRepeater.'
    }
  }
};

const SAMPLE_DATA = {
  projectName: 'Workspace Permissions',
  summary: 'Introduce scoped role assignments and delegated admin controls across workspace boundaries.',
  priority: 'high',
  stage: 'build',
  launchDate: '2026-06-15',
  owner: {
    name: 'Anil Beyazoglu',
    email: 'anil@example.com',
    timezone: 'Europe/Istanbul'
  },
  milestones: [
    {
      title: 'Access model approved',
      dueDate: '2026-05-30',
      status: 'done'
    },
    {
      title: 'Admin console rollout',
      dueDate: '2026-06-10',
      status: 'in_progress'
    }
  ],
  tags: ['security', 'rbac', 'workspace']
};

export function JsonSchemaFormDemo() {
  const [mode, setMode] = useState<'create' | 'edit' | 'view'>('edit');
  const [data, setData] = useState(SAMPLE_DATA);

  return (
    <div className="w-full space-y-4">
      <div className="flex flex-wrap items-center gap-2">
        {(['create', 'edit', 'view'] as const).map(value => (
          
        ))}
      </div>

      <div className="grid gap-4 xl:grid-cols-[minmax(0,1fr)_360px]">
        <div className={cn('rounded-2xl border bg-background p-4', mode === 'view' && 'bg-card/40')}>
          <JsonSchemaForm
            schema={SAMPLE_SCHEMA}
            data={mode === 'create' ? undefined : data}
            mode={mode}
            onChange={nextValue => setData(nextValue as typeof SAMPLE_DATA)}
            onSubmit={async nextValue => setData(nextValue as typeof SAMPLE_DATA)}
            submitLabel="Update project" />
        </div>

        <pre className="overflow-auto rounded-2xl border bg-muted/30 p-4 text-xs leading-6">
          {JSON.stringify(data, null, 2)}
        </pre>
      </div>
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-json-schema-form
```

**Dependencies:**
- [class-variance-authority](https://www.npmjs.com/package/class-variance-authority)
- [@tanstack/react-form](https://www.npmjs.com/package/@tanstack/react-form)

## Usage

```tsx
import {
  JsonSchemaForm
} from "@docyrus/ui/components/json-schema-form";

<JsonSchemaForm
  mode="create"
  schema={...}
  data={...}
  mode="create"
  disabled
  submitLabel="..."
  onChange={() => {}}
  onSubmit={() => {}}
  emptyState={...}
  ref={...}
/>
```

## Mode

| Mode | Description |
|------|-------------|
| `create` | Create — `space-y-6` |
| `edit` | Edit — `space-y-6` |
| `view` | View — `space-y-6` |

## API Reference

| Prop | Type | Default |
|------|------|---------|
| `mode` | `"create"` \| `"edit"` \| `"view"` | `"default"` |
| `schema` | `JsonSchema` | — |
| `data` | `JsonSchemaFormData \| null` | — |
| `mode` | `JsonSchemaFormMode` | — |
| `disabled` | `boolean` | — |
| `submitLabel` | `string` | — |
| `onChange` | `(value: JsonSchemaFormData) => void` | — |
| `onSubmit` | `(value: JsonSchemaFormData) => void \| Promise<void>` | — |
| `emptyState` | `ReactNode` | — |
| `ref` | `Ref<HTMLDivElement>` | — |
| `className` | `string` | — |

---

# Jsonata Editor
URL: /docs/web/components/jsonata-editor

A three-pane workbench for writing and evaluating JSONata expressions — a JSON input pane, an expression editor with IntelliSense, and a live result pane.

**Demo:**

```tsx
'use client';

import { useState } from 'react';

import {
  JSONATA_SAMPLES,
  JsonataEditor,
  type JsonataAIMessageContext,
  type JsonataEditorOrientation
} from '@docyrus/ui/components/jsonata-editor';
import { Label } from '@docyrus/ui/primitives/ui/label';
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue
} from '@docyrus/ui/primitives/ui/select';
import { Switch } from '@docyrus/ui/primitives/ui/switch';
import { Settings2 } from 'lucide-react';

/*
 * Demo data with nested objects and an array of objects so the editor's
 * autocomplete surfaces paths like `customer.address.city` and
 * `orders[0].product` — type `customer.` or `orders[0].` to see them.
 */
const DEMO_INPUT = {
  customer: {
    id: 'CUS-4821',
    name: 'Acme Corporation',
    email: 'hello@acme.example',
    isActive: true,
    address: {
      street: '100 Main St',
      city: 'Springfield',
      country: 'USA',
      postalCode: '01234'
    }
  },
  orders: [
    {
      id: 'ORD-1001',
      product: 'Widget Pro',
      quantity: 3,
      price: 29.99,
      tags: ['featured', 'sale']
    },
    {
      id: 'ORD-1002',
      product: 'Gadget Lite',
      quantity: 1,
      price: 79.5,
      tags: ['new']
    },
    {
      id: 'ORD-1003',
      product: 'Sprocket',
      quantity: 5,
      price: 12.25,
      tags: []
    }
  ],
  total: 261.97
};

const DEMO_EXPRESSION = '$sum(orders.(price * quantity))';

/** Canned demo replies — wire `onSendMessage` to a real backend in your app. */
async function demoAIReply(message: string, context: JsonataAIMessageContext): Promise<string> {
  await new Promise(resolve => setTimeout(resolve, 400));

  return [
    `_(Demo response)_ I'd help you with: **${message}**.`,
    '',
    `Your current expression is \`${context.expression || '(empty)'}\`.`,
    'Wire `aiAssistant.onSendMessage` to your LLM to get real answers.'
  ].join('\n');
}

export function JsonataEditorDemo() {
  const [showPanel, setShowPanel] = useState(false);
  const [orientation, setOrientation] = useState
            
              
                
              
            
          </div>

          <div className="flex items-center justify-between">
            
            
          </div>

          <div className="flex items-center justify-between">
            
            
          </div>

          <div className="flex items-center justify-between">
            
            
          </div>

          <div className="flex items-center justify-between">
            
            
          </div>
        </div>
      )}

      
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-jsonata-editor
```

**Dependencies:**
- [jsonata](https://www.npmjs.com/package/jsonata)
- [@uiw/react-codemirror](https://www.npmjs.com/package/@uiw/react-codemirror)
- [@uiw/codemirror-extensions-langs](https://www.npmjs.com/package/@uiw/codemirror-extensions-langs)
- [@codemirror/autocomplete](https://www.npmjs.com/package/@codemirror/autocomplete)
- [@codemirror/language](https://www.npmjs.com/package/@codemirror/language)
- [@codemirror/lint](https://www.npmjs.com/package/@codemirror/lint)
- [@codemirror/state](https://www.npmjs.com/package/@codemirror/state)
- [@codemirror/view](https://www.npmjs.com/package/@codemirror/view)
- [@lezer/highlight](https://www.npmjs.com/package/@lezer/highlight)
- [lucide-react](https://www.npmjs.com/package/lucide-react)

## Overview

`JsonataEditor` is a self-contained workbench for the
[JSONata](https://jsonata.org/) query and transformation language — modeled on
the official JSONata Exerciser. It has three panes:

| Pane | Role |
|------|------|
| **Input JSON** | A CodeMirror editor for the JSON document the expression runs against. |
| **Expression** | A JSONata editor with syntax highlighting, autocomplete, hover docs and inline parse-error linting. |
| **Result** | A read-only, live-updating view of the evaluated result (or the error). |

Evaluation happens automatically as you type (debounced). Expressions are
guarded by a timebox so an infinite loop or runaway recursion can't lock the
page.

## Features

- **Live evaluation** — debounced re-evaluation on every input or expression change.
- **IntelliSense** — autocomplete with snippet expansion for ~60 built-in `$` functions, grouped by category.
- **Hover documentation** — signatures, parameter docs and examples on hover.
- **Inline linting** — parse errors are underlined in the expression editor.
- **Timeboxed** — runaway recursion and infinite loops are aborted (`evaluationTimeout`).
- **Variable bindings** — inject values accessible as `$name` inside the expression.
- **Samples menu** — load ready-made input + expression pairs.
- **AI Assistant drawer** — opt-in chat panel built on ai-elements that slides in from the left and wires to your own LLM via `onSendMessage`.
- **Controlled or uncontrolled** — drive `expression` / `input` yourself or let the component own them.
- **Flexible layout** — `horizontal` or `vertical`, with the input and result panes individually toggleable.
- **Theme-aware** — follows the Docyrus light / dark theme.

## Usage

```tsx
import { JsonataEditor } from "@docyrus/ui/components/jsonata-editor";

export function Example() {
  return (
    <JsonataEditor
      defaultExpression="$sum(Account.Order.Product.(Price * Quantity))"
      defaultInput={{ Account: { Order: [] } }}
      onResult={(result) => console.log(result)}
    />
  );
}
```

### Controlled

Drive both panes from your own state:

```tsx
const [expression, setExpression] = useState("");
const [input, setInput] = useState("{}");

```

### Variable bindings

Values passed via `bindings` are available inside the expression as `$name`:

```tsx

```

> Memoize the `bindings` object if it is dynamic — the editor reads it on each
> evaluation but does not re-evaluate when only `bindings` changes.

## AI Assistant

Pass an `aiAssistant` config to add an **AI Assistant** button to the toolbar.
Clicking it slides a chat drawer in from the left of the editor, built on
ai-elements (`Conversation`, `Message`). Wire `onSendMessage` to your LLM and
return the reply (sync or async):

```tsx
<JsonataEditor
  defaultExpression="$sum(items.price)"
  aiAssistant={{
    onSendMessage: async (message, { expression, input, history }) => {
      const response = await fetch("/api/chat", {
        method: "POST",
        body: JSON.stringify({ message, expression, input, history })
      });
      const { reply } = await response.json();
      return reply;
    },
    suggestions: [
      "Explain this expression",
      "Show me a $map example",
      "How do I filter an array?"
    ]
  }}
/>
```

Pass `aiAssistant={true}` to mount the chat shell without a backend (useful
while wiring one — messages are stored locally but no reply arrives).

## Standalone expression editor

`JsonataCodeEditor` is the expression pane on its own — drop it into a form or
an automation node config when you only need to capture a JSONata expression.

```tsx
import { JsonataCodeEditor } from "@docyrus/ui/components/jsonata-editor";

const [value, setValue] = useState("");

```

## Headless evaluation

`useJsonata` debounces and evaluates an expression against an already-parsed
input value, with no UI:

```tsx
import { useJsonata } from "@docyrus/ui/components/jsonata-editor";

function useTotal(order: unknown) {
  const state = useJsonata("$sum(items.price)", order);

  return state.status === "success" ? state.result : undefined;
}
```

For a one-off evaluation outside React, use `evaluateJsonata`:

```tsx
import { evaluateJsonata } from "@docyrus/ui/components/jsonata-editor";

const state = await evaluateJsonata("$count(items)", { items: [1, 2, 3] });
// → { status: "success", result: 3 }
```

## EditorAgent integration

Pair `useApplyJsonata` with `renderAiAssistant` to give an LLM a writable expression pane. The hook owns the editor's controlled state and ships a `applyJsonata` tool that the agent calls to commit a new expression — the tool also evaluates against the current input JSON and returns a result preview so the agent can self-correct.

```tsx
import { EditorAgent } from '@docyrus/ui/components/editor-agent';
import { JsonataEditor, useApplyJsonata } from '@docyrus/ui/components/jsonata-editor';

export function JsonataPlayground({ client, user, agentId }) {
  const jsonata = useApplyJsonata();
  const [aiOpen, setAiOpen] = useState(false);

  return (
    <JsonataEditor
      expression={jsonata.expression}
      onExpressionChange={jsonata.setExpression}
      input={jsonata.input}
      onInputChange={jsonata.setInput}
      aiAssistantOpen={aiOpen}
      onAiAssistantOpenChange={setAiOpen}
      renderAiAssistant={({ open, onClose }) => (
        
      )}
    />
  );
}
```

The matching backend agent must register a tool named `applyJsonata` whose input schema mirrors `{ expression: string (required), input?: any, explanation?: string }`.

## API Reference

### JsonataEditor

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `expression` | `string` | — | Controlled JSONata expression. |
| `defaultExpression` | `string` | — | Initial expression for uncontrolled usage. |
| `onExpressionChange` | `(expression: string) => void` | — | Fired whenever the expression changes. |
| `input` | `string \| unknown` | — | Controlled JSON input — a string or any JSON-serializable value. |
| `defaultInput` | `string \| unknown` | — | Initial JSON input for uncontrolled usage. |
| `onInputChange` | `(input: string) => void` | — | Fired whenever the input text changes. |
| `bindings` | `Record<string, unknown>` | — | Variable bindings injected into `evaluate()` (accessible as `$name`). |
| `onResult` | `(result: unknown) => void` | — | Fired after a successful evaluation. |
| `onError` | `(error: JsonataEvaluationError) => void` | — | Fired when parsing the input or running the expression fails. |
| `onEvaluate` | `(state: JsonataEvaluationState) => void` | — | Fired after every evaluation, regardless of outcome. |
| `samples` | `JsonataSample[]` | — | Pre-defined input + expression pairs for the samples menu. |
| `aiAssistant` | `boolean \| JsonataAIAssistantConfig` | — | When provided, mounts the built-in AI Assistant drawer on the left. Pass `true` for the UI shell only, or a config object with `onSendMessage` to wire a backend. |
| `aiAssistantOpen` | `boolean` | — | Controlled open state for the AI Assistant drawer. When provided the editor stops managing the open state internally — pair with `onAiAssistantOpenChange`. |
| `onAiAssistantOpenChange` | `(open: boolean) => void` | — | Fired when the AI Assistant toolbar button toggles the drawer. |
| `renderAiAssistant` | `(ctx: IJsonataAiAssistantRenderContext) => ReactNode` | — | Replaces the built-in drawer body. When set, the toolbar button is shown even if `aiAssistant` is omitted, the drawer animates in as usual, and this render fn supplies the body. Use this to mount a custom agent (e.g. `<EditorAgent>`) inside the drawer. |
| `showInput` | `boolean` | `true` | Show the JSON input pane. |
| `showResult` | `boolean` | `true` | Show the result pane. |
| `showToolbar` | `boolean` | `true` | Show the header toolbar. |
| `title` | `string` | `'JSONata'` | Title shown in the toolbar. |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Pane arrangement. |
| `debounceMs` | `number` | `300` | Debounce before evaluating, in ms. |
| `evaluationTimeout` | `number` | `1000` | Evaluation timeout in ms. `0` disables the timebox. |
| `readOnly` | `boolean` | `false` | Disables editing of both panes. |
| `height` | `number \| string` | `'28rem'` | Overall editor height. |
| `placeholder` | `string` | — | Placeholder shown in the empty expression pane. |
| `className` | `string` | — | Root element className. |

### JsonataCodeEditor

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `string` | — | Current expression text. |
| `onChange` | `(value: string) => void` | — | Fired on every edit. |
| `readOnly` | `boolean` | `false` | Disables editing. |
| `placeholder` | `string` | — | Placeholder shown when empty. |
| `autoFocus` | `boolean` | `false` | Focus the editor on mount. |
| `minHeight` | `string` | `'2.5rem'` | Minimum editor height. |
| `maxHeight` | `string` | `'12rem'` | Maximum editor height. |
| `height` | `string` | — | Fixed editor height — overrides `minHeight` / `maxHeight`. |
| `lineNumbers` | `boolean` | `false` | Show line numbers. |
| `lint` | `boolean` | `true` | Enable the parse-error linter. |
| `basicSetup` | `BasicSetupOptions` | — | CodeMirror `basicSetup` overrides. |
| `extensions` | `Extension[]` | — | Extra CodeMirror extensions appended after the JSONata language. |
| `className` | `string` | — | Wrapper className. |

### useJsonata

```ts
useJsonata(expression: string, input: unknown, options?: UseJsonataOptions): JsonataEvaluationState
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `debounceMs` | `number` | `300` | Debounce before evaluating, in ms. |
| `enabled` | `boolean` | `true` | When `false`, evaluation is paused. |
| `bindings` | `Record<string, unknown>` | — | Variable bindings injected into `evaluate()`. |
| `timeout` | `number` | `1000` | Evaluation timeout in ms. `0` disables the timebox. |
| `maxDepth` | `number` | `500` | Maximum recursion depth before aborting. |

## Components

| Component | Description |
|-----------|-------------|
| `JsonataEditor` | The three-pane input / expression / result workbench. |
| `JsonataCodeEditor` | The standalone JSONata expression editor. |
| `useApplyJsonata` | Hook that owns `expression` + `input` state and exposes the `applyJsonata` client-side tool for `<EditorAgent>` — the tool writes the agent's expression AND evaluates it, returning a result preview or a categorized error (input-empty / parse / evaluate). See **EditorAgent integration** below. |

## Type Exports

| Type | Description |
|------|-------------|
| `JsonataEditorProps` | Props for `JsonataEditor`. |
| `JsonataCodeEditorProps` | Props for `JsonataCodeEditor`. |
| `JsonataEditorOrientation` | `'horizontal' \| 'vertical'`. |
| `JsonataSample` | A `{ name, description?, input, expression }` sample pair. |
| `JsonataAIAssistantConfig` | Config for the AI Assistant drawer — `onSendMessage`, `suggestions`, `title`, `defaultOpen`, `width`, `placeholder`, `emptyStateDescription`. |
| `IJsonataAiAssistantRenderContext` | Argument passed to `renderAiAssistant` — `{ open, width, onClose, expression, input }`. |
| `IUseApplyJsonataResult` | Return shape of `useApplyJsonata` — `{ expression, setExpression, input, setInput, tools }`. |
| `JsonataAIMessageContext` | Context passed to `onSendMessage`: current `expression`, `input` and `history`. |
| `JsonataChatMessage` | A `{ id, role: 'user' \| 'assistant', content }` chat entry. |
| `JsonataEvaluationState` | Discriminated union describing an evaluation outcome. |
| `JsonataEvaluationError` | Normalized parse / evaluation error (`phase`, `message`, `code?`, `position?`, `token?`). |
| `JsonataErrorPhase` | `'input' \| 'parse' \| 'evaluate'`. |
| `JsonataEvaluateOptions` | Options for `evaluateJsonata`. |
| `UseJsonataOptions` | Options for the `useJsonata` hook. |
| `JsonataFunction` | A built-in function descriptor used by IntelliSense. |
| `JsonataFunctionParam` | A single parameter of a `JsonataFunction`. |

## Helpers

| Export | Description |
|--------|-------------|
| `useJsonata` | Headless hook — debounced evaluation against a parsed input. |
| `evaluateJsonata` | Compiles and runs an expression; never throws. |
| `parseJsonInput` | Parses the JSON input text into a value or an error. |
| `stringifyResult` | Pretty-prints an evaluation result for display. |
| `jsonataExtensions` | CodeMirror extension bundle (language, autocomplete, hover, linter). |
| `jsonataLanguage` | CodeMirror `LanguageSupport` for JSONata. |
| `JSONATA_FUNCTIONS` | The built-in function catalog. |
| `JSONATA_FUNCTION_MAP` | `Map` of function name → descriptor. |
| `JSONATA_SAMPLES` | Ready-made sample input + expression pairs. |

---

# Kanban
URL: /docs/web/components/kanban

A drag-and-drop kanban board with sortable columns and items, column reordering, overlay previews, and final drop zones for archiving or completing tasks.

**Demo:**

```tsx
'use client';

import { useCallback, useMemo, useState } from 'react';

import {
  Kanban,
  KanbanBoard,
  KanbanColumn,
  KanbanColumnHandle,
  KanbanFinalColumn,
  KanbanFinalZone,
  KanbanItem,
  KanbanItemTitle,
  KanbanOverlay
} from '@docyrus/ui/components/kanban';
import { cn } from '@docyrus/ui/primitives/lib/utils';

import { PropControls, type PropControl } from '@/components/prop-controls';

// ─── Types ───────────────────────────────────────────────────────────────────

interface Task {
  id: string;
  title: string;
  priority: 'low' | 'medium' | 'high';
  assignee: string;
  tag?: string;
}

// ─── Data ────────────────────────────────────────────────────────────────────

const PRIORITY_STYLES: Record
      ) : <span className="truncate text-sm font-medium leading-snug">{task.title}</span>}
      <div className="flex items-center justify-between">
        <div className="flex items-center gap-1.5">
          {task.tag && (
            <span className="rounded-sm bg-muted px-1.5 py-0.5 text-[10px] font-medium text-muted-foreground">
              {task.tag}
            </span>
          )}
          <span
            className={cn(
              'rounded px-1.5 py-0.5 text-[10px] font-bold uppercase leading-none tracking-wide',
              PRIORITY_STYLES[task.priority]
            )}>
            {task.priority}
          </span>
        </div>
        <span className="flex size-6 items-center justify-center rounded-full bg-muted text-[10px] font-medium">
          {task.assignee}
        </span>
      </div>
    </div>
  );
}

// ─── KanbanDemo ──────────────────────────────────────────────────────────────

export function KanbanDemo() {
  const [columns, setColumns] = useState(INITIAL_TASKS);
  const [archivedCount, setArchivedCount] = useState(0);
  const [showDone, setShowDone] = useState(true);
  const [showArchive, setShowArchive] = useState(true);
  const [showCounts, setShowCounts] = useState(true);
  const [flatCursor, setFlatCursor] = useState(false);
  const [open, setOpen] = useState(false);
  const [clickedItem, setClickedItem] = useState<string | null>(null);

  const taskMap = useMemo(() => {
    const map = new Map<string, Task>();

    for (const items of Object.values(columns)) {
      for (const item of items) {
        map.set(item.id, item);
      }
    }

    return map;
  }, [columns]);

  const handleFinalDrop = useCallback((item: Task, finalColumnId: string | number) => {
    const targetColumn = String(finalColumnId);

    setColumns(prev => ({
      ...prev,
      [targetColumn]: [...(prev[targetColumn] ?? []), item]
    }));

    if (targetColumn !== 'done') {
      setArchivedCount(prev => prev + 1);
    }
  }, []);

  const controls: PropControl[] = [
    {
      type: 'boolean', name: 'showDone', label: 'Done Zone', value: showDone, onChange: setShowDone
    },
    {
      type: 'boolean', name: 'showArchive', label: 'Archive Zone', value: showArchive, onChange: setShowArchive
    },
    {
      type: 'boolean', name: 'showCounts', label: 'Counts', value: showCounts, onChange: setShowCounts
    },
    {
      type: 'boolean', name: 'flatCursor', label: 'Flat Cursor', value: flatCursor, onChange: setFlatCursor
    }
  ];

  return (
    <div className="w-full">
      <div className="mb-3 flex justify-end">
        <button
          type="button"
          className="inline-flex items-center gap-1.5 rounded-md border border-border bg-background px-3 py-1.5 text-sm font-medium transition-colors hover:bg-accent"
          onClick={() => setOpen(prev => !prev)}>
          <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M12.22 2h-.44a2 2 0 0 0-2 2v.18a2 2 0 0 1-1 1.73l-.43.25a2 2 0 0 1-2 0l-.15-.08a2 2 0 0 0-2.73.73l-.22.38a2 2 0 0 0 .73 2.73l.15.1a2 2 0 0 1 1 1.72v.51a2 2 0 0 1-1 1.74l-.15.09a2 2 0 0 0-.73 2.73l.22.38a2 2 0 0 0 2.73.73l.15-.08a2 2 0 0 1 2 0l.43.25a2 2 0 0 1 1 1.73V20a2 2 0 0 0 2 2h.44a2 2 0 0 0 2-2v-.18a2 2 0 0 1 1-1.73l.43-.25a2 2 0 0 1 2 0l.15.08a2 2 0 0 0 2.73-.73l.22-.39a2 2 0 0 0-.73-2.73l-.15-.08a2 2 0 0 1-1-1.74v-.5a2 2 0 0 1 1-1.74l.15-.09a2 2 0 0 0 .73-2.73l-.22-.38a2 2 0 0 0-2.73-.73l-.15.08a2 2 0 0 1-2 0l-.43-.25a2 2 0 0 1-1-1.73V4a2 2 0 0 0-2-2z" /><circle cx="12" cy="12" r="3" /></svg>
          Configure
          <svg xmlns="http://www.w3.org/2000/svg" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" className={cn('transition-transform duration-200', open && 'rotate-180')}><path d="m6 9 6 6 6-6" /></svg>
        </button>
      </div>
      <div
        className={cn(
          'grid transition-[grid-template-rows] duration-300 ease-in-out',
          open ? 'grid-rows-[1fr]' : 'grid-rows-[0fr]'
        )}>
        <div className="overflow-hidden">
          <div className="mb-4 rounded-lg border border-border bg-card p-4">
            
          </div>
        </div>
      </div>

      {clickedItem && (
        <div className="mb-3 flex items-center gap-2 rounded-lg border border-primary/20 bg-primary/5 px-3 py-2 text-sm">
          <span className="font-medium text-primary">Item clicked:</span>
          <span className="text-foreground">{taskMap.get(clickedItem)?.title ?? clickedItem}</span>
          <button
            type="button"
            className="ml-auto text-muted-foreground hover:text-foreground"
            onClick={() => setClickedItem(null)}>
            <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M18 6 6 18" /><path d="m6 6 12 12" /></svg>
          </button>
        </div>
      )}

      
                </div>

                <div className="flex flex-col gap-2 p-2">
                  {items.map(task => (
                    
                  ))}
                  {items.length === 0 && (
                    <p className="py-8 text-center text-xs text-muted-foreground">
                      No tasks
                    </p>
                  )}
                </div>
              
            );
          })}
        

        {(showDone || showArchive) && (
          
            )}
            {showArchive && (
              
            )}
          
        )}

        
      
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-kanban
```

**Dependencies:**
- [@dnd-kit/sortable](https://www.npmjs.com/package/@dnd-kit/sortable)
- [@dnd-kit/core](https://www.npmjs.com/package/@dnd-kit/core)
- [@dnd-kit/utilities](https://www.npmjs.com/package/@dnd-kit/utilities)
- [@radix-ui/react-slot](https://www.npmjs.com/package/@radix-ui/react-slot)
- [@types/react](https://www.npmjs.com/package/@types/react)

## Usage

```tsx
import {
  Kanban,
  KanbanBoard,
  KanbanColumn,
  KanbanColumnHandle,
  KanbanItem,
  KanbanItemHandle,
  KanbanItemTitle,
  KanbanOverlay,
  KanbanFinalZone,
  KanbanFinalColumn
} from '@docyrus/ui/components/kanban';

const [columns, setColumns] = useState({
  todo: [{ id: '1', title: 'Task 1' }, { id: '2', title: 'Task 2' }],
  done: [{ id: '3', title: 'Task 3' }]
});

        {items.map((item) => (
          
        ))}
      
    ))}
  
  

```

### With Final Drop Zones

Use `finalColumns` on `Kanban` and `KanbanFinalZone` + `KanbanFinalColumn` to create drop targets that remove items from columns (e.g., archive or complete).

```tsx

  
    
  

  

```

### With Custom Overlay

The `KanbanOverlay` children can be a render function that receives the active item's value and variant.

```tsx

```

### Item Detail

Use `onItemClick` and `KanbanItemTitle` to open item details. `KanbanItemTitle` creates a clickable title zone that prevents drag-and-drop and triggers the callback instead.

```tsx

        {items.map((item) => (
          
            <p className="text-sm text-muted-foreground">{item.description}</p>
          
        ))}
      
    ))}
  
  

```

### Vertical Layout

Set `orientation="vertical"` for a top-to-bottom column layout.

```tsx

```

## Components

| Component | Description |
|-----------|-------------|
| `Kanban` | Root provider. Wraps `DndContext` with collision detection, keyboard navigation, and screen reader announcements. |
| `KanbanBoard` | Container for columns. Renders a `SortableContext` for column reordering. |
| `KanbanColumn` | A sortable column container. Renders a `SortableContext` for its items. |
| `KanbanColumnHandle` | Drag handle for reordering columns. Must be inside `KanbanColumn`. |
| `KanbanItem` | A sortable item within a column. Supports cross-column drag. |
| `KanbanItemHandle` | Drag handle for items. Must be inside `KanbanItem`. |
| `KanbanItemTitle` | Clickable title zone inside `KanbanItem`. Prevents drag-and-drop and fires `onItemClick`. |
| `KanbanOverlay` | Portal-rendered drag overlay preview. Accepts a render function for custom previews. |
| `KanbanFinalZone` | Container for final drop columns. Only visible during item drag. |
| `KanbanFinalColumn` | A droppable target inside `KanbanFinalZone` that triggers `onFinalDrop`. |

## API Reference

### Kanban

The root component. Manages drag state, collision detection, and value changes.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `Record<UniqueIdentifier, T[]>` | — | Column data. Keys are column IDs, values are item arrays. |
| `onValueChange` | `(columns: Record<UniqueIdentifier, T[]>) => void` | — | Called when items are moved between or within columns. |
| `getItemValue` | `(item: T) => UniqueIdentifier` | — | Extracts a unique ID from each item. Required when `T` is an object. |
| `onMove` | `(event: DragEndEvent & { activeIndex: number; overIndex: number }) => void` | — | Called on reorder instead of `onValueChange` when provided. Useful for server-side persistence. |
| `onFinalDrop` | `(item: T, finalColumnId: UniqueIdentifier) => void` | — | Called when an item is dropped onto a `KanbanFinalColumn`. |
| `onItemClick` | `(value: UniqueIdentifier) => void` | — | Called when a `KanbanItemTitle` is clicked. Receives the item's value. |
| `finalColumns` | `UniqueIdentifier[]` | — | IDs of final drop columns (must match `KanbanFinalColumn` values). |
| `strategy` | `SortableContextProps['strategy']` | `verticalListSortingStrategy` | Sorting strategy for items within columns. |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Board layout direction. |
| `flatCursor` | `boolean` | `false` | Use `cursor-default` instead of `cursor-grab` for all drag handles. |
| `modifiers` | `DndContextProps['modifiers']` | — | dnd-kit modifiers for constraining drag movement. |
| `accessibility` | `DndContextProps['accessibility']` | — | Custom accessibility announcements (merged with built-in announcements). |

### KanbanBoard

Container for columns. Must be inside `Kanban`.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `asChild` | `boolean` | `false` | Render as child element using `Slot`. |
| `className` | `string` | — | Additional CSS classes. |

### KanbanColumn

A sortable column. Must be inside `KanbanBoard` or `KanbanOverlay`.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `UniqueIdentifier` | — | Unique column identifier. Must match a key in `Kanban`'s `value`. |
| `asChild` | `boolean` | `false` | Render as child element using `Slot`. |
| `asHandle` | `boolean` | `false` | Make the entire column a drag handle. |
| `disabled` | `boolean` | `false` | Disable column dragging. |
| `className` | `string` | — | Additional CSS classes. |

### KanbanColumnHandle

Drag handle for columns. Must be inside `KanbanColumn`.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `asChild` | `boolean` | `false` | Render as child element using `Slot`. |
| `disabled` | `boolean` | — | Override column's disabled state. |
| `className` | `string` | — | Additional CSS classes. |

### KanbanItem

A sortable item. Must be inside `KanbanColumn` (within `KanbanBoard` or `KanbanOverlay`).

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `UniqueIdentifier` | — | Unique item identifier. Must match the value returned by `getItemValue`. |
| `asChild` | `boolean` | `false` | Render as child element using `Slot`. |
| `asHandle` | `boolean` | `false` | Make the entire item a drag handle. |
| `disabled` | `boolean` | `false` | Disable item dragging. |
| `className` | `string` | — | Additional CSS classes. |

### KanbanItemHandle

Drag handle for items. Must be inside `KanbanItem`.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `asChild` | `boolean` | `false` | Render as child element using `Slot`. |
| `disabled` | `boolean` | — | Override item's disabled state. |
| `className` | `string` | — | Additional CSS classes. |

### KanbanItemTitle

Clickable title zone inside `KanbanItem`. Intercepts pointer events to prevent drag-and-drop activation, and fires the root `onItemClick` callback on click. Renders a `<button>` by default.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `asChild` | `boolean` | `false` | Render as child element using `Slot`. |
| `className` | `string` | — | Additional CSS classes. |

### KanbanOverlay

Portal-rendered drag preview overlay.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode \| ((params: { value: UniqueIdentifier; variant: 'column' \| 'item' }) => ReactNode)` | — | Static content or render function for custom preview. Receives the active item's value and whether it's a column or item. |
| `container` | `Element \| DocumentFragment \| null` | `document.body` | Portal container. |

### KanbanFinalZone

Container for final drop targets. Shows `data-dragging` attribute when an item is being dragged.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `asChild` | `boolean` | `false` | Render as child element using `Slot`. |
| `className` | `string` | — | Additional CSS classes. |

### KanbanFinalColumn

A droppable zone for permanently removing items from columns (e.g., archive, complete, delete).

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `UniqueIdentifier` | — | Unique identifier. Must be listed in `Kanban`'s `finalColumns` array. |
| `asChild` | `boolean` | `false` | Render as child element using `Slot`. |
| `className` | `string` | — | Additional CSS classes. |

### Data Attributes

| Attribute | Component | Description |
|-----------|-----------|-------------|
| `data-dragging` | `KanbanColumn`, `KanbanItem`, `KanbanColumnHandle`, `KanbanItemHandle`, `KanbanItemTitle`, `KanbanFinalZone`, `KanbanFinalColumn` | Present when the element (or its parent) is being dragged. |
| `data-disabled` | `KanbanColumn`, `KanbanItem`, `KanbanColumnHandle`, `KanbanItemHandle` | Present when the element is disabled. |
| `data-value` | `KanbanItem` | The item's unique identifier value. Used internally by `KanbanItemTitle`. |
| `data-over` | `KanbanFinalColumn` | Present when a dragged item is hovering over the final column. |
| `data-orientation` | `KanbanBoard` | Current board orientation (`horizontal` or `vertical`). |
| `data-slot` | All | Component identifier (`kanban-board`, `kanban-column`, `kanban-item`, etc.). |

### Keyboard Navigation

| Key | Action |
|-----|--------|
| `Space` / `Enter` | Pick up or drop the focused item/column. |
| `Arrow Keys` | Move the picked-up item/column in the corresponding direction. |
| `Escape` | Cancel the current drag operation. |

---

# Log Activity Form
URL: /docs/web/components/log-activity-form

A presentational multi-tab "log activity" composer — comment, email, call, meeting, task, and status — with every tab rendered inline, wired to Docyrus via the useDocyrusLogActivity hook.

**Demo:**

```tsx
'use client';

import { useState } from 'react';

import { type CommentUser } from '@docyrus/ui/components/comments-panel';
import { type EnumOption, type IField } from '@docyrus/ui/components/form-fields';
import { LogActivityForm, type LoggableActivityType } from '@docyrus/ui/components/log-activity-form';

const STATUS_FIELD: IField = {
  id: 'status', name: 'Status', slug: 'status', type: 'field-status'
};

const STATUS_OPTIONS: Array<EnumOption> = [
  { id: 'open', name: 'Open', color: 'emerald-500' },
  { id: 'in_progress', name: 'In Progress', color: 'amber-500' },
  { id: 'won', name: 'Won', color: 'green-600' },
  { id: 'lost', name: 'Lost', color: 'red-500' }
];

const TASK_STATUS_OPTIONS: Array<EnumOption> = [{ id: 'backlog', name: 'Backlog', color: 'slate-400' }, { id: 'todo', name: 'To Do', color: 'blue-500' }, { id: 'doing', name: 'In Progress', color: 'amber-500' }];

const TASK_PRIORITY_OPTIONS: Array<EnumOption> = [{ id: 'low', name: 'Low', color: 'slate-400' }, { id: 'medium', name: 'Medium', color: 'amber-500' }, { id: 'high', name: 'High', color: 'red-500' }];

const USER_OPTIONS: Array<EnumOption> = [{ id: 'u1', name: 'Ada Lovelace' }, { id: 'u2', name: 'Alan Turing' }];

const COMMENT_USERS: Array<CommentUser> = [{ id: 'u1', firstname: 'Ada', lastname: 'Lovelace' }, { id: 'u2', firstname: 'Alan', lastname: 'Turing' }];

const EVENT_TYPES: Array<EnumOption> = [{ id: 'call', name: 'Call' }, { id: 'meeting', name: 'Meeting' }];

/**
 * Presentational demo — every tab renders its form inline (no dialog / dropdown).
 * In a real app, spread `useDocyrusLogActivity(...).logActivityProps` instead of
 * the static props below.
 */
export function LogActivityFormDemo() {
  const [tab, setTab] = useState<LoggableActivityType>('comment');

  return (
    <div className="w-full max-w-xl">
      <LogActivityForm
        activeType={tab}
        onTypeChange={setTab}
        comments={[]}
        users={COMMENT_USERS}
        currentUser={COMMENT_USERS[0]}
        onCreateComment={async payload => console.info('comment', payload)}
        statusField={STATUS_FIELD}
        statusEnumOptions={STATUS_OPTIONS}
        statusInitialValues={{ status: '' }}
        onSubmitStatus={async input => console.info('status', input)}
        taskStatusOptions={TASK_STATUS_OPTIONS}
        taskPriorityOptions={TASK_PRIORITY_OPTIONS}
        taskUsers={USER_OPTIONS}
        onSubmitTask={async input => console.info('task', input)}
        eventTypes={EVENT_TYPES}
        eventUsers={USER_OPTIONS}
        callEventTypeId="call"
        meetingEventTypeId="meeting"
        onSubmitEvent={async (input, kind) => console.info('event', kind, input)} />
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-log-activity-form
```

**Dependencies:**
- [@tanstack/react-form](https://www.npmjs.com/package/@tanstack/react-form)
- [@tanstack/react-query](https://www.npmjs.com/package/@tanstack/react-query)
- [motion](https://www.npmjs.com/package/motion)
- [lucide-react](https://www.npmjs.com/package/lucide-react)
- [sonner](https://www.npmjs.com/package/sonner)

## Overview

`LogActivityForm` is a **presentational** component (it owns no network I/O). A tab bar switches between six surfaces and each one renders its form **inline** — no dialog, no dropdown-triggered form. Every tab reuses the real Docyrus components / form-fields:

| Tab | Inline surface |
|-----|----------------|
| Comment | [`CommentsPanel`](/docs/web/components/comments-panel) (threaded) |
| Email | [`EmailComposer`](/docs/web/components/email-composer) (send-only) |
| Status | inline `StatusFormField` (status list + sub-status / notes / follow-up date, no popover) |
| Task | `subject` + `status` + `priority` + `assignee` + `due date` + `description` form-fields |
| Call / Meeting | `subject` + `event type` + `start` / `end` + `owner` + `description` form-fields |

Wire it to a Docyrus record with [`useDocyrusLogActivity`](/docs/web/hooks/use-docyrus-log-activity) — the hook owns ALL I/O (option fetches, the per-tab create mutations, the two-call status update, and an embedded email composer) and returns a spreadable `logActivityProps` bag. This mirrors the `EmailComposer` / `useDocyrusEmailComposer` split.

## Usage

```tsx
import { LogActivityForm } from '@docyrus/ui/components/log-activity-form';
import { useDocyrusLogActivity } from '@docyrus/ui/library/hooks/use-docyrus-log-activity';
import { ContactActivityPanel, useDocyrusContactActivity } from '@docyrus/ui/components/contact-activity-panel';

function RecordActivity({ client, recordId }) {
  // One hook feeds the log form (all I/O).
  const { logActivityProps } = useDocyrusLogActivity({
    client,
    appSlug: 'base',
    dataSourceSlug: 'organization',
    recordId,
    taskRelationSlug: 'organization',   // per-tenant back-relation for task/event linking
    statusFieldSlug: 'status',
    callEventTypeName: 'Call',          // resolve the call/meeting event type by name
    meetingEventTypeName: 'Meeting'
  });

  // A sibling hook feeds the timeline. Both share the record-scoped query prefix,
  // so logging on the form auto-refreshes the panel — no manual refetch wiring.
  const { panelProps } = useDocyrusContactActivity({
    client, appSlug: 'base', dataSourceSlug: 'organization', recordId,
    taskRelationSlug: 'organization',
    sources: { audit: true, comments: true, tasks: true, statusUpdates: true }
  });

  return (
    <>
      
      
    </>
  );
}
```

## API Reference

Every prop is optional — a bare `` renders the tab shell with empty surfaces. In practice you spread `logActivityProps` (see the hook), which fills all of these.

### Shell

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `activityTypes` | `LoggableActivityType[]` | all six | Which tabs to show (order preserved). |
| `activeType` | `LoggableActivityType` | — | Controlled active tab. |
| `defaultActivityType` | `LoggableActivityType` | first tab | Uncontrolled initial tab. |
| `onTypeChange` | `(type: LoggableActivityType) => void` | — | Fired on tab change. |
| `disabled` | `boolean` | `false` | Disable every surface. |
| `className` | `string` | — | Root class. |

### Comment tab

| Prop | Type | Description |
|------|------|-------------|
| `comments` | `DocyrusComment[]` | Thread source. |
| `users` | `CommentUser[]` | Users for `@` mentions / avatars. |
| `currentUser` | `CommentUser` | The authoring user. |
| `onCreateComment` | `(payload: LogActivityCommentPayload) => void \| Promise<void>` | Create / reply. |
| `onDeleteComment` | `(commentId: string) => void \| Promise<void>` | Delete. |
| `isCommentsLoading` / `isCreatingComment` | `boolean` | Pending flags. |

### Email tab

| Prop | Type | Description |
|------|------|-------------|
| `emailComposerProps` | `Partial<EmailComposerProps>` | Spread onto the inline `EmailComposer` (from `useDocyrusEmailComposer`). |
| `onSendEmail` | `() => void \| Promise<void>` | Send handler (the tab wraps it with a toast). |
| `isSendingEmail` | `boolean` | Pending flag. |

### Status tab

| Prop | Type | Description |
|------|------|-------------|
| `statusField` | `IField \| null` | The record's status field (`field-status` / `field-select`). |
| `statusEnumOptions` | `EnumOption[]` | Status options. |
| `statusInitialValues` | `Record<string, unknown>` | Current status + companion values, keyed by field slug. |
| `onSubmitStatus` | `(input: LogStatusInput) => void \| Promise<void>` | Submit (two-call in the hook). |
| `isSubmittingStatus` / `isStatusLoading` | `boolean` | Pending / loading flags. |

### Task tab

| Prop | Type | Description |
|------|------|-------------|
| `taskStatusOptions` / `taskPriorityOptions` | `EnumOption[]` | Task enum options. |
| `taskUsers` | `EnumOption[]` | Assignee options (`{ id, name, icon }`). |
| `onSubmitTask` | `(input: LogTaskInput) => void \| Promise<void>` | Submit. |
| `isSubmittingTask` | `boolean` | Pending flag. |

### Call / Meeting tabs

| Prop | Type | Description |
|------|------|-------------|
| `eventTypes` | `EnumOption[]` | Event type options. |
| `eventUsers` | `EnumOption[]` | Owner options. |
| `callEventTypeId` / `meetingEventTypeId` | `string` | Preset event-type id per tab. |
| `onSubmitEvent` | `(input: LogEventInput, kind: 'call' \| 'meeting') => void \| Promise<void>` | Submit. |
| `isSubmittingEvent` | `boolean` | Pending flag. |

## Type Exports

| Type | Description |
|------|-------------|
| `LogActivityFormProps` | Props for the presentational form. |
| `LoggableActivityType` | `"comment" \| "email" \| "call" \| "meeting" \| "task" \| "status_update"` |
| `LogActivityCommentPayload` | Comment submit payload (`{ content, parent_id?, mentions? }`). |
| `LogTaskInput` | Task submit payload. |
| `LogEventInput` | Call / meeting submit payload. |
| `LogStatusInput` | Status submit payload. |

---

# Map
URL: /docs/web/components/map

Interactive map component built on Leaflet with SSR-safe lazy loading, theme-aware tiles, marker clustering, drawing tools, custom controls, and geolocation.

**Demo:**

```tsx
'use client';

import { useState } from 'react';

import { type LatLngExpression } from 'leaflet';

import {
  Map,
  MapDrawCircle,
  MapDrawControl,
  MapDrawDelete,
  MapDrawEdit,
  MapDrawMarker,
  MapDrawPolygon,
  MapDrawPolyline,
  MapDrawRectangle,
  MapDrawUndo,
  MapFullscreenControl,
  MapLocateControl,
  MapMarker,
  MapPopup,
  MapTileLayer,
  MapTooltip,
  MapZoomControl
} from '@docyrus/ui/components/map';
import { Switch } from '@docyrus/ui/primitives/ui/switch';
import { cn } from '@docyrus/ui/primitives/lib/utils';

const SF_CENTER: LatLngExpression = [37.7749, -122.4194];

interface MarkerData {
  position: LatLngExpression;
  title: string;
  description: string;
}

const MARKERS: MarkerData[] = [
  {
    position: [37.7749, -122.4194],
    title: 'San Francisco',
    description: 'City by the Bay'
  },
  {
    position: [37.8024, -122.4058],
    title: 'Fisherman\'s Wharf',
    description: 'Popular waterfront neighborhood'
  },
  {
    position: [37.7956, -122.3933],
    title: 'Financial District',
    description: 'Business center of San Francisco'
  }
];

export function MapDemo() {
  const [showControls, setShowControls] = useState(true);
  const [showDraw, setShowDraw] = useState(false);
  const [open, setOpen] = useState(false);

  return (
    <div className="w-full">
      <div className="mb-3 flex justify-end">
        <button
          type="button"
          className="inline-flex items-center gap-1.5 rounded-md border border-border bg-background px-3 py-1.5 text-sm font-medium transition-colors hover:bg-accent"
          onClick={() => setOpen(prev => !prev)}>
          <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M12.22 2h-.44a2 2 0 0 0-2 2v.18a2 2 0 0 1-1 1.73l-.43.25a2 2 0 0 1-2 0l-.15-.08a2 2 0 0 0-2.73.73l-.22.38a2 2 0 0 0 .73 2.73l.15.1a2 2 0 0 1 1 1.72v.51a2 2 0 0 1-1 1.74l-.15.09a2 2 0 0 0-.73 2.73l.22.38a2 2 0 0 0 2.73.73l.15-.08a2 2 0 0 1 2 0l.43.25a2 2 0 0 1 1 1.73V20a2 2 0 0 0 2 2h.44a2 2 0 0 0 2-2v-.18a2 2 0 0 1 1-1.73l.43-.25a2 2 0 0 1 2 0l.15.08a2 2 0 0 0 2.73-.73l.22-.39a2 2 0 0 0-.73-2.73l-.15-.08a2 2 0 0 1-1-1.74v-.5a2 2 0 0 1 1-1.74l.15-.09a2 2 0 0 0 .73-2.73l-.22-.38a2 2 0 0 0-2.73-.73l-.15.08a2 2 0 0 1-2 0l-.43-.25a2 2 0 0 1-1-1.73V4a2 2 0 0 0-2-2z" /><circle cx="12" cy="12" r="3" /></svg>
          Configure
          <svg xmlns="http://www.w3.org/2000/svg" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" className={cn('transition-transform duration-200', open && 'rotate-180')}><path d="m6 9 6 6 6-6" /></svg>
        </button>
      </div>
      <div
        className={cn(
          'grid transition-[grid-template-rows] duration-300 ease-in-out',
          open ? 'grid-rows-[1fr]' : 'grid-rows-[0fr]'
        )}>
        <div className="overflow-hidden">
          <div className="mb-4 grid gap-6 rounded-lg border border-border bg-muted/30 p-4">
            <div className="flex flex-wrap items-center gap-4">
              <label className="flex items-center gap-2">
                
                <span className="text-xs">Zoom / Fullscreen / Locate</span>
              </label>
              <label className="flex items-center gap-2">
                
                <span className="text-xs">Draw tools</span>
              </label>
            </div>
          </div>
        </div>
      </div>
      <div className="overflow-hidden rounded-lg border border-border">
        
              
            
          ))}

          {showControls && (
            <>
              
              
              
            </>
          )}

          {showDraw && (
            
          )}
        
      </div>
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-map
```

**Dependencies:**
- [leaflet-draw](https://www.npmjs.com/package/leaflet-draw)
- [leaflet](https://www.npmjs.com/package/leaflet)
- [leaflet.markercluster](https://www.npmjs.com/package/leaflet.markercluster)
- [lucide-react](https://www.npmjs.com/package/lucide-react)
- [react-dom](https://www.npmjs.com/package/react-dom)
- [react-leaflet](https://www.npmjs.com/package/react-leaflet)
- [react-leaflet-markercluster](https://www.npmjs.com/package/react-leaflet-markercluster)

## Usage

```tsx
import {
  Map,
  MapTileLayer,
  MapMarker,
  MapPopup,
  MapZoomControl,
  useLeaflet
} from '@docyrus/ui/components/map';

  

```

### With Layers & Clustering

```tsx
import {
  Map,
  MapTileLayer,
  MapLayers,
  MapLayerGroup,
  MapLayersControl,
  MapMarker,
  MapMarkerClusterGroup,
  MapZoomControl
} from '@docyrus/ui/components/map';

    
    
  
  

```

### With Drawing Tools

```tsx
import {
  Map,
  MapTileLayer,
  MapDrawControl,
  MapDrawMarker,
  MapDrawPolyline,
  MapDrawPolygon,
  MapDrawCircle,
  MapDrawRectangle,
  MapDrawEdit,
  MapDrawDelete,
  MapDrawUndo
} from '@docyrus/ui/components/map';

```

### Dark Mode Tile Layers

`MapTileLayer` supports separate `url` and `darkUrl` props. Theme detection uses `useDocyTheme` automatically.

```tsx

```

## Components

| Component | Description |
|-----------|-------------|
| `Map` | Root container. Wraps Leaflet `MapContainer` with SSR-safe lazy loading. |
| `MapTileLayer` | Tile layer with dark mode support via `darkUrl`. |
| `MapLayers` | Context provider for tile layer and layer group management. |
| `MapLayerGroup` | Named layer group that registers with `MapLayers`. |
| `MapFeatureGroup` | Feature group that registers with `MapLayers`. |
| `MapLayersControl` | Dropdown to select tile layers and toggle layer groups. |
| `MapMarker` | Marker with custom `ReactNode` icon via `DivIcon`. |
| `MapMarkerClusterGroup` | Cluster group with custom badge icon function. |
| `MapCircle` | Circle shape overlay. |
| `MapCircleMarker` | Circle marker overlay. |
| `MapPolyline` | Polyline shape overlay. |
| `MapPolygon` | Polygon shape overlay. |
| `MapRectangle` | Rectangle shape overlay. |
| `MapPopup` | Styled popup with dark mode support. |
| `MapTooltip` | Tooltip with directional arrow. |
| `MapControlContainer` | Container for custom controls (disables map interaction propagation). |
| `MapZoomControl` | Zoom in/out buttons. |
| `MapFullscreenControl` | Fullscreen toggle button. |
| `MapLocateControl` | Geolocation tracker with optional watch mode. |
| `MapSearchControl` | Place search via `PlaceAutocomplete` integration. |
| `MapDrawControl` | Context provider for drawing mode. |
| `MapDrawMarker` | Toggle button for marker drawing. |
| `MapDrawPolyline` | Toggle button for polyline drawing. |
| `MapDrawCircle` | Toggle button for circle drawing. |
| `MapDrawRectangle` | Toggle button for rectangle drawing. |
| `MapDrawPolygon` | Toggle button for polygon drawing. |
| `MapDrawEdit` | Toggle button for editing drawn shapes. |
| `MapDrawDelete` | Toggle button for deleting drawn shapes. |
| `MapDrawUndo` | Undo last edit/delete action. |
| `useLeaflet` | Hook to lazy-load Leaflet + plugins. Returns `{ L, ready }`. |

## API Reference

### Map

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `center` | `LatLngExpression` | — | Map center coordinates. |
| `zoom` | `number` | `15` | Initial zoom level. |
| `maxZoom` | `number` | `18` | Maximum zoom level. |
| `className` | `string` | — | Additional CSS classes. |

### MapTileLayer

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `name` | `string` | `'Default'` | Layer identifier for `MapLayersControl`. |
| `url` | `string` | OpenStreetMap URL | Tile URL template. |
| `darkUrl` | `string` | — | Dark theme tile URL. Auto-switches with `useDocyTheme`. |
| `attribution` | `string` | — | Attribution text for light theme. |
| `darkAttribution` | `string` | — | Attribution text for dark theme. |

### MapLayers

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `defaultTileLayer` | `string` | — | Initial active tile layer name. |
| `defaultLayerGroups` | `string[]` | `[]` | Initially visible layer group names. |

### MapLayerGroup

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `name` | `string` | — | Layer group identifier. |
| `disabled` | `boolean` | — | Hide from layer controls toggle. |

### MapMarker

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `position` | `LatLngExpression` | — | Marker coordinates. |
| `icon` | `ReactNode` | `` | Custom icon rendered as `DivIcon`. |
| `iconAnchor` | `[number, number]` | `[12, 12]` | Icon anchor point. |
| `popupAnchor` | `[number, number]` | — | Popup anchor offset. |
| `tooltipAnchor` | `[number, number]` | — | Tooltip anchor offset. |

### MapMarkerClusterGroup

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `icon` | `(count: number) => ReactNode` | — | Custom cluster badge render function. |
| `polygonOptions` | `object` | — | Cluster boundary polygon styling. |

### MapLayersControl

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `position` | `string` | `'top-1 right-1'` | Tailwind position classes. |
| `tileLayersLabel` | `string` | `'Map Type'` | Section label for tile layers. |
| `layerGroupsLabel` | `string` | `'Layers'` | Section label for layer groups. |

### MapTooltip

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'top'` | Arrow direction. |
| `sideOffset` | `number` | `15` | Distance from target element. |

### MapZoomControl

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `position` | `string` | `'top-1 left-1'` | Tailwind position classes. |

### MapFullscreenControl

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `position` | `string` | `'top-1 right-1'` | Tailwind position classes. |

### MapLocateControl

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `watch` | `boolean` | `false` | Continuously track location. |
| `onLocationFound` | `(event: LocationEvent) => void` | — | Called when location is found. |
| `onLocationError` | `(error: ErrorEvent) => void` | — | Called on location error. |
| `position` | `string` | `'right-1 bottom-1'` | Tailwind position classes. |

### MapSearchControl

Inherits all props from `PlaceAutocomplete`. Renders a search input on the map.

### MapDrawControl

Container for drawing tool buttons. Provides drawing mode context.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `className` | `string` | — | Additional CSS classes. |

### useLeaflet

Hook that lazy-loads the Leaflet library and its plugins.

```tsx
const { L, ready } = useLeaflet();
if (!ready) return ;
```

Returns `{ L: typeof Leaflet, ready: boolean }`.

---

# Mega Select
URL: /docs/web/components/mega-select

Mega Select component.

**Demo:**

```tsx
'use client';

import { useCallback } from 'react';

import { MegaSelect } from '@docyrus/ui/components/mega-select';
import { cn } from '@docyrus/ui/primitives/lib/utils';

import { PropControls } from '@/components/prop-controls';
import { useDemoData } from '@/data/mega-select-data';

export function MegaSelectDemo() {
  const { props, controls } = useDemoData();

  const handleChoose = useCallback((value: string) => {
    console.info('Chosen:', value);
  }, []);

  return (
    <div className="w-full">
      
      <div className={cn('mt-4 flex justify-center', props.size === 'full' && 'w-full')}>
        
      </div>
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-mega-select
```

**Dependencies:**
- [lucide-react](https://www.npmjs.com/package/lucide-react)
- [class-variance-authority](https://www.npmjs.com/package/class-variance-authority)

## Usage

```tsx
import {
  MegaSelect
} from "@docyrus/ui/components/mega-select";
import type {
  MegaSelectProps,
  MegaSelectSize,
  MegaSelectVariant,
  MegaSelectProviderProps,
  MegaSelectItemProps,
  MegaSelectSearchProps,
  MegaSelectCategoriesProps,
  MegaSelectGridProps,
  MegaSelectDetailProps,
  MegaSelectItem,
  MegaSelectCategory,
  MapToMegaSelectItemsConfig,
  MegaSelectContextValue
} from "@docyrus/ui/components/mega-select";

```

## Variants

| Variant | Description |
|---------|-------------|
| `default` | Default style |
| `elevated` | Elevated — `shadow-lg` |
| `flat` | Flat — `border-transparent shadow-none` |

## Sizes

| Size | Description |
|------|-------------|
| `thin` | thin — `w-90` |
| `default` | Default — `w-140` |
| `large` | large — `w-195` |
| `full` | full — `w-full` |

## Columns

| Columns | Description |
|---------|-------------|
| `auto` | Auto — `grid-cols-[repeat(auto-fill,minmax(220px,1fr))]` |

## API Reference

| Prop | Type | Default |
|------|------|---------|
| `columns` | `"auto"` | `"default"` |
| `className` | `string` | — |

## Components

| Component | Description |
|-----------|-------------|
| `MegaSelect` | Public export |
| `MegaSelectProvider` | Internal — `mega-select-context.tsx` |

## Type Exports

| Type | Description |
|------|-------------|
| `MegaSelectProps` | — |
| `MegaSelectSize` | — |
| `MegaSelectVariant` | — |
| `MegaSelectProviderProps` | — |
| `MegaSelectItemProps` | — |
| `MegaSelectSearchProps` | — |
| `MegaSelectCategoriesProps` | — |
| `MegaSelectGridProps` | — |
| `MegaSelectDetailProps` | — |
| `MegaSelectItem` | — |
| `MegaSelectCategory` | — |
| `MapToMegaSelectItemsConfig` | — |
| `MegaSelectContextValue` | — |

## Type Reference

### MegaSelectProps

| Field | Type | Description |
|-------|------|-------------|

### MegaSelectSize

`"thin"` | `"default"` | `"large"` | `"full"`

### MegaSelectVariant

`"default"` | `"elevated"` | `"flat"`

### MegaSelectProviderProps

| Field | Type | Description |
|-------|------|-------------|
| `children` | `ReactNode` | — |
| `items` | `MegaSelectItem<T>[]` | — |
| `categories` | `MegaSelectCategory[]` | — |
| `value` | `string \| null` | — |
| `defaultValue` | `string` | — |
| `disabled` | `boolean` | — |
| `loading` | `boolean` | — |
| `forceOpenDetail` | `boolean` | — |
| `restrictedValue` | `string` | — |
| `defaultColor` | `string` | — |
| `defaultIcon` | `string` | — |
| `searchable` | `boolean` | — |
| `onChoose` | `(value: string, item: MegaSelectItem<T>) => void` | — |
| `onSelectionChange` | `(value: string \| null, item: MegaSelectItem<T> \| null) => void` | — |
| `onClose` | `() => void` | — |

### MegaSelectItemProps

| Field | Type | Description |
|-------|------|-------------|

### MegaSelectSearchProps

`"onChange"`

### MegaSelectGridProps

| Field | Type | Description |
|-------|------|-------------|

### MegaSelectItem

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | — |
| `label` | `string` | — |
| `description` | `string` | — |
| `icon` | `string` | — |
| `image` | `string` | — |
| `color` | `string` | — |
| `categoryId` | `string` | — |
| `content` | `ReactNode` | — |
| `disabled` | `boolean` | — |
| `data` | `T` | — |

### MegaSelectCategory

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | — |
| `label` | `string` | — |
| `icon` | `string` | — |

### MapToMegaSelectItemsConfig

| Field | Type | Description |
|-------|------|-------------|
| `id` | `keyof R` | — |
| `label` | `keyof R` | — |
| `description` | `keyof R` | — |
| `icon` | `keyof R` | — |
| `image` | `keyof R` | — |
| `color` | `keyof R` | — |
| `categoryId` | `keyof R` | — |

### MegaSelectContextValue

| Field | Type | Description |
|-------|------|-------------|
| `items` | `MegaSelectItem<T>[]` | — |
| `filteredItems` | `MegaSelectItem<T>[]` | — |
| `categories` | `MegaSelectCategory[]` | — |
| `selectedId` | `string \| null` | — |
| `setSelectedId` | `(id: string \| null) => void` | — |
| `searchQuery` | `string` | — |
| `setSearchQuery` | `(query: string) => void` | — |
| `activeCategory` | `string \| null` | — |
| `setActiveCategory` | `(categoryId: string \| null) => void` | — |
| `detailItem` | `MegaSelectItem<T> \| null` | — |
| `setDetailItem` | `(item: MegaSelectItem<T> \| null) => void` | — |
| `disabled` | `boolean` | — |
| `loading` | `boolean` | — |
| `forceOpenDetail` | `boolean` | — |
| `restrictedValue` | `string \| undefined` | — |
| `defaultColor` | `string \| undefined` | — |
| `defaultIcon` | `string \| undefined` | — |
| `searchable` | `boolean` | — |
| `onChoose` | `(value: string, item: MegaSelectItem<T>) => void` | — |
| `onSelectionChange` | `(value: string \| null, item: MegaSelectItem<T> \| null) => void` | — |
| `onClose` | `() => void` | — |

---

# Morph Popover
URL: /docs/web/components/morph-popover

Morph Popover component with multiple variants and sizes.

**Demo:**

```tsx
'use client';
// @custom-demo

import { Sparkles } from 'lucide-react';

import { MorphPopover } from '@docyrus/ui/components/morph-popover';

export function MorphPopoverDemo() {
  return (
    <div className="flex min-h-90 items-center justify-center bg-background p-8">
      
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-morph-popover
```

**Dependencies:**
- [gsap](https://www.npmjs.com/package/gsap)

## Usage

```tsx
import {
  MorphPopover
} from "@docyrus/ui/components/morph-popover";

<MorphPopover
  trigger={...}
  triggerSize={DEFAULT_TRIGGER_SIZE}
  triggerWidth={0}
  triggerHeight={0}
  triggerRadius={0}
  triggerClassName="..."
  isOpen
  onOpenChange={() => {}}
  side="top"
  sideOffset={DEFAULT_SIDE_OFFSET}
  contentWidth={DEFAULT_CONTENT_WIDTH}
  speed={DEFAULT_SPEED}
  bgClassName="..."
  contentClassName="..."
/>
```

## API Reference

| Prop | Type | Default |
|------|------|---------|
| `trigger` | `ReactNode` | — |
| `triggerSize` | `number` | `DEFAULT_TRIGGER_SIZE` |
| `triggerWidth` | `number` | — |
| `triggerHeight` | `number` | — |
| `triggerRadius` | `number` | — |
| `triggerClassName` | `string` | — |
| `disabled` | `boolean` | `false` |
| `isOpen` | `boolean` | — |
| `onOpenChange` | `(open: boolean) => void` | — |
| `side` | `'top' \| 'bottom'` | `'top'` |
| `sideOffset` | `number` | `DEFAULT_SIDE_OFFSET` |
| `contentWidth` | `number` | `DEFAULT_CONTENT_WIDTH` |
| `speed` | `number` | `DEFAULT_SPEED` |
| `bgClassName` | `string` | — |
| `contentClassName` | `string` | — |
| `className` | `string` | — |

---

# Notification Stack
URL: /docs/web/components/notification-stack

A stacked notification card system with swipe-to-dismiss gestures, auto-pagination, action buttons, and animated transitions.

**Demo:**

```tsx
'use client';

import { useCallback, useState } from 'react';

import { type NotificationItem, NotificationStack } from '@docyrus/ui/components/notification-stack';

import {
  ArrowRight,
  ArrowUpRight,
  Check,
  Info,
  MessageSquare,
  Receipt,
  Rocket,
  X
} from 'lucide-react';

function createNotifications(startId: number): NotificationItem[] {
  return [
    {
      id: `${startId}`,
      type: 'comment',
      variant: 'unread',
      icon: 'OA',
      badge: ,
      title: (
        <>
          Oguz Aksu <span className="font-normal text-muted-foreground">commented on</span> Project Alpha
        </>
      ),
      content: (
        <div className="bg-muted p-2 rounded-md border border-border italic">
          &quot;Let&apos;s review the Q3 roadmap before the sprint planning session next week.&quot;
        </div>
      ),
      timestamp: '2m ago',
      showUnreadIndicator: true,
      actions: [{ label: 'Reply', variant: 'default' }, { label: 'View Thread', variant: 'link', icon:  }]
    },
    {
      id: `${startId + 1}`,
      type: 'approval',
      variant: 'unread',
      icon: ,
      title: 'Expense Approval for Q3 Travel',
      subtitle: (
        <>
          Requested by <span className="font-medium text-foreground">Sarah Jenkins</span> &bull; $1,240.50
        </>
      ),
      timestamp: '1h ago',
      showUnreadIndicator: true,
      actions: [{ label: 'Approve', variant: 'primary', icon:  }, { label: 'Deny', variant: 'danger', icon:  }]
    },
    {
      id: `${startId + 2}`,
      type: 'status',
      variant: 'default',
      icon: ,
      title: 'Update status for Project Apollo',
      subtitle: 'Weekly check-in required for the enterprise deal.',
      timestamp: '3h ago',
      actions: [{ label: 'Update Status', variant: 'default' }, { label: 'View Project', variant: 'link', icon:  }]
    },
    {
      id: `${startId + 3}`,
      type: 'info',
      variant: 'default',
      icon: ,
      title: 'New workspace features available',
      subtitle: 'Enhanced dashboard analytics and team collaboration tools are now live.',
      timestamp: '1d ago'
    },
    {
      id: `${startId + 4}`,
      type: 'success',
      variant: 'default',
      icon: ,
      title: 'Deployment succeeded',
      subtitle: 'Production release v2.4.1 deployed successfully.',
      timestamp: '2d ago'
    }
  ];
}

export function NotificationStackDemo() {
  const [notifications, setNotifications] = useState<NotificationItem[]>(
    () => createNotifications(1)
  );
  const [nextId, setNextId] = useState(6);

  const handleLoadMore = useCallback(() => {
    const newNotifications = createNotifications(nextId);

    setNotifications(prev => [...prev, ...newNotifications]);
    setNextId(prev => prev + 5);
  }, [nextId]);

  return (
    <div className="flex items-center justify-center py-8">
      <NotificationStack
        notifications={notifications}
        maxVisible={10}
        loadMoreThreshold={2}
        onLoadMore={handleLoadMore}
        onDismiss={(id) => {
          console.info(`Dismissed: ${id}`);
        }}
        onClick={(id) => {
          console.info(`Clicked: ${id}`);
        }}
        onAction={(id, action) => {
          console.info(`Action: ${id} - ${action}`);
          setNotifications(prev => prev.filter(n => n.id !== id));
        }} />
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-notification-stack
```

**Dependencies:**
- [lucide-react](https://www.npmjs.com/package/lucide-react)
- [motion](https://www.npmjs.com/package/motion)
- [@emotion/is-prop-valid](https://www.npmjs.com/package/@emotion/is-prop-valid)
- [class-variance-authority](https://www.npmjs.com/package/class-variance-authority)

## Usage

```tsx
import {
  NotificationStack
} from '@docyrus/ui/components/notification-stack';
import type { NotificationItem } from '@docyrus/ui/components/notification-stack';

const notifications: NotificationItem[] = [
  {
    id: '1',
    type: 'success',
    title: 'Deployment complete',
    message: 'Your app has been deployed successfully.',
    actions: [{ label: 'View' }]
  },
  {
    id: '2',
    type: 'warning',
    title: 'Storage warning',
    message: 'You are using 90% of your storage quota.'
  },
  {
    id: '3',
    type: 'info',
    title: 'New feature',
    message: 'Dark mode is now available in settings.',
    variant: 'unread'
  }
];

<NotificationStack
  notifications={notifications}
  onDismiss={(id) => console.log('dismissed', id)}
  onClick={(id) => console.log('clicked', id)}
  onAction={(id, action) => console.log('action', id, action)}
/>
```

### With Pagination & Load More

```tsx
<NotificationStack
  notifications={notifications}
  maxVisible={5}
  loadMoreThreshold={2}
  onLoadMore={() => fetchMoreNotifications()}
  onDismiss={handleDismiss}
  emptyState={<p>No notifications</p>}
/>
```

## Variants

| Variant | Description |
|---------|-------------|
| `default` | Standard notification cards. |
| `bordered` | Cards with enhanced shadow (`shadow-md`). |

## Sizes

| Size | Description |
|------|-------------|
| `sm` | Compact padding and smaller text. |
| `default` | Standard sizing. |
| `lg` | Larger padding and text. |

## Components

| Component | Description |
|-----------|-------------|
| `NotificationStack` | Main container. Manages stacking, pagination, and dismissed state. |
| `NotificationStackCard` | Individual notification card with swipe-to-dismiss gesture. |

## API Reference

### NotificationStack

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `notifications` | `NotificationItem[]` | — | Array of notification items to display. |
| `maxVisible` | `number` | `10` | Maximum number of visible cards before pagination. |
| `loadMoreThreshold` | `number` | `2` | When remaining count reaches this threshold, `onLoadMore` is triggered. |
| `onLoadMore` | `() => void` | — | Called when more notifications should be fetched. |
| `onDismiss` | `(id: string) => void` | — | Called when a notification is swiped away. |
| `onClick` | `(id: string) => void` | — | Called when a notification card is clicked. |
| `onAction` | `(id: string, action: string) => void` | — | Called when an action button is clicked. |
| `variant` | `'default' \| 'bordered'` | `'default'` | Visual style. |
| `size` | `'sm' \| 'default' \| 'lg'` | `'default'` | Card sizing. |
| `emptyState` | `ReactNode` | — | Content shown when no notifications exist. |
| `className` | `string` | — | Additional CSS classes. |

## Type Reference

### NotificationItem

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | Unique identifier. |
| `type` | `'default' \| 'success' \| 'warning' \| 'error' \| 'info'` | Notification type (determines icon and color). |
| `title` | `string` | Notification title. |
| `message` | `string` | Notification body text. |
| `icon` | `ReactNode \| string` | Custom icon override. |
| `badge` | `ReactNode` | Badge content displayed alongside the notification. |
| `actions` | `Array<{ label: string; onClick?: () => void }>` | Action buttons displayed at the bottom. |
| `variant` | `'default' \| 'unread' \| 'highlighted'` | Visual variant for the individual card. |

### Interaction Details

- **Swipe to dismiss**: Drag horizontally past 100px or at 500px/s velocity.
- **Stacking**: Cards stack with scale reduction (5% per level) and vertical offset (10px per level).
- **Pointer events**: Only the top card is interactive; stacked cards below are visual-only.
- **Auto-dismiss on action**: Cards are dismissed after an action button click.

---

# Notifications Panel
URL: /docs/web/components/notifications-panel

Notifications Panel component with multiple variants and sizes.

**Demo:**

```tsx
'use client';

import { useState } from 'react';

import { NotificationsPanel } from '@docyrus/ui/components/notifications-panel';
import {
  MessageSquare, Receipt, Rocket, Info, Check, X, ArrowUpRight, ArrowRight
} from 'lucide-react';

export function NotificationsPanelDemo() {
  const [activeTab, setActiveTab] = useState<'all' | 'requests' | 'mentioned'>('all');

  const allNotifications = [
    {
      id: '1',
      type: 'comment' as const,
      variant: 'default' as const,
      icon: 'OA',
      badge: ,
      title: (
        <>
          Oğuz Aksu <span className="font-normal text-muted-foreground">commented on</span> Google
        </>
      ),
      content: (
        <div className="bg-muted p-2 rounded-md border border-border italic">
          "We need to follow up on the Q3 expansion plans before the next board meeting. Can you check the latest financials?"
        </div>
      ),
      timestamp: '2m ago',
      actions: [
        { label: 'Reply', variant: 'default' as const },
        {
          label: 'View Google',
          variant: 'link' as const,
          icon: 
        }
      ]
    },
    {
      id: '2',
      type: 'approval' as const,
      variant: 'unread' as const,
      icon: ,
      title: 'Expense Approval for Q3 Travel',
      subtitle: (
        <>
          Requested by <span className="font-medium text-foreground">Sarah Jenkins</span> • $1,240.50
        </>
      ),
      timestamp: '1h ago',
      showUnreadIndicator: true,
      actions: [
        {
          label: 'Approve',
          variant: 'primary' as const,
          icon: 
        },
        {
          label: 'Deny',
          variant: 'danger' as const,
          icon: 
        }
      ]
    },
    {
      id: '3',
      type: 'status' as const,
      variant: 'default' as const,
      icon: ,
      title: 'Update status for Project Apollo',
      subtitle: 'Weekly check-in required for ongoing enterprise deal.',
      timestamp: '3h ago',
      actions: [
        { label: 'Update Status', variant: 'default' as const },
        {
          label: 'View Project',
          variant: 'link' as const,
          icon: 
        }
      ]
    },
    {
      id: '4',
      type: 'info' as const,
      variant: 'default' as const,
      icon: ,
      title: 'Welcome to the new workspace',
      subtitle: "We've updated the dashboard to help you track your leads more efficiently. Take a quick tour to see what's new.",
      timestamp: '1d ago'
    }
  ];

  const filteredNotifications = allNotifications.filter((notification) => {
    if (activeTab === 'requests') {
      return notification.type === 'approval' || notification.type === 'status';
    }
    if (activeTab === 'mentioned') {
      return notification.type === 'comment';
    }

    return true;
  });

  const tabs = [
    {
      label: 'All Notifications',
      count: allNotifications.length,
      active: activeTab === 'all',
      onClick: () => setActiveTab('all')
    },
    {
      label: 'Requests',
      count: allNotifications.filter(n => n.type === 'approval' || n.type === 'status').length,
      active: activeTab === 'requests',
      onClick: () => setActiveTab('requests')
    },
    {
      label: 'Mentioned',
      count: allNotifications.filter(n => n.type === 'comment').length,
      active: activeTab === 'mentioned',
      onClick: () => setActiveTab('mentioned')
    }
  ];

  return (

    <NotificationsPanel
      title="Notifications"
      headerAction={
        <button className="flex items-center gap-1.5 px-3 py-1.5 text-xs font-medium text-muted-foreground bg-card border border-border rounded-md hover:bg-muted/50 hover:text-foreground transition-colors shadow-sm">
          
          Mark all as read
        </button>
      }
      tabs={tabs}
      notifications={filteredNotifications}
      footer={
        <button className="text-xs font-medium text-muted-foreground hover:text-foreground transition-colors flex items-center gap-1">
          Load older notifications
          <svg className="h-4 w-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
            <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M19 9l-7 7-7-7" />
          </svg>
        </button>
      }
      onNotificationAction={(id, action) => {
        console.info(`Notification ${id}: ${action}`);
      }} />

  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-notifications-panel
```

**Dependencies:**
- [class-variance-authority](https://www.npmjs.com/package/class-variance-authority)

## Usage

```tsx
import {
  NotificationsPanel
} from "@docyrus/ui/components/notifications-panel";

<NotificationsPanel
  variant="default"
  size="sm"
  ref={...}
  title="Notifications"
  headerAction={...}
  tabs={...}
  label="..."
  count={0}
  active
  onClick={() => {}}
  notifications={NotificationItem[]}
  footer={...}
  onNotificationAction={() => {}}
/>
```

## Variants

| Variant | Description |
|---------|-------------|
| `default` | Default style |
| `elevated` | Elevated — `shadow-md` |

## Sizes

| Size | Description |
|------|-------------|
| `sm` | Small — `max-w-sm` |
| `default` | Default — `max-w-md` |
| `lg` | Large — `max-w-lg` |
| `full` | full — `w-full` |

## API Reference

| Prop | Type | Default |
|------|------|---------|
| `variant` | `"default"` \| `"elevated"` | `"default"` |
| `size` | `"sm"` \| `"default"` \| `"lg"` \| `"full"` | `"default"` |
| `ref` | `Ref<HTMLDivElement>` | — |
| `title` | `string` | `'Notifications'` |
| `headerAction` | `ReactNode` | — |
| `tabs` | `unknown` | — |
| `label` | `string` | — |
| `count` | `number` | — |
| `active` | `boolean` | — |
| `onClick` | `() => void` | — |
| `notifications` | `Array<NotificationItem>` | — |
| `footer` | `ReactNode` | — |
| `onNotificationAction` | `(notificationId: string, action: string) => void` | — |
| `className` | `string` | — |

---

# Pivot Calendar
URL: /docs/web/components/pivot-calendar

Calendar component that pivots time-based statistics across four layouts — full month, days of a week, days of a month, or months of a year — with grouping, tooltips, and local or remote aggregation.

**Demo:**

```tsx
'use client';
// @custom-demo

import {
  useMemo,
  useState
} from 'react';

import {
  PivotCalendar,
  type IPivotCalendarGroup,
  type IPivotCalendarMeasure,
  type IPivotCalendarRemoteCell,
  type TPivotCalendarMode
} from '@docyrus/ui/components/pivot-calendar';
import { useMounted } from '@docyrus/ui/primitives/hooks/use-mounted';
import {
  Tabs,
  TabsList,
  TabsTrigger
} from '@docyrus/ui/primitives/ui/tabs';
import { cn } from '@docyrus/ui/primitives/lib/utils';

import {
  buildAggregatedCells,
  generateWorkTimeEntries,
  USERS,
  type WorkTimeEntry
} from '@/data/pivot-calendar-data';

function formatHours(seconds: number): string {
  if (!seconds) return '0h';
  const hours = seconds / 3600;
  const rounded = Math.round(hours * 10) / 10;

  return `${rounded}h`;
}

const DEMO_MEASURES: Array
            
          
        
      </div>

      {mode === 'local' ? (
        <PivotCalendar<WorkTimeEntry>
          className="w-full"
          mode="local"
          data={localData}
          getDate={row => row.date}
          measures={DEMO_MEASURES}
          groupBy={{
            id: 'user',
            label: 'User',
            getId: row => row.user.id,
            getGroup: (row) => {
              const user = USERS.find(u => u.id === row.user.id);

              return {
                id: row.user.id,
                label: row.user.name,
                image: row.user.photo ? { signed_url: row.user.photo, file_name: row.user.name } : null,
                color: user?.color
              };
            }
          }}
          groups={groups}
          defaultView="month-calendar" />
      ) : (
        <PivotCalendar<WorkTimeEntry>
          className="w-full"
          mode="remote"
          cells={remoteCells}
          measures={DEMO_MEASURES}
          groupBy={{
            id: 'user',
            label: 'User',
            getId: row => row.user.id
          }}
          groups={groups}
          defaultView="month-calendar" />
      )}
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-pivot-calendar
```

**Dependencies:**
- [lucide-react](https://www.npmjs.com/package/lucide-react)
- [date-fns](https://www.npmjs.com/package/date-fns)
- [class-variance-authority](https://www.npmjs.com/package/class-variance-authority)

## Overview

`PivotCalendar` represents statistical totals on top of a calendar surface. It supports up to **four measures per cell** rendered as a 2×1 or 2×2 micro-grid with hover tooltips, an optional grouping category sidebar (used as filters in the month view, as row axis on the pivot grid views), and four visual layouts:

| View | Layout | Buckets | Use it for |
|------|--------|---------|------------|
| `month-calendar` | Standard month grid | Per day (`yyyy-MM-dd`) | Glanceable monthly overview |
| `days-of-week` | Pivot grid · groups × days of selected week | Per day (`yyyy-MM-dd`) | Weekly comparison across categories |
| `days-of-month` | Pivot grid · groups × days of selected month, scrolls horizontally | Per day (`yyyy-MM-dd`) | Detailed monthly comparison |
| `months-of-year` | Pivot grid · groups × months of selected year | Per month (`yyyy-MM`) | Long-term yearly trend |

## Calculation modes

The `mode` prop controls where aggregation happens.

### Local mode

Pass raw rows. The component buckets and aggregates each measure on the client based on `getDate` and the optional `groupBy.getId`:

```tsx
<PivotCalendar
  mode="local"
  data={timeEntries}
  getDate={row => row.date}
  measures={[
    { id: 'planned', label: 'Planned', aggregate: 'sum', getValue: r => r.duration_planned, formatValue: formatHours },
    { id: 'logged',  label: 'Logged',  aggregate: 'sum', getValue: r => r.duration_logged,  formatValue: formatHours }
  ]}
  groupBy={{
    id: 'user',
    label: 'User',
    getId: row => row.user.id,
    getGroup: row => ({ id: row.user.id, label: row.user.name, image: { signed_url: row.user.photo } })
  }}
/>
```

### Remote mode

Pass pre-aggregated `cells` keyed by bucket and group. The component only renders, never calculates:

```tsx
<PivotCalendar
  mode="remote"
  cells={cellsFromServer}            // [{ bucket: '2026-05-06', groupId: 'u1', values: [...] }, ...]
  measures={measures}
  groupBy={{ id: 'user', label: 'User', getId: row => row.user.id }}
  groups={users}
/>
```

The bucket key must match the active view: `yyyy-MM-dd` for day-based views (`month-calendar`, `days-of-week`, `days-of-month`) and `yyyy-MM` for `months-of-year`.

## Drill down on stat clicks

`PivotCalendar` exposes an `onCellClick` callback that fires whenever the user clicks a measure tile (in the calendar month view) or a value cell (in any pivot grid view). Tiles with a zero value stay non-interactive; tiles with a value render as `<button>` elements with hover / focus / "Click to drill down" tooltip styling whenever a handler is wired.

```tsx
<PivotCalendar
  mode="remote"
  cells={cells}
  measures={measures}
  groupBy={{ id: 'user', label: 'User', getId: row => row.user.id }}
  groups={users}
  onCellClick={(info) => {
    console.log(info.bucket, info.bucketStart, info.bucketEnd);
    console.log(info.measure.label, info.value, info.formattedValue);
    console.log(info.groupId, info.group?.label);
  }}
/>
```

The component itself is intentionally agnostic about what to do with the click — it does **not** ship a drilldown dialog. Pair it with `useDocyrusPivotCalendar` and its `buildDrilldownQuery` helper for Docyrus-backed apps, or build your own dialog around any data source.

### `IPivotCalendarCellClick`

| Field | Type | Description |
|-------|------|-------------|
| `bucket` | `string` | Bucket key (`yyyy-MM-dd` or `yyyy-MM`). |
| `bucketStart` | `Date` | Inclusive start of the bucket's range. |
| `bucketEnd` | `Date` | Inclusive end of the bucket's range (end-of-day or end-of-month). |
| `view` | `TPivotCalendarView` | View active at the time of the click. |
| `groupId` | `string \| null` | Group id when `groupBy` is configured. `null` for the "Totals" row or ungrouped totals. |
| `group` | `IPivotCalendarGroup \| undefined` | Resolved group entry when available. |
| `measure` | `IPivotCalendarMeasure<TData>` | Measure descriptor for the clicked tile. |
| `value` | `number` | Raw aggregated value. |
| `formattedValue` | `string` | Pre-formatted display value (e.g. `1.5h`). |

## Usage

```tsx
import {
  PivotCalendar,
  type IPivotCalendarMeasure,
  type IPivotCalendarRemoteCell,
  type TPivotCalendarMode
} from '@docyrus/ui/components/pivot-calendar';

const measures: Array<IPivotCalendarMeasure<TimeEntry>> = [
  { id: 'planned', label: 'Planned', aggregate: 'sum', getValue: r => r.duration_planned, formatValue: s => `${(s/3600).toFixed(1)}h` },
  { id: 'logged',  label: 'Logged',  aggregate: 'sum', getValue: r => r.duration_logged,  formatValue: s => `${(s/3600).toFixed(1)}h` }
];

<PivotCalendar
  mode="local"
  data={data}
  getDate={row => row.date}
  measures={measures}
  groupBy={{ id: 'user', label: 'User', getId: row => row.user.id }}
  groups={users}
  defaultView="month-calendar"
/>
```

## Sizes

| Size | Description |
|------|-------------|
| `sm` | Compact — `min-h-[480px]` |
| `default` | Default — `min-h-[600px]` |
| `lg` | Tall — `min-h-[720px]` |

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `mode` | `'local' \| 'remote'` | `'local'` | Calculation mode. |
| `data` | `Array<TData>` | — | Raw rows. Required when `mode='local'`. |
| `cells` | `Array<IPivotCalendarRemoteCell>` | — | Pre-aggregated cells. Required when `mode='remote'`. |
| `getDate` | `(row: TData) => Date \| string` | — | Reads the date for a row. Required when `mode='local'`. |
| `measures` | `Array<IPivotCalendarMeasure<TData>>` | — | Measures to display. Up to 4 are rendered per cell. |
| `groupBy` | `IPivotCalendarGroupBy<TData>` | — | Optional grouping category. Enables the side panel + pivot row axis. |
| `groups` | `Array<IPivotCalendarGroup>` | — | Group catalog (required for `mode='remote'` with `groupBy`). |
| `defaultView` | `TPivotCalendarView` | `'month-calendar'` | Initial view. |
| `view` | `TPivotCalendarView` | — | Controlled view value. |
| `onViewChange` | `(view: TPivotCalendarView) => void` | — | Called when view changes. |
| `defaultDate` | `Date` | `new Date()` | Initial reference date. |
| `date` | `Date` | — | Controlled reference date. |
| `onDateChange` | `(date: Date) => void` | — | Called when reference date changes. |
| `defaultSelectedGroupIds` | `Array<string>` | All | Initial selected groups. |
| `selectedGroupIds` | `Array<string>` | — | Controlled group selection. |
| `onSelectedGroupIdsChange` | `(ids: Array<string>) => void` | — | Called when group selection changes. |
| `visibleViews` | `Array<TPivotCalendarView>` | All | Views shown in the toolbar tabs. |
| `hideViewSwitcher` | `boolean` | `false` | Hide the view switcher tabs. |
| `hideSidebar` | `boolean` | `false` | Hide the group side panel (only used by `month-calendar`). |
| `title` | `ReactNode` | range label | Custom toolbar title. |
| `onCellClick` | `(info: IPivotCalendarCellClick<TData>) => void` | — | Fires when the user clicks a stat tile or pivot value cell. Tiles become interactive (hover ring + focus outline + drill-down hint) only when this prop is set. |
| `size` | `'sm' \| 'default' \| 'lg'` | `'default'` | Min height variant. |
| `className` | `string` | — | Extra wrapper classes. |

## Components

| Component | Description |
|-----------|-------------|
| `PivotCalendar` | Public root component |
| `pivotCalendarVariants` | CVA helper for the wrapper container |
| `usePivotCalendarController` | Standalone controller hook (advanced compositions) |

## Type Exports

| Type | Description |
|------|-------------|
| `PivotCalendarProps<TData>` | Component prop shape |
| `PivotCalendarRootProps<TData>` | Root component (props + size variant) |
| `IPivotCalendarController<TData>` | Controller returned by the hook |
| `IPivotCalendarMeasure<TData>` | Measure descriptor |
| `IPivotCalendarMeasureValue` | A measure result `{ measureId, value }` |
| `IPivotCalendarGroup` | Group entry used in the sidebar / row axis |
| `IPivotCalendarGroupBy<TData>` | Grouping dimension descriptor |
| `IPivotCalendarRemoteCell` | Pre-aggregated cell `{ bucket, groupId?, values }` |
| `IPivotCalendarCellClick<TData>` | Payload emitted by `onCellClick` when a stat tile is clicked |
| `TPivotCalendarView` | View id |
| `TPivotCalendarMode` | `'local' \| 'remote'` |
| `TPivotCalendarAggregate` | `'sum' \| 'count' \| 'avg' \| 'min' \| 'max'` |
| `TPivotCalendarBucketKind` | `'day' \| 'weekday' \| 'month'` |

## Type Reference

### IPivotCalendarMeasure

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | Unique measure id |
| `label` | `string` | Tooltip label |
| `shortLabel` | `string` | Compact label shown in the cell (defaults to `label`) |
| `aggregate` | `TPivotCalendarAggregate` | Aggregation strategy used in `local` mode |
| `getValue` | `(row: TData) => number \| null \| undefined` | Reads the numeric value from a row |
| `formatValue` | `(value: number) => string` | Formats the displayed value (e.g. `1.5h`) |
| `color` | `string` | CSS color of the dot accent |
| `description` | `string` | Extra context shown in the tooltip |

### IPivotCalendarRemoteCell

| Field | Type | Description |
|-------|------|-------------|
| `bucket` | `string` | `yyyy-MM-dd` (day views) or `yyyy-MM` (month view) |
| `groupId` | `string \| null` | Group id when `groupBy` is configured |
| `values` | `Array<IPivotCalendarMeasureValue>` | One entry per measure |

### TPivotCalendarView

`'month-calendar' \| 'days-of-week' \| 'days-of-month' \| 'months-of-year'`

---

# PivotFilter
URL: /docs/web/components/pivot-filter

Horizontal or vertical strip of count-tagged pills used to quickly slice a list by one dimension — status, user, date bucket, or any other categorical value.

**Demo:**

```tsx
'use client';

import { useState } from 'react';

import {
  PivotFilter,
  type PivotFilterItem
} from '@docyrus/ui/components/pivot-filter';
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue
} from '@docyrus/ui/primitives/ui/select';
import { Switch } from '@docyrus/ui/primitives/ui/switch';
import { cn } from '@docyrus/ui/primitives/lib/utils';

const STATUS_ITEMS: Array
                  
                    
                    
                  
                
              </div>
              <label className="flex items-center gap-2">
                
                <span className="text-xs">vertical</span>
              </label>
              <label className="flex items-center gap-2">
                
                <span className="text-xs">compact</span>
              </label>
              <label className="flex items-center gap-2">
                
                <span className="text-xs">loading</span>
              </label>
              <label className="flex items-center gap-2">
                
                <span className="text-xs">hideZeroValues</span>
              </label>
              <label className="flex items-center gap-2">
                
                <span className="text-xs">refresh button</span>
              </label>
              <label className="flex items-center gap-2">
                
                <span className="text-xs">settings slot</span>
              </label>
            </div>
          </div>
        </div>
      </div>

      <div className={cn('flex', vertical ? 'h-72 max-w-xs' : 'w-full')}>
        
      
    </div>
  } />
```

The popover open state is internal by default; pass `settingsOpen` + `onSettingsOpenChange` if you need to control it.

### Loading state

Pass `loading` while items are being fetched. The component renders two skeleton pills while keeping the "All" pill mounted so the selection is not lost.

```tsx

```

## Colors

Pills accent on selection. The accent color is derived from each item's `color` field through this pipeline:

1. If `color` already includes a Tailwind shade (e.g. `'emerald-600'`, `'rose-300'`), use it as-is.
2. Otherwise treat it as a family name and append `-500` (e.g. `'sky'` → `'sky-500'`).
3. Resolve the resulting token to a hex value through `resolveColorHex` (it also accepts hex / rgb / hsl / CSS variables as-is).
4. When `color` is omitted, the pill falls back to `sky-500`.

This means status / select / radio-group options that already carry a `color` value from Docyrus enum metadata work without any extra mapping.

## Empty items

Items flagged `isEmpty: true` are treated as the "Not Set" bucket:

- they render with a muted (`opacity-60`) style,
- they are **automatically hidden** when their `stat` is `0`, regardless of `hideZeroValues`,
- they are still emitted via `onSelect` when the user taps them.

## Hiding zero-count items

Set `hideZeroValues` to hide every item whose `stat === 0`, except the currently selected one (so the user can always reset). Use this when buckets are dynamically derived (e.g. user list, date buckets) and you don't want empty pills crowding the strip.

## API Reference

### `<PivotFilter>`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `items` | `Array<PivotFilterItem>` | — | Items rendered in the strip. |
| `selectedItemId` | `string \| null` | — | Currently selected item id, or `null` when the "All" pill is active. |
| `onSelect` | `(item: PivotFilterItem \| null) => void` | — | Fired when an item is selected. The "All" pill fires with `null`. |
| `total` | `number` | — | Aggregate stat displayed on the "All" pill. |
| `totalLabel` | `string` | translated `"All"` | Label for the "All" pill. |
| `loading` | `boolean` | `false` | Renders two skeleton pills instead of items. |
| `vertical` | `boolean` | `false` | Vertical column layout. |
| `compact` | `boolean` | `false` | Collapse name + stat onto a single row inside each pill. |
| `hideZeroValues` | `boolean` | `false` | Hide items whose `stat === 0` (except the currently selected one). |
| `hideAllPill` | `boolean` | `false` | Hide the "All" pill — use when a filter is required. |
| `onRefresh` | `() => void` | — | Refresh button click handler. Pass `undefined` to hide the refresh button. |
| `settingsContent` | `ReactNode` | — | Content rendered inside the settings popover. When `undefined`, the gear button is hidden. |
| `settingsOpen` | `boolean` | uncontrolled | Controlled open state for the settings popover. |
| `onSettingsOpenChange` | `(open: boolean) => void` | — | Called when the popover open state changes. |
| `emptyState` | `ReactNode` | built-in | Custom placeholder when there are no items and the "All" pill is hidden. |
| `className` | `string` | — | Wrapper class name. |

### `PivotFilterItem`

| Field | Type | Description |
|------|------|-------------|
| `id` | `string` | Stable identifier. Used to match `selectedItemId`. |
| `name` | `string` | Display label rendered in the pill. |
| `stat` | `number` | Numeric value shown on the right side of the pill (count, sum, etc.). |
| `secondary` | `string` | Secondary text (e.g. `"to 14"` for hours, `"01.01 - 07.01"` for week ranges). |
| `color` | `string` | Tailwind color token (e.g. `'sky'`, `'emerald-500'`) or hex. Drives selection accents. |
| `icon` | `string` | Docyrus icon identifier (e.g. `'huge building-06'`, `'fal star'`). Rendered via `DocyrusIcon`. |
| `user` | `PivotFilterUser` | When present, an avatar is rendered instead of an icon. |
| `isEmpty` | `boolean` | Marks the synthetic "Not Set" bucket — muted style, auto-hidden at `stat === 0`. |
| `meta` | `Record<string, unknown>` | Arbitrary payload returned to `onSelect`. Not read by the component. |

### `PivotFilterUser`

| Field | Type | Description |
|------|------|-------------|
| `id` | `string` | User id. |
| `name` | `string` | Display name. Initial is used as the avatar fallback. |
| `picturePath` | `string \| null` | Avatar URL. Falls back to initials when absent. |

## Components

| Component | Description |
|-----------|-------------|
| `PivotFilter` | Main strip — orchestrates toolbar, "All" pill, item list, loading state. |
| `PivotFilterPill` | Internal pill renderer — exported for advanced custom layouts. |

## Type Exports

| Type | Description |
|------|-------------|
| `PivotFilterItem` | Item shape — id, name, stat, plus optional icon / user / color / secondary / isEmpty / meta. |
| `PivotFilterProps` | Component prop shape. |
| `PivotFilterUser` | `{ id, name, picturePath? }` for the user-rendered variant. |

## i18n keys

The component reads these keys via `useUiTranslation()`. English fallbacks are bundled, so no provider is required.

| Key | Default |
|------|---------|
| `ui.pivotFilter.all` | `All` |
| `ui.pivotFilter.refresh` | `Refresh` |
| `ui.pivotFilter.settings` | `Settings` |
| `ui.pivotFilter.empty` | `No data` |

## When to reach for the hook

If you want the same UI bound to a Docyrus data source — auto-running a pivot query with `COUNT_OF_id` (or any other aggregate), reacting to active filters, and emitting a query rule when the user picks a bucket — use [`useDocyrusPivotFilter`](/docs/web/hooks/use-docyrus-pivot-filter) instead. It produces the `items` / `total` / `loading` / `onRefresh` / `settingsContent` props for you.

---

# Pivot Grid
URL: /docs/web/components/pivot-grid

A standalone pivot grid with 3-level row and column hierarchies, subtotals, grand totals, drilldown, pinning, resizing, and export.

**Demo:**

```tsx
'use client';
// @custom-demo

import {
  useCallback,
  useEffect,
  useMemo,
  useState
} from 'react';

import {
  PivotGridToolbar,
  PivotGridView, usePivotGrid
} from '@docyrus/ui/components/pivot-grid';
import { useMounted } from '@docyrus/ui/primitives/hooks/use-mounted';
import {
  AwesomeDialog,
  AwesomeDialogBody,
  AwesomeDialogHeader
} from '@docyrus/ui/components/awesome-dialog';
import { Button } from '@docyrus/ui/primitives/ui/button';
import { Switch } from '@docyrus/ui/primitives/ui/switch';
import { cn } from '@docyrus/ui/primitives/lib/utils';
import {
  ChevronDownIcon,
  Maximize2Icon,
  Settings2Icon
} from 'lucide-react';

import {
  createPivotGridDemoRows,
  pivotGridDemoColorRules,
  pivotGridDemoColumnDimensions,
  pivotGridDemoMeasures,
  pivotGridDemoRowDimensions,
  type PivotGridDemoRow
} from '@ui/components/pivot-grid/pivot-grid-demo-data';

interface PivotGridDemoSurfaceProps {
  enableColorRules: boolean;
  pinGrandTotals: boolean;
  showConfigure: boolean;
  onEnableColorRulesChange: (value: boolean) => void;
  onPinGrandTotalsChange: (value: boolean) => void;
  onShowConfigureChange: (value: boolean) => void;
  height: number | 'auto';
  showFullscreenButton?: boolean;
  onOpenFullscreen?: () => void;
}

function PivotGridDemoSurface({
  enableColorRules,
  pinGrandTotals,
  showConfigure,
  onEnableColorRulesChange,
  onPinGrandTotalsChange,
  onShowConfigureChange,
  height,
  showFullscreenButton = false,
  onOpenFullscreen
}: PivotGridDemoSurfaceProps) {
  const data = useMemo(() => createPivotGridDemoRows({
    regions: 2,
    countriesPerRegion: 2,
    citiesPerCountry: 2,
    years: 2,
    quarters: 2,
    channels: 2
  }), []);
  const measures = useMemo(() => pivotGridDemoMeasures.slice(0, 2), []);
  const getRowId = useCallback((row: PivotGridDemoRow) => row.id, []);

  const controller = usePivotGrid({
    data,
    rowDimensions: pivotGridDemoRowDimensions,
    columnDimensions: pivotGridDemoColumnDimensions,
    measures,
    getRowId,
    cellColorRules: enableColorRules ? pivotGridDemoColorRules : undefined,
    height,
    className: height === 'auto' ? 'min-h-0 flex-1' : undefined
  });
  const {
    pinColumns,
    table,
    unpinColumns,
    visibleLeafColumns
  } = controller;

  useEffect(() => {
    const grandTotalColumnIds = visibleLeafColumns
      .filter(column => column.kind === 'grand-total')
      .map(column => column.id);

    if (grandTotalColumnIds.length === 0) {
      return;
    }

    const hasPinnedGrandTotals = grandTotalColumnIds.every(
      columnId => table.getColumn(columnId)?.getIsPinned() === 'right'
    );

    if (pinGrandTotals) {
      if (!hasPinnedGrandTotals) {
        pinColumns(grandTotalColumnIds, 'right');
      }

      return;
    }

    if (hasPinnedGrandTotals) {
      unpinColumns(grandTotalColumnIds);
    }
  }, [
    pinColumns,
    table,
    unpinColumns,
    visibleLeafColumns,
    pinGrandTotals
  ]);

  return (
    <div className={cn('w-full space-y-3', height === 'auto' && 'flex min-h-0 flex-1 flex-col')}>
      
            ) : null}
            
          </>
        )} />

      <div
        className={cn(
          'grid transition-[grid-template-rows] duration-300 ease-in-out',
          showConfigure ? 'grid-rows-[1fr]' : 'grid-rows-[0fr]'
        )}>
        <div className="overflow-hidden">
          <div className="grid gap-4 rounded-lg border bg-muted/30 p-4 sm:grid-cols-2">
            <label className="flex items-center justify-between gap-3 rounded-md border bg-background px-3 py-2 text-sm">
              <span>Enable JSONata color rules</span>
              
      
    </>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-pivot-grid
```

**Dependencies:**
- [@tanstack/react-table](https://www.npmjs.com/package/@tanstack/react-table)
- [@tanstack/react-virtual](https://www.npmjs.com/package/@tanstack/react-virtual)
- [jsonata](https://www.npmjs.com/package/jsonata)
- [exceljs](https://www.npmjs.com/package/exceljs)
- [html2canvas-pro](https://www.npmjs.com/package/html2canvas-pro)
- [pdf-lib](https://www.npmjs.com/package/pdf-lib)

## Usage

```tsx
import {
  PivotGridToolbar,
  PivotGridView,
  usePivotGrid,
  type PivotGridCellColorRule,
  type PivotGridDimension,
  type PivotGridMeasure
} from '@docyrus/ui/components/pivot-grid';

const rowDimensions: PivotGridDimension<SalesRow>[] = [
  { id: 'region', label: 'Region', getValue: row => row.region },
  { id: 'country', label: 'Country', getValue: row => row.country },
  { id: 'city', label: 'City', getValue: row => row.city }
];

const columnDimensions: PivotGridDimension<SalesRow>[] = [
  { id: 'year', label: 'Year', getValue: row => row.year },
  { id: 'quarter', label: 'Quarter', getValue: row => row.quarter },
  { id: 'channel', label: 'Channel', getValue: row => row.channel }
];

const measures: PivotGridMeasure<SalesRow>[] = [
  {
    id: 'revenue',
    label: 'Revenue',
    aggregate: 'sum',
    getValue: row => row.revenue,
    formatValue: value => new Intl.NumberFormat(undefined, {
      style: 'currency',
      currency: 'USD',
      maximumFractionDigits: 0
    }).format(value)
  },
  {
    id: 'orders',
    label: 'Orders',
    aggregate: 'sum',
    getValue: row => row.orders
  }
];

const cellColorRules: PivotGridCellColorRule[] = [
  {
    scope: 'leaf',
    formula: 'measureId = "revenue" and value > 10000',
    color: 'emerald-100'
  },
  {
    scope: 'grand-total',
    formula: 'value > 0',
    color: 'slate-200'
  }
];

function SalesPivot() {
  const pivot = usePivotGrid({
    data,
    rowDimensions,
    columnDimensions,
    measures,
    getRowId: row => row.id,
    cellColorRules
  });

  return (
    <div className="space-y-3">
      
      
    </div>
  );
}
```

## Notes

- Row groups and column groups can be collapsed independently at each visible branch.
- Subtotals are emitted after every visible branch. Grand totals remain available even when groups are collapsed.
- Drilldown opens a read-only `DataGrid` dialog with the raw rows that contributed to the selected aggregate cell.
- CSV flattens the current visible header paths. Excel and PDF preserve the current visible hierarchy more faithfully.

---

# Place Autocomplete
URL: /docs/web/components/place-autocomplete

Place Autocomplete component with multiple variants and sizes.

**Demo:**

```tsx
'use client';

import { useCallback, useState } from 'react';

import {
  PlaceAutocomplete,
  type PlaceFeature
} from '@docyrus/ui/components/place-autocomplete';
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue
} from '@docyrus/ui/primitives/ui/select';
import { Switch } from '@docyrus/ui/primitives/ui/switch';
import { cn } from '@docyrus/ui/primitives/lib/utils';

export function PlaceAutocompleteDemo() {
  type Variant = 'default' | 'outline' | 'ghost';
  type Size = 'default' | 'sm' | 'lg';

  const [variant, setVariant] = useState
                  
                    
                    
                  
                
              </div>
              <div className="space-y-1.5">
                <span className="text-xs font-medium">Size</span>
                
                  
                    
                    
                  
                
              </div>
              <label className="flex items-center gap-2">
                
                <span className="text-xs">Disabled</span>
              </label>
            </div>
          </div>
        </div>
      </div>
      <div className="mx-auto max-w-md space-y-3">
        
        {selected ? (
          <div className="rounded-lg border border-border bg-muted/30 p-3 text-xs">
            <p className="mb-1 font-medium text-foreground">{selected.properties.name || selected.properties.street}</p>
            <p className="text-muted-foreground">
              Lat: {selected.geometry.coordinates[1].toFixed(6)}, Lng: {selected.geometry.coordinates[0].toFixed(6)}
            </p>
            {selected.properties.city && (
              <p className="text-muted-foreground">City: {selected.properties.city}</p>
            )}
            {selected.properties.country && (
              <p className="text-muted-foreground">Country: {selected.properties.country}</p>
            )}
          </div>
        ) : null}
      </div>
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-place-autocomplete
```

**Dependencies:**
- [class-variance-authority](https://www.npmjs.com/package/class-variance-authority)
- [lucide-react](https://www.npmjs.com/package/lucide-react)

## Usage

```tsx
import {
  PlaceAutocomplete
} from "@docyrus/ui/components/place-autocomplete";

<PlaceAutocomplete
  variant="default"
  size="sm"
  ref={...}
  debounceMs={0}
  value="..."
  defaultValue="..."
  onChange={() => {}}
  onPlaceSelect={() => {}}
  onResultsChange={(results: PlaceFeature) = void[]}
/>
```

## Variants

| Variant | Description |
|---------|-------------|
| `default` | Default style |
| `outline` | Outline — `border-border focus-within:border-ring focus-within:ring-3 focus-within:ring-ring/50` |
| `ghost` | Ghost — `border-transparent shadow-none focus-within:border-ring focus-within:ring-3 focus-within:ring-ring/50` |

## Sizes

| Size | Description |
|------|-------------|
| `sm` | Small — `h-8 px-2 text-xs` |
| `default` | Default — `h-9 px-2.5 text-sm` |
| `lg` | Large — `h-11 px-3 text-base` |

## API Reference

| Prop | Type | Default |
|------|------|---------|
| `variant` | `"default"` \| `"outline"` \| `"ghost"` | `"default"` |
| `size` | `"sm"` \| `"default"` \| `"lg"` | `"default"` |
| `ref` | `Ref<HTMLInputElement>` | — |
| `debounceMs` | `number` | — |
| `value` | `string` | — |
| `defaultValue` | `string` | — |
| `onChange` | `(value: string) => void` | — |
| `onPlaceSelect` | `(feature: PlaceFeature) => void` | — |
| `onResultsChange` | `(results: PlaceFeature[]) => void` | — |
| `className` | `string` | — |

---

# Pricing Engine Panel
URL: /docs/web/components/pricing-engine-panel

Pricing Engine Panel component.

**Demo:**

```tsx
'use client';

import { useState } from 'react';

import {
  PricingEnginePanel,
  type ICategoryCatalogItem,
  type IPricingDocumentData,
  type IProductCatalogItem
} from '@docyrus/ui/components/pricing-engine-panel';

const PRODUCT_CATALOG: IProductCatalogItem[] = [
  {
    id: 'prod-1', name: 'Web Development Services', category: 'Services', categoryId: 'cat-2', unitPrice: 150, vatRate: 18
  },
  {
    id: 'prod-2', name: 'UI/UX Design', category: 'Design', categoryId: 'cat-3', unitPrice: 120, vatRate: 18
  },
  {
    id: 'prod-3', name: 'Hosting (Annual)', category: 'Infrastructure', categoryId: 'cat-5', unitPrice: 480, vatRate: 8
  },
  {
    id: 'prod-4', name: 'Mobile App Development', category: 'Services', categoryId: 'cat-2', unitPrice: 180, vatRate: 18
  },
  {
    id: 'prod-5', name: 'SEO Optimization', category: 'Marketing', categoryId: 'cat-4', unitPrice: 90, vatRate: 18
  },
  {
    id: 'prod-6', name: 'Domain Registration', category: 'Infrastructure', categoryId: 'cat-5', unitPrice: 15, vatRate: 8
  },
  {
    id: 'prod-7', name: 'SSL Certificate', category: 'Infrastructure', categoryId: 'cat-6', unitPrice: 60, vatRate: 8
  },
  {
    id: 'prod-8', name: 'Logo Design', category: 'Design', categoryId: 'cat-3', unitPrice: 350
  },
  {
    id: 'prod-9', name: 'Social Media Management', category: 'Marketing', categoryId: 'cat-7', unitPrice: 200, vatRate: 18
  },
  {
    id: 'prod-10', name: 'Database Administration', category: 'Services', categoryId: 'cat-2', unitPrice: 160, vatRate: 18
  }
];

const CATEGORY_CATALOG: ICategoryCatalogItem[] = [
  { id: 'cat-1', name: 'Technology', parentId: null },
  { id: 'cat-2', name: 'Development', parentId: 'cat-1' },
  { id: 'cat-3', name: 'Design', parentId: 'cat-1' },
  { id: 'cat-4', name: 'Marketing', parentId: null },
  { id: 'cat-7', name: 'Social Media', parentId: 'cat-4' },
  { id: 'cat-8', name: 'SEO & SEM', parentId: 'cat-4' },
  { id: 'cat-5', name: 'Infrastructure', parentId: 'cat-1' },
  { id: 'cat-6', name: 'Security', parentId: 'cat-5' },
  { id: 'cat-9', name: 'Consulting', parentId: null },
  { id: 'cat-10', name: 'Strategy', parentId: 'cat-9' },
  { id: 'cat-11', name: 'Training', parentId: 'cat-9' }
];

export function PricingEnginePanelDemo() {
  const [lastSaved, setLastSaved] = useState<IPricingDocumentData | null>(null);

  return (
    <div className="w-full space-y-4">
      <PricingEnginePanel
        title="Invoice #2024-001"
        defaultValue={{
          lineItems: [
            {
              id: 'demo-1',
              position: 0,
              productId: 'prod-1',
              categoryId: 'cat-2',
              name: 'Web Development Services',
              category: 'Development',
              quantity: 40,
              unitPrice: 150,
              vatRate: 18,
              discountPercent: 0
            },
            {
              id: 'demo-2',
              position: 1,
              productId: 'prod-2',
              categoryId: 'cat-3',
              name: 'UI/UX Design',
              category: 'Design',
              quantity: 20,
              unitPrice: 120,
              vatRate: 18,
              discountPercent: 10
            },
            {
              id: 'demo-3',
              position: 2,
              productId: 'prod-3',
              categoryId: 'cat-5',
              name: 'Hosting (Annual)',
              category: 'Infrastructure',
              quantity: 1,
              unitPrice: 480,
              vatRate: 8,
              discountPercent: 0
            }
          ]
        }}
        productCatalog={PRODUCT_CATALOG}
        categoryCatalog={CATEGORY_CATALOG}
        onSave={data => setLastSaved(data)}
        onSaveDraft={data => setLastSaved(data)}
        size="full" />
      {lastSaved && (
        <p className="text-sm text-muted-foreground">
          Last saved: {lastSaved.status} — Grand Total: {lastSaved.totals.grandTotal.toFixed(2)} {lastSaved.currency.code}
        </p>
      )}
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-pricing-engine-panel
```

**Dependencies:**
- [lucide-react](https://www.npmjs.com/package/lucide-react)
- [class-variance-authority](https://www.npmjs.com/package/class-variance-authority)

## Usage

```tsx
import {
  PricingEnginePanel
} from "@docyrus/ui/components/pricing-engine-panel";
import type {
  PricingEnginePanelProps,
  TPricingViewMode,
  TDiscountMode,
  TPricingDocumentStatus,
  ILineItem,
  ILineItemCalculated,
  ILineItemRow,
  ITotals,
  IVatSummaryRow,
  ICurrencyConfig,
  IPricingConfig,
  IPricingDocumentData,
  IProductCatalogItem,
  ICategoryCatalogItem
} from "@docyrus/ui/components/pricing-engine-panel";

<PricingEnginePanel
  variant="default"
  size="sm"
  ref={...}
  value={...}
  defaultValue={...}
  showVatColumn={true}
  showDiscountColumn={true}
  showGrossColumn={true}
  showCategoryColumn={true}
  discountBeforeVat={true}
  enableVat={true}
  enableLineDiscount={true}
  enableGlobalDiscount={true}
  enableAdjustment={true}
  defaultVatRate={18}
  vatRates={[     0}
  defaultCurrency="USD"
  viewMode="net"
  onLineItemsChange={(items: ILineItem) = void[]}
  onTotalsChange={() => {}}
  onSave={() => {}}
  onSaveDraft={() => {}}
  onProductSelect={() => {}}
  onCategorySelect={() => {}}
  productCatalog={IProductCatalogItem[]}
  categoryCatalog={ICategoryCatalogItem[]}
  title="..."
  showDescription={true}
  showTerms={true}
  showActions={true}
/>
```

## Variants

| Variant | Description |
|---------|-------------|
| `default` | Default style |
| `bordered` | Bordered — `border-2 shadow-sm` |
| `compact` | Compact — `text-xs [&_input]:h-7 [&_input]:text-xs` |

## Sizes

| Size | Description |
|------|-------------|
| `sm` | Small — `max-w-3xl mx-auto` |
| `default` | Default — `max-w-5xl mx-auto` |
| `lg` | Large |
| `full` | full — `w-full` |

## API Reference

| Prop | Type | Default |
|------|------|---------|
| `variant` | `"default"` \| `"bordered"` \| `"compact"` | `"default"` |
| `size` | `"sm"` \| `"default"` \| `"lg"` \| `"full"` | `"default"` |
| `ref` | `Ref<HTMLDivElement>` | — |
| `value` | `Partial<IPricingDocumentData>` | — |
| `defaultValue` | `Partial<IPricingDocumentData>` | — |
| `showVatColumn` | `boolean` | `true` |
| `showDiscountColumn` | `boolean` | `true` |
| `showGrossColumn` | `boolean` | `true` |
| `showCategoryColumn` | `boolean` | `true` |
| `discountBeforeVat` | `boolean` | `true` |
| `enableVat` | `boolean` | `true` |
| `enableLineDiscount` | `boolean` | `true` |
| `enableGlobalDiscount` | `boolean` | `true` |
| `enableAdjustment` | `boolean` | `true` |
| `defaultVatRate` | `number` | `18` |
| `vatRates` | `number[]` | `[     0` |
| `defaultCurrency` | `string` | `'USD'` |
| `viewMode` | `TPricingViewMode` | `'net'` |
| `onLineItemsChange` | `(items: ILineItem[]) => void` | — |
| `onTotalsChange` | `(totals: ITotals) => void` | — |
| `onSave` | `(data: IPricingDocumentData) => void` | — |
| `onSaveDraft` | `(data: IPricingDocumentData) => void` | — |
| `onProductSelect` | `(lineId: string, callback: (product: IProductCatalogItem) => void) => void` | — |
| `onCategorySelect` | `(lineId: string, callback: (category: ICategoryCatalogItem) => void) => void` | — |
| `productCatalog` | `IProductCatalogItem[]` | — |
| `categoryCatalog` | `ICategoryCatalogItem[]` | — |
| `title` | `string` | — |
| `readOnly` | `boolean` | `false` |
| `showDescription` | `boolean` | `true` |
| `showTerms` | `boolean` | `true` |
| `showActions` | `boolean` | `true` |
| `className` | `string` | — |

## Components

| Component | Description |
|-----------|-------------|
| `PricingEnginePanel` | Public export |
| `PricingActionsBar` | Internal — `pricing-actions-bar.tsx` |
| `PricingCategoryCell` | Internal — `pricing-category-cell.tsx` |
| `PricingConfigPopover` | Internal — `pricing-config-popover.tsx` |
| `PricingContentSection` | Internal — `pricing-content-section.tsx` |
| `PricingCurrencyBar` | Internal — `pricing-currency-bar.tsx` |
| `PricingDiscountSection` | Internal — `pricing-discount-section.tsx` |
| `PricingHeader` | Internal — `pricing-header.tsx` |
| `PricingLineRowActions` | Internal — `pricing-line-row-actions.tsx` |
| `PricingLineRow` | Internal — `pricing-line-row.tsx` |
| `PricingLineTable` | Internal — `pricing-line-table.tsx` |
| `PricingProductCell` | Internal — `pricing-product-cell.tsx` |
| `PricingTotalsSection` | Internal — `pricing-totals-section.tsx` |
| `PricingVatSummary` | Internal — `pricing-vat-summary.tsx` |
| `PricingEngineProvider` | Internal — `contexts/pricing-context.tsx` |

## Type Exports

| Type | Description |
|------|-------------|
| `PricingEnginePanelProps` | — |
| `TPricingViewMode` | — |
| `TDiscountMode` | — |
| `TPricingDocumentStatus` | — |
| `ILineItem` | — |
| `ILineItemCalculated` | — |
| `ILineItemRow` | — |
| `ITotals` | — |
| `IVatSummaryRow` | — |
| `ICurrencyConfig` | — |
| `IPricingConfig` | — |
| `IPricingDocumentData` | — |
| `IProductCatalogItem` | — |
| `ICategoryCatalogItem` | — |

## Type Reference

### PricingEnginePanelProps

| Field | Type | Description |
|-------|------|-------------|
| `ref` | `Ref<HTMLDivElement>` | — |
| `value` | `Partial<IPricingDocumentData>` | — |
| `defaultValue` | `Partial<IPricingDocumentData>` | — |
| `showVatColumn` | `boolean` | — |
| `showDiscountColumn` | `boolean` | — |
| `showGrossColumn` | `boolean` | — |
| `showCategoryColumn` | `boolean` | — |
| `discountBeforeVat` | `boolean` | — |
| `enableVat` | `boolean` | — |
| `enableLineDiscount` | `boolean` | — |
| `enableGlobalDiscount` | `boolean` | — |
| `enableAdjustment` | `boolean` | — |
| `defaultVatRate` | `number` | — |
| `vatRates` | `number[]` | — |
| `defaultCurrency` | `string` | — |
| `viewMode` | `TPricingViewMode` | — |
| `onLineItemsChange` | `(items: ILineItem[]) => void` | — |
| `onTotalsChange` | `(totals: ITotals) => void` | — |
| `onSave` | `(data: IPricingDocumentData) => void` | — |
| `onSaveDraft` | `(data: IPricingDocumentData) => void` | — |
| `onProductSelect` | `(lineId: string, callback: (product: IProductCatalogItem) => void) => void` | — |
| `onCategorySelect` | `(lineId: string, callback: (category: ICategoryCatalogItem) => void) => void` | — |
| `productCatalog` | `IProductCatalogItem[]` | — |
| `categoryCatalog` | `ICategoryCatalogItem[]` | — |
| `title` | `string` | — |
| `readOnly` | `boolean` | — |
| `showDescription` | `boolean` | — |
| `showTerms` | `boolean` | — |
| `showActions` | `boolean` | — |
| `variant` | `'default' \| 'bordered' \| 'compact'` | — |
| `size` | `'sm' \| 'default' \| 'lg' \| 'full'` | — |

### TPricingViewMode

`"net"` | `"gross"`

### TDiscountMode

`"before-vat"` | `"after-vat"`

### TPricingDocumentStatus

`"draft"` | `"saved"`

### ILineItem

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | — |
| `position` | `number` | — |
| `productId` | `string \| null` | — |
| `categoryId` | `string \| null` | — |
| `name` | `string` | — |
| `category` | `string` | — |
| `quantity` | `number` | — |
| `unitPrice` | `number` | — |
| `vatRate` | `number` | — |
| `discountPercent` | `number` | — |

### ILineItemCalculated

| Field | Type | Description |
|-------|------|-------------|
| `lineSubtotal` | `number` | — |
| `discountAmount` | `number` | — |
| `netAfterDiscount` | `number` | — |
| `vatAmount` | `number` | — |
| `grossTotal` | `number` | — |

### ILineItemRow

| Field | Type | Description |
|-------|------|-------------|

### ITotals

| Field | Type | Description |
|-------|------|-------------|
| `subtotal` | `number` | — |
| `lineDiscountTotal` | `number` | — |
| `globalDiscountAmount` | `number` | — |
| `totalDiscount` | `number` | — |
| `netTotal` | `number` | — |
| `vatTotal` | `number` | — |
| `adjustment` | `number` | — |
| `grandTotal` | `number` | — |

### IVatSummaryRow

| Field | Type | Description |
|-------|------|-------------|
| `rate` | `number` | — |
| `taxableAmount` | `number` | — |
| `vatAmount` | `number` | — |

### ICurrencyConfig

| Field | Type | Description |
|-------|------|-------------|
| `code` | `string` | — |
| `secondaryCurrencyCode` | `string \| null` | — |
| `exchangeRate` | `number` | — |

### IPricingConfig

| Field | Type | Description |
|-------|------|-------------|
| `showVatColumn` | `boolean` | — |
| `showDiscountColumn` | `boolean` | — |
| `showGrossColumn` | `boolean` | — |
| `showCategoryColumn` | `boolean` | — |
| `discountBeforeVat` | `boolean` | — |
| `enableVat` | `boolean` | — |
| `enableLineDiscount` | `boolean` | — |
| `enableGlobalDiscount` | `boolean` | — |
| `enableAdjustment` | `boolean` | — |
| `defaultVatRate` | `number` | — |
| `vatRates` | `number[]` | — |
| `viewMode` | `TPricingViewMode` | — |

### IPricingDocumentData

| Field | Type | Description |
|-------|------|-------------|
| `lineItems` | `ILineItem[]` | — |
| `globalDiscountPercent` | `number` | — |
| `adjustment` | `number` | — |
| `currency` | `ICurrencyConfig` | — |
| `config` | `IPricingConfig` | — |
| `description` | `string` | — |
| `termsAndConditions` | `string` | — |
| `status` | `TPricingDocumentStatus` | — |
| `totals` | `ITotals` | — |

### IProductCatalogItem

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | — |
| `name` | `string` | — |
| `category` | `string` | — |
| `categoryId` | `string` | — |
| `unitPrice` | `number` | — |
| `vatRate` | `number` | — |

### ICategoryCatalogItem

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | — |
| `name` | `string` | — |
| `parentId` | `string \| null` | — |
| `children` | `ICategoryCatalogItem[]` | — |

---

# Query Builder
URL: /docs/web/components/query-builder

Query Builder component.

**Demo:**

```tsx
'use client';

import { useState } from 'react';

import { QueryBuilderDocyrus } from '@docyrus/ui/components/query-builder';
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue
} from '@docyrus/ui/primitives/ui/select';
import { cn } from '@docyrus/ui/primitives/lib/utils';

import { PropControls } from '@/components/prop-controls';
import { useDemoData } from '@/data/query-builder-data';

export function QueryBuilderDemo() {
  type Variant = 'default' | 'bordered' | 'compact' | 'striped';
  const [variant, setVariant] = useState
                  
                    
                    
                    
                  
                
              </div>
              <div className="space-y-1.5">
                <span className="text-xs font-medium">Size</span>
                
                  
                    
                    
                  
                
              </div>
              
            </div>
          </div>
        </div>
      </div>
      
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-query-builder
```

**Dependencies:**
- [@react-querybuilder/dnd](https://www.npmjs.com/package/@react-querybuilder/dnd)
- [@atlaskit/pragmatic-drag-and-drop](https://www.npmjs.com/package/@atlaskit/pragmatic-drag-and-drop)
- [@dnd-kit/core](https://www.npmjs.com/package/@dnd-kit/core)
- [react-dnd](https://www.npmjs.com/package/react-dnd)
- [react-dnd-html5-backend](https://www.npmjs.com/package/react-dnd-html5-backend)
- [react-dnd-touch-backend](https://www.npmjs.com/package/react-dnd-touch-backend)
- [react-querybuilder](https://www.npmjs.com/package/react-querybuilder)
- [lucide-react](https://www.npmjs.com/package/lucide-react)
- [class-variance-authority](https://www.npmjs.com/package/class-variance-authority)
- [jsonata](https://www.npmjs.com/package/jsonata)

## Usage

```tsx
import {
  QueryBuilderDocyrus
} from "@docyrus/ui/components/query-builder";
import type {
  QueryBuilderDocyrusProps,
  DocyrusQBField,
  RuleGroupType,
  RuleGroupTypeIC,
  RuleType,
  Field,
  FullField,
  FullOperator,
  FullCombinator,
  QueryBuilderProps,
  ActionProps,
  ValueSelectorProps,
  ValueEditorProps,
  NotToggleProps,
  DragHandleProps,
  CombinatorSelectorProps,
  FieldSelectorProps,
  OperatorSelectorProps,
  RuleGroupTypeAny,
  VersatileSelectorProps,
  QueryJsonataContext,
  EvaluateOptions,
  UseQuery2JsonataConverterOptions,
  UseQuery2JsonataConverterResult,
  ConvertQueryOptions,
  ConvertQueryResult,
  DateBindingSpec,
  OperatorApi,
  FilterGroup
} from "@docyrus/ui/components/query-builder";

<QueryBuilderDocyrus
  variant="default"
  size="sm"
  animated
  draggable
  showRuleNumbers
  maxDepth={0}
  emptyMessage={...}
  showClearButton
  clearButtonLabel={...}
  onRuleAdd={() => {}}
  onRuleRemove={() => {}}
  onGroupAdd={() => {}}
  onGroupRemove={() => {}}
  onClear={() => {}}
  enrichFieldDefaults
/>
```

## Variants

| Variant | Description |
|---------|-------------|
| `default` | Default style |
| `bordered` | Bordered — `rounded-lg border bg-card p-4 shadow-sm` |
| `compact` | Compact — `text-xs [&_.rule]:py-1 [&_.rule]:px-2 [&_.rule]:gap-1` |
| `striped` | Striped — `[&_.rule:nth-child(even)]:bg-muted/20` |

## Sizes

| Size | Description |
|------|-------------|
| `sm` | Small — `[&_.qb-control]:h-7 [&_.qb-control]:text-xs` |
| `default` | Default |
| `lg` | Large — `[&_.qb-control]:h-10 [&_.qb-control]:text-sm` |

## API Reference

| Prop | Type | Default |
|------|------|---------|
| `variant` | `"default"` \| `"bordered"` \| `"compact"` \| `"striped"` | `"default"` |
| `size` | `"sm"` \| `"default"` \| `"lg"` | `"default"` |
| `animated` | `boolean` | — |
| `draggable` | `boolean` | — |
| `showRuleNumbers` | `boolean` | — |
| `maxDepth` | `number` | — |
| `emptyMessage` | `ReactNode` | — |
| `showClearButton` | `boolean` | — |
| `clearButtonLabel` | `ReactNode` | — |
| `onRuleAdd` | `() => void` | — |
| `onRuleRemove` | `() => void` | — |
| `onGroupAdd` | `() => void` | — |
| `onGroupRemove` | `() => void` | — |
| `onClear` | `() => void` | — |
| `enrichFieldDefaults` | `boolean` | — |
| `className` | `string` | — |

## Components

| Component | Description |
|-----------|-------------|
| `QueryBuilderDocyrus` | Public export |

## Type Exports

| Type | Description |
|------|-------------|
| `QueryBuilderDocyrusProps` | — |
| `DocyrusQBField` | — |
| `RuleGroupType` | — |
| `RuleGroupTypeIC` | — |
| `RuleType` | — |
| `Field` | — |
| `FullField` | — |
| `FullOperator` | — |
| `FullCombinator` | — |
| `QueryBuilderProps` | — |
| `ActionProps` | — |
| `ValueSelectorProps` | — |
| `ValueEditorProps` | — |
| `NotToggleProps` | — |
| `DragHandleProps` | — |
| `CombinatorSelectorProps` | — |
| `FieldSelectorProps` | — |
| `OperatorSelectorProps` | — |
| `RuleGroupTypeAny` | — |
| `VersatileSelectorProps` | — |
| `QueryJsonataContext` | — |
| `EvaluateOptions` | — |
| `UseQuery2JsonataConverterOptions` | — |
| `UseQuery2JsonataConverterResult` | — |
| `ConvertQueryOptions` | — |
| `ConvertQueryResult` | — |
| `DateBindingSpec` | — |
| `OperatorApi` | — |
| `FilterGroup` | — |

## Type Reference

### DocyrusQBField

| Field | Type | Description |
|-------|------|-------------|
| `filterGroup` | `FilterGroup` | — |
| `fieldType` | `string` | — |
| `operatorValues` | `Record<string, QBOperatorValueOption[]>` | — |
| `operatorValueEditorType` | `Partial<Record<string, ValueEditorType>>` | — |

### QueryJsonataContext

| Field | Type | Description |
|-------|------|-------------|
| `activeUserId` | `string` | — |
| `activeUserTeamMemberIds` | `string[]` | — |

### EvaluateOptions

| Field | Type | Description |
|-------|------|-------------|
| `now` | `Date \| number` | — |
| `bindings` | `Record<string, unknown>` | — |

### UseQuery2JsonataConverterOptions

| Field | Type | Description |
|-------|------|-------------|

### UseQuery2JsonataConverterResult

| Field | Type | Description |
|-------|------|-------------|
| `expression` | `string` | — |
| `dateBindings` | `DateBindingSpec[]` | — |
| `unsupportedOperators` | `string[]` | — |
| `warnings` | `string[]` | — |
| `isValid` | `boolean` | — |
| `error` | `Error \| null` | — |
| `evaluate` | `(data: unknown, options?: EvaluateOptions) => Promise<boolean>` | — |

### ConvertQueryOptions

| Field | Type | Description |
|-------|------|-------------|
| `resolveGroup` | `(field: string) => FilterGroup \| undefined` | — |
| `fieldResolver` | `(field: string) => string` | — |
| `operatorOverrides` | `Record<string, (rule: RuleType, api: OperatorApi) => string \| null>` | — |
| `unsupportedFallback` | `boolean` | — |
| `weekStartsOn` | `0 \| 1` | — |

### ConvertQueryResult

| Field | Type | Description |
|-------|------|-------------|
| `expression` | `string` | — |
| `dateBindings` | `DateBindingSpec[]` | — |
| `unsupportedOperators` | `string[]` | — |
| `warnings` | `string[]` | — |

### DateBindingSpec

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | — |
| `operator` | `string` | — |
| `amount` | `number` | — |

### OperatorApi

| Field | Type | Description |
|-------|------|-------------|
| `field` | `string` | — |
| `str` | `(value: unknown) => string` | — |
| `num` | `(value: unknown) => string` | — |
| `strArr` | `(values: unknown[]) => string` | — |
| `fieldRef` | `(name: string) => string` | — |

### FilterGroup

`"ALPHA"`

---

# Radio Group
URL: /docs/web/components/radio-group

Radio Group component with multiple variants and sizes.

**Demo:**

```tsx
'use client';

import { useState } from 'react';

import { RadioGroup, type RadioGroupOption } from '@docyrus/ui/components/radio-group';
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue
} from '@docyrus/ui/primitives/ui/select';
import { cn } from '@docyrus/ui/primitives/lib/utils';

const planOptions: RadioGroupOption[] = [
  {
    value: 'starter', label: 'Starter', description: 'For individuals and small projects', icon: 'hi-user-02', color: '#3b82f6'
  },
  {
    value: 'pro', label: 'Professional', description: 'For growing teams with advanced needs', icon: 'hi-briefcase-02', color: '#8b5cf6'
  },
  {
    value: 'enterprise', label: 'Enterprise', description: 'Custom solutions for large organizations', icon: 'hi-building-06', color: '#f59e0b'
  },
  {
    value: 'legacy', label: 'Legacy', description: 'No longer available for new signups', disabled: true
  }
];

const priorityOptions: RadioGroupOption[] = [
  { value: 'low', label: 'Low', color: '#22c55e' },
  { value: 'medium', label: 'Medium', color: '#f59e0b' },
  { value: 'high', label: 'High', color: '#ef4444' },
  { value: 'critical', label: 'Critical', color: '#dc2626' }
];

export function RadioGroupDemo() {
  type Variant = 'default' | 'card';
  type ColumnCount = 1 | 2 | 3 | 4;

  const [variant, setVariant] = useState
                  
                    
                  
                
              </div>
              <div className="space-y-1.5">
                <span className="text-xs font-medium">Columns</span>
                
                  
                    
                    
                    
                  
                
              </div>
            </div>
          </div>
        </div>
      </div>

      <div className="space-y-8">
        <div className="space-y-2">
          <h3 className="text-sm font-medium">Select a plan</h3>
          
          <p className="text-xs text-muted-foreground">
            Selected: <span className="font-medium text-foreground">{selected}</span>
          </p>
        </div>

        <div className="space-y-2">
          <h3 className="text-sm font-medium">Priority</h3>
          
        </div>
      </div>
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-radio-group
```

**Dependencies:**
- [radix-ui](https://www.npmjs.com/package/radix-ui)
- [@types/react](https://www.npmjs.com/package/@types/react)
- [@types/react-dom](https://www.npmjs.com/package/@types/react-dom)
- [class-variance-authority](https://www.npmjs.com/package/class-variance-authority)
- [lucide-react](https://www.npmjs.com/package/lucide-react)

## Usage

```tsx
import {
  RadioGroup
} from "@docyrus/ui/components/radio-group";

```

## Variants

| Variant | Description |
|---------|-------------|
| `default` | Default style |
| `card` | Card — `gap-2` |

## API Reference

| Prop | Type | Default |
|------|------|---------|
| `variant` | `"default"` \| `"card"` | `"default"` |
| `options` | `RadioGroupOption[]` | — |
| `ref` | `Ref<HTMLDivElement>` | — |
| `className` | `string` | — |

---

# Record Activity Panel
URL: /docs/web/components/record-activity-panel

Record Activity Panel component.

**Demo:**

```tsx
'use client';
// @custom-demo

import { useState } from 'react';

import { RecordActivityPanel } from '@docyrus/ui/components/record-activity-panel';
import { Button } from '@docyrus/ui/primitives/ui/button';
import { cn } from '@docyrus/ui/primitives/lib/utils';

import { PropControls } from '@/components/prop-controls';
import { useDemoData } from '@/data/record-activity-panel-data';

export function RecordActivityPanelDemo() {
  const { props, controls, actions } = useDemoData();
  const [open, setOpen] = useState(false);

  return (
    <div className="w-full">
      <div className="mb-3 flex justify-end">
        <button
          type="button"
          className="inline-flex items-center gap-1.5 rounded-md border border-border bg-background px-3 py-1.5 text-sm font-medium transition-colors hover:bg-accent"
          onClick={() => setOpen(prev => !prev)}>
          <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M12.22 2h-.44a2 2 0 0 0-2 2v.18a2 2 0 0 1-1 1.73l-.43.25a2 2 0 0 1-2 0l-.15-.08a2 2 0 0 0-2.73.73l-.22.38a2 2 0 0 0 .73 2.73l.15.1a2 2 0 0 1 1 1.72v.51a2 2 0 0 1-1 1.74l-.15.09a2 2 0 0 0-.73 2.73l.22.38a2 2 0 0 0 2.73.73l.15-.08a2 2 0 0 1 2 0l.43.25a2 2 0 0 1 1 1.73V20a2 2 0 0 0 2 2h.44a2 2 0 0 0 2-2v-.18a2 2 0 0 1 1-1.73l.43-.25a2 2 0 0 1 2 0l.15.08a2 2 0 0 0 2.73-.73l.22-.39a2 2 0 0 0-.73-2.73l-.15-.08a2 2 0 0 1-1-1.74v-.5a2 2 0 0 1 1-1.74l.15-.09a2 2 0 0 0 .73-2.73l-.22-.38a2 2 0 0 0-2.73-.73l-.15.08a2 2 0 0 1-2 0l-.43-.25a2 2 0 0 1-1-1.73V4a2 2 0 0 0-2-2z" /><circle cx="12" cy="12" r="3" /></svg>
          Configure
          <svg xmlns="http://www.w3.org/2000/svg" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" className={cn('transition-transform duration-200', open && 'rotate-180')}><path d="m6 9 6 6 6-6" /></svg>
        </button>
      </div>
      <div
        className={cn(
          'grid transition-[grid-template-rows] duration-300 ease-in-out',
          open ? 'grid-rows-[1fr]' : 'grid-rows-[0fr]'
        )}>
        <div className="overflow-hidden">
          <div className="mb-4 rounded-lg border border-border bg-muted/30 p-4 grid gap-6">
            
            <div className="mt-3 flex flex-wrap gap-2">
              
              
              
            </div>
          </div>
        </div>
      </div>
      
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-record-activity-panel
```

**Dependencies:**
- [lucide-react](https://www.npmjs.com/package/lucide-react)

## Usage

```tsx
import { RecordActivityPanel } from "@docyrus/ui/components/record-activity-panel";
import type { RecordActivity } from "@docyrus/ui/components/record-activity-panel";

const activities: RecordActivity[] = [
  {
    id: "act-1",
    description: "Status changed from In Progress to In Review",
    shortDescription: "Status changed",
    icon: null,
    color: "#f59e0b",
    table_name: "tasks",
    operation: "STATUS_UPDATE",
    tenant_data_source_id: { id: "ds-1", name: "Tasks" },
    created_on: "2025-12-17T09:30:00Z",
    created_by: "u-alice",
    created_by_user: { firstname: "Alice", lastname: "Johnson", name: "Alice Johnson", email: "alice@docyrus.com", mobile: null },
    data_source_name: "Tasks",
    title: "Task #341"
  }
];

function Demo() {
  return ;
}
```

## API Reference

| Prop | Type | Default |
|------|------|---------|
| `activities` | `RecordActivity[]` | — |
| `isLoading` | `boolean` | `false` |
| `className` | `string` | — |

## Components

| Component | Description |
|-----------|-------------|
| `RecordActivityPanel` | Public export |

---

# Record Delete Confirm Dialog
URL: /docs/web/components/record-delete-confirm-dialog

Record Delete Confirm Dialog component.

**Demo:**

```tsx
'use client';
// @custom-demo

import { useState } from 'react';

import { RecordDeleteConfirmDialog } from '@docyrus/ui/components/record-delete-confirm-dialog';
import { Button } from '@docyrus/ui/primitives/ui/button';
import { cn } from '@docyrus/ui/primitives/lib/utils';

import { PropControls } from '@/components/prop-controls';
import { useDemoData } from '@/data/record-delete-confirm-dialog-data';

export function RecordDeleteConfirmDialogDemo() {
  const { props, controls } = useDemoData();
  const [open, setOpen] = useState(false);

  return (
    <div className="w-full">
      <div className="mb-3 flex justify-end">
        <button
          type="button"
          className="inline-flex items-center gap-1.5 rounded-md border border-border bg-background px-3 py-1.5 text-sm font-medium transition-colors hover:bg-accent"
          onClick={() => setOpen(prev => !prev)}>
          <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M12.22 2h-.44a2 2 0 0 0-2 2v.18a2 2 0 0 1-1 1.73l-.43.25a2 2 0 0 1-2 0l-.15-.08a2 2 0 0 0-2.73.73l-.22.38a2 2 0 0 0 .73 2.73l.15.1a2 2 0 0 1 1 1.72v.51a2 2 0 0 1-1 1.74l-.15.09a2 2 0 0 0-.73 2.73l.22.38a2 2 0 0 0 2.73.73l.15-.08a2 2 0 0 1 2 0l.43.25a2 2 0 0 1 1 1.73V20a2 2 0 0 0 2 2h.44a2 2 0 0 0 2-2v-.18a2 2 0 0 1 1-1.73l.43-.25a2 2 0 0 1 2 0l.15.08a2 2 0 0 0 2.73-.73l.22-.39a2 2 0 0 0-.73-2.73l-.15-.08a2 2 0 0 1-1-1.74v-.5a2 2 0 0 1 1-1.74l.15-.09a2 2 0 0 0 .73-2.73l-.22-.38a2 2 0 0 0-2.73-.73l-.15.08a2 2 0 0 1-2 0l-.43-.25a2 2 0 0 1-1-1.73V4a2 2 0 0 0-2-2z" /><circle cx="12" cy="12" r="3" /></svg>
          Configure
          <svg xmlns="http://www.w3.org/2000/svg" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" className={cn('transition-transform duration-200', open && 'rotate-180')}><path d="m6 9 6 6 6-6" /></svg>
        </button>
      </div>
      <div
        className={cn(
          'grid transition-[grid-template-rows] duration-300 ease-in-out',
          open ? 'grid-rows-[1fr]' : 'grid-rows-[0fr]'
        )}>
        <div className="overflow-hidden">
          <div className="mb-4 rounded-lg border border-border bg-muted/30 p-4 grid gap-6">
            
          </div>
        </div>
      </div>
      <div className="mt-3 flex flex-wrap gap-2">
        
      </div>
      
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-record-delete-confirm-dialog
```

**Dependencies:**
- [lucide-react](https://www.npmjs.com/package/lucide-react)

## Usage

```tsx
import { RecordDeleteConfirmDialog } from "@docyrus/ui/components/record-delete-confirm-dialog";
import type { DataSourceRelation } from "@docyrus/ui/components/record-delete-confirm-dialog";
import { useState } from "react";

const relations: DataSourceRelation[] = [
  { dataSourceId: "tasks", dataSourceName: "Tasks", dataSourceSlug: "tasks", appSlug: "base", dataSourceType: "table", fieldId: "task_id", fieldSlug: "task_id", fieldName: "Task", fieldType: "relation" }
];

function Demo() {
  const [open, setOpen] = useState(false);

  return (
    <RecordDeleteConfirmDialog
      open={open}
      onOpenChange={setOpen}
      recordCount={2}
      relations={relations}
      onConfirm={(childActions) => console.log(childActions)}
    />
  );
}
```

## API Reference

| Prop | Type | Default |
|------|------|---------|
| `open` | `boolean` | — |
| `onOpenChange` | `(open: boolean) => void` | — |
| `recordCount` | `number` | — |
| `relations` | `DataSourceRelation[]` | `[]` |
| `isLoadingRelations` | `boolean` | `false` |
| `onConfirm` | `(childActions: Record<string, ChildAction>) => void \| Promise<void>` | — |
| `isPending` | `boolean` | `false` |
| `className` | `string` | — |

## Components

| Component | Description |
|-----------|-------------|
| `RecordDeleteConfirmDialog` | Public export |

## Type Exports

| Type | Description |
|------|-------------|
| `DataSourceRelation` | — |

## Type Reference

### DataSourceRelation

| Field | Type | Description |
|-------|------|-------------|
| `dataSourceId` | `string` | — |
| `dataSourceName` | `string` | — |
| `dataSourceSlug` | `string` | — |
| `appSlug` | `string` | — |
| `dataSourceType` | `string` | — |
| `fieldId` | `string` | — |
| `fieldSlug` | `string` | — |
| `fieldName` | `string` | — |
| `fieldType` | `string` | — |

---

# Record Sharing
URL: /docs/web/components/record-sharing

Record Sharing component.

**Demo:**

```tsx
'use client';

import { useCallback, useState } from 'react';

import {
  RecordSharingButton,
  type SharedEntity,
  type SharingSearchResult, SharingPermissionPreset
} from '@docyrus/ui/components/record-sharing';

const MOCK_USERS: SharingSearchResult[] = [
  {
    id: 'u1', name: 'Alice Johnson', description: 'alice@company.com', type: 'user', initials: 'AJ'
  },
  {
    id: 'u2', name: 'Bob Smith', description: 'bob@company.com', type: 'user', initials: 'BS'
  },
  {
    id: 'u3', name: 'Carol Williams', description: 'carol@company.com', type: 'user', initials: 'CW'
  },
  {
    id: 't1', name: 'Engineering', description: '12 members', type: 'team', initials: 'EN'
  },
  {
    id: 'r1', name: 'Admin', description: 'Full system access', type: 'role', initials: 'AD'
  }
];

const INITIAL_SHARED: SharedEntity[] = [
  {
    id: 'u1', name: 'Alice Johnson', description: 'alice@company.com', type: 'user', initials: 'AJ', avatarUrl: null, permission: SharingPermissionPreset.FULL_ACCESS
  },
  {
    id: 't1', name: 'Engineering', description: '12 members', type: 'team', initials: 'EN', permission: SharingPermissionPreset.CAN_VIEW
  }
];

export function RecordSharingDemo() {
  const [sharedEntities, setSharedEntities] = useState<SharedEntity[]>(INITIAL_SHARED);

  const onSearch = useCallback(async (query: string): Promise<SharingSearchResult[]> => {
    await new Promise(r => setTimeout(r, 300));
    const q = query.toLowerCase();

    return MOCK_USERS.filter(u => u.name.toLowerCase().includes(q));
  }, []);

  const onAdd = useCallback((entities: Array<{ id: string; type: string; permission: number }>) => {
    setSharedEntities((prev) => {
      const newEntities = entities
        .filter(e => !prev.some(p => p.id === e.id))
        .map((e) => {
          const found = MOCK_USERS.find(u => u.id === e.id);

          return {
            id: e.id,
            name: found?.name ?? 'Unknown',
            description: found?.description,
            type: e.type as SharedEntity['type'],
            initials: found?.initials,
            avatarUrl: null,
            permission: e.permission
          };
        });

      return [...prev, ...newEntities];
    });
  }, []);

  const onPermissionChange = useCallback((entityId: string, permission: number) => {
    setSharedEntities(prev => prev.map(e => (e.id === entityId ? { ...e, permission } : e)));
  }, []);

  const onRemove = useCallback((entityId: string) => {
    setSharedEntities(prev => prev.filter(e => e.id !== entityId));
  }, []);

  return (
    <div className="flex items-center gap-4">
      
      
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-record-sharing
```

**Dependencies:**
- [lucide-react](https://www.npmjs.com/package/lucide-react)
- [class-variance-authority](https://www.npmjs.com/package/class-variance-authority)

## Usage

```tsx
import {
  RecordSharingButton
} from "@docyrus/ui/components/record-sharing";
import type {
  RecordSharingButtonProps,
  RecordSharingPanelProps,
  RecordSharingItemProps,
  SharedEntity,
  SharingSearchResult,
  SharingResourceType,
  SharingPermissionValue,
  SharingPermissionPresetValue,
  PermissionPresetOption
} from "@docyrus/ui/components/record-sharing";

```

## API Reference

| Component | Prop | Type | Default |
|-----------|------|------|---------|
| `RecordSharing` | `className` | `string` | — |

## Components

| Component | Description |
|-----------|-------------|
| `RecordSharingButton` | Public export |
| `RecordSharingItem` | Internal — `record-sharing-item.tsx` |
| `RecordSharingPanel` | Internal — `record-sharing-panel.tsx` |

## Type Exports

| Type | Description |
|------|-------------|
| `RecordSharingButtonProps` | — |
| `RecordSharingPanelProps` | — |
| `RecordSharingItemProps` | — |
| `SharedEntity` | — |
| `SharingSearchResult` | — |
| `SharingResourceType` | — |
| `SharingPermissionValue` | — |
| `SharingPermissionPresetValue` | — |
| `PermissionPresetOption` | — |

## Type Reference

### RecordSharingButtonProps

| Field | Type | Description |
|-------|------|-------------|
| `ref` | `Ref<HTMLDivElement>` | — |
| `variant` | `'button' \| 'avatar-group'` | — |
| `maxAvatars` | `number` | — |
| `size` | `'sm' \| 'default' \| 'lg'` | — |
| `align` | `'start' \| 'center' \| 'end'` | — |
| `side` | `'top' \| 'right' \| 'bottom' \| 'left'` | — |
| `open` | `boolean` | — |
| `onOpenChange` | `(open: boolean) => void` | — |
| `disabled` | `boolean` | — |
| `triggerClassName` | `string` | — |

### RecordSharingPanelProps

| Field | Type | Description |
|-------|------|-------------|
| `sharedEntities` | `SharedEntity[]` | — |
| `resources` | `SharingResourceType[]` | — |
| `permissionPresets` | `PermissionPresetOption[]` | — |
| `defaultPermission` | `number` | — |
| `onSearch` | `(query: string) => Promise<SharingSearchResult[]> \| SharingSearchResult[]` | — |
| `onAdd` | `(entities: Array<{ id: string; type: SharingResourceType; permission: number }>) => void \| Promise<void>` | — |
| `onPermissionChange` | `(entityId: string, permission: number) => void \| Promise<void>` | — |
| `onRemove` | `(entityId: string) => void \| Promise<void>` | — |
| `isLoading` | `boolean` | — |
| `isSearching` | `boolean` | — |
| `isAddPending` | `boolean` | — |
| `pendingPermissionChanges` | `Record<string, boolean>` | — |
| `pendingRemovals` | `Record<string, boolean>` | — |
| `title` | `string` | — |
| `maxHeight` | `number \| string` | — |
| `className` | `string` | — |

### RecordSharingItemProps

| Field | Type | Description |
|-------|------|-------------|
| `entity` | `SharedEntity` | — |
| `permissionPresets` | `PermissionPresetOption[]` | — |
| `onPermissionChange` | `(entityId: string, permission: number) => void \| Promise<void>` | — |
| `onRemove` | `(entityId: string) => void \| Promise<void>` | — |
| `isPermissionChangePending` | `boolean` | — |
| `isRemovePending` | `boolean` | — |

### SharedEntity

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | — |
| `name` | `string` | — |
| `description` | `string` | — |
| `type` | `SharingResourceType` | — |
| `avatarUrl` | `string \| null` | — |
| `initials` | `string` | — |
| `permission` | `number` | — |

### SharingSearchResult

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | — |
| `name` | `string` | — |
| `description` | `string` | — |
| `type` | `SharingResourceType` | — |
| `avatarUrl` | `string \| null` | — |
| `initials` | `string` | — |

### SharingResourceType

`"user"` | `"team"` | `"role"` | `"tenant"` | `"public"`

### PermissionPresetOption

| Field | Type | Description |
|-------|------|-------------|
| `label` | `string` | — |
| `value` | `number` | — |
| `description` | `string` | — |

---

# Resource Scheduler Panel
URL: /docs/web/components/resource-scheduler-panel

Resource Scheduler Panel component.

**Demo:**

```tsx
'use client';

import { useCallback, useState } from 'react';

import { format } from 'date-fns';

import {
  type SchedulerEvent,
  ResourceSchedulerPanel
} from '@docyrus/ui/components/resource-scheduler-panel';

import { useSchedulerDemoData } from '@/data/resource-scheduler-panel-data';

export function ResourceSchedulerPanelDemo() {
  const { resources, events: initialEvents } = useSchedulerDemoData();
  const [events, setEvents] = useState<Array<SchedulerEvent>>(initialEvents);
  const [logs, setLogs] = useState<Array<{ id: string; message: string }>>([]);

  const addLog = useCallback((message: string) => {
    setLogs(prev => [{ id: `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`, message }, ...prev].slice(0, 5));
  }, []);

  const handleEventClick = useCallback((event: SchedulerEvent) => {
    addLog(`Clicked "${event.title}"`);
  }, [addLog]);

  const handleEventMove = useCallback((
    event: SchedulerEvent,
    newStart: Date,
    newEnd: Date,
    newResourceId?: string
  ) => {
    setEvents(prev => prev.map(e => e.id === event.id ? {
      ...e, startDate: newStart, endDate: newEnd, resourceId: newResourceId ?? e.resourceId
    } : e));
    const target = newResourceId ? resources.find(r => r.id === newResourceId)?.name : undefined;

    addLog(
      `Moved "${event.title}" → ${format(newStart, 'MMM d, HH:mm')}${target ? ` (→ ${target})` : ''}`
    );
  }, [addLog, resources]);

  const handleEventResize = useCallback((
    event: SchedulerEvent,
    newStart: Date,
    newEnd: Date
  ) => {
    setEvents(prev => prev.map(e => e.id === event.id ? { ...e, startDate: newStart, endDate: newEnd } : e));
    addLog(
      `Resized "${event.title}" → ${format(newStart, 'MMM d, HH:mm')} – ${format(newEnd, 'MMM d, HH:mm')}`
    );
  }, [addLog]);

  const handleSlotClick = useCallback((resourceId: string, date: Date) => {
    const resource = resources.find(r => r.id === resourceId);

    addLog(`Slot click: ${resource?.name} at ${format(date, 'MMM d, HH:mm')}`);
  }, [addLog, resources]);

  return (
    <div className="space-y-3">
      <div className="overflow-x-auto">
        <div className="min-w-225">
          
        </div>
      </div>
      {logs.length > 0 && (
        <div className="rounded-md border bg-muted/50 px-3 py-2 font-mono text-xs text-muted-foreground">
          {logs.map((log, i) => (
            <div key={log.id} className={i > 0 ? 'opacity-50' : ''}>
              {log.message}
            </div>
          ))}
        </div>
      )}
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-resource-scheduler-panel
```

**Dependencies:**
- [date-fns](https://www.npmjs.com/package/date-fns)
- [@dnd-kit/core](https://www.npmjs.com/package/@dnd-kit/core)
- [@dnd-kit/modifiers](https://www.npmjs.com/package/@dnd-kit/modifiers)
- [class-variance-authority](https://www.npmjs.com/package/class-variance-authority)
- [lucide-react](https://www.npmjs.com/package/lucide-react)
- [@tanstack/react-table](https://www.npmjs.com/package/@tanstack/react-table)

## Usage

```tsx
import {
  ResourceSchedulerPanel
} from "@docyrus/ui/components/resource-scheduler-panel";
import type {
  ResourceSchedulerPanelProps,
  SchedulerEvent,
  SchedulerResource,
  TimelinePreset,
  TimelinePresetConfig,
  TimeUnit,
  TimelineColumn,
  TimelineGroupHeader
} from "@docyrus/ui/components/resource-scheduler-panel";

```

## API Reference

| Prop | Type | Default |
|------|------|---------|
| `className` | `string` | — |

## Components

| Component | Description |
|-----------|-------------|
| `ResourceSchedulerPanel` | Public export |
| `ResourceSchedulerProvider` | Internal — `resource-scheduler-context.tsx` |
| `ResourceSchedulerDraggableEvent` | Internal — `resource-scheduler-draggable-event.tsx` |
| `ResourceSchedulerEventBar` | Internal — `resource-scheduler-event-bar.tsx` |
| `ResourceSchedulerEventPopover` | Internal — `resource-scheduler-event-popover.tsx` |
| `ResourceSchedulerEventRow` | Internal — `resource-scheduler-event-row.tsx` |
| `ResourceSchedulerHeader` | Internal — `resource-scheduler-header.tsx` |
| `ResourceSchedulerResourceList` | Internal — `resource-scheduler-resource-list.tsx` |
| `ResourceSchedulerTimelineHeader` | Internal — `resource-scheduler-timeline-header.tsx` |
| `ResourceSchedulerTimeline` | Internal — `resource-scheduler-timeline.tsx` |
| `ResourceSchedulerToday` | Internal — `resource-scheduler-today.tsx` |

## Type Exports

| Type | Description |
|------|-------------|
| `ResourceSchedulerPanelProps` | — |
| `SchedulerEvent` | — |
| `SchedulerResource` | — |
| `TimelinePreset` | — |
| `TimelinePresetConfig` | — |
| `TimeUnit` | — |
| `TimelineColumn` | — |
| `TimelineGroupHeader` | — |

## Type Reference

### ResourceSchedulerPanelProps

| Field | Type | Description |
|-------|------|-------------|
| `resources` | `Array<SchedulerResource>` | — |
| `events` | `Array<SchedulerEvent>` | — |
| `presets` | `Array<TimelinePreset>` | — |
| `defaultPresetId` | `string` | — |
| `startDate` | `Date` | — |
| `endDate` | `Date` | — |
| `resourceColumns` | `Array<ColumnDef<SchedulerResource>>` | — |
| `onEventClick` | `(event: SchedulerEvent) => void` | — |
| `onEventMove` | `(event: SchedulerEvent, newStart: Date, newEnd: Date, newResourceId?: string) => void` | — |
| `onEventResize` | `(event: SchedulerEvent, newStart: Date, newEnd: Date) => void` | — |
| `onSlotClick` | `(resourceId: string, date: Date) => void` | — |
| `onDateRangeChange` | `(start: Date, end: Date) => void` | — |
| `onPresetChange` | `(presetId: string) => void` | — |
| `isLoading` | `boolean` | — |
| `readOnly` | `boolean` | — |
| `showTodayIndicator` | `boolean` | — |
| `showResourceCount` | `boolean` | — |
| `height` | `number \| 'auto'` | — |
| `resourcePanelWidth` | `number` | — |
| `rowHeight` | `number` | — |
| `className` | `string` | — |
| `locale` | `string` | — |

### SchedulerEvent

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | — |
| `resourceId` | `string` | — |
| `title` | `string` | — |
| `startDate` | `Date` | — |
| `endDate` | `Date` | — |
| `color` | `string` | — |
| `variant` | `'solid' \| 'outlined' \| 'subtle'` | — |
| `icon` | `ReactNode` | — |
| `description` | `string` | — |
| `location` | `string` | — |
| `metadata` | `Record<string, unknown>` | — |

### SchedulerResource

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | — |
| `name` | `string` | — |
| `avatar` | `string` | — |
| `subtitle` | `string` | — |
| `group` | `string` | — |

### TimelinePreset

| Field | Type | Description |
|-------|------|-------------|
| `unitWidth` | `number` | — |
| `interval` | `{ unit: TimeUnit; format: string }` | — |
| `groups` | `Array<{ unit: TimeUnit; format: string }>` | — |

### TimelinePresetConfig

| Field | Type | Description |
|-------|------|-------------|
| `unitWidth` | `number` | — |
| `interval` | `{ unit: TimeUnit; format: string }` | — |
| `groups` | `Array<{ unit: TimeUnit; format: string }>` | — |

### TimeUnit

`"hour"` | `"day"` | `"week"` | `"month"` | `"year"`

### TimelineColumn

| Field | Type | Description |
|-------|------|-------------|
| `start` | `Date` | — |
| `end` | `Date` | — |
| `label` | `string` | — |
| `index` | `number` | — |

### TimelineGroupHeader

| Field | Type | Description |
|-------|------|-------------|
| `start` | `Date` | — |
| `end` | `Date` | — |
| `label` | `string` | — |
| `spanCount` | `number` | — |

---

# Schema Repeater
URL: /docs/web/components/schema-repeater

Schema Repeater component with multiple variants and sizes.

**Demo:**

```tsx
'use client';

import { useCallback, useState } from 'react';

import { SchemaRepeater } from '@docyrus/ui/components/schema-repeater';
import { Input } from '@docyrus/ui/primitives/ui/input';
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue
} from '@docyrus/ui/primitives/ui/select';

interface FilterRule {
  id: string;
  field: string;
  operator: string;
  value: string;
}

const FIELD_OPTIONS = [
  { value: 'name', label: 'Name' },
  { value: 'email', label: 'Email' },
  { value: 'status', label: 'Status' },
  { value: 'role', label: 'Role' },
  { value: 'created', label: 'Created At' }
];

const OPERATOR_OPTIONS = [
  { value: 'equals', label: 'equals' },
  { value: 'contains', label: 'contains' },
  { value: 'starts_with', label: 'starts with' },
  { value: 'ends_with', label: 'ends with' },
  { value: 'is_empty', label: 'is empty' }
];

let counter = 0;

export function SchemaRepeaterDemo() {
  const [rules, setRules] = useState
              
                ))}
              
            
            
              
                ))}
              
            
            <Input
              value={item.value}
              onChange={e => update({ value: e.target.value })}
              placeholder="Value..."
              className="h-8 flex-1 text-sm" />
          </div>
        )} />
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-schema-repeater
```

**Dependencies:**
- [lucide-react](https://www.npmjs.com/package/lucide-react)

## Usage

```tsx
import {
  SchemaRepeater
} from "@docyrus/ui/components/schema-repeater";

```

## API Reference

| Prop | Type | Default |
|------|------|---------|
| `className` | `string` | — |

---

# Search Input
URL: /docs/web/components/search-input

Search Input component with multiple variants and sizes.

**Demo:**

```tsx
'use client';
// @custom-demo

import { useCallback, useState } from 'react';

import { SearchInput, type SearchInputMode } from '@docyrus/ui/components/search-input';
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue
} from '@docyrus/ui/primitives/ui/select';
import { Switch } from '@docyrus/ui/primitives/ui/switch';
import { cn } from '@docyrus/ui/primitives/lib/utils';

export function SearchInputDemo() {
  type Variant = 'default' | 'outline' | 'ghost';
  type Size = 'default' | 'sm' | 'lg';

  const [variant, setVariant] = useState
                  
                    
                    
                  
                
              </div>
              <div className="space-y-1.5">
                <span className="text-xs font-medium">Size</span>
                
                  
                    
                    
                  
                
              </div>
              <div className="space-y-1.5">
                <span className="text-xs font-medium">Mode</span>
                
                  
                    
                  
                
              </div>
              <label className="flex items-center gap-2">
                
                <span className="text-xs">Disabled</span>
              </label>
            </div>
          </div>
        </div>
      </div>
      <div className="mx-auto max-w-sm space-y-3">
        
        {searchResult ? (
          <p className="text-center text-xs text-muted-foreground">{searchResult}</p>
        ) : null}
      </div>
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-search-input
```

**Dependencies:**
- [class-variance-authority](https://www.npmjs.com/package/class-variance-authority)
- [lucide-react](https://www.npmjs.com/package/lucide-react)

## Usage

```tsx
import {
  SearchInput
} from "@docyrus/ui/components/search-input";

<SearchInput
  variant="default"
  size="sm"
  ref={...}
  value="..."
  onValueChange={() => {}}
  onSearch={() => {}}
  mode="debounce"
  debounceMs={300}
/>
```

## Variants

| Variant | Description |
|---------|-------------|
| `default` | Default style |
| `outline` | Outline — `border-border focus-within:border-ring focus-within:ring-3 focus-within:ring-ring/50` |
| `ghost` | Ghost — `border-transparent shadow-none focus-within:border-ring focus-within:ring-3 focus-within:ring-ring/50` |

## Sizes

| Size | Description |
|------|-------------|
| `sm` | Small — `h-8 px-2 text-xs` |
| `default` | Default — `h-8 px-2.5 text-sm` |
| `lg` | Large — `h-11 px-3 text-base` |

## API Reference

| Prop | Type | Default |
|------|------|---------|
| `variant` | `"default"` \| `"outline"` \| `"ghost"` | `"default"` |
| `size` | `"sm"` \| `"default"` \| `"lg"` | `"default"` |
| `ref` | `Ref<HTMLInputElement>` | — |
| `value` | `string` | — |
| `onValueChange` | `(value: string) => void` | — |
| `onSearch` | `(value: string) => void` | — |
| `mode` | `SearchInputMode` | `'debounce'` |
| `debounceMs` | `number` | `300` |
| `className` | `string` | — |

---

# Simple Markdown Editor
URL: /docs/web/components/simple-markdown-editor

Simple Markdown Editor component with multiple variants and sizes.

**Demo:**

```tsx
'use client';

import { useState } from 'react';

import { SimpleMarkdownEditor } from '@docyrus/ui/components/simple-markdown-editor';
import { Badge } from '@docyrus/ui/primitives/ui/badge';

const INITIAL_MARKDOWN = `# Team Notes\n\n- Review PR #142\n- Prepare release notes\n- Sync API contracts`;

export function SimpleMarkdownEditorDemo() {
  const [value, setValue] = useState(INITIAL_MARKDOWN);

  return (
    <div className="space-y-3">
      
      
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-simple-markdown-editor
```

**Dependencies:**
- [class-variance-authority](https://www.npmjs.com/package/class-variance-authority)
- [overtype](https://www.npmjs.com/package/overtype)
- [lucide-react](https://www.npmjs.com/package/lucide-react)

## Usage

```tsx
import {
  SimpleMarkdownEditor
} from "@docyrus/ui/components/simple-markdown-editor";

<SimpleMarkdownEditor
  variant="default"
  size="sm"
  ref={...}
  value="..."
  defaultValue="..."
  onValueChange={() => {}}
  textareaProps={...}
/>
```

## Variants

| Variant | Description |
|---------|-------------|
| `default` | Default style |
| `muted` | Muted — `border-border/70 bg-muted/20` |

## Sizes

| Size | Description |
|------|-------------|
| `sm` | Small — `text-sm` |
| `default` | Default — `text-sm` |
| `lg` | Large — `text-base` |

## API Reference

| Prop | Type | Default |
|------|------|---------|
| `variant` | `"default"` \| `"muted"` | `"default"` |
| `size` | `"sm"` \| `"default"` \| `"lg"` | `"default"` |
| `ref` | `Ref<SimpleMarkdownEditorRef>` | — |
| `value` | `string` | — |
| `defaultValue` | `string` | — |
| `onValueChange` | `(value: string) => void` | — |
| `resizable` | `boolean` | `false` |
| `textareaProps` | `OverTypeOptions['textareaProps']` | — |
| `className` | `string` | — |

---

# Stepper
URL: /docs/web/components/stepper

A multi-step progress indicator with 6 visual variants, horizontal/vertical orientation, animated transitions, and customizable step icons.

**Demo:**

```tsx
'use client';
// @custom-demo

import { useState } from 'react';

import {
  Stepper, Step, type StepperVariant, type StepperOrientation, type StepperSize
} from '@docyrus/ui/components/stepper';
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue
} from '@docyrus/ui/primitives/ui/select';
import { Switch } from '@docyrus/ui/primitives/ui/switch';
import { cn } from '@docyrus/ui/primitives/lib/utils';

const STEPS = [
  { label: 'Account', description: 'Create your account' },
  { label: 'Profile', description: 'Set up your profile' },
  { label: 'Review', description: 'Review your details' },
  { label: 'Complete', description: 'All done!' }
];

export function StepperDemo() {
  const [activeStep, setActiveStep] = useState(1);
  const [variant, setVariant] = useState
                  
                    
                    
                    
                    
                    
                  
                
              </div>
              <div className="space-y-1.5">
                <span className="text-xs font-medium">Orientation</span>
                
                  
                    
                  
                
              </div>
              <div className="space-y-1.5">
                <span className="text-xs font-medium">Size</span>
                
                  
                    
                    
                  
                
              </div>
              <label className="flex items-center gap-2">
                
                <span className="text-xs">alternativeLabel</span>
              </label>
              <label className="flex items-center gap-2">
                
                <span className="text-xs">nonLinear</span>
              </label>
              <label className="flex items-center gap-2">
                
                <span className="text-xs">Error (Step 2)</span>
              </label>
            </div>
          </div>
        </div>
      </div>
      <div className="rounded-lg border border-border p-6">
        
        <div className="mt-6 flex items-center justify-between">
          <button
            type="button"
            className="rounded-md border border-border px-4 py-2 text-sm font-medium transition-colors hover:bg-accent disabled:opacity-50"
            disabled={activeStep === 0}
            onClick={() => setActiveStep(prev => prev - 1)}>
            Back
          </button>
          <span className="text-sm text-muted-foreground">
            Step {activeStep + 1} / {STEPS.length}
          </span>
          {activeStep < STEPS.length - 1 ? (
            <button
              type="button"
              className="rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground transition-colors hover:bg-primary/90"
              onClick={() => setActiveStep(prev => prev + 1)}>
              Next
            </button>
          ) : (
            <button
              type="button"
              className="rounded-md border border-border px-4 py-2 text-sm font-medium transition-colors hover:bg-accent"
              onClick={() => setActiveStep(0)}>
              Reset
            </button>
          )}
        </div>
      </div>
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-stepper
```

**Dependencies:**
- [motion](https://www.npmjs.com/package/motion)
- [@emotion/is-prop-valid](https://www.npmjs.com/package/@emotion/is-prop-valid)
- [class-variance-authority](https://www.npmjs.com/package/class-variance-authority)

## Usage

```tsx
import {
  Stepper,
  useStepperContext
} from '@docyrus/ui/components/stepper';
import type { StepProps } from '@docyrus/ui/components/stepper';

const steps: StepProps[] = [
  { label: 'Account', description: 'Create your account' },
  { label: 'Profile', description: 'Set up your profile' },
  { label: 'Complete', description: 'All done!' }
];

function MyWizard() {
  const [active, setActive] = useState(0);

  return (
    
  );
}
```

### Vertical Orientation

```tsx

```

### With Custom Icons & Status

```tsx

```

## Variants

| Variant | Description |
|---------|-------------|
| `default` | Numbered circles with filled background. |
| `outline` | Outlined circles with border. |
| `dots` | Small dots with pulse animation on active step. |
| `dashed` | Dashed connector lines. |
| `gradient` | Gradient-filled indicators. |
| `minimal` | Text-only with subtle indicators. |

## Sizes

| Size | Description |
|------|-------------|
| `sm` | Small indicators and text. |
| `default` | Standard size. |
| `lg` | Large indicators and text. |

## Components

| Component | Description |
|-----------|-------------|
| `Stepper` | Root component with context provider. Renders the step layout. |
| `Stepper.Step` | Individual step with icon, label, description, and status. |
| `StepConnector` | Line between steps. Animates on completion. |
| `useStepperContext` | Hook to access stepper state (activeStep, variant, size, etc.). |

## API Reference

### Stepper

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `activeStep` | `number` | `0` | Current active step index. |
| `variant` | `'default' \| 'outline' \| 'dots' \| 'dashed' \| 'gradient' \| 'minimal'` | `'default'` | Visual style of the stepper. |
| `size` | `'sm' \| 'default' \| 'lg'` | `'default'` | Size of step indicators. |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout direction. |
| `nonLinear` | `boolean` | `false` | Allow clicking on any step regardless of order. |
| `alternativeLabel` | `boolean` | `false` | Place labels below indicators instead of beside them. |
| `onStepClick` | `(index: number) => void` | — | Called when a step is clicked. |
| `connector` | `ReactNode` | — | Custom connector component between steps. |
| `className` | `string` | — | Additional CSS classes. |

### Step

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `label` | `ReactNode` | — | Step title text. |
| `description` | `ReactNode` | — | Step subtitle/description. |
| `icon` | `ReactNode` | — | Custom step icon. Falls back to step number. |
| `status` | `'wait' \| 'process' \| 'finish' \| 'error'` | — | Manual status override. Auto-determined from `activeStep` if not set. |
| `optional` | `boolean` | — | Mark as optional step. |
| `disabled` | `boolean` | — | Disable click interaction. |

### StepConnector

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `animated` | `boolean` | `true` | Animate the connector fill on completion. |

## Type Reference

### StepStatus

`'wait'` | `'process'` | `'finish'` | `'error'`

### StepperVariant

`'default'` | `'outline'` | `'dots'` | `'dashed'` | `'gradient'` | `'minimal'`

### StepperSize

`'sm'` | `'default'` | `'lg'`

### StepperOrientation

`'horizontal'` | `'vertical'`

---

# Team Chat Channel
URL: /docs/web/components/team-chat-channel

Team Chat Channel component.

**Demo:**

```tsx
'use client';

import { TeamChatChannel } from '@docyrus/ui/components/team-chat-channel';
import { TooltipProvider } from '@docyrus/ui/primitives/ui/tooltip';

import { useTeamChatChannelData } from '@/data/team-chat-channel-data';

export function TeamChatChannelDemo() {
  const {
    posts,
    currentUser,
    users,
    dataSources,
    onCreatePost,
    onDeletePost,
    onToggleReaction,
    onLoadReplies,
    onFetchLinkPreview,
    onSearchEntity
  } = useTeamChatChannelData();

  return (
    <div className="h-150 w-full max-w-2xl">
      
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-team-chat-channel
```

**Dependencies:**
- [lucide-react](https://www.npmjs.com/package/lucide-react)

## Usage

```tsx
import {
  TeamChatChannel
} from "@docyrus/ui/components/team-chat-channel";
import type {
  ChatUser,
  ChatPost,
  PostAttachment,
  PostReaction,
  LinkPreview,
  LinkedEntity,
  EntitySearchResult,
  DataSourceOption,
  CreatePostPayload,
  TeamChatChannelProps,
  PresetEmoji
} from "@docyrus/ui/components/team-chat-channel";

```

## API Reference

| Prop | Type | Default |
|------|------|---------|
| `className` | `string` | — |

## Components

| Component | Description |
|-----------|-------------|
| `TeamChatChannel` | Public export |
| `EntityMentionInput` | Internal — `entity-mention-input.tsx` |
| `PostActions` | Internal — `post-actions.tsx` |
| `PostAttachments` | Internal — `post-attachments.tsx` |
| `PostCard` | Internal — `post-card.tsx` |
| `PostComposer` | Internal — `post-composer.tsx` |
| `PostContent` | Internal — `post-content.tsx` |
| `PostEmptyState` | Internal — `post-empty-state.tsx` |
| `PostEntityLink` | Internal — `post-entity-link.tsx` |
| `PostLinkPreview` | Internal — `post-link-preview.tsx` |
| `PostReactions` | Internal — `post-reactions.tsx` |
| `PostThread` | Internal — `post-thread.tsx` |
| `TeamChatProvider` | Internal — `team-chat-context.tsx` |

## Type Exports

| Type | Description |
|------|-------------|
| `ChatUser` | — |
| `ChatPost` | — |
| `PostAttachment` | — |
| `PostReaction` | — |
| `LinkPreview` | — |
| `LinkedEntity` | — |
| `EntitySearchResult` | — |
| `DataSourceOption` | — |
| `CreatePostPayload` | — |
| `TeamChatChannelProps` | — |
| `PresetEmoji` | — |

## Type Reference

### ChatUser

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | — |
| `firstname` | `string \| null` | — |
| `lastname` | `string \| null` | — |

### ChatPost

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | — |
| `content` | `string` | — |
| `attachments` | `Array<PostAttachment> \| null` | — |
| `reactions` | `Array<PostReaction>` | — |
| `hashtags` | `Array<string>` | — |

### PostAttachment

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | — |

### PostReaction

| Field | Type | Description |
|-------|------|-------------|
| `emoji` | `string` | — |
| `count` | `number` | — |

### LinkPreview

| Field | Type | Description |
|-------|------|-------------|
| `url` | `string` | — |
| `title` | `string` | — |
| `description` | `string` | — |

### LinkedEntity

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | — |
| `icon` | `string` | — |

### EntitySearchResult

| Field | Type | Description |
|-------|------|-------------|
| `icon` | `string` | — |

### DataSourceOption

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | — |
| `name` | `string` | — |
| `icon` | `string` | — |

### CreatePostPayload

| Field | Type | Description |
|-------|------|-------------|
| `content` | `string` | — |
| `attachments` | `Array<File>` | — |
| `hashtags` | `Array<string>` | — |

### TeamChatChannelProps

| Field | Type | Description |
|-------|------|-------------|
| `posts` | `Array<ChatPost>` | — |
| `currentUser` | `ChatUser` | — |
| `users` | `Array<ChatUser>` | — |
| `channelName` | `string` | — |
| `isLoading` | `boolean` | — |
| `isCreatePending` | `boolean` | — |
| `isDeletePending` | `boolean` | — |
| `onCreatePost` | `(payload: CreatePostPayload) => void \| Promise<void>` | — |
| `onUpdatePost` | `(postId: string, content: string, options?: { removedAttachmentIds?: Array<string>; newFiles?: Array<File> }) => void \| Promise<void>` | — |
| `onDeletePost` | `(postId: string) => void \| Promise<void>` | — |
| `onToggleReaction` | `(postId: string, emoji: string) => void \| Promise<void>` | — |
| `onUploadFile` | `(file: File) => Promise<PostAttachment>` | — |
| `onFetchLinkPreview` | `(url: string) => Promise<LinkPreview \| null>` | — |
| `dataSources` | `Array<DataSourceOption>` | — |
| `onSearchEntity` | `(dataSourceId: string, query: string) => Promise<Array<EntitySearchResult>>` | — |
| `onLoadReplies` | `(postId: string) => Promise<Array<ChatPost>>` | — |
| `maxHeight` | `number \| string` | — |
| `className` | `string` | — |

### PresetEmoji

`"\ud83d\udc4d"` | `"\u2764\ufe0f"` | `"\ud83d\ude02"` | `"\ud83d\ude2e"` | `"\ud83c\udf89"` | `"\ud83d\udd25"` | `"\ud83d\udc40"` | `"\ud83d\udca1"`

---

# Time Slot Scheduler
URL: /docs/web/components/time-slot-scheduler

Time Slot Scheduler component.

**Demo:**

```tsx
'use client';

import { TimeSlotScheduler } from '@docyrus/ui/components/time-slot-scheduler';

import { getTimeSlotSchedulerData } from '@/data/time-slot-scheduler-data';

export function TimeSlotSchedulerDemo() {
  const {
    user, event, reservations, unavailableSlots, timezones
  }
    = getTimeSlotSchedulerData();

  return (
    <div className="overflow-x-auto">
      <div className="min-w-225">
        <TimeSlotScheduler
          user={user}
          event={event}
          reservations={reservations}
          unavailableSlots={unavailableSlots}
          timezones={timezones}
          defaultTimezone="America/New_York"
          slotCapacity={3}
          showReservationDetail
          onSelect={(slot) => {
            console.info('Selected slot:', slot);
          }} />
      </div>
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-time-slot-scheduler
```

**Dependencies:**
- [date-fns](https://www.npmjs.com/package/date-fns)
- [lucide-react](https://www.npmjs.com/package/lucide-react)
- [class-variance-authority](https://www.npmjs.com/package/class-variance-authority)

## Usage

```tsx
import {
  TimeSlotScheduler
} from "@docyrus/ui/components/time-slot-scheduler";
import type {
  DaySlots,
  DisabledReason,
  SchedulerEvent,
  SchedulerUser,
  SlotSelectPayload,
  SlotStatus,
  TimeSlot,
  TimeSlotReservation,
  TimeSlotSchedulerMode,
  TimeSlotSchedulerProps,
  TimezoneOption,
  UnavailableRange
} from "@docyrus/ui/components/time-slot-scheduler";

```

## API Reference

| Prop | Type | Default |
|------|------|---------|
| `className` | `string` | — |

## Components

| Component | Description |
|-----------|-------------|
| `TimeSlotScheduler` | Public export |
| `TimeSlotSchedulerProvider` | Internal — `time-slot-scheduler-context.tsx` |

## Type Exports

| Type | Description |
|------|-------------|
| `DaySlots` | — |
| `DisabledReason` | — |
| `SchedulerEvent` | — |
| `SchedulerUser` | — |
| `SlotSelectPayload` | — |
| `SlotStatus` | — |
| `TimeSlot` | — |
| `TimeSlotReservation` | — |
| `TimeSlotSchedulerMode` | — |
| `TimeSlotSchedulerProps` | — |
| `TimezoneOption` | — |
| `UnavailableRange` | — |

## Type Reference

### DaySlots

| Field | Type | Description |
|-------|------|-------------|
| `date` | `Date` | — |
| `dayLabel` | `string` | — |
| `dateLabel` | `string` | — |
| `fullLabel` | `string` | — |
| `isToday` | `boolean` | — |
| `isWeekend` | `boolean` | — |
| `slots` | `Array<TimeSlot>` | — |
| `hasAvailability` | `boolean` | — |

### DisabledReason

`"past"` | `"full"` | `"unavailable"` | `"before-min-date"` | `"after-max-date"`

### SchedulerEvent

| Field | Type | Description |
|-------|------|-------------|
| `subject` | `string` | — |
| `duration` | `string` | — |
| `location` | `string` | — |
| `description` | `string` | — |
| `icon` | `ReactNode` | — |

### SchedulerUser

| Field | Type | Description |
|-------|------|-------------|
| `fullName` | `string` | — |
| `email` | `string` | — |
| `avatarUrl` | `string` | — |

### SlotSelectPayload

| Field | Type | Description |
|-------|------|-------------|
| `day` | `Date` | — |
| `startTime` | `string` | — |
| `endTime` | `string` | — |
| `startISO` | `string` | — |
| `endISO` | `string` | — |
| `capacity` | `number` | — |
| `reservationCount` | `number` | — |
| `remainingCapacity` | `number` | — |
| `reservations` | `Array<TimeSlotReservation>` | — |

### SlotStatus

`"available"` | `"partial"` | `"full"` | `"unavailable"` | `"past"` | `"disabled"`

### TimeSlot

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | — |
| `name` | `string` | — |
| `email` | `string` | — |
| `avatarUrl` | `string` | — |
| `startTime` | `string` | — |
| `endTime` | `string` | — |

### TimeSlotReservation

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | — |
| `name` | `string` | — |
| `email` | `string` | — |
| `avatarUrl` | `string` | — |
| `startTime` | `string` | — |
| `endTime` | `string` | — |

### TimeSlotSchedulerMode

`"columns"` | `"month"`

### TimeSlotSchedulerProps

| Field | Type | Description |
|-------|------|-------------|
| `startTime` | `string` | — |
| `endTime` | `string` | — |
| `slotSize` | `number` | — |
| `slotCapacity` | `number` | — |
| `reservations` | `Array<TimeSlotReservation>` | — |
| `unavailableSlots` | `Array<UnavailableRange>` | — |
| `user` | `SchedulerUser` | — |
| `event` | `SchedulerEvent` | — |
| `mode` | `TimeSlotSchedulerMode` | — |
| `defaultMode` | `TimeSlotSchedulerMode` | — |
| `onModeChange` | `(mode: TimeSlotSchedulerMode) => void` | — |
| `defaultDate` | `Date` | — |
| `minDate` | `Date` | — |
| `maxDate` | `Date` | — |
| `showSaturday` | `boolean` | — |
| `showSunday` | `boolean` | — |
| `timezone` | `string` | — |
| `defaultTimezone` | `string` | — |
| `timezones` | `Array<TimezoneOption>` | — |
| `onTimezoneChange` | `(tz: string) => void` | — |
| `showReservationDetail` | `boolean` | — |
| `selectedSlot` | `SlotSelectPayload \| null` | — |
| `defaultSelectedSlot` | `SlotSelectPayload \| null` | — |
| `onSelect` | `(payload: SlotSelectPayload) => void` | — |
| `className` | `string` | — |

### TimezoneOption

| Field | Type | Description |
|-------|------|-------------|
| `value` | `string` | — |
| `label` | `string` | — |
| `offset` | `string` | — |

### UnavailableRange

| Field | Type | Description |
|-------|------|-------------|
| `day` | `string` | — |
| `startTime` | `string` | — |
| `endTime` | `string` | — |

---

# Timeline
URL: /docs/web/components/timeline

Vertical timeline with status indicators, alternate layout, animated entrance, and custom content slots.

**Demo:**

```tsx
'use client';

import { useState } from 'react';

import {
  Timeline,
  type TimelineItem,
  type TimelineLayout,
  type TimelineLineStyle,
  type TimelineSize,
  type TimelineVariant
} from '@docyrus/ui/components/timeline';
import { cn } from '@docyrus/ui/primitives/lib/utils';
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue
} from '@docyrus/ui/primitives/ui/select';
import { Switch } from '@docyrus/ui/primitives/ui/switch';

const STATUS_ITEMS: TimelineItem[] = [
  {
    title: 'Order placed',
    description: 'Your order was confirmed',
    time: '10:00 AM',
    status: 'completed'
  },
  {
    title: 'Payment processed',
    description: 'Payment verified successfully',
    time: '10:05 AM',
    status: 'completed'
  },
  {
    title: 'Shipped',
    description: 'On the way to you',
    time: '2:00 PM',
    status: 'active',
    content: (
      <span className="inline-flex rounded-full bg-primary/10 px-2.5 py-0.5 text-[11px] font-semibold text-primary">
        In Transit
      </span>
    )
  },
  {
    title: 'Out for delivery',
    time: '—',
    status: 'pending'
  },
  {
    title: 'Delivered',
    time: '—',
    status: 'pending'
  }
];

const BASIC_ITEMS: TimelineItem[] = [
  {
    title: 'Project kickoff',
    description: 'Defined scope and milestones',
    time: 'Jan 5'
  },
  {
    title: 'Design review',
    description: 'Approved UI mockups',
    time: 'Jan 12',
    dotColor: 'hsl(var(--warning))'
  },
  {
    title: 'Development sprint',
    description: 'Core features implemented',
    time: 'Feb 1',
    dotColor: 'hsl(var(--success))'
  },
  {
    title: 'Launch',
    description: 'Released to production',
    time: 'Feb 15'
  }
];

export function TimelineDemo() {
  const [size, setSize] = useState
                
                  
                  
                
              
            </div>

            <div className="space-y-1.5">
              <span className="text-xs font-medium">Variant</span>
              
                
                  
                
              
            </div>

            <div className="space-y-1.5">
              <span className="text-xs font-medium">Layout</span>
              
                
                  
                  
                
              
            </div>

            <div className="space-y-1.5">
              <span className="text-xs font-medium">Line Style</span>
              
                
                  
                
              
            </div>

            <div className="flex items-center gap-2 pt-5">
              
              <label htmlFor="animated" className="text-xs font-medium">Animated</label>
            </div>

            <div className="flex items-center gap-2 pt-5">
              
              <label htmlFor="statusMode" className="text-xs font-medium">Status Mode</label>
            </div>
          </div>
        </div>
      </div>

      {/* Timeline */}
      <div className="rounded-lg border border-border bg-card p-6">
        <Timeline
          key={`${animated}-${layout}`}
          items={items}
          size={size}
          variant={variant}
          layout={layout}
          lineStyle={lineStyle}
          animated={animated}
          onItemClick={(item) => {
            /* eslint-disable-next-line no-alert -- demo only */
            alert(`Clicked: ${item.title}`);
          }} />
      </div>
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-timeline
```

**Dependencies:**
- [class-variance-authority](https://www.npmjs.com/package/class-variance-authority)
- [lucide-react](https://www.npmjs.com/package/lucide-react)
- [motion](https://www.npmjs.com/package/motion)

## Usage

```tsx
import { Timeline, type TimelineItem } from "@docyrus/ui/components/timeline";

const items: TimelineItem[] = [
  { title: "Order placed", description: "Confirmed", time: "10:00 AM", status: "completed" },
  { title: "Shipped", description: "On the way", time: "2:00 PM", status: "active" },
  { title: "Delivered", time: "—", status: "pending" },
];

```

## Variants

| Variant | Description |
|---------|-------------|
| `default` | Filled dot — `bg-primary` |
| `outline` | Outlined dot — `border-2 border-primary bg-transparent` |

## Sizes

| Size | Dot | Status Dot | Text |
|------|-----|-----------|------|
| `sm` | `10px` | `20px` | `text-sm` / `text-xs` |
| `md` | `12px` | `24px` | `text-sm` / `text-sm` |
| `lg` | `16px` | `28px` | `text-base` / `text-sm` |

## Layouts

| Layout | Description |
|--------|-------------|
| `left` | Content on the right side of the timeline (default) |
| `alternate` | Content alternates left and right |
| `right` | Content on the left side of the timeline |

## Status Indicators

When `TimelineItem.status` is set, the dot renders a status icon instead of a plain dot.

| Status | Appearance | Line Style |
|--------|-----------|------------|
| `completed` | Green circle with check icon | Solid primary |
| `active` | Primary circle with inner ring | Dashed primary |
| `pending` | Small muted circle (opacity 50%) | Dashed muted |
| `error` | Red circle with X icon | Solid destructive |

## Line Styles

| Style | Description |
|-------|-------------|
| `solid` | Continuous line (default for completed/error) |
| `dashed` | Dashed line (default for active/pending) |

Line style can be set globally via `lineStyle` prop or per-item via `TimelineItem.lineStyle`.

## Custom Content

Each item supports a `content` slot for arbitrary React nodes below the description:

```tsx
const items: TimelineItem[] = [
  {
    title: "Shipped",
    status: "active",
    content: (
      <span className="inline-flex rounded-full bg-primary/10 px-2.5 py-0.5 text-xs font-semibold text-primary">
        In Transit
      </span>
    ),
  },
];
```

## Custom Icons

Use the `icon` slot to render a custom icon instead of the default dot:

```tsx
import { Rocket } from "lucide-react";

const items: TimelineItem[] = [
  {
    title: "Launch",
    icon: ,
  },
];
```

## Custom Dot Colors

Use `dotColor` to override the dot color for individual items (works with both `default` and `outline` variants):

```tsx
const items: TimelineItem[] = [
  { title: "Warning", dotColor: "hsl(var(--warning))" },
  { title: "Success", dotColor: "hsl(var(--success))" },
];
```

## Animation

Set `animated` to enable staggered fade-in entrance with framer-motion:

```tsx

```

## API Reference

### TimelineProps

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `items` | `TimelineItem[]` | — | Array of timeline events (required) |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size of dots, text, and spacing |
| `variant` | `'default' \| 'outline'` | `'default'` | Dot style (filled or outlined) |
| `lineStyle` | `'solid' \| 'dashed'` | — | Global line style (overridden by item.lineStyle or status) |
| `layout` | `'left' \| 'alternate' \| 'right'` | `'left'` | Content placement relative to timeline |
| `animated` | `boolean` | `false` | Enable staggered entrance animation |
| `onItemClick` | `(item: TimelineItem, index: number) => void` | — | Click handler for items |
| `titleClassName` | `string` | — | Custom class for title text |
| `descriptionClassName` | `string` | — | Custom class for description text |
| `timeClassName` | `string` | — | Custom class for time text |
| `className` | `string` | — | Container className |

### TimelineItem

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `title` | `string` | — | Item title (required) |
| `description` | `string` | — | Item description text |
| `time` | `string` | — | Time label |
| `icon` | `ReactNode` | — | Custom icon replacing the dot |
| `dotColor` | `string` | — | Override dot color |
| `status` | `'completed' \| 'active' \| 'pending' \| 'error'` | — | Status indicator (replaces dot with icon) |
| `content` | `ReactNode` | — | Custom content below description |
| `lineStyle` | `'solid' \| 'dashed'` | — | Per-item line style override |

## Type Exports

| Type | Description |
|------|-------------|
| `TimelineProps` | Props for the Timeline component |
| `TimelineItem` | Individual timeline item configuration |
| `TimelineSize` | `'sm' \| 'md' \| 'lg'` |
| `TimelineVariant` | `'default' \| 'outline'` |
| `TimelineStatus` | `'completed' \| 'active' \| 'pending' \| 'error'` |
| `TimelineLineStyle` | `'solid' \| 'dashed'` |
| `TimelineLayout` | `'left' \| 'alternate' \| 'right'` |

---

# Tree Select
URL: /docs/web/components/tree-select

A select dropdown backed by a tree. Single mode renders like Select; multi mode renders like Tag Select. Hierarchical search, expand-all and parent-cascade checking come from the embedded Tree View.

**Demo:**

```tsx
'use client';
// @custom-demo

import { useMemo, useState, type ReactNode } from 'react';

import {
  Briefcase,
  Building2,
  ChevronDown,
  Coins,
  Cpu,
  Database,
  Folder,
  Megaphone,
  Settings2,
  Users
} from 'lucide-react';

import {
  TreeSelect,
  type TreeSelectDefaultExpanded
} from '@docyrus/ui/components/tree-select';
import { type TreeViewItem } from '@docyrus/ui/components/tree-view';
import { Button } from '@docyrus/ui/primitives/ui/button';
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue
} from '@docyrus/ui/primitives/ui/select';
import { Switch } from '@docyrus/ui/primitives/ui/switch';
import { cn } from '@docyrus/ui/primitives/lib/utils';

const DEPARTMENT_TREE: TreeViewItem[] = [
  {
    id: 'engineering',
    name: 'Engineering',
    type: 'group',
    children: [
      {
        id: 'frontend',
        name: 'Frontend',
        type: 'team',
        children: [{ id: 'web', name: 'Web', type: 'leaf' }, { id: 'mobile', name: 'Mobile', type: 'leaf' }, { id: 'design-systems', name: 'Design Systems', type: 'leaf' }]
      },
      {
        id: 'backend',
        name: 'Backend',
        type: 'team',
        children: [{ id: 'api', name: 'API Platform', type: 'leaf' }, { id: 'data', name: 'Data Platform', type: 'leaf' }, { id: 'infra', name: 'Infrastructure', type: 'leaf' }]
      }
    ]
  },
  {
    id: 'product',
    name: 'Product',
    type: 'group',
    children: [{ id: 'design', name: 'Design', type: 'leaf' }, { id: 'research', name: 'Research', type: 'leaf' }, { id: 'analytics', name: 'Analytics', type: 'leaf' }]
  },
  {
    id: 'gtm',
    name: 'Go-to-market',
    type: 'group',
    children: [{ id: 'marketing', name: 'Marketing', type: 'leaf' }, { id: 'sales', name: 'Sales', type: 'leaf' }, { id: 'cs', name: 'Customer Success', type: 'leaf' }]
  },
  {
    id: 'ops',
    name: 'Operations',
    type: 'group',
    children: [{ id: 'finance', name: 'Finance', type: 'leaf' }, { id: 'people', name: 'People Ops', type: 'leaf' }]
  }
];

const ICON_MAP: Record<string, ReactNode> = {
  group: 
      </div>

      <div
        className={cn(
          'grid transition-[grid-template-rows] duration-300 ease-in-out',
          open ? 'grid-rows-[1fr]' : 'grid-rows-[0fr]'
        )}>
        <div className="overflow-hidden">
          <div className="mb-4 grid gap-4 rounded-lg border border-border bg-muted/30 p-4 sm:grid-cols-2 lg:grid-cols-3">
            <label className="flex items-center gap-2">
              
              <span className="text-xs">Multiple</span>
            </label>
            <label className="flex items-center gap-2">
              
              <span className="text-xs">Leaf only</span>
            </label>
            <label className="flex items-center gap-2">
              
              <span className="text-xs">Show breadcrumb</span>
            </label>
            <label className="flex items-center gap-2">
              
              <span className="text-xs">Icons</span>
            </label>
            <label className="flex items-center gap-2">
              
              <span className="text-xs">Disabled</span>
            </label>
            <div className="flex items-center gap-2">
              <span className="text-xs">Default expanded</span>
              
                
                  
                  
                
              
            </div>
          </div>
        </div>
      </div>

      <div className="mx-auto max-w-md space-y-3">
        <TreeSelect
          data={DEPARTMENT_TREE}
          value={value}
          onValueChange={(next) => {
            if (multiple) {
              setMultiValue(Array.isArray(next) ? next : []);

              return;
            }
            setSingleValue(typeof next === 'string' ? next : null);
          }}
          multiple={multiple}
          leafOnly={leafOnly}
          defaultExpanded={defaultExpanded}
          showBreadcrumb={showBreadcrumb}
          disabled={disabled}
          maxHeight="320px"
          getIcon={showIcons ? renderIcon : undefined}
          searchPlaceholder="Search departments..." />

        <p className="text-center text-xs text-muted-foreground">
          {multiple ? leafOnly ? 'Click a folder row to expand it; tick checkboxes to add leaf departments.' : 'Tick checkboxes to add departments. Ticking a parent cascades to its descendants.' : leafOnly ? 'Click a folder row to expand it; only leaf rows commit a value.' : 'Click a row to pick a single department. The dropdown closes on selection.'}
        </p>

        <pre className="overflow-x-auto rounded-md border border-border bg-muted/40 px-3 py-2 text-xs">
          <span className="text-muted-foreground">value =</span> {valueLabel}
        </pre>
      </div>
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-tree-select
```

**Dependencies:**
- [lucide-react](https://www.npmjs.com/package/lucide-react)

## Overview

`TreeSelect` is a [Popover](/docs/web/components/popover)-anchored picker whose
dropdown body is the [`TreeView`](/docs/web/components/tree-view) component.
Pass `multiple` to switch between two trigger shapes that mirror the existing
form-field family:

| Mode | Trigger | Dropdown |
|------|---------|----------|
| `multiple={false}` (default) | One-line, [Select](/docs/web/components/select)-style row | TreeView without checkboxes — clicking a row picks it and closes the popover |
| `multiple` | Wrap-flowing badges with per-badge `×` — same shape as [Tag Select](/docs/web/components/form-fields) | TreeView with checkboxes — ticking a parent cascades to its descendants |

The dropdown's search input, expand/collapse-all menu and keyboard support
come straight from `TreeView`, so the same `TreeViewItem[]` you'd pass to a
plain tree works here without any reshaping.

## Usage

```tsx
import { TreeSelect } from "@docyrus/ui/components/tree-select";
import { type TreeViewItem } from "@docyrus/ui/components/tree-view";

const data: TreeViewItem[] = [
  {
    id: "engineering",
    name: "Engineering",
    type: "group",
    children: [
      { id: "frontend", name: "Frontend", type: "team" },
      { id: "backend", name: "Backend", type: "team" }
    ]
  },
  { id: "product", name: "Product", type: "group" }
];

export function Example() {
  const [value, setValue] = useState<string | null>(null);

  return (
    <TreeSelect
      data={data}
      value={value}
      onValueChange={(next) => setValue(typeof next === "string" ? next : null)}
      placeholder="Select a department..."
    />
  );
}
```

### Multi-select

Set `multiple` and treat `value` as an array of ids. The trigger renders one
removable badge per selection.

```tsx
const [value, setValue] = useState<string[]>([]);

<TreeSelect
  data={data}
  multiple
  value={value}
  onValueChange={(next) => setValue(Array.isArray(next) ? next : [])}
/>
```

### Leaf-only selection

Set `leafOnly` to restrict the value to leaf nodes only:

- **Single mode** — clicking a folder row expands / collapses it instead of
  committing a value. Only leaf rows commit.
- **Multi mode** — checking a folder cascades to its **leaf** descendants
  only; the folder id itself never enters `value`. Clicking a folder row
  (outside the checkbox) also expands / collapses it.

This relies on `TreeView`'s new `expandFolderOnRowClick` flag, which
`TreeSelect` enables automatically when `leafOnly` is on.

The default (`leafOnly={false}`) treats folders as selectable values and makes
a checked folder add the folder id **and** every descendant id.

```tsx
<TreeSelect
  data={data}
  multiple
  leafOnly
  value={value}
  onValueChange={(next) => setValue(Array.isArray(next) ? next : [])}
/>
```

### Default expansion

`defaultExpanded` controls which folders are open each time the dropdown
mounts. The default — `'selected'` — auto-expands the ancestor chain of every
currently-selected item so the value is always visible on reopen.

```tsx
// Always show the full tree.

// Start fully collapsed.

// Open exactly these folders.

```

| Value | Behaviour |
|-------|-----------|
| `'selected'` (default) | Expand ancestors of items in `value`. No-op when `value` is empty. |
| `'all'` | Expand every folder. |
| `'none'` | Start fully collapsed. |
| `string[]` | Expand exactly these ids. |

The popover unmounts its content on close, so the strategy is re-applied
every time the dropdown opens — `'selected'` always reflects the current
value, not the initial one.

### Trigger breadcrumb

Set `showBreadcrumb` to render the ancestor path on the trigger for each
selected item. Ancestor names render in muted text; the leaf name uses the
foreground color. `renderSelected` still wins when both are supplied.

```tsx
<TreeSelect
  data={data}
  showBreadcrumb
  value={value}
  onValueChange={(next) => setValue(typeof next === "string" ? next : null)}
/>
// Trigger shows:  Engineering › Frontend › Web
```

In multi mode the breadcrumb is repeated **per badge**, so each chip carries
its own ancestor chain.

### Custom row icons

Forward `getIcon` (and / or `iconMap`) directly to the underlying TreeView. The
same `(item, depth) => ReactNode` signature applies.

```tsx
import { Building2, Folder, Briefcase } from "lucide-react";

const iconMap = {
  group: <Building2 className="size-4 text-amber-500" />,
  team: ,
  leaf: 
};

```

### Custom trigger badges

`renderSelected` controls how each selected item appears inside the trigger.
Use it to inject icons, color swatches, or any custom shape — the per-badge
remove button (`×`) is added automatically in multi mode.

```tsx
<TreeSelect
  data={data}
  multiple
  renderSelected={(item) => (
    <span className="flex items-center gap-1">
      
      <span className="truncate">{item.name}</span>
    </span>
  )}
/>
```

### Controlled open state

`TreeSelect` is uncontrolled by default — pass `open` + `onOpenChange` to take
over the popover state (useful when driving the picker from a toolbar button
or external keyboard shortcut).

```tsx
const [open, setOpen] = useState(false);

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `TreeViewItem[]` | — | Tree data shown in the dropdown. Reuses the [TreeView](/docs/web/components/tree-view) data shape. |
| `value` | `string \| string[] \| null` | — | Currently selected id(s). String in single mode, array in multi mode. |
| `onValueChange` | `(value: string \| string[] \| null) => void` | — | Fired when the selection changes. Receives `string \| null` in single mode, `string[]` in multi mode. |
| `multiple` | `boolean` | `false` | Enable multi-select mode (badge trigger + checkbox dropdown). |
| `placeholder` | `string` | `'Select...'` / `'Select items...'` | Placeholder shown when nothing is selected. Falls back to a localized default. |
| `disabled` | `boolean` | `false` | Disable the trigger button. |
| `className` | `string` | — | Class applied to the trigger button. |
| `id` | `string` | — | Trigger button id — pair with a `<label htmlFor>`. |
| `name` | `string` | — | Form association name. |
| `onBlur` | `() => void` | — | Blur handler forwarded to the trigger. |
| `aria-invalid` | `boolean` | — | Show invalid styling on the trigger. |
| `maxHeight` | `string` | `'320px'` | Max height of the tree view inside the dropdown. |
| `getIcon` | `(item: TreeViewItem, depth: number) => ReactNode` | — | Custom icon renderer — forwarded to `TreeView.getIcon`. |
| `iconMap` | `TreeViewIconMap` | — | Map of `item.type` → icon — forwarded to `TreeView.iconMap`. |
| `hideInfo` | `boolean` | `true` | Hide the per-row hover-card info button (forwarded as `showInfo={!hideInfo}` to TreeView). |
| `searchPlaceholder` | `string` | — | Override the search input placeholder. Defaults to TreeView's localized default. |
| `leafOnly` | `boolean` | `false` | Restrict selection to leaf nodes. In single mode, folder clicks only expand / collapse. In multi mode, a parent's checkbox cascades to descendant **leaves** only. |
| `defaultExpanded` | `'none' \| 'all' \| 'selected' \| string[]` | `'selected'` | Initial expansion strategy applied each time the dropdown opens. `'selected'` expands ancestors of items in `value`. |
| `showBreadcrumb` | `boolean` | `false` | Render an ancestor breadcrumb (`Group › Subgroup › Item`) inside the trigger for each selected item. |
| `renderSelected` | `(item: TreeViewItem) => ReactNode` | — | Custom rendering for a selected item inside the trigger. Wins over `showBreadcrumb` when both are supplied. |
| `open` | `boolean` | — | Controlled open state for the popover. |
| `onOpenChange` | `(open: boolean) => void` | — | Fired when the popover opens or closes. |
| `ref` | `Ref<HTMLButtonElement>` | — | Ref to the trigger button. |

## Type Exports

| Type | Description |
|------|-------------|
| `TreeSelectProps` | Props for `TreeSelect`. |
| `TreeSelectValue` | `string \| string[] \| null \| undefined` — value shape across both modes. |
| `TreeSelectDefaultExpanded` | `'none' \| 'all' \| 'selected' \| ReadonlyArray<string>` — initial expansion strategies for the dropdown. |

## Form-field wrapper

[`TreeSelectFormField`](/docs/web/components/form-fields) (exported from
`@docyrus/ui/components/form-fields`) bridges `TreeSelect` to TanStack Form.
It converts flat `enumOptions` with `parent` references into a tree using
`field.nestedByProp` (default `'parent'`), then reads the following keys
from `field.options` to drive behaviour:

| `field.options` key | Maps to | Notes |
|---------------------|---------|-------|
| `multiple` | `multiple` | `true` switches to badge trigger + checkboxes. |
| `leafOnly` | `leafOnly` | Restrict the value to leaf nodes. |
| `defaultExpanded` | `defaultExpanded` | Accepts `'none' \| 'all' \| 'selected'` or a `string[]`. Invalid values fall back to the standalone default. |
| `showBreadcrumb` | `showBreadcrumb` | Render an ancestor breadcrumb on the trigger. |

```tsx
import { TreeSelectFormField } from "@docyrus/ui/components/form-fields";

```

---

# Tree Table
URL: /docs/web/components/tree-table

Tree Table component with multiple variants and sizes.

**Demo:**

```tsx
'use client';
// @custom-demo

import { useState, type ReactNode } from 'react';

import {
  TreeTable,
  type TreeTableColumn
} from '@docyrus/ui/components/tree-table';
import { type TreeViewItem } from '@docyrus/ui/components/tree-view';
import { Badge } from '@docyrus/ui/primitives/ui/badge';
import { Button } from '@docyrus/ui/primitives/ui/button';
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue
} from '@docyrus/ui/primitives/ui/select';
import { Switch } from '@docyrus/ui/primitives/ui/switch';
import { cn } from '@docyrus/ui/primitives/lib/utils';
import {
  FileText,
  Folder,
  FolderOpen
} from 'lucide-react';

type TreeTableDemoItem = TreeViewItem & {
  owner: string;
  status: 'Planned' | 'In Progress' | 'Done';
  updatedAt: string;
};

function makeTreeTableData(): TreeTableDemoItem[] {
  return [
    {
      id: 'product',
      name: 'Product',
      type: 'folder',
      owner: 'Ava',
      status: 'In Progress',
      updatedAt: 'Today',
      children: [
        {
          id: 'roadmap',
          name: 'Roadmap',
          type: 'folder',
          owner: 'Ava',
          status: 'In Progress',
          updatedAt: '1h ago',
          children: [
            {
              id: 'q3-review',
              name: 'Q3 Review',
              type: 'file',
              owner: 'Milo',
              status: 'Done',
              updatedAt: '10m ago'
            },
            {
              id: 'pricing-tests',
              name: 'Pricing Tests',
              type: 'file',
              owner: 'Iris',
              status: 'Planned',
              updatedAt: 'Yesterday'
            }
          ]
        },
        {
          id: 'research',
          name: 'User Research',
          type: 'file',
          owner: 'Noah',
          status: 'Done',
          updatedAt: '2d ago'
        }
      ]
    },
    {
      id: 'operations',
      name: 'Operations',
      type: 'folder',
      owner: 'Lena',
      status: 'Planned',
      updatedAt: 'Today',
      children: [
        {
          id: 'vendors',
          name: 'Vendor Audit',
          type: 'file',
          owner: 'Lena',
          status: 'In Progress',
          updatedAt: '3h ago'
        },
        {
          id: 'checklist',
          name: 'Launch Checklist',
          type: 'file',
          owner: 'Jade',
          status: 'Planned',
          updatedAt: '4d ago'
        }
      ]
    },
    {
      id: 'archive',
      name: 'Archive',
      type: 'folder',
      owner: 'Kai',
      status: 'Done',
      updatedAt: 'Last week',
      children: []
    }
  ];
}

function renderStatus(status: TreeTableDemoItem['status']) {
  if (status === 'Done') {
    return ;
  }

  if (status === 'In Progress') {
    return ;
  }

  return ;
}

const TREE_TABLE_COLUMNS: TreeTableColumn[] = [
  {
    id: 'owner',
    header: 'Owner',
    accessorKey: 'owner',
    width: 140
  },
  {
    id: 'status',
    header: 'Status',
    width: 150,
    cell: item => renderStatus(item.status as TreeTableDemoItem['status'])
  },
  {
    id: 'updatedAt',
    header: 'Updated',
    accessorKey: 'updatedAt',
    width: 120,
    align: 'right',
    className: 'text-muted-foreground'
  }
];

export function TreeTableDemo() {
  type Variant = 'default' | 'outline' | 'ghost';
  type Size = 'default' | 'sm' | 'lg';

  const [data, setData] = useState
      </div>

      <div
        className={cn(
          'grid transition-[grid-template-rows] duration-300 ease-in-out',
          open ? 'grid-rows-[1fr]' : 'grid-rows-[0fr]'
        )}>
        <div className="overflow-hidden">
          <div className="mb-4 grid gap-6 rounded-lg border border-border bg-muted/30 p-4">
            <div className="flex flex-wrap items-center gap-4">
              <div className="space-y-1.5">
                <span className="text-xs font-medium">Variant</span>
                
                  
                    
                    
                  
                
              </div>
              <div className="space-y-1.5">
                <span className="text-xs font-medium">Size</span>
                
                  
                    
                    
                  
                
              </div>
              <label className="flex items-center gap-2">
                
                <span className="text-xs">Drag &amp; Drop</span>
              </label>
            </div>
          </div>
        </div>
      </div>

      <div className="mx-auto max-w-4xl space-y-3">
        <TreeTable
          data={data}
          columns={TREE_TABLE_COLUMNS}
          variant={variant}
          size={size}
          draggable={draggable}
          getIcon={getIcon}
          maxHeight="420px"
          onDataChange={nextData => setData(nextData as TreeTableDemoItem[])} />
        <p className="text-center text-xs text-muted-foreground">
          Use the drag handle to reorder rows, drop onto a folder row to nest an item,
          or drop between top-level rows to bring an item back to the root.
        </p>
      </div>
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-tree-table
```

**Dependencies:**
- [@dnd-kit/core](https://www.npmjs.com/package/@dnd-kit/core)
- [@dnd-kit/utilities](https://www.npmjs.com/package/@dnd-kit/utilities)
- [lucide-react](https://www.npmjs.com/package/lucide-react)

## Usage

```tsx
import {
  TreeTable
} from "@docyrus/ui/components/tree-table";

<TreeTable
  ref={...}
  data={TreeViewItem[]}
  columns={TreeTableColumn[]}
  nameColumnHeader={...}
  getIcon={() => {}}
  showExpandAll
  searchPlaceholder="..."
  emptyText="..."
  draggable
  canDropInside={() => {}}
  onDataChange={(nextData: TreeViewItem, details: TreeViewMoveDetails) = void[]}
  maxHeight="..."
/>
```

## API Reference

| Prop | Type | Default |
|------|------|---------|
| `ref` | `Ref<HTMLDivElement>` | — |
| `data` | `TreeViewItem[]` | — |
| `columns` | `TreeTableColumn[]` | — |
| `nameColumnHeader` | `ReactNode` | — |
| `getIcon` | `(item: TreeViewItem, depth: number) => ReactNode` | — |
| `showExpandAll` | `boolean` | — |
| `searchPlaceholder` | `string` | — |
| `emptyText` | `string` | — |
| `draggable` | `boolean` | — |
| `canDropInside` | `(item: TreeViewItem) => boolean` | — |
| `onDataChange` | `(nextData: TreeViewItem[], details: TreeViewMoveDetails) => void` | — |
| `maxHeight` | `string` | — |
| `className` | `string` | — |

---

# Tree View
URL: /docs/web/components/tree-view

Tree View component with multiple variants and sizes.

**Demo:**

```tsx
'use client';
// @custom-demo

import { useCallback, useState, type ReactNode } from 'react';

import {
  TreeView,
  type TreeViewCheckboxPosition,
  type TreeViewItem,
  type TreeViewMenuItem
} from '@docyrus/ui/components/tree-view';
import { Button } from '@docyrus/ui/primitives/ui/button';
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue
} from '@docyrus/ui/primitives/ui/select';
import { Switch } from '@docyrus/ui/primitives/ui/switch';
import { cn } from '@docyrus/ui/primitives/lib/utils';
import {
  File, FileText, Folder, Image, Music, Video
} from 'lucide-react';

/* ------------------------------------------------------------------ */
/*  Sample data                                                        */
/* ------------------------------------------------------------------ */

function makeSampleData(): TreeViewItem[] {
  return [
    {
      id: 'src',
      name: 'src',
      type: 'folder',
      children: [
        {
          id: 'components',
          name: 'components',
          type: 'folder',
          children: [
            {
              id: 'button-tsx', name: 'button.tsx', type: 'file', checked: true
            },
            {
              id: 'dialog-tsx', name: 'dialog.tsx', type: 'file', checked: false
            },
            {
              id: 'input-tsx', name: 'input.tsx', type: 'file', checked: true
            },
            {
              id: 'tree-view-tsx', name: 'tree-view.tsx', type: 'file', checked: false
            }
          ]
        },
        {
          id: 'hooks',
          name: 'hooks',
          type: 'folder',
          children: [
            {
              id: 'use-debounce', name: 'use-debounce.ts', type: 'file', checked: true
            },
            {
              id: 'use-media-query', name: 'use-media-query.ts', type: 'file', checked: false
            }
          ]
        },
        {
          id: 'lib',
          name: 'lib',
          type: 'folder',
          children: [
            {
              id: 'utils-ts', name: 'utils.ts', type: 'file', checked: true
            }
          ]
        },
        {
          id: 'app-tsx', name: 'App.tsx', type: 'file', checked: true
        },
        {
          id: 'main-tsx', name: 'main.tsx', type: 'file', checked: true
        }
      ]
    },
    {
      id: 'public',
      name: 'public',
      type: 'folder',
      children: [
        {
          id: 'favicon', name: 'favicon.ico', type: 'image', checked: false
        },
        {
          id: 'logo-svg', name: 'logo.svg', type: 'image', checked: false
        },
        {
          id: 'assets',
          name: 'assets',
          type: 'folder',
          children: [
            {
              id: 'hero-png', name: 'hero.png', type: 'image', checked: false
            },
            {
              id: 'bg-mp4', name: 'background.mp4', type: 'video', checked: false
            },
            {
              id: 'notification-mp3', name: 'notification.mp3', type: 'audio', checked: false
            }
          ]
        }
      ]
    },
    {
      id: 'package-json', name: 'package.json', type: 'file', checked: true
    },
    {
      id: 'readme', name: 'README.md', type: 'file', checked: false
    },
    {
      id: 'tsconfig', name: 'tsconfig.json', type: 'file', checked: false
    }
  ];
}

/* ------------------------------------------------------------------ */
/*  Icon map                                                           */
/* ------------------------------------------------------------------ */

const FILE_ICON_MAP: Record<string, ReactNode> = {
  folder: ,
  file: ,
  image: ,
  video: ,
  audio: 
};

/* ------------------------------------------------------------------ */
/*  Demo                                                               */
/* ------------------------------------------------------------------ */

export function TreeViewDemo() {
  type Variant = 'default' | 'outline' | 'ghost';
  type Size = 'default' | 'sm' | 'lg';

  const [variant, setVariant] = useState
      </div>

      {/* Configure panel */}
      <div
        className={cn(
          'grid transition-[grid-template-rows] duration-300 ease-in-out',
          open ? 'grid-rows-[1fr]' : 'grid-rows-[0fr]'
        )}>
        <div className="overflow-hidden">
          <div className="mb-4 grid gap-6 rounded-lg border border-border bg-muted/30 p-4">
            <div className="flex flex-wrap items-center gap-4">
              <div className="space-y-1.5">
                <span className="text-xs font-medium">Variant</span>
                
                  
                    
                    
                  
                
              </div>
              <div className="space-y-1.5">
                <span className="text-xs font-medium">Size</span>
                
                  
                    
                    
                  
                
              </div>
              <div className="space-y-1.5">
                <span className="text-xs font-medium">Checkbox Position</span>
                
                  
                    
                  
                
              </div>
              <label className="flex items-center gap-2">
                
                <span className="text-xs">Checkboxes</span>
              </label>
              <label className="flex items-center gap-2">
                
                <span className="text-xs">Expand All</span>
              </label>
              <label className="flex items-center gap-2">
                
                <span className="text-xs">Info Tooltip</span>
              </label>
              <label className="flex items-center gap-2">
                
                <span className="text-xs">Drag &amp; Drop</span>
              </label>
            </div>
          </div>
        </div>
      </div>

      {/* Component preview */}
      <div className="mx-auto max-w-xl space-y-3">
        
        <p className="text-center text-xs text-muted-foreground">
          Drag a row handle to reorder siblings, drop on a folder to move inside it,
          or drop between root items to promote something back to the top level.
        </p>
        {selection.length > 0 ? (
          <p className="text-center text-xs text-muted-foreground">
            Selected: {selection.map(s => s.name).join(', ')}
          </p>
        ) : null}
      </div>
    </div>
  );
}

/* ------------------------------------------------------------------ */
/*  Utils                                                              */
/* ------------------------------------------------------------------ */

function setAllChecked(items: TreeViewItem[], checked: boolean): TreeViewItem[] {
  return items.map(it => ({
    ...it,
    checked,
    children: it.children ? setAllChecked(it.children, checked) : undefined
  }));
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-tree-view
```

**Dependencies:**
- [@dnd-kit/core](https://www.npmjs.com/package/@dnd-kit/core)
- [@dnd-kit/utilities](https://www.npmjs.com/package/@dnd-kit/utilities)
- [lucide-react](https://www.npmjs.com/package/lucide-react)
- [motion](https://www.npmjs.com/package/motion)
- [@emotion/is-prop-valid](https://www.npmjs.com/package/@emotion/is-prop-valid)
- [class-variance-authority](https://www.npmjs.com/package/class-variance-authority)

## Usage

```tsx
import {
  TreeView
} from "@docyrus/ui/components/tree-view";

<TreeView
  variant="default"
  size="sm"
  ref={...}
  data={TreeViewItem[]}
  showExpandAll
  showCheckboxes
  checkboxPosition="left"
  searchPlaceholder="..."
  selectionText="..."
  checkboxLabels={...}
  getIcon={() => {}}
  onSelectionChange={(selectedItems: TreeViewItem) = void[]}
  onAction={(action: string, items: TreeViewItem) = void[]}
  onCheckChange={() => {}}
  onDataChange={(nextData: TreeViewItem, details: TreeViewMoveDetails) = void[]}
  draggable
  canDropInside={() => {}}
  iconMap={...}
  menuItems={TreeViewMenuItem[]}
  showInfo
  maxHeight="..."
  defaultExpandedIds={Readonlystring[]}
  expandFolderOnRowClick
  onItemClick={() => {}}
  selectOnRowClick
/>
```

## Variants

| Variant | Description |
|---------|-------------|
| `default` | Default style |
| `outline` | Outline — `border-2 border-border` |
| `ghost` | Ghost — `border-transparent shadow-none` |

## Sizes

| Size | Description |
|------|-------------|
| `sm` | Small — `text-xs` |
| `default` | Default — `text-sm` |
| `lg` | Large — `text-base` |

## API Reference

| Prop | Type | Default |
|------|------|---------|
| `variant` | `"default"` \| `"outline"` \| `"ghost"` | `"default"` |
| `size` | `"sm"` \| `"default"` \| `"lg"` | `"default"` |
| `ref` | `Ref<HTMLDivElement>` | — |
| `data` | `TreeViewItem[]` | — |
| `showExpandAll` | `boolean` | — |
| `showCheckboxes` | `boolean` | — |
| `checkboxPosition` | `TreeViewCheckboxPosition` | — |
| `searchPlaceholder` | `string` | — |
| `selectionText` | `string` | — |
| `checkboxLabels` | `{ check: string; uncheck: string }` | — |
| `getIcon` | `(item: TreeViewItem, depth: number) => ReactNode` | — |
| `onSelectionChange` | `(selectedItems: TreeViewItem[]) => void` | — |
| `onAction` | `(action: string, items: TreeViewItem[]) => void` | — |
| `onCheckChange` | `(item: TreeViewItem, checked: boolean) => void` | — |
| `onDataChange` | `(nextData: TreeViewItem[], details: TreeViewMoveDetails) => void` | — |
| `draggable` | `boolean` | — |
| `canDropInside` | `(item: TreeViewItem) => boolean` | — |
| `iconMap` | `TreeViewIconMap` | — |
| `menuItems` | `TreeViewMenuItem[]` | — |
| `showInfo` | `boolean` | — |
| `maxHeight` | `string` | — |
| `defaultExpandedIds` | `ReadonlyArray<string>` | — |
| `expandFolderOnRowClick` | `boolean` | — |
| `onItemClick` | `(item: TreeViewItem) => void` | — |
| `selectOnRowClick` | `boolean` | — |
| `className` | `string` | — |

---

# Value Renderers
URL: /docs/web/components/value-renderers

Read-only value display system for table cells, detail views, and kanban cards. 44 renderer types with automatic dispatch via DynamicValue.

**Demo:**

```tsx
'use client';
// @custom-demo

import { type ReactNode } from 'react';

import { ApprovalStatusValue } from '@docyrus/ui/components/value-renderers/approval-status-value';
import { AvatarValue } from '@docyrus/ui/components/value-renderers/avatar-value';
import { ButtonValue } from '@docyrus/ui/components/value-renderers/button-value';
import { CheckboxValue } from '@docyrus/ui/components/value-renderers/checkbox-value';
import { CodeValue } from '@docyrus/ui/components/value-renderers/code-value';
import { ColorValue } from '@docyrus/ui/components/value-renderers/color-value';
import { ConversationChannelValue } from '@docyrus/ui/components/value-renderers/conversation-channel-value';
import { CurrencyCodeValue } from '@docyrus/ui/components/value-renderers/currency-code-value';
import { DateRangeValue } from '@docyrus/ui/components/value-renderers/date-range-value';
import { DateValue } from '@docyrus/ui/components/value-renderers/date-value';
import { DateTimeValue } from '@docyrus/ui/components/value-renderers/datetime-value';
import { DocEditorValue } from '@docyrus/ui/components/value-renderers/doc-editor-value';
import { DurationValue } from '@docyrus/ui/components/value-renderers/duration-value';
import { EmailValue } from '@docyrus/ui/components/value-renderers/email-value';
import { FileStorageFolderValue } from '@docyrus/ui/components/value-renderers/file-storage-folder-value';
import { FileValue } from '@docyrus/ui/components/value-renderers/file-value';
import { FormulaValue } from '@docyrus/ui/components/value-renderers/formula-value';
import { IconValue } from '@docyrus/ui/components/value-renderers/icon-value';
import { IdentityValue } from '@docyrus/ui/components/value-renderers/identity-value';
import { ImageValue } from '@docyrus/ui/components/value-renderers/image-value';
import { InlineDataValue } from '@docyrus/ui/components/value-renderers/inline-data-value';
import { JsonValue } from '@docyrus/ui/components/value-renderers/json-value';
import { ListValue } from '@docyrus/ui/components/value-renderers/list-value';
import { LocationValue } from '@docyrus/ui/components/value-renderers/location-value';
import { MoneyValue } from '@docyrus/ui/components/value-renderers/money-value';
import { MultiSelectValue } from '@docyrus/ui/components/value-renderers/multi-select-value';
import { NumberValue } from '@docyrus/ui/components/value-renderers/number-value';
import { PercentValue } from '@docyrus/ui/components/value-renderers/percent-value';
import { PhoneValue } from '@docyrus/ui/components/value-renderers/phone-value';
import { RatingValue } from '@docyrus/ui/components/value-renderers/rating-value';
import { RelatedFieldValue } from '@docyrus/ui/components/value-renderers/related-field-value';
import { RelationValue } from '@docyrus/ui/components/value-renderers/relation-value';
import { RichTextValue } from '@docyrus/ui/components/value-renderers/rich-text-value';
import { SelectValue } from '@docyrus/ui/components/value-renderers/select-value';
import { StatusValue } from '@docyrus/ui/components/value-renderers/status-value';
import { SwitchValue } from '@docyrus/ui/components/value-renderers/switch-value';
import { TaskListValue } from '@docyrus/ui/components/value-renderers/task-list-value';
import { TextValue } from '@docyrus/ui/components/value-renderers/text-value';
import { TimeValue } from '@docyrus/ui/components/value-renderers/time-value';
import { TodoValue } from '@docyrus/ui/components/value-renderers/todo-value';
import { UrlValue } from '@docyrus/ui/components/value-renderers/url-value';
import { UserMultiValue } from '@docyrus/ui/components/value-renderers/user-multi-value';
import { UserValue } from '@docyrus/ui/components/value-renderers/user-value';

import {
  APPROVAL_OPTIONS,
  CATEGORY_OPTIONS,
  DEMO_FIELDS,
  DEMO_RECORD,
  DEPARTMENT_OPTIONS,
  LIST_OPTIONS,
  PRIORITY_OPTIONS,
  RELATION_OPTIONS,
  SKILL_OPTIONS,
  STATUS_OPTIONS,
  TAG_OPTIONS,
  USER_OPTIONS
} from '@/data/value-renderers-data';

function SectionHeader({ children }: { children: string }) {
  return (
    <h3 className="border-b pb-1.5 text-sm font-semibold tracking-wide text-muted-foreground uppercase">
      {children}
    </h3>
  );
}

function ValueCard({ label, children }: { label: string; children: ReactNode }) {
  return (
    <div className="flex min-w-0 flex-col gap-1 overflow-hidden rounded-lg border border-border bg-card p-3">
      <span className="text-xs font-medium text-muted-foreground">{label}</span>
      <div className="min-h-6 min-w-0 overflow-hidden">{children}</div>
    </div>
  );
}

export function ValueRenderersDemo() {
  return (
    <div className="w-full space-y-8">
      {/* Text & Content */}
      <section className="space-y-4">
        
        <div className="grid grid-cols-1 gap-3 sm:grid-cols-2 lg:grid-cols-3">
          
          
          
          
          
          
          
          
        </div>
      </section>

      {/* Numbers */}
      <section className="space-y-4">
        
        <div className="grid grid-cols-1 gap-3 sm:grid-cols-2 lg:grid-cols-3">
          
          
          
          
          
          
        </div>
      </section>

      {/* Selection */}
      <section className="space-y-4">
        
        <div className="grid grid-cols-1 gap-3 sm:grid-cols-2 lg:grid-cols-3">
          
          
          
          
          
          
          
          
        </div>
      </section>

      {/* Date & Time */}
      <section className="space-y-4">
        
        <div className="grid grid-cols-1 gap-3 sm:grid-cols-2 lg:grid-cols-3">
          
          
          
          
        </div>
      </section>

      {/* Toggle */}
      <section className="space-y-4">
        
        <div className="grid grid-cols-1 gap-3 sm:grid-cols-2 lg:grid-cols-3">
          
          
          
          
        </div>
      </section>

      {/* Users & Relations */}
      <section className="space-y-4">
        
        <div className="grid grid-cols-1 gap-3 sm:grid-cols-2 lg:grid-cols-3">
          
          
          
        </div>
      </section>

      {/* Contact */}
      <section className="space-y-4">
        
        <div className="grid grid-cols-1 gap-3 sm:grid-cols-2 lg:grid-cols-3">
          
          
          
        </div>
      </section>

      {/* Visual */}
      <section className="space-y-4">
        
        <div className="grid grid-cols-1 gap-3 sm:grid-cols-2 lg:grid-cols-3">
          
          
          
        </div>
      </section>

      {/* Files & Media */}
      <section className="space-y-4">
        
        <div className="grid grid-cols-1 gap-3 sm:grid-cols-2 lg:grid-cols-3">
          
          
          
          
        </div>
      </section>

      {/* Structure */}
      <section className="space-y-4">
        
        <div className="grid grid-cols-1 gap-3 sm:grid-cols-2 lg:grid-cols-3">
          
          
          
          
        </div>
      </section>

      {/* System */}
      <section className="space-y-4">
        
        <div className="grid grid-cols-1 gap-3 sm:grid-cols-2 lg:grid-cols-3">
          
          
          
          
          
        </div>
      </section>
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-value-renderers
```

**Dependencies:**
- [lucide-react](https://www.npmjs.com/package/lucide-react)

## Usage

```tsx
import { DynamicValue } from '@docyrus/ui/components/value-renderers';
import type { IField, DocyrusValueProps } from '@docyrus/ui/components/value-renderers';

const fields: IField[] = [
  { id: '1', name: 'Full Name', slug: 'full_name', type: 'field-text' },
  { id: '2', name: 'Priority', slug: 'priority', type: 'field-select' },
  { id: '3', name: 'Status', slug: 'status', type: 'field-status' },
];

const record = {
  full_name: 'Erhan ERDOGAN',
  priority: 'high',
  status: 'in_progress',
  __status_description: 'Working on API',
};

const enumOptions = [
  { id: 'low', name: 'Low', color: '#22c55e' },
  { id: 'medium', name: 'Medium', color: '#f59e0b' },
  { id: 'high', name: 'High', color: '#ef4444' },
];

function RecordDetail() {
  return (
    <div>
      {fields.map((field) => (
        
      ))}
    </div>
  );
}
```

### Individual Import

You can import individual renderers to reduce bundle size:

```tsx
import { TextValue } from '@docyrus/ui/components/value-renderers/text-value';
import { SelectValue } from '@docyrus/ui/components/value-renderers/select-value';
import { StatusValue } from '@docyrus/ui/components/value-renderers/status-value';
```

## Renderer Types

### Text & Content

| Type | Component | Description |
|------|-----------|-------------|
| `field-text` | `TextValue` | Plain text display |
| `field-textarea` | `TextValue` | Multi-line text (shared renderer) |
| `field-display` | `TextValue` | Display-only text (shared renderer) |
| `field-code` | `TextValue` | Code snippet display (shared renderer) |
| `field-codeEditor` | `CodeValue` | Code block with monospace font |
| `field-htmlEditor` | `RichTextValue` | Rendered HTML content |
| `field-emailEditor` | `RichTextValue` | Email template preview |
| `field-docEditor` | `DocEditorValue` | Document content preview |
| `field-json` | `JsonValue` | JSON display with formatting |
| `field-formula` | `FormulaValue` | Formula expression display |
| `field-relatedField` | `RelatedFieldValue` | Related field value display |

### Numbers

| Type | Component | Description |
|------|-----------|-------------|
| `field-number` | `NumberValue` | Formatted number display |
| `field-money` | `MoneyValue` | Currency-formatted amount |
| `field-percent` | `PercentValue` | Percentage display |
| `field-duration` | `DurationValue` | Duration in HH:MM:SS format |
| `field-rating` | `RatingValue` | Star rating display |
| `field-currency` | `CurrencyCodeValue` | Currency code with symbol |

### Selection

| Type | Component | Description |
|------|-----------|-------------|
| `field-select` | `SelectValue` | Badge with color/icon |
| `field-radioGroup` | `SelectValue` | Badge display (shared renderer) |
| `field-enum` | `SelectValue` | Badge display (shared renderer) |
| `field-multiSelect` | `MultiSelectValue` | Multiple badges |
| `field-tagSelect` | `MultiSelectValue` | Tag badges (shared renderer) |
| `field-status` | `StatusValue` | Status badge with description + follow-up date |
| `field-approvalStatus` | `ApprovalStatusValue` | Approval workflow badge |
| `field-list` | `ListValue` | List item badge |

### Date & Time

| Type | Component | Description |
|------|-----------|-------------|
| `field-date` | `DateValue` | Localized date display |
| `field-dateTime` | `DateTimeValue` | Localized date + time display |
| `field-time` | `TimeValue` | Localized time display |
| `field-dateRange` | `DateRangeValue` | Date range with separator |

### Toggle

| Type | Component | Description |
|------|-----------|-------------|
| `field-checkbox` | `CheckboxValue` | Check/X icon indicator |
| `field-switch` | `SwitchValue` | On/Off text indicator |

### Users & Relations

| Type | Component | Description |
|------|-----------|-------------|
| `field-userSelect` | `UserValue` | User avatar with name |
| `field-userMultiSelect` | `UserMultiValue` | Stacked user avatars |
| `field-relation` | `RelationValue` | Related record link |

### Contact

| Type | Component | Description |
|------|-----------|-------------|
| `field-email` | `EmailValue` | Email link with icon |
| `field-phone` | `PhoneValue` | Phone with country code |
| `field-url` | `UrlValue` | URL link with hostname |

### Visual

| Type | Component | Description |
|------|-----------|-------------|
| `field-color` | `ColorValue` | Color swatch supporting hex and Tailwind color tokens |
| `field-icon` | `IconValue` | Rendered Docyrus icon string such as `huge ai-brain-03` |

### Files & Media

| Type | Component | Description |
|------|-----------|-------------|
| `field-file` | `FileValue` | File name with icon |
| `field-image` | `ImageValue` | Single image thumbnail or gallery thumbnail group |
| `field-avatar` | `AvatarValue` | Avatar thumbnail |

### Structure

| Type | Component | Description |
|------|-----------|-------------|
| `field-taskList` | `TaskListValue` | Checklist progress |
| `field-todo` | `TodoValue` | Todo item count |
| `field-inlineData` | `InlineDataValue` | Inline data row count |
| `field-locationSelect` | `LocationValue` | Address with map pin |

### System

| Type | Component | Description |
|------|-----------|-------------|
| `field-identity` | `IdentityValue` | Identity hash display |
| `field-autonumber` | `IdentityValue` | Auto-number display |
| `field-button` | `ButtonValue` | Action button label |
| `field-conversationChannel` | `ConversationChannelValue` | Channel name |
| `field-fileStorageFolder` | `FileStorageFolderValue` | Folder name |

## API Reference

### DynamicValue

Dispatcher component that renders the correct value renderer based on `field.type`.

Notes:

- `ColorValue` accepts hex values and Tailwind-style tokens such as `emerald-500`.
- `IconValue` expects a Docyrus icon string, for example `huge ai-brain-03`.
- `ImageValue` accepts either a single `{ file_name, signed_url }` object or an array of those objects for gallery-style output.

```tsx

```

### DocyrusValueProps

All value renderer components share this interface:

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `field` | `IField` | — | Field configuration from the data source |
| `value` | `unknown` | — | The field value to display |
| `record` | `Record<string, unknown>` | — | Full record for accessing companion columns |
| `enumOptions` | `EnumOption[]` | `[]` | Options for select-based fields |
| `className` | `string` | — | Additional CSS class |

### IField

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | Unique field identifier |
| `name` | `string` | Display label |
| `slug` | `string` | Record key for accessing the value |
| `type` | `IFieldType` | Field type — determines which renderer is used |
| `defaultValue` | `string \| null` | Default value |
| `validations` | `string[] \| null` | Validation rules |
| `readOnly` | `boolean \| null` | Read-only flag |

### EnumOption

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | Option identifier |
| `name` | `string` | Display label |
| `color` | `string` | Color indicator (hex) |
| `icon` | `string` | Docyrus icon name |
| `slug` | `string` | Slug value |
| `sort_order` | `number` | Display order |

---

# Bulk Update Dialog
URL: /docs/web/docyrus/bulk-update-dialog

Bulk Update Dialog component.

**Demo:**

```tsx
'use client';

import { Button } from '@docyrus/ui/primitives/ui/button';

export function BulkUpdateDialogDemo() {
  return (
    <div className="flex w-full flex-col gap-3 rounded-lg border border-dashed border-border p-6 text-sm text-muted-foreground">
      <p>
        <code>{''}</code> requires an authenticated{' '}
        <code>RestApiClient</code>, an app slug, a data source slug and one or
        more selected record ids — wire it up against your own Docyrus tenant
        to see it in action.
      </p>
      <div>
        
      </div>
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-bulk-update-dialog
```

**Dependencies:**
- [@tanstack/react-query](https://www.npmjs.com/package/@tanstack/react-query)
- [lucide-react](https://www.npmjs.com/package/lucide-react)

## Usage

```tsx
import {
  BulkUpdateDialog
} from "@docyrus/ui/components/bulk-update-dialog";
import type {
  BulkUpdateDialogProps,
  BulkUpdateRecord
} from "@docyrus/ui/components/bulk-update-dialog";

```

## API Reference

| Prop | Type | Default |
|------|------|---------|
| `className` | `string` | — |

## Components

| Component | Description |
|-----------|-------------|
| `BulkUpdateDialog` | Public export |

## Type Exports

| Type | Description |
|------|-------------|
| `BulkUpdateDialogProps` | — |
| `BulkUpdateRecord` | — |

## Type Reference

### BulkUpdateDialogProps

| Field | Type | Description |
|-------|------|-------------|
| `open` | `boolean` | — |
| `onOpenChange` | `(open: boolean) => void` | — |
| `client` | `RestApiClient` | — |
| `appSlug` | `string` | — |
| `dataSourceSlug` | `string` | — |
| `records` | `ReadonlyArray<BulkUpdateRecord>` | — |
| `enableAutomation` | `boolean` | — |
| `enableChangeLogging` | `boolean` | — |
| `onSuccess` | `(data: Array<BulkUpdateRecord>) => void` | — |
| `allowedFieldSlugs` | `ReadonlyArray<string>` | — |
| `dataSourceId` | `string` | — |
| `className` | `string` | — |

### BulkUpdateRecord

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | — |

---

# Contact Channels Panel
URL: /docs/web/docyrus/contact-channels-panel

A Docyrus-backed panel for managing a record's contact channels, the append-only consent ledger and the validation engine.

`ContactChannelsPanel` wires the full **Contact Channels & Consent API** to a single component, laid
out as a **Contact Points & Consent** detail view: a preferred email / phone **summary**, grouped
**Emails** / **Phones** (and messaging / social / web when present) cards showing each channel's
validation status, validating provider and source, per-brand **consent** breakdowns, and a merged
consent + validation **history** trail.

Give it an authenticated `client` and the owning `(appSlug, dataSourceSlug, recordId)` and it lists
the record's channels, lets you add / edit / archive / restore / delete them, promote a primary per
kind, append to the **consent ledger** (scoped by brand → medium → purpose), record a validation
result and run the **validation engine** — all through [`useDocyrusContactChannels`](#hook), which
you can also use standalone to build a custom UI.

**Demo:**

```tsx
'use client';

import { Button } from '@docyrus/ui/primitives/ui/button';

export function ContactChannelsPanelDemo() {
  return (
    <div className="flex w-full flex-col gap-3 rounded-lg border border-dashed border-border p-6 text-sm text-muted-foreground">
      <p>
        <code>{''}</code> requires an authenticated{' '}
        <code>RestApiClient</code> plus the owning{' '}
        <code>(appSlug, dataSourceSlug, recordId)</code>. It talks to the Contact
        Channels &amp; Consent API — listing channels, recording the consent
        ledger (brand · medium · purpose) and running the validation engine — so
        the preview here is informational only. Wire it against your tenant (or
        the playground page on <code>base.contact</code>) to see it live.
      </p>
      <div>
        
      </div>
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-contact-channels-panel
```

**Dependencies:**
- [@docyrus/api-client](https://www.npmjs.com/package/@docyrus/api-client)
- [@tanstack/react-query](https://www.npmjs.com/package/@tanstack/react-query)
- [lucide-react](https://www.npmjs.com/package/lucide-react)

## Usage

```tsx
import { useDocyrusAuth } from '@docyrus/signin';
import { ContactChannelsPanel } from '@docyrus/ui/components/contact-channels-panel';

function ContactChannels({ recordId }: { recordId: string }) {
  const { client } = useDocyrusAuth();

  if (!client) return null;

  return (
    
  );
}
```

### As a side drawer

Pass `open` / `onOpenChange` to render the panel inside an
[`AwesomeDialog`](/docs/web/components/awesome-dialog) — a **right-side sheet** by default. The
typical pairing is the compact [`ContactChannelsField`](/docs/web/components/contact-channels-field)
summary whose **Details** link opens this panel, with the contact / organization name as the
`subtitle`:

```tsx
const [open, setOpen] = useState(false);

<ContactChannelsField value={channels} brands={brands} readOnly onDetailsClick={() => setOpen(true)} />

```

## Endpoints

The panel (via `useDocyrusContactChannels`) targets, under the record base path
`/v1/apps/{appSlug}/data-sources/{dataSourceSlug}/items/{recordId}`:

| Group | Operations |
|-------|-----------|
| Channels | `GET /channels` · `POST /channels` · `PATCH /channels/{id}` · `POST /channels/{id}/make-primary` · `POST /channels/{id}/archive` · `POST /channels/{id}/unarchive` · `DELETE /channels/{id}` |
| Consent | `GET /consent` (record-wide) · `GET /channels/{id}/consent` · `POST /channels/{id}/consent` · `POST /channels/{id}/consent/bulk` · `POST /channels/consent/bulk` |
| Validation | `GET /validations` (record-wide) · `GET /channels/{id}/validations` · `POST /channels/{id}/validations` · `POST /channels/{id}/validate` |
| Brands | `GET /v1/tenant/brands` (for brand-aware consent labels) |

Read endpoints require the `DS.Read.All` scope; write endpoints require `DS.ReadWrite.All`. The
record-wide consent / validation queries avoid a per-channel N+1 in the panel. The consent and
validation ledgers are **append-only**; the channel's `consent` / `validation_status` caches are
maintained server-side by DB triggers and treated as read-only.

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `client` | `ContactChannelsClient` | — | Authenticated REST client (`@docyrus/api-client`'s `RestApiClient` works). |
| `appSlug` | `string` | — | App slug of the owning record. |
| `dataSourceSlug` | `string` | — | Data source slug of the owning record. |
| `recordId` | `string` | — | Owning record id (uuid). |
| `title` | `string` | `'Contact Points & Consent'` | Dialog heading. |
| `subtitle` | `string` | — | Sub-heading under the title (e.g. the contact and organization names). |
| `includeArchived` | `boolean` | `false` | Initial state of the "Show archived" toggle. |
| `enabled` | `boolean` | `true` | Defer queries until ready (e.g. auth resolved). |
| `loadBrands` | `boolean` | `true` | Fetch tenant brands for brand-aware consent. |
| `readOnly` | `boolean` | `false` | Hide every write affordance. |
| `maxHeight` | `string` | `'40rem'` | Max height when rendered inline (the dialog body scrolls). |
| `onChange` | `(channels: ContactChannel[]) => void` | — | Fired with the refreshed channel list after mutations. |
| `className` | `string` | — | Additional class on the root. |
| `open` | `boolean` | — | Dialog open state. Providing `open`/`onOpenChange` renders the panel in an `AwesomeDialog`. |
| `onOpenChange` | `(open: boolean) => void` | — | Dialog open-change handler. |
| `container` | `'sheet' \| 'drawer' \| 'modal'` | `'sheet'` | Dialog container when shown as a dialog. |
| `side` | `'left' \| 'right' \| 'top' \| 'bottom'` | `'right'` | Side for the sheet / drawer container. |
| `size` | `'sm' \| 'default' \| 'lg' \| 'xl' \| 'full'` | `'xl'` | Dialog size preset. |

## Hook

`useDocyrusContactChannels({ client, appSlug, dataSourceSlug, recordId })` returns the data and a
typed mutation for every endpoint:

```tsx
const channels = useDocyrusContactChannels({ client, appSlug, dataSourceSlug, recordId });

// data
channels.channels;          // ContactChannel[]
channels.brands;            // ContactBrand[]
channels.consentHistory;    // ConsentRecord[]  (record-wide)
channels.validationHistory; // ValidationRecord[] (record-wide)
channels.isLoading;
channels.error;

// mutations (all return promises)
await channels.createChannel({ channelKind: 'email', channelType: 'email', value: 'a@b.com' });
await channels.updateChannel(id, { label: 'work' });
await channels.makePrimary(id);
await channels.archiveChannel(id, 'old work email');
await channels.unarchiveChannel(id);
await channels.deleteChannel(id);
await channels.recordConsent(id, { purpose: 'marketing', action: 'opt_in', consentStatus: 'opted_in', consentChannel: 'sms' });
await channels.bulkRecordConsent(id, items);
await channels.bulkRecordRecordConsent(items);  // spans many channels
await channels.recordValidation(id, { method: 'manual', status: 'valid' });
await channels.runValidation(id);               // POST /channels/{id}/validate
```

## Components

| Component | Description |
|-----------|-------------|
| `ContactChannelsPanel` | Full Docyrus-backed panel (inline or as an `AwesomeDialog` drawer). |
| `PanelSummary` | Preferred email / phone summary cards. |
| `ChannelCard` | Per-channel read card with status grid (validation, provider, source) and the action menu. |
| `BrandConsentCard` | One brand's consent breakdown (EMAIL / PHONE mediums + capture metadata). |
| `ConsentHistory` | Merged, collapsible consent + validation audit trail. |
| `ChannelFormDialog` | Add / edit dialog (wraps the backend-agnostic `ChannelEditor`). |
| `ConsentDialog` | Records a single consent action (channel · purpose · action · status · medium · brand). |
| `ValidationDialog` | Records an externally-supplied validation result (`POST /channels/{id}/validations`). |
| `useDocyrusContactChannels` | The data + mutation hook. |

## Type Exports

| Type | Description |
|------|-------------|
| `ContactChannelsPanelProps` | Props for `ContactChannelsPanel`. |
| `ContactChannelsClient` | Minimal `{ get, post, patch, delete }` client contract. |
| `UseDocyrusContactChannelsOptions` / `UseDocyrusContactChannelsResult` | Hook options + return shape. |
| `ConsentEntryWithChannel` | A consent entry plus its target `channelId` (record-wide bulk). |
| `ContactChannel` / `ConsentRecord` / `ValidationRecord` / `ContactBrand` | Re-exported from the field package. |

---

# Docyrus Agent
URL: /docs/web/docyrus/docyrus-agent

AI-powered conversational agent component with chat, action panel, and trigger modes.

{/* @custom-mdx */}

**Demo:**

```tsx
'use client';

import { useState } from 'react';

import {
  DocyrusAgent,
  DocyrusAgentActionPanel,
  DocyrusAgentProvider,
  DocyrusAgentTrigger
} from '@docyrus/ui/components/docyrus-agent';
import {
  Tabs,
  TabsContent,
  TabsList,
  TabsTrigger
} from '@docyrus/ui/primitives/ui/tabs';
import { cn } from '@docyrus/ui/primitives/lib/utils';

import { PropControls } from '@/components/prop-controls';
import { useDemoData } from '@/data/docyrus-agent-data';

export function DocyrusAgentDemo() {
  const { props, controls } = useDemoData();
  const [open, setOpen] = useState(false);

  return (
    <div className="w-full">
      <div className="mb-3 flex justify-end">
        <button
          type="button"
          className="inline-flex items-center gap-1.5 rounded-md border border-border bg-background px-3 py-1.5 text-sm font-medium transition-colors hover:bg-accent"
          onClick={() => setOpen(prev => !prev)}>
          <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M12.22 2h-.44a2 2 0 0 0-2 2v.18a2 2 0 0 1-1 1.73l-.43.25a2 2 0 0 1-2 0l-.15-.08a2 2 0 0 0-2.73.73l-.22.38a2 2 0 0 0 .73 2.73l.15.1a2 2 0 0 1 1 1.72v.51a2 2 0 0 1-1 1.74l-.15.09a2 2 0 0 0-.73 2.73l.22.38a2 2 0 0 0 2.73.73l.15-.08a2 2 0 0 1 2 0l.43.25a2 2 0 0 1 1 1.73V20a2 2 0 0 0 2 2h.44a2 2 0 0 0 2-2v-.18a2 2 0 0 1 1-1.73l.43-.25a2 2 0 0 1 2 0l.15.08a2 2 0 0 0 2.73-.73l.22-.39a2 2 0 0 0-.73-2.73l-.15-.08a2 2 0 0 1-1-1.74v-.5a2 2 0 0 1 1-1.74l.15-.09a2 2 0 0 0 .73-2.73l-.22-.38a2 2 0 0 0-2.73-.73l-.15.08a2 2 0 0 1-2 0l-.43-.25a2 2 0 0 1-1-1.73V4a2 2 0 0 0-2-2z" /><circle cx="12" cy="12" r="3" /></svg>
          Configure
          <svg xmlns="http://www.w3.org/2000/svg" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" className={cn('transition-transform duration-200', open && 'rotate-180')}><path d="m6 9 6 6 6-6" /></svg>
        </button>
      </div>
      <div
        className={cn(
          'grid transition-[grid-template-rows] duration-300 ease-in-out',
          open ? 'grid-rows-[1fr]' : 'grid-rows-[0fr]'
        )}>
        <div className="overflow-hidden">
          <div className="mb-4 grid gap-6 rounded-lg border border-border bg-muted/30 p-4">
            
          </div>
        </div>
      </div>

      
          
          
        

        

        
          </div>
        

        
      
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-docyrus-agent
```

**Dependencies:**
- [ai](https://www.npmjs.com/package/ai)
- [zod](https://www.npmjs.com/package/zod)
- [lucide-react](https://www.npmjs.com/package/lucide-react)

## Usage

### Chat Mode

The default chat interface with message history, streaming responses, reasoning steps, tool calls, and suggestions.

```tsx
import { useChat } from 'ai/react';

import {
  DocyrusAgent
} from '@/components/docyrus/docyrus-agent';
import type {
  AgentProfile,
  AgentMessagePayload
} from '@/components/docyrus/docyrus-agent';

const agent: AgentProfile = {
  name: 'My Assistant',
  description: 'AI-powered helper',
  avatar: { color: '#6366f1', name: 'MA' }
};

function ChatExample() {
  const { messages, status, append, stop } = useChat({
    api: '/api/chat'
  });

  const handleSend = (payload: AgentMessagePayload) => {
    void append({ role: 'user', content: payload.text });
  };

  return (
    
  );
}
```

### Trigger Mode

Compact card with inline input that opens a dialog for the full chat experience.

```tsx
import {
  DocyrusAgentTrigger
} from '@/components/docyrus/docyrus-agent';

```

### Action Panel Mode

Pre-defined actions with parameter forms — useful for structured agent workflows (e.g. "Generate Report", "Send Email").

```tsx
import type { AgentAction, AgentActionPayload } from '@/components/docyrus/docyrus-agent';

const actions: AgentAction[] = [
  {
    id: 'summarize',
    label: 'Summarize Document',
    description: 'Create a concise summary',
    params: [
      { name: 'length', label: 'Length', type: 'select', options: [
        { label: 'Short', value: 'short' },
        { label: 'Medium', value: 'medium' },
        { label: 'Detailed', value: 'detailed' }
      ]}
    ]
  },
  {
    id: 'translate',
    label: 'Translate',
    description: 'Translate text to another language',
    params: [
      { name: 'text', label: 'Text', type: 'textarea', required: true },
      { name: 'language', label: 'Target Language', type: 'text', placeholder: 'e.g. Turkish' }
    ]
  }
];

const handleExecute = (payload: AgentActionPayload) => {
  console.log('Action:', payload.actionId, 'Params:', payload.params);
};

```

### With Sources

Attach contextual data (documents, JSON schemas, files) to the agent conversation.

```tsx
import type { AgentSource } from '@/components/docyrus/docyrus-agent';

const sources: AgentSource[] = [
  { type: 'json-schema', label: 'Contact Schema', value: JSON.stringify(schema) },
  { type: 'pdf', label: 'Q4 Report', value: 'https://...', mimeType: 'application/pdf' }
];

```

## API Reference

### DocyrusAgent

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `mode` | `'chat' \| 'action-panel' \| 'trigger'` | — | **Required.** Component display mode. |
| `agent` | `AgentProfile` | — | **Required.** Agent identity — name, description, avatar, model. |
| `messages` | `Array<UIMessage>` | `[]` | Chat message history (from Vercel AI SDK `useChat`). |
| `chatStatus` | `ChatStatus` | — | Stream status: `'ready'`, `'streaming'`, `'submitted'`, `'error'`. |
| `actions` | `Array<AgentAction>` | `[]` | Pre-defined actions shown in action panel mode. |
| `sources` | `Array<AgentSource>` | `[]` | Contextual data attached to the conversation. |
| `onSendMessage` | `(payload: AgentMessagePayload) => void \| Promise<void>` | — | Called when user sends a message. |
| `onStopGeneration` | `() => void` | — | Called when user stops generation. |
| `onExecuteAction` | `(payload: AgentActionPayload) => void \| Promise<void>` | — | Called when user executes an action. |
| `allowAttachments` | `boolean` | `false` | Show file attachment button in chat input. |
| `acceptFileTypes` | `string` | — | Accepted file MIME types (e.g. `'image/*,.pdf'`). |
| `suggestions` | `Array<string>` | `[]` | Quick-reply suggestions shown in empty state. |
| `emptyState` | `ReactNode` | — | Custom empty state. Defaults to agent name + icon. |
| `showMessageActions` | `boolean` | `true` | Show copy button on assistant messages. |
| `className` | `string` | — | Additional CSS classes. |

### DocyrusAgentTrigger

Extends all `DocyrusAgent` props (except `mode`) with:

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `open` | `boolean` | — | Controlled open state. |
| `onOpenChange` | `(open: boolean) => void` | — | Called when dialog open state changes. |
| `dialogContainer` | `'modal' \| 'sheet' \| 'drawer'` | `'sheet'` | Dialog container type. |
| `dialogSide` | `'left' \| 'right' \| 'top' \| 'bottom'` | `'right'` | Sheet/drawer side. |
| `dialogSize` | `'sm' \| 'default' \| 'lg' \| 'xl' \| 'full'` | `'lg'` | Dialog size. |

## Components

| Component | Description |
|-----------|-------------|
| `DocyrusAgent` | Main component — renders chat or action panel based on `mode` prop. |
| `DocyrusAgentTrigger` | Compact card with inline input → opens dialog with full chat. |
| `DocyrusAgentProvider` | Context provider — use to build custom layouts with agent sub-components. |
| `DocyrusAgentChat` | Full chat layout (header + messages + input). |
| `DocyrusAgentChatMessages` | Message list with reasoning, tool calls, and suggestions. |
| `DocyrusAgentChatInput` | Rich input with file attachments and submit/stop button. |
| `DocyrusAgentHeader` | Agent avatar + name + description header bar. |
| `DocyrusAgentActionPanel` | Action list → parameter form → execution flow. |
| `DocyrusAgentActionList` | Selectable action cards. |
| `DocyrusAgentActionParams` | Dynamic parameter form for selected action. |

## Type Exports

| Type | Description |
|------|-------------|
| `DocyrusAgentProps` | Props for `DocyrusAgent` component. |
| `DocyrusAgentTriggerProps` | Props for `DocyrusAgentTrigger` component. |
| `DocyrusAgentContextValue` | Context value — access via `useDocyrusAgent()` hook. |
| `AgentProfile` | Agent identity (name, description, avatar, model). |
| `AgentMode` | `'chat' \| 'action-panel' \| 'trigger'` |
| `AgentAction` | Action definition with params. |
| `AgentActionParam` | Individual action parameter definition. |
| `AgentActionPayload` | Payload sent when executing an action. |
| `AgentMessagePayload` | Payload sent when sending a message. |
| `AgentSource` | Contextual data source attached to conversation. |
| `AgentSourceType` | `'text' \| 'json' \| 'image' \| 'pdf' \| 'json-schema' \| 'file' \| 'custom'` |
| `ActionPanelView` | `'action-list' \| 'action-params' \| 'executing'` |

## Type Reference

### AgentProfile

| Field | Type | Description |
|-------|------|-------------|
| `name` | `string` | Agent display name. |
| `description` | `string` | Short description shown below name. |
| `avatar` | `{ name?: string; color?: string; icon?: string; image?: string }` | Avatar configuration — color for background, image for custom avatar. |
| `model` | `string` | AI model identifier (informational). |

### AgentAction

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | Unique action identifier. |
| `label` | `string` | Display label for the action card. |
| `description` | `string` | Short description shown below label. |
| `icon` | `ReactNode` | Icon displayed on the action card. |
| `params` | `Array<AgentActionParam>` | Parameters shown in the form when action is selected. |
| `isDefault` | `boolean` | If true, auto-selects this action on mount. |
| `opensChat` | `boolean` | If true, switches to chat mode after execution. |

### AgentActionParam

| Field | Type | Description |
|-------|------|-------------|
| `name` | `string` | Parameter key in the payload. |
| `label` | `string` | Display label for the form field. |
| `type` | `'text' \| 'textarea' \| 'number' \| 'boolean' \| 'select'` | Input type. |
| `required` | `boolean` | Whether the field is required. |
| `defaultValue` | `string \| number \| boolean` | Initial value. |
| `placeholder` | `string` | Placeholder text. |
| `options` | `Array<{ label: string; value: string }>` | Options for `select` type. |
| `description` | `string` | Help text shown below the field. |

### AgentSource

| Field | Type | Description |
|-------|------|-------------|
| `type` | `AgentSourceType` | Source type — determines how the data is interpreted. |
| `label` | `string` | Display label for the source badge. |
| `value` | `string` | Source content or URL. |
| `mimeType` | `string` | MIME type for file-based sources. |
| `meta` | `Record<string, unknown>` | Additional metadata. |

### AgentMessagePayload

| Field | Type | Description |
|-------|------|-------------|
| `text` | `string` | Message text content. |
| `files` | `Array<FileUIPart>` | Attached files (from Vercel AI SDK). |
| `sources` | `Array<AgentSource>` | Context sources included with the message. |
| `actionId` | `string` | Action ID if message originated from an action. |
| `actionParams` | `Record<string, string \| number \| boolean>` | Action parameters if from action execution. |

### AgentActionPayload

| Field | Type | Description |
|-------|------|-------------|
| `actionId` | `string` | Executed action ID. |
| `params` | `Record<string, string \| number \| boolean>` | User-provided parameter values. |
| `sources` | `Array<AgentSource>` | Context sources included with the action. |
| `customPrompt` | `string` | Additional user prompt text. |

---

# Docyrus Data Export Menu
URL: /docs/web/docyrus/docyrus-data-export-menu

Docyrus Data Export Menu component with multiple variants and sizes.

**Demo:**

```tsx
'use client';
// @custom-demo

import { useState } from 'react';

import {
  DocyrusDataExportMenu,
  encodeDocyrusDataExportColumn,
  type DocyrusDataExportFieldOption,
  type DocyrusDataExportSelection
} from '@docyrus/ui/components/docyrus-data-export-menu';

const DEMO_FIELDS: Array<DocyrusDataExportFieldOption> = [
  { slug: 'title', name: 'Title', type: 'field-text' },
  { slug: 'status', name: 'Status', type: 'field-select' },
  { slug: 'owner', name: 'Owner', type: 'field-userSelect' },
  { slug: 'country', name: 'Country', type: 'field-relation' },
  { slug: 'tags', name: 'Tags', type: 'field-tagSelect' },
  { slug: 'amount', name: 'Amount', type: 'field-number' },
  { slug: 'created_at', name: 'Created', type: 'field-dateTime' }
];

const DEFAULT_VISIBLE = DEMO_FIELDS.slice(0, 4).map(field => field.slug);

function describeSelection(selection: DocyrusDataExportSelection): string {
  if (selection.scope === 'visible') return 'visible columns';
  if (selection.scope === 'all') return 'all columns';

  const encoded = selection.columns.map(encodeDocyrusDataExportColumn).join(', ');

  return `custom columns: ${encoded}`;
}

export function DocyrusDataExportMenuDemo() {
  const [isExporting, setIsExporting] = useState(false);
  const [lastExport, setLastExport] = useState<string>('No export yet');

  async function handleExport(selection: DocyrusDataExportSelection) {
    setIsExporting(true);
    setLastExport(`Preparing ${describeSelection(selection)}...`);

    await new Promise(resolve => window.setTimeout(resolve, 800));

    setLastExport(`Exported ${describeSelection(selection)}`);
    setIsExporting(false);
  }

  return (
    <div className="mx-auto flex h-72 w-full max-w-md flex-col items-center justify-center gap-4">
      
      <p className="text-center text-sm text-muted-foreground">{lastExport}</p>
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-docyrus-data-export-menu
```

**Dependencies:**
- [lucide-react](https://www.npmjs.com/package/lucide-react)

## Usage

```tsx
import {
  DocyrusDataExportMenu
} from "@docyrus/ui/components/docyrus-data-export-menu";

<DocyrusDataExportMenu
  onExport={() => {}}
  fields={ReadonlyDocyrusDataExportFieldOption[]}
  visibleSlugs={Readonlystring[]}
/>
```

## API Reference

| Prop | Type | Default |
|------|------|---------|
| `onExport` | `(selection: DocyrusDataExportSelection) => void \| Promise<void>` | — |
| `fields` | `ReadonlyArray<DocyrusDataExportFieldOption>` | — |
| `visibleSlugs` | `ReadonlyArray<string>` | — |
| `isExporting` | `boolean` | `false` |
| `disabled` | `boolean` | `false` |
| `className` | `string` | — |

---

# Docyrus Query Builder
URL: /docs/web/docyrus/docyrus-query-builder

Visual query builder for Docyrus data sources — filters, columns, sorting, calculations, formulas, pivots, and child queries.

**Demo:**

```tsx
'use client';

import { useState } from 'react';

import {
  type EnumOption,
  type IField
} from '@docyrus/ui/components/form-fields';

import { useForm } from '@tanstack/react-form';
import { CalendarClock, FileBarChart, Send } from 'lucide-react';

import { Button } from '@docyrus/ui/primitives/ui/button';
import { Switch } from '@docyrus/ui/primitives/ui/switch';
import {
  Tabs,
  TabsContent,
  TabsList,
  TabsTrigger
} from '@docyrus/ui/primitives/ui/tabs';
import { cn } from '@docyrus/ui/primitives/lib/utils';

import { Field, FieldLabel } from '@docyrus/ui/primitives/ui/field';

import { CheckboxFormField } from '@docyrus/ui/components/form-fields/checkbox-form-field';
import { SelectFormField } from '@docyrus/ui/components/form-fields/select-form-field';
import { TextFormField } from '@docyrus/ui/components/form-fields/text-form-field';
import { TextareaFormField } from '@docyrus/ui/components/form-fields/textarea-form-field';

import {
  DocyrusDataSourceQueryBuilder,
  type IDataSourceReference,
  type ISelectQueryParams
} from '@docyrus/ui/components/docyrus-query-builder';

const tasksFields = [
  {
    id: 't-1', name: 'Title', slug: 'title', type: 'field-text' as const
  },
  {
    id: 't-2', name: 'Status', slug: 'status', type: 'field-status' as const
  },
  {
    id: 't-3', name: 'Owner', slug: 'owner', type: 'field-userSelect' as const
  },
  {
    id: 't-4', name: 'Due Date', slug: 'due_date', type: 'field-date' as const
  },
  {
    id: 't-5', name: 'Priority', slug: 'priority', type: 'field-select' as const
  },
  {
    id: 't-6', name: 'Created At', slug: 'created_at', type: 'field-dateTime' as const
  },
  {
    id: 't-7', name: 'Done', slug: 'is_done', type: 'field-checkbox' as const
  }
];

const dealsFields = [
  {
    id: 'd-1', name: 'Name', slug: 'name', type: 'field-text' as const
  },
  {
    id: 'd-2', name: 'Amount', slug: 'amount', type: 'field-money' as const
  },
  {
    id: 'd-3', name: 'Stage', slug: 'stage', type: 'field-status' as const
  },
  {
    id: 'd-4', name: 'Account', slug: 'account', type: 'field-relation' as const
  },
  {
    id: 'd-5', name: 'Close Date', slug: 'close_date', type: 'field-date' as const
  }
];

const dataSources: IDataSourceReference[] = [
  {
    id: 'crm.tasks',
    name: 'Tasks',
    title: 'Tasks',
    description: 'Things to get done.',
    slug: 'tasks',
    appSlug: 'crm',
    appName: 'CRM',
    fullSlug: 'crm.tasks',
    type: 'standard',
    fields: tasksFields
  },
  {
    id: 'crm.deals',
    name: 'Deals',
    title: 'Deals',
    description: 'Sales pipeline records.',
    slug: 'deals',
    appSlug: 'crm',
    appName: 'CRM',
    fullSlug: 'crm.deals',
    type: 'standard',
    fields: dealsFields
  }
];

const initialQuery: Partial
              <div className="h-[520px] overflow-hidden rounded-lg border">
                
              </div>
            
          )}
        </form.Field>

        <div className="flex items-center justify-between border-t pt-4">
          <span className="text-xs text-muted-foreground">
            Submitted value is shown to the right ↦
          </span>
          
        </div>
      </form>

      <aside className="flex min-h-0 flex-col gap-3">
        <div className="flex flex-col gap-3 rounded-xl border bg-muted/30 p-4">
          <span className="text-xs font-semibold uppercase tracking-wide text-muted-foreground">
            Live form values
          </span>
          <form.Subscribe selector={(state: any) => state.values}>
            {(values: SavedReportFormValues) => (
              <pre className="max-h-[260px] overflow-auto rounded-md border bg-background p-3 text-[11px] leading-relaxed">
                {JSON.stringify(values, null, 2)}
              </pre>
            )}
          </form.Subscribe>
        </div>

        <div className="flex flex-col gap-3 rounded-xl border bg-muted/30 p-4">
          <span className="text-xs font-semibold uppercase tracking-wide text-muted-foreground">
            Last submission
          </span>
          {submitted ? (
            <pre className="max-h-[260px] overflow-auto rounded-md border bg-background p-3 text-[11px] leading-relaxed">
              {JSON.stringify(submitted, null, 2)}
            </pre>
          ) : (
            <p className="text-xs text-muted-foreground">
              Click <span className="font-medium text-foreground">Save report</span> to capture the form payload here.
            </p>
          )}
        </div>
      </aside>
    </div>
  );
}

/* ────────────────────────────────────────────────────────────────────────── */
/* Root                                                                       */
/* ────────────────────────────────────────────────────────────────────────── */

export function DocyrusQueryBuilderDemo() {
  return (
    
        
      

      

      
    
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-docyrus-query-builder
```

**Dependencies:**
- [class-variance-authority](https://www.npmjs.com/package/class-variance-authority)
- [lucide-react](https://www.npmjs.com/package/lucide-react)
- [react-querybuilder](https://www.npmjs.com/package/react-querybuilder)

## Usage

```tsx
'use client';

import { useState } from 'react';

import {
  DocyrusQueryBuilder,
  type ISelectQueryParams
} from '@docyrus/ui/components/docyrus-query-builder';

export function MyQueryBuilder() {
  const [query, setQuery] = useState<Partial<ISelectQueryParams>>({});

  return (
    
  );
}
```

### With a Docyrus API client

Pass an authenticated `RestApiClient` from `@docyrus/api-client` (or any object that implements the `DocyrusQueryBuilderClient` shape) to enable data-source discovery and query previews.

```tsx
import { useDocyrusClient } from '@docyrus/signin';

export function MyAuthedQueryBuilder() {
  const client = useDocyrusClient();
  const [query, setQuery] = useState<Partial<ISelectQueryParams>>({});

  return (
    
  );
}
```

### Without a client (offline / preset data)

Skip the client and supply `dataSources` and `fields` yourself for offline editing and form-driven workflows.

```tsx

```

## EditorAgent integration

Pair `useApplyQuery` with `renderAiAssistant` to let an LLM author Docyrus query specs. The hook owns the controlled `value` and ships an `applyQuery` tool that the agent calls to commit a new query spec — the tool guards against primitives / arrays / null so a malformed payload cannot crash the builder.

```tsx
import { EditorAgent } from '@docyrus/ui/components/editor-agent';
import {
  DocyrusDataSourceQueryBuilder,
  useApplyQuery
} from '@docyrus/ui/components/docyrus-query-builder';

export function QueryBuilderPlayground({ client, user, agentId }) {
  const query = useApplyQuery();
  const [aiOpen, setAiOpen] = useState(false);

  return (
    <DocyrusDataSourceQueryBuilder
      client={client}
      value={query.query}
      onChange={query.setQuery}
      aiAssistantOpen={aiOpen}
      onAiAssistantOpenChange={setAiOpen}
      renderAiAssistant={({ open, onClose, selectedDataSource }) => (
        
      )}
    />
  );
}
```

The matching backend agent must register a tool named `applyQuery` whose input schema mirrors `{ value: object (required), explanation?: string }`.

## Columns — current + parent data sources

The **Columns** section is a single grouped, multi-select tree (no separate "selected columns" pane). In both the current and parent groups, **user** fields (`field-userSelect` / `field-userMultiSelect`) and **enum** fields (`field-select`, `field-radioGroup`, `field-enum`, `field-status`, `field-multiSelect`, `field-tagSelect`) are expandable into a fixed sub-field catalog — user → `id, firstname, lastname, email, photo`; enum → `id, autonumber_id, name, slug, icon, color`. A checked sub-field nests at the correct depth, e.g. `status(id, name)` or `company(owner(firstname, email))` (parent).

The header carries a **Parent Data Sources** switch (its state lives in the hook, so it survives switching to Run & Preview / JSON and back). It pulls fields from the data sources referenced by the current data source's `field-relation` columns and nests a checked field under its relation column, e.g. `company(title, industry)`. It requires a `client`; fields come from `GET /v1/dev/data-sources/:id/fields?expand=parent` (the `parent` expansion returns each parent's full field list keyed by data source id). The same wiring is exposed on the hook as `fetchRelatedFields(['parent', 'child'])` for custom UIs.

## Child Queries

The **Child Queries** panel (enabled via `enableChildQueries`) fetches related records as nested arrays, one per child data source. It uses the `child` expansion of the same endpoint (`GET /v1/dev/data-sources/:id/fields?expand=child`) to discover the data sources whose own `field-relation` points back to the current one:

1. Pick a child data source from the **Add child data source** dropdown — this creates an entry whose **From** and **Using** are auto-filled and read-only (`from` = the child data source as a `{appSlug}_{slug}` reference, e.g. `base_callcenter_call`; `using` = its back-reference relation field slug).
2. Select the columns to return via a multi-select tree-view of the child data source's own fields (with the same user / enum sub-field expansion as the Columns section).
3. Optionally set **Order By** (a field dropdown + asc/desc direction) and **Limit**.

`value.childQueries` is an **array** of `{ alias, from, using, columns, orderBy?, limit? }`. The `alias` (the result key the child rows are returned under) defaults to the child data source slug, and the editor automatically keeps it listed in the parent `value.columns` — the items endpoint **drops the child block unless its alias is also a parent column** (so the emitted request is `?columns=…,alias&childQueries=[{ alias, from, using, … }]`). Removing an entry strips its alias from the columns again. Child data sources load when the panel opens (it flips `relatedExpand.child`); the fetch is de-duped per `(dataSource, expand)` signature.

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `Partial<ISelectQueryParams>` | required | Current query payload |
| `onChange` | `(value: Partial<ISelectQueryParams>) => void` | required | Called whenever the query is edited |
| `client` | `DocyrusQueryBuilderClient \| null` | `null` | Authenticated Docyrus API client. Enables data-source discovery and query previews. |
| `fields` | `IField[]` | `[]` | Available fields for the selected data source. Overridden by the resolved data source when set. |
| `dataSources` | `IDataSourceReference[]` | `[]` | Pre-loaded data sources. Used as a fallback when no client is provided. |
| `locale` | `UiI18nLocale` | `'en'` | UI locale token forwarded to translation-aware sub-components |
| `variant` | `'default' \| 'bordered' \| 'compact'` | `'default'` | Visual variant |
| `size` | `'sm' \| 'default' \| 'lg'` | `'default'` | Component size |
| `className` | `string` | — | Additional CSS class |
| `defaultSection` | `DSQBSection` | `'dataSource'` | Initially active configure section |
| `lockDataSource` | `boolean` | `false` | Lock the builder to the data source supplied via `value` (`dataSourceId` / `dataSourceFullSlug`). Hides the "Select Data Source" step and the clear button so the user can't switch data sources. |
| `enableFormulas` | `boolean` | `true` | Show the formula editor section |
| `enablePivot` | `boolean` | `true` | Show the pivot editor section |
| `enableChildQueries` | `boolean` | `true` | Show the child queries editor section |
| `enableCalculations` | `boolean` | `true` | Show the calculations editor section |
| `aiAssistantOpen` | `boolean` | — | Controlled open state for the AI Assistant drawer. When provided the builder stops managing the open state internally — pair with `onAiAssistantOpenChange`. |
| `onAiAssistantOpenChange` | `(open: boolean) => void` | — | Fired when the AI Assistant toolbar button toggles the drawer. |
| `renderAiAssistant` | `(ctx: IQueryBuilderAiAssistantRenderContext) => ReactNode` | — | Mounts a custom AI Assistant drawer body. When set, the toolbar shows a Bot toggle that opens/closes the drawer; this render fn supplies the body (typically a `<DocyrusAgent>` or `<EditorAgent>` wrapper). The context exposes the live `value` payload and the currently-`selectedDataSource` so the slot can wire the agent's `dataSourceId` without re-deriving it. |
| `aiAssistantWidth` | `number` | `380` | Width in pixels the drawer animates to when open. |

## Components

| Component | Description |
|-----------|-------------|
| `DocyrusDataSourceQueryBuilder` | Top-level component — renders the Configure / Run & Preview / JSON tabs |
| `useApplyQuery` | Hook that owns `value` state and exposes the `applyQuery` client-side tool for `<EditorAgent>` — the tool replaces the builder's query spec with the agent's draft. Refuses primitives / arrays / null so a bad LLM call cannot crash the builder. |
| `DSQBDataSourceSelector` | Data source picker pane |
| `DSQBColumnsEditor` | Column selection + ordering pane |
| `DSQBFiltersEditor` | Filter rule builder pane |
| `DSQBOrderByEditor` | Sort builder pane |
| `DSQBPaginationEditor` | Limit + offset editor |
| `DSQBCalculationsEditor` | Aggregation / calculation rules editor |
| `DSQBFormulaEditor` | Formula composer (block AST) |
| `DSQBChildQueriesEditor` | Child queries editor |
| `DSQBPivotEditor` | Pivot matrix editor |
| `DSQBSettingsEditor` | Query mode + expand toggles |
| `DSQBJsonPreview` | Read-only JSON view of the current query |
| `DSQBRunPreview` | Run results table |
| `DSQBFieldSelector` | Reusable field picker primitive |

## Type Exports

| Type | Description |
|------|-------------|
| `DocyrusQueryBuilderProps` | Top-level component props |
| `DocyrusQueryBuilderClient` | Minimal HTTP client shape consumed by the component |
| `DSQBContextValue` | Shape of the internal context exposed by `useDSQB()` |
| `DSQBPrimaryTab` | `'configure' \| 'preview' \| 'json'` |
| `DSQBSection` | Configure section identifiers (data source, columns, filters, …) |
| `DSQBPreviewState` | Run-preview state (rows, columns, status, error) |
| `ISelectQueryParams` | Full query payload sent to the items endpoint |
| `IQueryFilterGroup` / `IQueryFilterRule` / `QueryFilterType` | Filter tree primitives |
| `ISelectQueryOrderBy` | Sort specifier |
| `ISelectQueryCalculationRule` / `AggregateFunction` / `NumberType` | Calculation rule primitives |
| `IQueryFormula` / `IQueryFormulaBlock` / `BlockKind` | Formula AST primitives |
| `IQueryChildQueryParams` | Child query specifier |
| `ISelectPivot` / `ISelectPivotMatrixQuery` / `DateRangeInterval` | Pivot primitives |
| `IDataSourceReference` | Discovered or supplied data source descriptor |
| `DSQBRelatedFields` / `DSQBParentFieldGroup` / `DSQBChildFieldGroup` | Parent / child field groups returned by `fetchRelatedFields()` |
| `DSQBRelatedExpand` | `{ parent, child }` expansion flags (`relatedExpand` / `setRelatedExpand` on the context) |
| `IField` / `IFieldType` | Docyrus field descriptor + supported field-type tokens |
| `QueryMode` / `ExpandType` | Execution flag tokens |
| `IQueryValidationError` | Validation error shape returned by `validateQuery()` |
| `ParsedColumn` | Parsed column descriptor returned by `parseColumnString()` |
| `UiI18nLocale` | Supported locale tokens |
| `IQueryBuilderAiAssistantRenderContext` | Argument passed to `renderAiAssistant` — `{ open, width, onClose, value, selectedDataSource }`. |
| `IUseApplyQueryResult` | Return shape of `useApplyQuery` — `{ query, setQuery, tools }`. |

## Helpers

| Export | Description |
|--------|-------------|
| `parseColumnString(columns)` | Parse a Docyrus columns string into `ParsedColumn[]` |
| `serializeColumns(columns)` | Inverse of `parseColumnString` |
| `normalizeOrderBy(orderBy)` | Coerce any orderBy value into an array |
| `serializeOrderBy(orderBy)` | Serialize orderBy into the API string form |
| `buildDefaultColumns(fields)` | Build a default columns string from a field list |
| `cleanPayload(query)` | Strip null / empty values from a query payload before sending |
| `getFieldTypeCategory(type)` | Map an `IFieldType` to its filter category |
| `getOperatorsForFieldType(type)` | Get the operator list applicable to a field type |
| `validateQuery(query)` | Run static validation, returning `IQueryValidationError[]` |
| `countFilterRules(filters)` | Count leaves in a filter tree |
| `createBlock(kind)` | Create a default formula block |
| `updateBlockAt(root, path, next)` | Immutably update a formula block at a path |
| `removeBlockAt(root, path)` | Immutably remove a formula block at a path |
| `insertBlockAt(root, path, next)` | Immutably insert a formula block at a path |
| `getBlockLabel(block)` | Render a human-readable label for a formula block |

---

# DSQL Editor
URL: /docs/web/docyrus/dsql-editor

A two-pane workbench for writing and running DSQL (security-scoped SQL) over Docyrus data sources, with a result grid and an embedded AI agent.

**DSQL** (Docyrus Structured Query Language) is a security-scoped SQL surface restricted to the
tenant's data sources. The `DsqlEditor` is a two-pane workbench: a top **DSQL Query** editor (SQL
syntax highlighting, Format + Run) and a bottom **Result** panel that renders the returned rows in a
paginated data grid. It carries the same embedded **AI agent** panel as the JSONata / Handlebars /
HTML Template editors.

Queries reference tables as `appSlug.dataSourceSlug` (e.g. `base.contact`), **not** raw schemas —
the backend rewrites them. Statements are SELECT-only / read-only and run through
`PUT /v1/dsql/query`.

**Demo:**

```tsx
'use client';

import { Button } from '@docyrus/ui/primitives/ui/button';

export function DsqlEditorDemo() {
  return (
    <div className="flex w-full flex-col gap-3 rounded-lg border border-dashed border-border p-6 text-sm text-muted-foreground">
      <p>
        <code>{''}</code> requires an authenticated{' '}
        <code>RestApiClient</code> and executes queries via{' '}
        <code>PUT /v1/dsql/query</code> against your Docyrus tenant — wire it up
        to see it in action. Tables are referenced as{' '}
        <code>app.dataSource</code> (e.g. <code>base.contact</code>). Results
        render in a paginated data grid, and an embedded AI agent can author
        DSQL for you.
      </p>
      <div>
        
      </div>
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-dsql-editor
```

**Dependencies:**
- [sql-formatter](https://www.npmjs.com/package/sql-formatter)
- [@uiw/react-codemirror](https://www.npmjs.com/package/@uiw/react-codemirror)
- [@uiw/codemirror-extensions-langs](https://www.npmjs.com/package/@uiw/codemirror-extensions-langs)
- [lucide-react](https://www.npmjs.com/package/lucide-react)

## Usage

```tsx
import { useState } from 'react';
import { useDocyrusAuth } from '@docyrus/signin';
import { DsqlEditor, useApplyDsql } from '@docyrus/ui/components/dsql-editor';
import { EditorAgentDrawer } from '@/components/editor-agent-drawer';

const DSQL_AGENT_ID = '019ecf41-2c43-7b0e-8d2d-71f218952e14';

function MyDsqlWorkbench() {
  const { client } = useDocyrusAuth();
  const dsql = useApplyDsql('select id, email from base.contact limit 100');
  const [aiOpen, setAiOpen] = useState(false);

  if (!client) return null;

  return (
    <DsqlEditor
      client={client}
      query={dsql.query}
      onQueryChange={dsql.setQuery}
      height="100%"
      aiAssistantOpen={aiOpen}
      onAiAssistantOpenChange={setAiOpen}
      renderAiAssistant={({ open, onClose, query }) => (
        <EditorAgentDrawer
          agentId={DSQL_AGENT_ID}
          open={open}
          onClose={onClose}
          clientTools={dsql.tools}
          editorContext={() => `Current DSQL query:\n${query || '(empty)'}`}
        />
      )}
    />
  );
}
```

For tests or mock data, supply `onRun` instead of `client`:

```tsx
<DsqlEditor onRun={async (query) => ({
  rows: [{ id: 1, email: 'a@b.com' }],
  columns: [{ name: 'id', type: 'number' }, { name: 'email', type: 'string' }],
  rowCount: 1
})} />
```

## Schema-aware autocomplete

Pass a `schema` namespace to get table + column completion: `from base.` completes data-source
names and `base.contact.` completes columns. The `useDsqlSchema` hook fetches it from
`GET /v1/dsql/schema/apps/:appSlug` (returns compact `create table appSlug.dataSourceSlug ( … )`
DDL per data source), parses it, and synthesizes the referenced `tenant.user` / `tenant.enum` system
tables. The same fetched DDL is ideal to feed into the agent's `editorContext` so it authors valid
DSQL.

```tsx
import { DsqlEditor, useApplyDsql, useDsqlSchema } from '@docyrus/ui/components/dsql-editor';

const dsql = useApplyDsql();
const { schema, tables } = useDsqlSchema(client, ['base']);

;
```

Building blocks are exported for custom wiring: `fetchDsqlAppSchema(client, appSlug)`,
`fetchDsqlSchemaNamespace(client, apps)`, `dsqlSchemasToNamespace(tables)`, and
`parseDsqlColumns(ddl)`. You can also pass a hand-built `SQLNamespace` directly to `schema` (or to
the standalone `DsqlCodeEditor` / `sqlExtensions({ schema })`).

## Auto-run when the agent writes a query

`useApplyDsql` takes an `onApply(query)` callback that fires right after the agent's `applyDsqlQuery`
tool writes a (formatted) query into the editor. Combine it with the imperative `ref` to close the
agent panel and run the query in one step:

```tsx
const editorRef = useRef<DsqlEditorHandle>(null);
const dsql = useApplyDsql('', {
  onApply: (query) => {
    setAiOpen(false);             // close the agent panel
    editorRef.current?.run(query); // run immediately (pass query to avoid stale state)
  }
});

;
```

The `DsqlEditorHandle` exposes `run(query?)` (runs the current text, or an explicit query) and
`getQuery()`.

## Row caps

The backend returns a single page — there is no server-side pagination. The effective row limit is
`min(yourLimit ?? 100, maxLimit)`, where `maxLimit` is **1000** for delegated user sessions and
**100** for API / client-credentials tokens. The editor surfaces the cap next to the result count so
a truncated result isn't mistaken for the full set. Add `LIMIT` / filters to narrow large queries.

## API Reference

| Prop | Type | Default |
|------|------|---------|
| `client` | `DsqlEditorClient \| null` | — |
| `onRun` | `(query: string) => Promise<DsqlRunResult>` | — |
| `query` | `string` | — |
| `defaultQuery` | `string` | — |
| `onQueryChange` | `(next: string) => void` | — |
| `onResult` | `(result: DsqlRunResult) => void` | — |
| `onError` | `(message: string) => void` | — |
| `schema` | `SQLNamespace` | — |
| `resultPageSize` | `number` | `25` |
| `height` | `number \| string` | `'100%'` |
| `className` | `string` | — |
| `aiAssistantOpen` | `boolean` | — |
| `onAiAssistantOpenChange` | `(open: boolean) => void` | — |
| `renderAiAssistant` | `(ctx: DsqlAiAssistantRenderProps) => ReactNode` | — |

### DsqlCodeEditor

The standalone SQL editor pane (embed it in form fields or automation-node configs).

| Prop | Type | Default |
|------|------|---------|
| `value` | `string` | — |
| `onChange` | `(value: string) => void` | — |
| `readOnly` | `boolean` | `false` |
| `placeholder` | `string` | — |
| `autoFocus` | `boolean` | `false` |
| `minHeight` | `string` | `'2.5rem'` |
| `maxHeight` | `string` | `'12rem'` |
| `height` | `string` | — |
| `className` | `string` | — |
| `lineNumbers` | `boolean` | `true` |
| `schema` | `SQLNamespace` | — |
| `basicSetup` | `BasicSetupOptions` | — |
| `extensions` | `Extension[]` | — |

## Components

| Component | Description |
|-----------|-------------|
| `DsqlEditor` | Two-pane query + result workbench |
| `DsqlCodeEditor` | Standalone SQL CodeMirror pane |
| `useApplyDsql` | Owns query state + the `applyDsqlQuery` agent client tool |
| `useDsqlSchema` | Fetches + builds the autocomplete `SQLNamespace` for given apps |
| `runDsqlQuery` | `PUT /v1/dsql/query` caller |
| `normalizeDsqlResponse` | Parses the API envelope into a `DsqlRunResult` |
| `extractDsqlError` | Pulls a human message out of a rejected request |
| `fetchDsqlAppSchema` / `fetchDsqlSchemaNamespace` | Fetch DSQL schema from the schema endpoints |
| `dsqlSchemasToNamespace` / `parseDsqlColumns` | Build a `SQLNamespace` from DDL schema text |
| `formatSql` | PostgreSQL-dialect formatter (never throws) |
| `sqlExtensions` | CodeMirror SQL highlight + completion extensions factory |

## Type Exports

| Type | Description |
|------|-------------|
| `DsqlEditorProps` | Props for `DsqlEditor` |
| `DsqlCodeEditorProps` | Props for `DsqlCodeEditor` |
| `DsqlEditorClient` | Minimal `{ put }` client contract |
| `DsqlRunResult` | `{ rows, columns, rowCount, durationMs? }` |
| `DsqlRunState` | Discriminated result-pane state |
| `DsqlColumnMeta` | `{ name, type?, label? }` resolved column |
| `DsqlTableSchema` | Raw schema row from the schema endpoints (`{ appSlug, slug, schema, … }`) |
| `DsqlAiAssistantRenderProps` | Context passed to `renderAiAssistant` |

## Type Reference

### DsqlRunResult

| Field | Type | Description |
|-------|------|-------------|
| `rows` | `Array<Record<string, unknown>>` | Returned rows |
| `columns` | `DsqlColumnMeta[]` | Columns inferred from row keys (SELECT order) |
| `rowCount` | `number` | Row count from the server (`meta.count`) |
| `durationMs` | `number` | Client-measured round-trip duration |

### DsqlColumnMeta

| Field | Type | Description |
|-------|------|-------------|
| `name` | `string` | Column key |
| `type` | `'number' \| 'boolean' \| 'date' \| 'datetime' \| 'uuid' \| 'string'` | Coarse inferred type (drives the cell variant) |
| `label` | `string` | Optional human label (defaults to `name`) |

---

# Email Compose Dialog
URL: /docs/web/docyrus/email-compose-dialog

A batteries-included launcher that opens the Docyrus EmailComposer (wired to the messaging API) inside a dialog, seeded with recipients/subject/body.

**Email Compose Dialog** opens the Docyrus [`EmailComposer`](/docs/web/components/email-composer)
inside a modal, fully wired to the tenant messaging API through
[`useDocyrusEmailComposer`](/docs/web/hooks/use-docyrus-email-composer). Give it a `client` and an
optional `to` / `cc` / `bcc` / `subject` / `body` seed and it handles account loading, sending, and a
success/error toast.

The composer body only mounts while the dialog is open, so each open re-reads the current seeds and
the `GET /v1/messaging/email/accounts` query fires only when visible. On a successful send it calls
`onSent(result)`, shows a toast, and closes.

The body editor's `@` mention autocomplete is active out of the box — the underlying hook loads the
tenant's users from `/v1/users` by default (see the hook's `mentions` option to disable).

It is the component behind the inline **compose** action on the
[`EmailFormField`](/docs/web/components/form-fields) and `EmailValue` renderer — pass a `client` to
those (directly or via `useDocyrusFormView` / `useDocyrusDataGrid` / `useDocyrusDataTable`) and the
action lights up automatically.

**Demo:**

```tsx
'use client';

import { Mail } from 'lucide-react';

import { Button } from '@docyrus/ui/primitives/ui/button';

export function EmailComposeDialogDemo() {
  return (
    <div className="flex w-full flex-col gap-3 rounded-lg border border-dashed border-border p-6 text-sm text-muted-foreground">
      <p>
        <code>{''}</code> requires an authenticated{' '}
        <code>RestApiClient</code> to list email accounts and send. Wire it up
        against your own Docyrus tenant (or the playground) to see it in action.
      </p>
      <div>
        
      </div>
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-email-compose-dialog
```

**Dependencies:**
- [@tanstack/react-query](https://www.npmjs.com/package/@tanstack/react-query)
- [lucide-react](https://www.npmjs.com/package/lucide-react)
- [sonner](https://www.npmjs.com/package/sonner)
- [@docyrus/api-client](https://www.npmjs.com/package/@docyrus/api-client)

## Usage

### Standalone

```tsx
import { useDocyrusAuth } from '@docyrus/signin';
import { EmailComposeDialog } from '@docyrus/ui/components/email-compose-dialog';

function ContactActions({ email }: { email: string }) {
  const { client } = useDocyrusAuth();

  if (!client) return null;

  return (
    } />
```

### Automatic on fields, values, and grids

Pass a `client` to the email form field / value renderer (or let the Docyrus hooks thread it for you)
and the compose action appears with no extra wiring:

```tsx
// Form field + value renderer

// Whole form — useDocyrusFormView threads `client` into every field
const formView = useDocyrusFormView({ client, appSlug, dataSourceSlug, itemId });

// Grids — EmailCell (data grid) and EmailValue (data table) light up automatically
const grid = useDocyrusDataGrid({ client, appSlug, dataSourceSlug });
```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `client` | `RestApiClient` | — | Authenticated Docyrus REST client. **Required.** |
| `to` | `string[]` | — | Pre-filled recipients. |
| `cc` | `string[]` | — | Pre-filled Cc recipients. |
| `bcc` | `string[]` | — | Pre-filled Bcc recipients. |
| `subject` | `string` | — | Pre-filled subject. |
| `body` | `string` | — | Pre-filled body (HTML). |
| `trigger` | `ReactNode` | Ghost mail icon button | Custom element that opens the dialog. |
| `open` | `boolean` | — | Controlled open state. |
| `onOpenChange` | `(open: boolean) => void` | — | Open-state change handler. |
| `title` | `string` | `"Compose email"` | Dialog title. |
| `disabled` | `boolean` | `false` | Disables the default trigger button. |
| `sendAsUser` | `boolean` | — | Send through the tenant account with the user's identity (subject to account override rules). |
| `slashCommands` | `EmailComposerSlashCommand[]` | — | Developer-defined `/` slash commands forwarded to the composer body editor (see the [composer's Slash Commands section](/docs/web/components/email-composer#-slash-commands)). |
| `onSent` | `(result: DocyrusEmailSendResult) => void` | — | Called after a successful send. |
| `className` | `string` | — | Extra class for the default trigger button. |

## Related

- [`EmailComposer`](/docs/web/components/email-composer) — the presentational composer this dialog mounts.
- [`useDocyrusEmailComposer`](/docs/web/hooks/use-docyrus-email-composer) — the hook that wires the composer to the messaging API.
- [`InstantMessageComposeDialog`](/docs/web/docyrus/instant-message-compose-dialog) — the SMS / WhatsApp counterpart for phone fields.

---

# Overview
URL: /docs/web/docyrus

Docyrus business components for building data-driven web applications.

Browse all available Docyrus UI docyrus.

## Available Docyrus Components

| Component | Description |
|-----------|-------------|
| [Docyrus Data Export Menu](/docs/web/docyrus/docyrus-data-export-menu) | Docyrus Data Export Menu component with multiple variants and sizes. |
| [Email Compose Dialog](/docs/web/docyrus/email-compose-dialog) | A batteries-included launcher that opens the Docyrus EmailComposer (wired to the messaging API) inside a dialog, seeded with recipients/subject/body. |
| [Instant Message Compose Dialog](/docs/web/docyrus/instant-message-compose-dialog) | A batteries-included launcher that opens the Docyrus InstantMessageComposer (SMS / WhatsApp) inside a dialog, seeded with recipients and body. |
| [Bulk Update Dialog](/docs/web/docyrus/bulk-update-dialog) | Bulk Update Dialog component. |
| [Contact Channels Panel](/docs/web/docyrus/contact-channels-panel) | A Docyrus-backed panel for managing a record's contact channels, the append-only consent ledger and the validation engine. |
| [Docyrus Agent](/docs/web/docyrus/docyrus-agent) | AI-powered conversational agent component with chat, action panel, and trigger modes. |
| [Docyrus Query Builder](/docs/web/docyrus/docyrus-query-builder) | Visual query builder for Docyrus data sources — filters, columns, sorting, calculations, formulas, pivots, and child queries. |
| [Dsql Editor](/docs/web/docyrus/dsql-editor) | A two-pane workbench for writing and running DSQL (security-scoped SQL) over Docyrus data sources, with a result grid and an embedded AI agent. |
| [Record Pdf Export](/docs/web/docyrus/record-pdf-export) | A three-step wizard (Select a Template → Preview → PDF) that renders a Docyrus data source record to PDF using its saved HTML templates, with an optional editable-template mode. |

---

# Instant Message Compose Dialog
URL: /docs/web/docyrus/instant-message-compose-dialog

A batteries-included launcher that opens the Docyrus InstantMessageComposer (SMS / WhatsApp) inside a dialog, seeded with recipients and body.

**Instant Message Compose Dialog** opens the Docyrus
[`InstantMessageComposer`](/docs/web/components/instant-message-composer) inside a modal, wired to the
tenant SMS / WhatsApp messaging API through
[`useDocyrusInstantMessageComposer`](/docs/web/hooks/use-docyrus-instant-message-composer). Give it a
`client` and an optional `to` / `body` seed and it handles channel switching, account loading,
sending, and a success/error toast.

The composer body only mounts while the dialog is open, so each open re-reads the current seeds and
the account-list queries (`GET /v1/messaging/sms/accounts`, `GET /v1/messaging/whatsapp/accounts`)
fire only when visible. On a successful send it calls `onSent(result)`, shows a toast, and closes.

It is the component behind the inline **send message** action on the `PhoneValue` renderer — pass a
`client` to it (directly or via `useDocyrusFormView` / `useDocyrusDataTable`) and the action lights up
automatically.

**Demo:**

```tsx
'use client';

import { MessageSquare } from 'lucide-react';

import { Button } from '@docyrus/ui/primitives/ui/button';

export function InstantMessageComposeDialogDemo() {
  return (
    <div className="flex w-full flex-col gap-3 rounded-lg border border-dashed border-border p-6 text-sm text-muted-foreground">
      <p>
        <code>{''}</code> requires an authenticated{' '}
        <code>RestApiClient</code> to list SMS / WhatsApp accounts and send. Wire
        it up against your own Docyrus tenant (or the playground) to see it in
        action.
      </p>
      <div>
        
      </div>
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-instant-message-compose-dialog
```

**Dependencies:**
- [@tanstack/react-query](https://www.npmjs.com/package/@tanstack/react-query)
- [lucide-react](https://www.npmjs.com/package/lucide-react)
- [sonner](https://www.npmjs.com/package/sonner)
- [@docyrus/api-client](https://www.npmjs.com/package/@docyrus/api-client)

## Usage

### Standalone

```tsx
import { useDocyrusAuth } from '@docyrus/signin';
import { InstantMessageComposeDialog } from '@docyrus/ui/components/instant-message-compose-dialog';

function ContactActions({ phone }: { phone: string }) {
  const { client } = useDocyrusAuth();

  if (!client) return null;

  return (
    } />
```

### Automatic on phone values and tables

Pass a `client` to the phone value renderer (or let the Docyrus hooks thread it for you) and the send
action appears with no extra wiring:

```tsx
// Value renderer

// Whole form / record detail — useDocyrusFormView threads `client` into every field
const formView = useDocyrusFormView({ client, appSlug, dataSourceSlug, itemId });

// Data table — cells render through the value renderers, so PhoneValue lights up
const table = useDocyrusDataTable({ client, appSlug, dataSourceSlug });
```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `client` | `RestApiClient` | — | Authenticated Docyrus REST client. **Required.** |
| `to` | `string[]` | — | Pre-filled recipient phone numbers (E.164-style). |
| `body` | `string` | — | Pre-filled message body. |
| `channel` | `'sms' \| 'whatsapp'` | `'sms'` | Initial channel. |
| `availableChannels` | `ReadonlyArray<'sms' \| 'whatsapp'>` | `['sms', 'whatsapp']` | Channels offered in the switcher. |
| `trigger` | `ReactNode` | Ghost message icon button | Custom element that opens the dialog. |
| `open` | `boolean` | — | Controlled open state. |
| `onOpenChange` | `(open: boolean) => void` | — | Open-state change handler. |
| `title` | `string` | `"Send message"` | Dialog title. |
| `disabled` | `boolean` | `false` | Disables the default trigger button. |
| `onSent` | `(result: DocyrusInstantMessageSendResult) => void` | — | Called after a successful send. |
| `className` | `string` | — | Extra class for the default trigger button. |

## Related

- [`InstantMessageComposer`](/docs/web/components/instant-message-composer) — the presentational composer this dialog mounts.
- [`useDocyrusInstantMessageComposer`](/docs/web/hooks/use-docyrus-instant-message-composer) — the hook that wires the composer to the SMS / WhatsApp API.
- [`EmailComposeDialog`](/docs/web/docyrus/email-compose-dialog) — the email counterpart for email fields.

---

# Record PDF Export
URL: /docs/web/docyrus/record-pdf-export

A three-step wizard (Select a Template → Preview → PDF) that renders a Docyrus data source record to PDF using its saved HTML templates, with an optional editable-template mode.

**Record PDF Export** turns a single Docyrus data source record into a PDF through a guided
three-step wizard:

1. **Select a Template** — lists the data source's saved HTML/PDF templates (`tenant_html_template`).
2. **Preview** — renders the chosen template compiled against the record, using the
   [`HtmlTemplateEditor`](/docs/web/components/html-template-editor) in **preview-only** mode.
3. **PDF** — generates the final PDF server-side and shows it in an inline viewer with a download button.
4. **Email** *(optional, when `sendEmail` is set)* — mounts an email composer
   ([`useDocyrusEmailComposer`](/docs/web/hooks/use-docyrus-email-composer)) with the generated PDF
   pre-attached, so the user can send the record straight from the wizard.

The headless [`useDocyrusRecordPdfExport`](#hook--usedocyrusrecordpdfexport) hook owns all data
fetching, step state, and PDF generation. `DocyrusRecordPdfExportWizard` is the batteries-included
UI built on top of it. The hook accepts a **`dataSourceId`** and **`recordId`** — the app / data
source slugs needed by the render endpoints are resolved automatically (or supplied explicitly).

**Demo:**

```tsx
'use client';

import { FileTextIcon } from 'lucide-react';

import { Step, Stepper } from '@docyrus/ui/components/stepper';
import { Button } from '@docyrus/ui/primitives/ui/button';

export function RecordPdfExportDemo() {
  return (
    <div className="flex w-full flex-col gap-4 rounded-lg border border-dashed border-border p-6 text-sm text-muted-foreground">
      

      <p>
        <code>{''}</code> requires an authenticated{' '}
        <code>RestApiClient</code> plus a <code>dataSourceId</code> and{' '}
        <code>recordId</code>. It lists the data source&apos;s saved HTML
        templates, previews the selected template compiled against the record
        (via the <code>HtmlTemplateEditor</code> in preview-only mode), and
        renders a server-side PDF — wire it to your tenant (or the playground)
        to see it live.
      </p>

      <div className="flex items-center gap-2">
        
      </div>
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-record-pdf-export
```

**Dependencies:**
- [@tanstack/react-query](https://www.npmjs.com/package/@tanstack/react-query)
- [lucide-react](https://www.npmjs.com/package/lucide-react)
- [@docyrus/api-client](https://www.npmjs.com/package/@docyrus/api-client)

## Usage

### Wizard inside a dialog

```tsx
import { useState } from 'react';

import { useDocyrusAuth } from '@docyrus/signin';
import { DocyrusRecordPdfExportWizard } from '@docyrus/ui/components/record-pdf-export';
import {
  Dialog,
  DialogContent,
  DialogHeader,
  DialogTitle,
  DialogTrigger
} from '@docyrus/ui/primitives/ui/dialog';
import { Button } from '@docyrus/ui/primitives/ui/button';

function ExportRecordButton({ dataSourceId, recordId }: { dataSourceId: string; recordId: string }) {
  const { client } = useDocyrusAuth();
  const [open, setOpen] = useState(false);

  if (!client) return null;

  return (
    
      
      
        
        
    
  );
}
```

### Editable-template mode

Pass `templateEditable` to let the user tweak the rendered document before exporting. The preview
step then exposes the **Code**, **Data** (read-only reference), and **Preview** tabs — the Code tab
holds the server-compiled document HTML for this record. When it is edited, the PDF step renders the
edited HTML through the custom-body endpoint instead of the saved template.

```tsx

```

### Email step

Pass `sendEmail` to append an **Email** step. After the PDF is generated, the wizard mounts an email
composer (via [`useDocyrusEmailComposer`](/docs/web/hooks/use-docyrus-email-composer)) with the
rendered PDF pre-attached (sent through its storage path) and the user's email accounts loaded into
the From selector. Sending requires the `Messaging.Email.Send` OAuth scope.

```tsx

```

### Headless — drive your own UI

```tsx
import { HtmlTemplateEditor } from '@docyrus/ui/components/html-template-editor';
import { useDocyrusRecordPdfExport } from '@docyrus/ui/components/record-pdf-export';

function CustomExport({ client, dataSourceId, recordId }) {
  const {
    step, goNext, goBack, canGoNext,
    templates, selectedTemplateId, setSelectedTemplateId,
    previewEditorProps,
    pdfUrl, isGeneratingPdf
  } = useDocyrusRecordPdfExport({ client, dataSourceId, recordId });

  // Step 1 — render `templates` and call `setSelectedTemplateId(id)`.
  // Step 2 — 
  // Step 3 — <iframe src={pdfUrl} /> (auto-generated on entering the step).
}
```

## How it works

| Step | Endpoint(s) | Notes |
|------|-------------|-------|
| Resolve slugs | `GET /v1/dev/data-sources/:dataSourceId` | Maps `dataSourceId` → `app_slug` + `slug`. Skipped when `appSlug` + `dataSourceSlug` are supplied. |
| List templates | `GET /v1/dev/html-templates?tenantDataSourceId=:dataSourceId` | Drives the "Select a Template" step. The default template (`is_default`) is auto-selected. |
| Compiled preview | `GET /v1/apps/:appSlug/data-sources/:dataSourceSlug/items/:recordId/templates/:templateId/html` | Returns the **server-compiled** document `body` (+ `styles`) for this record — the same `templateCompiler` the PDF uses. This is the preview source, so the preview matches the PDF exactly. |
| Record data (editable only) | `GET /v1/apps/:appSlug/data-sources/:dataSourceSlug/items/:recordId?columns=*` | Read-only reference shown in the editable-mode Data tab. |
| Render PDF (saved) | `GET /v1/apps/:appSlug/data-sources/:dataSourceSlug/items/:recordId/templates/:templateId/pdf` | Default path. The server compiles the saved template against the record. |
| Render PDF (edited) | `PUT /v1/apps/:appSlug/data-sources/:dataSourceSlug/items/:recordId/renderPdfTemplate/:templateId` | Used in `templateEditable` mode when the compiled HTML was edited. Sends the edited HTML as a `multipart/form-data` `body` file (`data={}` so the server loads the record for header/footer). |

## Preview uses the HTML Template Editor

The preview step mounts [`HtmlTemplateEditor`](/docs/web/components/html-template-editor) with the
**server-compiled** document HTML as `value`, then restricts the visible tabs. Compiling on the
server (rather than client-compiling the raw template against the raw record) is what makes the
preview faithful — the record's fields are mapped/expanded exactly as they are for the PDF. Three
editor props power this:

| Prop | Type | Purpose |
|------|------|---------|
| `visibleTabs` | `HtmlTemplateEditorTab[]` | Restricts which tabs render (and their order). The wizard passes `['preview']` (read-only) or `['code', 'data', 'preview']` (editable). The tab strip auto-hides when a single tab remains, and the Visual/Plate tab is intentionally omitted (its round-trip is lossy for complex nested-block table templates). |
| `dataReadOnly` | `boolean` | Makes only the **Data** tab read-only while keeping the Code editor editable — the record data is a reference, not editable. |
| `previewStyles` | `string` | Extra CSS injected into the Preview iframe (the template's `styles`), without baking a `<style>` block into the Plate document tree. |

In **editable** mode the user tweaks the *compiled* document HTML (the final output for this record)
in the Code tab — the custom-body PDF endpoint takes final HTML as-is, so this is the only
round-trip-faithful editing surface the API supports.

## Hook — `useDocyrusRecordPdfExport`

```tsx
const wizard = useDocyrusRecordPdfExport(options);
```

### Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `client` | `RestApiClient` | — | Authenticated REST client. |
| `dataSourceId` | `string` | — | `tenant_data_source.id` of the record's data source. |
| `recordId` | `string` | — | `tenant_data_source_item.id` of the record to render. |
| `appSlug` | `string` | — | App slug. When omitted, resolved from `dataSourceId`. |
| `dataSourceSlug` | `string` | — | Data source slug. When omitted, resolved from `dataSourceId`. |
| `enabled` | `boolean` | `true` | Toggles all network activity. |
| `templateEditable` | `boolean` | `false` | Exposes template + read-only Data tabs in the preview; edited bodies render via the custom-body endpoint. |
| `sendEmail` | `boolean` | `false` | Appends an **Email** step that mounts a composer with the generated PDF pre-attached. Sending needs the `Messaging.Email.Send` scope. |
| `initialTemplateId` | `string` | — | Pre-select a template by id. |
| `autoSelectDefaultTemplate` | `boolean` | `true` | Auto-select the default (or first) template once the list resolves. |
| `resolveDataSourceEndpoint` | `string` | `/v1/dev/data-sources/{id}` | Endpoint override for slug resolution. |
| `listTemplatesEndpoint` | `string` | `/v1/dev/html-templates` | Endpoint override for the templates list. |
| `templateDetailEndpoint` | `string` | `/v1/dev/html-templates/{templateId}` | Endpoint override for a template's body. |

### Returns

| Field | Type | Description |
|-------|------|-------------|
| `steps` | `RecordPdfExportStep[]` | Ordered steps for this wizard — includes `'email'` when `sendEmail` is set. |
| `step` / `setStep` / `stepIndex` | `RecordPdfExportStep` … | Current step (`'select' \| 'preview' \| 'pdf' \| 'email'`) and controls. |
| `goNext` / `goBack` / `canGoNext` / `canGoBack` / `isLastStep` | — | Step navigation. |
| `appSlug` / `dataSourceSlug` / `isResolving` / `resolveError` | — | Resolved slugs + resolution state. |
| `templates` / `isLoadingTemplates` / `templatesError` / `refetchTemplates` | — | Templates list state. |
| `selectedTemplateId` / `setSelectedTemplateId` / `selectedTemplate` | — | Selected template. |
| `templateDetail` / `isLoadingTemplateDetail` / `templateDetailError` | `DocyrusHtmlTemplateDetail` … | Selected template's body / styles. |
| `record` / `recordJson` / `isLoadingRecord` / `recordError` | — | The target record (object + pretty JSON string). |
| `templateEditable` / `editedHtml` / `setEditedHtml` / `isDirty` / `resetEdits` | — | Editable body state. |
| `generatePdf` / `isGeneratingPdf` / `pdfResult` / `pdfUrl` / `pdfError` | — | PDF generation. Auto-fires on entering the PDF step. |
| `previewEditorProps` | `RecordPdfExportPreviewEditorProps` | Ready to spread onto `<HtmlTemplateEditor>` for the preview step. |
| `reset` | `() => void` | Reset the wizard back to the first step. |

## API Reference — `DocyrusRecordPdfExportWizard`

Extends every [hook option](#options) plus:

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `className` | `string` | — | Wrapper class. |
| `bodyHeight` | `string` | `'70vh'` | Height of the wizard body region. |
| `onClose` | `() => void` | — | Fired by the footer **Done** button on the PDF step. |
| `hideClose` | `boolean` | `false` | Hide the footer **Done** button. |

## Type Exports

| Type | Description |
|------|-------------|
| `UseDocyrusRecordPdfExportOptions` | Options for the hook. |
| `UseDocyrusRecordPdfExportResult` | Return shape of the hook. |
| `RecordPdfExportPreviewEditorProps` | Props spread onto `HtmlTemplateEditor` for the preview. |
| `DocyrusRecordPdfExportWizardProps` | Props for the wizard component. |
| `DocyrusHtmlTemplateSummary` | Template list row. |
| `DocyrusHtmlTemplateDetail` | Template detail row (adds `body` / `styles`). |
| `DocyrusRecordPdfResult` | The upstream html-to-pdf result (`url`, `filename`, …). |
| `RecordPdfExportStep` | `'select' \| 'preview' \| 'pdf'`. |

---

# Distributions
URL: /docs/web/guide/distributions

Component distributions and core libraries that power Docyrus UI web components.

Docyrus UI is built on top of the shadcn ecosystem and depends on several major open-source libraries.

## Component Distributions

## UI Primitives

| Library | Description | Used In |
|---------|-------------|---------|
| [Radix UI](https://www.radix-ui.com) | Unstyled, accessible UI primitives for dialogs, popovers, tooltips, dropdowns, and more. | Primitives, Components |
| [Ariakit](https://ariakit.org) | Accessible components with WAI-ARIA patterns. | Select, Combobox |
| [Base UI](https://base-ui.com) | Unstyled React components from the MUI team. | Components |

## Rich Text & Code Editing

| Library | Description | Used In |
|---------|-------------|---------|
| [Plate.js](https://platejs.org) | Plugin-based rich text editor with AI, comments, mentions, tables, and 30+ plugins. | Editor |
| [CodeMirror](https://codemirror.net) | Extensible code editor with syntax highlighting and language support. | Code Editor |
| [Shiki](https://shiki.style) | Syntax highlighter powered by TextMate grammars with dual-theme support. | Code Blocks |

## Data & Tables

| Library | Description | Used In |
|---------|-------------|---------|
| [TanStack Table](https://tanstack.com/table) | Headless table library with sorting, filtering, grouping, and virtualization. | Data Grid |
| [TanStack Virtual](https://tanstack.com/virtual) | Headless virtualization for large lists and grids. | Data Grid |
| [Recharts](https://recharts.org) | Composable charting library built on D3. | Charts |
| [ExcelJS](https://github.com/exceljs/exceljs) | Excel file generation and parsing for data export. | Data Grid, Pivot Grid |
| [JSONata](https://jsonata.org) | Lightweight query and transformation language for JSON data. | Pivot Grid, Pricing Engine |

## Forms & Input

| Library | Description | Used In |
|---------|-------------|---------|
| [React Hook Form](https://react-hook-form.com) | Performant form library with `@hookform/resolvers` for schema validation. | Form Fields |
| [Zod](https://zod.dev) | TypeScript-first schema validation library. | Form Validation |
| [React Day Picker](https://daypicker.dev) | Flexible date picker component. | Day Picker, Date Time Picker |
| [date-fns](https://date-fns.org) | Modern date utility library for formatting, parsing, and manipulation. | Calendar, Scheduler |
| [cmdk](https://cmdk.paco.me) | Fast, composable command palette component. | Command |
| [React Query Builder](https://react-querybuilder.js.org) | Composable query builder for constructing complex filter expressions. | Query Builder |
| [input-otp](https://input-otp.rodz.dev) | One-time password input component. | OTP Input |

## Drag & Drop

| Library | Description | Used In |
|---------|-------------|---------|
| [dnd kit](https://dndkit.com) | Modern drag and drop toolkit for React with sortable support. | Kanban, Sortable Lists |
| [React DnD](https://react-dnd.github.io/react-dnd) | Drag and drop for complex interactions with HTML5 backend. | Gantt, Resource Scheduler |

## Animation & Motion

| Library | Description | Used In |
|---------|-------------|---------|
| [Motion](https://motion.dev) | Production-ready animation library for enter/exit transitions and layout animations. | Components |
| [GSAP](https://gsap.com) | High-performance animation platform for complex sequenced animations. | Components |

## Maps & Location

| Library | Description | Used In |
|---------|-------------|---------|
| [Leaflet](https://leafletjs.com) | Interactive map library with marker clustering, drawing tools, and fullscreen support. | Map |
| [React Leaflet](https://react-leaflet.js.org) | React components for Leaflet maps. | Map |

## Media & Content

| Library | Description | Used In |
|---------|-------------|---------|
| [React Player](https://github.com/cookpete/react-player) | Video and audio player supporting multiple sources. | Video Player |
| [Embla Carousel](https://www.embla-carousel.com) | Lightweight carousel with touch support and extensible plugins. | Carousel |
| [React Email Editor](https://github.com/unlayer/react-email-editor) | Drag and drop email template builder. | Email Composer |

## Layout & UI

| Library | Description | Used In |
|---------|-------------|---------|
| [Vaul](https://vaul.emilkowal.ski) | Drawer component with smooth touch interactions. | Drawer |
| [Sonner](https://sonner.emilkowal.ski) | Opinionated toast notification library. | Toast |
| [Resizable Panels](https://github.com/bvaughn/react-resizable-panels) | Resizable panel layout system. | Resizable |

## AI & LLM

| Library | Description | Used In |
|---------|-------------|---------|
| [Vercel AI SDK](https://sdk.vercel.ai) | React hooks and utilities for building AI-powered interfaces. | Docyrus Agent, Editor AI |

---

# Examples & Recipes
URL: /docs/web/guide/examples

Practical multi-component patterns and recipes for common UI scenarios.

Real-world patterns that combine multiple Docyrus UI components. Copy, adapt, and use in your projects.

## CRUD Table with Filters

A common pattern: a data grid with toolbar filters, search, and create/delete dialogs.

```tsx
import { useState } from 'react';

import { DataGrid } from '@/components/docyrus/data-grid';
import { DataTableFilter } from '@/components/docyrus/data-table-filter';
import { SearchInput } from '@/components/docyrus/search-input';
import { DeleteConfirmDialog } from '@/components/docyrus/delete-confirm-dialog';
import { CreateRecordDialog } from '@/components/docyrus/create-record-dialog';
import { Button } from '@/components/ui/button';

export function ContactsPage() {
  const [search, setSearch] = useState('');
  const [filters, setFilters] = useState([]);
  const [deleteId, setDeleteId] = useState<string | null>(null);
  const [showCreate, setShowCreate] = useState(false);

  return (
    <div className="flex flex-col gap-4">
      {/* Toolbar */}
      <div className="flex items-center gap-3">
        
        
        
      </div>

      {/* Grid */}
      
    </form>
  );
}
```

## Dashboard Layout

Combine stats, charts, and activity panels into a dashboard view:

```tsx
import { AwesomeStats } from '@/components/docyrus/awesome-stats';
import { RecordActivityPanel } from '@/components/docyrus/record-activity-panel';
import { NotificationsPanel } from '@/components/docyrus/notifications-panel';
import { Calendar } from '@/components/docyrus/calendar';

export function DashboardPage() {
  return (
    <div className="flex flex-col gap-6">
      {/* Stats row */}
      

      {/* Main content + sidebar */}
      <div className="grid grid-cols-1 gap-6 lg:grid-cols-3">
        <div className="lg:col-span-2">
          
        </div>

        <div className="flex flex-col gap-4">
          
          
        </div>
      </div>
    </div>
  );
}
```

## File Attachment with Preview

Handle file uploads with preview and attachment management:

```tsx
import { useState } from 'react';

import { FileAttachmentPanel } from '@/components/docyrus/file-attachment-panel';
import { ImageEditor } from '@/components/docyrus/image-editor';
import { AwesomeDialog } from '@/components/docyrus/awesome-dialog';

export function DocumentManager() {
  const [files, setFiles] = useState
    </>
  );
}
```

## Kanban with Detail Panel

Project board with click-to-expand detail view:

```tsx
import { useState } from 'react';

import { Kanban } from '@/components/docyrus/kanban';
import { AwesomeCard } from '@/components/docyrus/awesome-card';
import { CommentsPanel } from '@/components/docyrus/comments-panel';
import { EditableValue } from '@/components/docyrus/editable-value';

export function ProjectBoard() {
  const [selectedTask, setSelectedTask] = useState
      )}
    </div>
  );
}
```

## Record Detail Page

Editable record with activity timeline, sharing, and delete confirmation:

```tsx
import { EditableRecordDetail } from '@/components/docyrus/editable-record-detail';
import { RecordActivityPanel } from '@/components/docyrus/record-activity-panel';
import { RecordSharing } from '@/components/docyrus/record-sharing';
import { RecordDeleteConfirmDialog } from '@/components/docyrus/record-delete-confirm-dialog';
import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs';

export function RecordPage({ recordId }: { recordId: string }) {
  return (
    <div className="grid grid-cols-1 gap-6 lg:grid-cols-3">
      <div className="lg:col-span-2">
        
      </div>

      <div>
        
            
          
          
          
        
      </div>
    </div>
  );
}
```

## Related

- [Installation](/docs/web/guide/installation) — Set up Docyrus UI in your project
- [Components](/docs/web/components) — Browse all web components
- [API Reference](/docs/guide/api-reference) — REST client documentation

---

# Internationalization (i18n)
URL: /docs/web/guide/i18n

How to add multi-language support to Docyrus UI components.

## Overview

Docyrus UI components have built-in i18n support through a **provider-agnostic** translation system. Components display English by default and automatically switch to the active language when a translation provider is present.

No dependency on any specific i18n library — works with `@docyrus/i18n`, `react-i18next`, `next-intl`, or any custom solution.

## Quick Start

### 1. Wrap your app with `UiTranslationProvider`

```tsx
import { UiTranslationProvider } from '@docyrus/ui/hooks/use-ui-translation';

function App() {
  return (
    
  );
}
```

The `t` prop accepts any function with the signature:

```ts
(key: string, fallback?: string | Record<string, string | number>) => string
```

### 2. Without a provider

Components render in **English** with no setup required:

```tsx
// No provider needed — English fallback works automatically

```

## Integration Examples

### @docyrus/i18n

```tsx
import { useDocyrusI18n } from '@docyrus/i18n';
import { UiTranslationProvider } from '@docyrus/ui/hooks/use-ui-translation';

function AppShell({ children }: { children: React.ReactNode }) {
  const { t } = useDocyrusI18n();

  return (
    
  );
}
```

### react-i18next

```tsx
import { useTranslation } from 'react-i18next';
import { UiTranslationProvider } from '@docyrus/ui/hooks/use-ui-translation';

function AppShell({ children }: { children: React.ReactNode }) {
  const { t } = useTranslation();

  return (
    
  );
}
```

### next-intl

```tsx
import { useTranslations } from 'next-intl';
import { UiTranslationProvider } from '@docyrus/ui/hooks/use-ui-translation';

function AppShell({ children }: { children: React.ReactNode }) {
  const t = useTranslations();

  return (
    
  );
}
```

## Translation Keys

All component translation keys follow the `ui.<group>.<camelCaseKey>` convention:

| Group | Prefix | Example Key | English Default |
|-------|--------|-------------|-----------------|
| Common | `ui.common` | `ui.common.search` | Search |
| Calendar | `ui.calendar` | `ui.calendar.addEvent` | Add Event |
| Data Grid | `ui.dataGrid` | `ui.dataGrid.filter` | Filter |
| Form Fields | `ui.formField` | `ui.formField.selectPlaceholder` | Select... |
| Pricing Engine | `ui.pricing` | `ui.pricing.subtotal` | Subtotal |
| Mega Select | `ui.megaSelect` | `ui.megaSelect.search` | Search |
| Team Chat | `ui.teamChat` | `ui.teamChat.writePost` | Write a post... |
| Contact Activity | `ui.contactActivity` | `ui.contactActivity.all` | All |
| Log Activity | `ui.logActivity` | `ui.logActivity.taskSubject` | Task subject |
| Email Composer | `ui.emailComposer` | `ui.emailComposer.send` | Send |
| Record Sharing | `ui.recordSharing` | `ui.recordSharing.share` | Share |
| Query Builder | `ui.queryBuilder` | `ui.queryBuilder.columns` | Columns |
| Data Grid View | `ui.dataGridView` | `ui.dataGridView.selectView` | Select view |
| Time Slot | `ui.timeSlot` | `ui.timeSlot.available` | Available |
| Scheduler | `ui.scheduler` | `ui.scheduler.today` | Today |
| Agent | `ui.agent` | `ui.agent.sendMessage` | Send message |
| Tree View | `ui.treeView` | `ui.treeView.expandAll` | Expand All |
| Place Autocomplete | `ui.placeAutocomplete` | `ui.placeAutocomplete.searchPlaces` | Search places... |

## How It Works

Components use the `useUiTranslation` hook internally:

```tsx
import { useUiTranslation } from '@/hooks/use-ui-translation';

function MyComponent() {
  const { t } = useUiTranslation();

  return (
    <button>{t('ui.calendar.addEvent', 'Add Event')}</button>
  );
}
```

- **First argument:** Translation key
- **Second argument:** English fallback text (shown when key has no translation or no provider)

The hook reads from `UiTranslationContext`:
- If `UiTranslationProvider` is in the tree → uses the provided `t` function
- If no provider → returns the English fallback string

## Customizing Translations

To override a specific component's text, add the corresponding key to your i18n translation dictionary.

For example, to change the Calendar's "Add Event" button to "New Appointment" in Turkish:

```json
{
  "ui.calendar.addEvent": "Yeni Randevu"
}
```

Any key not present in your dictionary will fall back to the English default embedded in the component.

## Date Formatting

Docyrus UI components **do not format dates** — they display raw values by default. To show formatted dates (e.g. `DD/MM/YYYY` or `MM/DD/YYYY`), wrap your app with `DateFormatProvider`.

### Setup

```tsx
import { DateFormatProvider } from '@docyrus/ui/hooks/use-date-format';
import { format } from 'date-fns';

function App() {
  return (
    
  );
}
```

Works with any date library — `date-fns`, `dayjs`, `Intl.DateTimeFormat`, or plain functions.

### Per-component override

Some components accept `formatDate` / `formatDateTime` props directly for per-instance customization:

```tsx
<DataGrid
  table={table}
  formatDate={(v) => dayjs(v).format('MM/DD/YYYY')}
  formatDateTime={(v) => dayjs(v).format('MM/DD/YYYY h:mm A')}
/>
```

Per-component props take precedence over the provider.

### Without a provider

Components display **raw values** (e.g. `2026-04-13` or `2026-04-13T10:30:00.000Z`) with no formatting applied.

### useDateFormat hook

```ts
import { useDateFormat } from '@docyrus/ui/hooks/use-date-format';

function MyComponent() {
  const { formatDate, formatDateTime, formatTime } = useDateFormat();

  return <span>{formatDate(someDate)}</span>;
}
```

## API Reference

### UiTranslationProvider

| Prop | Type | Description |
|------|------|-------------|
| `t` | `(key: string, fallback?: string \| Record<string, string \| number>) => string` | Translation function from your i18n library |
| `children` | `ReactNode` | Child components |

### useUiTranslation

```ts
function useUiTranslation(): { t: TranslateFn }
```

Returns `{ t }` where `t(key, fallback)` resolves to:
- Translated string from provider (if available)
- English fallback string (if no provider or key not found)

### DateFormatProvider

| Prop | Type | Description |
|------|------|-------------|
| `formatDate` | `(value: unknown) => string` | Format a date value for display |
| `formatDateTime` | `(value: unknown) => string` | Format a datetime value for display |
| `formatTime` | `(value: unknown) => string` | Format a time value for display |
| `children` | `ReactNode` | Child components |

### useDateFormat

```ts
function useDateFormat(): {
  formatDate: (value: unknown) => string;
  formatDateTime: (value: unknown) => string;
  formatTime: (value: unknown) => string;
}
```

Returns formatters from `DateFormatProvider`. Without a provider, all formatters return the raw value as a string.

---

# Installation
URL: /docs/web/guide/installation

How to install and set up Docyrus UI components in your project.

## Prerequisites

Docyrus UI components are distributed via the shadcn registry. Before you start, make sure your project has shadcn/ui initialized.

If you haven't set up shadcn/ui yet, run the init command to create a `components.json` configuration file in your project root:

```bash
npx shadcn@latest init
```

## Add the Docyrus registry

Add the Docyrus registry to your `components.json` file so the CLI knows where to fetch components from:

```json title="components.json"
{
  "registries": {
    "docyrus": {
      "url": "https://ui.docy.app/r"
    }
  }
}
```

## Add components

Install components using the **Docyrus CLI**:

```bash
# Install a component
npx @docyrus/cli add button

# Install a hook
npx @docyrus/cli add hooks-debounce

# Install a utility
npx @docyrus/cli add utils-cn

# Install multiple items at once
npx @docyrus/cli add button dialog hooks-debounce
```

The CLI reads your `components.json` configuration and installs the correct variant automatically.

## Import and use

Once installed, import the component from your local components directory and use it in your project:

```tsx title="app/page.tsx"
import { Button } from '@/components/docyrus/button';

export default function Home() {
  return (
    <div>
      
    </div>
  );
}
```

Components are installed as source code — you can freely modify, extend, or restyle them to fit your needs.

---

# Releases
URL: /docs/web/guide/releases

Latest releases and updates for Docyrus UI web components.

Track the latest changes, features, and bug fixes for the `@docyrus/ui` web component library.

---

# Theming
URL: /docs/web/guide/theming

Customize the look and feel of Docyrus UI components with CSS variables and the theme generator.

## Overview

Docyrus UI uses CSS custom properties (variables) with the OKLCH color space for theming. Every component reads its colors, spacing, typography, and shadows from these variables — making full visual customization possible without touching component code.

The theme system is built on top of [shadcn/ui theming](https://ui.shadcn.com/docs/theming), extended with additional variables for charts, sidebar, shadows, and tracking.

## Color System

All colors use the **OKLCH** color space for perceptually uniform color manipulation:

```css title="globals.css"
:root {
  --background: oklch(1.0000 0 0);
  --foreground: oklch(0.1288 0.0406 264.6952);
  --primary: oklch(0.2077 0.0398 265.7549);
  --primary-foreground: oklch(0.9842 0.0034 247.8575);
  /* ... */
}

.dark {
  --background: oklch(0.1288 0.0406 264.6952);
  --foreground: oklch(0.9842 0.0034 247.8575);
  --primary: oklch(0.9842 0.0034 247.8575);
  --primary-foreground: oklch(0.1288 0.0406 264.6952);
  /* ... */
}
```

### Core Variables

| Variable | Description |
|----------|-------------|
| `--background` | Page/app background |
| `--foreground` | Default text color |
| `--primary` | Primary brand color (buttons, links, active states) |
| `--secondary` | Secondary UI surfaces |
| `--muted` | Subdued backgrounds and borders |
| `--accent` | Highlighted or focused elements |
| `--destructive` | Error/danger actions |
| `--border` | Default border color |
| `--input` | Input field borders |
| `--ring` | Focus ring color |

### Card & Popover

| Variable | Description |
|----------|-------------|
| `--card` | Card background |
| `--card-foreground` | Card text color |
| `--popover` | Popover/dropdown background |
| `--popover-foreground` | Popover text color |

### Sidebar

| Variable | Description |
|----------|-------------|
| `--sidebar` | Sidebar background |
| `--sidebar-foreground` | Sidebar text |
| `--sidebar-primary` | Sidebar active item |
| `--sidebar-accent` | Sidebar hover state |
| `--sidebar-border` | Sidebar border |

### Charts

| Variable | Description |
|----------|-------------|
| `--chart-1` through `--chart-5` | Chart color palette |

### Shadows

Shadows use a composable system with individual variables:

```css
:root {
  --shadow-x: 0px;
  --shadow-y: 1px;
  --shadow-blur: 3px;
  --shadow-spread: 0px;
  --shadow-opacity: 0.1;
  --shadow-color: 0 0 0;
}
```

Pre-composed shadow scales: `--shadow-2xs`, `--shadow-xs`, `--shadow-sm`, `--shadow`, `--shadow-md`, `--shadow-lg`, `--shadow-xl`, `--shadow-2xl`.

### Typography

| Variable | Description |
|----------|-------------|
| `--font-sans` | Sans-serif font stack |
| `--font-serif` | Serif font stack |
| `--font-mono` | Monospace font stack |
| `--tracking-normal` | Default letter spacing |

### Geometry

| Variable | Description |
|----------|-------------|
| `--radius` | Base border radius (default: `0.5rem`) |
| `--spacing` | Base spacing unit (default: `0.25rem`) |

## Dark Mode

Dark mode is activated by adding the `dark` class to a parent element (typically `<html>`). Docyrus UI provides `DocyThemeProvider` for automatic dark/light/system switching:

```tsx
import { DocyThemeProvider } from '@/lib/theme';

function App({ children }) {
  return (
    
  );
}
```

Inside components, use the `useDocyTheme()` hook to access the resolved theme:

```tsx
import { useDocyTheme } from '@/lib/theme';

function MyComponent() {
  const { isDark, mode, setMode, lang } = useDocyTheme();

  return <div>{isDark ? 'Dark' : 'Light'}</div>;
}
```

Components automatically adapt to the active theme through CSS variable inheritance. `DocyThemeProvider` manages the `dark` class on `<html>`, persists the preference to localStorage, and listens for system color scheme changes.

## Theme Generator

Use the built-in [Theme Generator](/themes) to visually customize your theme:

1. **Pick a base color scheme** (Slate, Gray, Zinc, Stone, Neutral)
2. **Adjust primary accent** color with the color picker
3. **Set border radius** and shadow intensity
4. **Preview** components in real-time
5. **Export** the CSS variables to paste into your `globals.css`

## Custom Theme Example

To create a custom theme, override the CSS variables in your `globals.css`:

```css title="globals.css"
@import "tailwindcss";

:root {
  /* Warm orange primary */
  --primary: oklch(0.7690 0.1880 70.0800);
  --primary-foreground: oklch(0.1500 0 0);

  /* Rounded look */
  --radius: 0.75rem;

  /* Softer shadows */
  --shadow-opacity: 0.06;
}

.dark {
  --primary: oklch(0.7690 0.1880 70.0800);
  --primary-foreground: oklch(0.1500 0 0);
  --shadow-opacity: 0.4;
}
```

## Using Theme Values in Components

Access theme variables through Tailwind CSS utilities:

```tsx
// Background and text
<div className="bg-primary text-primary-foreground" />

// Borders
<div className="border border-border rounded-[var(--radius)]" />

// Shadows
<div className="shadow-md" />

// Custom usage with CSS variable
<div style={{ color: 'var(--chart-1)' }} />
```

## Color Palette Reference

Docyrus UI ships with 5 neutral base palettes:

| Palette | Character |
|---------|-----------|
| **Slate** | Cool blue-gray (default) |
| **Gray** | Pure neutral gray |
| **Zinc** | Warm gray with slight warmth |
| **Stone** | Warm brown-gray |
| **Neutral** | True neutral, no undertone |

Each palette provides a complete set of light and dark mode variables.

---

# Troubleshooting
URL: /docs/web/guide/troubleshooting

Common issues and solutions when using Docyrus UI web components.

## Verify your versions

Make sure your environment meets or exceeds these minimum versions.

| Dependency | Minimum Version |
|---|---|
| React | 19 |
| Next.js | 16 |
| Tailwind CSS | 4.0 |
| Node.js | 18 |
| Radix UI | 1.4.0 |

## Registry not found

If you see a "registry not found" error when installing components, make sure you've added the Docyrus registry to your `components.json` file. The registry URL should point to `https://ui.docy.app/r`. Without this entry, neither the shadcn CLI nor the Docyrus CLI will know where to fetch components from.

## Components not resolving after installation

After installing a component, your imports should point to the local file path where the component was placed — not to an NPM package. If your IDE shows unresolved imports, check that the component files were actually written to disk and that your TypeScript path aliases match the install location.

## Tailwind CSS v4 classes not applying

Tailwind CSS v4 uses a CSS-based configuration system. If component styles aren't applying, make sure your CSS entry file includes a `@source` directive that covers the directory where Docyrus UI components are installed. Without this, Tailwind's compiler won't scan those files for utility classes.

## Dark mode not working

Docyrus UI components use CSS custom properties (CSS variables) for theming. Dark mode relies on these variables being defined in your global stylesheet. If dark mode isn't working, verify that your theme variables are set up correctly for both light and dark color schemes.

## Motion library version conflicts

Some Docyrus UI components use the Motion library for animations. If you see runtime errors related to motion or framer-motion, make sure you're using a compatible version. Docyrus UI targets Motion v12 and above.

## Still having issues?

If none of the above solutions resolve your problem, please [open an issue on GitHub](https://github.com/docyrus/docyrus-ui/issues) with a description of what you're experiencing and your environment details.

---

# Overview
URL: /docs/web/hooks

Reusable React hooks for common patterns.

Browse all available Docyrus UI hooks.

## Available Hooks

| Hook | Description |
|-----------|-------------|
| [useClickOutside](/docs/web/hooks/use-click-outside) | useClickOutside hook. |
| [useDateFormat](/docs/web/hooks/use-date-format) | Provider-agnostic date / datetime / time formatting context for Docyrus UI components. Wired automatically by DocyrusTenantProvider, but works with any date library. |
| [useNumberFormat](/docs/web/hooks/use-number-format) | Provider-agnostic number formatting context for Docyrus UI components. Mirror of useDateFormat — wired automatically by DocyrusTenantProvider, but works with any number formatting library. |
| [useUiTranslation](/docs/web/hooks/use-ui-translation) | useUiTranslation hook. |
| [useAdaptiveCard](/docs/web/hooks/use-adaptive-card) | Headless state, validation, visibility, and action dispatch for the Adaptive Cards 1.5 renderer. Drives the `AdaptiveCard` component and is exported so consumers can wire custom toolbars or server-side validation. |
| [useDataExport](/docs/web/hooks/use-data-export) | Project an in-memory array of rows through a column definition and trigger a browser download as CSV, JSON, Markdown, or XLSX. |
| [useDocyrusAdaptiveCardItemDetail](/docs/web/hooks/use-docyrus-adaptive-card-item-detail) | Generate an Adaptive Card JSON payload from a Docyrus field list + a single record — mapping Docyrus field types onto the Adaptive Cards element vocabulary — and render it with the shared AdaptiveCard renderer. |
| [useDocyrusAdaptiveCardItemList](/docs/web/hooks/use-docyrus-adaptive-card-item-list) | Generate an array of Adaptive Card JSON payloads from a Docyrus field list + many records, and render them as a responsive grid, a stacked list, or a single Carousel card with the shared AdaptiveCard renderer. |
| [useDocyrusAgentAttachments](/docs/web/hooks/use-docyrus-agent-attachments) | useDocyrusAgentAttachments hook. |
| [useDocyrusAgentInfo](/docs/web/hooks/use-docyrus-agent-info) | useDocyrusAgentInfo hook. |
| [useDocyrusAgentMemories](/docs/web/hooks/use-docyrus-agent-memories) | useDocyrusAgentMemories hook. |
| [useDocyrusAgentMemoryCandidates](/docs/web/hooks/use-docyrus-agent-memory-candidates) | useDocyrusAgentMemoryCandidates hook. |
| [useDocyrusAgentProjects](/docs/web/hooks/use-docyrus-agent-projects) | useDocyrusAgentProjects hook. |
| [useDocyrusAgentThreads](/docs/web/hooks/use-docyrus-agent-threads) | useDocyrusAgentThreads hook. |
| [useDocyrusCalendar](/docs/web/hooks/use-docyrus-calendar) | Wire a Docyrus data source to a fully configured calendar with auto-detected date / title / user fields, view-aware date-range fetching, color mapping, and drag-and-drop persistence. |
| [useDocyrusContactActivity](/docs/web/hooks/use-docyrus-contact-activity) | Merge a Docyrus record's audit log, threaded comments, related events, tasks, and status updates into one timeline for , plus comment and status mutations. |
| [useDocyrusContactChannels](/docs/web/hooks/use-docyrus-contact-channels) | useDocyrusContactChannels hook. |
| [useDocyrusDataExport](/docs/web/hooks/use-docyrus-data-export) | Server-side export for Docyrus data sources — POSTs a query payload to the export edge function and streams the result file straight to the browser. |
| [useDocyrusDataGallery](/docs/web/hooks/use-docyrus-data-gallery) | One-call wiring of a Docyrus data source to a fully configured DataGallery + toolbar (DataGridViewSelect, search, filters, sort, group, gallery display menu, card config menu) — including row fetching, saved views, pivot filters, and automatic card field detection. |
| [useDocyrusDataGrid](/docs/web/hooks/use-docyrus-data-grid) | One-call wiring of a Docyrus data source to a fully configured DataGrid + toolbar (DataGridViewSelect, search, filters, group, sort, row height, display) — including row fetching with view-derived query parameters. |
| [useDocyrusDataImportWizard](/docs/web/hooks/use-docyrus-data-import-wizard) | One-call wiring of a Docyrus data source to the DataImportWizard — handles upload, analyse, mapping, preview, and import in a single guided flow. |
| [useDocyrusDataSourceJsonSchema](/docs/web/hooks/use-docyrus-data-source-json-schema) | Generate a JSON Schema (object schema, properties keyed by field slug) from a Docyrus data source field list. |
| [useDocyrusDataTable](/docs/web/hooks/use-docyrus-data-table) | One-call wiring of a Docyrus data source to a fully configured DataTable + toolbar (DataGridViewSelect, search, filters, group, sort) — including row fetching with view-derived query parameters and an optional side-panel filter rail. |
| [useDocyrusDataViewSelect](/docs/web/hooks/use-docyrus-data-view-select) | Fetch data source fields and saved views from Docyrus and wire them into DataGridViewSelect with a single hook. |
| [useDocyrusDummyDataGeneratorWizard](/docs/web/hooks/use-docyrus-dummy-data-generator-wizard) | One-call wiring of a Docyrus data source to the DummyDataGenerator — handles field-aware strategies, deterministic generation, preview, and batch insert in a single guided flow. |
| [useDocyrusEmailComposer](/docs/web/hooks/use-docyrus-email-composer) | Wire an `` to the Docyrus messaging API — loads sender accounts, lets the user pick a From address, and ships emails through `/v1/messaging/email/accounts/{id}/send`. |
| [useDocyrusFieldComponent](/docs/web/hooks/use-docyrus-field-component) | Resolve the right UI component (form input, value renderer, data-grid cell, editable value, or TanStack column def builder) for any Docyrus data source field type. |
| [useDocyrusFormView](/docs/web/hooks/use-docyrus-form-view) | One-call wiring of a Docyrus data source item to create, edit, and read-only layouts with shared field-component mapping, item loading, option hydration, and submit handling. |
| [useDocyrusInstantMessageComposer](/docs/web/hooks/use-docyrus-instant-message-composer) | useDocyrusInstantMessageComposer hook. |
| [useDocyrusInventory](/docs/web/hooks/use-docyrus-inventory) | Shared app-utils inventory cache for Docyrus metadata (apps, data sources with fields/enums/views/forms, users, brands, preferences) plus a post-sign-in load() warm-up hook that drives an application loading dialog. |
| [useDocyrusKanban](/docs/web/hooks/use-docyrus-kanban) | One-call wiring of a Docyrus data source to a fully configured Kanban board with select/status/radio-group, user, and date columns, drag-to-update persistence, final-zone integration, and a standard Docyrus card layout. |
| [useDocyrusLogActivity](/docs/web/hooks/use-docyrus-log-activity) | useDocyrusLogActivity hook. |
| [useDocyrusMapView](/docs/web/hooks/use-docyrus-map-view) | Build Docyrus-backed map pages from a locationSelect field with saved views, marker models, and ready-to-render Leaflet or Google Maps canvases. |
| [useDocyrusPivotCalendar](/docs/web/hooks/use-docyrus-pivot-calendar) | Wires the PivotCalendar component to a Docyrus data source using the items endpoint's pivot parameter for server-side aggregation. |
| [useDocyrusPivotFilter](/docs/web/hooks/use-docyrus-pivot-filter) | Wire a Docyrus data source to a `<PivotFilter>` strip — auto-detects the field type, runs a pivot/aggregate query, transforms results into pill items, and emits filter rules ready to merge into a grid query. |
| [useDocyrusPivotGrid](/docs/web/hooks/use-docyrus-pivot-grid) | Wires the PivotGrid component to a Docyrus data source with optional server-side aggregation via pivot.matrix + calculations. |
| [useDocyrusTenant](/docs/web/hooks/use-docyrus-tenant) | Single-line tenant integration that fetches tenant preferences, builds dateUtils + numberUtils, and wires DateFormatProvider + NumberFormatProvider so every UI component (data grids, calendars, filters, value renderers) picks up the tenant's configured date/time/number formats automatically. |
| [useDynamicFormView](/docs/web/hooks/use-dynamic-form-view) | Backend-agnostic dynamic form renderer — the sibling of useDocyrusFormView with no Docyrus wiring. Supply fields, values, options, and an onSubmit sink to render create/edit/view forms against any backend. |
| [useLocalDataSourceDataGrid](/docs/web/hooks/use-local-data-source-data-grid) | Wire a LocalDataSource object into the Docyrus DataGrid hook stack, including toolbar search, filters, sorting, grouping, saved views, and local CRUD. |
| [useLocalDataSource](/docs/web/hooks/use-local-data-source) | Create an in-memory Docyrus-compatible data source from a JSON array, with local CRUD and Docyrus-style query parameters. |
| [useParameterPersistence](/docs/web/hooks/use-parameter-persistence) | useParameterPersistence hook. |
| [useSpeechRecognition](/docs/web/hooks/use-speech-recognition) | useSpeechRecognition hook. |

---

# useAdaptiveCard
URL: /docs/web/hooks/use-adaptive-card

Headless state, validation, visibility, and action dispatch for the Adaptive Cards 1.5 renderer. Drives the `AdaptiveCard` component and is exported so consumers can wire custom toolbars or server-side validation.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-adaptive-card
```

**Dependencies:**
- [react](https://react.dev)

## Overview

`useAdaptiveCard` owns the runtime state for an [`AdaptiveCard`](/docs/web/components/adaptive-card) instance:

- **Inputs** — a registry of every visible `Input.*` element, keyed by `id`, with live values and per-input validation state.
- **Visibility overrides** — the `Action.ToggleVisibility` map layered on top of static `isVisible` defaults.
- **Show-card state** — open/closed flags for every `Action.ShowCard` button.
- **Action dispatch** — typed event emission for `submit`, `execute`, `openUrl`, `toggleVisibility`, `showCard`.
- **Submit payload assembly** — walks the visible tree honoring `associatedInputs: 'auto' \| 'none'`, merges `action.data`, and emits a strongly typed event.

The `` component composes this hook internally. You only need to call it directly when:

- You want to trigger actions programmatically (e.g. a custom toolbar that says "Submit & close").
- You need to read input state from outside the card (e.g. to disable a parent's submit button).
- You want to wire server-side validation that returns errors per `inputId`.

## Usage

### Default integration (when `` isn't enough)

```tsx
'use client';

import {
  AdaptiveCardView,
  useAdaptiveCard,
  type AdaptiveCardActionEvent,
  type AdaptiveCardPayload
} from '@docyrus/ui/components/adaptive-card';

export function CardWithToolbar({ payload }: { payload: AdaptiveCardPayload }) {
  function handleAction(event: AdaptiveCardActionEvent) {
    console.log(event);
  }

  const adaptive = useAdaptiveCard(payload, { onAction: handleAction });

  return (
    <div>
      <button onClick={() => adaptive.controls.validateAll()}>Validate</button>
      
    </div>
  );
}
```

### Reading current input state

```tsx
const adaptive = useAdaptiveCard(payload);

// Live, controlled
console.log(adaptive.state.inputs.email);
console.log(adaptive.state.validations.email);
```

### Programmatic submit

```tsx
const submitAction = payload.actions?.find(a => a.type === 'Action.Submit');

if (submitAction && submitAction.type === 'Action.Submit') {
  adaptive.controls.submit(submitAction);
}
```

### Resetting after a successful save

```tsx
async function handleAction(event: AdaptiveCardActionEvent) {
  if (event.type !== 'submit') return;

  await fetch('/api/forms', { method: 'POST', body: JSON.stringify(event.data) });
  adaptive.controls.reset(); // clears inputs, visibility overrides, show-card state
}
```

## API Reference

### `UseAdaptiveCardOptions`

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `onAction` | `(event: AdaptiveCardActionEvent) => void \| Promise<void>` | — | Receives every dispatched action. |
| `hostConfig` | `AdaptiveCardHostConfigOverride` | — | Deep-merged onto `defaultHostConfig`. |
| `customElements` | `Record<string, ElementRenderer>` | `{}` | Renderers for unknown `type` strings. |

### `UseAdaptiveCardReturn`

| Field | Type | Description |
|-------|------|-------------|
| `card` | `AdaptiveCardPayload` | The original payload (post-`parseAdaptiveCard` normalization). |
| `hostConfig` | `AdaptiveCardHostConfig` | The resolved host config (default deep-merged with override). |
| `state.inputs` | `Record<string, AdaptiveCardInputValue>` | Live input values, keyed by `id`. |
| `state.validations` | `Record<string, { isValid; errorMessage? }>` | Per-input validation, recomputed on every input change. |
| `state.visibilityOverrides` | `Record<string, boolean>` | `Action.ToggleVisibility` overrides keyed by element `id`. |
| `state.showCardOpen` | `Record<string, boolean>` | Open flags for `Action.ShowCard`, keyed by action `id`/`title`. |
| `state.hasSubmittedOnce` | `boolean` | Becomes `true` after the first failed submit so per-input error messages render. |
| `controls.setInput(id, value)` | `(id, value) => void` | Imperatively set an input. |
| `controls.submit(action)` | `(action: AdaptiveCardActionSubmit) => void` | Validate + dispatch `'submit'`. |
| `controls.execute(action)` | `(action: AdaptiveCardActionExecute) => void` | Validate + dispatch `'execute'` with `verb`. |
| `controls.openUrl(action)` | `(action: AdaptiveCardActionOpenUrl) => void` | Dispatch `'openUrl'`. |
| `controls.toggleVisibility(action)` | `(action: AdaptiveCardActionToggleVisibility) => void` | Apply visibility overrides + dispatch `'toggleVisibility'`. |
| `controls.toggleShowCard(action)` | `(action: AdaptiveCardActionShowCard) => void` | Flip a show-card and dispatch `'showCard'`. |
| `controls.validateAll()` | `() => { ok; firstInvalidId?; errors }` | Run validation immediately. Does not dispatch. |
| `controls.reset()` | `() => void` | Clear inputs / overrides / show-card state. |
| `cardProps` | `AdaptiveCardContextValue` | The projection consumed by ``. |

## Validation timing

- **First submit** runs validation silently. If any input fails, the hook sets `state.hasSubmittedOnce = true`, focuses the first invalid input, and does **not** dispatch.
- After the first failed submit, validations re-render live so error messages clear as the user fixes them.
- This matches the reference renderer's behavior — users don't see errors before they've tried to submit.

## `associatedInputs` contract

`Action.Submit` and `Action.Execute` walk the **currently visible** card tree to build the submit payload:

- `'auto'` (default) — collect every `Input.*` whose `isVisible` evaluation is true under the current `visibilityOverrides` map. Hidden inputs are dropped.
- `'none'` — skip inputs entirely; emit only the literal `action.data`.

For `Action.ShowCard`-nested submits, the nested card's inputs merge into the parent's, mirroring the spec.

## Type Exports

| Type | Description |
|------|-------------|
| `UseAdaptiveCardOptions` | Hook options. |
| `UseAdaptiveCardReturn` | Full hook return. |
| `AdaptiveCardInputValue` | `string \| Array<string> \| boolean \| number \| null`. |

---

# useClickOutside
URL: /docs/web/hooks/use-click-outside

useClickOutside hook.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-click-outside
```

## Usage

```tsx
import { useClickOutside } from '@docyrus/ui/hooks/use-click-outside';

function MyComponent() {
  const result = useClickOutside(..., () => {}, 'mousedown');
}
```

## API Reference

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `ref` | `RefObject<T \| null> \| RefObject<T \| null>[]` | `—` | — |
| `handler` | `(event: Event) => void` | `—` | — |
| `eventType` | `EventType` | `'mousedown'` | — |

**Returns:** `void`

---

# useDataExport
URL: /docs/web/hooks/use-data-export

Project an in-memory array of rows through a column definition and trigger a browser download as CSV, JSON, Markdown, or XLSX.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-data-export
```

**Dependencies:**
- [xlsx](https://www.npmjs.com/package/xlsx)

`xlsx` is loaded with a dynamic `import('xlsx')` and is only fetched when `format === 'xlsx'`. CSV, JSON, and Markdown exports work without it.

## Overview

`useDataExport` is a generic, framework-agnostic export hook for any in-memory array. You describe how each column should be projected, and the hook handles serialization, escaping, blob construction, and the browser download.

- **Four formats** — `csv`, `json`, `markdown`, and `xlsx`.
- **Column projection** — pick fields, rename headers, derive values via `accessor`, format cells via `formatter`. Order is preserved in the output.
- **Safe by default** — CSV cells are RFC 4180 escaped, Markdown cells escape `|`, `\`, and newlines, and `Date` values are written as ISO strings.
- **Excel-friendly** — CSV output is prefixed with a UTF-8 BOM so Excel auto-detects encoding (toggle with `csvBom`).
- **SSR-safe** — `exportData()` is a no-op on the server (`typeof window === 'undefined'`) and returns `null` instead of throwing.
- **Lazy xlsx** — the `xlsx` package is only loaded when the user actually picks the XLSX format.

## Usage

### Basic example

```tsx
'use client';

import { Button } from '@docyrus/ui/primitives/ui/button';
import { useDataExport } from '@docyrus/ui/library/hooks/use-data-export';

type Contact = {
  id: string;
  name: string;
  email: string;
  createdAt: Date;
};

const rows: Array
  );
}
```

### Custom accessor + formatter

```tsx
const { exportData } = useDataExport
    
    
      ))}
    
  
);
```

### Awaiting the resolved file metadata

```tsx
async function downloadAndToast() {
  const result = await exportData(rows, 'xlsx');

  if (!result) return; // server-side, no-op

  toast.success(`Saved ${result.fileName}`);
}
```

## API Reference

### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `options` | `UseDataExportOptions<TData>` | — | Hook configuration (see below). **Required.** |

### `UseDataExportOptions<TData>`

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `columns` | `Array<DataExportColumn<TData>>` | — | Column projection. Order is preserved in the output. **Required.** |
| `fileName` | `string` | `'export'` | File name without extension. The format-specific extension is appended automatically. |
| `sheetName` | `string` | `'Sheet1'` | Sheet name used for `xlsx` exports. |
| `csvBom` | `boolean` | `true` | Prepend a UTF-8 BOM to CSV output so Excel auto-detects encoding. |

### `DataExportColumn<TData>`

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `id` | `string` | — | Stable column id. Used as the JSON object key when `format === 'json'` and as the lookup key when `accessor` is omitted. **Required.** |
| `header` | `string` | — | Header label rendered in CSV / Markdown / XLSX output. **Required.** |
| `accessor` | `(row: TData) => unknown` | `row => row[id]` | Pull the raw cell value for this column from a row. |
| `formatter` | `(value: unknown, row: TData) => string` | default stringifier | Coerce the raw value into the string written to the file. The default renders primitives verbatim, ISO-formats `Date`s, and `JSON.stringify`s objects/arrays. |

### Return Value — `UseDataExportResult<TData>`

| Property | Type | Description |
|----------|------|-------------|
| `exportData` | `(rows: Array<TData>, format: DataExportFormat) => Promise<DataExportResult \| null>` | Project `rows` through `columns` and trigger a browser download in the requested `format`. Returns `null` on the server. |
| `isExporting` | `boolean` | `true` while a download is in flight (mainly relevant for the async `xlsx` path). Use it to disable the trigger button. |

### `DataExportResult`

| Property | Type | Description |
|----------|------|-------------|
| `mimeType` | `string` | MIME type written to the `Blob`. |
| `extension` | `string` | File extension including the leading dot (e.g. `'.csv'`). |
| `fileName` | `string` | Final file name (`<fileName><extension>`). |

### Type Exports

| Type | Description |
|------|-------------|
| `DataExportFormat` | `'csv' \| 'json' \| 'markdown' \| 'xlsx'` |
| `DataExportColumn<TData>` | Single-column definition (`id`, `header`, `accessor`, `formatter`). |
| `UseDataExportOptions<TData>` | Hook input (`columns`, `fileName`, `sheetName`, `csvBom`). |
| `UseDataExportResult<TData>` | Hook return value (`exportData`, `isExporting`). |
| `DataExportResult` | File metadata returned by `exportData()`. |

## Format Reference

| Format | Extension | MIME Type | Notes |
|--------|-----------|-----------|-------|
| `csv` | `.csv` | `text/csv;charset=utf-8` | RFC 4180 escaping. UTF-8 BOM prepended unless `csvBom: false`. CRLF line endings. |
| `json` | `.json` | `application/json;charset=utf-8` | Pretty-printed (`JSON.stringify(rows, null, 2)`). Object keys come from each column's `id`. |
| `markdown` | `.md` | `text/markdown;charset=utf-8` | GitHub-flavored table. `\|`, `\\`, and newlines are escaped; multi-line cells use `<br />`. |
| `xlsx` | `.xlsx` | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` | Lazy-loads the `xlsx` package. Numbers, booleans, and `Date` values are written as their native Excel types. |

## Notes

- The hook keeps no internal cache — pass the rows you want to export each time you call `exportData()`. This is what lets the same hook handle a filtered grid, a selection-only export, and a "download all" button.
- Calling `exportData()` from a server component or during SSR is safe: the function bails out before touching `document` and resolves to `null`.
- The download is triggered by injecting a temporary `<a download>` element. No popup, no new tab, no user gesture beyond the original click.

---

# useDateFormat
URL: /docs/web/hooks/use-date-format

Provider-agnostic date / datetime / time formatting context for Docyrus UI components. Wired automatically by DocyrusTenantProvider, but works with any date library.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-date-format
```

The module exports `useDateFormat()` (hook) and `
  );
}
```

The same pattern works with `dayjs`, `next-intl`, or any other library.

## API Reference

### `useDateFormat()`

Returns `DateFormatContextValue`.

| Field | Type | Description |
|-------|------|-------------|
| `formatDate` | `(value: unknown) => string` | Date-only output. |
| `formatDateTime` | `(value: unknown) => string` | Date + time output. |
| `formatTime` | `(value: unknown) => string` | Time-only output. |

### `<DateFormatProvider>`

| Prop | Type | Description |
|------|------|-------------|
| `formatDate` | `DateFormatFn` | Required. Backs `formatDate` inside the tree. |
| `formatDateTime` | `DateFormatFn` | Required. Backs `formatDateTime` inside the tree. |
| `formatTime` | `DateFormatFn` | Required. Backs `formatTime` inside the tree. |
| `children` | `ReactNode` | Tree to wrap. |

### `isDefaultDateFormatContext(ctx)`

Returns `true` when the value returned by `useDateFormat()` is the built-in no-provider sentinel (raw string renderer) rather than a real provider. Internal hooks use this to avoid shadowing a cell's own fallback when no provider is mounted. Most apps don't need to call it directly.

## Type Exports

| Type | Description |
|------|-------------|
| `DateFormatFn` | Signature of each formatter function (`(value: unknown) => string`). |
| `DateFormatContextValue` | Shape returned by `useDateFormat()`. |

---

# useDocyrusAdaptiveCardItemDetail
URL: /docs/web/hooks/use-docyrus-adaptive-card-item-detail

Generate an Adaptive Card JSON payload from a Docyrus field list + a single record — mapping Docyrus field types onto the Adaptive Cards element vocabulary — and render it with the shared AdaptiveCard renderer.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-docyrus-adaptive-card-item-detail
```

**Dependencies:**
- [react](https://react.dev)

## Overview

`useDocyrusAdaptiveCardItemDetail` is the bridge between **Docyrus field types**
(`field-select`, `field-money`, `field-image`, …) and the **Adaptive Cards**
element vocabulary (`TextBlock`, `FactSet`, `Image`, `Badge`, `CodeBlock`, …).

You hand it a field list + one record and it **generates an Adaptive Card JSON
payload** (`card`) — the primary output. The card is then drawn by the shared
[`AdaptiveCard`](/docs/web/components/adaptive-card) renderer; the hook also
returns a ready-to-render `view` and the full [`useAdaptiveCard`](/docs/web/hooks/use-adaptive-card)
runtime (state / controls / `cardProps`) so you can wire actions.

It is **backend-agnostic** — no network I/O. Pass any Docyrus-shaped field list
(`IField[]`, `DataSourceField[]`, or the loose `DocyrusAdaptiveCardField[]`) and
a plain record object. When a [`DocyrusTenantProvider`](/docs/web/hooks/use-docyrus-tenant)
is mounted, date / number / currency values are formatted with the tenant's
preferences automatically.

## Usage

### Generate + render a detail card

```tsx
'use client';

import { useDocyrusAdaptiveCardItemDetail } from '@docyrus/ui/hooks/use-docyrus-adaptive-card-item-detail';

export function DealDetail({ fields, record }) {
  const { view } = useDocyrusAdaptiveCardItemDetail({ fields, record });

  return view;
}
```

### Use the generated JSON directly

The `card` field is a plain Adaptive Card payload — persist it, post it to Teams,
or render it yourself with ``.

```tsx
import { AdaptiveCard } from '@docyrus/ui/components/adaptive-card';
import { useDocyrusAdaptiveCardItemDetail } from '@docyrus/ui/hooks/use-docyrus-adaptive-card-item-detail';

const { card } = useDocyrusAdaptiveCardItemDetail({ fields, record });

// `card` === { type: 'AdaptiveCard', version: '1.5', body: [...] }
await fetch('/api/teams/notify', { method: 'POST', body: JSON.stringify(card) });

return ;
```

### Pin slots, add actions, react to clicks

```tsx
const { view } = useDocyrusAdaptiveCardItemDetail({
  fields,
  record,
  slots: {
    titleField: 'name',
    badgeField: 'status',
    coverImageField: 'cover',
    subtitleField: 'description'
  },
  actions: [
    { type: 'Action.OpenUrl', title: 'Open record', url: `/records/${record.id}` }
  ],
  onAction: (event) => {
    if (event.type === 'openUrl') router.push(event.url);
  }
});
```

## Field-type → Adaptive Card element mapping

The card body is assembled from three regions: a header (cover / avatar / title /
subtitle / status badge), a `FactSet` of scalar fields, and standalone blocks for
rich fields. Slots are auto-detected from field type + slug (see
[Slot detection](#slot-detection)); everything else lands in the body.

| Docyrus field type | Adaptive Card representation |
|--------------------|------------------------------|
| `field-text`, `field-email`, `field-url`, `field-phone`, `field-currency`, `field-color`, `field-icon`, `field-formula`, `field-identity` | Header title **or** `FactSet` value (`TextBlock`) |
| `field-number`, `field-autonumber`, `field-money`, `field-percent`, `field-duration`, `field-rating` | `FactSet` value — formatted (currency, `%`, `★`, `hh:mm:ss`) |
| `field-checkbox`, `field-switch` | `FactSet` value — `Yes`/`No`, `On`/`Off` |
| `field-date`, `field-dateTime`, `field-time`, `field-dateRange` | `FactSet` value — tenant-formatted date/time |
| `field-select`, `field-radioGroup`, `field-enum`, `field-systemEnum`, `field-status`, `field-approvalStatus` | Header status `Badge` (semantic color) **or** `FactSet` value (option name) |
| `field-multiSelect`, `field-tagSelect` | `FactSet` value — comma-joined option names |
| `field-userSelect` | `FactSet` value — user display name |
| `field-userMultiSelect` | `FactSet` value — joined user names |
| `field-relation`, `field-relatedField` | `FactSet` value — related record label |
| `field-image`, `field-avatar` | Cover / avatar `Image`, or an `Image` / `ImageSet` body block |
| `field-textarea`, `field-markdown`, `field-htmlEditor`, `field-emailEditor`, `field-docEditor` | Wrapped `TextBlock` block (HTML stripped) |
| `field-json`, `field-jsonSchema`, `field-jsonata`, `field-handlebars`, `field-code`, `field-codeEditor`, `field-queryBuilder`, `field-dsql` | `CodeBlock` block (language-tagged) |
| `field-file` | `FactSet` value — file name |
| `field-locationSelect` | `FactSet` value — address label |
| `field-taskList`, `field-todo` | `FactSet` value — `done / total` summary |
| `field-adaptiveCard`, `field-button`, `field-password`, `field-inlineForm`, `field-schema*`, `field-inlineData`, `field-dynamic`, `field-conversationChannel`, `field-fileStorageFolder`, `field-system*` | Skipped (no meaningful card representation) |

Enum / status colors (Tailwind families or hex) are classified to the nearest
Adaptive Card badge style: green → `good`, red → `attention`, amber → `warning`,
blue/purple → `accent`, otherwise `informative`.

## Slot detection

When you don't pin slots, bindings are auto-detected from the field list using the
same heuristics as the [data gallery](/docs/web/hooks/use-docyrus-data-gallery)
(slug hints first, then type). Override any slot with a slug, or `null` to disable
a detected binding:

| Slot | Auto-detected from |
|------|--------------------|
| `titleField` | slug `name` / `title` / `subject` / `label`, then a text/identity field |
| `subtitleField` | slug `description` / `summary` / `subtitle`, then a textarea field |
| `coverImageField` | slug `cover` / `image` / `thumbnail` / `banner`, then a `field-image` |
| `avatarField` | slug `avatar` / `profile_photo`, then a `field-avatar` |
| `badgeField` | slug `status` / `priority` / `stage`, then a status/select field |
| `timelineField` | slug `due` / `deadline` / `start`, then a `field-date` (leads the facts) |
| `bodyFields` | every remaining non-system field |

## API Reference

### `UseDocyrusAdaptiveCardItemDetailOptions`

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `fields` | `DocyrusAdaptiveCardField[]` | — | Field metadata (accepts `IField` / `DataSourceField` / `DocyrusFieldLike`). |
| `record` | `Record<string, unknown> \| null` | — | The record to render. |
| `enumOptions` | `Record<string, EnumOption[]>` | — | Per-field-slug enum options. Falls back to each field's inline `enums`. |
| `slots` | `DocyrusAdaptiveCardSlotOverrides` | — | Pin (`string`) or disable (`null`) individual slot bindings. |
| `includeFields` | `string[]` | — | Explicit, ordered body field list (replaces auto-detected body). |
| `excludeFields` | `string[]` | — | Field slugs to drop from the body. |
| `title` | `string` | — | Force the header title text. |
| `actions` | `AdaptiveCardAction[]` | — | Card-level actions appended to `payload.actions`. |
| `hideEmpty` | `boolean` | `true` | Drop empty fields instead of rendering an em-dash. |
| `factLayout` | `'facts' \| 'stacked'` | `'facts'` | Scalar layout — a `FactSet` or stacked label/value blocks. |
| `version` | `string` | `'1.5'` | Adaptive Card schema version. |
| `formatDate` | `(value) => string` | tenant context | Override the date formatter. |
| `formatDateTime` | `(value) => string` | tenant context | Override the datetime formatter. |
| `formatNumber` | `(value, opts?) => string` | tenant context | Override the number/currency/percent formatter. |
| `className` | `string` | — | Class forwarded to the rendered `view`. |
| `onAction` | `(event: AdaptiveCardActionEvent) => void` | — | Forwarded to `useAdaptiveCard`. |
| `hostConfig` | `AdaptiveCardHostConfigOverride` | — | Forwarded to `useAdaptiveCard`. |
| `customElements` | `Record<string, ElementRenderer>` | — | Forwarded to `useAdaptiveCard`. |
| `onChoiceQuery` | `(request) => Promise<AdaptiveCardChoice[]>` | — | Forwarded to `useAdaptiveCard`. |

### `UseDocyrusAdaptiveCardItemDetailReturn`

Extends [`UseAdaptiveCardReturn`](/docs/web/hooks/use-adaptive-card) (`state`,
`controls`, `cardProps`, `hostConfig`) with:

| Field | Type | Description |
|-------|------|-------------|
| `card` | `AdaptiveCardPayload` | The generated Adaptive Card JSON — the primary output. |
| `slots` | `DocyrusAdaptiveCardSlots` | The resolved slot bindings. |
| `view` | `ReactNode` | Ready-to-render `<AdaptiveCardView>` for the generated card. |

## Type Exports

| Type | Description |
|------|-------------|
| `UseDocyrusAdaptiveCardItemDetailOptions` | Hook options. |
| `UseDocyrusAdaptiveCardItemDetailReturn` | Hook return. |
| `DocyrusAdaptiveCardField` | Minimal field shape (`slug` + `name` + `type`, optional `enums`). |
| `DocyrusAdaptiveCardSlots` | Resolved slot bindings. |
| `DocyrusAdaptiveCardSlotOverrides` | Slot override map (`string` to pin, `null` to disable). |
| `DocyrusAdaptiveCardFactLayout` | `'facts' \| 'stacked'`. |

## See also

- [`useDocyrusAdaptiveCardItemList`](/docs/web/hooks/use-docyrus-adaptive-card-item-list) — the same mapping, for a list of records.
- [`AdaptiveCard`](/docs/web/components/adaptive-card) — the renderer.
- [`useAdaptiveCard`](/docs/web/hooks/use-adaptive-card) — the underlying runtime.

---

# useDocyrusAdaptiveCardItemList
URL: /docs/web/hooks/use-docyrus-adaptive-card-item-list

Generate an array of Adaptive Card JSON payloads from a Docyrus field list + many records, and render them as a responsive grid, a stacked list, or a single Carousel card with the shared AdaptiveCard renderer.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-docyrus-adaptive-card-item-list
```

**Dependencies:**
- [react](https://react.dev)

## Overview

`useDocyrusAdaptiveCardItemList` is the list companion of
[`useDocyrusAdaptiveCardItemDetail`](/docs/web/hooks/use-docyrus-adaptive-card-item-detail).
You hand it a **Docyrus field list + a list of records** and it **generates one
Adaptive Card JSON payload per record** (`cards`) — mapping Docyrus field types
onto the Adaptive Cards element vocabulary — then renders them with the shared
[`AdaptiveCard`](/docs/web/components/adaptive-card) renderer.

Both hooks share the same backend-agnostic mapper, so a card looks identical
whether it's shown alone (detail) or in a list. Four layouts are supported:

- **`grid`** (default) — a responsive CSS grid of cards (auto-fill or fixed columns).
- **`list`** — a single stacked column of cards.
- **`carousel`** — one combined Adaptive Card whose `Carousel` pages are the per-record bodies.
- **`table`** — one combined Adaptive Card whose `Table` has a field-label header row and one row per record (scalar fields become columns; images / rich-text / code are excluded). The table scrolls horizontally when it's wider than its container.

When a [`DocyrusTenantProvider`](/docs/web/hooks/use-docyrus-tenant) is mounted,
dates / numbers / currency are formatted with the tenant's preferences.

See [`useDocyrusAdaptiveCardItemDetail`](/docs/web/hooks/use-docyrus-adaptive-card-item-detail#field-type--adaptive-card-element-mapping)
for the full field-type → element mapping and slot-detection rules.

## Usage

### Render a responsive grid of cards

```tsx
'use client';

import { useDocyrusAdaptiveCardItemList } from '@docyrus/ui/hooks/use-docyrus-adaptive-card-item-list';

export function DealGallery({ fields, records }) {
  const { view } = useDocyrusAdaptiveCardItemList({
    fields,
    records,
    layout: 'grid',
    columns: 'flex',
    minCardWidth: 340
  });

  return view;
}
```

### Per-card actions + scoped click handler

`onItemAction` receives the originating record and index, so one handler routes
every card (not applied in `carousel` layout).

```tsx
const { view } = useDocyrusAdaptiveCardItemList({
  fields,
  records,
  getItemActions: (record) => [
    { type: 'Action.OpenUrl', title: 'Open', url: `/deals/${record.id}` }
  ],
  onItemAction: (event, record) => {
    if (event.type === 'openUrl') router.push(event.url);
  }
});
```

### Use the generated JSON array directly

```tsx
const { cards, items } = useDocyrusAdaptiveCardItemList({ fields, records });

// `cards` is AdaptiveCardPayload[] — one per record
// `items` is [{ id, record, card }] if you need the record alongside its card
await syncToTeams(cards);
```

### Carousel

```tsx
const { view, carouselCard } = useDocyrusAdaptiveCardItemList({
  fields,
  records,
  layout: 'carousel'
});

// `carouselCard` is the single combined AdaptiveCardPayload (a Carousel).
return view;
```

### Table

```tsx
const { view, tableCard } = useDocyrusAdaptiveCardItemList({
  fields,
  records,
  layout: 'table'
});

// `tableCard` is the single combined AdaptiveCardPayload (a Table:
// header row = field labels, one row per record). Scrolls horizontally
// when wider than its container.
return view;
```

## API Reference

### `UseDocyrusAdaptiveCardItemListOptions`

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `fields` | `DocyrusAdaptiveCardField[]` | — | Field metadata (accepts `IField` / `DataSourceField` / `DocyrusFieldLike`). |
| `records` | `Record<string, unknown>[] \| null` | — | Records to render as cards. |
| `enumOptions` | `Record<string, EnumOption[]>` | — | Per-field-slug enum options. Falls back to each field's inline `enums`. |
| `slots` | `DocyrusAdaptiveCardSlotOverrides` | — | Slot bindings shared by every card. |
| `includeFields` | `string[]` | — | Explicit, ordered body field list. |
| `excludeFields` | `string[]` | — | Field slugs to drop from every card body. |
| `hideEmpty` | `boolean` | `true` | Drop empty fields instead of rendering an em-dash. |
| `factLayout` | `'facts' \| 'stacked'` | `'facts'` | Scalar layout — a `FactSet` or stacked label/value blocks. |
| `version` | `string` | `'1.5'` | Adaptive Card schema version. |
| `getRecordId` | `(record, index) => string` | `record.id` → index | Stable key per record. |
| `getItemTitle` | `(record, index) => string \| undefined` | — | Per-card title override. |
| `getItemActions` | `(record, index) => AdaptiveCardAction[] \| undefined` | — | Per-card actions. |
| `onItemAction` | `(event, record, index) => void` | — | Action handler scoped to the record. Not applied in `carousel`. |
| `layout` | `'grid' \| 'list' \| 'carousel' \| 'table'` | `'grid'` | Rendered layout. `carousel` / `table` produce one combined card. |
| `columns` | `number \| 'flex'` | `'flex'` | Grid columns. `'flex'` auto-fills using `minCardWidth`. |
| `minCardWidth` | `number` | `320` | Minimum card width (px) for the `'flex'` grid. |
| `gap` | `number` | `16` | Gap (px) between cards. |
| `className` | `string` | — | Class for the list container. |
| `cardClassName` | `string` | — | Class for each card wrapper. |
| `emptyContent` | `ReactNode` | built-in | Shown when there are no records. |
| `formatDate` / `formatDateTime` / `formatNumber` | `function` | tenant context | Override formatters. |
| `hostConfig` | `AdaptiveCardHostConfigOverride` | — | Forwarded to every rendered card. |
| `customElements` | `Record<string, ElementRenderer>` | — | Forwarded to every rendered card. |

### `UseDocyrusAdaptiveCardItemListReturn`

| Field | Type | Description |
|-------|------|-------------|
| `cards` | `AdaptiveCardPayload[]` | The generated Adaptive Card JSON payloads — the primary output. |
| `items` | `DocyrusAdaptiveCardListItem[]` | `{ id, record, card }` per record. |
| `slots` | `DocyrusAdaptiveCardSlots` | Slot bindings shared by every card. |
| `carouselCard` | `AdaptiveCardPayload \| null` | Combined `Carousel` card in `carousel` layout, else `null`. |
| `view` | `ReactNode` | Ready-to-render list element. |

## Type Exports

| Type | Description |
|------|-------------|
| `UseDocyrusAdaptiveCardItemListOptions` | Hook options. |
| `UseDocyrusAdaptiveCardItemListReturn` | Hook return. |
| `DocyrusAdaptiveCardListItem` | `{ id, record, card }`. |
| `DocyrusAdaptiveCardListLayout` | `'grid' \| 'list' \| 'carousel'`. |
| `DocyrusAdaptiveCardField` | Minimal field shape. |
| `DocyrusAdaptiveCardSlots` / `DocyrusAdaptiveCardSlotOverrides` | Slot bindings / overrides. |
| `DocyrusAdaptiveCardFactLayout` | `'facts' \| 'stacked'`. |

## See also

- [`useDocyrusAdaptiveCardItemDetail`](/docs/web/hooks/use-docyrus-adaptive-card-item-detail) — single-record detail card + the full mapping table.
- [`AdaptiveCard`](/docs/web/components/adaptive-card) — the renderer.

---

# useDocyrusAgentAttachments
URL: /docs/web/hooks/use-docyrus-agent-attachments

useDocyrusAgentAttachments hook.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-docyrus-agent-attachments
```

## Usage

```tsx
import { useDocyrusAgentAttachments } from '@docyrus/ui/library/hooks/use-docyrus-agent-attachments';

function MyComponent() {
  const result = useDocyrusAgentAttachments(...);
}
```

## API Reference

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `{` | `—` | `—` | — |

---

# useDocyrusAgentInfo
URL: /docs/web/hooks/use-docyrus-agent-info

useDocyrusAgentInfo hook.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-docyrus-agent-info
```

## Usage

```tsx
import { useDocyrusAgentInfo } from '@docyrus/ui/library/hooks/use-docyrus-agent-info';

function MyComponent() {
  const result = useDocyrusAgentInfo(...);
}
```

## API Reference

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `{` | `—` | `—` | — |

---

# useDocyrusAgentMemories
URL: /docs/web/hooks/use-docyrus-agent-memories

useDocyrusAgentMemories hook.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-docyrus-agent-memories
```

## Usage

```tsx
import { useDocyrusAgentMemories } from '@docyrus/ui/library/hooks/use-docyrus-agent-memories';

function MyComponent() {
  const result = useDocyrusAgentMemories(...);
}
```

## API Reference

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `{` | `—` | `—` | — |

---

# useDocyrusAgentMemoryCandidates
URL: /docs/web/hooks/use-docyrus-agent-memory-candidates

useDocyrusAgentMemoryCandidates hook.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-docyrus-agent-memory-candidates
```

## Usage

```tsx
import { useDocyrusAgentMemoryCandidates } from '@docyrus/ui/library/hooks/use-docyrus-agent-memory-candidates';

function MyComponent() {
  const result = useDocyrusAgentMemoryCandidates(...);
}
```

## API Reference

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `{` | `—` | `—` | — |

---

# useDocyrusAgentProjects
URL: /docs/web/hooks/use-docyrus-agent-projects

useDocyrusAgentProjects hook.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-docyrus-agent-projects
```

## Usage

```tsx
import { useDocyrusAgentProjects } from '@docyrus/ui/library/hooks/use-docyrus-agent-projects';

function MyComponent() {
  const result = useDocyrusAgentProjects(...);
}
```

## API Reference

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `{` | `—` | `—` | — |

---

# useDocyrusAgentThreads
URL: /docs/web/hooks/use-docyrus-agent-threads

useDocyrusAgentThreads hook.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-docyrus-agent-threads
```

## Usage

```tsx
import { useDocyrusAgentThreads } from '@docyrus/ui/library/hooks/use-docyrus-agent-threads';

function MyComponent() {
  const result = useDocyrusAgentThreads(...);
}
```

## API Reference

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `{` | `—` | `—` | — |

---

# useDocyrusCalendar
URL: /docs/web/hooks/use-docyrus-calendar

Wire a Docyrus data source to a fully configured calendar with auto-detected date / title / user fields, view-aware date-range fetching, color mapping, and drag-and-drop persistence.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-docyrus-calendar
```

**Dependencies:**
- [@docyrus/app-utils](https://www.npmjs.com/package/@docyrus/app-utils)
- [@docyrus/api-client](https://www.npmjs.com/package/@docyrus/api-client)
- [@tanstack/react-query](https://tanstack.com/query/latest)

This hook is distributed as source. It expects an authenticated `RestApiClient` from `@docyrus/api-client` and a `QueryClientProvider` from `@tanstack/react-query` somewhere above your component tree.

## Overview

`useDocyrusCalendar` is the calendar-first companion to [`useDocyrusDataGrid`](/docs/web/hooks/use-docyrus-data-grid). It maps a Docyrus data source to the `Calendar` component without forcing you to hand-build the event transformation:

- loads the active Docyrus data source metadata
- auto-detects the date / end-date / title / color / description / user fields, or uses the slugs you provide
- keeps saved-view filtering, sorting, and search wiring from `useDocyrusDataGrid`
- requests only the columns the calendar actually needs
- transforms records into `IEvent` objects ready for `CalendarProvider`
- wires create / update / delete / drag-and-drop callbacks to the Docyrus REST endpoints
- optionally narrows the items query to records overlapping the calendar's visible range

The hook returns a ready-to-spread `calendarProviderProps` object so the page code stays small.

## Usage

### Minimal page

```tsx
'use client';

import { useDocyrusAuth } from '@docyrus/signin';

import {
  Calendar,
  CalendarProvider
} from '@docyrus/ui/components/calendar';
import { useDocyrusCalendar } from '@docyrus/ui/library/hooks/use-docyrus-calendar';

export function MeetingsCalendarPage() {
  const { client } = useDocyrusAuth();

  if (!client) return null;

  const calendar = useDocyrusCalendar({
    client,
    appSlug: 'base',
    dataSourceSlug: 'meeting',
    searchPlaceholder: 'Search meetings'
  });

  if (!calendar.hasDateField) {
    return <div>This data source has no date field.</div>;
  }

  return (
    <div className="space-y-4">
      {calendar.toolbar}

      
    </div>
  );
}
```

### With explicit field slugs and color mapping

```tsx
const calendar = useDocyrusCalendar({
  client,
  appSlug: 'base',
  dataSourceSlug: 'meeting',
  startDateFieldSlug: 'starts_at',
  endDateFieldSlug: 'ends_at',
  titleFieldSlug: 'subject',
  colorFieldSlug: 'meeting_type',
  descriptionFieldSlug: 'agenda',
  userFieldSlug: 'organizer',
  colorMap: {
    standup: 'blue',
    review: 'purple',
    leave: 'red',
    'all-hands': 'orange'
  },
  defaultView: 'week',
  defaultEventDurationMinutes: 30
});
```

### Visible-range filtering

When events live in a large data source, fetching every record at once is wasteful. Set `enableDateRangeFilter: true` and the hook narrows the items query to the calendar's currently visible window using an overlap test:

```tsx
const calendar = useDocyrusCalendar({
  client,
  appSlug: 'base',
  dataSourceSlug: 'meeting',
  enableDateRangeFilter: true
});

return (
  
);
```

The hook will refetch every time the user navigates the calendar (next month, switch to week view, etc.).

### Custom event builder

Use `getEvent` when the default mapping is not enough — for example to derive the color from multiple fields or to skip records that should not appear on the calendar.

```tsx
const calendar = useDocyrusCalendar
```

### Event interaction callbacks

Each callback below **replaces the built-in dialog** for that interaction. Leave it out and the calendar uses its bundled add / details / delete dialogs.

| Prop | Type | Replaces |
|------|------|----------|
| `onCreateEvent` | `(date: Date) => void` | The built-in add-event dialog. Use it to open your own form (e.g. a side sheet bound to the Docyrus form layout). |
| `onEventClick` | `(event: IEvent) => void` | The built-in event-details dialog. Look up `event.recordId` to find the underlying Docyrus row. |
| `onSlotClick` | `(start: Date, end: Date) => void` | Click handler for empty time slots in week/day view. Use it to start a "drag to create" flow. |
| `onDaySelect` | `(date: Date) => void` | Click handler on day cells (fires regardless of whether a slot or event is hit). |
| `onVisibleRangeChange` | `(range, view) => void` | Notifies on view switch / date navigation. Wire it to `setVisibleRange` to drive the date-range filter. |

### Header visibility toggles

| Prop | Default | Effect |
|------|---------|--------|
| `hideHeaderAddButton` | `false` | Hides the "Add Event" button in the header. |
| `hideCellAddButton` | `false` | Hides the "+" buttons that appear inside empty day cells. |
| `hideAddButton` | `false` | **Deprecated** — hides both header and cell add buttons. Use the two flags above instead. |
| `hideUserSelect` | `false` | Hides the user / filter dropdown in the header. |
| `hideFilter` | `false` | Hides the color filter dropdown in the header. |
| `hideSettings` | `false` | Hides the settings gear (badge style, 24h format, agenda group-by). |
| `hideEventCount` | `false` | Hides the event count badge that sits next to the date navigator. |

### Labels & placeholders

| Prop | Default | Description |
|------|---------|-------------|
| `addButtonLabel` | translated "Add Event" | Custom text for the header add button. |
| `eventCountLabel` | translated "events" | Custom unit for the count badge (e.g. `"meetings"`, `"leaves"`, `"entries"`). |
| `searchPlaceholder` | translated "Search…" | Custom placeholder for the agenda view search input. |

### View configuration

| Prop | Type | Description |
|------|------|-------------|
| `visibleViews` | `Array<TCalendarView>` | Which views to surface in the tab bar. Defaults to all five (`day`, `week`, `month`, `year`, `agenda`). Use `['week', 'month']` for a leaner board. |
| `defaultView` | `TCalendarView` | First view shown on mount. Pre-wired by the hook from `options.defaultView` (defaults to `'month'`). |
| `badge` | `'dot' \| 'colored'` | Event badge style in the month view. Defaults to `'colored'`. The user can override via the settings gear unless `hideSettings` is set. |

### Filter customization

The hook auto-derives `filterItems` from the user field. You can override the entire filter experience with these props:

| Prop | Type | Description |
|------|------|-------------|
| `filterItems` | `Array<CalendarFilterItem>` | Replace the auto-derived list (e.g. show statuses, projects, or any other dimension). Each item is `{ id, label, image? }`. |
| `onFilterChange` | `(id: string) => void` | Called when the user picks a filter item — wire it to your own data-source query filter. |
| `renderFilterSelect` | `(context) => ReactNode` | Render prop to replace the filter dropdown entirely with custom UI. |

### Custom rendering

| Prop | Type | Description |
|------|------|-------------|
| `sidebarContent` | `ReactNode` | Custom content rendered alongside the calendar body (e.g. a list of upcoming events, mini month, or filter chips). |
| `renderEventBadge` | `(event, defaultBadge) => ReactNode` | Replace the badge rendered for events in the month view. The second argument is the default node so you can wrap it. |

### Settings the user controls

These live in the settings gear and persist to `localStorage` under the key `calendar-settings`. They are not part of `CalendarProvider`'s prop API — show or hide the gear with `hideSettings` to control whether the user can change them.

| Setting | Values | Default |
|---------|--------|---------|
| Badge style | `'dot' \| 'colored'` | `'colored'` |
| Time format | 12h / 24h | 24h |
| Agenda group-by | `'date' \| 'color'` | `'date'` |

## How the query is built

Internally the hook reuses the saved-view state from `useDocyrusDataGrid`, then creates its own items query with a stronger `columns` list.

That means a user can save a view that hides the title or date field, but the hook will still request:

- `id`
- the resolved start date field
- the resolved end date field (when present)
- the resolved title field
- the resolved color field (when present)
- the resolved description field (when present)
- the resolved user field (when present)

So events keep rendering correctly while the rest of the data-view behavior still follows the active Docyrus view.

## Field resolution

### Start date field

Resolution order:

1. `startDateFieldSlug`
2. first field with `type === 'field-date'` or `'field-dateTime'`

If no start date field can be resolved, the hook returns `hasDateField: false` and renders no events.

### End date field

Resolution order:

1. `endDateFieldSlug`
2. first matching slug from: `end_date`, `end_time`, `end_datetime`, `finish_date`, `due_date`, `deadline`, `ends_at`, `ended_at` (excluding the start field)
3. first date / dateTime field different from the start field

When no end date field is available, the hook falls back to `defaultEventDurationMinutes` (60 minutes by default) to compute each event's end.

### Title field

Resolution order:

1. `titleFieldSlug`
2. first matching slug from: `name`, `title`, `label`, `subject`, `display_name`, `displayName`, `commercial_title`, `short_name`

If no title can be resolved, events fall back to `Event <index>`.

### Color field

Resolution order:

1. `colorFieldSlug`
2. field whose slug is `color` or `colour`

### Description field

Resolution order:

1. `descriptionFieldSlug`
2. first matching slug from: `description`, `notes`, `content`, `details`, `body`, `summary` (excluding the title field)

### User field

Resolution order:

1. `userFieldSlug`
2. first field with `type === 'field-userSelect'` or `'field-userMultiSelect'`
3. field whose slug is `record_owner`

User values shape `users[]` (unique list used by the calendar's filter dropdown) and the `filterItems[]` array that powers the header filter.

## Color resolution

Each record's color is normalized through this pipeline:

1. Read the raw value from `colorField` (string, enum option name, or object with a `name` / `label` / `title` / `value` string property).
2. Lower-case and trim the value.
3. Look up the value in `colorMap` (both original casing and lower-cased keys are tried).
4. If the value is already one of `'blue' | 'green' | 'red' | 'yellow' | 'purple' | 'orange'`, use it as-is.
5. Otherwise default to `'blue'`.

This means a `field-select` whose option names are `Standup`, `Review`, `Leave` etc. can be mapped to event colors with a small map:

```tsx
colorMap: {
  standup: 'blue',
  review: 'purple',
  leave: 'red'
}
```

## Persistence (CRUD wiring)

`calendarProviderProps` plugs the calendar's lifecycle events into the Docyrus REST endpoints (or your custom `collection` adapter when provided):

| Calendar action | Wired to | Effect |
|------|----------|--------|
| Create event in the UI | `onEventCreate` | `PATCH /items/:id` with the new start / end on the matching record (events are created through the UI from existing records — use the explicit `createRecord` helper to create a brand-new row). |
| Edit event details | `onEventUpdate` | `PATCH /items/:id` with the patched start / end date fields. |
| Delete event | `onEventDelete` | `DELETE /items/:id`. |
| Drag-and-drop | `onEventDrop` | `PATCH /items/:id` with new start / end. |

If you need to create a new Docyrus record from the calendar (for example from an "Add event" toolbar button), call the exposed `createRecord(startDate, endDate, extraValues?)` helper. It posts to the items endpoint (or your `collection.create`) and reloads the calendar.

## Loading lifecycle

The hook exposes three loading-related fields that map to different UX needs:

| Field | Use it for |
|------|-------|
| `isLoading` | `true` while either the metadata or the items query is still running for the first time. Combine with `hasLoadedOnce` to render a full-screen skeleton only on first mount. |
| `isFetching` | `true` while a background refetch is in flight. Good for small spinners on the toolbar. |
| `hasLoadedOnce` | Flips to `true` after the first successful items fetch and stays true. Use it to keep `<Calendar>` mounted on subsequent refetches — passing `isLoading` directly would unmount the provider and reset its internal `selectedDate` / `view` state. |

## API Reference

### `useDocyrusCalendar(options)`

The hook accepts every `useDocyrusDataGrid` option except `data`, `enableItemsQuery`, `showSelectColumn`, `enableRowMarkers`, and `collection` (replaced by the `DocyrusCalendarCollection` shape). It also accepts the options below.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `client` | `RestApiClient` | — | Authenticated Docyrus API client. |
| `appSlug` | `string` | — | Target Docyrus app slug (e.g. `'base'`). |
| `dataSourceSlug` | `string` | — | Target data source slug. |
| `collection` | `DocyrusCalendarCollection<TData>` | — | Optional collection adapter (e.g. typed `@docyrus/tanstack-db-generator` output). When provided, the hook calls `collection.list / create / update / delete` instead of hitting REST endpoints directly. |
| `startDateFieldSlug` | `string` | auto | Slug of the date / dateTime field used as event start. Auto-detected when omitted. |
| `endDateFieldSlug` | `string` | auto | Slug of the date / dateTime field used as event end. Auto-detected when omitted; falls back to `defaultEventDurationMinutes` when no end field is found. |
| `titleFieldSlug` | `string` | auto | Slug of the field used as event title. Auto-detected when omitted. |
| `colorFieldSlug` | `string` | auto | Slug of the field used to derive the event color. Auto-detected when omitted. |
| `descriptionFieldSlug` | `string` | auto | Slug of the field used as event description. Auto-detected when omitted. |
| `userFieldSlug` | `string` | auto | Slug of the user / userSelect field. Drives the calendar's user filter dropdown. Auto-detected when omitted. |
| `colorMap` | `Record<string, TEventColor>` | — | Map of raw color / enum-option values to `TEventColor`. Example: `{ 'Meeting': 'blue', 'Leave': 'red' }`. |
| `defaultEventDurationMinutes` | `number` | `60` | Fallback event length used when the end date field is absent or empty. |
| `getEvent` | `(item, context) => DocyrusCalendarEvent \| null` | — | Override event construction. Return `null` to skip a record entirely. |
| `defaultView` | `TCalendarView` | `'month'` | Default calendar view. One of `'day' \| 'week' \| 'month' \| 'year' \| 'agenda'`. |
| `enableDateRangeFilter` | `boolean` | `false` | When `true`, the items query is narrowed to records overlapping the calendar's visible range. Pair with `setVisibleRange` on `CalendarProvider.onVisibleRangeChange` to drive it. |
| `staleTime` | `number` | `30000` | TanStack Query `staleTime` for the items query (ms). |
| `enableGroupMenu` | `boolean` | `false` | Forwarded to the underlying data-grid toolbar. Off by default for calendar pages. |
| `enableRowHeightMenu` | `boolean` | `false` | Forwarded to the underlying data-grid toolbar. |
| `enableDisplayMenu` | `boolean` | `false` | Forwarded to the underlying data-grid toolbar. |
| `onReload` | `() => void` | — | Forwarded to the underlying data-grid hook. |

### Return value

| Property | Type | Description |
|----------|------|-------------|
| `calendarProviderProps` | `Omit<CalendarProviderProps, 'children'>` | Ready-to-spread props for `<CalendarProvider>`. Wires only `events`, `users`, `defaultView`, `filterItems`, and the CRUD callbacks (`onEventCreate`, `onEventUpdate`, `onEventDelete`, `onEventDrop`). All other `CalendarProvider` props (`onEventClick`, `onSlotClick`, `onDaySelect`, `visibleViews`, hide-flags, custom labels, custom renderers…) are passthroughs you add alongside — see [Customizing the calendar UI](#customizing-the-calendar-ui). |
| `events` | `DocyrusCalendarEvent<TData>[]` | Transformed events ready for the calendar. Each event carries its original `recordId` and raw `item`. |
| `users` | `IUser[]` | Unique users extracted from the user field. Drives the filter dropdown. |
| `filterItems` | `CalendarFilterItem[]` | Generic filter items derived from `users` — already wired into `calendarProviderProps.filterItems`. |
| `items` | `TData[]` | All raw records returned by the items query. |
| `startDateField` | `DataSourceField \| null` | Resolved start date field definition. |
| `endDateField` | `DataSourceField \| null` | Resolved end date field definition (may be `null` when none exists). |
| `titleField` | `DataSourceField \| null` | Resolved title field definition. |
| `colorField` | `DataSourceField \| null` | Resolved color field definition. |
| `descriptionField` | `DataSourceField \| null` | Resolved description field definition. |
| `userField` | `DataSourceField \| null` | Resolved user field definition. |
| `hasDateField` | `boolean` | `true` when a usable start date field was resolved. Use it to render a fallback when the data source is incompatible. |
| `createRecord` | `(startDate, endDate, extraValues?) => Promise<void>` | Persist a brand-new event to Docyrus. Use from custom "Add event" buttons. |
| `updateRecord` | `(recordId, data) => Promise<void>` | Patch an existing record by its UUID. |
| `deleteRecord` | `(recordId) => Promise<void>` | Delete a record by its UUID. |
| `moveRecord` | `(recordId, newStart, newEnd) => Promise<void>` | Move an event (drag-and-drop). Patches the start / end date fields. |
| `visibleRange` | `{ start: Date; end: Date } \| null` | Currently active visible range — drives the date-range filter when enabled. |
| `setVisibleRange` | `(range \| null) => void` | Setter wired to `CalendarProvider.onVisibleRangeChange`. |
| `requestedColumns` | `string` | Final comma-separated columns string sent to the items endpoint. |
| `resolvedListParams` | `DocyrusDataGridListParams` | Full query payload (filters, orderBy, limit, offset, columns) passed to the Docyrus items endpoint. |
| `toolbar` | `ReactNode` | Prebuilt Docyrus data-view toolbar from `useDocyrusDataGrid`. |
| `table` | `Table<TData>` | Underlying TanStack table used by the toolbar and saved-view editor. |
| `views` | `SavedDataGridView[]` | Saved views from `useDocyrusDataGrid`. |
| `fields` | `DataSourceField[]` | Full field list from `useDocyrusDataGrid`. |
| `dataSource` | `DataSourceMetadata \| null` | Resolved Docyrus data source metadata. |
| `activeViewId` | `string \| null` | Currently active saved view id. |
| `setActiveViewId` | `(id) => void` | Switch the active saved view. |
| `isLoading` | `boolean` | `true` until both metadata and items have finished their first fetch. |
| `isFetching` | `boolean` | `true` while a refetch is in flight (initial or otherwise). |
| `hasLoadedOnce` | `boolean` | `true` after the first successful items fetch — use to keep `<Calendar>` mounted across refetches. |
| `error` | `Error \| null` | First query error, if any. |
| `reload` | `() => void` | Refetches the metadata and the items query. |

## Type Exports

| Type | Description |
|------|-------------|
| `DocyrusCalendarEvent<TData>` | Calendar event extended with `recordId` and raw `item`. |
| `DocyrusCalendarCollection<TData>` | Shape of an optional collection adapter (`list / create / update / delete`). |
| `DocyrusCalendarEventBuilderContext<TData>` | Context passed to a custom `getEvent` builder (resolved fields + item + index). |
| `UseDocyrusCalendarOptions<TData>` | Hook option shape (extends `UseDocyrusDataGridOptions`). |
| `UseDocyrusCalendarResult<TData>` | Hook return shape. |
| `IEvent` | Calendar event shape (re-exported from `@ui/components/calendar`). |
| `IUser` | Calendar user shape (re-exported from `@ui/components/calendar`). |
| `TCalendarView` | `'day' \| 'week' \| 'month' \| 'year' \| 'agenda'`. |
| `TEventColor` | `'blue' \| 'green' \| 'red' \| 'yellow' \| 'purple' \| 'orange'`. |
| `CalendarFilterItem` | `{ id, label, image? }` filter dropdown item. |

---

# useDocyrusContactActivity
URL: /docs/web/hooks/use-docyrus-contact-activity

Merge a Docyrus record's audit log, threaded comments, related events, tasks, and status updates into one timeline for <ContactActivityPanel />, plus comment and status mutations.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-docyrus-contact-activity
```

**Dependencies:**
- [@docyrus/api-client](https://www.npmjs.com/package/@docyrus/api-client)
- [@tanstack/react-query](https://tanstack.com/query/latest)

The hook needs an authenticated `RestApiClient` from `@docyrus/api-client` and a `QueryClientProvider`
above your component tree. Read endpoints require the relevant `DS.Read.*` scopes; comment writes and
status updates require `DS.ReadWrite.*` on the record's data source.

## Overview

`useDocyrusContactActivity` is the Docyrus-backed engine behind [`ContactActivityPanel`](/docs/web/components/contact-activity-panel).
It runs up to **five** React Query sources scoped to one record and merges them into a single
date-sorted `ContactActivity[]` feed:

- **Audit** — `GET …/items/:id/activities`: CRUD + file trace. Comment operations (`INSERT_COMMENT` / `UPDATE_COMMENT` / `DELETE_COMMENT`) are **filtered out** here because they arrive threaded from the comments source (hybrid, dedup-safe).
- **Comments** — `GET …/items/:id/comments`: the flat comment list, rebuilt into a `parent_id` tree (arbitrary depth). Top-level comments become timeline entries; `onLoadReplies` returns all descendants.
- **Events** — related `base/event` rows (needs `relationSlug` / `eventRelationSlug`), classified `call` vs `meeting` from the `calendar` event-type name.
- **Tasks** — related `base/task` rows (needs `relationSlug` / `taskRelationSlug`).
- **Status updates** — `base/activity` rows where `status_update_record_id = recordId`, surfaced as first-class `status_update` entries.

A status change goes through the two-call `updateStatus` flow — it PATCHes the record (which emits a
generic audit `UPDATE`) **and** logs a `status_update` activity. The merge suppresses the audit
`record_update` row that coincides with a status update (short time window) so a single change surfaces
once, not twice.

The primary output is `panelProps` — spread it straight onto ``. The panel
stays presentational; the hook owns all I/O.

## Usage

```tsx
import { useDocyrusContactActivity } from '@docyrus/ui/library/hooks/use-docyrus-contact-activity';
import { ContactActivityPanel } from '@docyrus/ui/components/contact-activity-panel';

function RecordTimeline({ client, recordId }) {
  const activity = useDocyrusContactActivity({
    client,
    appSlug: 'base',
    dataSourceSlug: 'contact',
    recordId,
    // Per-tenant back-relation slug on base/event + base/task — required for those sources.
    relationSlug: 'contact',
    currentUserId: myUserId
  });

  return ;
}
```

## Options

`useDocyrusContactActivity(options: UseDocyrusContactActivityOptions)`

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `client` | `ContactActivityClient` | — | Authenticated REST client (`RestApiClient` satisfies it). |
| `appSlug` | `string` | — | App slug of the owning record. |
| `dataSourceSlug` | `string` | — | Data source slug of the owning record. |
| `recordId` | `string` | — | Owning record id. |
| `relationSlug` | `string` | — | Back-relation slug on `base/event` + `base/task` pointing at this record (per-tenant, e.g. `contact`). Required to include the events / tasks sources. |
| `eventRelationSlug` | `string` | `relationSlug` | Override the event back-relation slug. |
| `taskRelationSlug` | `string` | `relationSlug` | Override the task back-relation slug. |
| `sources` | `ContactActivitySources` | all `true` | Toggle which sources merge (`audit` / `comments` / `events` / `tasks` / `statusUpdates`). |
| `eventAppSlug` / `eventDataSourceSlug` | `string` | `base` / `event` | Events source override. |
| `taskAppSlug` / `taskDataSourceSlug` | `string` | `base` / `task` | Tasks source override. |
| `activityAppSlug` / `activityDataSourceSlug` | `string` | `base` / `activity` | Status-activity source override. |
| `users` | `ChatUser[]` | — | Consumer-supplied users (preferred). Falls back to `/v1/users` when omitted. |
| `currentUserId` | `string` | — | Flags the viewer's own activities. |
| `activityTypes` | `ActivityType[]` | — | Restrict the panel's type-filter toggles. |
| `eventTypeNames` | `EventTypeNameHints` | call: `['call','phone']`, meeting: `['meeting','visit','demo']` | Case-insensitive name hints for call vs meeting classification. |
| `classifyEvent` | `(event) => 'call' \| 'meeting'` | — | Custom classifier (wins over `eventTypeNames`). |
| `limit` | `number` | `100` | Per-source page size (the API caps at 100 for OAuth tokens). |
| `enabled` | `boolean` | `true` once `recordId` is present | Gate every query. |

## Returns

`UseDocyrusContactActivityResult`

| Field | Type | Description |
|-------|------|-------------|
| `activities` | `ContactActivity[]` | Merged, date-sorted timeline. |
| `users` | `ChatUser[]` | Resolved users. |
| `currentUser` | `ChatUser \| undefined` | Resolved current user. |
| `panelProps` | `ContactActivityPanelData` | Spread onto ``. |
| `isLoading` | `boolean` | Any read source loading. |
| `error` | `Error \| null` | First read-source error. |
| `isMutating` | `boolean` | Any mutation pending. |
| `mutationError` | `Error \| null` | First mutation error. |
| `refetch` | `() => Promise<unknown>` | Invalidate the record-scoped keys. |
| `createComment` | `(payload: CreatePostPayload) => Promise<void>` | Post a comment (threaded reply via `parent_id`). |
| `deleteComment` | `(commentId: string) => Promise<void>` | Delete a comment by id. |
| `updateStatus` | `(input: UpdateStatusInput) => Promise<void>` | Two-call status change (see below). |
| `isUpdatingStatus` | `boolean` | Status mutation pending. |

## Two-call status update

`updateStatus` performs the record PATCH **then** logs the status-update activity:

```tsx
await activity.updateStatus({
  statusFieldSlug: 'status',
  value: enumId,
  secondaryValue,      // → __status_secondary  (only sent when provided)
  description,         // → __status_description
  followupDate         // → __status_followup_date
});
```

Companion fields (`__<slug>_*`) are only sent when provided, so plain `field-select` status fields
(which have no companion columns) don't 400. If the record PATCH succeeds but logging fails, the promise
rejects with a **partial-failure** error (`error.partial === true`) — the record *did* change, and the
timeline still invalidates (`onSettled`) so the change is reflected. Surface this to the user so a retry
isn't mistaken for a no-op.

## Notes

- **Users are shared.** All Docyrus activity hooks fetch `/v1/users` under one query key (`['docyrus-users', limit]`) and the same canonical shape, so React Query dedupes to a single request across this hook, `useDocyrusCreateTask`, and `useDocyrusEventCreate`.
- **Rate-limit aware.** Read sources carry a short `staleTime` so tab switches / refocus don't refire the 5-source fan-out against the tight API rate limit.
- **Per-tenant relations.** On some tenants `base/event ↔ contact` is many-to-many with no scalar column — pass the correct scalar back-relation via `eventRelationSlug` / `taskRelationSlug`, or omit them to leave those sources off.

## Type Exports

| Type | Description |
|------|-------------|
| `UseDocyrusContactActivityOptions` | Hook options. |
| `UseDocyrusContactActivityResult` | Hook return. |
| `ContactActivityPanelData` | The `panelProps` bag. |
| `ContactActivitySources` | Per-source toggles. |
| `EventTypeNameHints` | Call / meeting classification hints. |
| `UpdateStatusInput` | `updateStatus` payload. |
| `ContactActivityClient` | Minimal REST surface the hook needs. |

---

# useDocyrusContactChannels
URL: /docs/web/hooks/use-docyrus-contact-channels

useDocyrusContactChannels hook.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-docyrus-contact-channels
```

## Usage

```tsx
import { useDocyrusContactChannels } from '@docyrus/ui/library/hooks/use-docyrus-contact-channels';

function MyComponent() {
  const result = useDocyrusContactChannels(...);
}
```

## API Reference

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `options` | `UseDocyrusContactChannelsOptions` | `—` | — |

**Returns:** `UseDocyrusContactChannelsResult`

---

# useDocyrusDataExport
URL: /docs/web/hooks/use-docyrus-data-export

Server-side export for Docyrus data sources — POSTs a query payload to the export edge function and streams the result file straight to the browser.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-docyrus-data-export
```

**Dependencies:**
- [@docyrus/api-client](https://www.npmjs.com/package/@docyrus/api-client)
- [react-querybuilder](https://www.npmjs.com/package/react-querybuilder)

This hook is distributed as source. It needs an authenticated `RestApiClient` from `@docyrus/api-client` somewhere above your component tree.

## Overview

`useDocyrusDataExport` wraps the Docyrus server-side export endpoint (`POST /v1/edge/run/query-export`). The server applies the same filters, search, and column projection used by the items query and streams back a binary file (xlsx by default). `RestApiClient.download()` then writes it to the user's browser using the `Content-Disposition` filename.

Use this hook when:

- The export needs to cover more rows than the grid currently has loaded.
- You want the canonical, server-authored xlsx (with formatting, formula columns, lookups resolved).
- You want filters, search, and column visibility to round-trip exactly as the user sees them.

For exports of an already-loaded array of rows (no server round-trip, four formats including JSON and Markdown), use [`useDataExport`](/docs/web/hooks/use-data-export) instead.

| Hook | Where serialization happens | Formats | Best for |
|------|-----------------------------|---------|----------|
| [`useDataExport`](/docs/web/hooks/use-data-export) | Client | csv, json, markdown, xlsx | In-memory rows, custom columns, selection-only exports |
| `useDocyrusDataExport` | Server (edge function) | xlsx (default), csv | Full data source, large exports, canonical Docyrus output |

## Usage

### Basic example

```tsx
'use client';

import { useDocyrusAuth } from '@docyrus/signin';

import { Button } from '@docyrus/ui/primitives/ui/button';
import { useDocyrusDataExport } from '@docyrus/ui/library/hooks/use-docyrus-data-export';

export function ExportContactsButton({ dataSourceId }: { dataSourceId: string }) {
  const { client } = useDocyrusAuth();

  if (!client) return null;

  const { exportData, isExporting, error } = useDocyrusDataExport({ client });

  return (
    <>
      
      {error ? <p className="text-destructive">{error.message}</p> : null}
    </>
  );
}
```

With no extra payload fields, the server defaults apply: every exportable column, no filters, the hook's `defaultLimit` (10 000 rows), and xlsx output.

### Mirroring the visible grid

Pair the hook with [`useDocyrusDataGrid`](/docs/web/hooks/use-docyrus-data-grid) so the export reflects exactly what the user sees — same filters, same search, same column visibility:

```tsx
const grid = useDocyrusDataGrid({ client, appSlug, dataSourceSlug });
const { exportData, isExporting } = useDocyrusDataExport({ client });

async function handleExport() {
  await exportData({
    dataSourceId: grid.dataSourceId,
    columns: grid.visibleColumnSlugs, // visible-only, in display order
    filters: grid.filterGroup,
    filterKeyword: grid.search,
    limit: 50000
  });
}
```

### Free-form extras (server-controlled fields)

Any unknown keys on the payload are forwarded verbatim. Use this for tenant-specific fields the server understands without changing the hook:

```tsx
await exportData({
  dataSourceId,
  columns: ['name', 'email', 'createdOn'],
  format: 'csv',
  // forwarded as-is
  timezone: 'Europe/Istanbul',
  locale: 'tr-TR'
});
```

### Override the endpoint

```tsx
const { exportData } = useDocyrusDataExport({
  client,
  endpoint: '/v1/edge/run/tenant-export',
  defaultLimit: 25000
});
```

Override only when a deployment exposes the export edge function under a non-standard route.

## API Reference

### Parameters — `UseDocyrusDataExportOptions`

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `client` | `RestApiClient` | — | Authenticated REST client used to POST the export request. **Required.** |
| `defaultLimit` | `number` | `10000` | Default row cap when `payload.limit` is omitted. |
| `endpoint` | `string` | `'/v1/edge/run/query-export'` | Endpoint path. Override only when a deployment exposes the export edge function under a different route. |

### `exportData(payload)` — `DocyrusDataExportPayload`

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `dataSourceId` | `string` | — | Target data source ID — required by the edge query. **Required.** |
| `columns` | `'*' \| ReadonlyArray<string>` | `'*'` | Columns to include. Pass `'*'` (or omit) to let the server default to every exportable field, or an array of field slugs to project a specific subset. |
| `filters` | `RuleGroupType \| null` | `null` | Filter group applied to the underlying items query. Pass the same shape used by the items endpoint (combinator + rules). Empty rule groups are normalised to `null` server-side. |
| `filterKeyword` | `string` | — | Free-text keyword search forwarded to the server. Omitted from the request body when empty. |
| `limit` | `number` | `defaultLimit` | Maximum number of rows to export. Falls back to `defaultLimit` when omitted or non-positive. |
| `format` | `'xlsx' \| 'csv'` | `'xlsx'` | Optional override for the export format. Final format is server-controlled. |
| `[key: string]` | `unknown` | — | Free-form extras forwarded verbatim to the endpoint. |

### Return Value — `UseDocyrusDataExportResult`

| Property | Type | Description |
|----------|------|-------------|
| `exportData` | `(payload: DocyrusDataExportPayload) => Promise<void>` | Trigger a server-side export. Resolves once the file has been streamed to the browser; rejects with the original error (which is also stored in `error`). |
| `isExporting` | `boolean` | `true` while a request is in flight. Use it to disable the trigger button. |
| `error` | `Error \| null` | Last error thrown by `exportData`. Cleared on every new attempt. |

### Type Exports

| Type | Description |
|------|-------------|
| `UseDocyrusDataExportOptions` | Hook input (`client`, `defaultLimit`, `endpoint`). |
| `UseDocyrusDataExportResult` | Hook return value (`exportData`, `isExporting`, `error`). |
| `DocyrusDataExportPayload` | Body shape POSTed to the export endpoint. Includes the index signature for forwarding extras. |

## Backend connection

| Method | Endpoint | Purpose |
|--------|----------|---------|
| `POST` | `/v1/edge/run/query-export` | Server reads the payload, applies filters/search/column projection, and streams back a binary file (xlsx by default). The browser saves it using the `Content-Disposition` filename. |

The endpoint can be overridden via the `endpoint` option when a deployment exposes the export edge function under a different route.

## Notes

- Empty filter groups (`{ combinator: 'and', rules: [] }`) are normalised to `null` before the request leaves the client so the server query plan stays clean.
- `client.download()` handles the binary response: it reads the `Content-Disposition` filename, builds a `Blob`, and triggers the download via a temporary `<a download>` element.
- Errors are stored on `error` and re-thrown from `exportData()` so callers can `await` and catch (or rely on the state).
- This hook does **not** project rows or own a column UI — pair it with [`useDocyrusDataGrid`](/docs/web/hooks/use-docyrus-data-grid) (or any source of `dataSourceId` + filter group) to drive the payload.

---

# useDocyrusDataGallery
URL: /docs/web/hooks/use-docyrus-data-gallery

One-call wiring of a Docyrus data source to a fully configured DataGallery + toolbar (DataGridViewSelect, search, filters, sort, group, gallery display menu, card config menu) — including row fetching, saved views, pivot filters, and automatic card field detection.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-docyrus-data-gallery
```

**Dependencies:**
- [@docyrus/app-utils](https://www.npmjs.com/package/@docyrus/app-utils)
- [@docyrus/api-client](https://www.npmjs.com/package/@docyrus/api-client)
- [@tanstack/react-query](https://tanstack.com/query/latest)
- [@tanstack/react-table](https://tanstack.com/table/latest)
- [@tanstack/react-virtual](https://tanstack.com/virtual/latest)
- [react-querybuilder](https://react-querybuilder.js.org)

This hook is distributed as source. It requires an authenticated `RestApiClient` from `@docyrus/api-client` and a `QueryClientProvider` from `@tanstack/react-query` somewhere above your component tree.

## Overview

`useDocyrusDataGallery` composes [`useDocyrusDataGrid`](/docs/web/hooks/use-docyrus-data-grid) and layers a gallery-specific presentation on top. The result is a ready-to-render setup with:

- **Backend wiring** — data source schema fetch, items query, saved views, side filters, pivot filters (all from the data-grid hook).
- **Tenant-aware formatting** — inherited from the composed grid hook. Date / datetime / number cells pick up the formatters installed by [`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `collection` | `DocyrusDataGridCollection<TData>` | — | TanStack DB collection. The hook calls `collection.list(listParams)` to fetch rows. |
| `data` | `Array<TData>` | — | Pre-resolved rows. Skips the internal items query. |
| `appSlug` | `string` | — | Required for data source schema and view fetches. |
| `dataSourceSlug` | `string` | — | Required for data source schema and view fetches. |
| `listParams` | `DocyrusDataGridListParams` | — | Extra query params merged on top of view-derived ones. |
| `pivotFilters` | `ReadonlyArray<DocyrusPivotFilterGroupField>` | — | Render pivot strips above the toolbar. |
| `enableSideFilters` | `boolean` | `false` | Enable the side-panel filter rail. |
| `sideFiltersConfig` | `DocyrusDataGridSideFiltersConfig<TData>` | — | Side panel config. |
| `cardConfig` | `DataGalleryCardConfigSerializable` | auto-detected | Initial card field bindings. |
| `onCardConfigChange` | `(config) => void` | — | Fires whenever the card config changes. |
| `displayConfig` | `Partial<DataGalleryDisplayConfig>` | — | Initial display config. |
| `onDisplayConfigChange` | `(config) => void` | — | Fires whenever the display config changes. |
| `enableSearchInput` | `boolean` | `true` | Toggle the toolbar search input. |
| `enableFilterMenu` | `boolean` | `true` | Toggle the filter menu. |
| `enableSortMenu` | `boolean` | `true` | Toggle the sort menu. |
| `enableGroupMenu` | `boolean` | `true` | Toggle the group menu. |
| `enableDisplayMenu` | `boolean` | `true` | Toggle the gallery display menu. |
| `enableCardConfigMenu` | `boolean` | `true` | Toggle the card config menu. |
| `enableViewSelect` | `boolean` | `true` | Toggle the view picker. |
| `enableReloadButton` | `boolean` | `true` | Toggle the reload button. |
| `viewSelectVariant` | `'horizontal-tabs' \| 'dropdown' \| 'vertical-tabs'` | `'horizontal-tabs'` | View picker variant. |
| `onAdd` | `() => void` | — | When supplied, renders a primary "Add" button on the toolbar's right edge. |
| `addLabel` | `string` | `'Add'` | Label for the add button. |
| `minCardWidth` | `number` | `260` | Min card width for the `'flex'` column count auto-fit. |
| `estimatedCardHeight` | `number` | `360` | Initial virtualizer estimate — `measureElement` replaces per-row after first paint. |
| `excludeFieldSlugs` | `ReadonlyArray<string>` | — | Drop stale field slugs from the data source schema before downstream consumers see it. See the Stale Schema Escape Hatch section. |
| `overscan` | `number` | `3` | Virtualizer overscan rows. |
| `users` | `ReadonlyArray<CellUserOption>` | — | Tenant users for `field-userSelect` cells. Forwarded to the grid. |
| `formatDate`, `formatDateTime`, `formatNumber` | functions | — | Tenant-aware formatters. Forwarded to the grid. |
| `bulkActions` | `false \| ReadonlyArray<DocyrusDataGridBulkAction>` | `['update', 'delete', 'export']` | Action bar bulk actions. |
| `extraBulkActions` | `Array<DataGalleryAction<TData>>` | — | Extra row-selection actions. |

### Returns

| Key | Type | Description |
|-----|------|-------------|
| `galleryProps` | `DocyrusDataGalleryProps<TData>` | Spread onto `<DataGallery>`. Includes `table`, `displayConfig`, `virtualizer`, `containerRef`, etc. |
| `toolbar` | `ReactNode` | Pre-wired gallery toolbar element. Render above `<DataGallery>`. |
| `cardConfig` | `DataGalleryCardConfigSerializable` | Current card field bindings. |
| `setCardConfig` | `(updater) => void` | Card config setter. |
| `displayConfig` | `DataGalleryDisplayConfig` | Current display config. |
| `setDisplayConfig` | `(updater) => void` | Display config setter. |
| `searchInput` | `string` | Immediate search input value. |
| `searchKeyword` | `string` | Debounced search keyword sent to the backend. |
| `setSearchInput` | `(value) => void` | Search input setter. |
| `items` | `Array<TData>` | Resolved rows. |
| `fields` | `Array<FullField>` | Data source fields (filter-friendly shape). |
| `dataSource` | `DataSource \| undefined` | Resolved data source metadata. |
| `activeViewId` | `string` | Current saved view id. |
| `setActiveViewId` | `(viewId) => void` | View setter. |
| `views` | `Array<SavedDataGridView>` | Available saved views. |
| `pivotFilterRule` | `Array<PivotFilterRule> \| null` | Combined pivot filter rule. |
| `sideFilters` | `ReactNode` | Side panel element (or `null`). |
| `sideFiltersExpanded`, `setSideFiltersExpanded`, `sideFiltersQuery` | — | Side filter wiring. |
| `resolvedListParams` | `DocyrusDataGridListParams` | The list params actually sent to the backend. |
| `pagingMode` | `'standard' \| 'virtual-scroll' \| undefined` | Resolved paging mode for the active view. |
| `reload` | `() => void` | Refetch metadata + items. |
| `refetch` | `() => void` | Alias of `reload`. |
| `isLoading` | `boolean` | Initial load indicator. |
| `error` | `Error \| null` | Schema or items error. |
| `gridViewSelectProps` | `Pick<DataGridViewSelectProps, ManagedProps>` | View-select props with the hook's `onViewSave` / `onViewCreate` wrappers already attached — saving a view from a custom toolbar still persists gallery state. |
| `pivotFiltersStrip` | `ReactNode` | The pivot strip element (or `null` when no `pivotFilters` configured) — render before the toolbar when composing a custom layout. |

## Helper Exports

### `detectCardConfigFromFields(fields)`

Build a `DataGalleryCardConfigSerializable` from a `DataSourceField[]`. Used internally; exported so consumers can re-run the detection after schema changes or build their own card configs.

```tsx
import { detectCardConfigFromFields } from '@/hooks/use-docyrus-data-gallery';

const cardConfig = detectCardConfigFromFields(dataSource.fields);
```

## Related

- [`DataGallery`](/docs/web/components/data-gallery) — the standalone presentation component.
- [`useDocyrusDataGrid`](/docs/web/hooks/use-docyrus-data-grid) — table-mode sibling; gallery composes it internally.
- [`useDocyrusDataViewSelect`](/docs/web/hooks/use-docyrus-data-view-select) — shared saved view storage.

---

# useDocyrusDataGrid
URL: /docs/web/hooks/use-docyrus-data-grid

One-call wiring of a Docyrus data source to a fully configured DataGrid + toolbar (DataGridViewSelect, search, filters, group, sort, row height, display) — including row fetching with view-derived query parameters.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-docyrus-data-grid
```

**Dependencies:**
- [@docyrus/app-utils](https://www.npmjs.com/package/@docyrus/app-utils)
- [@docyrus/api-client](https://www.npmjs.com/package/@docyrus/api-client)
- [@tanstack/react-query](https://tanstack.com/query/latest)
- [@tanstack/react-table](https://tanstack.com/table/latest)
- [react-querybuilder](https://react-querybuilder.js.org)

This hook is distributed as source. It requires an authenticated `RestApiClient` from `@docyrus/api-client` and a `QueryClientProvider` from `@tanstack/react-query` somewhere above your component tree.

## Overview

`useDocyrusDataGrid` is the one-call entry point that wires a Docyrus data source to `

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `data` | `Array

## Translating enum options

`dynamicLabelTranslator` only touches **field-level** labels (headers). To translate the option labels **inside** enum-backed cells and filter dropdowns (`field-select`, `field-status`, `field-radioGroup`, `field-enum`, `field-multiSelect`, `field-tagSelect`), pass `dynamicEnumOptionTranslator`.

Enum options carry a stable, language-independent `slug` (the stored value) plus a display `name`. Key your translation by `enums.<field.slug>.<option.slug>` and translate only `name` — `slug`, `color`, and `icon` are preserved automatically:

```tsx
const { t } = useTranslation();

useDocyrusDataGrid({
  client,
  appSlug: 'base',
  dataSourceSlug: 'task',
  dynamicEnumOptionTranslator: (option, field) =>
    t(`enums.${field.slug}.${option.slug}`, option.name)
});
```

```tsx
// Simple dictionary keyed by option slug
const statusLabels: Record<string, string> = { open: 'Açık', done: 'Tamamlandı' };

useDocyrusDataGrid({
  client,
  appSlug: 'base',
  dataSourceSlug: 'task',
  dynamicEnumOptionTranslator: (option) =>
    option.slug ? statusLabels[option.slug] ?? option.name : option.name
});
```

---

# useDocyrusDataImportWizard
URL: /docs/web/hooks/use-docyrus-data-import-wizard

One-call wiring of a Docyrus data source to the DataImportWizard — handles upload, analyse, mapping, preview, and import in a single guided flow.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-docyrus-data-import-wizard
```

**Dependencies:**
- [@docyrus/app-utils](https://www.npmjs.com/package/@docyrus/app-utils)
- [@docyrus/api-client](https://www.npmjs.com/package/@docyrus/api-client)
- [@tanstack/react-query](https://tanstack.com/query/latest)

This hook is distributed as source. It needs an authenticated `RestApiClient` from `@docyrus/api-client` and a `QueryClientProvider` from `@tanstack/react-query` somewhere above your component tree.

## Overview

`useDocyrusDataImportWizard` is the one-call entry point that wires a Docyrus data source to [`
      {wizard}
    </>
  );
}
```

### Side-by-side with `useDocyrusDataGrid`

Both hooks accept the same `client` + `appSlug` + `dataSourceSlug`. Wire `onImported` to the grid's `reload()` so a successful import refreshes the visible rows:

```tsx
const grid = useDocyrusDataGrid({ client, appSlug, dataSourceSlug });
const importer = useDocyrusDataImportWizard({
  client,
  appSlug,
  dataSourceSlug,
  fields: grid.fields,                 // skip duplicate metadata fetch
  onImported: () => grid.reload()
});

return (
  <>
    {grid.toolbar}
    
    
    {importer.wizard}
  </>
);
```

### Imperative usage (skip the dialog UI)

```tsx
const importer = useDocyrusDataImportWizard({ client, appSlug, dataSourceSlug });

async function silentImport(file: File) {
  const uploaded = await importer.uploadAsync(file);
  await importer.analyseAsync(uploaded.fileName);
  // …mutate `importer.mapping` via your own UI…
  return importer.importAsync();
}
```

## API Reference

### Parameters

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `client` | `RestApiClient` | — | Authenticated client from `@docyrus/api-client`. **Required.** |
| `appSlug` | `string` | — | Target app slug. **Required.** |
| `dataSourceSlug` | `string` | — | Target data source slug. **Required.** |
| `appId` | `string` | — | Optional multi-tenant isolation key. |
| `fields` | `Array<DocyrusFieldLike>` | — | Pre-resolved target fields. When provided, the hook skips its internal data source fetch. |
| `requiredFieldSlugs` | `Array<string>` | `[]` | Slugs that must be mapped before the user can leave the mapping step. |
| `uniqueFieldSlugs` | `Array<string>` | from analyse response | Slugs covered by unique indexes — controls upsert availability. |
| `endpoints` | `{ upload?: string; analyse?: string; import?: string }` | derived | Override the three endpoints (e.g. for tenant-specific routing). |
| `previewRowCount` | `number` | `10` | Number of rows shown in the preview step. |
| `maxFileSizeBytes` | `number` | `20 * 1024 * 1024` | Client-side size limit. |
| `acceptedExtensions` | `Array<string>` | `['xlsx','xls','csv']` | Allowed file extensions. |
| `initialMapping` | `WizardMappingMap` | — | Seed mapping that overrides auto-mapping after the first analyse. |
| `enabled` | `boolean` | `true` | When `false` the hook returns `wizard: null` (use as a feature flag). |
| `open` | `boolean` | — | Controlled open state. When omitted the hook owns the open flag. |
| `onOpenChange` | `(open: boolean) => void` | — | Fires whenever the open state changes (controlled or not). |
| `onImported` | `(result: ImportResultPayload) => void` | — | Called after a successful import. |
| `onError` | `(error: Error, phase: 'upload' \| 'analyse' \| 'import') => void` | — | Called whenever any of the three phases throws. |
| `title` / `description` | `ReactNode` | translated default | Override the wizard header copy. |

### Return Value

| Property | Type | Description |
|----------|------|-------------|
| `wizard` | `ReactElement \| null` | Render this once next to the trigger button — already wired. `null` when `enabled === false`. |
| `open` | `boolean` | Current open state of the dialog. |
| `openWizard` / `closeWizard` / `resetWizard` | `() => void` | Imperative dialog controls. |
| `step` | `ImportWizardStep` | Current step. |
| `setStep` | `(step) => void` | Move to a step programmatically. |
| `uploadAsync` | `(file: File) => Promise<UploadedFileInfo>` | POST to the upload endpoint. |
| `analyseAsync` | `(fileName: string) => Promise<AnalysedFile>` | GET the analyse endpoint. |
| `importAsync` | `() => Promise<ImportResultPayload>` | POST the import endpoint using the current mapping + options. |
| `uploadedFile` / `analysedFile` / `importResult` | `* \| null` | Latest payloads from each phase. |
| `fields` | `Array<DocyrusFieldLike>` | Resolved target fields (from `fields` prop or `useDocyrusDataViewSelect`). |
| `isUploading` / `isAnalysing` / `isImporting` | `boolean` | TanStack Query mutation pending flags. |
| `error` | `Error \| null` | First error from any of the three phases. |

## Field-Type Awareness

The wizard uses field metadata in three places:

| Surface | Mechanism |
|---------|-----------|
| **Mapping step** — per-type config (relation `reference_key`, phone country code, date format, money/phone companion column) | Direct switch on `field.type` in the dumb `<DataImportWizard>` component. |
| **Preview step** — every cell rendered with the right Docyrus widget | [`useDocyrusFieldComponent(field.type, 'value-renderer')`](/docs/web/hooks/use-docyrus-field-component). |
| **uniqueData pre-resolution** — slugs values to `matchedId` for enum-like fields | Reads `field.enums` / `field.options` client-side. Relation lookups are deferred to the server. |

## Error Handling

- File-too-large, wrong-extension, and empty-file errors fire client-side and surface as inline banners on the upload step (no network round-trip).
- Network errors are stored on each mutation's `error` and shown in the same banner; `onError(err, phase)` fires for telemetry.
- Partial server-side errors come back in `importResult.error[]` — rendered as a per-row error list on the result step.
- The wizard locks the close button (`preventOutsideClose`) while any phase is in flight so the user can't accidentally drop the upload mid-stream.

---

# useDocyrusDataSourceJsonSchema
URL: /docs/web/hooks/use-docyrus-data-source-json-schema

Generate a JSON Schema (object schema, properties keyed by field slug) from a Docyrus data source field list.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-docyrus-data-source-json-schema
```

This hook is distributed as source. It is fully standalone — it ships its own `JsonSchema` type and a Docyrus field-type → JSON Schema mapping, so it has no runtime dependency on the JSON Schema Designer or the form-fields system.

## Overview

`useDocyrusDataSourceJsonSchema` turns an array of Docyrus field descriptors into a standard **object JSON Schema** (Draft 2020-12 / Draft-07 compatible). Each field becomes one property:

- `field.slug` → the property **key** (machine name).
- `field.name` → the property `title` (user-facing label).
- `field.type` → the property `type` / `format` (via the built-in field-type map).
- `field.description` → the property `description`.

Use it to drive AI Structured Outputs / tool definitions, runtime validation (Ajv, Zod-from-JSON-Schema, etc.), form generation, or any flow that needs a machine-readable contract for a data source.

The hook is a pure, memoized transform — no state, no effects, no fetching.

## Usage

```tsx
'use client';

import { useDocyrusDataSourceJsonSchema } from '@/hooks/use-docyrus-data-source-json-schema';

const fields = [
  { slug: 'full_name', name: 'Full Name', type: 'field-text', description: 'Contact full name' },
  { slug: 'email', name: 'Email', type: 'field-email' },
  { slug: 'status', name: 'Status', type: 'field-status', description: 'Pipeline stage' },
  { slug: 'tags', name: 'Tags', type: 'field-tagSelect' },
  { slug: 'revenue', name: 'Annual Revenue', type: 'field-money' },
];

export function ContactSchema() {
  const schema = useDocyrusDataSourceJsonSchema(fields, {
    title: 'Contact',
    description: 'A CRM contact record',
  });

  return <pre>{JSON.stringify(schema, null, 2)}</pre>;
}
```

Produces:

```json
{
  "type": "object",
  "properties": {
    "full_name": { "type": "string", "title": "Full Name", "description": "Contact full name" },
    "email": { "type": "string", "format": "email", "title": "Email" },
    "status": { "type": "string", "title": "Status", "description": "Pipeline stage" },
    "tags": { "type": "array", "items": { "type": "string" }, "title": "Tags" },
    "revenue": { "type": "number", "title": "Annual Revenue" }
  },
  "additionalProperties": true,
  "title": "Contact",
  "description": "A CRM contact record"
}
```

### OpenAI Structured Outputs (strict mode)

Set `strict: true` to constrain the output to OpenAI Structured Outputs rules — `additionalProperties: false` plus every field slug listed in `required`:

```tsx
const schema = useDocyrusDataSourceJsonSchema(fields, { title: 'Contact', strict: true });
// schema.additionalProperties === false
// schema.required === ['full_name', 'email', 'status', 'tags', 'revenue']
```

### Marking fields required

```tsx
// every field required
useDocyrusDataSourceJsonSchema(fields, { required: true });

// only specific slugs required
useDocyrusDataSourceJsonSchema(fields, { required: ['full_name', 'email'] });
```

### Refining individual fields with `overrides`

The built-in mapping uses pragmatic defaults (single-choice / reference fields → `string`, multi-choice → `array` of `string`, structured fields → open `object`). When a field needs a tighter shape, deep-merge an override keyed by slug:

```tsx
const schema = useDocyrusDataSourceJsonSchema(fields, {
  overrides: {
    // narrow an enum/status field to a fixed set of option ids
    status: { enum: ['lead', 'qualified', 'won', 'lost'] },
    // describe the shape of a relation reference
    owner: { type: 'object', properties: { id: { type: 'string' }, name: { type: 'string' } } },
  },
});
```

Overrides are deep-merged onto the generated property (override wins; nested objects merge recursively), so `title`/`description` derived from the field metadata are preserved unless you replace them explicitly.

### Outside React

Both `buildDataSourceJsonSchema` and `fieldToJsonSchema` are pure and can be called from server components, API routes, or AI tool-definition builders:

```ts
import { buildDataSourceJsonSchema } from '@/hooks/use-docyrus-data-source-json-schema';

const schema = buildDataSourceJsonSchema(fields, { strict: true });
```

## API Reference

### `useDocyrusDataSourceJsonSchema(fields, options?)`

| Parameter | Type | Description |
|-----------|------|-------------|
| `fields` | `DataSourceFieldDescriptor[]` | Field list. Each entry: `{ slug, name, type, description? }`. |
| `options` | `UseDocyrusDataSourceJsonSchemaOptions` | Generation options (see below). |

Returns a memoized `JsonSchema` object. Memoization keys on `fields` and each option — pass a stable `fields` reference to avoid rebuilding on every render.

### `DataSourceFieldDescriptor`

| Field | Type | Description |
|-------|------|-------------|
| `slug` | `string` | Machine name → JSON Schema **property key**. Fields without a slug are skipped. |
| `name` | `string` | User-facing label → property `title`. |
| `type` | `IFieldType` | Docyrus field type (e.g. `field-text`, `field-email`, `field-status`). Drives `type` / `format`. |
| `description` | `string \| null` | Optional → property `description`. |

### `UseDocyrusDataSourceJsonSchemaOptions`

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `title` | `string` | `—` | `title` for the root object schema. |
| `description` | `string` | `—` | `description` for the root object schema. |
| `required` | `boolean \| string[]` | `—` | `true` → all slugs required; `string[]` → listed slugs required; omitted → no `required` array. |
| `strict` | `boolean` | `false` | OpenAI Structured Outputs mode: forces `additionalProperties: false` + all slugs `required`. Overrides `required` and `additionalProperties`. |
| `additionalProperties` | `boolean` | `true` | Root-level `additionalProperties`. Ignored when `strict`. |
| `includeTitles` | `boolean` | `true` | Emit each property's `title` from `field.name`. |
| `includeDescriptions` | `boolean` | `true` | Emit each property's `description` from `field.description`. |
| `includeDialect` | `boolean` | `false` | Include the `$schema` dialect keyword on the root. |
| `dialect` | `string` | `DEFAULT_JSON_SCHEMA_DIALECT` | Dialect URI used when `includeDialect` is set. |
| `overrides` | `Record<string, JsonSchema>` | `—` | Per-slug schema overrides, deep-merged onto the generated property. |

### Exports

| Export | Type | Purpose |
|--------|------|---------|
| `useDocyrusDataSourceJsonSchema` | `(fields, options?) => JsonSchema` | React hook (memoized). |
| `buildDataSourceJsonSchema` | `(fields, options?) => JsonSchema` | Pure builder — usable outside React. |
| `fieldToJsonSchema` | `(field, options?) => JsonSchema` | Pure single-field → property converter. |
| `FIELD_TYPE_SCHEMA_MAP` | `Partial<Record<IFieldType, JsonSchema>>` | Field type → base schema fragment map. |
| `DEFAULT_JSON_SCHEMA_DIALECT` | `string` | Default dialect (`https://json-schema.org/draft/2020-12/schema`). |
| `JsonSchema` | `interface` | Self-contained JSON Schema type returned by the hook. |
| `DataSourceFieldDescriptor` | `interface` | Field descriptor input type. |
| `UseDocyrusDataSourceJsonSchemaOptions` | `interface` | Options type. |

## Field type mapping

The defaults below are intentionally pragmatic. Refine any field with `overrides`.

| JSON Schema output | Docyrus field types |
|--------------------|---------------------|
| `string` | `field-text`, `field-textarea`, `field-password`, `field-phone`, `field-color`, `field-icon`, `field-currency`, `field-display`, `field-htmlEditor`, `field-emailEditor`, `field-codeEditor`, `field-markdown`, `field-formula`, `field-code`, `field-identity`, `field-handlebars`, `field-fileStorageFolder`, `field-systemEnum` |
| `string` + `format` | `field-email` (`email`), `field-url` (`uri`), `field-date` (`date`), `field-dateTime` (`date-time`), `field-time` (`time`) |
| `number` | `field-number`, `field-money`, `field-percent`, `field-duration`, `field-rating` |
| `integer` | `field-autonumber` |
| `boolean` | `field-checkbox`, `field-switch`, `field-todo` |
| `string` (id of choice / reference) | `field-enum`, `field-select`, `field-radioGroup`, `field-status`, `field-approvalStatus`, `field-userSelect`, `field-relation`, `field-locationSelect`, `field-button` |
| `array` of `string` | `field-multiSelect`, `field-tagSelect`, `field-userMultiSelect`, `field-list`, `field-systemTextArray`, `field-systemUuidArray` |
| `array` of `object` | `field-taskList`, `field-schemaRepeater` |
| open `object` | `field-json`, `field-jsonSchema`, `field-jsonata`, `field-adaptiveCard`, `field-schema`, `field-dynamic`, `field-inlineData`, `field-inlineForm`, `field-conversationChannel`, `field-queryBuilder`, `field-systemBuffer`, `field-systemVector` |
| stored-file `object` | `field-file`, `field-image`, `field-avatar` |
| date-range `object` (`{ from, to }`) | `field-dateRange` |
| `string` (fallback) | any unmapped / unknown type |

## How It Works

The hook reads `FIELD_TYPE_SCHEMA_MAP` for each field's base fragment, layers on `title` / `description` from the field metadata, deep-merges any per-slug `overrides`, and assembles the property bag under a root `object` schema. `strict` and `required` only affect the root `additionalProperties` / `required` keywords — they never mutate individual property shapes. The whole transform is pure and memoized against `fields` + options.

### Out of scope

- Fetching the field list — pass the data source's fields in yourself (e.g. from `@docyrus/app-utils` `DataSourceField` metadata).
- Resolving enum options or relation targets into concrete schemas — supply those via `overrides` when you need them.
- Validation — feed the returned schema to your validator of choice (Ajv, etc.).

---

# useDocyrusDataTable
URL: /docs/web/hooks/use-docyrus-data-table

One-call wiring of a Docyrus data source to a fully configured DataTable + toolbar (DataGridViewSelect, search, filters, group, sort) — including row fetching with view-derived query parameters and an optional side-panel filter rail.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-docyrus-data-table
```

## Overview

`useDocyrusDataTable` is the table-flavored sibling of [`useDocyrusDataGrid`](/docs/web/hooks/use-docyrus-data-grid). It produces a TanStack Table instance + toolbar wired to the same Docyrus saved-views, filter, and items endpoints, but renders rows through `

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `data` | `Array<TData>` | — | Pre-resolved rows. Skips the internal items query. |
| `collection` | `{ list: (params?) => Promise<…> }` | — | TanStack DB collection. `list(resolvedListParams)` is called inside `useQuery`. |
| `listParams` | `DocyrusDataGridListParams` | — | Extra query params merged on top of the view-derived payload. |
| `defaultLimit` | `number` | `100` | Default page size when no `limit` is supplied via `listParams`. |
| `enableItemsQuery` | `boolean` | `true` when no `data` | Toggle the internal items query. |
| `showSelectColumn` | `boolean` | `true` | Show the row-select checkbox column as the **first** column. |
| `enableRowNumbers` | `boolean` | `true` | Show 1-based row numbers on the select column when not selected. |
| `selectColumn` | `ColumnDef<TData>` | — | Override the default select column entirely. |
| `actionsColumn` | `ColumnDef<TData>` | — | Optional actions column rendered as the **second** column. |
| `extraColumns` | `Array<ColumnDef<TData>>` | — | Extra columns prepended after the select + actions columns. |
| `inferColumnsFromData` | `boolean` | `false` | Derive table columns from the loaded rows when the data source exposes **no schema fields** (e.g. system data sources, typically paired with `enabled: false`) and no `extraColumns` are supplied. Columns are built from the union of keys in the first rows; identity/label keys (`id`, `name`, `title`, …) lead and audit keys (`created_on`, …) trail. Ignored when schema fields or `extraColumns` exist. |
| `mapColumn` | `(field, defaultColumn) => ColumnDef \| null` | — | Per-field column override. Return `null` to skip a field. |
| `enableViewSelect` / `enableSearchInput` / `enableFilterMenu` / `enableGroupMenu` / `enableSortMenu` / `enableReloadButton` | `boolean` | `true` | Toggle individual toolbar items. The toolbar filter menu (`enableFilterMenu`) and the side filter panel (`enableSideFilters`) are independent — both can be active at the same time. |
| `enableSideFilters` | `boolean` | `false` | Activate the side-panel filter rail rendered alongside the table. When `true`, the hook returns a ready-to-render `sideFilters` element wired to `<DataTableSideFilters>` and merges its emitted `RuleGroupType` into the items request alongside the saved view filter and toolbar filter rules. Requires `sideFiltersConfig`. |
| `sideFiltersConfig` | `DocyrusDataTableSideFiltersConfig<TData>` | — | Configuration for the side panel. Required when `enableSideFilters` is `true`. See [Side panel filters](#side-panel-filters). |
| `sideFiltersDefaultExpanded` | `boolean` | `true` | Initial expanded state. When `false`, the panel mounts collapsed and renders a thin vertical rail with a 90°-rotated "Filters" label that re-expands the panel on click. |
| `sideFiltersExpanded` | `boolean` | — | Controlled expanded state. Pair with `onSideFiltersExpandedChange`. |
| `onSideFiltersExpandedChange` | `(expanded: boolean) => void` | — | Called when the user toggles the panel via the close icon (top right of the panel header) or the rotated rail button. |
| `sideFiltersWidth` | `number \| string` | `280` | Width of the side panel when expanded. Number → px. |
| `enableServerExportMenu` | `boolean` | `true` | Show the server-side data export dropdown in the toolbar. |
| `serverExportLimit` | `number` | `10000` | Row cap forwarded to the server export endpoint. |
| `onReload` | `() => void` | — | Called when the reload button is clicked, after the items query refetches. |
| `searchPlaceholder` | `string` | `'Search...'` | Placeholder for the toolbar search input. |
| `searchDebounceMs` | `number` | `300` | Debounce in ms before the search input is sent as `filterKeyword`. |
| `toolbarClassName` | `string` | — | Extra className for the toolbar root. |
| `toolbarStartContent` / `toolbarEndContent` | `ReactNode` | — | Custom nodes prepended/appended to the built-in toolbar. |
| `tableClassName` / `tableContainerClassName` | `string` | — | Forwarded to `<DataTable>`. |
| `emptyText` | `string` | — | Empty-state text forwarded to `<DataTable>`. |

### Return Value

| Property | Type | Description |
|----------|------|-------------|
| `table` | `Table<TData>` | TanStack Table instance — pass to `<DataTable>`. |
| `tableProps` | `Omit<DataTableProps, 'table'>` | Spread onto ``. |
| `toolbar` | `ReactNode` | Pre-wired toolbar element ready to render above the table. |
| `sidePanel` | `ReactNode` | Vertical view-picker panel. `null` for `'horizontal-tabs'`/`'dropdown'` view variants. |
| `sideFilters` | `ReactNode` | Side-panel filter rail. `null` when `enableSideFilters` is `false`. Renders the full `<DataTableSideFilters>` panel (with a panel-close icon in the header) when expanded, and a thin vertical rail (with a 90°-rotated "Filters" label) when collapsed. |
| `sideFiltersExpanded` | `boolean` | Current expanded state of the side filter panel. |
| `setSideFiltersExpanded` | `(expanded: boolean) => void` | Programmatically toggle the side filter panel. |
| `sideFiltersQuery` | `RuleGroupType \| undefined` | Current `RuleGroupType` emitted by the side panel — already merged into `resolvedListParams.filters`. |
| `items` | `Array<TData>` | Resolved rows passed to the table. |
| `resolvedListParams` | `DocyrusDataGridListParams` | The list params actually sent to the backend (after merging view state, search, side panel filters, and `listParams`). |
| `pagingMode` | `'standard' \| 'virtual-scroll' \| undefined` | Resolved paging mode for the active view. |
| `reload` | `() => void` | Triggers refetch of the data source, views, and items queries plus the optional `onReload` callback. |
| `views` | `SavedDataGridView[]` | Saved views mapped from the backend shape. |
| `fields` | `FullField[]` | Fields mapped for `react-querybuilder` filter editor. |
| `dataSource` | `DataSource \| undefined` | Raw data source metadata response. |
| `activeViewId` | `string` | Id of the currently active view. |
| `setActiveViewId` | `(viewId: string) => void` | Programmatically switch views. Persisted per user (follows `persistState` storage when enabled, `localStorage` otherwise). |
| `isLoading` | `boolean` | `true` until all queries (data source, views, items) have resolved. |
| `error` | `Error \| null` | First error from any of the queries. |
| `refetch` | `() => void` | Alias for `reload`. |

## Side panel filters

When `enableSideFilters` is `true`, the hook renders a [`<DataTableSideFilters>`](/docs/web/components/data-table-side-filters) rail alongside the table. The panel emits a `RuleGroupType` whenever the user adjusts a filter; the hook ANDs it onto the saved view's `filterQuery` and any toolbar filter menu rules before sending the items request — so side filters, toolbar filters, and the saved view all stack.

The toolbar filter menu (`enableFilterMenu`) is **not** auto-hidden; both can be active at the same time.

### Collapse / expand

- `sideFiltersDefaultExpanded` controls the initial state. Default `true`.
- When **expanded**, a panel-close icon (top right of the panel header) collapses it to a vertical rail.
- When **collapsed**, the rail shows a 90°-rotated "Filters" label (with the active-filter count appended) that re-expands the panel on click.
- For controlled collapse state, pass `sideFiltersExpanded` + `onSideFiltersExpandedChange`.

### `DocyrusDataTableSideFiltersConfig<TData>`

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `columnsConfig` | `ReadonlyArray<ColumnConfig<TData>>` | — | **Required.** Filter columns for the panel. Mirrors the `columnsConfig` accepted by `useDataTableFilters` / `useDataTableSideFilters`. |
| `strategy` | `'server' \| 'client'` | `'server'` | Filter strategy. Server-paged tables should use `'server'` so values surface as `RuleGroupType` rules; `'client'` filters the in-memory dataset. |
| `defaults` | `SideFilterDefaults` | — | Per-column UI hints (`collapsed`, `mode`, `showMoreThreshold`, `hidden`, `sticky`, etc.). |
| `sections` | `ReadonlyArray<SideFilterSectionGroup>` | — | Optional grouping of filter sections into named blocks. |
| `variant` | `'default' \| 'bordered' \| 'compact'` | `'default'` | Visual variant for the panel container. |
| `title` | `ReactNode` | `'Filters'` | Header title. Pass `null` to hide. |
| `showActiveChips` | `boolean` | `true` | Show the active-filter chip strip below the header. |
| `showClearAll` | `boolean` | `true` | Show the "Clear all" button next to the title when any filter is active. |
| `searchable` | `boolean \| string` | `false` | Render a search input above the sections that drives the first text-typed column (or a column id you pass explicitly). |
| `clearAllLabel` | `string` | `'Clear all'` | Override for the "Clear all" label. |
| `clearLabel` | `string` | `'Clear'` | Override for the per-section "Clear" label. |
| `locale` | `Locale` | `'en'` | Locale forwarded to the underlying filter UI. |
| `className` | `string` | — | Extra className for the panel root. |
| `collapseAriaLabel` | `string` | `'Collapse filters'` | Override for the collapse-button accessible label. |
| `expandAriaLabel` | `string` | `'Expand filters'` | Override for the expand-button accessible label. |
| `collapsedWidth` | `number \| string` | `36` | Width of the collapsed rail. Number → px. |

### Usage

```tsx
'use client';

import { useDocyrusAuth } from '@docyrus/signin';

import { DataTable } from '@docyrus/ui/components/data-table';
import { useDocyrusDataTable } from '@docyrus/ui/library/hooks/use-docyrus-data-table';
import { createColumnConfigHelper } from '@docyrus/ui/components/data-table-filter';

type OrganizationRow = { id: string; name: string; status: 'active' | 'archived' };

const dtf = createColumnConfigHelper<OrganizationRow>();

const sideFilterColumns = [
  dtf
    .text()
    .id('name')
    .accessor(row => row.name)
    .displayName('Name')
    .build(),
  dtf
    .option()
    .id('status')
    .accessor(row => row.status)
    .displayName('Status')
    .options([
      { value: 'active', label: 'Active' },
      { value: 'archived', label: 'Archived' }
    ])
    .build()
] as const;

export function OrganizationsTable() {
  const { client } = useDocyrusAuth();

  if (!client) return null;

  const {
    table, tableProps, toolbar, sideFilters
  } = useDocyrusDataTable<OrganizationRow>({
    client,
    appSlug: 'crm',
    dataSourceSlug: 'organization',
    enableSideFilters: true,
    sideFiltersDefaultExpanded: true,
    sideFiltersWidth: 280,
    sideFiltersConfig: {
      columnsConfig: sideFilterColumns,
      strategy: 'server',
      defaults: {
        status: { mode: 'inline-checkbox' }
      }
    }
  });

  return (
    <div className="flex h-full flex-col gap-3">
      {toolbar}
      <div className="flex flex-1 min-h-0">
        {sideFilters}
        
      </div>
    </div>
  );
}
```

---

# useDocyrusDataViewSelect
URL: /docs/web/hooks/use-docyrus-data-view-select

Fetch data source fields and saved views from Docyrus and wire them into DataGridViewSelect with a single hook.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-docyrus-data-view-select
```

**Dependencies:**
- [@docyrus/app-utils](https://www.npmjs.com/package/@docyrus/app-utils)
- [@docyrus/api-client](https://www.npmjs.com/package/@docyrus/api-client)
- [@tanstack/react-query](https://tanstack.com/query/latest)
- [react-querybuilder](https://react-querybuilder.js.org)

This hook is distributed as source. It requires an authenticated `RestApiClient` from `@docyrus/api-client` and a `QueryClientProvider` from `@tanstack/react-query` somewhere above your component tree.

## Overview

`useDocyrusDataViewSelect` loads a data source's fields and saved data views from the Docyrus backend via `@docyrus/app-utils`, adapts them to the shapes `DataGridViewSelect` expects, and returns a ready-to-spread props bag. The hook:

- Fetches the data source with `expand=enums` so enum-backed fields (status, enum, select, systemEnum) come back with their options attached and are mapped to `FullField.values` for the filter editor.
- Wires `create`, `update`, and `delete` to `createDataViewClient` with automatic view-list invalidation.
- Tracks the active view as controlled state and persists the last selection per user, scoped by app + data source (+ app id if present). Defaults to `localStorage`; `activeViewStorage: 'session'` scopes it per tab (threaded automatically from `persistState` by the data-listing hooks).

## Usage

```tsx
'use client';

import { useDocyrusDataViewSelect } from '@/hooks/use-docyrus-data-view-select';
import { DataGridViewSelect } from '@/components/docyrus/data-grid-view-select';
import { useReactTable } from '@tanstack/react-table';

export function ContactsGridHeader({ client, table }) {
  const { gridViewSelectProps, isLoading } = useDocyrusDataViewSelect({
    client,
    appSlug: 'crm',
    dataSourceSlug: 'contacts'
  });

  if (isLoading) return null;

  return (
    
  );
}
```

The hook does not accept `table` — spread the returned props onto `DataGridViewSelect` and pass `table` separately so TanStack Table generics are preserved.

## API Reference

### Parameters

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `client` | `RestApiClient` | — | Authenticated Docyrus API client. |
| `appSlug` | `string` | — | Slug of the app the data source belongs to. |
| `dataSourceSlug` | `string` | — | Slug of the data source. |
| `appId` | `string` | — | Optional app id filter for views scoped to a different app than the data source owner. |
| `overrideFields` | `FullField[]` | — | Replace the computed query-builder fields entirely. |
| `mapField` | `(field, defaultMapped) => FullField \| null` | — | Per-field transform run after default mapping. Return `null` to drop a field from filter UI. |
| `staleTime` | `number` | `30_000` | TanStack Query `staleTime` applied to both the data source and views queries. |
| `enabled` | `boolean` | `true` | Disable queries while other state is still loading. |
| `dataSource` | `DataSource \| null` | — | Pre-resolved schema. When provided, the hook **skips the `getBySlug` metadata fetch** and reads fields / metadata from this object — the field list, relation targets, and the returned `dataSource` all come from it. See [DB-free metadata](#db-free-metadata). |
| `enableDataViews` | `boolean` | `true` | Fetch and manage saved data views (the `/views` endpoint). Set `false` for data sources without a view-configuration backend (e.g. core/tenant system data sources) so the hook never calls `/views`; the tab strip then shows only `systemViews` (if any). |
| `dataSourceExpand` | `string \| false` | `'enums'` | `expand` query param for the schema fetch (so select/status fields carry option metadata). Pass `false`/`''` to omit `expand` for backends that don't support it. Ignored when `dataSource` is injected. |
| `persistActiveView` | `boolean` | `true` | Persist the last-selected view per user. Set to `false` to disable. |
| `persistKey` | `string` | auto | Override the auto-generated storage key (default: `docyrus:data-grid-view:<appSlug>:<dataSourceSlug>[:<appId>]`). |
| `activeViewStorage` | `'session' \| 'local'` | `'local'` | Storage backend for the persisted active-view id. The data-listing hooks (`useDocyrusDataGrid` / `useDocyrusDataTable` / `useDocyrusKanban`) thread their `persistState.storage` here automatically, so the active view follows the same session/local scope as the rest of the persisted view parameters. |
| `defaultRowGroupingColumn` | `string` | — | Forwarded to `DataGridViewSelect` as the default row-grouping column for views that don't already specify a `grouping`. Pair with [`useDocyrusDataGrid`](/docs/web/hooks/use-docyrus-data-grid) which actually applies it to the table. |

### Return Value

| Property | Type | Description |
|----------|------|-------------|
| `gridViewSelectProps` | `Pick<DataGridViewSelectProps, ...>` | Pre-wired props: `views`, `activeViewId`, `fields`, `onViewChange`, `onViewCreate`, `onViewSave`, `onViewDelete`, `disabled`. |
| `views` | `SavedDataGridView[]` | Views already mapped from the backend shape. |
| `fields` | `FullField[]` | Fields mapped for `react-querybuilder` filter editor. |
| `dataSource` | `DataSource \| undefined` | The raw data source metadata response. |
| `activeViewId` | `string` | The id of the currently active view (empty while loading). |
| `setActiveViewId` | `(viewId: string) => void` | Programmatically switch views. Persisted per user (`activeViewStorage` backend — `localStorage` by default). |
| `isLoading` | `boolean` | `true` until both queries have resolved. |
| `error` | `Error \| null` | First error from either query. |
| `refetch` | `() => void` | Refetch both the data source and views queries. |

## How It Works

### Backend calls

- **Data source** (`createDataSourceClient`) — `getBySlug(appSlug, dataSourceSlug, { expand: dataSourceExpand })` loads the data source, its fields, and (with the default `'enums'` expansion) enum options in a single request. The `enums` expansion implies `fields`. Skipped entirely when `dataSource` is injected.
- **Views** (`createDataViewClient`) — `list({ appId })` loads non-archived views. Mutations use `create`, `update(id, body)`, and `remove(id)`. Successful mutations invalidate the views query so the tab list refreshes. Skipped when `enableDataViews` is `false`.

### DB-free metadata

For surfaces that already hold the schema in memory — or system data sources without a metadata / view-configuration route — the hook can run without any schema fetch:

- **`dataSource`** injects the schema; the `getBySlug` call is skipped and fields, relation targets, and the returned `dataSource` all read from your object.
- **`enableDataViews: false`** stops the `/views` request (the tab strip then shows only `systemViews`).
- **`dataSourceExpand: false`** drops the `expand` param for backends that reject it (only relevant when the hook *does* fetch).

```tsx
const viewSelect = useDocyrusDataViewSelect({
  client,
  appSlug: 'core',
  dataSourceSlug: 'system_users',
  dataSource: systemUsersSchema, // ← no getBySlug
  enableDataViews: false         // ← no /views
});
```

This is the single integration point that makes [`useDocyrusDataGrid`](/docs/web/hooks/use-docyrus-data-grid), [`useDocyrusDataTable`](/docs/web/hooks/use-docyrus-data-table), [`useDocyrusKanban`](/docs/web/hooks/use-docyrus-kanban), [`useDocyrusDataGallery`](/docs/web/hooks/use-docyrus-data-gallery), and [`useDocyrusMapView`](/docs/web/hooks/use-docyrus-map-view) accept the same `dataSource` / `enableDataViews` / `dataSourceExpand` options — they all forward into this hook.

### View shape mapping

`DataGridViewSelect` uses `SavedDataGridView` (TanStack Table + react-querybuilder types). `DataView` from the Docyrus backend uses opaque `Record<string, unknown>` fields. The hook packs and unpacks like this:

| `DataView` field | `SavedDataGridView` fields |
|------------------|----------------------------|
| `columns` | `columnVisibility`, `columnOrder`, `columnPinning`, `grouping`, `rowHeight`, `displayMode` |
| `filters` | `columnFilters`, `filterQuery` |
| `sort` | `sorting` |
| `color_rules` | `rowColorRules`, `cellColorRules` |

Views created by other clients with empty `columns` still unpack to valid `SavedDataGridView` objects (empty `{}` / `[]` defaults).

### Field type mapping

The default `DataSourceField` → `FullField` mapping covers common Docyrus field types (`field-text`, `field-number`, `field-date`, `field-dateTime`, `field-status`, `field-enum`, `field-multiSelect`, etc.). For enum-backed fields, the `enums` array from the `expand=enums` response is mapped to `FullField.values` using each enum's `slug` as the filter value and `name` as the label. For field types that need richer filter UI, pass `mapField` or replace the whole list via `overrideFields`.

### Active view & persistence

The hook owns active view state and passes it as a controlled `activeViewId` to `DataGridViewSelect`. On first load:

1. If `persistActiveView` is on (default) and a previous selection is in storage for the same app/data source, that view is restored — provided it still exists.
2. Otherwise the view marked `is_default` on the backend wins.
3. Otherwise the first view wins.

User selections update state and write to storage under `docyrus:data-grid-view:<appSlug>:<dataSourceSlug>[:<appId>]`. The backend defaults to `localStorage`; pass `activeViewStorage: 'session'` for per-tab scoping. If the active view is deleted by another client, the hook automatically reselects using the same fallback chain after the next refetch.

When a data-listing hook (`useDocyrusDataGrid` / `useDocyrusDataTable` / `useDocyrusKanban`) is given `persistState`, it threads `activeViewStorage` (from `persistState.storage`) and a unified `persistKey` (`docyrus:view-params:<appSlug>:<dataSourceSlug>[:<appId>]:__active-view__` — `appId` included when present because saved-view lists are appId-scoped) into this hook automatically — so the active view lives in the same storage backend and key namespace as the persisted view parameters. Explicit `activeViewStorage` / `persistKey` options passed by the consumer still win. Without `persistState`, the historical always-on `localStorage` behavior is unchanged. The per-user hidden-views list always stays in `localStorage` — hiding a view is a durable preference, not a per-tab tweak.

### Out of scope

- Hidden views (`onViewHide` / `onViewUnhide`). `DataView.archived` is a destructive soft-delete and shouldn't be conflated with "hidden from tabs".

---

# useDocyrusDummyDataGeneratorWizard
URL: /docs/web/hooks/use-docyrus-dummy-data-generator-wizard

One-call wiring of a Docyrus data source to the DummyDataGenerator — handles field-aware strategies, deterministic generation, preview, and batch insert in a single guided flow.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-docyrus-dummy-data-generator-wizard
```

**Dependencies:**
- [@docyrus/app-utils](https://www.npmjs.com/package/@docyrus/app-utils)
- [@docyrus/api-client](https://www.npmjs.com/package/@docyrus/api-client)
- [@tanstack/react-query](https://tanstack.com/query/latest)

This hook is distributed as source. It needs an authenticated `RestApiClient` from `@docyrus/api-client` and a `QueryClientProvider` from `@tanstack/react-query` somewhere above your component tree.

## Overview

`useDocyrusDummyDataGeneratorWizard` is the one-call entry point that wires a Docyrus data source to [`
    
    
  </>
);
```

### Side-by-side with `useDocyrusDataGrid`

Both hooks accept the same `client` + `appSlug` + `dataSourceSlug`. Wire `onGenerated` to the grid's `reload()` so newly inserted rows show up immediately:

```tsx
const grid = useDocyrusDataGrid({ client, appSlug, dataSourceSlug });
const seeder = useDocyrusDummyDataGeneratorWizard({
  client,
  appSlug,
  dataSourceSlug,
  collection: grid.collection,         // bulk-insert via collection.createMany when available
  fields: grid.fields,                 // skip duplicate metadata fetch
  users: grid.users,                   // populate field-userSelect strategies
  onGenerated: () => grid.reload()
});

return (
  <>
    {grid.toolbar}
    
    {seeder.wizard}
  </>
);
```

### Preview-only flow (no inserts)

```tsx
const seeder = useDocyrusDummyDataGeneratorWizard({
  client,
  appSlug,
  dataSourceSlug,
  previewOnly: true,
  onGenerated: (_result, rows) => {
    download('seed.json', JSON.stringify(rows, null, 2));
  }
});
```

### Custom batch endpoint

```tsx
const seeder = useDocyrusDummyDataGeneratorWizard({
  client,
  appSlug,
  dataSourceSlug,
  insertRecords: async (rows) => {
    const response = await client.post(`/v1/apps/${appSlug}/data-sources/${dataSourceSlug}/items/bulk`, { records: rows });
    const errors = (response as { errors?: Array<{ index: number; message: string }> }).errors ?? [];

    return { errors: errors.map(e => ({ rowIndex: e.index, message: e.message })) };
  }
});
```

## API Reference

### Parameters

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `client` | `RestApiClient` | — | Authenticated client from `@docyrus/api-client`. **Required.** |
| `appSlug` | `string` | — | Target app slug. **Required.** |
| `dataSourceSlug` | `string` | — | Target data source slug. **Required.** |
| `appId` | `string` | — | Optional multi-tenant isolation key. |
| `fields` | `Array<DocyrusFieldLike>` | — | Pre-resolved target fields. When provided, the hook skips its internal data source fetch. |
| `requiredFieldSlugs` | `Array<string>` | `[]` | Slugs locked to `enabled: true`. |
| `defaultCount` | `number` | `10` | Initial row count. |
| `maxCount` | `number` | `1000` | UI hard cap. |
| `previewRowCount` | `number` | `10` | Number of rows shown in the preview step. |
| `collection` | `{ create?, createMany? }` | — | Optional collection wrapper. `createMany` is preferred over per-record `create` for batch inserts. |
| `users` | `Array<DummyUserOption>` | — | Tenant users used for `field-userSelect` / `field-userMultiSelect` strategies. |
| `relationOptionsByFieldSlug` | `Record<string, Array<DummyRelationOption>>` | — | Relation pool keyed by field slug. Without it, relation fields are skipped. |
| `previewOnly` | `boolean` | `false` | When `true` the preview-step CTA is "Finish" — the hook never POSTs anything. |
| `enabled` | `boolean` | `true` | When `false` the hook returns `wizard: null` (use as a feature flag). |
| `onGenerated` | `(result, rows) => void` | — | Called after the progress phase completes. |
| `onError` | `(error: Error, rowIndex: number) => void` | — | Called whenever a per-row insert throws (default `insertRecords` only). |
| `insertRecords` | `(rows) => Promise<{ errors }>` | derived | Override the per-row insert pipeline. |
| `title` / `description` / `icon` | `ReactNode` / `ReactNode` / `string` | translated default | Override the wizard header copy. |
| `exportFileName` | `string` | `<dataSourceSlug>-dummy-data` | File name (without extension) for CSV / XLSX downloads. |

### Return Value

| Property | Type | Description |
|----------|------|-------------|
| `wizard` | `ReactElement \| null` | Inline wizard panel. Render it directly or wrap it in a dialog. `null` when `enabled === false`. |
| `resetWizard` | `() => void` | Reset the wizard back to the configure step (clears generated rows + result). |
| `step` | `DummyDataGeneratorStep` | Current step. |
| `setStep` | `(step) => void` | Move to a step programmatically. |
| `count` / `setCount` | `number` / `(next) => void` | Row count + setter. Setter clamps to `[1, maxCount]`. |
| `strategies` / `setStrategies` | `DummyStrategyMap` / `(next) => void` | Per-field strategies + setter. |
| `generatedRows` | `Array<Record<string, unknown>>` | The rows shown in the preview / saved on the next step. |
| `result` | `DummyGenerationResult \| null` | Final-step summary. |
| `generateAsync` | `() => Array<Record<string, unknown>>` | Imperative generation that returns the rows (skips the wizard UI). |
| `insertAsync` | `(rows) => Promise<DummyGenerationResult>` | Imperative insert (skips the wizard UI). |
| `fields` | `Array<DocyrusFieldLike>` | Resolved target fields (from `fields` prop or `useDocyrusDataViewSelect`). |
| `isGenerating` / `isCreating` | `boolean` | Pending flags. |
| `error` | `Error \| null` | Last insert error. |

## Determinism

Generation uses a Mulberry32 PRNG seeded with a fresh value on every "Regenerate sample" click. Within one click, the preview rows are byte-identical to the rows that get inserted. Pass `seed` directly to `generateDummyRows(ctx)` if you want test-stable output.

## Error Handling

- Per-row insert errors are collected and shown as a per-row error list on the result step. The wizard always reaches the result step — partial failures don't abort the run.
- A thrown `insertRecords` (the override) marks every row as failed and surfaces the message in the per-row list.

## See Also

- [`<DummyDataGenerator>`](/docs/web/components/dummy-data-generator) — the presentational wizard wired by this hook.
- [`useDocyrusDataImportWizard`](/docs/web/hooks/use-docyrus-data-import-wizard) — companion hook for importing real spreadsheets.
- [`useDocyrusFieldComponent`](/docs/web/hooks/use-docyrus-field-component) — the registry that powers preview rendering.
- [`useDocyrusDataGrid`](/docs/web/hooks/use-docyrus-data-grid) — companion hook for displaying the inserted records.

---

# useDocyrusEmailComposer
URL: /docs/web/hooks/use-docyrus-email-composer

Wire an `<EmailComposer />` to the Docyrus messaging API — loads sender accounts, lets the user pick a From address, and ships emails through `/v1/messaging/email/accounts/{id}/send`.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-docyrus-email-composer
```

**Dependencies:**
- [@docyrus/api-client](https://www.npmjs.com/package/@docyrus/api-client)
- [@tanstack/react-query](https://tanstack.com/query/latest)

The hook needs an authenticated `RestApiClient` from `@docyrus/api-client` and a `QueryClientProvider` from `@tanstack/react-query` somewhere above your component tree. The access token must carry the `Messaging.Email.Send` scope — otherwise both the list-accounts and send calls return `403 insufficient_scope`.

## Overview

`useDocyrusEmailComposer` is the Docyrus-backed companion to [`EmailComposer`](/docs/web/components/email-composer). It does three things:

- **Loads sender accounts** — `GET /v1/messaging/email/accounts` returns both shared **tenant** accounts (`tenant_email_configuration`) and the caller's own connected OAuth mailboxes (Microsoft / Google).
- **Manages composer state** — `to`, `cc`, `bcc`, `subject`, `body`, plus the currently selected account id. State persists across re-renders and resets after a successful send (toggle via `resetOnSendSuccess`).
- **Sends through the picked account** — `POST /v1/messaging/email/accounts/{accountId}/send` returns `{ messageId, provider, accepted, rejected }`. Per-call overrides let you set `sendAsUser`, storage-backed `attachments`, or `replyTo` without touching the composer state.

The first user-accessible account is auto-selected once the list resolves, so consumers don't have to wait for the user to pick before the composer becomes interactive.

## Usage

### Default integration

```tsx
'use client';

import { useDocyrusAuth } from '@docyrus/signin';

import { EmailComposer } from '@docyrus/ui/components/email-composer';
import {
  useDocyrusEmailComposer
} from '@docyrus/ui/library/hooks/use-docyrus-email-composer';

export function SendEmailDialog({ onClose }: { onClose: () => void }) {
  const { client } = useDocyrusAuth();

  if (!client) return null;

  const composer = useDocyrusEmailComposer({
    client,
    initialTo: ['customer@example.com'],
    initialSubject: 'Following up on your order'
  });

  return (
    
  );
}
```

`composerProps` spreads the wiring for the From dropdown, recipient fields, subject, body, and the `onSend` handler. The composer's built-in Send button fires the hook's mutation; no glue required.

### Sending with `sendAsUser`

For tenant accounts that allow it, `sendAsUser: true` overrides the From name/address with the authenticated user's identity at the API layer (subject to each account's `allowOverrideName` / `allowOverrideEmail` flags).

```tsx
const composer = useDocyrusEmailComposer({
  client,
  sendAsUser: true // forwarded with every send call
});
```

Or override it per call:

```tsx
await composer.send({ sendAsUser: true });
```

### Storage-backed attachments

The composer's local `EmailAttachment` carries `{ name, size }` only — it cannot be transmitted as-is, because the send endpoint expects files that already live in Docyrus storage. Upload first, then hand the storage path(s) to `send()`:

```tsx
await composer.send({
  attachments: [
    { filePath: 'tenant-files/invoices/inv-1234.pdf', fileName: 'invoice.pdf', mimeType: 'application/pdf' }
  ]
});
```

### Reading the response

`lastSendResult` carries the latest server response so you can surface rejected recipients:

```tsx
{composer.lastSendResult?.rejected.length > 0 && (
  <p>The provider rejected: {composer.lastSendResult.rejected.join(', ')}</p>
)}
```

## Account selection

The dropdown surfaces every account returned by the API:

| Account kind | Source | Behavior |
|--------------|--------|----------|
| `tenant` | Shared tenant configuration (`tenant_email_configuration`) | Send From is the configured `senderName` / `senderEmail`. `sendAsUser` may override these if `allowOverride*` is set. |
| `user` | The caller's connected OAuth mailbox (`tenant_connection_user`) | Always sends as the user; `sendAsUser` is ignored by the server. |

Entries with `isUserAccessible: false` are rendered disabled in the dropdown — they exist in the tenant configuration but the current user can't send through them.

The hook auto-selects the first `isUserAccessible: true` account on first load. Override via `initialAccountId` or by calling `setSelectedAccountId(id)`.

## API Reference

### `useDocyrusEmailComposer(options)`

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `client` | `RestApiClient` | — | Authenticated Docyrus API client. |
| `initialTo` | `string[]` | `[]` | Initial **To** recipients. |
| `initialCc` | `string[]` | `[]` | Initial **Cc** recipients. |
| `initialBcc` | `string[]` | `[]` | Initial **Bcc** recipients. |
| `initialReplyTo` | `string[]` | `[]` | Initial **Reply-To** addresses (forwarded with every send). |
| `initialSubject` | `string` | `''` | Initial subject. |
| `initialBody` | `string` | `''` | Initial body HTML. |
| `initialAccountId` | `string` | — | Preselect a specific account id. When omitted, the hook picks the first `isUserAccessible: true` account once the list resolves. |
| `resetOnSendSuccess` | `boolean` | `true` | Clear `to` / `cc` / `bcc` / `subject` / `body` / `attachments` after a successful send. Disable to keep the composer populated for a follow-up send. |
| `enabled` | `boolean` | `true` | Toggles the `GET /v1/messaging/email/accounts` query. |
| `sendAsUser` | `boolean` | — | Default forwarded as `sendAsUser` on every send unless explicitly overridden. |
| `listAccountsEndpoint` | `string` | `/v1/messaging/email/accounts` | Override the list endpoint. |
| `sendEndpoint` | `string` | `/v1/messaging/email/accounts/{accountId}/send` | Override the send endpoint. `{accountId}` is replaced with the selected id. |
| `mentions` | `boolean` | `true` | Toggles the `GET /v1/users` query that powers the body editor's `@` mention autocomplete. `/v1/users` has no server-side search, so the list is fetched once (limit 1000, 5-minute stale time) and filtered client-side. |
| `mentionUsers` | `EmailComposerMentionUser[]` | — | Explicit mention users. When provided, the `/v1/users` fetch is skipped. |
| `listUsersEndpoint` | `string` | `/v1/users` | Override the mention users list endpoint. |
| `slashCommands` | `EmailComposerSlashCommand[]` | — | Developer-defined `/` slash commands forwarded to the composer body editor. Pure passthrough — no fetching. See the [composer's Slash Commands section](/docs/web/components/email-composer#-slash-commands) for the command API. |

### Return value

| Property | Type | Description |
|----------|------|-------------|
| `composerProps` | `Pick<EmailComposerProps, ...>` | Ready-to-spread props for ``. Wires accounts, selected account, all recipient/subject/body fields, `mentionUsers`, `slashCommands`, `onSend`, and `sending`. |
| `accounts` | `DocyrusEmailAccount[]` | Raw account DTOs (includes provider / override metadata). |
| `selectedAccount` | `DocyrusEmailAccount \| null` | Currently selected account. |
| `setSelectedAccountId` | `(accountId: string) => void` | Programmatically change the selection. |
| `isLoadingAccounts` | `boolean` | First-fetch loading state for the accounts query. |
| `accountsError` | `Error \| null` | Last error from the accounts query (e.g. `insufficient_scope`). |
| `refetchAccounts` | `() => Promise<unknown>` | Invalidate and refetch the accounts cache. |
| `mentionUsers` | `EmailComposerMentionUser[]` | Users offered by the body editor's `@` mention autocomplete (from `mentionUsers` option or the `/v1/users` fetch; empty when `mentions: false`). |
| `to` / `setTo` | `string[]` / `(next) => void` | Direct access to the **To** state. |
| `cc` / `setCc` | `string[]` / `(next) => void` | Direct access to the **Cc** state. |
| `bcc` / `setBcc` | `string[]` / `(next) => void` | Direct access to the **Bcc** state. |
| `replyTo` / `setReplyTo` | `string[]` / `(next) => void` | Direct access to the **Reply-To** state. |
| `subject` / `setSubject` | `string` / `(next) => void` | Direct access to the subject. |
| `body` / `setBody` | `string` / `(next) => void` | Direct access to the HTML body. |
| `attachments` / `setAttachments` | `EmailAttachment[]` / `(next) => void` | Local attachment metadata. **Not** sent automatically — the send endpoint expects storage paths. |
| `send` | `(overrides?) => Promise<DocyrusEmailSendResult>` | Trigger a send. Resolves with `{ messageId, provider, accepted, rejected }`. |
| `isSending` | `boolean` | Mutation in-flight state. |
| `sendError` | `Error \| null` | Last send error. |
| `lastSendResult` | `DocyrusEmailSendResult \| null` | Last successful send response — surface rejected recipients here. |
| `reset` | `() => void` | Clear all field state back to the `initial*` values. |

### `send(overrides?)`

Every field is optional — anything omitted falls back to current composer state.

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `to` | `string[]` | `state.to` | Override **To** recipients. |
| `cc` | `string[]` | `state.cc` | Override **Cc** recipients. |
| `bcc` | `string[]` | `state.bcc` | Override **Bcc** recipients. |
| `replyTo` | `string[]` | `state.replyTo` | Override **Reply-To** addresses. |
| `subject` | `string` | `state.subject` | Override subject. |
| `body` | `string` | `state.body` | Override HTML body. |
| `sendAsUser` | `boolean` | `options.sendAsUser` | Override the `sendAsUser` flag. Honored only on tenant accounts with `allowOverride*` set. |
| `attachments` | `DocyrusEmailAttachment[]` | — | Storage-backed attachments (`{ filePath, fileName?, mimeType? }`). |
| `accountId` | `string` | `selectedAccountId` | Send through a specific account, bypassing the dropdown selection. |

## Type Exports

| Type | Description |
|------|-------------|
| `UseDocyrusEmailComposerOptions` | Hook option shape. |
| `UseDocyrusEmailComposerResult` | Hook return shape. |
| `DocyrusEmailAccount` | Account DTO returned by the list endpoint — extends `EmailComposerAccount` with provider / override metadata. |
| `DocyrusEmailAttachment` | `{ filePath; fileName?; mimeType? }` — payload shape for the send endpoint. |
| `DocyrusEmailSendOverrides` | Optional overrides accepted by `send(...)`. |
| `DocyrusEmailSendResult` | `{ messageId; provider; accepted[]; rejected[] }`. |
| `DocyrusEmailProvider` | `'aws' \| 'smtp' \| 'mailgun' \| 'resend' \| 'microsoft-graph' \| 'gmail'`. |

## Error handling

`accountsError` and `sendError` surface the underlying API failures verbatim. Common ones:

| Status | When | What to do |
|--------|------|------------|
| `401` | Missing/invalid access token. | Re-authenticate via `@docyrus/signin`. |
| `403 insufficient_scope` | The access token doesn't include `Messaging.Email.Send`. | Add the scope to the OAuth2 client config, re-authorize. |
| `403` (accessible flag) | Selected account has `isUserAccessible: false`. | Disable the option in the dropdown (already done by default). |
| `404` | The chosen `accountId` doesn't exist. | Re-fetch the account list. |
| `400` | Validation failure (invalid email, missing subject/body, attachment limits). | Surface from `sendError.message`. |

---

# useDocyrusFieldComponent
URL: /docs/web/hooks/use-docyrus-field-component

Resolve the right UI component (form input, value renderer, data-grid cell, editable value, or TanStack column def builder) for any Docyrus data source field type.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-docyrus-field-component
```

This hook is distributed as source. It re-exports component registries used by `DynamicFormField`, `DynamicValue`, the data-grid cell system, and `useDocyrusDataGrid`, so adding a new field type only requires updating one place.

## Overview

`useDocyrusFieldComponent` is a synchronous lookup hook that maps a Docyrus field type (e.g. `field-select`) to the right React component (or builder) for one of five render contexts:

- **`form-field`** — TanStack Form input component (e.g. `SelectFormField`).
- **`value-renderer`** — Read-only display component (e.g. `SelectValue`).
- **`data-grid-cell-variant`** — TanStack-table cell component (e.g. `SelectCell`).
- **`editable-value`** — Always returns `EditableValue`, which dispatches read/edit modes by field type internally.
- **`tanstack-column-def`** — Returns a `<TData>(opts) => ColumnDef<TData>` builder that produces a fully-configured TanStack column for the field.

With this hook, you can build fully dynamic interfaces (auto-rendered forms, tables, and inline-edit views) just by iterating field metadata — no per-type switch statements at the call site.

## Usage

```tsx
'use client';

import { useDocyrusFieldComponent } from '@/hooks/use-docyrus-field-component';
import { type IField } from '@/components/docyrus/form-fields/types';

export function DynamicFieldRenderer({ field, value, record, form }: {
  field: IField;
  value: unknown;
  record: Record<string, unknown>;
  form: any;
}) {
  const FormField = useDocyrusFieldComponent(field.type, 'form-field');
  const Value     = useDocyrusFieldComponent(field.type, 'value-renderer');
  const Cell      = useDocyrusFieldComponent(field.type, 'data-grid-cell-variant');
  const Editable  = useDocyrusFieldComponent(field.type, 'editable-value');

  // form-field can be null for read-only/unsupported types
  if (FormField) return ;

  // value-renderer always returns a component (TextValue fallback)
  return ;
}
```

The return type is conditionally typed by the `kind` argument:

```ts
const Form = useDocyrusFieldComponent('field-select', 'form-field');
//    ^? ComponentType<DocyrusFormFieldProps> | null

const Value = useDocyrusFieldComponent('field-select', 'value-renderer');
//    ^? ComponentType<DocyrusValueProps>

const Cell = useDocyrusFieldComponent('field-select', 'data-grid-cell-variant');
//    ^? ComponentType<DataGridCellProps<unknown>>

const Editable = useDocyrusFieldComponent('field-select', 'editable-value');
//    ^? typeof EditableValue

const Build = useDocyrusFieldComponent('field-select', 'tanstack-column-def');
//    ^? <TData>(opts: BuildTanstackColumnDefOptions) => ColumnDef<TData>
```

### Building TanStack column defs

For dynamic tables, get a column-def builder for each field and feed the results to TanStack Table:

```tsx
'use client';

import { useMemo } from 'react';
import { useDocyrusFieldComponent } from '@/hooks/use-docyrus-field-component';
import { useReactTable, getCoreRowModel } from '@tanstack/react-table';

export function ContactsTable({ fields, rows, appSlug, dataSourceSlug }) {
  const buildColumn = useDocyrusFieldComponent(fields[0]?.type, 'tanstack-column-def');

  const columns = useMemo(
    () => fields.map((field) => buildColumn({ field, appSlug, dataSourceSlug })),
    [fields, buildColumn, appSlug, dataSourceSlug]
  );

  const table = useReactTable({ data: rows, columns, getCoreRowModel: getCoreRowModel() });
  // ...
}
```

The builder returns `ColumnDef<TData>` with:

- `id` = `field.slug`
- `accessorFn` reads `row[field.slug]` and normalizes object payloads (enum/multi/relation) so grouping & sorting work
- `header` = `field.name`
- `meta.label`, `meta.cell` (the `CellOpts` config), `meta.groupable`, and `meta.renderGroupValue` (renders group headers with the right value renderer)

> The `fieldType` argument is a memoization key for this kind — the builder itself reads `field.type` from the passed `field`, so a single builder can construct columns for any field type. Pass any `IFieldType`; we recommend the type of one representative field for stability.

## API Reference

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `fieldType` | `IFieldType` | The Docyrus data source field type, e.g. `field-text`, `field-select`, `field-dateTime`. |
| `kind` | `'form-field' \| 'value-renderer' \| 'data-grid-cell-variant' \| 'editable-value' \| 'tanstack-column-def'` | Which render context to resolve the component for. |

### Return Value

| `kind` | Returns | Unknown-type fallback |
|--------|---------|-----------------------|
| `form-field` | `ComponentType<DocyrusFormFieldProps> \| null` | `null` (read-only/unsupported types) |
| `value-renderer` | `ComponentType<DocyrusValueProps>` | `TextValue` |
| `data-grid-cell-variant` | `ComponentType<DataGridCellProps<unknown>>` | `ShortTextCell` |
| `editable-value` | `typeof EditableValue` | `EditableValue` (it dispatches by field type internally) |
| `tanstack-column-def` | `<TData>(opts: BuildTanstackColumnDefOptions) => ColumnDef<TData>` | Builder produces `short-text` cell variant for unknown types |

### Exported registries

The hook module exports the underlying maps and helpers as named consts so non-React code, server components, or column-def builders can read them directly:

| Export | Type | Purpose |
|--------|------|---------|
| `FORM_FIELD_MAP` | `Partial<Record<IFieldType, ComponentType<DocyrusFormFieldProps>>>` | Field type → form input component. |
| `VALUE_RENDERER_MAP` | `Partial<Record<IFieldType, ComponentType<DocyrusValueProps>>>` | Field type → read-only renderer. |
| `CELL_COMPONENT_MAP` | `Partial<Record<IFieldType, ComponentType<DataGridCellProps<unknown>>>>` | Field type → data-grid cell component. |
| `GROUPABLE_FIELD_TYPES` | `Set<IFieldType>` | Field types selectable in the grouping picker. |
| `getCellOpts(field, opts)` | `(field, { appSlug?, dataSourceSlug? }) => CellOpts` | Pure function: field metadata → TanStack `meta.cell` config. |
| `buildTanstackColumnDef(opts)` | `<TData>(opts) => ColumnDef<TData>` | Pure builder: field metadata → full `ColumnDef`. |

`DynamicFormField`, `DynamicValue`, and `useDocyrusDataGrid` all consume this hook internally — adding a new field type means editing the maps in this module and nothing else.

### `BuildTanstackColumnDefOptions`

| Field | Type | Description |
|-------|------|-------------|
| `field` | `DocyrusFieldLike` | Field metadata. Accepts both `IField` and `@docyrus/app-utils`'s `DataSourceField`. |
| `appSlug` | `string` | Wired into `enum` cell meta for dynamic option loading. |
| `dataSourceSlug` | `string` | Wired into `enum` cell meta for dynamic option loading. |

## How It Works

The hook is a memoized lookup with no state, no effects, and no fetching. It reads from one of the three exported registries based on `kind`, applies the appropriate fallback for unknown field types, and returns the resolved component (referentially stable while `fieldType` and `kind` are unchanged).

### Why `data-grid-cell-variant` returns the cell component, not the variant string

The cell components (`SelectCell`, `EnumCell`, etc.) render correctly only when their host column is wired with the matching `meta.cell` config (options, app/data source slugs, etc.). For TanStack column-def construction with that wiring, use [`useDocyrusDataGrid`](/docs/web/hooks/use-docyrus-data-grid), which builds the variant **and** the column meta together. This hook is the lower-level component-resolution primitive.

### Why `editable-value` always returns `EditableValue`

`EditableValue` is itself a field-type dispatcher: internal sets (`INLINE_TYPES`, `INSTANT_SAVE_TYPES`, `EXPLICIT_SAVE_TYPES`, `POPOVER_TYPES`, `READ_ONLY_TYPES`) drive its read/edit behavior per field type. Returning the same component for every field type keeps the hook's API consistent (always returns a renderable component) and lets callers always render `` regardless of type.

### Out of scope

- Fetching enum options or relation records — pass them as props (`enumOptions`, etc.) when rendering the returned component.
- Wiring up the full data-grid (rows, view tabs, toolbar) — use [`useDocyrusDataGrid`](/docs/web/hooks/use-docyrus-data-grid) which calls `buildTanstackColumnDef` internally.

---

# useDocyrusFormView
URL: /docs/web/hooks/use-docyrus-form-view

One-call wiring of a Docyrus data source item to create, edit, and read-only layouts with shared field-component mapping, item loading, option hydration, and submit handling.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-docyrus-form-view
```

**Dependencies:**
- [@docyrus/app-utils](https://www.npmjs.com/package/@docyrus/app-utils)
- [@docyrus/api-client](https://www.npmjs.com/package/@docyrus/api-client)
- [@tanstack/react-query](https://tanstack.com/query/latest)

This hook is distributed as source. It requires an authenticated `RestApiClient` from `@docyrus/api-client` and a `QueryClientProvider` from `@tanstack/react-query` somewhere above your component tree.

## Overview

`useDocyrusFormView` is the one-call entry point for Docyrus record forms and detail views. It wires together:

- **data source metadata** (`fields`, enum expansions, relation targets)
- **item loading** for edit/view flows
- **local form state** compatible with the Docyrus form-field components
- **shared field-component resolution** via [`useDocyrusFieldComponent`](/docs/web/hooks/use-docyrus-field-component)
- **option hydration** for enum, user, and relation fields
- **submit handling** for create/update flows
- **layout helpers** (`renderField`, `renderLayout`)
- **optional click-to-edit detail mode** in read-only views via [`EditableRecordDetail`](/docs/web/docyrus/editable-record-detail)
- **computed fields** and imperative **field actions** driven by JSONata / query-builder rules
- **form-level actions** (`onFormLoad` / `onFormBeforeSubmit` / `onFormAfterSubmit`) and **form-level validations**
- **DB-free operation** — inject `dataSource` + `item` to render entirely from in-memory schema (no `getBySlug`)

The result is a single hook you can use to build:

- **create forms**
- **edit forms**
- **read-only record layouts**

without writing your own per-field switch statements.

> **Not on a Docyrus backend?** [`useDynamicFormView`](/docs/web/hooks/use-dynamic-form-view) is the backend-agnostic sibling of this hook. It shares the exact same rendering / computed / actions / validation engine but does no fetching — you supply the `fields`, `values`, static `enumOptions`, upload handlers, and an `onSubmit` sink to wire any backend.

## Centralized field-component mapping

The hook does **not** keep its own parallel field-type registry. Instead it resolves components from the shared `useDocyrusFieldComponent` / `FORM_FIELD_MAP` source of truth:

- **editable mode** → `useDocyrusFieldComponent(field.type, 'form-field')`
- **read-only mode** → `useDocyrusFieldComponent(field.type, 'value-renderer')`

That means `useDocyrusFormView`, `DynamicFormField`, `DynamicValue`, and `useDocyrusDataGrid` all stay aligned when a new Docyrus field type is added.

Behavior is determined like this:

1. If the field type has a registered **form-field component** and the field is not read-only, it renders as an editable form input.
2. Otherwise it renders with the registered **value renderer**.
3. In **create** mode, unsupported editable types default to `unsupportedFieldBehavior='skip'`.
4. In **edit/view** mode, unsupported or read-only types default to `unsupportedFieldBehavior='value'`.

## Backend connection

The hook supports three layers of backend work.

### 1) Data source metadata

By default the hook loads the data source through `createDataSourceClient(client).getBySlug(appSlug, dataSourceSlug, { expand: schemaExpand })` (where `schemaExpand` defaults to `'enums'`).

That fetch provides the field metadata used to:

- build the local `IField` shape for Docyrus form/value components
- read enum options for select-like fields
- derive companion columns that must be requested for composite fields
- detect relation target data sources

Two options let you adapt or bypass this fetch:

- **`schemaExpand`** — change or drop the `expand` query param. Pass `false`/`''` for backends (e.g. core/tenant system data sources) that don't support `expand`.
- **`dataSource`** — inject a pre-resolved schema object. When provided, the `getBySlug` call is **skipped entirely** and every downstream derivation reads from your object instead. See [DB-free / in-memory schema](#db-free--in-memory-schema).

### 2) Item loading

For **edit** and **view** flows, the hook resolves the record in this precedence order:

1. **`item`** — pre-resolved object; skips the item query entirely
2. **`collection.get(recordId, params)`** — generated/custom collection mode
3. **Direct API** — `GET /v1/apps/:appSlug/data-sources/:dataSourceSlug/items/:itemId`

The hook always sends `columns`, including companion fields needed by composite renderers.

### 3) Remote option loading

When needed, the hook hydrates option lists for dynamic selectors:

- **enum-backed select fields** (`field-select`, `field-radioGroup`, `field-enum`, `field-systemEnum`, `field-status`, `field-multiSelect`, `field-tagSelect`) → fallback `GET /v1/apps/enums` when the data-source metadata does not already contain options
- **user fields** (`field-userSelect`, `field-userMultiSelect`) → `GET /v1/users`
- **relation fields** (`field-relation`) →
  1. `GET /v1/apps/data-sources?expand=fields`
  2. resolve the target by `relationDataSourceId`
  3. query target items with a minimal `columns` set for labels + item mapping fields

You can disable user / relation fetches via `resolveUserOptions={false}` / `resolveRelationOptions={false}` or override any field with `enumOptions={{ [slug]: [...] }}`.

## Usage

Below are four complete usage patterns for the same Docyrus data source.

### 1) Create Item

Use `mode: 'create'` when you want to start from defaults and submit a brand-new record.

```tsx
'use client';

import { useDocyrusAuth } from '@docyrus/signin';

import { useDocyrusFormView } from '@docyrus/ui/library/hooks/use-docyrus-form-view';
import { Button } from '@docyrus/ui/primitives/ui/button';

export function CreateContactForm() {
  const { client } = useDocyrusAuth();

  if (!client) return null;

  const createView = useDocyrusFormView({
    client,
    appSlug: 'crm',
    dataSourceSlug: 'contacts',
    mode: 'create',
    gridColumns: 2,
    defaultValues: {
      status: 'lead'
    },
    fieldOrder: ['full_name', 'email', 'phone', 'status', 'notes'],
    fieldLayout: {
      notes: { colSpan: 'full' }
    }
  });

  return (
    <form
      onSubmit={async (event) => {
        event.preventDefault();
        await createView.submit();
      }}
      className="space-y-4">
      {createView.renderLayout()}

      <div className="flex items-center gap-2">
        
        
      </div>
    </form>
  );
}
```

### 2) Edit Item

Use `mode: 'edit'` with an `itemId` to load an existing record, keep the same field mapping, and submit updates back to Docyrus.

```tsx
'use client';

import { useDocyrusAuth } from '@docyrus/signin';

import { useDocyrusFormView } from '@docyrus/ui/library/hooks/use-docyrus-form-view';
import { Button } from '@docyrus/ui/primitives/ui/button';

export function EditContactForm({ contactId }: { contactId: string }) {
  const { client } = useDocyrusAuth();

  if (!client) return null;

  const editView = useDocyrusFormView({
    client,
    appSlug: 'crm',
    dataSourceSlug: 'contacts',
    itemId: contactId,
    mode: 'edit',
    gridColumns: 2,
    fieldOrder: ['full_name', 'email', 'phone', 'status', 'notes'],
    fieldLayout: {
      notes: { colSpan: 'full' },
      status: { description: 'Primary pipeline status' }
    }
  });

  return (
    <form
      onSubmit={async (event) => {
        event.preventDefault();
        await editView.submit();
      }}
      className="space-y-4">
      {editView.renderLayout()}

      <div className="flex items-center gap-2">
        
        
      </div>
    </form>
  );
}
```

### 3) View Item

Use `mode: 'view'` to render the same record as a read-only detail layout.

```tsx
'use client';

import { useDocyrusAuth } from '@docyrus/signin';

import { useDocyrusFormView } from '@docyrus/ui/library/hooks/use-docyrus-form-view';

export function ContactDetail({ contactId }: { contactId: string }) {
  const { client } = useDocyrusAuth();

  if (!client) return null;

  const detailView = useDocyrusFormView({
    client,
    appSlug: 'crm',
    dataSourceSlug: 'contacts',
    itemId: contactId,
    mode: 'view',
    gridColumns: 2,
    fieldOrder: ['full_name', 'email', 'phone', 'status', 'notes']
  });

  return detailView.renderLayout();
}
```

### 4) View Item Click to Edit

When `clickToEdit` is enabled and `renderLayout()` is called in `view` mode, the hook swaps the plain value grid for [`EditableRecordDetail`](/docs/web/docyrus/editable-record-detail). Fields stay read-only visually until the user clicks into a row, then saves inline changes through the normal Docyrus update pipeline.

```tsx
'use client';

import { useDocyrusAuth } from '@docyrus/signin';

import { useDocyrusFormView } from '@docyrus/ui/library/hooks/use-docyrus-form-view';

export function ContactInlineDetail({ contactId }: { contactId: string }) {
  const { client } = useDocyrusAuth();

  if (!client) return null;

  const inlineDetailView = useDocyrusFormView({
    client,
    appSlug: 'crm',
    dataSourceSlug: 'contacts',
    itemId: contactId,
    mode: 'view',
    clickToEdit: true,
    fieldOrder: ['full_name', 'email', 'phone', 'status', 'notes']
  });

  return inlineDetailView.renderLayout();
}
```

### Nested sections with fieldset + tabpanel + tab

Use `layout` when a plain flat grid is not enough. Every section renders its own grid with the active `gridColumns` count, and both fields and sections can span multiple columns.

```tsx
'use client';

import { useDocyrusAuth } from '@docyrus/signin';

import { useDocyrusFormView } from '@docyrus/ui/library/hooks/use-docyrus-form-view';
import { Button } from '@docyrus/ui/primitives/ui/button';

const contactLayout = [
  {
    id: 'identity',
    variant: 'fieldset',
    title: 'Identity',
    colSpan: 2,
    items: [
      { type: 'field', slug: 'full_name', colSpan: 2 },
      'email',
      'phone'
    ]
  },
  {
    id: 'sales-workspace',
    variant: 'tabpanel',
    title: 'Sales Workspace',
    colSpan: 'full',
    defaultTabId: 'overview',
    items: [
      {
        id: 'overview',
        variant: 'tab',
        title: 'Overview',
        items: [
          { type: 'field', slug: 'status', colSpan: 2 },
          'owner',
          { type: 'field', slug: 'expected_value', colSpan: 2 },
          { type: 'field', slug: 'next_step', colSpan: 2 }
        ]
      },
      {
        id: 'notes',
        variant: 'tab',
        title: 'Notes',
        items: [{ type: 'field', slug: 'notes', colSpan: 'full' }]
      }
    ]
  }
] as const;

export function EditContactWorkspace({ contactId }: { contactId: string }) {
  const { client } = useDocyrusAuth();

  if (!client) return null;

  const formView = useDocyrusFormView({
    client,
    appSlug: 'crm',
    dataSourceSlug: 'contacts',
    itemId: contactId,
    mode: 'edit',
    gridColumns: 4,
    layout: contactLayout
  });

  return (
    <form
      onSubmit={async (event) => {
        event.preventDefault();
        await formView.submit();
      }}
      className="space-y-4">
      {formView.renderLayout()}

      
    </form>
  );
}
```

### Collection mode

If your app already has a generated Docyrus collection, pass it in and the hook will use `collection.get`, `collection.create`, and `collection.update` instead of raw endpoints.

```tsx
const contacts = useCrmContactsCollection();

const formView = useDocyrusFormView({
  client,
  appSlug: 'crm',
  dataSourceSlug: 'contacts',
  itemId,
  collection: contacts
});
```

### DB-free / in-memory schema

Pass `dataSource` to render a form from schema you already hold in memory — the hook never calls `getBySlug`. Combine it with `item` (record data) and `layout` for a form that performs **no network requests at all** (useful for previews, the form builder, snapshot tests, or system data sources without a metadata route). Setting `enabled: false` additionally stops the relation-option fetch.

```tsx
'use client';

import { useDocyrusFormView } from '@docyrus/ui/library/hooks/use-docyrus-form-view';
import type { DataSource } from '@docyrus/app-utils';

// Schema + record already resolved elsewhere (cache, props, fixture, …)
const contactSchema: DataSource = {
  id: 'ds_contacts',
  slug: 'contacts',
  fields: [
    { id: '1', name: 'Full Name', slug: 'full_name', type: 'field-text' },
    { id: '2', name: 'Status', slug: 'status', type: 'field-select', options: { /* … */ } }
  ]
  // …other DataSource metadata
} as DataSource;

export function ContactPreview({ record }: { record: Record<string, unknown> }) {
  const previewView = useDocyrusFormView({
    client,
    appSlug: 'crm',
    dataSourceSlug: 'contacts',
    mode: 'view',
    dataSource: contactSchema, // ← skips getBySlug
    item: record,              // ← skips the item fetch
    enabled: false             // ← skips relation-option fetch (fully offline)
  });

  return previewView.renderLayout();
}
```

When `dataSource` is provided with `enabled: true`, the schema is still injected (no `getBySlug`) but live option fetches (`/v1/users`, relation targets, `/v1/apps/enums`) remain active — handy when you have the schema cached but still want fresh option lists.

## API Reference

### Parameters

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `client` | `RestApiClient` | — | Authenticated Docyrus API client. |
| `appSlug` | `string` | — | Slug of the app that owns the data source. |
| `dataSourceSlug` | `string` | — | Slug of the data source. |
| `itemId` | `string` | — | Record id for edit/view flows. |
| `mode` | `'create' \| 'edit' \| 'view'` | `itemId ? 'edit' : 'create'` | Explicit form mode. Use `'view'` for read-only layouts. |
| `item` | `Record<string, unknown> \| null` | — | Pre-resolved record. When provided, skips the item query. |
| `dataSource` | `DataSource \| null` | — | Pre-resolved data-source schema. When provided, the hook **skips the `getBySlug` metadata fetch entirely** and reads fields / metadata from this object. Pair with `item` + `layout` (and `enabled: false`) for a fully DB-free form. See [DB-free / in-memory schema](#db-free--in-memory-schema). |
| `collection` | `{ get?, create?, update? }` | — | Generated/custom collection used instead of direct REST calls. |
| `enabled` | `boolean` | `true` | Disable all remote queries while surrounding state is still loading. |
| `staleTime` | `number` | `30_000` | TanStack Query stale time for metadata, item, and remote-option queries. |
| `schemaExpand` | `string \| false` | `'enums'` | `expand` query param sent with the data-source schema fetch (so select/status fields carry their option metadata). Pass `false` (or `''`) to omit `expand` entirely for backends that don't support it — e.g. core/tenant system data sources. Ignored when `dataSource` is injected. |
| `disabled` | `boolean` | `false` | Disables editable fields globally. |
| `defaultValues` | `Record<string, unknown>` | — | Extra defaults merged after schema defaults and before the loaded item. |
| `itemQueryParams` | `DocyrusFormViewGetParams` | — | Extra query params for the item `get` request. `columns` is merged, not replaced. |
| `fieldSlugs` | `string[]` | — | Whitelist fields by slug before layout/rendering. |
| `fieldOrder` | `string[]` | — | Explicit field ordering. Unlisted fields sort after listed ones. |
| `hiddenFieldSlugs` | `string[]` | — | Hard-hide fields by slug. |
| `fieldLayout` | `Record<string, DocyrusFormViewFieldLayout>` | — | Per-field UI overrides: hidden/required/readOnly/disabled, colSpan, labels, descriptions, and prop overrides. |
| `layout` | `DocyrusFormViewLayoutItem[]` | — | Optional nested layout tree. Supports `fieldset`, `tabpanel`, and `tab` sections plus explicit field items. Visible fields not referenced in the tree are appended after the declared layout. |
| `mapField` | `(field, defaultMapped) => IField \| null` | — | Per-field transform after metadata normalization. Return `null` to drop the field completely. |
| `dynamicLabelTranslator` | `(label: string) => string` | — | Translate / override every field label before render. Called once per field with the schema label (`field.name`); return the text to display. Applied after `mapField`. See [Translating field labels](#translating-field-labels). |
| `dynamicEnumOptionTranslator` | `(option: EnumOption, field: IField) => string` | — | Translate / override every enum option label in dropdowns, chips, and read-only value rows. Called once per resolved option; return the display text. Key by `enums.<field.slug>.<option.slug>`; `slug` / `color` / `icon` are preserved. See [Translating enum options](#translating-enum-options). |
| `includeReadOnlyFields` | `boolean` | `mode !== 'create'` | Include fields that resolve to read-only display rows. |
| `unsupportedFieldBehavior` | `'skip' \| 'value'` | `'skip'` in create, `'value'` otherwise | Whether unsupported field types disappear or fall back to value-render mode. |
| `gridColumns` | `1 \| 2 \| 3 \| 4` | `2` | Default responsive column count used by `renderLayout()`. |
| `clickToEdit` | `boolean` | `false` | When `true` and `renderLayout()` is used in `view` mode, the hook renders [`EditableRecordDetail`](/docs/web/docyrus/editable-record-detail) instead of the simple value grid and persists inline saves through the standard update pipeline. |
| `resolveUserOptions` | `boolean` | `true` | Whether to fetch `/v1/users` for user selector fields. |
| `resolveRelationOptions` | `boolean` | `true` | Whether to resolve relation target options automatically. |
| `optionLimit` | `number` | `100` | Limit used when loading relation target items. |
| `enumOptions` | `Record<string, EnumOption[]>` | — | Field-level option overrides. Wins over static enums and remote fetches. |
| `transformSubmit` | `(payload, context) => payload` | — | Final payload transform before mutation. |
| `onSubmit` | `(payload, context) => Promise<unknown> \| unknown` | — | Full custom submit handler. When provided, bypasses default create/update logic. |
| `onSubmitSuccess` | `(result, payload) => void` | — | Called after a successful mutation. |
| `onSubmitError` | `(error, payload) => void` | — | Called after a failed mutation. |
| `formActions` | `FormAction[] \| null` | — | Form-level lifecycle actions evaluated on `onFormLoad`, `onFormBeforeSubmit`, and `onFormAfterSubmit`. Same block/step structure as field actions. See [Form-level actions](#form-level-actions). |
| `formCustomValidations` | `FormCustomValidationRule[] \| null` | — | Form-level validation rules evaluated on submit (after field-level validation passes). Failures surface in `formValidationErrors` as banner messages. See [Form-level validations](#form-level-validations). |

### `DocyrusFormViewFieldLayout`

| Field | Type | Description |
|-------|------|-------------|
| `hidden` | `boolean \| ((values) => boolean)` | Hide the field conditionally. |
| `required` | `boolean \| ((values) => boolean)` | Mark the field required conditionally. |
| `readOnly` | `boolean` | Force the field into value-render mode. |
| `disabled` | `boolean` | Disable editing without changing render mode. |
| `colSpan` | `1 \| 2 \| 3 \| 4 \| 'full'` | Width override used by `renderLayout()`. |
| `className` | `string` | Extra wrapper/field className. |
| `label` | `ReactNode` | Override the display label. |
| `description` | `ReactNode` | Description shown in read-only layout or available to your custom props. |
| `fieldProps` | `Partial
```

### Circular action protection

If action A sets field B and that triggers action B which sets field A (and so on), execution stops after 5 nested levels to prevent infinite loops. A warning is logged in development.

## Form-level actions

Where field actions react to a single field's `onFieldChange`, **form-level actions** react to the form's lifecycle. Pass them via the top-level `formActions` option. They share the exact same block/step structure as field actions (`FieldActionBlock[]`, the same step methods, the same JSONata / QB conditions).

```tsx
import type { FormAction } from '@docyrus/ui/components/form-fields';
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | Stable action id. |
| `name` | `string` | Optional label. |
| `triggerType` | `'onFormLoad' \| 'onFormBeforeSubmit' \| 'onFormAfterSubmit'` | Lifecycle event that fires the action. |
| `blocks` | `FieldActionBlock[]` | Ordered blocks — same shape as field actions (`conditionalItems` → `elseActions` → `unconditionalActions`). |

### Triggers

| Trigger | When it fires | Notes |
|---------|---------------|-------|
| `onFormLoad` | Once, when initial data finishes loading (immediately in `create` mode). | Guarded so it runs a single time per mount. Use it to seed defaults or pre-hide/disable fields based on the loaded record. |
| `onFormBeforeSubmit` | After field + form validation passes, **before** the API call. | May mutate field values (e.g. last-minute transforms) before the payload is built. |
| `onFormAfterSubmit` | After a successful API call. | The mutation result is available to expressions via the `$result` binding. |

```tsx
const formView = useDocyrusFormView({
  client,
  appSlug: 'crm',
  dataSourceSlug: 'contacts',
  mode: 'create',
  formActions: [
    {
      id: 'fa-load',
      triggerType: 'onFormLoad',
      blocks: [
        {
          id: 'b1',
          sortOrder: 0,
          conditionalItems: [
            {
              id: 'c1',
              condition: "source = 'import'",
              actions: [{ method: 'setFieldReadOnly', fieldSlug: 'email', readOnly: true }]
            }
          ],
          elseActions: [],
          unconditionalActions: []
        }
      ]
    }
  ]
});
```

Form-action property overrides accumulate just like field-action overrides and are cleared by `resetActionOverrides()`. When two layers touch the same property, priority is **computed formulas → field-action overrides → form-action overrides → `fieldLayout` callbacks → `IField` defaults**.

## Form-level validations

`formCustomValidations` are submit-time rules evaluated **after** all field-level validation passes. Each rule's `expression` must return `true` for the form to be valid; otherwise its `message` is collected into `formValidationErrors` and the submit is aborted.

```tsx
import type { FormCustomValidationRule } from '@docyrus/ui/components/form-fields';
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | Stable rule id. |
| `expression` | `string` | JSONata expression or QB rule-group JSON. Must return `true` to pass. Evaluated against current form values. |
| `message` | `string` | Banner message shown when the rule fails. |

Render `formValidationErrors` as a destructive banner above the form:

```tsx
import { Alert, AlertDescription } from '@docyrus/ui/primitives/ui/alert';

const formView = useDocyrusFormView({
  client,
  appSlug: 'crm',
  dataSourceSlug: 'deals',
  mode: 'edit',
  itemId: dealId,
  formCustomValidations: [
    {
      id: 'v1',
      // close date must be on/after the open date
      expression: 'close_date >= open_date',
      message: 'Close date cannot be earlier than the open date.'
    }
  ]
});

return (
  <form onSubmit={async (e) => { e.preventDefault(); await formView.submit(); }}>
    {formView.formValidationErrors.length > 0 && (
      
      
    )}
    {formView.renderLayout()}
  </form>
);
```

Field-level errors stay per-field in `validationErrors` (keyed by slug); form-level errors are global and live in `formValidationErrors`.

## Out of scope

- record comments, attachments, or activity timelines — compose those around the hook
- autosave — call `submit()` on your own schedule if needed
- server-side rendering data preload — this hook is intentionally client-first and React Query driven

---

# useDocyrusInstantMessageComposer
URL: /docs/web/hooks/use-docyrus-instant-message-composer

useDocyrusInstantMessageComposer hook.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-docyrus-instant-message-composer
```

## Usage

```tsx
import { useDocyrusInstantMessageComposer } from '@docyrus/ui/library/hooks/use-docyrus-instant-message-composer';

function MyComponent() {
  const result = useDocyrusInstantMessageComposer(...);
}
```

## API Reference

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `options` | `UseDocyrusInstantMessageComposerOptions` | `—` | — |

**Returns:** `UseDocyrusInstantMessageComposerResult`

---

# useDocyrusInventory
URL: /docs/web/hooks/use-docyrus-inventory

Shared app-utils inventory cache for Docyrus metadata (apps, data sources with fields/enums/views/forms, users, brands, preferences) plus a post-sign-in load() warm-up hook that drives an application loading dialog.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-docyrus-inventory
```

**Dependencies:**
- [@docyrus/app-utils](https://www.npmjs.com/package/@docyrus/app-utils)
- [@docyrus/api-client](https://www.npmjs.com/package/@docyrus/api-client)

This module ships two named exports:

- `getSharedDocyrusInventory(client)` — returns the process-wide shared `InventoryClient` for a given `RestApiClient`, creating it on first use (memoized in a `WeakMap` keyed by client). Pass the result into `createDataSourceClient` / `createDataViewClient` / `createDataFormClient` (`{ inventory }`) so every client shares one in-memory cache. `null` in → `null` out.
- `useDocyrusInventoryLoader(options)` — headless React hook that runs `inventory.load()` once per client (StrictMode-safe) right after sign-in, exposing determinate progress + status so a host app can render a loading dialog before routing to the home page.

## Why this exists

The `@docyrus/app-utils` inventory (`createInventoryClient`) caches everything a Docyrus app needs at startup — apps, data sources (with embedded `views` / `forms` / `fields`, and `enums` on select-type fields), users, brands, and tenant preferences — in one `GET /v1/apps/data-sources?expand=views,forms,fields` request (plus a request each for users / brands / preferences). Because the cache lives in the returned client's closure, a **single shared instance** is what lets:

1. a post-sign-in `load()` warm-up populate it behind a progress bar, and
2. every inventory-backed hook (`useDocyrusFormView`, `useDocyrusDataGrid`, `useDocyrusDataViewSelect`, …) read tenant metadata from that same warm cache instead of re-fetching per mount.

`getSharedDocyrusInventory` is the single source of that instance; the Docyrus hooks call it internally, so warming the cache once makes their schema / enum / view / form / relation reads cache hits.

## `getSharedDocyrusInventory(client)`

```tsx
import { getSharedDocyrusInventory } from '@docyrus/ui/library/hooks/use-docyrus-inventory';
import { createDataSourceClient } from '@docyrus/app-utils';

const inventory = getSharedDocyrusInventory(apiClient);
const dataSources = createDataSourceClient(apiClient, { inventory });

// No `expand` → served from the shared cache (fields incl. enums, views, forms embedded)
const contacts = await dataSources.getBySlug('crm', 'contacts');
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `client` | `RestApiClient \| null \| undefined` | The authenticated API client. |

**Returns:** `InventoryClient` (or `null` when `client` is nullish).

## `useDocyrusInventoryLoader(options)`

Runs `inventory.load()` once, as soon as it is `enabled` and a `client` exists, and re-runs automatically when the client identity changes (e.g. a tenant switch that rebuilds the client). Failures do not throw — `status` becomes `'error'` and `reload()` retries; the app can still run (inventory-backed reads fall back to the API).

```tsx
import { useDocyrusAuth } from '@docyrus/signin';
import { useDocyrusInventoryLoader } from '@docyrus/ui/library/hooks/use-docyrus-inventory';

function InventoryGate({ children }) {
  const { client, status } = useDocyrusAuth();
  const { status: loadStatus, progress, error, reload } = useDocyrusInventoryLoader({
    client,
    enabled: status === 'authenticated'
  });

  if (loadStatus === 'ready') return children;

  return (
    
  );
}
```

### Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `client` | `RestApiClient \| null \| undefined` | `—` | The authenticated API client. The loader waits until this is set. |
| `enabled` | `boolean` | `true` | Gate the warm-up (e.g. only once authenticated). Still requires a non-null `client`. |
| `include` | `InventoryLoadStepId[]` | `['apps','data-sources','users','brands','preferences']` | Which tenant-wide steps to warm. Drop `'users'` when the signed-in user may lack the `Users.Read.All` scope. |
| `configAppIds` | `string[]` | `VITE_APP_ID` (if set) | App ids whose config + user-config to warm. Pass `[]` to skip. |
| `force` | `boolean` | `true` | Invalidate caches before loading so the warm-up issues fresh network calls. |

### Result

| Field | Type | Description |
|-------|------|-------------|
| `inventory` | `InventoryClient \| null` | The shared inventory for the current client. |
| `status` | `'idle' \| 'loading' \| 'ready' \| 'error'` | Warm-up lifecycle. |
| `progress` | `InventoryLoadProgress \| null` | Latest progress event — drive a determinate bar with `progress.ratio`. |
| `error` | `unknown` | Present when `status === 'error'`. |
| `result` | `InventoryLoadResult \| null` | The loaded payload once ready. |
| `isLoading` | `boolean` | `true` while warming. |
| `isReady` | `boolean` | `true` once warmed successfully. |
| `reload` | `() => void` | Re-run the warm-up (Retry button, or after a tenant switch). |

---

# useDocyrusKanban
URL: /docs/web/hooks/use-docyrus-kanban

One-call wiring of a Docyrus data source to a fully configured Kanban board with select/status/radio-group, user, and date columns, drag-to-update persistence, final-zone integration, and a standard Docyrus card layout.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-docyrus-kanban
```

**Dependencies:**
- [@docyrus/app-utils](https://www.npmjs.com/package/@docyrus/app-utils)
- [@docyrus/api-client](https://www.npmjs.com/package/@docyrus/api-client)
- [@tanstack/react-query](https://tanstack.com/query/latest)
- [@dnd-kit/core](https://www.npmjs.com/package/@dnd-kit/core)
- [@dnd-kit/sortable](https://www.npmjs.com/package/@dnd-kit/sortable)
- [react-querybuilder](https://react-querybuilder.js.org)

This hook is distributed as source. It expects an authenticated `RestApiClient` from `@docyrus/api-client` and a `QueryClientProvider` from `@tanstack/react-query` somewhere above your component tree.

## Overview

`useDocyrusKanban` is the kanban-first companion to [`useDocyrusDataGrid`](/docs/web/hooks/use-docyrus-data-grid). It wires a Docyrus data source to a fully configured `

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `groupByFieldSlug` | `string` | — | **Required.** Slug of the field whose values become kanban columns. |
| `data` | `Array<TData>` | — | Pre-resolved rows. When provided, the hook skips its internal items query. |
| `collection` | `DocyrusKanbanCollection<TData>` | — | TanStack DB collection. Optional `update` and `remove` methods are wired to drag-move and the default delete action. |
| `listParams` | `DocyrusKanbanListParams` | — | Extra query params merged on top of the view-derived payload. |
| `defaultLimit` | `number` | `200` | Default page size when no `limit` is supplied via `listParams`. |
| `enableItemsQuery` | `boolean` | `true` when no `data` | Toggle the internal items query. |
| `dateGroupBy` | `'day' \| 'week' \| 'month'` | `'day'` | Initial date bucket granularity. The toolbar switch overrides this at runtime. |
| `userGroupBy` | `'user' \| 'team'` | `'user'` | Initial user grouping mode for `field-userSelect`. |
| `showAllColumns` | `boolean` | `true` | Initial state of the "Show all" switch (enum group-by only). |
| `avatarColumn` | `string` | — | Field slug bound to the card avatar (icon/color/image). |
| `titleColumn` | `string` | — | Field slug bound to the card title. |
| `descriptionColumn` | `string` | — | Field slug bound to the card description. |
| `userColumn` | `string` | — | Field slug bound to the user shown in the card footer. |
| `cardContent` | `(ctx) => ReactNode` | — | Free-form card body. Receives `{ row, column }`. |
| `cardMenuItems` | `Array<DocyrusKanbanCardMenuItem<TData>>` \| `(row, defaults) => Array<...>` | — | Override the action menu. The function form keeps the default Open/Edit/Delete entries available. |
| `cardActions` | `Array<'open' \| 'edit' \| 'delete'>` | `['open', 'edit', 'delete']` | Whitelist of the default actions. |
| `onCardOpen` | `(row) => void` | — | Wired to the default **Open** menu item. |
| `onCardEdit` | `(row) => void` | — | Wired to the default **Edit** menu item. |
| `onCardDelete` | `(row) => Promise<void> \| void` | — | Custom delete handler. When omitted the hook calls `collection.remove(id)` or `DELETE /items/:id` after a confirmation dialog. |
| `onCardClick` | `(row) => void` | — | Click handler fired when the card body is clicked. |
| `enableViewSelect` | `boolean` | `true` | Show the saved-view picker in the toolbar. |
| `enableSearchInput` | `boolean` | `true` | Show the search input. |
| `enableDateGroupMenu` | `boolean` | `true` | Show the Day/Week/Month picker when grouping by date. |
| `enableUserGroupMenu` | `boolean` | `true` | Show the User/Team picker when grouping by user. |
| `enableShowAllColumnsSwitch` | `boolean` | `true` | Show the "Show all" switch when grouping by enum. |
| `enableReloadButton` | `boolean` | `true` | Show the reload button. |
| `onReload` | `() => void` | — | Called when the reload button is clicked, after the internal `refetch`. |
| `searchPlaceholder` | `string` | `'Search…'` | Placeholder for the toolbar search input. |
| `searchDebounceMs` | `number` | `300` | Debounce in ms before the search input is sent as `filterKeyword`. |
| `toolbarClassName` | `string` | — | Extra className for the toolbar root. |
| `toolbarStartContent` | `ReactNode` | — | Extra node prepended to the left side of the toolbar. |
| `toolbarEndContent` | `ReactNode` | — | Extra node appended to the right side of the toolbar. |
| `onItemMove` | `(params) => void` | — | Fired when a card is dropped into a different column. Runs alongside the built-in mutation. |
| `onItemMoveCommit` | `(params) => Promise<void> \| void` | — | Replace the built-in `PATCH` with a custom handler. Throw to abort the move. |

### Return Value

| Property | Type | Description |
|----------|------|-------------|
| `toolbar` | `ReactNode` | Pre-wired toolbar element ready to render above the board. |
| `board` | `ReactNode` | Pre-wired kanban board element. Render directly. |
| `items` | `Array<TData>` | Resolved rows passed to the board. |
| `resolvedListParams` | `DocyrusKanbanListParams` | The list params actually sent to the backend. |
| `groupByField` | `DataSourceField \| undefined` | The field metadata used to derive columns. |
| `columns` | `Array<DocyrusKanbanColumnMeta>` | Ordered metadata for every rendered column (including counts). |
| `columnsItems` | `Record<string, Array<TData>>` | Items grouped by `column.id`. |
| `dateGroupBy` | `'day' \| 'week' \| 'month'` | Active date grouping. |
| `setDateGroupBy` | `(value) => void` | Programmatically switch date grouping. |
| `userGroupBy` | `'user' \| 'team'` | Active user grouping. |
| `setUserGroupBy` | `(value) => void` | Programmatically switch user grouping. |
| `showAllColumns` | `boolean` | Active state of the "Show all" switch. |
| `setShowAllColumns` | `(value) => void` | Programmatically toggle the switch. |
| `views` | `Array<SavedDataGridView>` | Saved views mapped from the backend shape. |
| `fields` | `Array<FullField>` | Fields mapped for `react-querybuilder`. |
| `dataSource` | `DataSource \| undefined` | Raw data source metadata response. |
| `activeViewId` | `string` | Id of the currently active view. |
| `setActiveViewId` | `(viewId) => void` | Programmatically switch views. |
| `reload` | `() => void` | Triggers refetch of the data source, views, and items queries plus the optional `onReload` callback. |
| `isLoading` | `boolean` | `true` until all queries have resolved. |
| `error` | `Error \| null` | First error from any of the queries. |
| `refetch` | `() => void` | Alias for `reload`. |

## Drag-and-drop persistence

When a card is dropped into a different column the hook computes a payload based on the field type and either:

- calls `collection.update(id, payload)` if the consumer passed a TanStack DB collection with an `update` method, **or**
- issues a `PATCH /v1/apps/:appSlug/data-sources/:dataSourceSlug/items/:id` with the `RestApiClient` from `@docyrus/signin`.

| Group-by field | Payload sent on drop |
|----------------|----------------------|
| `field-select`, `field-radioGroup`, `field-status` | `{ [fieldSlug]: <enumOptionId> }` |
| `field-userSelect` (`userGroupBy: 'user'`) | `{ [fieldSlug]: <userId> }` |
| `field-userSelect` (`userGroupBy: 'team'`) | _(no-op — teams aren't writable on the user reference)_ |
| `field-date`, `field-dateTime` | _(no-op — bucketing is derived, not stored)_ |

Pass `onItemMoveCommit` to skip the built-in `PATCH` entirely (e.g. for optimistic updates with rollback) and `onItemMove` to mirror the change in local state without replacing the mutation.

## Field type → column derivation matrix

| Docyrus `type` | Column id | Column label | Color/icon source | Final-zone integration |
|----------------|-----------|--------------|-------------------|-------------------------|
| `field-select` | enum option `id` (or `slug`) | enum option `name` | enum option `color` / `icon` | — |
| `field-radioGroup` | enum option `id` (or `slug`) | enum option `name` | enum option `color` / `icon` | — |
| `field-status` | enum option `id` (or `slug`) | enum option `name` | enum option `color` / `icon` | options where `is_final_option === true` |
| `field-userSelect` (user) | user id | full name (or email) | user `photo` | — |
| `field-userSelect` (team) | team id | team `name` | — | — |
| `field-date`, `field-dateTime` | bucket key (`YYYY-MM-DD` / `YYYY-Www` / `YYYY-MM`) | localized label | — | — |

### Out of scope

- `field-relation`, `field-multiSelect`, and `field-tagSelect` are intentionally not surfaced as group-by candidates — relation fields would require additional metadata to render meaningful column headers and multi-value fields don't map cleanly onto a single column. If you need to group by one of these, render your own board with the same `useDocyrusDataViewSelect` wiring.

---

# useDocyrusLogActivity
URL: /docs/web/hooks/use-docyrus-log-activity

useDocyrusLogActivity hook.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-docyrus-log-activity
```

## Usage

```tsx
import { useDocyrusLogActivity } from '@docyrus/ui/library/hooks/use-docyrus-log-activity';

function MyComponent() {
  const result = useDocyrusLogActivity(...);
}
```

## API Reference

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `options` | `UseDocyrusLogActivityOptions` | `—` | — |

**Returns:** `UseDocyrusLogActivityResult`

---

# useDocyrusMapView
URL: /docs/web/hooks/use-docyrus-map-view

Build Docyrus-backed map pages from a locationSelect field with saved views, marker models, and ready-to-render Leaflet or Google Maps canvases.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-docyrus-map-view
```

**Dependencies:**
- [@docyrus/app-utils](https://www.npmjs.com/package/@docyrus/app-utils)
- [@docyrus/api-client](https://www.npmjs.com/package/@docyrus/api-client)
- [@tanstack/react-query](https://tanstack.com/query/latest)
- [react-leaflet](https://react-leaflet.js.org)
- [leaflet](https://leafletjs.com)
- [@vis.gl/react-google-maps](https://visgl.github.io/react-google-maps/)

This hook is distributed as source. It expects an authenticated Docyrus client, a `QueryClientProvider`, and a data source that includes at least one `field-locationSelect` field.

## Overview

`useDocyrusMapView` is the map-first companion to [`useDocyrusDataGrid`](/docs/web/hooks/use-docyrus-data-grid):

- loads the active Docyrus data source metadata
- auto-detects the first `field-locationSelect` field, or uses the slug you provide
- keeps saved-view filtering, sorting, and search wiring from `useDocyrusDataGrid`
- appends required map columns (`id`, location, title, popup fields) even when a saved view hides them
- transforms records into provider-agnostic marker objects
- returns ready-to-render helpers for both **Leaflet** and **Google Maps**

The hook is designed for pages where records stay in Docyrus, but the primary surface is a map instead of a table.

## Supported map providers

### 1. Leaflet

Use [`DocyrusLeafletMapView`](#docyrusleafletmapview) when you want the built-in Docyrus UI map stack:

- no API key requirement
- theme-aware tile layers
- clustering
- custom Docyrus map controls (zoom, fullscreen, locate)

### 2. Google Maps

Use [`DocyrusGoogleMapView`](#docyrusgooglemapview) when you want Google basemaps.

Provide the key either with the hook/component `googleMapsApiKey` prop or through `VITE_GOOGLE_MAPS_API_KEY`.

## Usage

### Leaflet page

```tsx
'use client';

import { useDocyrusAuth } from '@docyrus/signin';

import {
  DocyrusLeafletMapView,
  useDocyrusMapView
} from '@docyrus/ui/library/hooks/use-docyrus-map-view';

import { useBaseOrganizationCollection } from '@/db/collections/base-organization.collection';

export function OrganizationLocationsPage() {
  const { client } = useDocyrusAuth();

  if (!client) return null;

  const collection = useBaseOrganizationCollection();

  const mapView = useDocyrusMapView({
    client,
    appSlug: 'base',
    dataSourceSlug: 'organization',
    collection,
    locationFieldSlug: 'map_location',
    titleFieldSlug: 'name',
    descriptionFieldSlugs: ['address', 'city'],
    searchPlaceholder: 'Search organizations',
    enableGroupMenu: false,
    enableDisplayMenu: false,
    enableRowHeightMenu: false
  });

  return (
    <div className="space-y-4">
      {mapView.toolbar}

      
    </div>
  );
}
```

### Google Maps page

```tsx
'use client';

import { useDocyrusAuth } from '@docyrus/signin';

import {
  DocyrusGoogleMapView,
  useDocyrusMapView
} from '@docyrus/ui/library/hooks/use-docyrus-map-view';

export function WarehouseMapPage() {
  const { client } = useDocyrusAuth();

  if (!client) return null;

  const mapView = useDocyrusMapView({
    client,
    appSlug: 'base',
    dataSourceSlug: 'warehouse',
    locationFieldSlug: 'location',
    titleFieldSlug: 'name',
    descriptionFieldSlugs: ['city', 'status'],
    googleMapsApiKey: import.meta.env.VITE_GOOGLE_MAPS_API_KEY
  });

  return (
    
  );
}
```

## How the query is built

Internally the hook reuses the saved-view state from `useDocyrusDataGrid`, then creates its own items query with a stronger `columns` list.

That means a user can save a view that hides `map_location`, but the hook will still request:

- `id`
- the location field
- the resolved title field
- any popup/description fields you configured

So markers keep rendering correctly while the rest of the data-view behavior still follows the active Docyrus view.

## Field resolution

### Location field

Resolution order:

1. `locationFieldSlug`
2. first field with `type === 'field-locationSelect'`

### Title field

Resolution order:

1. `titleFieldSlug`
2. first matching slug from: `name`, `title`, `label`, `subject`, `display_name`, `displayName`, `commercial_title`, `short_name`
3. first text-like field that is not the location field

### Description fields

Resolution order:

1. `descriptionFieldSlugs`
2. first matching slugs from: `description`, `details`, `address`, `city`, `district`, `country`, `state`, `province`, `status`, `type`

### Marker visual (image + icon)

Each marker can render as either a circular avatar (from an image field) or a Docyrus icon, with a configurable priority.

**Image field** (`markerImageFieldSlug`):
- Reads `field-image` / `field-file` payloads (array of `{ signed_url, url, src }`)
- Renders as a 36×36 circular avatar with a white ring

**Icon field** (`markerIconFieldSlug`):
- Reads a Docyrus icon identifier string such as `"huge building-06"` or `"fal star"`
- Auto-detected from `field-icon` type or the `icon` slug when omitted
- Renders the same SVG asset used by `DocyrusIcon` inside a 32×32 white badge

**Priority** (`markerPriority`):
- `'image'` (default): image when present → icon when present → default `MapPin`
- `'icon'`: icon when present → default `MapPin` (image is ignored)

**Icon color** (`markerIconColorFieldSlug` + `markerIconColor`):
- Per-record color via the field, with a static fallback through `markerIconColor`
- Accepts hex, `rgb()`, CSS variables, or Tailwind tokens like `"emerald-500"` (resolved via `resolveColorHex`)
- Leaflet recolors the icon itself via CSS `mask-image`
- Google Maps renders the icon URL natively and does not support recoloring; the color value is ignored on that provider

The hook exposes the resolved values on each marker as `marker.imageUrl`, `marker.iconUrl`, and `marker.iconColor`. Custom `renderMarkerIcon` / `getMarkerIcon` callbacks should return `null` (Leaflet) or fall through (Google) when either is set to let the built-in renderer take over.

### Viewport filter

When `enableViewportFilter` is `true`, `markers` / `mappedItems` are narrowed to records whose `position` falls inside the active map bounds. `allMarkers` keeps the unfiltered set.

Two modes:

- **`auto`** (default) — every pan/zoom updates the filter. Side lists and counts feel "live".
- **`manual`** — the filter only applies when `searchThisArea()` is called. `isViewportStale` becomes `true` when the user moves the map without confirming, perfect for an Airbnb-style button.

```tsx
// Manual mode "Search this area" button
{mapView.isViewportStale && (
  
)}
```

Wire the map → hook connection by passing `mapView.setViewportBounds` to the `onViewportChange` prop of `DocyrusLeafletMapView` / `DocyrusGoogleMapView`.

## API Reference

### `useDocyrusMapView(options)`

The hook accepts all `useDocyrusDataGrid` options except `enableItemsQuery`, `showSelectColumn`, and `enableRowMarkers`, plus the options below.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `locationFieldSlug` | `string` | auto | Explicit location field slug. Use when the data source has multiple `field-locationSelect` fields. |
| `titleFieldSlug` | `string` | auto | Field slug used for marker titles and side-list labels. |
| `descriptionFieldSlugs` | `string[]` | auto | Extra fields appended into popup text. |
| `markerImageFieldSlug` | `string` | — | Field whose value resolves to an image URL (e.g. `field-image` / `field-file` payload). Used as the marker's circular avatar. |
| `markerIconFieldSlug` | `string` | auto | Field whose value is a Docyrus icon identifier (e.g. `huge building-06`). Auto-detects `field-icon` type or the `icon` slug. |
| `markerIconColorFieldSlug` | `string` | — | Field whose value is a CSS color (hex, `rgb()`, Tailwind token like `emerald-500`). Tints the icon in Leaflet via CSS `mask-image`. |
| `markerIconColor` | `string` | — | Static fallback color used when the per-record color field is empty. |
| `markerPriority` | `'image' \| 'icon'` | `'image'` | Which source wins when both fields are populated. `'image'` falls back to icon when image is empty; `'icon'` always renders the icon when present. |
| `enableViewportFilter` | `boolean` | `false` | Narrow `markers` / `mappedItems` to records inside the map's current visible bounds. `allMarkers` keeps the unfiltered set. |
| `viewportFilterMode` | `'auto' \| 'manual'` | `'auto'` | `'auto'` re-filters on every pan/zoom. `'manual'` only filters when `searchThisArea()` is called — pair with an Airbnb-style "Search this area" button via `isViewportStale`. |
| `enableMarkerDrag` | `boolean` | `false` | Make every marker draggable. On drop, the hook calls `onMarkerMove` (if provided) or PATCHes the resolved location field of the record. |
| `onMarkerMove` | `(marker, newPosition) => void \| Promise<void>` | — | Custom drop handler. Default behavior: reverse-geocodes the new coordinates, PATCHes the location field with `{ latitude, longitude, address }`, then `reload()`s. |
| `basemaps` | `Array<DocyrusBasemapId \| DocyrusBasemapDefinition> \| false` | — | Basemaps to surface in the in-map picker. Built-in ids: `'street'`, `'satellite'`, `'hybrid'`, `'terrain'`. Pass custom `DocyrusBasemapDefinition` for non-default tile servers. |
| `defaultBasemap` | `string` | first entry | Initially selected basemap id. |
| `markerTemplate` | `string` | — | Handlebars-style template for popup body text (e.g. `"{{name}} — {{city}}"`). |
| `getMarker` | `(item, context) => DocyrusMapMarker \| null` | — | Override marker generation completely. Return `null` to skip a record. |
| `defaultCenter` | `{ lat: number; lng: number }` | Ankara | Fallback center used when there are no mapped records. |
| `defaultZoom` | `number` | `6` | Base zoom level when the map starts without fitted bounds. |
| `focusedZoom` | `number` | `14` | Zoom level used when the result set has a single marker. |
| `fitBoundsPadding` | `number` | `48` | Padding used when fitting multiple markers into view. |
| `autoSelectSingleMarker` | `boolean` | `true` | Opens the only marker automatically when the query returns exactly one mapped record. |
| `googleMapsApiKey` | `string \| null` | `VITE_GOOGLE_MAPS_API_KEY` | API key forwarded to `DocyrusGoogleMapView`. |
| `onMapClick` | `(position: DocyrusMapPoint) => void` | — | Called when the user clicks an empty area of the map (not a marker). Used to power click-to-locate flows for unmapped records. |

### Return value

| Property | Type | Description |
|----------|------|-------------|
| `toolbar` | `ReactNode` | Prebuilt Docyrus data-view toolbar from `useDocyrusDataGrid`. |
| `table` | `Table<TData>` | Underlying TanStack table used by the toolbar and saved-view editor. |
| `items` | `TData[]` | All fetched records for the active view. |
| `markers` | `DocyrusMapMarker<TData>[]` | Mapped records transformed into provider-agnostic marker models. Filtered by the active viewport when `enableViewportFilter` is on. |
| `allMarkers` | `DocyrusMapMarker<TData>[]` | All resolved markers before viewport filtering. Use this for the underlying dataset (e.g. counts or "show all" links). |
| `mappedItems` | `TData[]` | Records that produced markers successfully. Also viewport-filtered. |
| `unmappedItems` | `TData[]` | Records without usable coordinates. |
| `viewportBounds` | `DocyrusMapBounds \| null` | Bounds reported by the active map provider on its last `moveend` / `idle` event. |
| `setViewportBounds` | `(bounds \| null) => void` | Wired internally — pass to `DocyrusLeafletMapView` / `DocyrusGoogleMapView` via `onViewportChange`. |
| `isViewportStale` | `boolean` | `true` when the map has moved since the last applied viewport filter (manual mode). |
| `searchThisArea` | `() => void` | Apply the current viewport as the active filter (manual mode). |
| `clearViewportFilter` | `() => void` | Remove the viewport filter and restore the full marker set. |
| `enableMarkerDrag` | `boolean` | Mirrors the input option — pass to a map view's `draggableMarkers` prop. |
| `handleMarkerMove` | `(marker, newPosition) => Promise<void>` | Default drop handler wired to the Docyrus client — pass to a map view's `onMarkerMove` prop. |
| `availableBasemaps` | `DocyrusBasemapDefinition[]` | Resolved basemap list after expanding ids. Pass to a map view's `basemaps` prop. |
| `activeBasemap` | `DocyrusBasemapDefinition \| null` | Currently selected basemap. Pass to a map view's `activeBasemap` prop. |
| `setActiveBasemap` | `(id: string) => void` | Switch the active basemap. Pass to a map view's `onBasemapChange` prop. |
| `locationField` | `DataSourceField \| null` | Resolved `field-locationSelect` definition. |
| `titleField` | `DataSourceField \| null` | Resolved title field definition. |
| `descriptionFields` | `DataSourceField[]` | Resolved popup/description fields. |
| `hasLocationField` | `boolean` | `true` when a usable location field was resolved on the data source. |
| `defaultZoom` | `number` | Mirrors the resolved option — pass to a map view's `defaultZoom` prop. |
| `focusedZoom` | `number` | Mirrors the resolved option — pass to a map view's `focusedZoom` prop. |
| `fitBoundsPadding` | `number` | Mirrors the resolved option — pass to a map view's `fitBoundsPadding` prop. |
| `views` | `SavedDataGridView[]` | Saved views from `useDocyrusDataGrid`. |
| `fields` | `DataSourceField[]` | Full field list from `useDocyrusDataGrid`. |
| `dataSource` | `DataSourceMetadata \| null` | Resolved Docyrus data source metadata. |
| `activeViewId` | `string \| null` | Currently active saved view id. |
| `setActiveViewId` | `(id) => void` | Switch the active saved view. |
| `onMapClick` | `((position) => void) \| undefined` | Mirrors the option — pass to a map view's `onMapClick` prop. |
| `requestedColumns` | `string` | Final comma-separated columns string sent to the items endpoint. |
| `resolvedListParams` | `DocyrusDataGridListParams` | Full query payload passed to the Docyrus items endpoint. |
| `center` | `{ lat: number; lng: number }` | Computed center for the current marker set. |
| `bounds` | `{ north; south; east; west } \| null` | Bounding box for the current marker set. |
| `selectedMarkerId` | `string \| null` | Currently selected marker id. Updated by popup open/close events. |
| `selectedMarker` | `DocyrusMapMarker<TData> \| null` | Full selected marker object. |
| `selectMarker` | `(id: string) => void` | Programmatically select a marker (e.g. from a side list). Pass to `onSelectMarker`. |
| `setSelectedMarkerId` | `(id: string \| null) => void` | Raw selection setter — prefer `selectMarker` / `clearSelectedMarker`. |
| `clearSelectedMarker` | `() => void` | Clears the active selection. |
| `counts` | `{ total; mapped; unmapped }` | Summary metrics for the active result set. |
| `googleMapsApiKey` | `string \| null` | Resolved Google Maps API key. |
| `reload` | `() => void` | Refetches the saved-view metadata and the map items query. |
| `isLoading` | `boolean` | Combined loading state for metadata + items. |
| `error` | `Error \| null` | First query error, if any. |

## `DocyrusLeafletMapView`

Renders the hook's marker model on top of the Docyrus UI Leaflet map.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `markers` | `DocyrusMapMarker<TData>[]` | — | Marker models from `useDocyrusMapView`. |
| `center` | `{ lat; lng }` | — | Center point used when bounds are not available. |
| `bounds` | `DocyrusMapBounds \| null` | — | Bounding box used for `fitBounds`. |
| `defaultZoom` | `number` | `6` | Base zoom level. |
| `focusedZoom` | `number` | `14` | Zoom level for a single marker. |
| `fitBoundsPadding` | `number` | `48` | Padding used in `fitBounds`. |
| `selectedMarkerId` | `string \| null` | — | Tracks the currently selected marker for list ↔ map synchronization. Does not control popup visibility directly — popups are managed by Leaflet natively. |
| `onSelectMarker` | `(id: string \| null) => void` | — | Called when a marker popup opens or closes, and when the map background is clicked. |
| `onMapClick` | `(position) => void` | — | Called on a click on empty map area (not a marker). Reverse-geocodes the position and re-fires with `address`. |
| `onEditMarker` | `(marker) => void` | — | Edit button handler used by the built-in popup. |
| `onViewportChange` | `(bounds \| null) => void` | — | Fires on `moveend` with the new visible bounds. Pass `mapView.setViewportBounds` here to power viewport filtering. |
| `draggableMarkers` | `boolean` | `false` | Make each marker draggable. |
| `onMarkerMove` | `(marker, newPosition) => void \| Promise<void>` | — | Fired after a marker is dropped. Pass `mapView.handleMarkerMove` for default PATCH+reload behavior. |
| `allMarkersCount` | `number` | — | Underlying marker count before viewport filtering. When provided and non-zero, the map keeps rendering even if the filtered `markers` array is empty (so panning to an area without records doesn't unmount the map). Pass `mapView.allMarkers.length`. |
| `basemaps` | `DocyrusBasemapDefinition[]` | — | Basemap options to surface in the in-map picker. Pass `mapView.availableBasemaps`. Picker shows when at least 2 entries are provided. |
| `activeBasemap` | `DocyrusBasemapDefinition \| null` | — | Currently selected basemap. Pass `mapView.activeBasemap`. |
| `onBasemapChange` | `(id: string) => void` | — | Called when the user picks a different basemap. Pass `mapView.setActiveBasemap`. |
| `renderPopup` | `(marker) => ReactNode` | default popup | Custom popup renderer. |
| `renderMarkerIcon` | `(marker, isSelected) => ReactNode` | default pin | Custom marker icon renderer. Called with `isSelected=false` on creation and `isSelected=true/false` imperatively when the popup opens/closes. |
| `emptyState` | `ReactNode` | built-in | Custom empty state when no markers exist. |
| `className` | `string` | — | Wrapper class name. |

## `DocyrusGoogleMapView`

Renders the same marker model on Google Maps.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `apiKey` | `string \| null` | env | Google Maps API key. When absent, the component renders a graceful fallback. |
| `markers` | `DocyrusMapMarker<TData>[]` | — | Marker models from `useDocyrusMapView`. |
| `center` | `{ lat; lng }` | — | Center point used when bounds are not available. |
| `bounds` | `DocyrusMapBounds \| null` | — | Bounding box used for `fitBounds`. |
| `defaultZoom` | `number` | `6` | Base zoom level. |
| `focusedZoom` | `number` | `14` | Zoom level for a single marker. |
| `fitBoundsPadding` | `number` | `48` | Padding used in `fitBounds`. |
| `defaultMapType` | `DocyrusGoogleMapType` | `'roadmap'` | Initial Google `mapTypeId`. Ignored when `activeBasemap` is provided. |
| `selectedMarkerId` | `string \| null` | — | Opens the selected marker popup. |
| `onSelectMarker` | `(id: string \| null) => void` | — | Called when a marker or the map background is clicked. |
| `onMapClick` | `(position) => void` | — | Called on a click on empty map area (not a marker). |
| `onEditMarker` | `(marker) => void` | — | Edit button handler used by the built-in popup. |
| `onViewportChange` | `(bounds \| null) => void` | — | Fires on Google's `idle` event with the new visible bounds. Pass `mapView.setViewportBounds` here to power viewport filtering. |
| `draggableMarkers` | `boolean` | `false` | Make each marker draggable. |
| `onMarkerMove` | `(marker, newPosition) => void \| Promise<void>` | — | Fired after a marker is dropped. Pass `mapView.handleMarkerMove` for default PATCH+reload behavior. |
| `allMarkersCount` | `number` | — | Underlying marker count before viewport filtering. Keeps the map mounted when the filtered `markers` array is empty. Pass `mapView.allMarkers.length`. |
| `basemaps` | `DocyrusBasemapDefinition[]` | — | Basemap options to surface in the in-map picker. Pass `mapView.availableBasemaps`. Picker shows when at least 2 entries are provided. |
| `activeBasemap` | `DocyrusBasemapDefinition \| null` | — | Currently selected basemap. Pass `mapView.activeBasemap`. |
| `onBasemapChange` | `(id: string) => void` | — | Called when the user picks a different basemap. Pass `mapView.setActiveBasemap`. |
| `getMarkerIcon` | `(marker, isSelected) => string \| DocyrusMapMarkerIcon \| null` | default | Custom Google icon resolver. Return `null` to fall through to the built-in image/icon logic. |
| `renderPopup` | `(marker) => ReactNode` | default popup | Custom info-window renderer. |
| `emptyState` | `ReactNode` | built-in | Custom empty state when no markers exist. |
| `className` | `string` | — | Wrapper class name. |

## Type Exports

| Type | Description |
|------|-------------|
| `DocyrusMapMarker<TData>` | Provider-agnostic marker model with `id`, `title`, `position`, optional `imageUrl` / `iconUrl` / `iconColor`, and the underlying `item`. |
| `DocyrusMapMarkerBuilderContext<TData>` | Context passed to a custom `getMarker` builder. |
| `DocyrusMapPoint` | `{ lat: number; lng: number }`. |
| `DocyrusMapBounds` | `{ north; south; east; west }` rectangle. |
| `DocyrusNormalizedLocation` | Shape used internally for location-field values (`lat`, `lng`, plus address/description/details/placeId). |
| `DocyrusLocationValue` | Loose location-field payload that the hook normalizes (supports both `latitude`/`longitude` and `lat`/`lng`). |
| `DocyrusMapProvider` | `'leaflet' \| 'google'`. |
| `DocyrusGoogleMapType` | `'roadmap' \| 'satellite' \| 'hybrid' \| 'terrain'`. |
| `DocyrusBasemapId` | Built-in basemap id: `'street' \| 'satellite' \| 'hybrid' \| 'terrain'`. |
| `DocyrusBasemapDefinition` | Custom basemap shape: `{ id, label, leafletUrl, leafletDarkUrl?, leafletAttribution?, googleMapType }`. |
| `DocyrusMapMarkerIcon` | `{ url, size? }` icon descriptor returned by Google's `getMarkerIcon`. |
| `DEFAULT_DOCYRUS_BASEMAPS` | Built-in basemap registry, keyed by `DocyrusBasemapId`. Useful for cloning/extending presets. |
| `UseDocyrusMapViewOptions<TData>` | Hook option shape (extends `UseDocyrusDataGridOptions`). |
| `UseDocyrusMapViewResult<TData>` | Hook return shape. |

---

# useDocyrusPivotCalendar
URL: /docs/web/hooks/use-docyrus-pivot-calendar

Wires the PivotCalendar component to a Docyrus data source using the items endpoint's pivot parameter for server-side aggregation.

`useDocyrusPivotCalendar` builds a `pivot` payload (matrix + calculations) for a Docyrus data source items endpoint, runs it via `RestApiClient`, and parses the result into the `cells` and `groups` shape that `` consumes.

The matrix is rebuilt automatically as the user navigates views (month-calendar / days-of-week / days-of-month / months-of-year) and dates, so all aggregation happens on the server with one round-trip per change.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-docyrus-pivot-calendar
```

## How it builds the request

For a given `view` + reference `date`, the hook constructs a payload like:

```json
{
  "pivot": {
    "matrix": [
      {
        "using": "<dateField>",
        "columns": "bucket:to_char[YYYY-MM-DD]@<dateField>",
        "spread": true,
        "dateRange": { "interval": "day", "min": "<rangeStart>", "max": "<rangeEnd>" }
      },
      {
        "using": "<groupField>",
        "columns": "groupLabel:<labelField>",
        "spread": true
      }
    ]
  },
  "calculations": [
    { "field": "<measure.field>", "func": "<measure.func>", "name": "<measure.id>" }
  ]
}
```

| View | `dateRange.interval` | `bucket` token |
|------|----------------------|----------------|
| `month-calendar` | `day` | `YYYY-MM-DD` |
| `days-of-week` | `day` | `YYYY-MM-DD` |
| `days-of-month` | `day` | `YYYY-MM-DD` |
| `months-of-year` | `month` | `YYYY-MM` |

Each result row contains `bucket`, optional `groupLabel`, and one column per measure (named after `measure.id`). The hook maps each row to an `IPivotCalendarRemoteCell`. The relation's primary key is implicit on the SQL join — by default the hook uses the displayed `groupLabel` (e.g. user name) as the stable group key.

When `groupBy.idField` is set the matrix also exposes a non-join key column (e.g. `'user_id'` for user relations) as `groupId:<idField>`. The hook then uses that resolved UUID as the cell's `groupId` so drilldown queries can filter by `<groupBy.field> = <uuid>` directly. The relation's actual `id` column **cannot** be aliased — it is the SQL join key — so `idField` must point at a separate column on the related data source.

## Example: `base/time_entry`

Wires `` to the `base/time_entry` data source on the Docyrus tenant. Two measures (logged + billable durations, both stored in seconds) are aggregated server-side with `sum`, then converted to hours and formatted as `1.5h` for display. Time entries are grouped by `record_owner` so each user becomes a row in the pivot views.

```tsx
'use client';

import { useDocyrusAuth } from '@docyrus/signin';
import { Clock, RefreshCw } from 'lucide-react';

import { PivotCalendar } from '@docyrus/ui/components/pivot-calendar';
import { useDocyrusPivotCalendar } from '@docyrus/ui/library/hooks/use-docyrus-pivot-calendar';
import { Button } from '@docyrus/ui/primitives/ui/button';
import { Spinner } from '@docyrus/ui/primitives/ui/spinner';

const APP_SLUG = 'base';
const DATA_SOURCE_SLUG = 'time_entry';

function secondsToHours(value: number): number {
  return value / 3600;
}

function formatHours(hours: number): string {
  if (!hours) return '0h';
  const rounded = Math.round(hours * 10) / 10;

  return `${rounded}h`;
}

export function TimeEntriesPage() {
  const { client } = useDocyrusAuth();

  if (!client) return null;

  return ;
}

function TimeEntriesPageInner({
  client
}: {
  client: NonNullable
        </div>
      </div>

      {error ? (
        <div className="rounded-md border border-destructive/40 bg-destructive/5 p-3 text-sm text-destructive">
          Failed to load time entries: {error.message}
        </div>
      ) : null}

      <div className="flex min-h-0 flex-1 overflow-hidden">
        
      </div>
    </div>
  );
}
```

### Generated request

For the **month-calendar** view of May 2026, the hook sends the following payload to `GET /v1/apps/base/data-sources/time_entry/items`:

```json
{
  "columns": "...record_owner(name)",
  "pivot": {
    "matrix": [
      {
        "using": "date",
        "columns": "bucket:to_char[YYYY-MM-DD]@date",
        "spread": true,
        "dateRange": {
          "interval": "day",
          "min": "2026-05-01T00:00:00.000Z",
          "max": "2026-05-31T23:59:59.999Z"
        }
      },
      {
        "using": "record_owner",
        "columns": "groupLabel:name, groupId:user_id",
        "spread": true
      }
    ]
  },
  "calculations": [
    { "field": "duration",          "func": "sum", "name": "logged" },
    { "field": "duration_billable", "func": "sum", "name": "billable" }
  ]
}
```

### Sample response row

```json
{
  "bucket": "2026-05-06",
  "groupLabel": "Cameron Shaw",
  "groupId": "aeafdd7a-9217-4438-8e70-d3ac6d9b709a",
  "name": "Cameron Shaw",
  "logged": "10800",
  "billable": "9000"
}
```

The hook converts each row into an `IPivotCalendarRemoteCell` (with `idField: 'user_id'` set):

```ts
{
  bucket: '2026-05-06',
  groupId: 'aeafdd7a-9217-4438-8e70-d3ac6d9b709a',
  values: [
    { measureId: 'logged',   value: 3 },   // 10800 / 3600
    { measureId: 'billable', value: 2.5 }  // 9000 / 3600
  ]
}
```

The corresponding `IPivotCalendarGroup` keeps the user's name as `label`, and the UUID as `id` so drilldown filters can target `record_owner = <uuid>` directly.

## Drilldown

When the user clicks a stat tile, `` emits an `IPivotCalendarCellClick` with the bucket, resolved date range, group, measure, and value. The hook lets you turn that click into a ready-to-run Docyrus query in two steps:

1. Pass an `onCellClick` handler to the hook (forwarded to ``).
2. Inside the handler, call `buildDrilldownQuery(info)` to obtain a `DocyrusPivotDrilldownQuery` containing the merged filters, suggested `columns`, and `orderBy` for the underlying records.

The hook never owns the dialog or the data table — it only emits the parameters. Render whatever you need (a generic dialog backed by `useDocyrusDataGrid`, a side panel, navigation to a saved view, etc.) on top of those params.

### Filter shape

`buildDrilldownQuery` always emits an `and` group with:

- `<dateField> between [bucketStartIso, bucketEndIso]`
- The grouping clause (only when `groupBy` is configured and the click had a `groupId`):
  - With `idField`: `<groupBy.field> = <uuid>` (resolved via the matrix's `groupId:<idField>` column)
  - Without `idField`: `rel_<groupBy.field>/<labelField> = <name>` (label-based fallback)
- Any caller-provided `filters` are nested first inside the merged group so they keep their semantics

### Wiring example

```tsx
import { useState } from 'react';

import { useDocyrusAuth } from '@docyrus/signin';

import { PivotCalendar } from '@docyrus/ui/components/pivot-calendar';
import {
  useDocyrusPivotCalendar,
  type DocyrusPivotDrilldownQuery
} from '@docyrus/ui/library/hooks/use-docyrus-pivot-calendar';

import { PivotDrilldownDialog } from '@/components/pivot-drilldown-dialog';

function TimeEntriesPage() {
  const { client } = useDocyrusAuth();
  const [drilldown, setDrilldown] = useState<DocyrusPivotDrilldownQuery | null>(null);

  const { pivotCalendarProps, buildDrilldownQuery } = useDocyrusPivotCalendar({
    client: client!,
    appSlug: 'base',
    dataSourceSlug: 'time_entry',
    dateField: 'date',
    measures: [/* ... */],
    groupBy: {
      field: 'record_owner',
      label: 'User',
      labelField: 'name',
      idField: 'user_id'
    },
    onCellClick: info => setDrilldown(buildDrilldownQuery(info))
  });

  return (
    <>
      
      {drilldown ? (
        <PivotDrilldownDialog
          open
          client={client!}
          drilldown={drilldown}
          onOpenChange={open => { if (!open) setDrilldown(null); }} />
      ) : null}
    </>
  );
}
```

### Sample drilldown payload

For a click on **2026-05-06 → Cameron Shaw → Logged**, `buildDrilldownQuery` returns:

```ts
{
  appSlug: 'base',
  dataSourceSlug: 'time_entry',
  dateField: 'date',
  groupField: 'record_owner',
  groupLabel: 'Cameron Shaw',
  bucketStartIso: '2026-05-06T00:00:00.000Z',
  bucketEndIso: '2026-05-06T23:59:59.999Z',
  measureField: 'duration',
  measureFunc: 'sum',
  measureValue: 3,
  measureFormatted: '3h',
  filters: {
    combinator: 'and',
    rules: [
      { field: 'date', operator: 'between',
        value: ['2026-05-06T00:00:00.000Z', '2026-05-06T23:59:59.999Z'] },
      { field: 'record_owner', operator: '=',
        value: 'aeafdd7a-9217-4438-8e70-d3ac6d9b709a' }
    ]
  },
  columns: 'id, date, duration, ...record_owner(name)',
  orderBy: 'date DESC'
}
```

The `filters`, `columns`, and `orderBy` go straight into `useDocyrusDataGrid({ listParams: { ... } })` — the dialog wrapper at `apps/playground/src/components/pivot-drilldown-dialog.tsx` is a thin reference implementation.

### `DocyrusPivotDrilldownQuery`

| Field | Type | Description |
|-------|------|-------------|
| `appSlug` | `string` | App slug, ready to pass to `useDocyrusDataGrid`. |
| `dataSourceSlug` | `string` | Data source slug. |
| `dateField` | `string` | Date field that produced the bucket. |
| `groupField` | `string \| undefined` | Group field slug, when `groupBy` is configured. |
| `groupLabel` | `string \| null` | Display label of the clicked group (e.g. user name). |
| `bucketStart` / `bucketEnd` | `Date` | Resolved date range of the bucket. |
| `bucketStartIso` / `bucketEndIso` | `string` | ISO strings of the same range. |
| `measureField` | `string` | Field slug of the clicked measure. |
| `measureFunc` | `TPivotCalendarAggregate` | Aggregation function. |
| `measure` | `IPivotCalendarMeasure<PivotRow>` | Measure descriptor (label, color, format). |
| `measureValue` | `number` | Raw aggregated value. |
| `measureFormatted` | `string` | Pre-formatted value (e.g. `1.5h`). |
| `filters` | `DocyrusPivotFilterGroup` | Merged AND filter group. |
| `columns` | `string` | Suggested `columns` selection. |
| `orderBy` | `string` | Suggested `orderBy` (`<dateField> DESC`). |

## Usage (minimal)

```tsx
import { useDocyrusAuth } from '@docyrus/signin';
import { PivotCalendar } from '@docyrus/ui/components/pivot-calendar';
import { useDocyrusPivotCalendar } from '@docyrus/ui/library/hooks/use-docyrus-pivot-calendar';

function Report() {
  const { client } = useDocyrusAuth();

  const { pivotCalendarProps } = useDocyrusPivotCalendar({
    client: client!,
    appSlug: 'base',
    dataSourceSlug: 'time_entry',
    dateField: 'date',
    measures: [
      {
        id: 'logged',
        label: 'Logged',
        field: 'duration',
        func: 'sum',
        transform: s => s / 3600,
        formatValue: h => `${h.toFixed(1)}h`
      }
    ],
    groupBy: { field: 'record_owner', label: 'User', labelField: 'name' }
  });

  return ;
}
```

## Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `client` | `RestApiClient` | — | Authenticated Docyrus API client. |
| `appSlug` | `string` | — | App slug. |
| `dataSourceSlug` | `string` | — | Data source slug. |
| `dateField` | `string` | — | Field used for the date range matrix. |
| `measures` | `Array<DocyrusPivotMeasure>` | — | Up to 2 measures with field, func, color, format. |
| `groupBy` | `DocyrusPivotGroupBy` | — | Optional grouping dimension (e.g. user/team). |
| `columns` | `string` | `''` | Extra `columns` segment for joined labels. |
| `filters` | `unknown` | — | Filters applied to the main query. |
| `defaultView` | `TPivotCalendarView` | `'month-calendar'` | Initial view. |
| `view` | `TPivotCalendarView` | — | Controlled view. |
| `onViewChange` | `(view) => void` | — | View change handler. |
| `defaultDate` | `Date` | now | Initial reference date. |
| `date` | `Date` | — | Controlled reference date. |
| `onDateChange` | `(date) => void` | — | Date change handler. |
| `hideViewSwitcher` | `boolean` | `false` | Forwarded to `<PivotCalendar>`. |
| `hideSidebar` | `boolean` | `false` | Forwarded to `<PivotCalendar>`. |
| `visibleViews` | `Array<TPivotCalendarView>` | all | Forwarded to `<PivotCalendar>`. |
| `enabled` | `boolean` | `true` | TanStack Query gate. |
| `staleTime` | `number` | `30_000` | Cache window in ms. |
| `showEmptyCells` | `boolean` | `true` | When `false`, sends `pivot.hideEmptyRows: true`. |
| `onCellClick` | `(info) => void` | — | Forwarded to `<PivotCalendar>`. Pair with `buildDrilldownQuery` to open a drilldown dialog. |

### `groupBy` (`DocyrusPivotGroupBy`)

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `field` | `string` | — | Field slug of the grouping relation/select. |
| `label` | `string` | — | Visible label for the sidebar / pivot row header. |
| `labelField` | `string` | `'name'` | Subfield used to label groups in the matrix CTE (`groupLabel:<labelField>`). |
| `idField` | `string` | — | Subfield exposing the relation's stable primary key in the matrix CTE (e.g. `'user_id'` for users). When set, drilldown filters become `<field> = <uuid>`; otherwise the hook falls back to `rel_<field>/<labelField>`. |
| `filters` | `unknown` | — | Filters applied to the group dimension's CTE. |
| `toGroup` | `(row) => Partial<IPivotCalendarGroup>` | — | Per-row override that returns avatar / colour metadata for the resolved group. |

## Returns

| Field | Type | Description |
|-------|------|-------------|
| `pivotCalendarProps` | `PivotCalendarProps<TData>` | Props ready to spread on `<PivotCalendar>` (already configured for `mode='remote'`). |
| `cells` | `Array<IPivotCalendarRemoteCell>` | Parsed remote cells. |
| `groups` | `Array<IPivotCalendarGroup>` | Inferred groups from the response. |
| `measures` | `Array<IPivotCalendarMeasure>` | Component-shaped measures. |
| `view` | `TPivotCalendarView` | Active view. |
| `setView` | `(view) => void` | Manual view setter. |
| `selectedDate` | `Date` | Active reference date. |
| `setSelectedDate` | `(date) => void` | Manual date setter. |
| `isLoading` | `boolean` | TanStack Query loading flag. |
| `error` | `Error \| null` | Last query error. |
| `refetch` | `() => void` | Force a refetch. |
| `buildDrilldownQuery` | `(info: IPivotCalendarCellClick) => DocyrusPivotDrilldownQuery` | Converts a click event into Docyrus query parameters (filters, columns, orderBy) ready for `useDocyrusDataGrid`. |

## Notes

- The hook caps the displayed measures at **2** (matching `<PivotCalendar>`).
- The `count` aggregate uses the `id` field — pass `field: 'id'` together with `func: 'count'`.
- For relations (e.g. `record_owner`, `user`), the default `labelField` is `name`. Override via `groupBy.labelField` when the related data source uses a different display field.
- For user relations like `record_owner`, set `groupBy.idField: 'user_id'` so the matrix surfaces the stable UUID and drilldown filters use `record_owner = <uuid>` instead of the `rel_record_owner/name` fallback. The relation's actual `id` column can never be aliased (it is the SQL join key).
- `transform` runs client-side on each value before formatting — useful for unit conversions like seconds→hours.
- The pivot calendar emits a click for every measure tile / pivot value; `buildDrilldownQuery` is the bridge to `useDocyrusDataGrid` — your dialog or panel stays decoupled from both the calendar and the hook.

---

# useDocyrusPivotFilter
URL: /docs/web/hooks/use-docyrus-pivot-filter

Wire a Docyrus data source to a `<PivotFilter>` strip — auto-detects the field type, runs a pivot/aggregate query, transforms results into pill items, and emits filter rules ready to merge into a grid query.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-docyrus-pivot-filter
```

**Dependencies:**
- [@docyrus/app-utils](https://www.npmjs.com/package/@docyrus/app-utils)
- [@docyrus/api-client](https://www.npmjs.com/package/@docyrus/api-client)
- [@tanstack/react-query](https://tanstack.com/query/latest)
- [date-fns](https://date-fns.org)

This hook is distributed as source. It expects an authenticated `RestApiClient` from `@docyrus/api-client` and a `QueryClientProvider` from `@tanstack/react-query` somewhere above your component tree.

## Overview

`useDocyrusPivotFilter` is the Docyrus-backed companion to [`PivotFilter`](/docs/web/components/pivot-filter). It does for the pivot filter what [`useDocyrusKanban`](/docs/web/hooks/use-docyrus-kanban) does for kanban boards:

- loads the data source metadata (`expand=enums`)
- auto-detects the field strategy from the field's `type`
- builds a native Docyrus pivot query (`columns: '<field>(id, name, icon, color)'` for relations, `columns: '<bucket>@<field>'` for dates) — no `pivot.matrix`, no alias quirks
- transforms the API response into ready-to-render `PivotFilterItem`s
- generates date buckets for date / dateTime fields
- enriches list pills with `icon` / `color` directly from the join (no FE lookup for enums)
- exposes a `filterRule` matching the active selection — feed it back into your data grid filter
- provides a settings popover content node ready to slot into `<PivotFilter>`

For multi-pivot pages (e.g. "filter by status AND priority"), reach for [`<DocyrusPivotFilterGroup>`](#docyruspivotfiltergroup) below — it stacks N strips and handles bidirectional cross-filtering for free.

**If your page already uses [`useDocyrusDataGrid`](/docs/web/hooks/use-docyrus-data-grid),** prefer its built-in `pivotFilters` option — the grid hook renders the strips above its toolbar automatically, AND-merges selections into the items query, and feeds the grid's own filter chain back into the pivots as `activeFilters`. No glue required:

```tsx
const grid = useDocyrusDataGrid({
  client,
  appSlug: 'base',
  dataSourceSlug: 'task',
  pivotFilters: [
    { fieldSlug: 'status' },
    { fieldSlug: 'priority' }
  ]
});

// grid.toolbar already contains the pivot strips on top.
```

## Supported field types

The hook reads `field.type` and picks a strategy:

| Field type | Strategy | Pill content | Filter rule emitted |
|-----------|----------|--------------|---------------------|
| `field-select`, `field-status`, `field-radioGroup` | `list` | `id` + `name` + `icon` + `color` from joined `tenant_enum` | `{ field, operator: '=', value: id }` |
| `field-relation` | `list` | `id` + `name` from related data source (icon / color silently dropped) | `{ field, operator: '=', value: id }` |
| `field-userSelect` | `user` | avatar (from caller's user list) + name from joined `tenant_user` | `{ field, operator: '=', value: userId }` |
| `field-date` | `date` (date-only) | bucket label + range | `{ operator: 'between', value: [start+00:00, end+00:00] }` — wall-clock dates pinned to UTC |
| `field-dateTime` | `date` (with time) | bucket label + range | `{ operator: 'between', value: [startLocalISO, endLocalISO] }` — preserves the user's local timezone offset |
| `field-multiSelect`, `field-tagSelect`, `field-userMultiSelect` | `unsupported` | — | none (the backend's `applyPivot` currently rejects these as axis fields, so the query is skipped) |

Empty (null) values are surfaced as a synthetic `EMPTY` pill that emits `{ operator: 'empty', value: null }`.

### `field-date` vs `field-dateTime` timezone handling

A `field-date` represents a calendar day with no time component. When the user picks the "13 May" bucket in Istanbul (UTC+3), they mean *the calendar day 2026-05-13*, not "2026-05-13T00:00:00+03:00" (which is 2026-05-12T21:00:00Z in UTC and could silently shift the filter to the previous day on a UTC backend). The hook handles this by **stamping date-only bucket bounds as `+00:00`** — preserving the wall-clock numbers (`2026-05-13T00:00:00+00:00`).

For `field-dateTime`, the local offset is preserved (`2026-05-13T00:00:00+03:00`), matching the way Docyrus stores datetime values.

This matches the Vue `KvPivotFilter` behavior verbatim.

## Usage

### Status filter above a grid

```tsx
'use client';

import { useState } from 'react';

import { useDocyrusAuth } from '@docyrus/signin';

import { PivotFilter } from '@docyrus/ui/components/pivot-filter';
import {
  useDocyrusDataGrid
} from '@docyrus/ui/library/hooks/use-docyrus-data-grid';
import {
  useDocyrusPivotFilter
} from '@docyrus/ui/library/hooks/use-docyrus-pivot-filter';

export function OrderListWithStatusFilter() {
  const { client } = useDocyrusAuth();

  if (!client) return null;

  const grid = useDocyrusDataGrid({
    client,
    appSlug: 'sales',
    dataSourceSlug: 'order'
  });

  const pivot = useDocyrusPivotFilter({
    client,
    appSlug: 'sales',
    dataSourceSlug: 'order',
    fieldSlug: 'status',
    defaultFilters: grid.resolvedListParams.filters
  });

  return (
    <div className="space-y-3">
      
      {grid.toolbar}
      {grid.table}
    </div>
  );
}
```

`pivot.filterRule` carries the rule the grid needs to apply — merge it into your grid's filter to actually narrow the rows.

### Date pivot (days of week)

```tsx
const pivot = useDocyrusPivotFilter({
  client,
  appSlug: 'support',
  dataSourceSlug: 'ticket',
  fieldSlug: 'created_at',
  defaultDateBucket: 'days_of_week'
});

return (
  <>
    
    {/* The settings popover lets the user switch to days_of_month, months_of_year, etc. */}
  </>
);
```

The hook always renders the date strip as **Before · [buckets] · Upcoming · Not Set**, so users can grab the long tail outside the current window without losing the count.

### User filter (avatars)

```tsx
const pivot = useDocyrusPivotFilter({
  client,
  appSlug: 'project',
  dataSourceSlug: 'task',
  fieldSlug: 'assignee'
});
```

For `userMultiSelect` the hook walks each user array and re-sums the aggregate per-user in the FE, so a record assigned to three users contributes the same stat to all three pills.

### Custom calculation (sum / avg)

The default aggregate is `count` of `id`. To pivot by sum of an amount field:

```tsx
const pivot = useDocyrusPivotFilter({
  client,
  appSlug: 'sales',
  dataSourceSlug: 'invoice',
  fieldSlug: 'status',
  calculation: { func: 'sum', field: 'amount' }
});
```

The settings popover surfaces all numeric / money / duration fields and lets the user pick the function (`sum`, `avg`, `min`, `max`). Hide the popover with `disableSettings: true` when you want to lock the calculation.

### Feeding selection back to a grid

Combine `filterRule` with the grid's `defaultFilters` / `filters`:

```tsx
const grid = useDocyrusDataGrid({
  client,
  appSlug: 'sales',
  dataSourceSlug: 'invoice',
  filters: pivot.filterRule
    ? { combinator: 'and', rules: pivot.filterRule }
    : undefined
});
```

When the user resets to the "All" pill, `filterRule` flips to `null` and the grid sees no filter.

## Query payload

The hook uses Docyrus' native pivot syntax — `columns: '<field>(...)'` for relation joins or `columns: '<bucket>@<field>'` for date buckets. Combined with `calculations`, the backend auto-joins the related table and auto-groups by the joined keys. No `pivot.matrix` is involved.

```jsonc
// List strategy (field-select / field-status / field-radioGroup / field-relation)
{
  "columns": "status(id, name, icon, color)",
  "filters": { "combinator": "and", "rules": [/* defaultFilters + activeFilters + parentPivotFilters */] },
  "calculations": [{ "field": "id", "func": "count", "name": "COUNT_OF_id" }]
}
// Response: [{ status: { id, name, icon, color }, COUNT_OF_id }, ...]
```

```jsonc
// User strategy (field-userSelect)
{
  "columns": "assignee(id, name)",
  "filters": { ... },
  "calculations": [...]
}
// Response: [{ assignee: { id, name }, COUNT_OF_id }, ...]
```

```jsonc
// Date strategy (field-date / field-dateTime)
{
  "columns": "days_of_week@start_date",
  "filters": { ... },
  "calculations": [...]
}
// Response: [{ "days_of_week@start_date": "2026-05-13" | "OLDER" | "UPCOMING" | null, COUNT_OF_id }, ...]
```

The backend recognizes 8 date bucket functions natively: `hours_of_today`, `days_of_week`, `days_of_month`, `weeks_of_month`, `weeks_of_quarter`, `months_of_quarter`, `months_of_year`, `quarters_of_year`. Each emits a CASE expression with `OLDER` / `UPCOMING` sentinels for records outside the current window plus the formatted bucket key for in-range records, and the response groups by that result.

## Filter merging

Three filter inputs are merged with `combinator: and`:

1. `defaultFilters` — base filter, e.g. the saved view's filter.
2. `activeFilters` — the user's current filter on the consuming surface (grid, map, etc.). Passing this lets the pill counts react when the user filters the grid.
3. `parentPivotFilters` — for nested pivot filters, the rule contributed by the parent (e.g. when you stack a status pivot above a user pivot).

Pass `null` / `undefined` for any you don't need.

**Selection reset on parent change:** when `parentPivotFilters` changes, the current selection may point to a bucket that no longer exists in the new result set. The hook resets `selectedItemId` to `null` automatically — matching Vue `KvPivotFilter`'s behavior. `defaultFilters` and `activeFilters` changes do **not** reset the selection (they just refetch counts).

## Date buckets

Eight buckets are supported. Each generates a fixed window relative to the `referenceDate` option (defaults to `new Date()`):

| Bucket | Window | Pill labels |
|--------|--------|------------|
| `hours_of_today` | today | 00 → 23 |
| `days_of_week` | current ISO week | MON … SUN |
| `days_of_month` | current month | 1 … 31 |
| `weeks_of_month` | current month | W01 … W05 |
| `weeks_of_quarter` | current quarter | W01 … W13 |
| `months_of_quarter` | current quarter | Jan, Feb, Mar (or matching quarter months) |
| `months_of_year` | current year | Jan … Dec |
| `quarters_of_year` | current year | Q1 … Q4 |

The hook always prepends a `BEFORE` pill (records older than the window) and appends `UPCOMING` (newer) plus `EMPTY` (null date). `BEFORE` and `UPCOMING` emit `<` / `>` filter rules using the bucket boundary so the user can still drill into the long tail.

Change the bucket via the settings popover or programmatically via `setDateBucket(bucket)`. Changing the bucket resets the selection.

## Settings popover

The hook builds a ready-to-render settings popover (passed through `pivotFilterProps.settingsContent`). Contents depend on the field type:

- **For date fields** — a radio group with the eight buckets above.
- **All field types** — a "COUNT of records" preset button plus a function (`sum` / `avg` / `min` / `max`) + field selector populated from the data source's numeric / money / duration fields.

Pass `disableSettings: true` to hide the gear button entirely.

## Loading & error

`isLoading` and `isFetching` mirror the data source + items queries combined. `error` returns the first failed query.

The component renders skeleton pills while the items query is in flight; the underlying data source metadata is reused across pivots that target the same `appSlug` + `dataSourceSlug` via the shared TanStack Query cache key (`['docyrus', 'dataSource', appSlug, dataSourceSlug]`).

## API Reference

### `useDocyrusPivotFilter(options)`

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `client` | `RestApiClient` | — | Authenticated Docyrus API client. |
| `appSlug` | `string` | — | Target Docyrus app slug. |
| `dataSourceSlug` | `string` | — | Target data source slug. |
| `fieldSlug` | `string` | — | Slug of the field to pivot on. |
| `calculation` | `PivotFilterCalculation \| null` | `null` (count of id) | Aggregate function + field. |
| `defaultDateBucket` | `PivotFilterDateBucket` | `'days_of_week'` | Initial bucket for date / dateTime fields. |
| `defaultFilters` | `unknown` | — | Base filter merged into every query (e.g. saved view). |
| `activeFilters` | `unknown` | — | Current user filter — drives pill counts. |
| `parentPivotFilters` | `unknown` | — | Filter contributed by a parent pivot filter (nested setups). |
| `hideZeroValues` | `boolean` | `false` | Forwarded to `<PivotFilter>`. |
| `defaultSelectedItemId` | `string \| null` | `null` | Initial selection. |
| `referenceDate` | `Date` | `new Date()` | Reference point used to compute date buckets. |
| `disableSettings` | `boolean` | `false` | Hide the gear popover entirely. The hook stays role-agnostic; gate the popover yourself from the caller (e.g. only pass `disableSettings: !isAdmin`). |
| `onConfigurationChange` | `(config: { dateBucket; calculation }) => void` | — | Fires whenever the user changes the bucket or the calculation. Use it to persist the user's preference back to a saved view / preferences API. Matches Vue `KvPivotFilter`'s `configuration` event. |
| `staleTime` | `number` | `30000` | TanStack Query `staleTime` (ms). |
| `enabled` | `boolean` | `true` | Skip fetching when `false`. |
| `dataSourceExpand` | `string \| false` | `'enums'` | `expand` query param for the data-source schema fetch (so select/status fields carry their option metadata). Pass `false`/`''` to omit `expand` for backends that don't support it — e.g. core/tenant system data sources. |

### Return value

| Property | Type | Description |
|----------|------|-------------|
| `pivotFilterProps` | `PivotFilterProps` | Ready-to-spread props for `<PivotFilter>`. Wires `items`, `selectedItemId`, `onSelect`, `total`, `loading`, `hideZeroValues`, `onRefresh`, `settingsContent`. |
| `items` | `Array<PivotFilterItem>` | All items derived from the API response. |
| `total` | `number` | Aggregated stat across all items. |
| `selectedItemId` | `string \| null` | Currently selected item id (`null` = "All"). |
| `setSelectedItemId` | `(id) => void` | Update the selection programmatically. |
| `selectedItem` | `PivotFilterItem \| null` | Currently selected item (`null` for "All"). |
| `filterRule` | `Array<PivotFilterRule> \| null` | Filter rule(s) corresponding to the current selection — merge into your consumer's filter. `null` when "All" is selected. |
| `field` | `DataSourceField \| null` | Resolved field definition. |
| `fieldType` | `'list' \| 'user' \| 'user-multi' \| 'date' \| 'unsupported'` | Strategy derived from `field.type`. |
| `dateBucket` | `PivotFilterDateBucket` | Current bucket. |
| `setDateBucket` | `(bucket) => void` | Change the bucket (resets selection). |
| `calculation` | `PivotFilterCalculation \| null` | Current calculation. |
| `setCalculation` | `(calc) => void` | Change the calculation. |
| `reload` | `() => void` | Refetch metadata + items. |
| `isLoading` | `boolean` | First-fetch loading state. |
| `isFetching` | `boolean` | Background refetch state. |
| `error` | `Error \| null` | First query error, if any. |

## `DocyrusPivotFilterGroup`

Stacks multiple `<PivotFilter>` strips above a consumer surface (data grid, calendar, map…) and wires **bidirectional cross-filtering** between them automatically — when the user picks an item in one strip, every other strip refetches its pill counts with the new selection applied as an `activeFilters` rule.

Because React hooks can't be called in a loop with a dynamic count, the group component delegates each field to a single-instance child that owns its own `useDocyrusPivotFilter`. The group lifts each row's `filterRule` into a shared map and feeds the **other** rows' rules back down as `activeFilters` — so consumer pages don't need to write any state-lift glue.

### Usage

```tsx
'use client';

import { useState } from 'react';

import { useDocyrusAuth } from '@docyrus/signin';

import { useDocyrusDataGrid } from '@docyrus/ui/library/hooks/use-docyrus-data-grid';
import {
  DocyrusPivotFilterGroup,
  type PivotFilterRule
} from '@docyrus/ui/library/hooks/use-docyrus-pivot-filter';

export function TasksPage() {
  const { client } = useDocyrusAuth();
  const [pivotRule, setPivotRule] = useState<Array<PivotFilterRule> | null>(null);

  if (!client) return null;

  const grid = useDocyrusDataGrid({
    client,
    appSlug: 'base',
    dataSourceSlug: 'task',
    listParams: pivotRule
      ? { filters: { combinator: 'and', rules: pivotRule } }
      : undefined
  });

  return (
    <>
      

      {grid.toolbar}
      {grid.table}
    </>
  );
}
```

Clicking **High** in the priority strip narrows the status strip's pill counts to "only high-priority tasks per status", and vice-versa. The `onFilterRuleChange` callback fires whenever any pivot selection changes, with the AND-combined rule of every active selection (or `null` when nothing is selected).

### API Reference

| Prop | Type | Description |
|------|------|-------------|
| `client` | `RestApiClient` | Authenticated Docyrus API client. |
| `appSlug` | `string` | Target app slug. |
| `dataSourceSlug` | `string` | Target data source slug. |
| `fields` | `ReadonlyArray<DocyrusPivotFilterGroupField>` | One entry per stacked strip. Order = stack order top-to-bottom. |
| `defaultFilters` | `unknown` | Base filter applied to every strip's items query (e.g. saved view). |
| `activeFilters` | `unknown` | External filter applied to every strip's items query (e.g. the consumer grid's current toolbar filter). |
| `onFilterRuleChange` | `(rule: Array<PivotFilterRule> \| null) => void` | Fired with the AND-combined rule of every pivot's current selection. `null` when no pivot has a selection. |
| `vertical` | `boolean` | Render strips vertically (column rail). |
| `compact` | `boolean` | Compact pill layout. |
| `className` | `string` | Wrapper class name. |
| `staleTime` | `number` | TanStack Query `staleTime` (ms). Forwarded to every strip. |
| `dataSourceExpand` | `string \| false` | `expand` query param for the shared data-source schema fetch (default `'enums'`). Pass `false`/`''` to omit `expand` for backends that don't support it. Forwarded to every strip. |

### `DocyrusPivotFilterGroupField`

| Field | Type | Description |
|-------|------|-------------|
| `fieldSlug` | `string` | Slug of the field to pivot on. |
| `defaultDateBucket` | `PivotFilterDateBucket` | Initial date bucket — only used for `field-date` / `field-dateTime`. |
| `calculation` | `PivotFilterCalculation \| null` | Initial calculation. `null` (default) is `count` of `id`. |
| `totalLabel` | `string` | Override the "All" pill label for this strip. |
| `hideZeroValues` | `boolean` | Hide items whose stat is zero (except the currently selected one). |
| `disableSettings` | `boolean` | Disable the settings popover for this strip. |
| `defaultSelectedItemId` | `string \| null` | Initial selection. |

## Type Exports

| Type | Description |
|------|-------------|
| `PivotFilterAggregateFunc` | `'count' \| 'sum' \| 'avg' \| 'min' \| 'max'`. |
| `PivotFilterCalculation` | `{ func: PivotFilterAggregateFunc; field: string }`. |
| `PivotFilterDateBucket` | One of the eight bucket ids. |
| `PivotFilterFieldType` | `'list' \| 'user' \| 'user-multi' \| 'date' \| 'unsupported'`. |
| `PivotFilterRule` | `{ field, operator, value }` — emitted via `filterRule`. |
| `UseDocyrusPivotFilterOptions` | Hook option shape. |
| `UseDocyrusPivotFilterResult` | Hook return shape. |
| `DocyrusPivotFilterGroupField` | Per-pivot config shape used in `<DocyrusPivotFilterGroup>`. |
| `DocyrusPivotFilterGroupProps` | Group component prop shape. |

---

# useDocyrusPivotGrid
URL: /docs/web/hooks/use-docyrus-pivot-grid

Wires the PivotGrid component to a Docyrus data source with optional server-side aggregation via pivot.matrix + calculations.

`useDocyrusPivotGrid` fetches data from a Docyrus items endpoint and feeds it into the `usePivotGrid` controller that `` consumes. It supports two modes:

- **`'client'`** (default) — fetches raw records and aggregates in the browser. Simple to set up; suitable for datasets up to ~5 000 rows.
- **`'server'`** — sends a `pivot.matrix` + `calculations` payload so the database aggregates. Returns one row per dimension combination; scales to any dataset size.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-docyrus-pivot-grid
```

## How it works

### Client mode

The hook builds a standard `columns` + optional `filters` / `orderBy` / `limit` query, fetches raw records, then hands them to `usePivotGrid` together with mapped dimension/measure descriptors. All grouping and aggregation happens in the browser.

### Server mode

For each date dimension that has `dateFormat` + `dateRange` set, the hook builds a matrix entry:

```json
{
  "using": "<field>",
  "columns": "<dimAlias>:to_char[<dateFormat>]@<field>",
  "spread": true,
  "dateRange": { "interval": "day", "min": "<min>", "max": "<max>" }
}
```

> **Important:** always use `interval: "day"` for date bucketing (e.g. monthly). The backend `generate_series` creates one entry per day; the `to_char` token then groups them into buckets (months, years, etc.) via the SQL GROUP BY. Using `interval: "month"` would only match records that fall exactly on the first day of each month.

For relation/userSelect dimensions the matrix entry uses the `subField` directly:

```json
{ "using": "record_owner", "columns": "dim_user:name", "spread": true }
```

The full server-mode payload looks like:

```json
{
  "columns": "id",
  "pivot": {
    "matrix": [
      { "using": "record_owner", "columns": "dim_user:name", "spread": true },
      {
        "using": "date",
        "columns": "dim_month:to_char[YYYY-MM]@date",
        "spread": true,
        "dateRange": { "interval": "day", "min": "2025-11-01", "max": "2026-05-31" }
      }
    ]
  },
  "calculations": [
    { "field": "duration", "func": "sum", "name": "logged" },
    { "field": "duration_billable", "func": "sum", "name": "billable" }
  ]
}
```

Each result row contains `dim_user`, `dim_month`, `logged`, `billable`. The hook reads these via server aliases and passes them to `usePivotGrid` for rendering.

## Example: `base/time_entry`

Pivot grid of logged and billable hours by user × month. Server-mode aggregation — the database returns one row per user+month combination.

```tsx
'use client';

import { useMemo } from 'react';

import { useDocyrusAuth } from '@docyrus/signin';
import {
  PivotGridExportMenu,
  PivotGridToolbar,
  PivotGridView
} from '@docyrus/ui/components/pivot-grid';
import { useDocyrusPivotGrid } from '@docyrus/ui/library/hooks/use-docyrus-pivot-grid';

function secondsToHours(v: number) { return v / 3600; }
function formatHours(h: number) { return `${Math.round(h * 10) / 10}h`; }
function formatMonth(value: unknown) {
  if (typeof value !== 'string' || !value) return '—';
  const [y, m] = value.split('-').map(Number);
  return new Date(y, m - 1, 1).toLocaleDateString('en-US', { month: 'short', year: 'numeric' });
}

export function TimeEntryReportsPage() {
  const { client } = useDocyrusAuth();
  if (!client) return null;

  const dateRange = useMemo(() => {
    const now = new Date();
    const min = new Date(now.getFullYear(), now.getMonth() - 5, 1).toISOString().slice(0, 10);
    const max = new Date(now.getFullYear(), now.getMonth() + 1, 0).toISOString().slice(0, 10);
    return { interval: 'day', min, max };
  }, []);

  const rowDimensions = useMemo(() => [{
    id: 'user',
    label: 'User',
    field: 'record_owner',
    subField: 'name',
    emptyLabel: 'Unassigned'
  }], []);

  const columnDimensions = useMemo(() => [{
    id: 'month',
    label: 'Month',
    field: 'date',
    dateFormat: 'YYYY-MM',
    dateRange,
    formatValue: formatMonth,
    sort: (a: unknown, b: unknown) => String(a).localeCompare(String(b))
  }], [dateRange]);

  const measures = useMemo(() => [
    { id: 'logged', label: 'Logged (h)', field: 'duration', aggregate: 'sum' as const, transform: secondsToHours, formatValue: formatHours },
    { id: 'billable', label: 'Billable (h)', field: 'duration_billable', aggregate: 'sum' as const, transform: secondsToHours, formatValue: formatHours }
  ], []);

  const { controller } = useDocyrusPivotGrid({
    client,
    appSlug: 'base',
    dataSourceSlug: 'time_entry',
    mode: 'server',
    rowDimensions,
    columnDimensions,
    measures,
    height: 'auto'
  });

  return (
    <div>
      
      
      
    </div>
  );
}
```

## API Reference

### `UseDocyrusPivotGridOptions`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `client` | `RestApiClient` | — | Authenticated Docyrus API client. |
| `appSlug` | `string` | — | App slug (e.g. `'base'`). |
| `dataSourceSlug` | `string` | — | Data source slug (e.g. `'time_entry'`). |
| `mode` | `'client' \| 'server'` | `'client'` | Aggregation mode. |
| `rowDimensions` | `DocyrusPivotGridDimension[]` | — | Row grouping axes. |
| `columnDimensions` | `DocyrusPivotGridDimension[]` | — | Column grouping axes. |
| `measures` | `DocyrusPivotGridMeasure[]` | — | Values to aggregate in each cell. |
| `columns` | `string` | auto-derived | Columns expression forwarded to the items endpoint. |
| `filters` | `unknown` | — | Server-side filters forwarded verbatim. |
| `orderBy` | `string` | — | Client mode only. |
| `limit` | `number` | `5000` | Client mode only. Max records to fetch. |
| `getRowId` | `(row, index) => string` | — | Stable row identifier for `usePivotGrid`. |
| `initialState` | `Partial<PivotGridState>` | — | Initial expand/pin/size state. |
| `cellColorRules` | `PivotGridCellColorRule[]` | — | Formula-based cell colour rules. |
| `drilldown` | `PivotGridDrilldown<TData>` | — | Drilldown configuration. |
| `height` | `number \| 'auto'` | `600` | Grid height in pixels or `'auto'`. |
| `enabled` | `boolean` | `true` | Enable/disable the query. |
| `staleTime` | `number` | `30000` | TanStack Query stale time in ms. |

### `DocyrusPivotGridDimension`

| Prop | Type | Description |
|------|------|-------------|
| `id` | `string` | Unique id used internally and as server alias prefix (`dim_<id>`). |
| `label` | `string` | Header label. |
| `field` | `string` | Field slug on the data source. |
| `subField` | `string` | Sub-field for relation/userSelect fields (e.g. `'name'`). |
| `dateFormat` | `string` | Postgres `to_char` token for server-mode date bucketing (e.g. `'YYYY-MM'`). |
| `dateRange` | `{ interval, increment?, min, max }` | Required when `dateFormat` is set. Use `interval: 'day'` for monthly/yearly bucketing. |
| `getValue` | `(row) => unknown` | Custom extractor. Overrides server alias accessor — only set for custom logic. |
| `formatValue` | `(value) => string` | Display formatter for header values. |
| `sort` | `(a, b) => number` | Custom sort for dimension values. |
| `emptyLabel` | `string` | Label for null/empty dimension values. |

### `DocyrusPivotGridMeasure`

| Prop | Type | Description |
|------|------|-------------|
| `id` | `string` | Unique id — also used as the server-side calculation alias. |
| `label` | `string` | Column header label. |
| `field` | `string` | Field slug to aggregate (use `'id'` for count). |
| `aggregate` | `PivotGridAggregate` | Aggregation function (`'sum'`, `'count'`, `'avg'`, `'min'`, `'max'`). |
| `transform` | `(value: number) => number` | Post-aggregation transform (e.g. seconds → hours). |
| `getValue` | `(row) => number \| null` | Custom extractor — overrides field accessor. |
| `formatValue` | `(value: number) => string` | Display formatter for cell values. |

### `UseDocyrusPivotGridResult`

| Property | Type | Description |
|----------|------|-------------|
| `controller` | `PivotGridController<TData>` | Pass to ``. |
| `items` | `TData[]` | Raw records (client mode) or aggregated rows (server mode). |
| `isLoading` | `boolean` | True on the first fetch. |
| `isFetching` | `boolean` | True on any background refetch. |
| `error` | `Error \| null` | Query error if any. |
| `refetch` | `() => void` | Manually trigger a refetch. |

## Server-mode notes

- **`getValue` on dimensions**: in server mode, the hook auto-generates `(row) => row['dim_<id>']` for each dimension. Set `getValue` only when you need custom transformation logic on the server-returned value.
- **`dateRange.interval`**: use `'day'` even for monthly/yearly bucketing. The backend `generate_series` uses this as the axis step; `to_char` then groups days into the desired bucket. Using `'month'` only matches records that fall exactly on the first day of each month.
- **`columns` in server mode**: defaults to `'id'`. Override only if you need extra fields in the main query alongside the pivot payload.

---

# useDocyrusTenant
URL: /docs/web/hooks/use-docyrus-tenant

Single-line tenant integration that fetches tenant preferences, builds dateUtils + numberUtils, and wires DateFormatProvider + NumberFormatProvider so every UI component (data grids, calendars, filters, value renderers) picks up the tenant's configured date/time/number formats automatically.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-docyrus-tenant
```

**Dependencies:**
- [@docyrus/app-utils](https://www.npmjs.com/package/@docyrus/app-utils)
- [@docyrus/api-client](https://www.npmjs.com/package/@docyrus/api-client)
- [@tanstack/react-query](https://tanstack.com/query/latest)

This module ships two named exports:

- `
  );
}
```

From there, every UI component that reads `useDateFormat()` / `useNumberFormat()` — including [`useDocyrusDataGrid`](/docs/web/hooks/use-docyrus-data-grid), [`useDocyrusDataTable`](/docs/web/hooks/use-docyrus-data-table), [`useDocyrusDataGallery`](/docs/web/hooks/use-docyrus-data-gallery), calendar event cells, side-filter chips, and the standalone value renderers — picks up the tenant's configured formats automatically. **No per-page formatter wiring required.**

For ad-hoc formatting (custom chart axes, header labels, etc.) read the same utils via the hook:

```tsx
import { useDocyrusTenant } from '@docyrus/ui/library/hooks/use-docyrus-tenant';

function ChartHeader({ date }: { date: string }) {
  const { dateUtils, isLoading } = useDocyrusTenant();

  if (isLoading || !dateUtils) return <span>—</span>;

  return <span>{dateUtils.formatDateLong(date)}</span>;
}
```

## Provider props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `client` | `RestApiClient \| null \| undefined` | — | The `@docyrus/api-client` instance used to fetch `/v1/tenant/preferences`. |
| `enabled` | `boolean` | `Boolean(client)` | Defer the fetch until your auth flow is ready. Set to `false` (or leave `client` null) until the user is authenticated. |
| `userTimezone` | `string` | `'UTC'` | IANA timezone id forwarded to `createDateUtils`. Typically the user profile's `timeZone.id`. |
| `staleTime` | `number` | `1_800_000` (30 min) | TanStack Query stale window for the preferences query. |
| `children` | `ReactNode` | — | App tree to wrap. |

## Hook return

`useDocyrusTenant()` returns:

| Field | Type | Description |
|-------|------|-------------|
| `preferences` | `TenantPreferences \| null` | Normalized tenant preferences (camelCase keys mirrored to snake_case). `null` until the fetch finishes. |
| `dateUtils` | `DateUtils \| null` | Output of `createDateUtils({ preferences, userTimezone })`. Exposes `formatDate`, `formatDateTime`, `formatDateLong`, `toUserTimezone`. |
| `numberUtils` | `NumberUtils \| null` | Output of `createNumberUtils({ preferences })`. Exposes `formatNumber`. |
| `isLoading` | `boolean` | TanStack Query's loading flag for the preferences fetch. |

## Auto-wired contexts

Internally `<DocyrusTenantProvider>` mounts:

```text
DocyrusTenantContext.Provider
└── DateFormatProvider (formatDate / formatDateTime / formatTime)
    └── NumberFormatProvider (formatNumber)
        └── {children}
```

Every Docyrus UI component reads from these contexts:

| Consumer | Context | Effect |
|----------|---------|--------|
| `useDocyrusDataGrid` / `useDocyrusDataTable` / `useDocyrusDataGallery` | `useDateFormat()` + `useNumberFormat()` | Date / datetime / number cells pick up tenant formatting unless a `formatDate` / `formatDateTime` / `formatNumber` prop is passed explicitly (props still win). |
| Calendar event cells, side-filter chips | `useDateFormat()` | Same fallback chain. |
| `DocyrusDateValue`, `DocyrusDateTimeValue`, `DocyrusNumberValue` value renderers | `useDateFormat()` / `useNumberFormat()` | Standalone display components inherit tenant formatting. |

**Backwards compatible:** the data-grid / data-table hooks detect whether a real provider is mounted (vs. the no-provider sentinel) before injecting the context formatter. Apps that haven't adopted `<DocyrusTenantProvider>` yet keep their previous behaviour byte-for-byte — the cells fall back to their internal `Intl.NumberFormat` / raw-string renderers exactly as before.

## Standalone `normalizeTenantPreferences`

If you maintain your own provider stack (for example you also need to seed a non-Docyrus formatter), you can call the helper directly:

```tsx
import {
  normalizeTenantPreferences,
  type DocyrusTenantContextValue
} from '@docyrus/ui/library/hooks/use-docyrus-tenant';
import {
  createDateUtils,
  createNumberUtils,
  getTenantPreferences
} from '@docyrus/app-utils';

const envelope = await getTenantPreferences(client);
const preferences = normalizeTenantPreferences(envelope);

if (preferences) {
  const dateUtils = createDateUtils({ preferences, userTimezone });
  const numberUtils = createNumberUtils({ preferences });
  // …wire them into your own context
}
```

The helper accepts either the full envelope (`{ preferences, tenant, product, enums }`) or an already inner-shaped object and is safe to call with `null` / `undefined` (returns `null`).

## Type Exports

| Type | Description |
|------|-------------|
| `DocyrusTenantContextValue` | Shape returned by `useDocyrusTenant()`. |
| `DocyrusTenantProviderProps` | Props accepted by `<DocyrusTenantProvider>`. |

---

# useDynamicFormView
URL: /docs/web/hooks/use-dynamic-form-view

Backend-agnostic dynamic form renderer — the sibling of useDocyrusFormView with no Docyrus wiring. Supply fields, values, options, and an onSubmit sink to render create/edit/view forms against any backend.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-dynamic-form-view
```

**Dependencies:**
- [@tanstack/react-query](https://tanstack.com/query/latest)
- [jsonata](https://www.npmjs.com/package/jsonata)

This hook is distributed as source. It shares the same rendering engine as [`useDocyrusFormView`](/docs/web/hooks/use-docyrus-form-view) but performs **no fetching** — you inject the schema, values, options, and submit handler yourself, so it works against any backend (or none).

## Overview

`useDynamicFormView` is the backend-agnostic counterpart of [`useDocyrusFormView`](/docs/web/hooks/use-docyrus-form-view). Both drive the exact same internal engine, so this hook supports **every** rendering feature of `useDocyrusFormView` — it just drops the Docyrus-specific data layer:

- **local form state** compatible with the Docyrus form-field components
- **shared field-component resolution** via [`useDocyrusFieldComponent`](/docs/web/hooks/use-docyrus-field-component)
- **layout helpers** (`renderField`, `renderLayout`) including nested `fieldset` / `tabpanel` / `tab` sections
- **computed fields** (`computedHidden` / `computedRequired` / `computedLabel` / `computedDescription` / `computedFormula`)
- **imperative field actions** and **form-level actions** (`onFormLoad` / `onFormBeforeSubmit` / `onFormAfterSubmit`)
- **field-level and form-level validations**
- **companion columns / submit keys** for composite fields (money, phone, status, avatar)
- **click-to-edit** detail mode via [`EditableRecordDetail`](/docs/web/docyrus/editable-record-detail)

What it does **not** do (and what you provide instead):

| `useDocyrusFormView` does… | In `useDynamicFormView` you supply… |
|----------------------------|-------------------------------------|
| fetches the data-source schema (`getBySlug`) | `fields: IField[]` |
| loads the record (`GET …/items/:id` / `collection.get`) | `initialValues` / `values` |
| loads enum / user / relation options (`/v1/apps/enums`, `/v1/users`, relation `/items`) | `enumOptions` (static, per slug) |
| uploads files (`POST …/files/upload`) | `onImageUpload` / `onFileUpload` |
| persists the record (`POST` / `PATCH` / `collection`) | `onSubmit` |

For a Docyrus-backed form, use [`useDocyrusFormView`](/docs/web/hooks/use-docyrus-form-view) instead.

## Usage

### Create form (static options + onSubmit)

```tsx
'use client';

import { useDynamicFormView } from '@docyrus/ui/library/hooks/use-dynamic-form-view';
import type { IField, EnumOption } from '@docyrus/ui/components/form-fields';
import { Button } from '@docyrus/ui/primitives/ui/button';

const fields: IField[] = [
  { id: '1', name: 'Full Name', slug: 'full_name', type: 'field-text', validations: ['required'] },
  { id: '2', name: 'Email', slug: 'email', type: 'field-email', validations: ['required'] },
  { id: '3', name: 'Status', slug: 'status', type: 'field-select' },
  { id: '4', name: 'Notes', slug: 'notes', type: 'field-textarea' }
];

const enumOptions: Record<string, EnumOption[]> = {
  status: [
    { id: 'lead', name: 'Lead', color: 'sky-500' },
    { id: 'active', name: 'Active', color: 'emerald-500' }
  ]
};

export function CreateContactForm() {
  const form = useDynamicFormView({
    fields,
    mode: 'create',
    gridColumns: 2,
    enumOptions,
    fieldOrder: ['full_name', 'email', 'status', 'notes'],
    fieldLayout: { notes: { colSpan: 'full' } },
    onSubmit: async (payload) => {
      // Persist to any backend of your choice.
      await fetch('/api/contacts', { method: 'POST', body: JSON.stringify(payload) });
    }
  });

  return (
    <form
      onSubmit={async (event) => {
        event.preventDefault();
        await form.submit();
      }}
      className="space-y-4">
      {form.renderLayout()}

      <div className="flex items-center gap-2">
        
        
      </div>
    </form>
  );
}
```

### Edit form (uncontrolled seed)

Pass `initialValues` to seed an edit form. Values are owned internally; read the result via `form.values` or the `onSubmit` payload.

```tsx
const form = useDynamicFormView({
  fields,
  mode: 'edit',
  initialValues: record,          // seeds the form once (and re-seeds if its content changes)
  enumOptions,
  onSubmit: (payload) => saveContact(record.id, payload)
});
```

### Controlled values

Provide `values` to fully control the form from the outside. The form re-seeds whenever the object's content changes, and `onValuesChange` fires on every field edit.

```tsx
const [values, setValues] = useState(record);

const form = useDynamicFormView({
  fields,
  mode: 'edit',
  values,                         // controlled
  onValuesChange: setValues,      // fires on every field change
  enumOptions
});
```

### Read-only view + click-to-edit

```tsx
const form = useDynamicFormView({
  fields,
  mode: 'view',
  initialValues: record,
  clickToEdit: true,              // rows become inline-editable on click
  enumOptions,
  onSubmit: (payload) => saveContact(record.id, payload)
});

return form.renderLayout();
```

### Nested layout, computed fields, actions & validations

Everything from [`useDocyrusFormView`](/docs/web/hooks/use-docyrus-form-view) works identically — `layout`, `fieldLayout` (including `computedHidden` / `computedFormula` / `fieldActions`), `formActions`, and `formCustomValidations`.

```tsx
const form = useDynamicFormView({
  fields,
  mode: 'create',
  gridColumns: 4,
  layout: [
    { id: 'identity', variant: 'fieldset', title: 'Identity', colSpan: 2, items: ['full_name', 'email'] }
  ],
  fieldLayout: {
    vat_number: { computedHidden: 'is_company != true' },
    total_price: { computedFormula: '$number(qty) * $number(unit_price)', readOnly: true }
  },
  formCustomValidations: [
    { id: 'v1', expression: 'close_date >= open_date', message: 'Close date cannot precede the open date.' }
  ]
});
```

Render `form.formValidationErrors` as a destructive banner above the form; per-field errors live in `form.validationErrors` (keyed by slug). See the [`useDocyrusFormView` docs](/docs/web/hooks/use-docyrus-form-view#computed-fields) for the full computed-field, field-action, form-action, and validation reference — the behavior is shared.

### Uploads

Wire `onImageUpload` / `onFileUpload` to persist a picked `File` to your storage and return a stored-value object; the hook injects them into `field-image` / `field-file` fields.

```tsx
const form = useDynamicFormView({
  fields,
  onImageUpload: async (file) => uploadToStorage(file),   // → StoredFileValue | null
  onFileUpload: async (file) => uploadToStorage(file)
});
```

### Dynamic option loading (per field)

`enumOptions` is static. For typeahead / lazy loading on a single select or relation field, hand-wire that field's loader through `fieldLayout[slug].fieldProps` — the engine threads `onSearch` / `searching` / `onLoadMore` / `hasMore` / `onExpand` straight to the field component.

```tsx
fieldLayout={{
  owner: {
    fieldProps: {
      onSearch: (term) => loadUsers(term),
      searching: isLoading,
      onLoadMore: () => loadNextPage(),
      hasMore
    }
  }
}}
```

## API Reference

### Parameters

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `fields` | `IField[]` | — | **Required.** Field schema, already normalized to `IField`. Replaces the Docyrus schema fetch. |
| `mode` | `'create' \| 'edit' \| 'view'` | `'create'` (no values) / `'edit'` (with values) | Explicit form mode. |
| `initialValues` | `Record<string, unknown>` | — | Uncontrolled seed, merged over field defaults. Re-seeds when its content changes. |
| `values` | `Record<string, unknown>` | — | Controlled values. When set, the form is controlled and re-seeds on content change. |
| `onValuesChange` | `(values) => void` | — | Fires on every field change (both controlled and uncontrolled). |
| `disabled` | `boolean` | `false` | Disable editable fields globally. |
| `clickToEdit` | `boolean` | `false` | In `view` mode, route `renderLayout()` through `EditableRecordDetail` for inline editing. |
| `includeReadOnlyFields` | `boolean` | `mode !== 'create'` | Include fields that resolve to read-only display rows. |
| `unsupportedFieldBehavior` | `'skip' \| 'value'` | `'skip'` in create, `'value'` otherwise | Whether unsupported field types disappear or fall back to value-render mode. |
| `gridColumns` | `1 \| 2 \| 3 \| 4` | `2` | Default responsive column count used by `renderLayout()`. |
| `fieldSlugs` | `string[]` | — | Whitelist fields by slug. |
| `fieldOrder` | `string[]` | — | Explicit field ordering. |
| `hiddenFieldSlugs` | `string[]` | — | Hard-hide fields by slug. |
| `fieldLayout` | `Record<string, DynamicFormViewFieldLayout>` | — | Per-field UI overrides, computed props, field actions, and custom validations. Same shape as `DocyrusFormViewFieldLayout`. |
| `layout` | `DynamicFormViewLayoutItem[]` | — | Nested layout tree (`fieldset` / `tabpanel` / `tab`). |
| `enumOptions` | `Record<string, EnumOption[]>` | — | Static option lists keyed by field slug. Absent slugs fall back to the field's inline `enums` / `options`. |
| `onImageUpload` | `(file) => Promise<StoredFileValue \| null>` | — | Upload handler for `field-image`. |
| `onFileUpload` | `(file) => Promise<StoredFileValue \| null>` | — | Upload handler for `field-file`. |
| `onSubmit` | `(payload, context) => Promise<unknown> \| unknown` | — | Persistence handler. When omitted, `submit()` just returns the built payload. |
| `transformSubmit` | `(payload, context) => payload` | — | Final payload transform before `onSubmit`. |
| `onSubmitSuccess` | `(result, payload) => void` | — | Called after a successful submit. |
| `onSubmitError` | `(error, payload) => void` | — | Called after a failed submit. |
| `formActions` | `FormAction[] \| null` | — | Form-level lifecycle actions. |
| `formCustomValidations` | `FormCustomValidationRule[] \| null` | — | Form-level validation rules evaluated on submit. |
| `client` | `RestApiClient` | — | Optional passthrough forwarded to field / value components (e.g. inline email compose). Never used for fetching. |

### Return Value

| Property | Type | Description |
|----------|------|-------------|
| `mode` | `DynamicFormViewMode` | Resolved mode. |
| `item` | `Record<string, unknown>` | Current values (alias of `values`). |
| `form` | `{ Field(...) }` | Internal form object compatible with the Docyrus form-field components. |
| `values` | `Record<string, unknown>` | Current live values snapshot. |
| `defaultValues` | `Record<string, unknown>` | Resolved initial values after schema defaults + seed merge. |
| `fields` | `DynamicFormViewField[]` | Resolved visible field descriptors. |
| `allFields` | `DynamicFormViewField[]` | Same resolved field list as `fields`. |
| `unsupportedFields` | `DynamicFormViewField[]` | Fields shown as value-render fallbacks. |
| `validationErrors` | `Map<string, string>` | Per-field validation errors keyed by slug. |
| `formValidationErrors` | `string[]` | Form-level validation messages from `formCustomValidations`. |
| `isDirty` | `boolean` | Whether current values differ from the committed baseline. |
| `isLoading` | `boolean` | Always `false` — this hook does no fetching. |
| `isSubmitting` | `boolean` | `true` while `submit()` is running. |
| `error` | `Error \| null` | Last submit error, if any. |
| `setValue` | `(slug, value) => void` | Imperatively update one field value. |
| `validate` | `() => Promise<boolean>` | Run validation without submitting. |
| `reset` | `() => void` | Reset values to the committed baseline. |
| `submit` | `() => Promise<unknown>` | Validate and run the submit pipeline. |
| `resetActionOverrides` | `() => void` | Clear accumulated field-action / form-action property overrides. |
| `renderField` | `(slug, options?) => ReactNode` | Render a single resolved field by slug. |
| `renderLayout` | `(options?) => ReactNode` | Render the visible field list using the responsive grid / layout tree. |

### Type Exports

| Type | Description |
|------|-------------|
| `UseDynamicFormViewOptions` | Options for the hook. |
| `UseDynamicFormViewResult` | Return value of the hook. |
| `DynamicFormViewMode` | `'create' \| 'edit' \| 'view'`. |
| `DynamicFormViewField` | Resolved per-field descriptor. |
| `DynamicFormViewFieldLayout` | Per-field override shape (same as `DocyrusFormViewFieldLayout`). |
| `DynamicFormViewLayoutItem` | Layout tree node (`fieldset` / `tabpanel` / `tab` / field). |
| `DynamicFormViewSubmitContext` | Context passed to `onSubmit` / `transformSubmit`. |

## Out of scope

- data fetching, option loading, uploads, and persistence — you provide these
- for a batteries-included Docyrus-backed form, use [`useDocyrusFormView`](/docs/web/hooks/use-docyrus-form-view)

---

# useLocalDataSourceDataGrid
URL: /docs/web/hooks/use-local-data-source-data-grid

Wire a LocalDataSource object into the Docyrus DataGrid hook stack, including toolbar search, filters, sorting, grouping, saved views, and local CRUD.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-local-data-source-data-grid
```

**Dependencies:**
- [@tanstack/react-query](https://tanstack.com/query/latest)
- [@tanstack/react-table](https://tanstack.com/table/latest)
- [jsonata](https://www.npmjs.com/package/jsonata)

## Overview

`useLocalDataSourceDataGrid` connects a [`LocalDataSource`](/docs/web/hooks/use-local-data-source) to the same grid workflow used by [`useDocyrusDataGrid`](/docs/web/hooks/use-docyrus-data-grid). It gives local JSON data the standard Docyrus grid experience:

- Automatic columns from local field metadata.
- Toolbar search, filter, group, sort, row height, field visibility, display controls, and reload.
- `DataGridViewSelect` with developer-provided `systemViews`.
- Local list queries using the same `filterKeyword`, `filters`, `formulas`, `calculations`, `orderBy`, `limit`, and `offset` behavior exposed by `LocalDataSource.list`.
- Inline change save and bulk delete/update through the local collection methods.

The hook disables server export by default because the records are local. Use `useDataExport` for browser-side export flows.

## Usage

```tsx
'use client';

import { useState } from 'react';

import { DataGrid, type SavedDataGridView } from '@docyrus/ui/components/data-grid';
import { useLocalDataSource } from '@docyrus/ui/library/hooks/use-local-data-source';
import { useLocalDataSourceDataGrid } from '@docyrus/ui/library/hooks/use-local-data-source-data-grid';

type Deal = {
  id: string;
  account: string;
  stage: string;
  amount: number;
  probability: number;
};

const fields = [
  { slug: 'id', name: 'ID', type: 'field-identity', readOnly: true },
  { slug: 'account', name: 'Account', type: 'field-text' },
  { slug: 'stage', name: 'Stage', type: 'field-select' },
  { slug: 'amount', name: 'Amount', type: 'field-money' },
  { slug: 'probability', name: 'Probability', type: 'field-percent' },
  { slug: 'weighted_amount', name: 'Weighted Amount', type: 'field-money', readOnly: true }
];

const views: Array
), [addRow]);

useLocalDataSourceDataGrid({
  dataSource,
  listParams,
  systemViews,
  toolbarEndContent
});
```

## API Reference

### Parameters

`useLocalDataSourceDataGrid(options)` accepts:

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `dataSource` | `LocalDataSource<TData>` | — | Local data source from `useLocalDataSource` or `createLocalDataSource`. Required. |
| `listParams` | `LocalDataSourceQueryParams` | — | Query params passed to `dataSource.list` after the active view/search/filter state is merged by `useDocyrusDataGrid`. |
| `systemViews` | `Array<SavedDataGridView>` | — | Developer-defined views shown in `DataGridViewSelect`. These are local and not persisted to a backend. |
| `defaultRowGroupingColumn` | `string` | — | Field slug used for initial grouping when the active view does not define grouping. |
| `enableServerExportMenu` | `boolean` | `false` | Server export menu is disabled by default for local data. |
| `...gridOptions` | `Omit<UseDocyrusDataGridOptions, 'client' \| 'appSlug' \| 'dataSourceSlug' \| 'collection' \| 'listParams'>` | — | All other supported `useDocyrusDataGrid` options, including toolbar toggles, column mapping, row actions, side filters, pivot filters, formatting, and change tracking. |

### Return Value

The hook returns `UseDocyrusDataGridResult<TData>`.

| Property | Description |
|----------|-------------|
| `table` | TanStack Table instance for `<DataGrid>`. |
| `gridProps` | Props to spread onto `<DataGrid>`. |
| `toolbar` | Pre-wired toolbar with view select, search, filters, grouping, sorting, fields, display, reload, and custom toolbar slots. |
| `items` | Current local rows returned by `dataSource.list`. |
| `resolvedListParams` | Merged local query params sent to `dataSource.list`. |
| `reload` | Refetch local rows and refresh view metadata. |
| `views` / `activeViewId` / `setActiveViewId` | Local/system view state exposed by the underlying data-grid view hook. |

## Playground

See the local demo in the playground at `apps/playground/src/pages/local-data-source-page.tsx`.

---

# useLocalDataSource
URL: /docs/web/hooks/use-local-data-source

Create an in-memory Docyrus-compatible data source from a JSON array, with local CRUD and Docyrus-style query parameters.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-local-data-source
```

**Dependencies:**
- [jsonata](https://www.npmjs.com/package/jsonata)

## Overview

`useLocalDataSource` turns a JSON array of objects into a local `LocalDataSource` object that behaves like a lightweight Docyrus data source. It is useful for prototypes, offline demos, local previews, and components that should run without a backend.

It supports:

- Local CRUD: `list`, `get`, `create`, `update`, `updateMany`, `delete`, `deleteMany`.
- Docyrus-compatible field metadata, JSON Schema metadata, or inferred fields from row values.
- Local query payloads modeled after `GET /apps/:appId/data-sources/:dataSourceId/items`.
- `filterKeyword`, nested `filters`, `orderBy`, `limit`, `offset`, `columns`, `distinctColumns`, `calculations`, and basic `pivot`.
- Local formula columns using JSONata expressions.

`childQueries` are accepted in the query type but intentionally skipped.

## Usage

```tsx
'use client';

import { useState } from 'react';

import { useLocalDataSource } from '@docyrus/ui/library/hooks/use-local-data-source';

type Deal = {
  id: string;
  account: string;
  stage: string;
  amount: number;
  probability: number;
};

const fields = [
  { slug: 'id', name: 'ID', type: 'field-identity', readOnly: true },
  { slug: 'account', name: 'Account', type: 'field-text' },
  { slug: 'stage', name: 'Stage', type: 'field-select' },
  { slug: 'amount', name: 'Amount', type: 'field-money' },
  { slug: 'probability', name: 'Probability', type: 'field-percent' },
  { slug: 'weighted_amount', name: 'Weighted Amount', type: 'field-money', readOnly: true }
];

export function LocalDeals() {
  const [rows, setRows] = useState<Array<Deal>>([
    { id: '1', account: 'Northwind Labs', stage: 'Proposal', amount: 120000, probability: 0.6 },
    { id: '2', account: 'Contoso Finance', stage: 'Discovery', amount: 80000, probability: 0.35 }
  ]);

  const deals = useLocalDataSource<Deal>({
    id: 'local-deals',
    slug: 'deals',
    appSlug: 'local',
    name: 'Local Deals',
    data: rows,
    metadata: fields,
    onDataChange: setRows
  });

  async function loadPipeline() {
    const response = await deals.list({
      columns: 'stage',
      formulas: {
        weighted_amount: { jsonata: 'amount * probability' }
      },
      calculations: [
        { field: 'id', func: 'count', name: 'deals' },
        { field: 'weighted_amount', func: 'sum', name: 'weighted_pipeline' }
      ],
      orderBy: 'weighted_pipeline DESC'
    });

    console.log(response.data, response.meta.total);
  }

  return <button onClick={loadPipeline}>Load pipeline</button>;
}
```

## Metadata

### Docyrus fields

Pass an array of field-like objects when you already know the Docyrus field shape:

```ts
const metadata = [
  { slug: 'name', name: 'Name', type: 'field-text' },
  { slug: 'amount', name: 'Amount', type: 'field-money' },
  { slug: 'closed_on', name: 'Closed On', type: 'field-date' }
];
```

### JSON Schema

Pass a JSON Schema object and field types are mapped automatically:

```ts
const metadata = {
  type: 'object',
  properties: {
    name: { type: 'string', title: 'Name' },
    email: { type: 'string', format: 'email' },
    amount: { type: 'number' },
    active: { type: 'boolean' },
    status: { type: 'string', enum: ['Open', 'Closed'] }
  }
};
```

### Inferred fields

If `metadata` is omitted, fields are inferred from all row keys. Values are sampled to choose simple Docyrus field types such as `field-text`, `field-number`, `field-checkbox`, `field-date`, `field-dateTime`, `field-email`, `field-url`, and `field-multiSelect`.

## Query Support

`list(params)` returns `{ data, meta: { total } }`. `meta.total` is always the number of rows after formulas, keyword search, filters, calculations/pivot, sorting, and before `limit`/`offset`.

| Parameter | Description |
|-----------|-------------|
| `columns` | Comma-separated field slugs. Used for projection and grouping when `calculations` are present. |
| `filterKeyword` | Case-insensitive search across serialized row values. |
| `filters` | Nested `and`/`or` filter groups with common Docyrus/querybuilder operators. |
| `formulas` | Map of virtual column aliases to JSONata expressions. |
| `calculations` | Aggregations over the filtered row set. Supports `count`, `sum`, `avg`, `min`, `max`, `jsonb_agg`, `json_agg`, and `array_agg`. |
| `pivot` | Basic cross-tab output using the first matrix definition. |
| `orderBy` | String, object, or array sort definition. |
| `limit` / `offset` | Local pagination. |
| `distinctColumns` | Dedupe rows by one or more columns before projection. |

### Filters

Supported operators include equality/inequality, comparisons, text matching, set membership, ranges, null/empty checks, and their negated variants:

```ts
await source.list({
  filters: {
    combinator: 'and',
    rules: [
      { field: 'stage', operator: 'notIn', value: ['Closed Lost'] },
      { field: 'amount', operator: '>=', value: 50000 },
      {
        combinator: 'or',
        rules: [
          { field: 'region', operator: '=', value: 'EMEA' },
          { field: 'region', operator: '=', value: 'APAC' }
        ]
      }
    ]
  }
});
```

### JSONata formulas

Each formula runs against the current row and writes a virtual column with the formula key:

```ts
await source.list({
  formulas: {
    weighted_amount: { jsonata: 'amount * probability' },
    display_name: { jsonata: 'account & " · " & stage' }
  },
  columns: 'account, weighted_amount, display_name'
});
```

## API Reference

### `useLocalDataSource(options)`

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `data` | `Array<TData>` | — | Source rows. Required. Rows without `id` receive a generated id from `getRowId`. |
| `metadata` | `LocalDataSourceMetadata` | inferred | Docyrus field list or JSON Schema. |
| `id` | `string` | `'local-data-source'` | Data source id exposed through `dataSource.id`. |
| `slug` | `string` | `'local'` | Data source slug. |
| `appSlug` | `string` | `'local'` | App slug used by the local client shim. |
| `name` | `string` | `'Local Data Source'` | Display name. |
| `getRowId` | `(row, index) => string` | `index + 1` | Generates ids for rows that do not already have an `id`. |
| `onDataChange` | `(data) => void` | — | Called after local create/update/delete operations. Use this to keep React state in sync. |

### Return Value

| Property | Type | Description |
|----------|------|-------------|
| `dataSource` | `DataSource` | Docyrus-compatible data source metadata. |
| `fields` | `Array<DataSourceField>` | Normalized field list. |
| `getData` | `() => Array<TData>` | Return the current local rows. |
| `setData` | `(data) => void` | Replace all rows and call `onDataChange`. |
| `list` | `(params?) => Promise<{ data, meta: { total } }>` | Query rows with local Docyrus-style query params. |
| `get` | `(id) => Promise<TData \| undefined>` | Read one row by `id`. |
| `create` | `(record) => Promise<TData>` | Insert a row and generate an id when needed. |
| `update` | `(id, patch) => Promise<TData>` | Patch one row. Throws if the id does not exist. |
| `updateMany` | `({ records }) => Promise<Array<TData>>` | Bulk patch rows by id. Matches the collection shape used by `useDocyrusDataGrid`. |
| `delete` | `(id) => Promise<void>` | Delete one row. |
| `deleteMany` | `({ recordIds }) => Promise<void>` | Bulk delete rows by id. |
| `client` | `RestApiClient` | Local client shim used by `useLocalDataSourceDataGrid` for metadata/view requests. |

## `createLocalDataSource`

`createLocalDataSource(options)` exposes the same local data source object without using React. Use it in tests, examples, or non-React local query helpers.

---

# useNumberFormat
URL: /docs/web/hooks/use-number-format

Provider-agnostic number formatting context for Docyrus UI components. Mirror of useDateFormat — wired automatically by DocyrusTenantProvider, but works with any number formatting library.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-number-format
```

The module exports `useNumberFormat()` (hook) and `
  );
}
```

## API Reference

### `useNumberFormat()`

Returns `NumberFormatContextValue`.

| Field | Type | Description |
|-------|------|-------------|
| `formatNumber` | `(value: unknown, options?: NumberFormatOptions) => string` | Formats a number using the active provider's strategy. |

### `NumberFormatOptions`

| Field | Type | Description |
|-------|------|-------------|
| `variant` | `'number' \| 'currency' \| 'percent'` | Output style. Default `'number'`. `'percent'` multiplies the input by 100 and appends `%`. |
| `currency` | `string` | ISO 4217 currency code, used when `variant === 'currency'`. |
| `decimalPrecision` | `number` | Override the locale's default fraction digits. Pass `0` for identifier-like numerics. |
| `thousandSeparator` | `string` | Override the locale's default thousands grouping. Empty string disables grouping. |

### `<NumberFormatProvider>`

| Prop | Type | Description |
|------|------|-------------|
| `formatNumber` | `NumberFormatFn` | Required. The implementation that backs `useNumberFormat()` inside the tree. |
| `children` | `ReactNode` | Tree to wrap. |

### `isDefaultNumberFormatContext(ctx)`

Returns `true` when the value returned by `useNumberFormat()` is the built-in no-provider sentinel (raw `String(value)` renderer) rather than a real provider. Internal hooks use this to avoid shadowing a cell's locale-aware fallback when no provider is mounted. Most apps don't need to call it directly.

## Type Exports

| Type | Description |
|------|-------------|
| `NumberFormatFn` | Signature of the formatter function. |
| `NumberFormatOptions` | Options accepted by `formatNumber`. |
| `NumberFormatContextValue` | Shape returned by `useNumberFormat()`. |

---

# useParameterPersistence
URL: /docs/web/hooks/use-parameter-persistence

useParameterPersistence hook.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-parameter-persistence
```

## Usage

```tsx
import { resolvePersistConfig } from '@docyrus/ui/library/hooks/use-parameter-persistence';

const result = resolvePersistConfig(...);
```

## API Reference

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `prop` | `PersistStateProp \| undefined` | `—` | — |

**Returns:** `ResolvedPersistConfig \| null`

---

# useSpeechRecognition
URL: /docs/web/hooks/use-speech-recognition

useSpeechRecognition hook.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-speech-recognition
```

## Usage

```tsx
import { useSpeechRecognition } from '@docyrus/ui/library/hooks/use-speech-recognition';

function MyComponent() {
  const result = useSpeechRecognition(...);
}
```

## API Reference

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `{` | `—` | `—` | — |

---

# useUiTranslation
URL: /docs/web/hooks/use-ui-translation

useUiTranslation hook.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-ui-translation
```

## Usage

```tsx
import { useUiTranslation } from '@docyrus/ui/hooks/use-ui-translation';

function MyComponent() {
  const { ... } = useUiTranslation();
}
```

## API Reference

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|

**Returns:** `{ t: TranslateFn }`