# API Reference
URL: /docs/guide/api-reference

Reference documentation for the @docyrus/api-client — type-safe REST client with streaming, token management, and error handling.

The `@docyrus/api-client` is a modern, type-safe API client for JavaScript and TypeScript. It works across Web, React Native, and Node.js.

## Installation

```bash tab="pnpm"
pnpm add @docyrus/api-client
```

```bash tab="npm"
npm install @docyrus/api-client
```

## Quick Start

```tsx
import { RestApiClient } from '@docyrus/api-client';

const client = new RestApiClient({
  baseUrl: 'https://api.example.com',
  getAccessToken: () => getToken(),
});

// GET request
const users = await client.get('/v1/users');

// POST with body
const user = await client.post('/v1/users', {
  body: { name: 'Ali', email: 'ali@example.com' },
});
```

## Client Configuration

```tsx
const client = new RestApiClient({
  baseUrl: string;              // API base URL (required)
  getAccessToken: () => Promise<string | null>;  // Token provider
  refreshToken?: () => Promise<string | null>;   // Auto-refresh on 401
  onUnauthorized?: () => void;  // Callback when auth fails
  headers?: Record<string, string>;  // Default headers
  timeout?: number;             // Request timeout (ms)
});
```

| Option | Type | Required | Description |
|--------|------|----------|-------------|
| `baseUrl` | `string` | Yes | API base URL |
| `getAccessToken` | `() => Promise<string \| null>` | Yes | Returns current access token |
| `refreshToken` | `() => Promise<string \| null>` | No | Called on 401 — refreshes token and retries |
| `onUnauthorized` | `() => void` | No | Called when both token and refresh fail |
| `headers` | `Record<string, string>` | No | Default headers for every request |
| `timeout` | `number` | No | Request timeout in milliseconds |

## HTTP Methods

### GET

```tsx
// Simple GET
const data = await client.get('/v1/users');

// With query parameters
const data = await client.get('/v1/users', {
  params: { page: 1, limit: 20, search: 'Ali' },
});

// With type safety
interface User { id: string; name: string; email: string }
const users = await client.get<User[]>('/v1/users');
```

### POST

```tsx
const user = await client.post<User>('/v1/users', {
  body: { name: 'Ali', email: 'ali@example.com' },
});
```

### PUT / PATCH

```tsx
await client.put('/v1/users/123', {
  body: { name: 'Updated Name' },
});

await client.patch('/v1/users/123', {
  body: { email: 'new@example.com' },
});
```

### DELETE

```tsx
await client.delete('/v1/users/123');
```

## Streaming

For real-time data and server-sent events:

```tsx
const stream = client.stream('/v1/chat/completions', {
  method: 'POST',
  body: { message: 'Hello', model: 'gpt-4' },
});

for await (const chunk of stream) {
  console.log(chunk); // Process each chunk as it arrives
}
```

## Error Handling

```tsx
import { ApiError } from '@docyrus/api-client';

try {
  await client.post('/v1/users', { body: userData });
} catch (error) {
  if (error instanceof ApiError) {
    console.log(error.status);   // HTTP status code
    console.log(error.message);  // Error message
    console.log(error.data);     // Response body
  }
}
```

| Property | Type | Description |
|----------|------|-------------|
| `status` | `number` | HTTP status code (400, 401, 404, 500, etc.) |
| `message` | `string` | Error message from the server |
| `data` | `unknown` | Full response body |

## Token Management

The client handles token refresh automatically:

1. Request fails with `401 Unauthorized`
2. Client calls `refreshToken()` to get a new token
3. Original request is retried with the new token
4. If refresh also fails, `onUnauthorized()` is called

```tsx
const client = new RestApiClient({
  baseUrl: 'https://api.example.com',
  getAccessToken: () => tokenStore.getAccessToken(),
  refreshToken: async () => {
    const newToken = await authService.refresh();
    tokenStore.setAccessToken(newToken);
    return newToken;
  },
  onUnauthorized: () => {
    // Redirect to login
    router.push('/login');
  },
});
```

## Usage with React

### With TanStack Query

```tsx
import { useQuery, useMutation } from '@tanstack/react-query';

function useUsers() {
  const client = useApiClient(); // Your custom hook

  return useQuery({
    queryKey: ['users'],
    queryFn: () => client.get<User[]>('/v1/users'),
  });
}

function useCreateUser() {
  const client = useApiClient();

  return useMutation({
    mutationFn: (data: CreateUserInput) =>
      client.post<User>('/v1/users', { body: data }),
  });
}
```

### With React Native

The API client works identically in React Native — no additional configuration needed:

```tsx
import { RestApiClient } from '@docyrus/api-client';
import * as SecureStore from 'expo-secure-store';

const client = new RestApiClient({
  baseUrl: 'https://api.example.com',
  getAccessToken: () => SecureStore.getItemAsync('access_token'),
});
```

## Related

- [Packages](/docs/guide/packages) — All `@docyrus/*` NPM packages
- [CLI](/docs/guide/cli) — Authentication and project setup commands

---

# Changelog
URL: /docs/guide/changelog

Latest releases and updates for the Docyrus CLI.

Track the latest changes, features, and bug fixes for the `@docyrus/cli` command-line tool.

For component library releases, see [Web Releases](/docs/web/guide/releases) and [Native Releases](/docs/native/guide/releases).

---

# CLI
URL: /docs/guide/cli

The Docyrus CLI for authentication, project scaffolding, and component management.

The `@docyrus/cli` is a command-line tool that handles authentication, project creation, component installation, theme management, and code generation from the Docyrus registry.

[<img src="https://img.shields.io/npm/v/@docyrus/cli?color=cb0000&label=npm" alt="npm" />](https://www.npmjs.com/package/@docyrus/cli)

## Installation

You can use the CLI directly with `npx` without installing it globally:

```bash
npx @docyrus/cli <command>
```

Or install it globally:

```bash tab="pnpm"
pnpm add -g @docyrus/cli
```

```bash tab="npm"
npm install -g @docyrus/cli
```

```bash tab="yarn"
yarn global add @docyrus/cli
```

```bash tab="bun"
bun add -g @docyrus/cli
```

Or install it globally for quicker access:

  
  
  

Once installed globally, you can use the `docyrus` command directly:

```bash
docyrus add button
```

## Commands

### Authentication

| Command | Description |
|---------|-------------|
| `docyrus login` | Log in with browser-based SSO |
| `docyrus login --email` | Log in with email and password |
| `docyrus login -e user@example.com` | Log in with pre-filled email |
| `docyrus logout` | Clear stored auth tokens |
| `docyrus whoami` | Display current logged-in user info |

### Components

| Command | Description |
|---------|-------------|
| `docyrus add [items...]` | Add components, hooks, or utilities from the registry |
| `docyrus add button dialog` | Add multiple components at once |
| `docyrus add --all web` | Install all web components |
| `docyrus add --all react-native` | Install all React Native components |
| `docyrus add --all-web` | Shortcut for `--all web` |
| `docyrus add --all-rn` | Shortcut for `--all react-native` |
| `docyrus add --overwrite` | Skip file conflict prompts |
| `docyrus add --dry-run` | Preview installation without writing files |
| `docyrus add --path ./src/ui` | Custom target path for installation |
| `docyrus update` | Update all installed Docyrus components to latest |
| `docyrus update button toast` | Update specific components only |
| `docyrus update rn-card rn-button` | Update specific native components |
| `docyrus update --prune` | Update and remove components deleted from registry |
| `docyrus update --dry-run` | Preview what would be updated |
| `docyrus list` | List available components, hooks, and utilities |
| `docyrus list --packages` | List published @docyrus npm packages |

### Themes

| Command | Description |
|---------|-------------|
| `docyrus themes list` | List available theme presets |
| `docyrus themes add [name]` | Apply a theme preset to your project |
| `docyrus themes add --url <url>` | Apply theme from a share URL |
| `docyrus themes add --file <path>` | Apply theme from a local JSON file |
| `docyrus themes current` | Show current `:root` and `.dark` CSS variables |

### Project Creation

| Command | Description |
|---------|-------------|
| `docyrus create [name]` | Create a new project from a template (interactive) |
| `docyrus create my-app --nextjs` | Create with a specific framework |
| `docyrus create my-app --react --shadcn --zustand` | Create with full stack flags |

**Framework flags:** `--nextjs`, `--react`, `--vue`

**UI library flags:** `--shadcn`

**State management flags:** `--zustand`, `--tanstack-query`, `--tanstack-vue-query`

**Linter flags:** `--eslint`, `--biome`, `--no-linter`

**Package manager flags:** `--pnpm`, `--npm`, `--yarn`, `--bun`

**Styling options (shadcn):**

| Option | Description |
|--------|-------------|
| `--style <style>` | Component style (vega, nova, maia, lyra, mira) |
| `--base-color <color>` | Base color for shadcn (zinc, slate, neutral, stone, gray) |
| `--rtl` | Enable RTL (right-to-left) support |

**Other options:**

| Option | Description |
|--------|-------------|
| `--alias <prefix>` | Custom import alias prefix (must start with @) |
| `-p, --path <path>` | Target directory path |

### Code Generation

| Command | Description |
|---------|-------------|
| `docyrus generate api-spec` | Download OpenAPI spec from the Docyrus API |
| `docyrus generate api-spec -o ./spec.json` | Custom output path for the spec file |
| `docyrus generate db [spec]` | Generate TanStack Query collections from an OpenAPI spec |
| `docyrus generate db ./spec.json -o ./src/api` | Custom output directory |

### Project Setup

| Command | Description |
|---------|-------------|
| `docyrus commitlint` | Set up commitlint, husky, and lint-staged |
| `docyrus commitlint --scopes cli,ui,web` | Pre-configure allowed commit scopes |
| `docyrus commitlint --monorepo` | Auto-detect workspace scopes for monorepo |
| `docyrus commitlint --scope-strategy required` | Set scope strategy (required, optional, none) |
| `docyrus commitlint -y` | Accept defaults and overwrite existing files |

### System

| Command | Description |
|---------|-------------|
| `docyrus info` | Display CLI version, Node.js, OS, and auth status |
| `docyrus config --show` | Show current configuration |
| `docyrus config --token` | Update token for private templates |
| `docyrus config --theme` | Change help output color theme |
| `docyrus upgrade` | Upgrade CLI to the latest version |
| `docyrus completion <shell>` | Generate shell completion script (bash, zsh, fish) |

### Global Options

| Option | Description |
|--------|-------------|
| `--json` | Output results in JSON format |
| `-v, --version` | Display CLI version |
| `-h, --help` | Display help information |

## Examples

```bash
# Log in and add components
docyrus login
docyrus add button dialog date-time-picker
docyrus add --all web
docyrus add --all-rn

# Update all installed components
docyrus update

# Update specific components
docyrus update button toast rn-card

# Update and remove components deleted from registry
docyrus update --prune

# Browse and apply a theme
docyrus themes list
docyrus themes add midnight

# Create a new Next.js project with shadcn and Zustand
docyrus create my-app --nextjs --shadcn --zustand --pnpm

# Create with Nova style and RTL support
docyrus create my-app --nextjs --shadcn --style nova --rtl --pnpm

# Generate TanStack Query code from an API spec
docyrus generate api-spec
docyrus generate db openapi.json --output src/

# Set up commitlint in a monorepo
docyrus commitlint --monorepo
```

---

# Distributions
URL: /docs/guide/distributions

Component distributions and core libraries that power Docyrus UI.

Docyrus UI is built on top of the shadcn ecosystem and depends on several major open-source libraries. This page lists the component distributions we work alongside and the core libraries our components are built on.

## Component Distributions

## Web Libraries

The major open-source libraries that Docyrus UI web components are built on.

| Library | Description | Used In |
|---------|-------------|---------|
| [Radix UI](https://www.radix-ui.com) | Unstyled, accessible UI primitives. Provides the foundation for dialogs, popovers, tooltips, dropdowns, and more. | Primitives, Components |
| [Plate.js](https://platejs.org) | Plugin-based rich text editor framework. Powers the WYSIWYG editor with AI, comments, mentions, tables, and 30+ plugins. | Editor |
| [Motion](https://motion.dev) | Production-ready animation library for React. Used for enter/exit transitions, layout animations, and gesture interactions. | Components |
| [TanStack Table](https://tanstack.com/table) | Headless table library with sorting, filtering, grouping, and virtualization. Powers the Data Grid component. | Data Grid |
| [TanStack Virtual](https://tanstack.com/virtual) | Headless virtualization for large lists and grids. Provides smooth scrolling for thousands of rows. | Data Grid |
| [TanStack Form](https://tanstack.com/form) | Type-safe form library with framework-agnostic validation. Powers the form-fields system with schema-driven field rendering. | Form Fields |
| [React Day Picker](https://daypicker.dev) | Flexible date picker component. Powers the Day Picker and Date Time Picker components. | Day Picker, Date Time Picker |
| [Recharts](https://recharts.org) | Composable charting library built on D3. Used for data visualization components. | Charts |
| [CodeMirror](https://codemirror.net) | Extensible code editor with syntax highlighting, autocompletion, and language support. | Code Editor |
| [Embla Carousel](https://www.embla-carousel.com) | Lightweight carousel library with touch support and extensible plugins. | Carousel |
| [cmdk](https://cmdk.paco.me) | Fast, composable command palette component. | Command |
| [Vaul](https://vaul.emilkowal.ski) | Drawer component for React with smooth touch interactions. | Drawer |
| [Sonner](https://sonner.emilkowal.ski) | Opinionated toast notification library. | Toast |

## React Native Libraries

The core libraries that Docyrus UI native components are built on.

| Library | Description | Used In |
|---------|-------------|---------|
| [Expo](https://expo.dev) | Framework and platform for universal React applications. Provides managed workflow, OTA updates, and native module access. | All Native Components |
| [Uniwind](https://github.com/nicepkg/uniwind) | Build-time Tailwind CSS v4 integration for React Native. Compiles `className` to `StyleSheet` objects via a Metro plugin. | All Native Components |
| [React Native SVG](https://github.com/software-mansion/react-native-svg) | SVG support for React Native. Used for icons, charts, and vector graphics. | Icons, Charts |
| [Expo Document Picker](https://docs.expo.dev/versions/latest/sdk/document-picker) | Native file picker with multi-file support. | Document Picker |
| [Expo Localization](https://docs.expo.dev/versions/latest/sdk/localization) | Locale and internationalization utilities. | Localize |
| [React Native Reanimated](https://docs.swmansion.com/react-native-reanimated) | High-performance animation library running on the UI thread. Used for gesture-driven animations. | Animations |
| [React Native Gesture Handler](https://docs.swmansion.com/react-native-gesture-handler) | Native gesture system for touch interactions. Powers swipe, pinch, and drag gestures. | Gestures |
| [DateTimePicker](https://github.com/react-native-datetimepicker/datetimepicker) | Native date and time picker for iOS and Android. | DateTimePicker |

---

# FAQ
URL: /docs/guide/faq

Frequently asked questions about Docyrus UI — installation, usage, customization, and troubleshooting.

## General

### What is Docyrus UI?

Docyrus UI is a component library built on top of [shadcn/ui](https://ui.shadcn.com) primitives. It provides **business-grade compound components** — calendars, data grids, pricing engines, resource schedulers, and more — that go beyond basic UI primitives.

Unlike traditional component libraries published to NPM, Docyrus UI uses the **shadcn registry pattern**: components are copied into your project as source code, giving you full ownership and customization control.

### How is Docyrus UI different from shadcn/ui?

| | shadcn/ui | Docyrus UI |
|---|----------|------------|
| **Focus** | UI primitives (Button, Card, Dialog) | Business components (Calendar, DataGrid, PricingEngine) |
| **Built on** | Radix UI | shadcn/ui + Radix UI + AI Elements |
| **Distribution** | Registry (copy to project) | Registry (copy to project) |
| **Styling** | Tailwind CSS | Tailwind CSS v4 |
| **Variants** | CVA | CVA (web), tailwind-variants (native) |
| **Platform** | Web only | Web + React Native |

Docyrus UI **includes** shadcn/ui as vendor primitives. When you install a Docyrus component, its shadcn dependencies are installed automatically.

### Is Docyrus UI free?

Yes. Docyrus UI is open-source. You can use it in personal and commercial projects.

### Which frameworks are supported?

**Web:**
- Next.js 16+ (App Router)
- React 19 + Vite
- Vue 3.5 + Vite (via templates)

**Native:**
- React Native 0.83+ with Expo SDK 55+

### Do I need to use the CLI?

The CLI (`@docyrus/cli`) is the recommended way to install components. It handles dependency resolution, import rewriting, and file placement automatically.

---

## Installation

### Why do components get copied into my project?

This is the **shadcn pattern** — instead of importing from `node_modules`, components live in your codebase. Benefits:

- **Full control**: Modify any component to match your needs
- **No version lock-in**: Components don't break when the library updates
- **Tree-shaking**: Only the components you use are in your bundle
- **No runtime dependency**: Your project has zero dependency on Docyrus UI at runtime

### Where do components get installed?

| Type | Default Location |
|------|-----------------|
| Docyrus components | `components/docyrus/` |
| shadcn primitives | `components/ui/` |
| Hooks | `hooks/` |
| Utilities | `lib/` |
| Native components | `components/docyrus-native/` |

These paths are configurable via your project's `components.json`.

### How do I install all components at once?

```bash
# All web components
docyrus add --all web

# All native components
docyrus add --all react-native

# Specific component
docyrus add calendar
docyrus add rn-button
```

### I'm getting peer dependency warnings

Docyrus components may require peer dependencies like `motion`, `date-fns`, or `@tanstack/react-table`. The CLI warns you about missing peer dependencies during installation. Install them with:

```bash
pnpm add <package-name>
```

---

## Customization

### How do I change the color theme?

Docyrus UI uses CSS variables with the OKLCH color space. You can:

1. **Use the Theme Generator** at [docyrus.dev/themes](/themes) to create a custom theme visually
2. **Edit CSS variables** directly in your `globals.css` — see the [Web Theming Guide](/docs/web/guide/theming) or [Native Theming Guide](/docs/native/guide/theming)

### Can I use a different color palette?

Yes. The theme system supports any OKLCH color values. You can change the primary, secondary, accent, and all other colors by updating CSS variables. The [Theme Generator](/themes) provides preset palettes and a visual editor.

### How do I override component styles?

Every component accepts a `className` prop for Tailwind CSS overrides:

```tsx

```

For deeper customization, edit the component source directly — it's in your project.

### Can I use CSS Modules or styled-components instead of Tailwind?

Docyrus UI is built with Tailwind CSS v4 and CVA (class-variance-authority). While you can technically replace the styling system, it would require significant refactoring. We recommend using Tailwind CSS for the best experience.

---

## React Native

### Do I need Expo?

Expo is **recommended** but not strictly required. Docyrus UI Native components use React Native APIs and some Expo packages. Components that require Expo-specific packages are clearly marked in the [Expo section](/docs/native/expo) of the documentation.

### Can I preview native components in a browser?

No. Native components are previewed exclusively via the **Expo Preview app** on a physical device or simulator. The documentation shows a QR code to open the preview in Expo Go.

### How do I style native components?

Native components use **Tailwind CSS via Uniwind** for static styling (`className` prop) and the `useDocyTheme()` hook only for dynamic values (Ionicons colors, platform shadows, runtime lookups). See the [Native Theming Guide](/docs/native/guide/theming) for setup and customization.

```tsx
{/* Static styling — use className */}

{/* Dynamic values only — use useDocyTheme() */}
const { colors, isDark } = useDocyTheme();

```

---

## Troubleshooting

### Components don't render / blank screen

1. Make sure you have `'use client'` directive if using Next.js App Router
2. Check that all peer dependencies are installed
3. For Tailwind v4, ensure you have `@import` directives in your CSS entry file

### TypeScript errors after installation

Components are installed as `.tsx` source files. Ensure your `tsconfig.json` has:

```json
{
  "compilerOptions": {
    "jsx": "react-jsx",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}
```

The `@/` alias must resolve to your `src/` directory (or wherever components are installed).

### Motion animations not working

Components using motion (framer-motion) require the `motion` package:

```bash
pnpm add motion
```

If using Next.js, ensure the component has `'use client'` since motion requires client-side rendering.

### Icons not displaying

Docyrus uses icons from Lucide React and the Docyrus CDN (Font Awesome Brands + Huge Icons). Install Lucide:

```bash
pnpm add lucide-react
```

For Docyrus CDN icons, ensure your CSP (Content Security Policy) allows loading from the Docyrus CDN domain.

### How do I report a bug?

Open an issue on GitHub with:
- Component name and version
- Framework and version (Next.js, Vite, Expo)
- Minimal reproduction steps
- Expected vs actual behavior

---

# Internationalization (i18n)
URL: /docs/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.

## 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)

---

# Introduction
URL: /docs/guide

Docyrus UI is an open-source component distribution built with React, TypeScript, Tailwind CSS, and the shadcn registry.

## What is Docyrus UI?

Docyrus UI is an open-source component distribution — not an installable NPM library. Built with React, TypeScript, Tailwind CSS v4, and the shadcn registry, it provides production-ready UI components, hooks, and utilities that you copy directly into your codebase.

Inspired by the shadcn/ui philosophy, Docyrus UI gives you full ownership and control over every component. No wrapper overhead, no version lock-in — just open code that lives in your project.

## Not a library — an open component distribution

Traditional UI libraries ship as NPM packages you import. When something doesn't fit, you're stuck waiting for a PR or working around the API.

Docyrus UI takes a different approach. Every component is installed as source code into your project. You own it, you modify it, you style it however you want. The registry simply delivers the starting point.

## What's included

- **Components** — Production-ready UI pieces built on top of Radix UI, covering forms, data display, navigation, feedback, and more. Each component uses CVA for variant management and supports full theme customization.

- **Hooks** — Reusable React hooks for common patterns like debouncing, media queries, local storage, disclosure state, and more.

- **Utilities** — Helper functions for class name merging, type-safe operations, and other everyday needs.

- **Icons** — Docyrus Icon system with support for Font Awesome, Huge Icons, and custom icon sets via CDN.

## Why Docyrus UI?

- **Open source and copy-first** — Every component lives in your codebase. Full ownership, zero lock-in.

- **Built on shadcn registry** — Install components with the `shadcn` CLI or the Docyrus CLI. Same workflow you already know.

- **Tailwind CSS v4** — Designed from the ground up for Tailwind CSS v4 with CSS-based configuration and modern utility classes.

- **Type-safe** — Full TypeScript support with strict types, generics, and inference across all components, hooks, and utilities.

- **Accessible by default** — Built on Radix UI primitives with WAI-ARIA compliance, keyboard navigation, and screen reader support out of the box.

- **Performance-conscious** — Sensible defaults, tree-shakeable exports, and minimal runtime overhead. Ship only what you use.

---

# Installation
URL: /docs/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.

---

# Native Migration
URL: /docs/guide/native-migration

How to migrate from other React Native UI libraries to Docyrus UI Native.

## Overview

This guide helps you migrate from popular React Native UI libraries to Docyrus UI Native. Each section covers the key differences and provides mapping tables for common components.

## From React Native Paper

[React Native Paper](https://callstack.github.io/react-native-paper/) uses Material Design. Docyrus UI Native follows a custom design system with semantic color tokens.

### Theme Migration

```tsx
// Before (Paper)
import { Provider as PaperProvider, DefaultTheme } from 'react-native-paper';

const theme = {
  ...DefaultTheme,
  colors: {
    ...DefaultTheme.colors,
    primary: '#6200ee',
    accent: '#03dac4',
  },
};

// After (Docyrus)
import { DocyThemeProvider } from '@/lib/theme';

```

### Component Mapping

| Paper | Docyrus UI Native | Notes |
|-------|-------------------|-------|
| `

// After (Docyrus)
import { DocyThemeProvider } from '@/lib/theme';

```

### Styling Differences

```tsx
// NativeBase — utility props

// Docyrus — style objects with theme
const { colors, spacing, borderRadius } = useDocyTheme();

```

### Component Mapping

| NativeBase | Docyrus UI Native | Notes |
|------------|-------------------|-------|
| `

// Docyrus — style objects
const { colors, spacing, borderRadius } = useDocyTheme();

```

## From Gluestack UI

[Gluestack UI](https://gluestack.io/) is the spiritual successor to NativeBase with a new styling engine.

### Key Differences

| Feature | Gluestack | Docyrus UI Native |
|---------|-----------|-------------------|
| Styling | `styled()` + utility props | `useDocyTheme()` + style objects |
| Tokens | Design tokens via config | Semantic colors + spacing scale |
| Components | Headless + styled | Styled with theme |

### Migration Pattern

```tsx
// Gluestack
import { Button, ButtonText } from '@gluestack-ui/themed';

// Docyrus
import { Button } from '@/components/docyrus-native/button';

```

## General Migration Tips

### 1. Install DocyThemeProvider First

Before migrating any components, set up the theme provider at your app root. This ensures all migrated components have access to theme values.

### 2. Migrate Bottom-Up

Start with leaf components (Button, Input, Badge) and work up to compound components (DataTable, Form). This minimizes cascading changes.

### 3. Keep Both Libraries Temporarily

During migration, you can use both libraries simultaneously. Remove the old library only after all components are migrated.

```json
{
  "dependencies": {
    "react-native-paper": "^5.0.0",
    "@docyrus/ui-native": "workspace:*"
  }
}
```

### 4. Map Your Color Tokens

Create a mapping between your current library's color tokens and Docyrus semantic tokens:

| Your Token | Docyrus Token |
|-----------|---------------|
| `primary` | `colors.primary` |
| `onPrimary` | `colors.primaryForeground` |
| `surface` | `colors.card` |
| `onSurface` | `colors.cardForeground` |
| `error` | `colors.destructive` |
| `background` | `colors.background` |

### 5. Replace Theme Hooks

Find-and-replace your current theme hook with Docyrus:

```tsx
// Common patterns to replace
useTheme()        → useDocyTheme()
theme.colors.X    → colors.X
theme.spacing.X   → spacing[X]
theme.roundness   → borderRadius.DEFAULT
```

### 6. Update Imports

After installing Docyrus components via CLI:

```bash
docyrus add rn-button rn-input rn-card rn-badge
```

Update imports:

```tsx
// Before
import { Button } from 'react-native-paper';

// After
import { Button } from '@/components/docyrus-native/button';
```

---

# Packages
URL: /docs/guide/packages

Official Docyrus NPM packages for authentication, API integration, code generation, and developer tooling.

All `@docyrus/*` packages are published on [NPM](https://www.npmjs.com/org/docyrus) and designed to work together. They cover authentication, API integration, code generation, and developer tooling for Docyrus-powered applications.

## Core

### @docyrus/api-client

A modern, type-safe API client for JavaScript and TypeScript with support for multiple backend types, streaming, error handling, and token management.

[<img src="https://img.shields.io/npm/v/@docyrus/api-client?color=cb0000&label=npm" alt="npm" />](https://www.npmjs.com/package/@docyrus/api-client)

```bash tab="pnpm"
pnpm add @docyrus/api-client
```

```bash tab="npm"
npm install @docyrus/api-client
```

```bash tab="yarn"
yarn add @docyrus/api-client
```

```bash tab="bun"
bun add @docyrus/api-client
```

---

### @docyrus/signin

Authentication provider for Docyrus apps. Supports React, Vue, Electron, and Next.js SSR with OAuth2 and session management.

[<img src="https://img.shields.io/npm/v/@docyrus/signin?color=cb0000&label=npm" alt="npm" />](https://www.npmjs.com/package/@docyrus/signin)

```bash tab="pnpm"
pnpm add @docyrus/signin
```

```bash tab="npm"
npm install @docyrus/signin
```

```bash tab="yarn"
yarn add @docyrus/signin
```

```bash tab="bun"
bun add @docyrus/signin
```

---

### @docyrus/i18n

Internationalization provider with API-based and static translation support, cookie-based locale persistence, and variable interpolation. Works across **Web**, **React Native**, and **Vue**.

[<img src="https://img.shields.io/npm/v/@docyrus/i18n?color=cb0000&label=npm" alt="npm" />](https://www.npmjs.com/package/@docyrus/i18n)

```bash tab="pnpm"
pnpm add @docyrus/i18n
```

```bash tab="npm"
npm install @docyrus/i18n
```

```bash tab="yarn"
yarn add @docyrus/i18n
```

```bash tab="bun"
bun add @docyrus/i18n
```

#### Web Usage

Wrap your app with `DocyrusI18nProvider`:

```tsx
import { DocyrusI18nProvider } from '@docyrus/i18n';

;
}
```

**Key differences from web:**

| Feature | Web | React Native |
|---------|-----|-------------|
| Import | `@docyrus/i18n` | `@docyrus/i18n/rn` |
| Provider | `DocyrusI18nProvider` | `DocyI18nProvider` |
| Hook | `useTranslation()`, `useDocyrusI18n()` | `useI18n()`, `useTranslation()` |
| Storage | Cookie (`CookieStorageAdapter`) | MMKV / AsyncStorage (`getString`/`setString`) |
| Languages | Any locale string | `'en'` \| `'tr'` |
| Translation format | Flat dictionary | Nested (`{ en: { common: { key: 'val' } } }`) |
| Fallback without provider | Throws | Graceful (returns key) |

---

## Dev Tools

### @docyrus/tanstack-db-generator

Code generator for TanStack Query and database integration. Generates typed collections from OpenAPI specs for the Docyrus API.

[<img src="https://img.shields.io/npm/v/@docyrus/tanstack-db-generator?color=cb0000&label=npm" alt="npm" />](https://www.npmjs.com/package/@docyrus/tanstack-db-generator)

```bash tab="pnpm"
pnpm add -D @docyrus/tanstack-db-generator
```

```bash tab="npm"
npm install -D @docyrus/tanstack-db-generator
```

```bash tab="yarn"
yarn add -D @docyrus/tanstack-db-generator
```

```bash tab="bun"
bun add -D @docyrus/tanstack-db-generator
```

---

### @docyrus/rules

Shared ESLint and Biome configurations for Docyrus projects. Provides consistent linting and formatting rules across your codebase.

[<img src="https://img.shields.io/npm/v/@docyrus/rules?color=cb0000&label=npm" alt="npm" />](https://www.npmjs.com/package/@docyrus/rules)

```bash tab="pnpm"
pnpm add -D @docyrus/rules
```

```bash tab="npm"
npm install -D @docyrus/rules
```

```bash tab="yarn"
yarn add -D @docyrus/rules
```

```bash tab="bun"
bun add -D @docyrus/rules
```

#### ESLint Configs

Each config is composable — combine them based on your stack:

| Config | Import | Use for |
|--------|--------|---------|
| `baseConfig` | `@docyrus/rules/eslint` | All projects (TypeScript, import ordering, stylistic) |
| `reactConfig` | `@docyrus/rules/eslint` | React projects (hooks, react-refresh) |
| `nextjsConfig` | `@docyrus/rules/eslint` | Next.js projects (core-web-vitals) |
| `reactNativeConfig` | `@docyrus/rules/eslint` | React Native / Expo projects |
| `vueConfig` | `@docyrus/rules/eslint` | Vue 3 projects |
| `astroConfig` | `@docyrus/rules/eslint` | Astro projects |
| `electronConfig` | `@docyrus/rules/eslint` | Electron projects |
| `aiConfig` | `@docyrus/rules/eslint` | AI/LLM integrations |

**Next.js setup** (`eslint.config.mjs`):

```js
import { baseConfig, reactConfig, nextjsConfig } from '@docyrus/rules/eslint';

export default [
  ...baseConfig,
  ...reactConfig,
  ...nextjsConfig,
];
```

**React + Vite setup:**

```js
import { baseConfig, reactConfig } from '@docyrus/rules/eslint';

export default [
  ...baseConfig,
  ...reactConfig,
];
```

**Expo / React Native setup:**

```js
import { baseConfig, reactConfig, reactNativeConfig } from '@docyrus/rules/eslint';

export default [
  ...baseConfig,
  ...reactConfig,
  ...reactNativeConfig,
];
```

**Key rules enforced by `baseConfig`:**

| Rule | Behavior |
|------|----------|
| TypeScript | Consistent type imports (`import type`), no unused vars |
| Import ordering | `type → builtin → external → internal → sibling` with blank lines |
| Unused imports | Error on unused imports |
| Stylistic | 2-space indent, single quotes, semicolons, trailing commas |
| React named imports | `React.*` namespace access forbidden — use named imports |
| No `console.log` | Warning (allows `warn`, `error`, `info`) |
| `prefer-const` | Error |

#### Biome Configs

Available as JSON preset files:

| Config | Path |
|--------|------|
| Base | `@docyrus/rules/biome/base` |
| React | `@docyrus/rules/biome/react` |
| Next.js | `@docyrus/rules/biome/nextjs` |
| Vue | `@docyrus/rules/biome/vue` |
| Astro | `@docyrus/rules/biome/astro` |
| Cloudflare | `@docyrus/rules/biome/cloudflare` |
| Electron | `@docyrus/rules/biome/electron` |

**Biome setup** (`biome.json`):

```json
{
  "extends": ["@docyrus/rules/biome/nextjs"]
}
```

## Utilities

### @docyrus/addin-client

Client for embedded add-ins to communicate with the host app from an iframe using postMessage. Handles handshake, RPC calls, and event dispatching.

[<img src="https://img.shields.io/npm/v/@docyrus/addin-client?color=cb0000&label=npm" alt="npm" />](https://www.npmjs.com/package/@docyrus/addin-client)

```bash tab="pnpm"
pnpm add @docyrus/addin-client
```

```bash tab="npm"
npm install @docyrus/addin-client
```

```bash tab="yarn"
yarn add @docyrus/addin-client
```

```bash tab="bun"
bun add @docyrus/addin-client
```

---

### @docyrus/logo-asset-generator

CLI tool to generate favicon and app icons from a source logo. Produces all required sizes for web, iOS, and Android.

[<img src="https://img.shields.io/npm/v/@docyrus/logo-asset-generator?color=cb0000&label=npm" alt="npm" />](https://www.npmjs.com/package/@docyrus/logo-asset-generator)

```bash tab="pnpm"
pnpm add -D @docyrus/logo-asset-generator
```

```bash tab="npm"
npm install -D @docyrus/logo-asset-generator
```

```bash tab="yarn"
yarn add -D @docyrus/logo-asset-generator
```

```bash tab="bun"
bun add -D @docyrus/logo-asset-generator
```

---

### @docyrus/dom-selector-client

DOM selector CLI client for programmatic element selection and inspection in web pages.

[<img src="https://img.shields.io/npm/v/@docyrus/dom-selector-client?color=cb0000&label=npm" alt="npm" />](https://www.npmjs.com/package/@docyrus/dom-selector-client)

```bash tab="pnpm"
pnpm add @docyrus/dom-selector-client
```

```bash tab="npm"
npm install @docyrus/dom-selector-client
```

```bash tab="yarn"
yarn add @docyrus/dom-selector-client
```

```bash tab="bun"
bun add @docyrus/dom-selector-client
```

---

# Troubleshooting
URL: /docs/guide/troubleshooting

Common issues and solutions when using Docyrus UI.

## Verify your versions

Make sure your environment meets or exceeds these minimum versions to ensure Docyrus UI components work correctly.

### Web

| Dependency | Minimum Version |
|---|---|
| React | 19 |
| Next.js | 16 |
| Tailwind CSS | 4.0 |
| Node.js | 18 |
| Radix UI | 1.4.0 |

### React Native

| Dependency | Minimum Version |
|---|---|
| React | 19 |
| React Native | 0.83 |
| Expo SDK | 55 |
| Uniwind | 0.1+ |
| Node.js | 18 |

## Web

### 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.

## React Native

### Theme not applying

Make sure your app is wrapped with `DocyThemeProvider` at the root level. Without this provider, components will fall back to default styles. If using Expo Router, wrap it in your root `_layout.tsx`.

### Expo Go compatibility

Some native components require a development build and won't work in Expo Go. Check the component's `expoGoCompatible` flag in the documentation. Components that use native modules (e.g., `expo-document-picker`, `expo-localization`) require `npx expo prebuild` and a custom dev client.

### Missing peer dependencies

Native components declare peer dependencies for packages like `react-native-svg`, `expo-document-picker`, and `expo-localization`. If you see module resolution errors, install the required peer dependency:

```bash
npx expo install react-native-svg
```

### Font Awesome icons not loading

If `DocyrusIcon` is not rendering icons, make sure you've configured the icon CDN path correctly. Native icons are loaded from the Docyrus CDN — verify your network connectivity and that the icon name matches the registry.

## 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.

---

# rn-accordion
URL: /docs/native/components/accordion

Collapsible content sections with animated expand/collapse transitions.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-accordion
```

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

## Usage

```tsx
import {
  AccordionRoot,
  AccordionItem,
  AccordionTrigger,
  AccordionContent
} from '@/components/docyrus-native/accordion';

    
  
  
    
  

```

## API Reference

### AccordionRoot

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `type` | `'single' \| 'multiple'` | `'single'` | Whether one or multiple items can be open at once |
| `collapsible` | `boolean` | `true` | Whether open items can be collapsed (single mode only) |
| `value` | `string \| string[]` | — | Controlled open value(s) |
| `defaultValue` | `string \| string[]` | — | Initial open value(s) |
| `onValueChange` | `(val: string \| string[]) => void` | — | Callback when open state changes |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size of trigger and content text |
| `variant` | `'default' \| 'outline' \| 'filled'` | `'default'` | Visual style variant |
| `chevronPosition` | `'left' \| 'right'` | `'right'` | Position of the expand/collapse chevron |
| `spacing` | `'none' \| 'sm' \| 'md' \| 'lg'` | `'none'` | Gap between accordion items |
| `className` | `string` | — | Additional CSS classes |
| `children` | `ReactNode` | — | AccordionItem children |

### AccordionItem

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `string` | — | Unique identifier for the item |
| `disabled` | `boolean` | — | Whether the item is disabled |
| `className` | `string` | — | Item container CSS classes |
| `children` | `ReactNode` | — | Trigger and content children |

### AccordionTrigger

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode` | — | Trigger label (string or custom node) |
| `className` | `string` | — | Trigger CSS classes |
| `textClassName` | `string` | — | Text CSS classes |

### AccordionContent

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode` | — | Content to show when expanded (string or custom node) |
| `className` | `string` | — | Content area CSS classes |

## Components

| Component | Description |
|-----------|-------------|
| `AccordionRoot` | Root container managing open state and context |
| `AccordionItem` | Individual collapsible item wrapper |
| `AccordionTrigger` | Pressable header that toggles open/close |
| `AccordionContent` | Animated content area that expands/collapses |

## Type Exports

| Type | Description |
|------|-------------|
| `AccordionRootProps` | Props for AccordionRoot component |
| `AccordionItemProps` | Props for AccordionItem component |
| `AccordionTriggerProps` | Props for AccordionTrigger component |
| `AccordionContentProps` | Props for AccordionContent component |
| `AccordionType` | `'single' \| 'multiple'` |
| `AccordionSize` | `'sm' \| 'md' \| 'lg'` |
| `AccordionVariant` | `'default' \| 'outline' \| 'filled'` |

---

# rn-alert-dialog
URL: /docs/native/components/alert-dialog

Confirmation dialog with customizable title, description, variant colors, and action buttons.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-alert-dialog
```

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

## Usage

```tsx
import { AlertDialog } from '@/components/docyrus-native/alert-dialog';

<AlertDialog
  title="Delete item?"
  description="This action cannot be undone."
  variant="destructive"
  onConfirm={() => handleDelete()}
  onCancel={() => console.log('cancelled')}
/>
```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `visible` | `boolean` | — | Controlled visibility state |
| `onConfirm` | `() => void` | — | Confirm button handler |
| `onCancel` | `() => void` | — | Cancel button handler |
| `title` | `string` | `'Are you sure?'` | Dialog title text |
| `description` | `string` | — | Dialog description text |
| `confirmText` | `string` | `'Confirm'` | Confirm button label |
| `cancelText` | `string` | `'Cancel'` | Cancel button label |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Dialog size |
| `variant` | `'default' \| 'destructive' \| 'success' \| 'warning'` | `'default'` | Confirm button color variant |
| `backdropOpacity` | `'light' \| 'medium' \| 'dark'` | `'medium'` | Backdrop darkness level |
| `animationType` | `'none' \| 'slide' \| 'fade'` | `'fade'` | Modal animation type |
| `trigger` | `ReactNode \| ((opts: { onPress: () => void }) => ReactNode)` | — | Custom trigger element or render function |
| `triggerLabel` | `string` | — | Default trigger button label |
| `className` | `string` | — | Additional CSS classes |
| `backdropClassName` | `string` | — | Backdrop CSS classes |
| `contentClassName` | `string` | — | Content area CSS classes |
| `titleClassName` | `string` | — | Title text CSS classes |
| `descriptionClassName` | `string` | — | Description text CSS classes |
| `confirmButtonClassName` | `string` | — | Confirm button CSS classes |
| `cancelButtonClassName` | `string` | — | Cancel button CSS classes |
| `triggerClassName` | `string` | — | Trigger CSS classes |

## Type Exports

| Type | Description |
|------|-------------|
| `AlertDialogProps` | Props for AlertDialog component |
| `AlertDialogVariant` | `'default' \| 'destructive' \| 'success' \| 'warning'` |
| `AlertDialogSize` | `'sm' \| 'md' \| 'lg'` |

---

# rn-alert
URL: /docs/native/components/alert

Inline alert banner with variant colors, sizes, and rounded corners.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-alert
```

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

## Usage

```tsx
import { Alert } from '@/components/docyrus-native/alert';

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `title` | `string` | — | Alert title text |
| `description` | `string` | — | Alert description text |
| `variant` | `'info' \| 'success' \| 'warning' \| 'destructive'` | `'info'` | Visual style variant |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Component size |
| `rounded` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Border radius preset |
| `className` | `string` | — | Additional CSS classes |
| `titleClassName` | `string` | — | Title text CSS classes |
| `descriptionClassName` | `string` | — | Description text CSS classes |

## Type Exports

| Type | Description |
|------|-------------|
| `AlertProps` | Props for Alert component |
| `AlertVariant` | `'info' \| 'success' \| 'warning' \| 'destructive'` |
| `AlertSize` | `'sm' \| 'md' \| 'lg'` |

---

# rn-avatar
URL: /docs/native/components/avatar

User avatar component with image, initials fallback, status indicator, and pressable support.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-avatar
```

## Usage

```tsx
import { Avatar } from '@/components/docyrus-native/avatar';

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `uri` | `string` | — | Image URI for the avatar |
| `name` | `string` | — | Name used to generate initials fallback |
| `shape` | `'circle' \| 'rounded'` | `'circle'` | Avatar shape |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Avatar size |
| `variant` | `'solid' \| 'soft' \| 'outline'` | `'solid'` | Background style variant |
| `status` | `'none' \| 'online' \| 'offline' \| 'busy' \| 'away'` | `'none'` | Status indicator dot |
| `onPress` | `() => void` | — | Press handler (wraps in Pressable) |
| `className` | `string` | — | Additional CSS classes |
| `textClassName` | `string` | — | Initials text CSS classes |

## Type Exports

| Type | Description |
|------|-------------|
| `AvatarProps` | Props for Avatar component |
| `AvatarShape` | `'circle' \| 'rounded'` |
| `AvatarSize` | `'xs' \| 'sm' \| 'md' \| 'lg'` |
| `AvatarVariant` | `'solid' \| 'soft' \| 'outline'` |
| `AvatarStatus` | `'none' \| 'online' \| 'offline' \| 'busy' \| 'away'` |

---

# rn-badge
URL: /docs/native/components/badge

Small label component for status, categories, or counts with variant and size options.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-badge
```

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

## Usage

```tsx
import { Badge } from '@/components/docyrus-native/badge';

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode` | — | Badge content |
| `variant` | `'default' \| 'secondary' \| 'destructive' \| 'outline'` | `'default'` | Visual style variant |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Badge size |
| `className` | `string` | — | Additional CSS classes |
| `textClassName` | `string` | — | Text CSS classes |

## Type Exports

| Type | Description |
|------|-------------|
| `BadgeProps` | Props for Badge component |
| `BadgeVariant` | `'default' \| 'secondary' \| 'destructive' \| 'outline'` |
| `BadgeSize` | `'sm' \| 'md' \| 'lg'` |

---

# rn-button
URL: /docs/native/components/button

Pressable button component with multiple variants and sizes for user actions.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-button
```

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

## Usage

```tsx
import { Button } from '@/components/docyrus-native/button';

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode` | — | Button content |
| `variant` | `'default' \| 'secondary' \| 'destructive' \| 'outline' \| 'ghost' \| 'link'` | `'default'` | Visual style variant |
| `size` | `'sm' \| 'md' \| 'lg' \| 'icon'` | `'md'` | Button size |
| `disabled` | `boolean` | `false` | Disable interaction |
| `loading` | `boolean` | `false` | Show loading spinner with smooth layout transition |
| `feedbackVariant` | `'scale' \| 'scale-highlight' \| 'none'` | `'scale-highlight'` | Press feedback animation type |
| `onPress` | `() => void` | — | Press handler |
| `onLongPress` | `() => void` | — | Long press handler |
| `className` | `string` | — | Additional CSS classes |
| `textClassName` | `string` | — | Text CSS classes |
| `accessibilityLabel` | `string` | — | Accessibility label |

## Type Exports

| Type | Description |
|------|-------------|
| `ButtonProps` | Props for Button component |
| `ButtonVariant` | `'default' \| 'secondary' \| 'destructive' \| 'outline' \| 'ghost' \| 'link'` |
| `ButtonSize` | `'sm' \| 'md' \| 'lg' \| 'icon'` |

---

# rn-card
URL: /docs/native/components/card

Versatile card container with header, footer, animations, and pressable support.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-card
```

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

## Usage

```tsx
import { Card } from '@/components/docyrus-native/card';

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode` | — | Card body content |
| `variant` | `'default' \| 'outlined' \| 'elevated' \| 'ghost'` | `'default'` | Visual style variant |
| `size` | `'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Card padding and text sizing |
| `header` | `ReactNode` | — | Header content rendered above body |
| `title` | `string` | — | Card title text |
| `description` | `string` | — | Card description text |
| `footer` | `ReactNode` | — | Footer content rendered below body |
| `onPress` | `() => void` | — | Press handler (makes card pressable) |
| `animation` | `'none' \| 'fade' \| 'scale' \| 'slideUp' \| 'slideDown' \| 'slideLeft' \| 'slideRight'` | `'none'` | Entry animation type |
| `className` | `string` | — | Additional CSS classes |
| `titleClassName` | `string` | — | Title text CSS classes |
| `descriptionClassName` | `string` | — | Description text CSS classes |

## Type Exports

| Type | Description |
|------|-------------|
| `CardProps` | Props for Card component |
| `CardVariant` | `'default' \| 'outlined' \| 'elevated' \| 'ghost'` |
| `CardSize` | `'sm' \| 'md' \| 'lg' \| 'xl'` |
| `CardAnimationType` | `'none' \| 'fade' \| 'scale' \| 'slideUp' \| 'slideDown' \| 'slideLeft' \| 'slideRight'` |

---

# rn-carousel
URL: /docs/native/components/carousel

Horizontal content carousel with pagination dots and arrow navigation.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-carousel
```

## Usage

```tsx
import { Carousel } from '@/components/docyrus-native/carousel';

, , ]}
  showDots
  showArrows
/>
```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `ReactNode[]` | — | Array of slide content (required) |
| `autoPlay` | `boolean` | `false` | Enable auto-play |
| `autoPlayInterval` | `number` | `3000` | Auto-play interval (ms) |
| `showDots` | `boolean` | `true` | Show pagination dots |
| `showArrows` | `boolean` | `false` | Show navigation arrows |
| `loop` | `boolean` | `false` | Enable infinite loop |
| `onIndexChange` | `(index: number) => void` | — | Slide change callback |
| `className` | `string` | — | Additional CSS classes |
| `itemClassName` | `string` | — | Slide item CSS classes |
| `dotClassName` | `string` | — | Inactive dot CSS classes |
| `activeDotClassName` | `string` | — | Active dot CSS classes |

## Type Exports

| Type | Description |
|------|-------------|
| `CarouselProps` | Props for Carousel component |

---

# rn-checkbox
URL: /docs/native/components/checkbox

Standalone checkbox component with optional label and size variants.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-checkbox
```

## Usage

```tsx
import { Checkbox } from '@/components/docyrus-native/checkbox';

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `checked` | `boolean` | `false` | Checkbox state |
| `onCheckedChange` | `(checked: boolean) => void` | — | State change handler |
| `disabled` | `boolean` | `false` | Disable interaction |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Checkbox size |
| `label` | `string` | — | Optional label text |
| `className` | `string` | — | Additional CSS classes |
| `labelClassName` | `string` | — | Label CSS classes |
| `accessibilityLabel` | `string` | — | Accessibility label |

## Type Exports

| Type | Description |
|------|-------------|
| `CheckboxProps` | Props for Checkbox component |
| `CheckboxSize` | `'sm' \| 'md' \| 'lg'` |

---

# rn-collapsible
URL: /docs/native/components/collapsible

Expandable/collapsible container with animated height transitions.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-collapsible
```

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

## Usage

```tsx
import { Collapsible, CollapsibleTrigger, CollapsibleContent } from '@/components/docyrus-native/collapsible';

  
  
  

```

## API Reference

### Collapsible

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `open` | `boolean` | — | Controlled open state |
| `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled) |
| `onOpenChange` | `(open: boolean) => void` | — | Open state change handler |
| `children` | `ReactNode` | — | Trigger and Content children |
| `className` | `string` | — | Additional CSS classes |

### CollapsibleTrigger

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode` | — | Trigger content |
| `className` | `string` | — | Additional CSS classes |

### CollapsibleContent

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode` | — | Collapsible content |
| `className` | `string` | — | Additional CSS classes |

## Components

| Component | Description |
|-----------|-------------|
| `Collapsible` | Root container with context provider |
| `CollapsibleTrigger` | Pressable trigger that toggles content |
| `CollapsibleContent` | Animated content container |

## Type Exports

| Type | Description |
|------|-------------|
| `CollapsibleProps` | Props for Collapsible |
| `CollapsibleTriggerProps` | Props for CollapsibleTrigger |
| `CollapsibleContentProps` | Props for CollapsibleContent |

---

# rn-drawer
URL: /docs/native/components/drawer

Slide-in side panel with animated entrance, backdrop, and swipe-to-dismiss support.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-drawer
```

**Dependencies:**
- [react-native-gesture-handler](https://www.npmjs.com/package/react-native-gesture-handler)
- [react-native-reanimated](https://www.npmjs.com/package/react-native-reanimated)
- [react-native-worklets](https://www.npmjs.com/package/react-native-worklets)

## Usage

```tsx
import { Drawer } from '@/components/docyrus-native/drawer';

}
>
  

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `visible` | `boolean` | — | Controlled visibility state |
| `onClose` | `() => void` | — | Close handler |
| `side` | `'left' \| 'right'` | `'left'` | Side the drawer slides in from |
| `width` | `number` | `300` | Drawer width in pixels |
| `variant` | `'default' \| 'elevated' \| 'minimal' \| 'glass'` | `'default'` | Visual variant |
| `backdropOpacity` | `'light' \| 'medium' \| 'dark'` | `'medium'` | Backdrop darkness level |
| `header` | `ReactNode` | — | Header content element |
| `footer` | `ReactNode` | — | Footer content element |
| `swipeToDismiss` | `boolean` | `true` | Enable swipe gesture to close |
| `animationDuration` | `number` | `200` | Open/close animation duration in ms |
| `children` | `ReactNode` | — | Drawer body content |
| `trigger` | `ReactNode \| ((opts: { onPress: () => void }) => ReactNode)` | — | Custom trigger element or render function |
| `triggerLabel` | `string` | `'Open Drawer'` | Default trigger button label |
| `hideTrigger` | `boolean` | `true` | Hide default trigger when no custom trigger |
| `className` | `string` | — | Additional CSS classes |
| `backdropClassName` | `string` | — | Backdrop CSS classes |
| `contentClassName` | `string` | — | Content area CSS classes |
| `headerClassName` | `string` | — | Header CSS classes |
| `footerClassName` | `string` | — | Footer CSS classes |
| `triggerClassName` | `string` | — | Trigger CSS classes |

## Type Exports

| Type | Description |
|------|-------------|
| `DrawerProps` | Props for Drawer component |
| `DrawerSide` | `'left' \| 'right'` |
| `DrawerVariant` | `'default' \| 'elevated' \| 'minimal' \| 'glass'` |

---

# rn-dropdown-menu
URL: /docs/native/components/dropdown-menu

Menu popup component with items, separators, and destructive actions.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-dropdown-menu
```

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

## Usage

```tsx
import { DropdownMenu } from '@/components/docyrus-native/dropdown-menu';

}
  items={[
    { label: 'Edit', onPress: handleEdit },
    { label: 'Duplicate', onPress: handleDuplicate },
    { type: 'separator' },
    { label: 'Delete', onPress: handleDelete, destructive: true },
  ]}
/>
```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `trigger` | `ReactNode` | — | Trigger element (required) |
| `items` | `DropdownMenuEntry[]` | — | Menu items and separators (required) |
| `align` | `'start' \| 'end'` | — | Menu alignment |
| `className` | `string` | — | Additional CSS classes |
| `menuClassName` | `string` | — | Menu panel CSS classes |

### DropdownMenuItem

| Property | Type | Description |
|----------|------|-------------|
| `label` | `string` | Item label |
| `icon` | `ReactNode` | Optional icon |
| `onPress` | `() => void` | Press handler |
| `destructive` | `boolean` | Destructive action styling |
| `disabled` | `boolean` | Disable this item |

### DropdownMenuSeparator

| Property | Type | Description |
|----------|------|-------------|
| `type` | `'separator'` | Separator marker |

## Type Exports

| Type | Description |
|------|-------------|
| `DropdownMenuProps` | Props for DropdownMenu |
| `DropdownMenuItem` | Menu item type |
| `DropdownMenuSeparator` | Separator type |
| `DropdownMenuEntry` | Union of item and separator |

---

# Overview
URL: /docs/native/components

React Native UI primitives for mobile applications with iOS and Android support.

Browse all available Docyrus UI native primitives. These are the core building blocks — buttons, inputs, cards, modals, and more.

## Available Components

| Component | Description |
|-----------|-------------|
| [rn-accordion](/docs/native/components/accordion) | Collapsible content sections with animated expand/collapse transitions. |
| [rn-alert](/docs/native/components/alert) | Inline alert banner with variant colors, sizes, and rounded corners. |
| [rn-alert-dialog](/docs/native/components/alert-dialog) | Confirmation dialog with customizable title, description, variant colors, and action buttons. |
| [rn-avatar](/docs/native/components/avatar) | User avatar component with image, initials fallback, status indicator, and pressable support. |
| [rn-badge](/docs/native/components/badge) | Small label component for status, categories, or counts with variant and size options. |
| [rn-button](/docs/native/components/button) | Pressable button component with multiple variants and sizes for user actions. |
| [rn-card](/docs/native/components/card) | Versatile card container with header, footer, animations, and pressable support. |
| [rn-carousel](/docs/native/components/carousel) | Horizontal content carousel with pagination dots and arrow navigation. |
| [rn-checkbox](/docs/native/components/checkbox) | Standalone checkbox component with optional label and size variants. |
| [rn-collapsible](/docs/native/components/collapsible) | Expandable/collapsible container with animated height transitions. |
| [rn-confirmation-button](/docs/native/components/confirmation-button) | Button that opens a countdown confirmation modal before executing the action. |
| [rn-date-time-picker](/docs/native/components/date-time-picker) | A modal date and time picker with calendar grid and scrollable time controls. |
| [rn-date-time-range-picker](/docs/native/components/date-time-range-picker) | A modal date-time range picker with start/end tabs, calendar grid, and time controls. |
| [rn-day-picker](/docs/native/components/day-picker) | An inline calendar day picker supporting single, multiple, and range selection modes. |
| [rn-docyrus-icon](/docs/native/components/docyrus-icon) | CDN-powered icon component supporting Font Awesome, Huge Icons, emojis, and custom libraries. |
| [rn-drawer](/docs/native/components/drawer) | Slide-in side panel with animated entrance, backdrop, and swipe-to-dismiss support. |
| [rn-dropdown-menu](/docs/native/components/dropdown-menu) | Menu popup component with items, separators, and destructive actions. |
| [rn-duration-select](/docs/native/components/duration-select) | Duration picker with hours and minutes grid, supporting multiple display formats. |
| [rn-empty-state](/docs/native/components/empty-state) | Placeholder display for empty content areas with variant-specific icons and actions. |
| [rn-error-state](/docs/native/components/error-state) | Error display with variant-specific messaging, retry actions, and expandable error details. |
| [rn-fab](/docs/native/components/fab) | Floating action button with expandable menu, position control, and variant colors. |
| [rn-grid](/docs/native/components/grid) | Responsive grid layout with configurable columns, gap control, and spanning grid items. |
| [rn-input](/docs/native/components/input) | Text input primitive with size variants, icons, and validation states. |
| [rn-input-otp](/docs/native/components/input-otp) | OTP code input with segmented cells for verification codes. |
| [rn-label](/docs/native/components/label) | Form label component with size variants and required indicator. |
| [rn-mini-calendar](/docs/native/components/mini-calendar) | Compact date picker calendar with month navigation and locale-aware day names. |
| [rn-modal](/docs/native/components/modal) | Flexible modal dialog with preset types, header/footer configurations, and position options. |
| [rn-network-banner](/docs/native/components/network-banner) | Animated banner for displaying network connectivity status with retry and dismiss actions. |
| [rn-notification-stack](/docs/native/components/notification-stack) | Stacked notification cards with dismiss, load more, and action buttons. |
| [rn-pagination](/docs/native/components/pagination) | Page navigation control with page numbers, ellipsis, and info text. |
| [rn-phone-input](/docs/native/components/phone-input) | Phone number input with country code picker and search. |
| [rn-popover](/docs/native/components/popover) | Floating content panel with arrow, placement options, and multiple visual variants. |
| [rn-progress](/docs/native/components/progress) | Linear progress bar with label, size, and color variant options. |
| [rn-qr-code](/docs/native/components/qr-code) | QR code display component with size variants and optional logo overlay. |
| [rn-radio-group](/docs/native/components/radio-group) | Radio button group component with compound pattern for single-option selection. |
| [rn-rating](/docs/native/components/rating) | Star rating input with half-star support and custom icon rendering. |
| [rn-search-input](/docs/native/components/search-input) | Search input with debounce and clear button, supporting manual and automatic search modes. |
| [rn-select](/docs/native/components/select) | Dropdown select component with modal picker for option selection. |
| [rn-separator](/docs/native/components/separator) | Visual divider component for horizontal or vertical separation. |
| [rn-skeleton](/docs/native/components/skeleton) | Animated loading placeholders with card, list, table, and calendar presets. |
| [rn-slider](/docs/native/components/slider) | Draggable slider with custom range, step, tooltip, and track marks. |
| [rn-spinner](/docs/native/components/spinner) | Loading indicator component with size and variant options. |
| [rn-status](/docs/native/components/status) | Status indicator badge with dot and colored variants. |
| [rn-stepper](/docs/native/components/stepper) | Step indicator component for multi-step wizards and onboarding flows. |
| [rn-switch](/docs/native/components/switch) | Toggle switch component with optional label and size variants. |
| [rn-table](/docs/native/components/table) | Lightweight data table with sorting, striped rows, grouping, and built-in pagination. |
| [rn-tabs](/docs/native/components/tabs) | Tabbed navigation with horizontal/vertical orientation and multiple visual variants. |
| [rn-textarea](/docs/native/components/textarea) | Multi-line text input component with size variants and validation. |
| [rn-timeline](/docs/native/components/timeline) | Vertical timeline component for displaying chronological events. |
| [rn-toast](/docs/native/components/toast) | Stackable toast notification system with rich colors, swipe-to-dismiss, and a Sonner-like imperative API. |
| [rn-toggle](/docs/native/components/toggle) | Toggle button component with pressed state and variant options. |
| [rn-toggle-group](/docs/native/components/toggle-group) | Segmented control component for single or multiple option selection. |
| [rn-tooltip](/docs/native/components/tooltip) | Contextual popup with configurable placement, arrow, and visual variants. |
| [rn-tree-view](/docs/native/components/tree-view) | Hierarchical tree component with expand/collapse, search, and optional checkboxes. |
| [rn-wheel-picker](/docs/native/components/wheel-picker) | Scrollable wheel picker for selecting from a list of options with snap-to-item behavior. |

---

# rn-input-otp
URL: /docs/native/components/input-otp

OTP code input with segmented cells for verification codes.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-input-otp
```

## Usage

```tsx
import { InputOtp } from '@/components/docyrus-native/input-otp';

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `string` | `''` | Current OTP value |
| `onValueChange` | `(value: string) => void` | — | Value change handler |
| `onComplete` | `(value: string) => void` | — | Called when all digits are entered |
| `length` | `number` | `6` | Number of digits |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Cell size |
| `disabled` | `boolean` | `false` | Disable interaction |
| `invalid` | `boolean` | `false` | Show invalid state |
| `mask` | `boolean` | `false` | Mask entered digits |
| `className` | `string` | — | Additional CSS classes |
| `cellClassName` | `string` | — | Individual cell CSS classes |
| `textClassName` | `string` | — | Digit text CSS classes |
| `accessibilityLabel` | `string` | — | Accessibility label |

## Type Exports

| Type | Description |
|------|-------------|
| `InputOtpProps` | Props for InputOtp component |
| `InputOtpSize` | `'sm' \| 'md' \| 'lg'` |

---

# rn-input
URL: /docs/native/components/input

Text input primitive with size variants, icons, and validation states.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-input
```

## Usage

```tsx
import { Input } from '@/components/docyrus-native/input';

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Input size |
| `disabled` | `boolean` | `false` | Disable interaction |
| `invalid` | `boolean` | `false` | Show invalid state |
| `startIcon` | `ReactNode` | — | Icon at the start |
| `endIcon` | `ReactNode` | — | Icon at the end |
| `className` | `string` | — | Additional CSS classes |
| `inputClassName` | `string` | — | TextInput CSS classes |

All standard `TextInputProps` are also supported (except `style`).

## Type Exports

| Type | Description |
|------|-------------|
| `InputProps` | Props for Input component |
| `InputSize` | `'sm' \| 'md' \| 'lg'` |

---

# rn-label
URL: /docs/native/components/label

Form label component with size variants and required indicator.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-label
```

## Usage

```tsx
import { Label } from '@/components/docyrus-native/label';

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `string` | — | Label text |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Label size |
| `required` | `boolean` | `false` | Show required asterisk |
| `disabled` | `boolean` | `false` | Muted color for disabled state |
| `nativeID` | `string` | — | Native ID for accessibility linking |
| `className` | `string` | — | Additional CSS classes |

## Type Exports

| Type | Description |
|------|-------------|
| `LabelProps` | Props for Label component |
| `LabelSize` | `'sm' \| 'md' \| 'lg'` |

---

# rn-modal
URL: /docs/native/components/modal

Flexible modal dialog with preset types, header/footer configurations, and position options.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-modal
```

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

## Usage

```tsx
import { Modal } from '@/components/docyrus-native/modal';

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `visible` | `boolean` | — | Whether the modal is visible |
| `onClose` | `() => void` | — | Close handler |
| `onConfirm` | `() => void` | — | Confirm handler (for confirm/picker types) |
| `title` | `string` | — | Modal title |
| `closeOnOverlayPress` | `boolean` | — | Close on backdrop tap (auto-configured by modalType) |
| `size` | `'sm' \| 'md' \| 'lg' \| 'full'` | `'md'` | Modal width/height size |
| `position` | `'center' \| 'bottom'` | `'center'` | Modal position on screen |
| `variant` | `'default' \| 'elevated' \| 'bordered'` | `'default'` | Visual variant |
| `backdropOpacity` | `number` | `0.4` | Backdrop opacity (0 to 1) |
| `modalType` | `'default' \| 'info' \| 'confirm' \| 'picker' \| 'custom'` | `'default'` | Preset type (auto-configures header/footer) |
| `headerType` | `'none' \| 'title-close' \| 'title-actions'` | — | Header layout (auto-set by modalType unless custom) |
| `footerType` | `'none' \| 'actions'` | — | Footer layout (auto-set by modalType unless custom) |
| `confirmText` | `string` | `'Confirm'` | Confirm button label |
| `cancelText` | `string` | `'Cancel'` | Cancel button label |
| `header` | `ReactNode` | — | Custom header element |
| `footer` | `ReactNode` | — | Custom footer element |
| `children` | `ReactNode` | — | Modal body content |
| `className` | `string` | — | Additional CSS classes |
| `backdropClassName` | `string` | — | Backdrop CSS classes |
| `contentClassName` | `string` | — | Content area CSS classes |
| `headerClassName` | `string` | — | Header CSS classes |
| `titleClassName` | `string` | — | Title text CSS classes |
| `footerClassName` | `string` | — | Footer CSS classes |
| `accessibilityLabel` | `string` | — | Accessibility label for the modal |

### Modal Type Presets

| Type | Header | Footer | Close on overlay |
|------|--------|--------|------------------|
| `default` / `info` | title-close (if title set) | none | yes |
| `confirm` | none | actions | no |
| `picker` | title-actions | none | yes |
| `custom` | configurable | configurable | yes |

## Type Exports

| Type | Description |
|------|-------------|
| `ModalProps` | Props for Modal component |
| `ModalType` | `'default' \| 'info' \| 'confirm' \| 'picker' \| 'custom'` |
| `ModalHeaderType` | `'none' \| 'title-close' \| 'title-actions'` |
| `ModalFooterType` | `'none' \| 'actions'` |
| `ModalSize` | `'sm' \| 'md' \| 'lg' \| 'full'` |
| `ModalPosition` | `'center' \| 'bottom'` |
| `ModalVariant` | `'default' \| 'elevated' \| 'bordered'` |

---

# rn-pagination
URL: /docs/native/components/pagination

Page navigation control with page numbers, ellipsis, and info text.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-pagination
```

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

## Usage

```tsx
import { Pagination } from '@/components/docyrus-native/pagination';

const [page, setPage] = useState(1);

```

### With Info Text

```tsx

```

### First/Last Buttons

```tsx

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `currentPage` | `number` | — | Current active page (1-based) |
| `totalPages` | `number` | — | Total number of pages |
| `onPageChange` | `(page: number) => void` | — | Callback when page changes |
| `totalItems` | `number` | — | Total item count (used for info text) |
| `pageSize` | `number` | — | Items per page (used for info text) |
| `maxVisiblePages` | `number` | `7` | Maximum number of page buttons to show |
| `showFirstLast` | `boolean` | `false` | Show first/last page buttons |
| `showPageNumbers` | `boolean` | `true` | Show individual page number buttons |
| `showInfo` | `boolean` | `false` | Show "Showing X-Y of Z" info text |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Button and text size |
| `disabled` | `boolean` | `false` | Disable all pagination controls |
| `className` | `string` | — | Additional CSS classes |

## Type Exports

| Type | Description |
|------|-------------|
| `PaginationProps` | Props for Pagination component |
| `PaginationSize` | `'sm' \| 'md' \| 'lg'` |

---

# rn-popover
URL: /docs/native/components/popover

Floating content panel with arrow, placement options, and multiple visual variants.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-popover
```

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

## Usage

```tsx
import { Popover } from '@/components/docyrus-native/popover';

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `visible` | `boolean` | — | Controlled open state |
| `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled) |
| `onOpenChange` | `(open: boolean) => void` | — | Open state change callback |
| `onClose` | `() => void` | — | Called when popover closes |
| `title` | `string` | — | Popover title text |
| `placement` | `PopoverPlacement` | `'bottom'` | Popover placement relative to trigger |
| `offset` | `number` | `10` | Distance from trigger in pixels |
| `arrow` | `boolean` | `true` | Show directional arrow |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Popover size |
| `variant` | `'default' \| 'elevated' \| 'minimal' \| 'glass'` | `'default'` | Visual variant |
| `delayHide` | `number` | `0` | Auto-hide delay in ms (0 = manual close) |
| `maxWidth` | `number` | — | Maximum popover width |
| `children` | `ReactNode` | — | Trigger element |
| `content` | `ReactNode` | — | Popover content (string or element) |
| `className` | `string` | — | Popover container CSS classes |
| `contentClassName` | `string` | — | Content area CSS classes |

### PopoverPlacement

`'top' | 'bottom' | 'left' | 'right' | 'topLeft' | 'topRight' | 'bottomLeft' | 'bottomRight'`

## Type Exports

| Type | Description |
|------|-------------|
| `PopoverProps` | Props for Popover component |
| `PopoverPlacement` | Placement position union type |
| `PopoverSize` | `'sm' \| 'md' \| 'lg'` |
| `PopoverVariant` | `'default' \| 'elevated' \| 'minimal' \| 'glass'` |

---

# rn-pressable-feedback
URL: /docs/native/components/pressable-feedback

Animated press feedback wrapper with scale and highlight effects.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-pressable-feedback
```

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

## Usage

```tsx
import { PressableFeedback } from '@/components/docyrus-native/pressable-feedback';

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode` | — | Content to wrap |
| `feedbackVariant` | `'scale' \| 'scale-highlight' \| 'none'` | `'scale-highlight'` | Type of press feedback |
| `scaleValue` | `number` | `0.97` | Scale factor on press |
| `highlightOpacity` | `number` | `0.7` | Opacity on press (scale-highlight only) |
| `disabled` | `boolean` | `false` | Disable interactions |
| `className` | `string` | — | Additional classes |

All `PressableProps` are also accepted.

## Type Exports

| Type | Description |
|------|-------------|
| `PressableFeedbackProps` | Props for PressableFeedback |
| `FeedbackVariant` | `'scale' \| 'scale-highlight' \| 'none'` |

---

# rn-progress
URL: /docs/native/components/progress

Linear progress bar with label, size, and color variant options.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-progress
```

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

## Usage

```tsx
import { Progress } from '@/components/docyrus-native/progress';

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `number` | — | Progress value (0-100) |
| `showLabel` | `boolean` | `false` | Show percentage label |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Track height size |
| `variant` | `'default' \| 'secondary' \| 'success' \| 'warning' \| 'destructive'` | `'default'` | Fill color variant |
| `className` | `string` | — | Additional CSS classes |
| `labelClassName` | `string` | — | Label text CSS classes |
| `trackClassName` | `string` | — | Track background CSS classes |
| `fillClassName` | `string` | — | Fill bar CSS classes |

## Type Exports

| Type | Description |
|------|-------------|
| `ProgressProps` | Props for Progress component |
| `ProgressSize` | `'xs' \| 'sm' \| 'md' \| 'lg'` |
| `ProgressVariant` | `'default' \| 'secondary' \| 'success' \| 'warning' \| 'destructive'` |

---

# rn-radio-group
URL: /docs/native/components/radio-group

Radio button group component with compound pattern for single-option selection.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-radio-group
```

## Usage

```tsx
import { RadioGroup, RadioGroupItem } from '@/components/docyrus-native/radio-group';

```

## API Reference

### RadioGroup

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `string` | — | Selected value |
| `onValueChange` | `(value: string) => void` | — | Selection change handler |
| `disabled` | `boolean` | `false` | Disable all items |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Radio size |
| `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Layout direction |
| `className` | `string` | — | Additional CSS classes |
| `children` | `ReactNode` | — | RadioGroupItem elements |

### RadioGroupItem

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `string` | — | Item value (required) |
| `label` | `string` | — | Label text |
| `disabled` | `boolean` | `false` | Disable this item |
| `className` | `string` | — | Additional CSS classes |
| `labelClassName` | `string` | — | Label CSS classes |

## Components

| Component | Description |
|-----------|-------------|
| `RadioGroup` | Root container with context provider |
| `RadioGroupItem` | Individual radio button |

## Type Exports

| Type | Description |
|------|-------------|
| `RadioGroupProps` | Props for RadioGroup |
| `RadioGroupItemProps` | Props for RadioGroupItem |
| `RadioGroupSize` | `'sm' \| 'md' \| 'lg'` |
| `RadioGroupOrientation` | `'vertical' \| 'horizontal'` |

---

# rn-scroll-shadow
URL: /docs/native/components/scroll-shadow

ScrollView wrapper with animated gradient shadows indicating scrollable content.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-scroll-shadow
```

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

## Usage

```tsx
import { ScrollShadow } from '@/components/docyrus-native/scroll-shadow';

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode` | — | Scrollable content |
| `orientation` | `'horizontal' \| 'vertical'` | `'vertical'` | Scroll direction |
| `shadowSize` | `number` | `40` | Shadow gradient size in px |
| `className` | `string` | — | Additional classes |

All `ScrollViewProps` are also accepted.

## Type Exports

| Type | Description |
|------|-------------|
| `ScrollShadowProps` | Props for ScrollShadow |
| `ScrollShadowOrientation` | `'horizontal' \| 'vertical'` |

---

# rn-select
URL: /docs/native/components/select

Dropdown select component with modal picker for option selection.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-select
```

## Usage

```tsx
import { Select } from '@/components/docyrus-native/select';

const options = [
  { label: 'Apple', value: 'apple' },
  { label: 'Banana', value: 'banana' },
  { label: 'Cherry', value: 'cherry' },
];

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `options` | `SelectOption[]` | — | Array of options (required) |
| `value` | `string` | — | Selected option value |
| `onValueChange` | `(value: string) => void` | — | Selection change handler |
| `placeholder` | `string` | `'Select...'` | Placeholder text |
| `disabled` | `boolean` | `false` | Disable interaction |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Trigger size |
| `title` | `string` | — | Modal header title |
| `className` | `string` | — | Trigger CSS classes |
| `textClassName` | `string` | — | Trigger text CSS classes |
| `accessibilityLabel` | `string` | — | Accessibility label |

### SelectOption

| Property | Type | Description |
|----------|------|-------------|
| `label` | `string` | Display text |
| `value` | `string` | Option value |
| `disabled` | `boolean` | Disable this option |

## Type Exports

| Type | Description |
|------|-------------|
| `SelectProps` | Props for Select component |
| `SelectOption` | Option item type |
| `SelectSize` | `'sm' \| 'md' \| 'lg'` |

---

# rn-separator
URL: /docs/native/components/separator

Visual divider component for horizontal or vertical separation.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-separator
```

## Usage

```tsx
import { Separator } from '@/components/docyrus-native/separator';

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Separator direction |
| `color` | `string` | theme `border` | Custom color |
| `thickness` | `number` | `1` | Line thickness |
| `className` | `string` | — | Additional CSS classes |

## Type Exports

| Type | Description |
|------|-------------|
| `SeparatorProps` | Props for Separator component |
| `SeparatorOrientation` | `'horizontal' \| 'vertical'` |

---

# rn-skeleton
URL: /docs/native/components/skeleton

Animated loading placeholders with card, list, table, and calendar presets.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-skeleton
```

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

## Usage

```tsx
import {
  SkeletonBase, SkeletonCard, SkeletonList,
  SkeletonTable, SkeletonCalendar
} from '@/components/docyrus-native/skeleton';

```

## API Reference

### SkeletonBase

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `width` | `number \| string \| 'auto'` | `'100%'` | Element width (number for px, string for %) |
| `height` | `number \| string \| 'auto'` | — | Element height (falls back to size preset) |
| `variant` | `'default' \| 'light' \| 'dark'` | `'default'` | Background color variant |
| `rounded` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` | `'md'` | Border radius preset |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Height preset when height is not set |
| `animated` | `boolean` | `true` | Enable pulse animation |
| `className` | `string` | — | Additional CSS classes |

### SkeletonCard

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `showImage` | `boolean` | `true` | Show image placeholder |
| `imageHeight` | `number` | `160` | Image placeholder height |
| `lines` | `number` | `3` | Number of text line placeholders |
| `variant` | `'default' \| 'light' \| 'dark'` | `'default'` | Color variant |
| `className` | `string` | — | Additional CSS classes |

### SkeletonList

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `items` | `number` | `5` | Number of list items |
| `showAvatar` | `boolean` | `true` | Show avatar circle placeholder |
| `showSubtitle` | `boolean` | `false` | Show subtitle line |
| `showAction` | `boolean` | `false` | Show action button placeholder |
| `variant` | `'default' \| 'light' \| 'dark'` | `'default'` | Color variant |
| `className` | `string` | — | Additional CSS classes |

### SkeletonTable

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `rows` | `number` | `5` | Number of table rows |
| `columns` | `number` | `4` | Number of table columns |
| `showHeader` | `boolean` | `true` | Show header row |
| `variant` | `'default' \| 'light' \| 'dark'` | `'default'` | Color variant |
| `className` | `string` | — | Additional CSS classes |

### SkeletonCalendar

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `events` | `number` | `3` | Number of event placeholders |
| `variant` | `'default' \| 'light' \| 'dark'` | `'default'` | Color variant |
| `className` | `string` | — | Additional CSS classes |

## Components

| Component | Description |
|-----------|-------------|
| `SkeletonBase` | Base animated skeleton element |
| `SkeletonCard` | Card loading placeholder with image and text lines |
| `SkeletonList` | List loading placeholder with avatar and text |
| `SkeletonTable` | Table loading placeholder with header and rows |
| `SkeletonCalendar` | Calendar loading placeholder with grid and events |

## Type Exports

| Type | Description |
|------|-------------|
| `SkeletonBaseProps` | Props for SkeletonBase |
| `SkeletonCardProps` | Props for SkeletonCard |
| `SkeletonListProps` | Props for SkeletonList |
| `SkeletonTableProps` | Props for SkeletonTable |
| `SkeletonCalendarProps` | Props for SkeletonCalendar |
| `SkeletonVariant` | `'default' \| 'light' \| 'dark'` |
| `SkeletonRounded` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` |
| `SkeletonSize` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` |

---

# rn-slider
URL: /docs/native/components/slider

Draggable slider with custom range, step, tooltip, and track marks.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-slider
```

**Dependencies:**
- [react-native-gesture-handler](https://www.npmjs.com/package/react-native-gesture-handler)
- [react-native-reanimated](https://www.npmjs.com/package/react-native-reanimated)
- [react-native-worklets](https://www.npmjs.com/package/react-native-worklets)

## Usage

```tsx
import { Slider } from '@/components/docyrus-native/slider';

<Slider value={50} onValueChange={(v) => setValue(v)} />

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `number` | `0` | Current slider value |
| `min` | `number` | `0` | Minimum value |
| `max` | `number` | `100` | Maximum value |
| `step` | `number` | `1` | Step increment |
| `disabled` | `boolean` | `false` | Disabled state |
| `showTooltip` | `boolean` | `false` | Show value tooltip while dragging |
| `marks` | `boolean` | `false` | Show track marks |
| `markInterval` | `number` | `25` | Interval between marks |
| `formatTooltip` | `(value: number) => string` | — | Custom tooltip formatter |
| `onValueChange` | `(value: number) => void` | — | Value change handler (while dragging) |
| `onSlidingComplete` | `(value: number) => void` | — | Handler called when sliding ends |
| `trackHeight` | `number` | `4` | Track height in pixels |
| `thumbSize` | `number` | `20` | Thumb diameter in pixels |
| `tintColor` | `string` | — | Custom fill color (overrides theme primary) |
| `className` | `string` | — | Additional CSS classes |

## Type Exports

| Type | Description |
|------|-------------|
| `SliderProps` | Props for Slider component |

---

# rn-spinner
URL: /docs/native/components/spinner

Loading indicator component with size and variant options.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-spinner
```

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

## Usage

```tsx
import { Spinner } from '@/components/docyrus-native/spinner';

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Spinner size |
| `variant` | `'default' \| 'primary' \| 'secondary' \| 'destructive'` | `'default'` | Color variant |
| `color` | `string` | — | Custom color (overrides variant) |
| `speed` | `number` | `800` | Rotation speed in ms |
| `children` | `ReactNode` | — | Custom spinner icon (replaces default SVG arc) |
| `className` | `string` | — | Additional CSS classes |

## Type Exports

| Type | Description |
|------|-------------|
| `SpinnerProps` | Props for Spinner component |
| `SpinnerSize` | `'sm' \| 'md' \| 'lg'` |
| `SpinnerVariant` | `'default' \| 'primary' \| 'secondary' \| 'destructive'` |

---

# rn-switch
URL: /docs/native/components/switch

Toggle switch component with optional label and size variants.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-switch
```

## Usage

```tsx
import { Switch } from '@/components/docyrus-native/switch';

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `checked` | `boolean` | `false` | Switch state |
| `onCheckedChange` | `(value: boolean) => void` | — | State change handler |
| `disabled` | `boolean` | `false` | Disable interaction |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Switch size |
| `label` | `string` | — | Optional label text |
| `className` | `string` | — | Additional CSS classes |
| `labelClassName` | `string` | — | Label CSS classes |
| `accessibilityLabel` | `string` | — | Accessibility label |

## Type Exports

| Type | Description |
|------|-------------|
| `SwitchProps` | Props for Switch component |
| `SwitchSize` | `'sm' \| 'md' \| 'lg'` |

---

# rn-table
URL: /docs/native/components/table

Lightweight data table with sorting, striped rows, grouping, and built-in pagination.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-table
```

## Usage

```tsx
import { Table } from '@/components/docyrus-native/table';

type Product = { id: string; name: string; price: number };

const data: Product[] = [
  { id: '1', name: 'Widget', price: 9.99 },
  { id: '2', name: 'Gadget', price: 19.99 },
];

<Table
  data={data}
  columns={[
    { key: 'name', title: 'Name', sortable: true },
    { key: 'price', title: 'Price', align: 'right' },
  ]}
  keyExtractor={(item) => item.id}
/>
```

### Striped & Bordered

```tsx
<Table data={data} columns={columns} keyExtractor={(item) => item.id} striped bordered />
```

### With Sorting

```tsx
const [sortKey, setSortKey] = useState<string | undefined>();
const [sortDir, setSortDir] = useState<'asc' | 'desc' | null>(null);

<Table
  data={data}
  columns={columns}
  keyExtractor={(item) => item.id}
  sortKey={sortKey}
  sortDirection={sortDir ?? undefined}
  onSort={(key, dir) => { setSortKey(key); setSortDir(dir); }}
/>
```

### With Pagination

```tsx
<Table
  data={data}
  columns={columns}
  keyExtractor={(item) => item.id}
  currentPage={page}
  totalPages={5}
  totalItems={50}
  pageSize={10}
  onPageChange={setPage}
/>
```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `T[]` | — | Array of data items to display |
| `columns` | `TableColumn<T>[]` | — | Column definitions |
| `keyExtractor` | `(item: T) => string` | — | Function to extract unique key per row |
| `sortKey` | `string` | — | Currently sorted column key |
| `sortDirection` | `'asc' \| 'desc'` | — | Current sort direction |
| `onSort` | `(key: string, direction: 'asc' \| 'desc' \| null) => void` | — | Sort change callback |
| `striped` | `boolean` | `false` | Alternate row background colors |
| `bordered` | `boolean` | `false` | Show column border lines |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Table cell padding and font size |
| `groupBy` | `string` | — | Data key to group rows by |
| `groupHeaderRender` | `(groupKey: string, items: T[]) => ReactNode` | — | Custom group header renderer |
| `emptyMessage` | `string` | `'No data available'` | Message when data is empty |
| `loading` | `boolean` | `false` | Show loading state |
| `currentPage` | `number` | — | Current page for pagination |
| `totalPages` | `number` | — | Total pages for pagination |
| `totalItems` | `number` | — | Total item count for pagination info |
| `pageSize` | `number` | — | Items per page for pagination info |
| `onPageChange` | `(page: number) => void` | — | Page change callback |
| `className` | `string` | — | Additional CSS classes |

### TableColumn\<T\>

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `key` | `string` | — | Data field key |
| `title` | `string` | — | Column header text |
| `width` | `number` | `120` | Column width in pixels |
| `sortable` | `boolean` | `false` | Whether column is sortable |
| `align` | `'left' \| 'center' \| 'right'` | `'left'` | Text alignment |
| `render` | `(value: unknown, item: T, index: number) => ReactNode` | — | Custom cell renderer |

## Type Exports

| Type | Description |
|------|-------------|
| `TableProps<T>` | Props for Table component |
| `TableColumn<T>` | Column definition type |
| `TableSize` | `'sm' \| 'md' \| 'lg'` |

---

# rn-tabs
URL: /docs/native/components/tabs

Tabbed navigation with animated sliding indicator, horizontal/vertical orientation, and multiple visual variants.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-tabs
```

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

## Usage

```tsx
import {
  TabsRoot,
  TabsList,
  TabsTrigger,
  TabsContent
} from '@/components/docyrus-native/tabs';

    
  
  
  

```

## API Reference

### TabsRoot

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `string` | — | Controlled active tab value |
| `defaultValue` | `string` | — | Initial active tab value |
| `onValueChange` | `(value: string) => void` | — | Callback when active tab changes |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Tab layout orientation |
| `variant` | `'default' \| 'pills' \| 'underline'` | `'default'` | Visual style variant |
| `children` | `ReactNode` | — | TabsList and TabsContent children |
| `className` | `string` | — | Additional CSS classes |
| `accessibilityLabel` | `string` | `'Tabs'` | Accessibility label for the tab list |

### TabsList

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `scrollable` | `boolean` | `false` | Wrap triggers in a horizontal/vertical ScrollView |
| `children` | `ReactNode` | — | TabsTrigger children |
| `className` | `string` | — | List container CSS classes |

### TabsTrigger

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `string` | — | Unique tab identifier (must match TabsContent value) |
| `disabled` | `boolean` | `false` | Whether the trigger is disabled |
| `textClassName` | `string` | — | Text CSS classes |
| `children` | `ReactNode` | — | Trigger label |
| `className` | `string` | — | Trigger CSS classes |

### TabsContent

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `string` | — | Tab identifier (must match TabsTrigger value) |
| `children` | `ReactNode` | — | Content to render when tab is active |
| `className` | `string` | — | Content area CSS classes |

## Components

| Component | Description |
|-----------|-------------|
| `TabsRoot` | Root container managing active tab state and context |
| `TabsList` | Container for tab triggers with animated sliding indicator (Reanimated spring) |
| `TabsTrigger` | Pressable tab button with layout measurement for indicator positioning |
| `TabsContent` | Content panel with Reanimated fade-in/fade-out transitions |

## Type Exports

| Type | Description |
|------|-------------|
| `TabsRootProps` | Props for TabsRoot component |
| `TabsListProps` | Props for TabsList component |
| `TabsTriggerProps` | Props for TabsTrigger component |
| `TabsContentProps` | Props for TabsContent component |
| `TabsOrientation` | `'horizontal' \| 'vertical'` |
| `TabsVariant` | `'default' \| 'pills' \| 'underline'` |

---

# rn-textarea
URL: /docs/native/components/textarea

Multi-line text input component with size variants and validation.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-textarea
```

## Usage

```tsx
import { Textarea } from '@/components/docyrus-native/textarea';

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Input size |
| `disabled` | `boolean` | `false` | Disable interaction |
| `invalid` | `boolean` | `false` | Show invalid state |
| `rows` | `number` | `3` | Minimum visible rows |
| `className` | `string` | — | Additional CSS classes |
| `inputClassName` | `string` | — | TextInput CSS classes |

All standard `TextInputProps` are also supported (except `style` and `multiline`).

## Type Exports

| Type | Description |
|------|-------------|
| `TextareaProps` | Props for Textarea component |
| `TextareaSize` | `'sm' \| 'md' \| 'lg'` |

---

# rn-toast
URL: /docs/native/components/toast

Stackable toast notification system with rich colors, swipe-to-dismiss, and a Sonner-like imperative API.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-toast
```

**Dependencies:**
- [react-native-gesture-handler](https://www.npmjs.com/package/react-native-gesture-handler)
- [react-native-reanimated](https://www.npmjs.com/package/react-native-reanimated)
- [react-native-worklets](https://www.npmjs.com/package/react-native-worklets)

## Usage

Wrap your app with `
  );
}

// Fire toasts from anywhere
toast.success('Changes saved');
toast.error('Upload failed');
toast.warning('Disk almost full');
toast.info('New update available');
toast.loading('Processing...');
```

## Toaster Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode` | — | App content to wrap |
| `position` | `ToastPosition` | `'bottom-center'` | Default position for toasts |
| `duration` | `number` | `4000` | Auto-dismiss duration in ms |
| `gap` | `number` | `1` | Gap between stacked toasts |
| `visibleToasts` | `number` | `3` | Maximum visible toast count |
| `swipeDirection` | `'up' \| 'down' \| 'left' \| 'right'` | `'up'` | Swipe direction to dismiss |
| `richColors` | `boolean` | `true` | Use colored backgrounds per variant |
| `closeButton` | `boolean` | `false` | Show close button on all toasts |
| `swipeThreshold` | `number` | `100` | Swipe distance to trigger dismiss |
| `titleMaxLines` | `number` | `2` | Maximum title text lines |
| `descMaxLines` | `number` | `3` | Maximum description text lines |
| `variantColors` | `Partial<Record<ToastType, Partial<ToastVariantColors>>>` | — | Override default variant colors |

## ToastData Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `id` | `string \| number` | — | Unique toast identifier (auto-generated) |
| `type` | `'success' \| 'error' \| 'info' \| 'warning' \| 'default' \| 'loading'` | `'default'` | Toast variant type |
| `title` | `ReactNode` | — | Toast title content |
| `description` | `ReactNode` | — | Toast description content |
| `duration` | `number` | `4000` | Auto-dismiss duration in ms |
| `action` | `ToastAction` | — | Action button with label and onClick |
| `icon` | `ReactNode` | — | Custom icon element |
| `closeButton` | `boolean` | `false` | Show close button |
| `important` | `boolean` | — | Prevent auto-dismiss |
| `onDismiss` | `(toast: ToastData) => void` | — | Called when toast is dismissed |
| `onAutoClose` | `(toast: ToastData) => void` | — | Called when toast auto-closes |
| `dismissible` | `boolean` | `true` | Allow swipe-to-dismiss |
| `position` | `ToastPosition` | — | Override default position for this toast |
| `className` | `string` | — | Toast container CSS classes |
| `titleLines` | `number` | — | Override title max lines |
| `descLines` | `number` | — | Override description max lines |
| `colors` | `Partial<ToastVariantColors>` | — | Override variant colors for this toast |

## Type Exports

| Type | Description |
|------|-------------|
| `ToasterProps` | Props for Toaster provider component |
| `ToastData` | Individual toast data object |
| `ToastType` | `'success' \| 'error' \| 'info' \| 'warning' \| 'default' \| 'loading'` |
| `ToastPosition` | `'top-center' \| 'bottom-center' \| 'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right'` |
| `ToastAction` | `{ label: string; onClick: () => void }` |
| `ToastVariantColors` | `{ bg: string; fg: string; icon?: string; border?: string }` |

---

# rn-toggle-group
URL: /docs/native/components/toggle-group

Segmented control component for single or multiple option selection.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-toggle-group
```

## Usage

```tsx
import { ToggleGroup, ToggleGroupItem } from '@/components/docyrus-native/toggle-group';

  
  

```

## API Reference

### ToggleGroup

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `type` | `'single' \| 'multiple'` | `'single'` | Selection mode |
| `value` | `string \| string[]` | — | Selected value(s) |
| `onValueChange` | `(value: string \| string[]) => void` | — | Value change handler |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Item size |
| `variant` | `'default' \| 'outline'` | `'default'` | Visual variant |
| `disabled` | `boolean` | `false` | Disable all items |
| `children` | `ReactNode` | — | ToggleGroupItem elements |
| `className` | `string` | — | Additional CSS classes |

### ToggleGroupItem

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `string` | — | Item value (required) |
| `children` | `ReactNode` | — | Item content |
| `disabled` | `boolean` | `false` | Disable this item |
| `className` | `string` | — | Item CSS classes |
| `textClassName` | `string` | — | Text CSS classes |

## Components

| Component | Description |
|-----------|-------------|
| `ToggleGroup` | Root container with context provider |
| `ToggleGroupItem` | Individual toggle item |

## Type Exports

| Type | Description |
|------|-------------|
| `ToggleGroupProps` | Props for ToggleGroup |
| `ToggleGroupItemProps` | Props for ToggleGroupItem |
| `ToggleGroupType` | `'single' \| 'multiple'` |
| `ToggleGroupSize` | `'sm' \| 'md' \| 'lg'` |
| `ToggleGroupVariant` | `'default' \| 'outline'` |

---

# rn-toggle
URL: /docs/native/components/toggle

Toggle button component with pressed state and variant options.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-toggle
```

## Usage

```tsx
import { Toggle } from '@/components/docyrus-native/toggle';

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `pressed` | `boolean` | `false` | Toggle pressed state |
| `onPressedChange` | `(pressed: boolean) => void` | — | State change handler |
| `children` | `ReactNode` | — | Toggle content |
| `variant` | `'default' \| 'outline'` | `'default'` | Visual style variant |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Toggle size |
| `disabled` | `boolean` | `false` | Disable interaction |
| `className` | `string` | — | Additional CSS classes |
| `textClassName` | `string` | — | Text CSS classes |
| `accessibilityLabel` | `string` | — | Accessibility label |

## Type Exports

| Type | Description |
|------|-------------|
| `ToggleProps` | Props for Toggle component |
| `ToggleVariant` | `'default' \| 'outline'` |
| `ToggleSize` | `'sm' \| 'md' \| 'lg'` |

---

# rn-tooltip
URL: /docs/native/components/tooltip

Contextual popup with configurable placement, arrow, and visual variants.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-tooltip
```

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

## Usage

```tsx
import { Tooltip } from '@/components/docyrus-native/tooltip';

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `visible` | `boolean` | — | Controlled visibility state |
| `defaultOpen` | `boolean` | `false` | Whether the tooltip is initially open |
| `onOpenChange` | `(open: boolean) => void` | — | Callback when visibility changes |
| `onClose` | `() => void` | — | Callback when tooltip closes |
| `text` | `string` | — | Tooltip text content (required) |
| `placement` | `'top' \| 'bottom' \| 'left' \| 'right' \| 'topLeft' \| 'topRight' \| 'bottomLeft' \| 'bottomRight'` | `'bottom'` | Tooltip position relative to the trigger |
| `offset` | `number` | `8` | Distance from the trigger element in pixels |
| `arrow` | `boolean` | `true` | Show directional arrow |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Tooltip padding and font size |
| `variant` | `'default' \| 'dark' \| 'light'` | `'default'` | Visual style variant |
| `delayHide` | `number` | `0` | Auto-hide delay in milliseconds (0 = manual close only) |
| `maxWidth` | `number` | — | Maximum tooltip width |
| `children` | `ReactNode` | — | Trigger element |
| `className` | `string` | — | Tooltip bubble CSS classes |
| `contentClassName` | `string` | — | Inner content container CSS classes |
| `textClassName` | `string` | — | Tooltip text CSS classes |

## Type Exports

| Type | Description |
|------|-------------|
| `TooltipProps` | Props for Tooltip component |
| `TooltipPlacement` | `'top' \| 'bottom' \| 'left' \| 'right' \| 'topLeft' \| 'topRight' \| 'bottomLeft' \| 'bottomRight'` |
| `TooltipSize` | `'sm' \| 'md' \| 'lg'` |
| `TooltipVariant` | `'default' \| 'dark' \| 'light'` |

---

# rn-adaptive-card
URL: /docs/native/docyrus/adaptive-card

Render Microsoft Adaptive Cards JSON natively — elements, inputs, actions, charts, and templating.

`AdaptiveCard` renders an [Adaptive Cards](https://adaptivecards.io) JSON document with native React Native primitives — no WebView. It is a 1:1 native port of the web `@docyrus/ui` Adaptive Card renderer and supports the same payloads produced by the Docyrus Adaptive Card Designer: every element, input, action, the chart family, templating (`${...}`, `$data`, `$when`), `requires`/`fallback`, and host-config overrides.

## Installation

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

**Dependencies:**
- [react-native-svg](https://www.npmjs.com/package/react-native-svg)
- [@react-native-community/datetimepicker (optional)](https://www.npmjs.com/package/@react-native-community/datetimepicker)

`react-native-svg` powers the chart family, the progress ring, and CDN icons. `@react-native-community/datetimepicker` is optional — when absent, `Input.Date` / `Input.Time` fall back to a plain text field.

## Usage

```tsx
import { AdaptiveCard } from '@/components/docyrus-native/adaptive-card';

const payload = {
  type: 'AdaptiveCard',
  version: '1.5',
  body: [
    { type: 'TextBlock', text: 'Hello **world**', size: 'large', weight: 'bolder', wrap: true },
    { type: 'Input.Text', id: 'name', label: 'Name', isRequired: true },
  ],
  actions: [{ type: 'Action.Submit', title: 'Send', style: 'positive' }],
};

      
    </>
  );
}
```

### Filtered Input.ChoiceSet (Data.Query)

A `style: 'filtered'` ChoiceSet that declares `choices.data` calls `onChoiceQuery` with the dataset + debounced search text; return the matching choices:

```tsx
<AdaptiveCard
  payload={payload}
  onChoiceQuery={async ({ dataset, search }) => {
    const rows = await client.get(`/lookup/${dataset}?q=${search}`);
    return rows.map(r => ({ title: r.label, value: r.id }));
  }}
/>
```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `payload` | `AdaptiveCardPayload` | — | The Adaptive Card JSON document to render. Required. |
| `data` | `unknown` | — | Data context for template expansion (`${path}`, `$data`, `$when`, built-in functions). When provided, the payload is expanded against it before rendering. |
| `onAction` | `(event: AdaptiveCardActionEvent) => void \| Promise<void>` | — | Fires for every action: submit, execute, openUrl, toggleVisibility, showCard, resetInputs. |
| `hostConfig` | `AdaptiveCardHostConfigOverride` | — | Deep-partial overrides for spacing, actions orientation/limits, etc. Merged over `defaultHostConfig`. |
| `customElements` | `Record<string, ElementRenderer>` | — | Custom renderers keyed by element `type`. Takes precedence over the built-ins — use it to override `Media`, `Component`, or any element. |
| `onChoiceQuery` | `(request: { dataset, search, inputId }) => Promise<AdaptiveCardChoice[]>` | — | Async resolver for a filtered `Input.ChoiceSet` declaring `choices.data` (`Data.Query`). |
| `className` | `string` | — | Extra classes for the card surface. |

## Supported elements

| Group | Types |
|-------|-------|
| Text & media | `TextBlock`, `RichTextBlock`, `Image`, `ImageSet`, `Media` |
| Containers | `Container`, `ColumnSet` / `Column`, `FactSet`, `Table`, `ActionSet` |
| Inputs | `Input.Text`, `Input.Number`, `Input.Date`, `Input.Time`, `Input.Toggle`, `Input.ChoiceSet`, `Input.Rating` |
| Display (1.6) | `Badge`, `CodeBlock`, `CompoundButton`, `Icon`, `ProgressBar`, `ProgressRing`, `Rating` |
| Layout (1.6) | `Carousel`, `Accordion`, `TabSet` |
| Charts (1.6) | `Chart.VerticalBar`, `Chart.HorizontalBar`, `Chart.Pie`, `Chart.Donut`, `Chart.Line`, `Chart.Gauge` |
| Extensibility | `Component`, `LoopComponent` (placeholders) |

## Supported actions

| Type | Behavior |
|------|----------|
| `Action.Submit` | Validates inputs, then fires `onAction` with the collected input map merged with `data`. |
| `Action.Execute` | Same as submit plus `verb`. |
| `Action.OpenUrl` | Opens the URL via `Linking` and fires `onAction`. |
| `Action.ShowCard` | Toggles an inline nested card below the action row. |
| `Action.ToggleVisibility` | Shows/hides target elements by id. |
| `Action.ResetInputs` | Clears the named inputs (or all in scope). |

`selectAction` is supported on `Container`, `Column`, `ColumnSet`, `Image`, `Icon`, `TableCell`, `CompoundButton`, and the card root.

## Action dispatch

Every action emits a typed event through `onAction` (`AdaptiveCardActionEvent`, a discriminated union on `type`):

| 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 opens the URL via `Linking`) |
| `'toggleVisibility'` | `action`, `card` | `Action.ToggleVisibility` |
| `'showCard'` | `isOpen`, `action`, `card` | `Action.ShowCard` (fires on open and close) |
| `'resetInputs'` | `action`, `card` | `Action.ResetInputs` |

`data` follows the spec's `associatedInputs` contract: `'auto'` (default) collects every **visible** input in scope; `'none'` ships only `action.data`. `${input.<id>}` placeholders inside `action.data` are substituted with the current input values.

## Helpers

All exported from `@/components/docyrus-native/adaptive-card`:

| Export | Use |
|--------|-----|
| `useAdaptiveCard(payload, options)` | Headless hook — state, validation, action dispatch. Returns `{ cardProps, controls, state }`. |
| `AdaptiveCardView` | Renders from a `cardProps` produced by the hook. |
| `registerElement(type, renderer)` | Register a **global** custom element renderer (vs. the per-instance `customElements` prop). |
| `expandTemplate(payload, data)` | Stand-alone templating expander (`${}`, `$data`, `$when`). |
| `evaluateExpression(expr, scope)` / `registerExpressionFunction(name, fn)` | Evaluate / extend the expression language. |
| `validateInput` / `validateInputs` / `collectInputs` / `buildSubmitData` | Input validation + submit-payload helpers. |
| `defaultHostConfig` / `mergeHostConfig` | Host config base + deep-merge. |
| `parseAdaptiveCard` / `isAdaptiveCard` | Payload guards. |

## Native notes

- **Charts** render with `react-native-svg` (no tooltips/axis ticks of the web charting lib) — bars are View-based, pie/donut/line/gauge are SVG.
- **`Media`** has no bundled player: it shows the poster (or an audio chip) and opens the source via `Linking` on tap. **`Component`** / **`LoopComponent`** render lossless placeholders. Register a `customElements` override for inline playback.
- **`TextBlock` / `FactSet` markdown** supports the inline subset: bold, italic, strikethrough, inline code, links. Block lists are not formatted.
- **Icons** (`Icon`, `Badge.icon`, accordion/tab headers) map Fluent names to Font Awesome glyphs loaded from the Docyrus icon CDN.

## Type Exports

| Type | Description |
|------|-------------|
| `AdaptiveCardPayload` | The card document (`type`, `version`, `body`, `actions`, …). |
| `AdaptiveCardProps` | Props for the `AdaptiveCard` component. |
| `AdaptiveCardElement` | Union of all supported element shapes. |
| `AdaptiveCardAction` / `AdaptiveCardSelectAction` | Action unions. |
| `AdaptiveCardActionEvent` | The `onAction` event union. |
| `AdaptiveCardHostConfig` / `AdaptiveCardHostConfigOverride` | Host config + deep-partial override. |
| `AdaptiveCardInput` / `AdaptiveCardInputValue` | Input element union + value type. |
| `ElementRenderer` | Signature for `customElements` entries. |

## Related

- `useAdaptiveCard(payload, options)` — the headless hook powering the component (state, validation, action dispatch).
- `registerElement(type, renderer)` — register a global custom element renderer.
- `expandTemplate(payload, data)` / `evaluateExpression(expr, scope)` — standalone templating helpers.

---

# rn-avatar-select
URL: /docs/native/docyrus/avatar-select

Avatar picker with color palette and emoji tabs, previewing the selected avatar in real time.

## Installation

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

## Usage

```tsx
import { AvatarSelect } from '@/components/docyrus-native/avatar-select';
import type { AvatarFieldValue } from '@/components/docyrus-native/avatar-select';

const [avatar, setAvatar] = useState<AvatarFieldValue>({
  icon: null,
  color: null,
  image: null,
});

```

### Custom Size

```tsx

```

### With Initial Value

```tsx

```

### Disabled

```tsx

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `Partial<AvatarFieldValue> \| null` | — | Current avatar value containing icon, color, and image data. |
| `size` | `number` | `40` | Size of the avatar trigger thumbnail in pixels. |
| `disabled` | `boolean` | `false` | When true, the picker cannot be opened and the trigger is visually dimmed. |
| `onChange` | `(value: AvatarFieldValue) => void` | — | Callback when the avatar value changes (color or emoji selected). |
| `className` | `string` | — | Additional CSS classes |

### AvatarFieldValue

| Property | Type | Description |
|----------|------|-------------|
| `icon` | `string \| null` | Emoji or text icon string. |
| `color` | `string \| null` | Color name resolved by `resolveColorHex`. |
| `image` | `AvatarImageValue \| null` | Image file data with signed URL. |

### AvatarImageValue

| Property | Type | Description |
|----------|------|-------------|
| `id` | `string` | File identifier. |
| `file_name` | `string` | Original file name. |
| `signed_url` | `string \| null` | Signed URL for the image. |
| `file_type` | `string` | MIME type of the file. |
| `file_size` | `number` | File size in bytes. |

## Type Exports

| Type | Description |
|------|-------------|
| `AvatarSelectProps` | Props for the AvatarSelect component. |
| `AvatarFieldValue` | Avatar value shape with icon, color, and image. |
| `AvatarImageValue` | Image file data shape. |
| `AvatarSelectTab` | Picker tab: `'color' \| 'emoji'`. |

---

# rn-avatar-thumbnail
URL: /docs/native/docyrus/avatar-thumbnail

Avatar display component with image, emoji, or icon text fallback and configurable shape.

## Installation

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

## Usage

```tsx
import { AvatarThumbnail } from '@/components/docyrus-native/avatar-thumbnail';

```

### With Image

```tsx

```

### With Emoji

```tsx

```

### Shapes

```tsx

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `size` | `number` | `32` | Width and height of the avatar in pixels. |
| `icon` | `string \| null` | — | Icon content. If the string is an emoji, it is rendered directly. Otherwise, the first character is displayed as uppercase text. |
| `color` | `string \| null` | — | Background color name resolved via `resolveColorHex`. Falls back to `colors.muted` when not provided. |
| `image` | `{ signed_url?: string \| null; file_name?: string } \| null` | — | Image object. When `signed_url` is present, the image is displayed and other fallbacks are skipped. |
| `shape` | `'rounded' \| 'circle' \| 'square'` | `'rounded'` | Controls the border radius of the avatar. |
| `className` | `string` | — | Additional CSS classes |

## Type Exports

| Type | Description |
|------|-------------|
| `AvatarThumbnailProps` | Props for the AvatarThumbnail component. |
| `AvatarThumbnailShape` | Shape variant: `'rounded' \| 'circle' \| 'square'`. |

---

# rn-awesome-card
URL: /docs/native/docyrus/awesome-card

Multi-purpose stat card with collapsible body, compound component pattern for flexible layout.

## Installation

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

## Usage

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

    
  
  
    
  

```

### Collapsible

```tsx

  
  
    
  

```

### Chevron Position

```tsx

  
  
  

```

### Initially Collapsed

```tsx

  
  
  

```

## API Reference

### AwesomeCard

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode` | — | Card content (AwesomeCardHeader, AwesomeCardBody, etc.). |
| `collapsible` | `boolean` | `false` | When true, enables collapse/expand behavior on header press. |
| `collapsed` | `boolean` | `false` | Initial collapsed state (only used when `collapsible` is true). |
| `chevronPosition` | `'left' \| 'right'` | `'left'` | Position of the collapse chevron indicator in the header. |
| `className` | `string` | — | Custom style applied to the outer card container. |

### AwesomeCardHeader

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode` | — | Header content (typically AwesomeCardTitle and AwesomeCardIcon). |
| `className` | `string` | — | Custom style applied to the header container. |

### AwesomeCardTitle

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode` | — | Title content. Strings are rendered as muted text. |
| `className` | `string` | — | Custom style applied to the title container. |

### AwesomeCardIcon

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode` | — | Icon content. Strings are rendered as muted text. |
| `className` | `string` | — | Custom style applied to the icon container. |

### AwesomeCardBody

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode` | — | Body content (typically AwesomeCardValue and AwesomeCardTrend). Hidden when the card is collapsed. |
| `className` | `string` | — | Custom style applied to the body container. |

### AwesomeCardValue

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode` | — | Value content. Strings and numbers are rendered as large bold text with tabular numerals. |
| `className` | `string` | — | Custom style applied to the value container. |

### AwesomeCardTrend

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode` | — | Trend content. Strings are rendered with the appropriate trend color. |
| `positive` | `boolean` | — | When `true`, uses green color. When `false`, uses red. When `undefined`, uses muted color. |
| `className` | `string` | — | Custom style applied to the trend container. |

## Components

| Component | Description |
|-----------|-------------|
| `AwesomeCard` | Root card container with collapsible state management. |
| `AwesomeCardHeader` | Header section, pressable when collapsible is enabled. |
| `AwesomeCardTitle` | Title text within the header. |
| `AwesomeCardIcon` | Icon element within the header. |
| `AwesomeCardBody` | Collapsible body section with card-style background. |
| `AwesomeCardValue` | Large value display for stats or metrics. |
| `AwesomeCardTrend` | Trend indicator with positive/negative color coding. |

## Type Exports

| Type | Description |
|------|-------------|
| `AwesomeCardProps` | Props for the AwesomeCard component. |
| `AwesomeCardHeaderProps` | Props for the AwesomeCardHeader component. |
| `AwesomeCardTitleProps` | Props for the AwesomeCardTitle component. |
| `AwesomeCardIconProps` | Props for the AwesomeCardIcon component. |
| `AwesomeCardBodyProps` | Props for the AwesomeCardBody component. |
| `AwesomeCardValueProps` | Props for the AwesomeCardValue component. |
| `AwesomeCardTrendProps` | Props for the AwesomeCardTrend component. |

---

# rn-awesome-dialog
URL: /docs/native/docyrus/awesome-dialog

Compound modal dialog system with header, body, footer, and toolbar sub-components.

## Installation

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

## Usage

```tsx
import {
  AwesomeDialog,
  AwesomeDialogHeader,
  AwesomeDialogBody,
  AwesomeDialogFooter,
} from '@/components/docyrus-native/awesome-dialog';

  
  
    
  

```

## API Reference

### AwesomeDialogProps

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `open` | `boolean` | - | Controls dialog visibility (controlled mode). Omit for uncontrolled. |
| `onOpenChange` | `(open: boolean) => void` | - | Callback when dialog open state changes |
| `size` | `'sm' \| 'default' \| 'lg' \| 'full'` | `'default'` | Dialog size preset |
| `title` | `string` | - | Title displayed in the default header |
| `children` | `ReactNode` | - | Dialog content (Header, Body, Footer, Toolbar sub-components) |
| `className` | `string` | - | Additional CSS classes |

### Size Presets

| Size | Width | Max Height |
|------|-------|------------|
| `sm` | 75% | 50% |
| `default` | 85% | 70% |
| `lg` | 92% | 85% |
| `full` | 100% | 100% |

### AwesomeDialogHeaderProps

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode` | - | Custom header content. When omitted, renders default title + close button. |
| `className` | `string` | - | Additional styles for the header |

### AwesomeDialogBodyProps

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode` | - | Scrollable body content |
| `className` | `string` | - | Additional styles for the body content container |

### AwesomeDialogFooterProps

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode` | - | Footer content (typically action buttons, right-aligned) |
| `className` | `string` | - | Additional styles for the footer |

### AwesomeDialogToolbarProps

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode` | - | Toolbar content (placed between header and body) |
| `className` | `string` | - | Additional styles for the toolbar |

## Components

| Component | Description |
|-----------|-------------|
| `AwesomeDialog` | Root dialog wrapper with Modal and backdrop |
| `AwesomeDialogHeader` | Header section with title and close button |
| `AwesomeDialogBody` | Scrollable body content area |
| `AwesomeDialogFooter` | Footer with right-aligned action buttons |
| `AwesomeDialogToolbar` | Optional toolbar between header and body |

## Type Exports

| Type | Description |
|------|-------------|
| `AwesomeDialogProps` | Props for AwesomeDialog component |
| `AwesomeDialogSize` | `'sm' \| 'default' \| 'lg' \| 'full'` |
| `AwesomeDialogHeaderProps` | Props for AwesomeDialogHeader |
| `AwesomeDialogBodyProps` | Props for AwesomeDialogBody |
| `AwesomeDialogFooterProps` | Props for AwesomeDialogFooter |
| `AwesomeDialogToolbarProps` | Props for AwesomeDialogToolbar |

---

# rn-awesome-stats
URL: /docs/native/docyrus/awesome-stats

Statistics display component with horizontal scroll or grid layouts, number formatting, and comparison indicators.

## Installation

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

## Usage

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

```

## API Reference

### AwesomeStatsProps

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `items` | `AwesomeStatItem[]` | - | Array of stat items to display |
| `layout` | `AwesomeStatsLayout` | - | Layout configuration (scroll or grid) |
| `className` | `string` | - | Additional CSS classes |

### AwesomeStatsLayout

The layout is a discriminated union with two modes:

**Scroll layout:**

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `type` | `'scroll'` | - | Horizontal scroll mode |
| `cardWidth` | `number` | `160` | Width of each stat card |

**Grid layout:**

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `type` | `'grid'` | - | Grid mode (non-scrollable) |
| `columns` | `number` | `2` | Number of columns |

### AwesomeStatItem

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `id` | `string` | - | Unique identifier |
| `title` | `string` | - | Stat label text |
| `icon` | `ReactNode` | - | Icon element displayed next to the title |
| `value` | `number` | - | Numeric value to display |
| `format` | `AwesomeStatFormat` | - | Number formatting options |
| `comparison` | `AwesomeStatComparison` | - | Comparison with a previous value |
| `color` | `string` | - | Custom color for value text and icon background |

### AwesomeStatFormat

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `style` | `'number' \| 'currency' \| 'percent'` | - | Number format style |
| `currency` | `string` | `'USD'` | Currency code (when style is `'currency'`) |
| `notation` | `'standard' \| 'compact' \| 'scientific' \| 'engineering'` | - | Number notation |
| `minimumFractionDigits` | `number` | - | Minimum fraction digits |
| `maximumFractionDigits` | `number` | - | Maximum fraction digits |

### AwesomeStatComparison

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `previousValue` | `number` | - | Previous period value for comparison |
| `period` | `string` | - | Label for the comparison period (e.g. `'vs last month'`) |
| `positiveDirection` | `'up' \| 'down'` | `'up'` | Which direction is considered positive |

## Type Exports

| Type | Description |
|------|-------------|
| `AwesomeStatsProps` | Props for AwesomeStats component |
| `AwesomeStatItem` | Individual stat item configuration |
| `AwesomeStatFormat` | Number formatting options |
| `AwesomeStatComparison` | Comparison period configuration |
| `AwesomeStatsLayout` | Layout configuration (scroll or grid) |

---

# rn-calendar
URL: /docs/native/docyrus/calendar

Full-featured calendar with month, week, day, and agenda views with event display.

## Installation

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

### Expo Configuration

`react-native-localize` requires plugin configuration in your `app.config.ts`:

```ts
{
  plugins: [
    [
      'react-native-localize',
      { locales: ['en', 'tr'] } // list your supported locales
    ]
  ]
}
```

## Usage

```tsx
import { CalendarView, type CalendarEvent } from '@/components/docyrus-native/calendar';

const events: CalendarEvent[] = [
  {
    id: '1',
    title: 'Team Meeting',
    start: new Date(2026, 2, 4, 10, 0),
    end: new Date(2026, 2, 4, 11, 0),
    color: '#3b82f6',
  },
];

<CalendarView
  events={events}
  onEventPress={(event) => console.log(event.title)}
  onCreateEvent={(date) => console.log('Create event at', date)}
/>
```

### Specific Views

```tsx

```

### Monday Start

```tsx

```

## View Modes

| Mode | Description |
|------|-------------|
| `month` | Monthly calendar grid with event dots. Tap a day to create events. |
| `week` | Weekly time grid with hourly slots and day headers. |
| `day` | Single day time grid with all-day event section. |
| `agenda` | 14-day scrollable agenda with event cards. |

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `events` | `CalendarEvent[]` | `[]` | Array of calendar events |
| `defaultDate` | `Date` | `new Date()` | Initial displayed date |
| `defaultView` | `'month' \| 'week' \| 'day' \| 'agenda'` | `'month'` | Initial view mode |
| `visibleViews` | `CalendarViewMode[]` | `['month', 'week', 'day', 'agenda']` | Which view tabs to show |
| `views` | `CalendarViewMode[]` | — | Deprecated — use `visibleViews` |
| `firstDayOfWeek` | `0 \| 1` | `1` | First day of week (0 = Sunday, 1 = Monday) |
| `onEventPress` | `(event: CalendarEvent) => void` | — | Callback when an event is tapped |
| `onCreateEvent` | `(date: Date) => void` | — | Callback when tapping an empty slot |
| `onDaySelect` | `(date: Date) => void` | — | Callback when any day cell is tapped, independent of event creation |
| `onDateChange` | `(date: Date) => void` | — | Callback when the displayed date changes |
| `onViewChange` | `(view: CalendarViewMode) => void` | — | Callback when the view mode changes |
| `showFab` | `boolean` | `true` | Show floating action button for creating events |
| `hideColorFilter` | `boolean` | `false` | Hide the color filter strip |
| `hideViewTabs` | `boolean` | `false` | Hide the view tabs (month/week/day/agenda) |
| `hideNavigation` | `boolean` | `false` | Hide the date navigation row (arrows + today) |
| `renderEventBadge` | `(event: CalendarEvent, defaultBadge: ReactNode) => ReactNode` | — | Custom render prop for event badges in month view |
| `minDate` | `Date` | — | Minimum navigable date |
| `maxDate` | `Date` | — | Maximum navigable date |
| `className` | `string` | — | Additional CSS classes |

### CalendarEvent

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `id` | `string` | — | Unique event identifier |
| `title` | `string` | — | Event title |
| `start` | `Date` | — | Event start date/time |
| `end` | `Date` | — | Event end date/time |
| `color` | `string` | — | Custom event color (falls back to preset palette) |
| `allDay` | `boolean` | `false` | Whether this is an all-day event |
| `description` | `string` | — | Optional event description |

## Type Exports

| Type | Description |
|------|-------------|
| `CalendarViewProps` | Props for CalendarView component |
| `CalendarEvent` | Event data type |
| `CalendarViewMode` | `'month' \| 'week' \| 'day' \| 'agenda'` |

---

# rn-chart
URL: /docs/native/docyrus/chart

Comprehensive charting library with 13 chart types, VChart adapter, touch interactions, and animations.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-chart
```

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

## Usage

```tsx
import { DocyLineChart } from '@/components/docyrus-native/chart';

const data = {
  categories: ['Jan', 'Feb', 'Mar', 'Apr', 'May'],
  series: [
    { name: 'Revenue', data: [30, 40, 35, 50, 49] },
    { name: 'Expenses', data: [20, 25, 30, 28, 32] }
  ]
};

```

## Chart Types

### Line Chart

```tsx
import { DocyLineChart } from '@/components/docyrus-native/chart';

```

### Bar Chart

```tsx
import { DocyBarChart } from '@/components/docyrus-native/chart';

```

### Pie Chart

```tsx
import { DocyPieChart } from '@/components/docyrus-native/chart';

```

### Area Chart

```tsx
import { DocyAreaChart } from '@/components/docyrus-native/chart';

```

### Scatter Chart

```tsx
import { DocyScatterChart } from '@/components/docyrus-native/chart';

```

### Radar Chart

```tsx
import { DocyRadarChart } from '@/components/docyrus-native/chart';

```

### Gauge Chart

```tsx
import { DocyGaugeChart } from '@/components/docyrus-native/chart';

```

### Funnel Chart

```tsx
import { DocyFunnelChart } from '@/components/docyrus-native/chart';

```

### Heatmap Chart

```tsx
import { DocyHeatmapChart } from '@/components/docyrus-native/chart';

```

### Treemap Chart

```tsx
import { DocyTreemapChart } from '@/components/docyrus-native/chart';

```

### Candlestick Chart

```tsx
import { DocyCandlestickChart } from '@/components/docyrus-native/chart';

```

### Sparkline Chart

```tsx
import { DocySparklineChart } from '@/components/docyrus-native/chart';

```

### Combo Chart (Bar + Line)

```tsx
import { DocyComboChart } from '@/components/docyrus-native/chart';

```

## VChart Adapter

The `DocyVChart` component accepts VChart-compatible spec format and renders the appropriate chart.

```tsx
import { DocyVChart } from '@/components/docyrus-native/chart';

```

## API Reference — Base Props

All chart components share these base props:

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `width` | `number` | screen width | Chart width in pixels |
| `height` | `number` | `300` | Chart height in pixels |
| `title` | `string` | — | Chart title text |
| `description` | `string` | — | Chart description text |
| `loading` | `boolean` | `false` | Show loading state |
| `error` | `string` | — | Error message to display |
| `className` | `string` | — | Additional CSS classes |
| `config` | `ChartConfig` | — | Axis, grid, legend, tooltip configuration |
| `animated` | `boolean` | `false` | Enable entry animations |
| `animationDuration` | `number` | `500` | Animation duration in milliseconds |
| `animationDelay` | `number` | `0` | Animation delay in milliseconds |

## API Reference — Touch Props

Charts with touch support (Line, Area, Combo) accept:

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `showCrosshair` | `boolean` | `false` | Show crosshair line on touch |
| `showTooltip` | `boolean` | `false` | Show tooltip on touch |
| `tooltipComponent` | `(data: TooltipData) => ReactNode` | — | Custom tooltip renderer |
| `onTouch` | `(point: TooltipData \| null) => void` | — | Touch event callback |

## API Reference — Chart Config

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `padding` | `{ top, right, bottom, left }` | `{ 20, 20, 50, 50 }` | Chart SVG internal padding |
| `xAxis` | `ChartAxis` | — | X axis configuration |
| `yAxis` | `ChartAxis` | — | Y axis configuration |
| `grid` | `ChartGrid` | — | Grid line configuration |
| `legend` | `ChartLegend` | — | Legend position and alignment |
| `tooltip` | `ChartTooltip` | — | Tooltip formatting |

## Components

| Component | Description |
|-----------|-------------|
| `DocyLineChart` | Line chart with smooth curves, area fill, crosshair |
| `DocyBarChart` | Vertical/horizontal bar chart with stacking |
| `DocyPieChart` | Pie/donut chart with labels |
| `DocyAreaChart` | Stacked area chart with smooth curves |
| `DocyScatterChart` | Scatter plot with grid |
| `DocyRadarChart` | Radar/spider chart |
| `DocyGaugeChart` | Semicircular gauge with value display |
| `DocyFunnelChart` | Funnel/pyramid chart with labels |
| `DocyHeatmapChart` | Color-encoded matrix chart |
| `DocyTreemapChart` | Proportional rectangle layout |
| `DocyCandlestickChart` | OHLC financial chart with volume |
| `DocySparklineChart` | Inline mini chart (no axes) |
| `DocyComboChart` | Combined bar + line chart |
| `DocyVChart` | VChart spec adapter |

## Core Sub-Components

| Component | Description |
|-----------|-------------|
| `DocyChartAxis` | Axis labels and ticks |
| `DocyChartGrid` | Background grid lines |
| `DocyChartLegend` | Color legend with series names |
| `DocyChartCrosshair` | Touch crosshair overlay |
| `DocyChartTooltip` | Floating data tooltip |

## Hooks

| Hook | Description |
|------|-------------|
| `useChartAnimation` | Returns animated progress value (0 → 1) for chart transitions |
| `useChartTouch` | Pan responder for crosshair and tooltip interactions |

## Type Exports

| Type | Description |
|------|-------------|
| `LineChartProps` | Props for DocyLineChart |
| `BarChartProps` | Props for DocyBarChart |
| `PieChartProps` | Props for DocyPieChart |
| `AreaChartProps` | Props for DocyAreaChart |
| `ScatterChartProps` | Props for DocyScatterChart |
| `RadarChartProps` | Props for DocyRadarChart |
| `GaugeChartProps` | Props for DocyGaugeChart |
| `FunnelChartProps` | Props for DocyFunnelChart |
| `HeatmapChartProps` | Props for DocyHeatmapChart |
| `TreemapChartProps` | Props for DocyTreemapChart |
| `CandlestickChartProps` | Props for DocyCandlestickChart |
| `SparklineChartProps` | Props for DocySparklineChart |
| `ComboChartProps` | Props for DocyComboChart |
| `DocyVChartProps` | Props for DocyVChart adapter |
| `ChartConfig` | Chart configuration object |
| `ChartData` | Generic chart data type |
| `ChartSeries` | Series data definition |
| `TooltipData` | Tooltip callback data |
| `VChartSpec` | VChart-compatible spec type |

---

# rn-checkin
URL: /docs/native/docyrus/checkin

Location-based check-in/check-out system with timer, option selection, and check-out form.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-checkin
```

## Overview

The Check In system is a multi-component feature for location-based check-in/check-out workflows. It consists of:

- **`CheckInProvider`** — Context provider that manages state (session, timer, sheets)
- **`DocyCheckInButton`** — Floating action button that toggles check-in/check-out
- **`DocyCheckInSheet`** — ActionSheet for selecting a check-in location/option
- **`DocyCheckOutSheet`** — ActionSheet with notes/outcome form for completing check-out

The system is **form-library-agnostic** and **geolocation-library-agnostic** — you provide `getLocation` and optionally `requestLocationPermission` callbacks.

## Usage

```tsx
import {
  CheckInProvider,
  DocyCheckInButton,
  DocyCheckInSheet,
  DocyCheckOutSheet
} from '@/components/docyrus-native/checkin';

function App() {
  const getLocation = async () => {
    // Use any geolocation library
    return { latitude: 41.0082, longitude: 28.9784 };
  };

  return (
    
  );
}
```

## API Reference

### CheckInProvider

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode` | — | Child components |
| `getLocation` | `() => Promise<{ latitude: number; longitude: number }>` | — | **Required.** Returns current device location |
| `requestLocationPermission` | `() => Promise<'granted' \| 'denied'>` | — | Request location permission before check-in |
| `defaultOptions` | `CheckInOption[]` | `[]` | Default check-in options if `onCheckIn` is not provided |
| `onCheckIn` | `(location) => Promise<CheckInOption[]>` | — | Called on check-in, returns available options |
| `onCheckOut` | `(data) => Promise<void>` | — | Called on check-out with session data, form data, and end location |

### DocyCheckInButton

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `size` | `'sm' \| 'md' \| 'lg'` | `'sm'` | Button size |
| `bottom` | `number` | `20` | Bottom position offset |
| `top` | `number` | — | Top position offset |
| `left` | `number` | — | Left position offset |
| `right` | `number` | `20` | Right position offset |
| `onCheckInStart` | `() => void` | — | Called when check-in starts |
| `onCheckInComplete` | `() => void` | — | Called when check-in completes |
| `onCheckOutStart` | `() => void` | — | Called when check-out starts |
| `onCheckOutComplete` | `() => void` | — | Called when check-out completes |

### DocyCheckInSheet

No additional props. Uses `CheckInProvider` context internally.

### DocyCheckOutSheet

No additional props. Uses `CheckInProvider` context internally. Displays session info, notes textarea, outcome input, and submit/cancel buttons.

## Components

| Component | Description |
|-----------|-------------|
| `CheckInProvider` | Context provider for check-in state |
| `DocyCheckInButton` | Floating action button (location icon → timer) |
| `DocyCheckInSheet` | Location/option selection sheet |
| `DocyCheckOutSheet` | Check-out form sheet with notes and outcome |

## Hooks

| Hook | Returns | Description |
|------|---------|-------------|
| `useCheckIn()` | `CheckInContextType` | Access check-in state and actions |

## Type Exports

| Type | Description |
|------|-------------|
| `CheckInProviderProps` | Props for CheckInProvider |
| `DocyCheckInButtonProps` | Props for DocyCheckInButton |
| `CheckInOption` | Check-in option (`{ id, label, icon?, color? }`) |
| `CheckInSession` | Active session (`{ id, optionId, optionLabel, startTime, elapsedSeconds, location }`) |

---

# rn-comments-panel
URL: /docs/native/docyrus/comments-panel

Threaded comments panel with replies, editing, deletion, and attachments.

## Installation

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

## Usage

```tsx
import { CommentsPanel } from '@/components/docyrus-native/comments-panel';

<CommentsPanel
  comments={comments}
  currentUser={{ id: 'user1', name: 'John Doe' }}
  onCreateComment={({ message, parentId }) => createComment(message, parentId)}
  onUpdateComment={(id, message) => updateComment(id, message)}
  onDeleteComment={(id) => deleteComment(id)}
/>
```

## API Reference

### CommentsPanelProps

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `comments` | `Comment[]` | - | Array of comment objects (threaded via `parent_id`) |
| `currentUser` | `CommentUser` | - | Current user for ownership checks (edit/delete visibility) |
| `editable` | `boolean` | `true` | Enable reply, edit, and delete actions |
| `isLoading` | `boolean` | `false` | Show loading state |
| `onCreateComment` | `(payload: { message: string; parentId?: string }) => void` | - | Callback to create a new comment or reply |
| `onUpdateComment` | `(id: string, message: string) => void` | - | Callback to update an existing comment |
| `onDeleteComment` | `(id: string) => void` | - | Callback to delete a comment |
| `className` | `string` | - | Additional CSS classes |

### Comment

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `id` | `string` | - | Unique identifier |
| `message` | `string` | - | Comment text content |
| `created_on` | `string` | - | ISO 8601 timestamp |
| `parent_id` | `string \| null` | - | Parent comment ID for threading (`null` for top-level) |
| `record_id` | `string` | - | Associated record identifier |
| `user` | `CommentUser` | - | Author of the comment |
| `attachments` | `CommentAttachment[]` | - | File attachments on the comment |

### CommentUser

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `id` | `string` | - | Unique user identifier |
| `name` | `string` | - | Display name (used for initials and header) |
| `avatarUrl` | `string` | - | Avatar image URL |

### CommentAttachment

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `id` | `string` | - | Unique attachment identifier |
| `file_name` | `string` | - | File name |
| `file_type` | `string` | - | MIME type |
| `file_size` | `number` | - | File size in bytes |
| `signed_url` | `string` | - | Signed URL for file access |

## Type Exports

| Type | Description |
|------|-------------|
| `CommentsPanelProps` | Props for CommentsPanel component |
| `Comment` | Comment data structure |
| `CommentUser` | Comment author information |
| `CommentAttachment` | File attachment on a comment |

---

# rn-confirmation-button
URL: /docs/native/docyrus/confirmation-button

Button that opens a countdown confirmation modal before executing the action.

## Installation

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

## Usage

```tsx
import { ConfirmationButton } from '@/components/docyrus-native/confirmation-button';

```

### Custom Messages

```tsx

```

### Variants

```tsx

```

### With Callbacks

```tsx

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode` | — | Button content. Strings are rendered as styled text automatically. |
| `onConfirm` | `() => void \| Promise<void>` | — | Callback invoked when the confirm button is pressed. Supports async functions with loading state. |
| `confirmationTitle` | `string` | `'Are you sure?'` | Title text displayed in the confirmation modal. |
| `confirmationMessage` | `string` | `'Please confirm before this action is executed.'` | Description text displayed in the confirmation modal. |
| `confirmLabel` | `string` | `'Confirm'` | Label for the confirm button in the modal. |
| `cancelLabel` | `string` | `'Cancel'` | Label for the cancel button in the modal. |
| `countdownSeconds` | `number` | `6` | Countdown duration in seconds. The modal auto-cancels when the countdown reaches zero. Minimum value is 1. |
| `disabled` | `boolean` | `false` | When true, the trigger button is disabled and cannot open the modal. |
| `onCancel` | `() => void` | — | Callback invoked when the user cancels (presses cancel or taps outside). |
| `onTimeout` | `() => void` | — | Callback invoked when the countdown expires and the modal auto-closes. |
| `variant` | `ConfirmationButtonVariant` | `'destructive'` | Visual variant of the trigger button. |
| `className` | `string` | — | Custom style applied to the trigger button (merged after buttonStyle). |
| `buttonClassName` | `string` | — | Custom style applied to the trigger button (merged before style). |

## Type Exports

| Type | Description |
|------|-------------|
| `ConfirmationButtonProps` | Props for the ConfirmationButton component. |
| `ConfirmationButtonVariant` | Button variant: `'default' \| 'secondary' \| 'destructive' \| 'outline' \| 'ghost'`. |

---

# rn-contact-activity-panel
URL: /docs/native/docyrus/contact-activity-panel

A timeline panel for displaying and adding contact activities with type-specific icons, user badges, and an inline add form.

## Installation

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

## Usage

```tsx
import { ContactActivityPanel } from '@/components/docyrus-native/contact-activity-panel';

<ContactActivityPanel
  activities={[
    {
      id: '1',
      type: 'call',
      title: 'Follow-up call',
      description: 'Discussed pricing options',
      timestamp: '2024-01-15T14:30:00Z',
      user: { id: 'u1', name: 'Jane Smith' }
    }
  ]}
  currentUser={{ id: 'u1', name: 'Jane Smith' }}
  onAddActivity={(activity) => console.log(activity)}
/>
```

## API Reference

### ContactActivityPanelProps

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `activities` | `ActivityItem[]` | — | Array of activity items to display |
| `currentUser` | `ActivityUser` | — | Current user. Required for showing the add activity button |
| `onAddActivity` | `(activity: { type: ActivityType; title: string; description?: string }) => void` | — | Called when a new activity is submitted. Add button only shows when both this and `currentUser` are provided |
| `isLoading` | `boolean` | `false` | Shows a loading state instead of the activity list |
| `emptyMessage` | `string` | `'No activities yet'` | Message displayed when activities array is empty |
| `className` | `string` | — | Additional CSS classes |

### ActivityItem

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | Unique identifier for the activity |
| `type` | `ActivityType` | Type of activity |
| `title` | `string` | Activity title text |
| `description` | `string` | Optional description text |
| `timestamp` | `string` | ISO 8601 timestamp |
| `user` | `ActivityUser` | The user who performed the activity |
| `metadata` | `Record<string, unknown>` | Optional metadata |

### ActivityUser

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | Unique user identifier |
| `name` | `string` | User display name |
| `avatarUrl` | `string` | Optional avatar image URL |

### ActivityType

```ts
type ActivityType = 'note' | 'email' | 'call' | 'meeting' | 'task' | 'status_change';
```

## Type Exports

| Type | Description |
|------|-------------|
| `ContactActivityPanelProps` | Props for ContactActivityPanel component |
| `ActivityItem` | Activity record data shape |
| `ActivityUser` | User data shape |
| `ActivityType` | Union of supported activity types |

---

# rn-create-record-dialog
URL: /docs/native/docyrus/create-record-dialog

A bottom-sheet dialog for creating new records with configurable selector fields, toggles, subject, and description inputs.

## Installation

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

## Usage

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

```

## Interaction Model

Selector fields expand inline inside the form instead of opening a second nested sheet. Long option lists keep their own internal scroll area, while the main form scroll pauses until the selector is closed.

## API Reference

### CreateRecordDialogProps

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `open` | `boolean` | `false` | Controls dialog visibility |
| `onOpenChange` | `(open: boolean) => void` | — | Called when the dialog open state changes |
| `children` | `ReactNode` | — | Trigger element. Wrapped in a Pressable that opens the dialog |
| `headerLabel` | `string` | `'Create Record'` | Title displayed in the dialog header |
| `headerFields` | `SelectorFieldConfig[]` | `[]` | Selector fields displayed above the subject input. They expand inline inside the form. |
| `subjectPlaceholder` | `string` | `'Enter title...'` | Placeholder text for the subject input |
| `descriptionPlaceholder` | `string` | `'Add a description...'` | Placeholder text for the description input |
| `footerFields` | `SelectorFieldConfig[]` | `[]` | Selector fields displayed below the description. They expand inline inside the form. |
| `footerToggles` | `FooterToggleConfig[]` | `[]` | Toggle switches displayed in the content area |
| `enableCreateMore` | `boolean` | `false` | Shows a "Create another" toggle in the footer |
| `onSubmit` | `(data: CreateRecordFormData) => void \| Promise<void>` | — | Called when the form is submitted |
| `isPending` | `boolean` | `false` | Shows a loading indicator and disables the submit button |
| `saveLabel` | `string` | `'Create'` | Label text for the submit button |
| `cancelLabel` | `string` | `'Cancel'` | Label text for the cancel button |
| `createMoreLabel` | `string` | `'Create another'` | Label for the create-more toggle |
| `addDescriptionLabel` | `string` | `'Add description'` | Label for the add-description link |
| `dialogTitle` | `string` | — | Overrides `headerLabel` as the dialog title |
| `className` | `string` | — | Custom styles applied to the dialog content container |

### SelectorFieldConfig

| Field | Type | Description |
|-------|------|-------------|
| `key` | `string` | Unique identifier for the field |
| `label` | `string` | Display label shown above the selector |
| `placeholder` | `string` | Placeholder text when no option is selected |
| `options` | `SelectorOption[]` | Available options to choose from |
| `value` | `string \| null` | Controlled selected value |
| `defaultValue` | `string` | Default selected option ID |
| `onChange` | `(value: string \| null) => void` | Called when the selection changes |

### SelectorOption

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | Unique identifier for the option |
| `label` | `string` | Display label |
| `description` | `string` | Optional description shown below the label |
| `icon` | `ReactNode` | Optional icon element |

### FooterToggleConfig

| Field | Type | Description |
|-------|------|-------------|
| `key` | `string` | Unique identifier for the toggle |
| `label` | `string` | Display label |
| `defaultValue` | `boolean` | Default toggle state (defaults to `false`) |

### CreateRecordFormData

| Field | Type | Description |
|-------|------|-------------|
| `subject` | `string` | The entered subject/title text |
| `description` | `string` | The entered description text |
| `fields` | `Record<string, string \| null>` | Selected values for all selector fields |
| `toggles` | `Record<string, boolean>` | Toggle states for all footer toggles |

## Type Exports

| Type | Description |
|------|-------------|
| `CreateRecordDialogProps` | Props for CreateRecordDialog component |
| `SelectorFieldConfig` | Selector field configuration |
| `SelectorOption` | Option within a selector field |
| `FooterToggleConfig` | Footer toggle configuration |
| `CreateRecordFormData` | Form data returned on submit |

---

# rn-data-grid-view-select
URL: /docs/native/docyrus/data-grid-view-select

A view selector component for data grids with tabs and dropdown variants, supporting view creation, deletion, and renaming.

## Installation

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

## Usage

```tsx
import { DataGridViewSelect } from '@/components/docyrus-native/data-grid-view-select';

<DataGridViewSelect
  views={[
    { id: '1', name: 'All Records', isDefault: true },
    { id: '2', name: 'Active' },
    { id: '3', name: 'Archived' }
  ]}
  onViewChange={(view) => console.log(view)}
  variant="tabs"
/>
```

## API Reference

### DataGridViewSelectProps

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `views` | `DataGridView[]` | — | Array of available views |
| `activeViewId` | `string` | — | Controlled active view ID |
| `defaultActiveViewId` | `string` | — | Initial active view ID for uncontrolled usage. Falls back to first view |
| `onViewChange` | `(view: DataGridView) => void` | — | Called when the active view changes |
| `onViewCreate` | `(name: string) => void` | — | Called when a new view is created. Enables the add button when provided |
| `onViewDelete` | `(viewId: string) => void` | — | Called when a view is deleted. Delete controls only show for non-default views |
| `onViewRename` | `(viewId: string, name: string) => void` | — | Called when a view is renamed (tabs variant, long press to rename) |
| `variant` | `'tabs' \| 'dropdown'` | `'tabs'` | Visual variant. `tabs` renders horizontal scrollable tabs, `dropdown` renders a select-style dropdown |
| `editable` | `boolean` | `false` | Enables create, delete, and rename actions |
| `disabled` | `boolean` | `false` | Disables all interactions |
| `placeholder` | `string` | `'Select view'` | Placeholder text for the dropdown variant when no view is selected |
| `className` | `string` | — | Additional CSS classes |

### DataGridView

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | Unique identifier for the view |
| `name` | `string` | Display name of the view |
| `icon` | `string` | Optional emoji or icon character displayed before the name |
| `isDefault` | `boolean` | Marks the view as default. Default views cannot be deleted |
| `filters` | `unknown` | View filter configuration |
| `sorting` | `unknown` | View sorting configuration |
| `columns` | `unknown` | View column configuration |

### DataGridViewSelectVariant

```ts
type DataGridViewSelectVariant = 'tabs' | 'dropdown';
```

## Type Exports

| Type | Description |
|------|-------------|
| `DataGridViewSelectProps` | Props for DataGridViewSelect component |
| `DataGridView` | View configuration object |
| `DataGridViewSelectVariant` | Union of supported visual variants |

---

# rn-data-grid
URL: /docs/native/docyrus/data-grid

Spreadsheet-like data grid with inline cell editing, sorting, filtering, gallery mode, and bulk actions.

## Installation

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

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

## Usage

```tsx
import { DataGrid } from '@/components/docyrus-native/data-grid';
import { type ColumnDef } from '@tanstack/react-table';

type Row = { name: string; email: string; status: string };

const columns: ColumnDef<Row, unknown>[] = [
  {
    accessorKey: 'name',
    header: 'Name',
    meta: { label: 'Name', width: 140, cell: { variant: 'short-text' } }
  },
  {
    accessorKey: 'email',
    header: 'Email',
    meta: { label: 'Email', width: 180, cell: { variant: 'email' } }
  },
  {
    accessorKey: 'status',
    header: 'Status',
    meta: {
      label: 'Status', width: 100,
      cell: {
        variant: 'status',
        options: [
          { label: 'Active', value: 'Active', color: '#22c55e' },
          { label: 'Inactive', value: 'Inactive', color: '#ef4444' }
        ]
      }
    }
  }
];

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `TData[]` | — | Grid data array (required) |
| `columns` | `ColumnDef<TData>[]` | — | Column definitions with cell variant metadata (required) |
| `sorting` | `SortingState` | — | Controlled sorting state |
| `onSortingChange` | `(sorting: SortingState) => void` | — | Sorting change callback |
| `columnFilters` | `ColumnFiltersState` | — | Controlled column filters |
| `onColumnFiltersChange` | `(filters: ColumnFiltersState) => void` | — | Column filter change callback |
| `rowHeight` | `'short' \| 'medium' \| 'tall'` | `'medium'` | Row height preset |
| `onRowHeightChange` | `(value: RowHeightValue) => void` | — | Row height change callback |
| `displayMode` | `'table' \| 'gallery'` | `'table'` | Display mode |
| `onDisplayModeChange` | `(mode: DataGridDisplayMode) => void` | — | Display mode change callback |
| `cardConfig` | `DataGridCardConfig<TData>` | — | Card configuration for gallery mode |
| `onDataUpdate` | `(update: CellUpdate) => void` | — | Inline cell edit callback |
| `onDataChange` | `(data: TData[]) => void` | — | Bulk data change callback |
| `onRowAdd` | `() => void` | — | Row add callback |
| `onRowsDelete` | `(rows: TData[], indices: number[]) => void` | — | Row delete callback |
| `actions` | `DataGridAction<TData>[]` | — | Bulk actions shown when rows are selected |
| `readOnly` | `boolean` | `false` | Read-only mode |
| `enableGrouping` | `boolean` | `false` | Enable row grouping |
| `enableSearch` | `boolean` | `false` | Enable search |
| `isLoading` | `boolean` | — | Show loading skeleton |
| `emptyText` | `string` | `'No data'` | Empty state text |
| `height` | `number` | — | Grid container height |
| `className` | `string` | — | Additional CSS classes |

### Column Meta

Each column can specify `meta` fields on `columnDef.meta`:

| Meta Field | Type | Description |
|------------|------|-------------|
| `label` | `string` | Display name used in toolbar menus |
| `group` | `string` | Column grouping category |
| `cell` | `CellOpts` | Cell variant and its configuration |
| `width` | `number` | Column width in pixels (default: 120) |
| `format` | `(value: TValue, row: TData) => string` | Custom formatter for cell display and export |

### Cell Variants

Column `meta.cell` accepts a `CellOpts` discriminated union:

| Variant | Options | Description |
|---------|---------|-------------|
| `short-text` | — | Single-line text |
| `long-text` | — | Multi-line text |
| `email` | — | Email display |
| `phone` | — | Phone display |
| `url` | — | URL display |
| `number` | `min`, `max`, `step` | Numeric value |
| `currency` | `currency`, `min`, `max` | Currency display |
| `percent` | `min`, `max` | Percentage |
| `select` | `options: CellSelectOption[]` | Single select |
| `status` | `options: CellSelectOption[]` | Status badge |
| `multi-select` | `options: CellSelectOption[]` | Multi select |
| `tag-select` | `options: CellSelectOption[]` | Tag selector |
| `user` | `options: CellUserOption[]` | User avatar select |
| `user-multi-select` | `options: CellUserOption[]` | Multi user select |
| `checkbox` | — | Boolean checkbox |
| `switch` | — | Boolean switch |
| `date` | — | Date picker |
| `datetime` | — | DateTime picker |
| `time` | — | Time picker |
| `date-range` | — | Date range |
| `rating` | `max` | Star rating |
| `duration` | — | Duration |
| `color` | — | Color picker |
| `relation` | `dataSourceId`, `displayField` | Linked record |
| `sparkline` | `color` | Mini chart |

## Components

| Component | Description |
|-----------|-------------|
| `DataGrid` | Main grid component |
| `DataGridCell` | Individual cell renderer |
| `DataGridGallery` | Gallery mode card layout |
| `DataGridSkeleton` | Loading skeleton |

## Type Exports

| Type | Description |
|------|-------------|
| `DataGridProps` | Props for DataGrid |
| `CellVariant` | Cell type union |
| `CellOpts` | Discriminated cell options |
| `CellSelectOption` | Select/status option |
| `CellUserOption` | User option with avatar |
| `CellUpdate` | Cell edit payload |
| `DataGridAction` | Bulk action definition |
| `DataGridCardConfig` | Gallery card config |
| `DataGridDisplayMode` | Display mode type |
| `RowHeightValue` | Row height preset type |

---

# rn-data-table-filter
URL: /docs/native/docyrus/data-table-filter

Filter builder for data tables with column selection, operator matching, and filter pills.

## Installation

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

## Usage

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

```

## API Reference

### DataTableFilterProps

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `columns` | `FilterColumn[]` | - | Column definitions for filter options |
| `filters` | `FilterItem[]` | - | Current active filters |
| `onFiltersChange` | `(filters: FilterItem[]) => void` | - | Callback when filters are added, removed, or cleared |
| `strategy` | `'and' \| 'or'` | `'and'` | Logical operator between filters (displayed as toggle when 2+ filters) |
| `className` | `string` | - | Additional CSS classes |

### FilterColumn

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `id` | `string` | - | Unique column identifier |
| `label` | `string` | - | Column display name |
| `type` | `FilterColumnType` | - | Column data type: `'text' \| 'number' \| 'date' \| 'boolean' \| 'select'` |
| `options` | `{ label: string; value: string }[]` | - | Options for `select` type columns |

### FilterItem

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `id` | `string` | - | Unique filter identifier |
| `columnId` | `string` | - | ID of the column being filtered |
| `operator` | `FilterOperator` | - | Filter operator |
| `value` | `unknown` | - | Filter value (omitted for `is_empty`/`is_not_empty` operators) |

### FilterOperator

| Operator | Label | Compatible Types | Needs Value |
|----------|-------|------------------|-------------|
| `equals` | Equals | text, number, date, select | Yes |
| `contains` | Contains | text | Yes |
| `gt` | Greater than | number, date | Yes |
| `lt` | Less than | number, date | Yes |
| `between` | Between | number, date | Yes |
| `is_empty` | Is empty | text, number, date, boolean, select | No |
| `is_not_empty` | Is not empty | text, number, date, boolean, select | No |

### FilterColumnType

```tsx
type FilterColumnType = 'text' | 'number' | 'date' | 'boolean' | 'select';
```

## Type Exports

| Type | Description |
|------|-------------|
| `DataTableFilterProps` | Props for DataTableFilter component |
| `FilterColumn` | Column definition for filter options |
| `FilterItem` | Active filter configuration |
| `FilterOperator` | `'equals' \| 'contains' \| 'gt' \| 'lt' \| 'between' \| 'is_empty' \| 'is_not_empty'` |
| `FilterColumnType` | `'text' \| 'number' \| 'date' \| 'boolean' \| 'select'` |

---

# rn-data-table
URL: /docs/native/docyrus/data-table

Full-featured data table with sorting, filtering, pagination, grouping, and pinning.

## Installation

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

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

## Usage

```tsx
import { DataTable, DataTableToolbar } from '@/components/docyrus-native/data-table';
import { type ColumnDef } from '@tanstack/react-table';

const columns: ColumnDef<Person>[] = [
  { accessorKey: 'name', header: 'Name' },
  { accessorKey: 'role', header: 'Role' },
  { accessorKey: 'status', header: 'Status' },
];

```

## API Reference

### DataTable

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `TData[]` | — | Table data array |
| `columns` | `ColumnDef<TData>[]` | — | Column definitions |
| `getRowId` | `(row: TData) => string` | — | Custom row ID accessor |
| `getSubRows` | `(row: TData) => TData[] \| undefined` | — | Sub-row accessor for expandable rows |
| `enableSorting` | `boolean` | `true` | Enable column sorting |
| `enableFiltering` | `boolean` | `false` | Enable column filtering |
| `enableGlobalFilter` | `boolean` | `false` | Enable global search filter |
| `enableColumnVisibility` | `boolean` | — | Enable column visibility toggling |
| `enableRowSelection` | `boolean` | `false` | Enable row selection |
| `enableMultiRowSelection` | `boolean` | `false` | Enable multi-row selection |
| `enableColumnPinning` | `boolean` | `false` | Enable column pinning |
| `enableColumnResizing` | `boolean` | — | Enable column resizing |
| `enableGrouping` | `boolean` | `false` | Enable row grouping |
| `enableExpanding` | `boolean` | `false` | Enable row expanding |
| `enableRowPinning` | `boolean` | `false` | Enable row pinning |
| `pagination` | `PaginationConfig` | — | Pagination configuration object |
| `sorting` | `SortingState` | — | Controlled sorting state |
| `onSortingChange` | `OnChangeFn<SortingState>` | — | Sorting state change handler |
| `columnFilters` | `ColumnFiltersState` | — | Controlled column filters state |
| `onColumnFiltersChange` | `OnChangeFn<ColumnFiltersState>` | — | Column filters change handler |
| `globalFilter` | `string` | — | Controlled global filter value |
| `onGlobalFilterChange` | `OnChangeFn<string>` | — | Global filter change handler |
| `columnVisibility` | `VisibilityState` | — | Controlled column visibility state |
| `onColumnVisibilityChange` | `OnChangeFn<VisibilityState>` | — | Column visibility change handler |
| `rowSelection` | `RowSelectionState` | — | Controlled row selection state |
| `onRowSelectionChange` | `OnChangeFn<RowSelectionState>` | — | Row selection change handler |
| `expanded` | `ExpandedState` | — | Controlled expanded rows state |
| `onExpandedChange` | `OnChangeFn<ExpandedState>` | — | Expanded rows change handler |
| `columnPinning` | `ColumnPinningState` | — | Controlled column pinning state |
| `onColumnPinningChange` | `OnChangeFn<ColumnPinningState>` | — | Column pinning change handler |
| `grouping` | `GroupingState` | — | Controlled grouping state |
| `onGroupingChange` | `OnChangeFn<GroupingState>` | — | Grouping state change handler |
| `rowPinning` | `RowPinningState` | — | Controlled row pinning state |
| `onRowPinningChange` | `OnChangeFn<RowPinningState>` | — | Row pinning change handler |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Table size |
| `variant` | `'default' \| 'outlined' \| 'elevated'` | `'default'` | Table visual variant |
| `zebra` | `boolean` | `false` | Alternate row background colors |
| `rowDividers` | `boolean` | `true` | Show row divider lines |
| `columnDividers` | `boolean` | `false` | Show column divider lines |
| `stickyHeader` | `boolean` | `false` | Sticky table header on scroll |
| `maxHeight` | `number` | — | Maximum table height for scrollable content |
| `maxCellCharacters` | `number` | — | Max characters per cell before truncation |
| `onRowClick` | `(row: TData) => void` | — | Row click handler |
| `emptyText` | `string` | — | Text shown when table has no data |

### PaginationConfig

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `enabled` | `boolean` | — | Enable pagination |
| `pageSize` | `number` | `10` | Number of rows per page |
| `pageIndex` | `number` | `0` | Current page index (zero-based) |
| `currentPage` | `number` | — | Current page (one-based, for server-side) |
| `itemsPerPage` | `number` | — | Items per page |
| `totalItems` | `number` | — | Total item count (enables server-side pagination) |
| `showFirstLast` | `boolean` | — | Show first/last page buttons |
| `showPrevNext` | `boolean` | — | Show prev/next page buttons |
| `showPageNumbers` | `boolean` | — | Show page number buttons |
| `maxPageNumbers` | `number` | — | Maximum visible page numbers |
| `onPaginationChange` | `(pageIndex: number, pageSize: number) => void` | — | Page change callback |

### DataTableToolbar

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `globalFilter` | `string` | — | Current global filter value |
| `onGlobalFilterChange` | `(value: string) => void` | — | Global filter change handler |
| `searchPlaceholder` | `string` | — | Search input placeholder text |
| `enableColumnVisibility` | `boolean` | — | Show column visibility toggle |
| `columns` | `{ id: string; label: string; visible: boolean }[]` | — | Column visibility list |
| `onColumnVisibilityChange` | `(columnId: string, visible: boolean) => void` | — | Column visibility change handler |
| `actions` | `ReactNode` | — | Custom toolbar actions |

## Components

| Component | Description |
|-----------|-------------|
| `DataTable` | Main data table component |
| `DataTableToolbar` | Search, column visibility and actions toolbar |

## Type Exports

| Type | Description |
|------|-------------|
| `DataTableProps` | Props for DataTable component |
| `DataTableToolbarProps` | Props for DataTableToolbar component |

---

# rn-date-time-picker
URL: /docs/native/docyrus/date-time-picker

A date and time picker using the native platform picker with ActionSheet presentation on iOS and dialog on Android.

## Installation

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

**Dependencies:**
- [@react-native-community/datetimepicker](https://www.npmjs.com/package/@react-native-community/datetimepicker)

The native picker is loaded via dynamic `require()` — the component renders a fallback message if the package is not installed.

## Usage

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

<DateTimePicker
  value={new Date()}
  onChange={(date) => console.log(date)}
  format="datetime"
/>
```

### Date only

```tsx

```

### Time only

```tsx

```

### Controlled visibility (for embedding in forms)

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

```

When `open` and `onOpenChange` are provided, the built-in trigger button is not rendered — the parent controls visibility.

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `Date \| null` | — | The currently selected date/time value. |
| `onChange` | `(date: Date \| null) => void` | — | Callback fired when the user confirms or clears the selection. |
| `minDate` | `Date` | — | Minimum selectable date. |
| `maxDate` | `Date` | — | Maximum selectable date. |
| `disabled` | `boolean` | `false` | Disables the picker trigger. |
| `placeholder` | `string` | — | Placeholder text when no value is selected. |
| `format` | `DateTimePickerFormat` | `'datetime'` | Controls which picker mode is used: `'datetime'`, `'date'`, or `'time'`. |
| `size` | `DateTimePickerSize` | `'md'` | Trigger button size (only in uncontrolled mode). |
| `clearable` | `boolean` | `true` | Show clear button in the picker header. |
| `messages` | `Partial<DateTimePickerMessages>` | — | Override default English labels for i18n. |
| `open` | `boolean` | — | Controlled visibility. When provided, no built-in trigger is rendered. |
| `onOpenChange` | `(open: boolean) => void` | — | Callback when picker visibility changes. |
| `className` | `string` | — | Additional class names for the trigger. |
| `style` | `ViewStyle` | — | Additional styles for the trigger. |

### DateTimePickerMessages

| Key | Default | Description |
|-----|---------|-------------|
| `selectDate` | `'Select Date'` | ActionSheet title for date mode. |
| `selectTime` | `'Select Time'` | ActionSheet title for time mode. |
| `selectDateTime` | `'Select Date & Time'` | ActionSheet title for datetime mode. |
| `cancel` | `'Cancel'` | Cancel button label. |
| `done` | `'Done'` | Done button label. |
| `clear` | `'Clear'` | Clear button label. |
| `fallback` | `'Install @react-native-community/...'` | Fallback message when native picker is not installed. |

## Platform Behavior

| Platform | Presentation | Picker type |
|----------|-------------|-------------|
| iOS | ActionSheet with spinner | Native `UIDatePicker` (spinner mode) |
| Android | Native dialog | `DatePickerDialog` / `TimePickerDialog` |
| No native picker | Inline fallback message | — |

## Exported Helpers

| Export | Type | Description |
|--------|------|-------------|
| `formatPickerDate` | `(date, mode, dateFormat?, timeFormat?) => string` | Format a date for display. Used by form fields. |
| `getDeviceLocale` | `() => string` | Returns the device locale string via `Intl.DateTimeFormat`. |

## Type Exports

| Type | Description |
|------|-------------|
| `DateTimePickerProps` | Props for the DateTimePicker component. |
| `DateTimePickerFormat` | `'datetime' \| 'date' \| 'time'` — picker mode. |
| `DateTimePickerSize` | Size variant for the trigger button. |
| `DateTimePickerMessages` | i18n message overrides. |

---

# rn-date-time-range-picker
URL: /docs/native/docyrus/date-time-range-picker

A modal date-time range picker with start/end tabs, calendar grid, and time controls.

## Installation

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

## Usage

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

<DateTimeRangePicker
  startDate={new Date()}
  endDate={new Date()}
  onChange={(start, end) => console.log(start, end)}
/>
```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `startDate` | `Date \| null` | — | The start date/time of the range. |
| `endDate` | `Date \| null` | — | The end date/time of the range. |
| `onChange` | `(start: Date \| null, end: Date \| null) => void` | — | Callback fired when the user confirms or clears the selection. |
| `minDate` | `Date` | — | Minimum selectable date. Days before this are disabled. |
| `maxDate` | `Date` | — | Maximum selectable date. Days after this are disabled. |
| `minuteInterval` | `number` | `5` | Step interval for minute selection. |
| `disabled` | `boolean` | `false` | Disables the picker trigger. |
| `placeholder` | `string` | — | Placeholder text shown when no range is selected. Defaults to `"Select range"`. |
| `className` | `string` | — | Additional CSS classes |

## Type Exports

| Type | Description |
|------|-------------|
| `DateTimeRangePickerProps` | Props for the DateTimeRangePicker component. |

---

# rn-day-picker
URL: /docs/native/docyrus/day-picker

An inline calendar day picker supporting single, multiple, and range selection modes.

## Installation

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

## Usage

```tsx
import { DayPicker } from '@/components/docyrus-native/day-picker';

<DayPicker
  value={new Date()}
  onChange={(date) => console.log(date)}
  mode="single"
/>
```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `Date \| Date[] \| null` | — | The selected date(s). A single `Date` for single mode, an array for multiple/range modes. |
| `onChange` | `(date: Date \| Date[] \| null) => void` | — | Callback fired when the selection changes. |
| `mode` | `DayPickerMode` | `'single'` | Selection mode: `'single'`, `'multiple'`, or `'range'`. |
| `minDate` | `Date` | — | Minimum selectable date. Days before this are disabled. |
| `maxDate` | `Date` | — | Maximum selectable date. Days after this are disabled. |
| `disabled` | `boolean` | `false` | Disables all day interactions. |
| `className` | `string` | — | Additional CSS classes |

## Type Exports

| Type | Description |
|------|-------------|
| `DayPickerProps` | Props for the DayPicker component. |
| `DayPickerMode` | `'single' \| 'multiple' \| 'range'` — selection mode. |

---

# rn-delete-confirm-dialog
URL: /docs/native/docyrus/delete-confirm-dialog

Modal confirmation dialog for delete operations with customizable title, description, and pending state.

## Installation

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

## Usage

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

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

<DeleteConfirmDialog
  open={open}
  onOpenChange={setOpen}
  objectName="item"
  count={3}
  onConfirm={async () => {
    await deleteItems();
  }}
/>
```

### Custom Labels

```tsx

```

### With Pending State

```tsx

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `open` | `boolean` | — | Controls the visibility of the dialog. |
| `onOpenChange` | `(open: boolean) => void` | — | Callback when the dialog open state changes. |
| `objectName` | `string` | — | The name of the object type being deleted (used in auto-generated title/description). |
| `count` | `number` | — | Number of items being deleted (used in auto-generated title/description). |
| `onConfirm` | `() => void \| Promise<void>` | — | Callback invoked when the confirm button is pressed. |
| `isPending` | `boolean` | `false` | When true, disables buttons and shows "Deleting..." on the confirm button. |
| `title` | `string` | `"Delete {count} {objectName}(s)?"` | Custom dialog title. Overrides the auto-generated title. |
| `description` | `string` | `"This will permanently delete..."` | Custom dialog description. Overrides the auto-generated description. |
| `confirmLabel` | `string` | `'Delete'` | Label for the confirm button. |
| `cancelLabel` | `string` | `'Cancel'` | Label for the cancel button. |
| `className` | `string` | — | Custom style applied to the dialog container. |

## Type Exports

| Type | Description |
|------|-------------|
| `DeleteConfirmDialogProps` | Props for the DeleteConfirmDialog component. |

---

# rn-docyrus-icon
URL: /docs/native/docyrus/docyrus-icon

CDN-powered icon component supporting Font Awesome, Huge Icons, emojis, and custom libraries.

## Installation

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

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

## Usage

```tsx
import { DocyrusIcon } from '@/components/docyrus-native/docyrus-icon';

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `icon` | `string` | — | Icon string (e.g. `"fal star"`, `"huge notification-01"`, `"dot"`, or emoji) |
| `lib` | `string` | `'kv'` | Default icon library when not specified in icon string |
| `group` | `string \| null` | `null` | Icon group/subfolder override |
| `size` | `number \| 'xs' \| 'sm' \| 'default' \| 'lg' \| 'xl'` | `'default'` | Icon size (pixel number or preset) |
| `color` | `DocyrusIconColor` | `'default'` | Icon color (theme key or custom color string) |
| `className` | `string` | — | Additional CSS classes |
| `onPress` | `() => void` | — | Press handler (wraps in Pressable) |
| `disabled` | `boolean` | `false` | Disabled state (only with onPress) |

### DocyrusIconColor

Theme color keys: `'default'`, `'muted'`, `'primary'`, `'secondary'`, `'accent'`, `'destructive'`, `'success'`, `'warning'`, `'info'`

Any custom hex or RGB string is also accepted.

### Icon String Format

| Format | Example | Description |
|--------|---------|-------------|
| `"<lib> <name>"` | `"fal star"` | Font Awesome Light star |
| `"<lib> <group> <name>"` | `"huge editor bold"` | Huge Icons with group |
| `"<name>"` | `"settings"` | Uses default lib (kv) |
| `"dot"` | `"dot"` | Renders a bullet character |
| emoji | `"⭐"` | Renders the emoji directly |

## Type Exports

| Type | Description |
|------|-------------|
| `DocyrusIconProps` | Props for DocyrusIcon component |
| `DocyrusIconSize` | `number \| 'xs' \| 'sm' \| 'default' \| 'lg' \| 'xl'` |
| `DocyrusIconColor` | Theme color key or custom string |

---

# rn-duration-select
URL: /docs/native/docyrus/duration-select

Duration picker with hours and minutes grid, supporting multiple display formats.

## Installation

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

## Usage

```tsx
import { DurationSelect } from '@/components/docyrus-native/duration-select';

const [duration, setDuration] = useState<number | null>(3600); // 1 hour in seconds

```

### Display Formats

```tsx
// Compact: "2h 30m"

// HH:MM: "02:30"

// Decimal: "2.50h"

```

### Custom Increments

```tsx

```

### Format Helper

```tsx
import { formatDurationDisplay } from '@/components/docyrus-native/duration-select';

formatDurationDisplay(5400, 'compact'); // "1h 30m"
formatDurationDisplay(5400, 'HH:MM');   // "01:30"
formatDurationDisplay(5400, 'decimal'); // "1.50h"
```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `number \| null \| undefined` | — | Duration value in seconds. |
| `onChange` | `(seconds: number \| null) => void` | — | Callback when the duration changes. Receives `null` when cleared. |
| `format` | `'HH:MM' \| 'compact' \| 'decimal'` | `'compact'` | Display format for the trigger label. |
| `minuteIncrement` | `number` | `15` | Minute step interval in the picker grid. |
| `maxHours` | `number` | `8` | Maximum number of hours shown in the picker grid. |
| `disabled` | `boolean` | `false` | When true, the trigger is non-interactive and visually dimmed. |
| `invalid` | `boolean` | `false` | When true, the trigger border uses the destructive color. |
| `placeholder` | `string` | — | Placeholder text when no value is selected. Falls back to `'0h 0m'`. |
| `className` | `string` | — | Custom style applied to the trigger button. |

## Exported Functions

| Function | Signature | Description |
|----------|-----------|-------------|
| `formatDurationDisplay` | `(totalSeconds: number, format: DurationFormat) => string` | Formats a duration in seconds to a display string using the specified format. |

## Type Exports

| Type | Description |
|------|-------------|
| `DurationSelectProps` | Props for the DurationSelect component. |
| `DurationFormat` | Display format: `'HH:MM' \| 'compact' \| 'decimal'`. |

---

# rn-editable-record-detail
URL: /docs/native/docyrus/editable-record-detail

An inline-editable record detail view that tracks field changes and supports custom renderers for both display and edit modes.

## Installation

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

## Usage

```tsx
import { EditableRecordDetail } from '@/components/docyrus-native/editable-record-detail';

<EditableRecordDetail
  fields={[
    { key: 'name', label: 'Name', value: 'John Doe', type: 'text' },
    { key: 'email', label: 'Email', value: 'john@example.com', type: 'email' },
    { key: 'notes', label: 'Notes', value: '', type: 'multiline', placeholder: 'Add notes...' }
  ]}
  onSave={(changes) => console.log(changes)}
/>
```

### Horizontal Layout

Use `fieldLayout="horizontal"` to render labels on the left and values on the right. Plain text-style fields stay inline, while custom editors expand directly under the row so you do not need a second ActionSheet layer to finish editing.

```tsx
<EditableRecordDetail
  fieldLayout="horizontal"
  fields={[
    { key: 'name', label: 'Full Name', value: 'John Doe', type: 'text' },
    { key: 'email', label: 'Email', value: 'john@example.com', type: 'email' },
    { key: 'phone', label: 'Phone', value: '+1 555-1234', type: 'phone' },
    { key: 'notes', label: 'Notes', value: 'Some long notes...', type: 'multiline' }
  ]}
  onSave={(changes) => console.log(changes)}
/>
```

## Visual Feedback

Editable fields provide visual cues to indicate interactivity:

- **Inline text fields** render as editable inputs directly in the row, so typing updates the draft immediately
- **Custom editors** such as status, select, and date fields expand inline beneath the row instead of opening a second modal editor
- **Changed fields** are highlighted with a tinted background, plus a small dot next to the label
- **Read-only fields** have no press feedback and appear static

## API Reference

### EditableRecordDetailProps

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `fields` | `RecordDetailField[]` | — | Array of field definitions to render |
| `onSave` | `(changes: FieldChange[]) => void \| Promise<void>` | — | Called with an array of changed fields when save is pressed |
| `onCancel` | `() => void` | — | Called when the cancel button is pressed |
| `isSaving` | `boolean` | `false` | Shows saving state on the save button and disables actions |
| `saveLabel` | `string` | `'Save'` | Label text for the save button |
| `cancelLabel` | `string` | `'Cancel'` | Label text for the cancel button |
| `emptyValueText` | `string` | `'—'` | Text displayed for null or empty field values |
| `fieldLayout` | `'vertical' \| 'horizontal'` | `'vertical'` | Controls label/value placement. Horizontal puts label left and value right while expanded custom editors render inline under the active row. |
| `className` | `string` | — | Additional CSS classes |

### RecordDetailField

| Field | Type | Description |
|-------|------|-------------|
| `key` | `string` | Unique identifier for the field |
| `label` | `string` | Display label |
| `value` | `unknown` | Current field value |
| `type` | `'text' \| 'number' \| 'email' \| 'phone' \| 'url' \| 'multiline'` | Input type, determines keyboard type and layout |
| `readOnly` | `boolean` | Prevents editing when true |
| `required` | `boolean` | Marks field as required — save is blocked when empty and an inline error is shown |
| `placeholder` | `string` | Placeholder text for the input |
| `renderValue` | `(value: unknown) => ReactNode` | Custom renderer for display mode |
| `renderEditor` | `(value: unknown, onChange: (value: unknown) => void, onDone?: (value?: unknown) => void) => ReactNode` | Custom renderer for edit mode. Use `onDone` when a picker should commit immediately after selection. |

### FieldChange

| Field | Type | Description |
|-------|------|-------------|
| `fieldKey` | `string` | Key of the changed field |
| `fieldLabel` | `string` | Label of the changed field |
| `originalValue` | `unknown` | Original value before editing |
| `newValue` | `unknown` | New value after editing |

## Type Exports

| Type | Description |
|------|-------------|
| `EditableRecordDetailProps` | Props for EditableRecordDetail component |
| `RecordDetailField` | Field configuration object |
| `FieldChange` | Object representing a single field change |
| `FieldLayout` | `'vertical' \| 'horizontal'` layout type |

---

# rn-editable-value
URL: /docs/native/docyrus/editable-value

Inline editable text field with view/edit mode toggle and optional save/cancel actions.

## Installation

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

## Usage

```tsx
import { EditableValue } from '@/components/docyrus-native/editable-value';

<EditableValue
  value="Hello World"
  onValueChange={(value) => console.log(value)}
  placeholder="Click to edit..."
/>
```

## API Reference

### EditableValueProps

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `string` | - | Current display value |
| `onValueChange` | `(value: string) => void` | - | Callback when value is saved |
| `disabled` | `boolean` | `false` | Disables editing and dims the text |
| `readOnly` | `boolean` | `false` | Prevents entering edit mode (no dim styling) |
| `placeholder` | `string` | `'Click to edit...'` | Placeholder text when value is empty |
| `showActions` | `boolean` | `true` | Show Save/Cancel buttons in edit mode |
| `explicitSave` | `boolean` | `false` | Require explicit Save button press (prevents auto-save on blur) |
| `editing` | `boolean` | - | Controlled editing state |
| `onEditingChange` | `(editing: boolean) => void` | - | Callback when editing state changes |
| `multiline` | `boolean` | `false` | Enable multiline text input |
| `className` | `string` | - | Additional CSS classes |

## Type Exports

| Type | Description |
|------|-------------|
| `EditableValueProps` | Props for EditableValue component |

---

# rn-empty-state
URL: /docs/native/docyrus/empty-state

Placeholder display for empty content areas with variant-specific icons and actions.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-empty-state
```

## Usage

```tsx
import { EmptyState } from '@/components/docyrus-native/empty-state';

<EmptyState
  variant="default"
  title="No projects yet"
  description="Create your first project to get started."
  action={{ label: 'Create Project', onPress: () => {} }}
/>
```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `variant` | `'default' \| 'search' \| 'filter' \| 'error' \| 'offline' \| 'permission' \| 'empty-inbox' \| 'no-data'` | `'default'` | Preset variant with default icon, title, and description |
| `icon` | `ReactNode` | — | Custom icon to display (overrides variant emoji) |
| `title` | `string` | — | Custom title (overrides variant default) |
| `description` | `string` | — | Custom description (overrides variant default) |
| `action` | `EmptyStateAction` | — | Primary action button |
| `secondaryAction` | `EmptyStateAction` | — | Secondary action button (outline style) |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Component size |
| `animated` | `boolean` | `true` | Enable floating animation on the icon |
| `className` | `string` | — | Additional CSS classes |
| `accessibilityLabel` | `string` | — | Accessibility label override |

### EmptyStateAction

| Prop | Type | Description |
|------|------|-------------|
| `label` | `string` | Button text |
| `onPress` | `() => void` | Button press handler |

## Type Exports

| Type | Description |
|------|-------------|
| `EmptyStateProps` | Props for EmptyState component |
| `EmptyStateVariant` | `'default' \| 'search' \| 'filter' \| 'error' \| 'offline' \| 'permission' \| 'empty-inbox' \| 'no-data'` |
| `EmptyStateSize` | `'sm' \| 'md' \| 'lg'` |
| `EmptyStateAction` | Action button configuration object |

---

# rn-error-state
URL: /docs/native/docyrus/error-state

Error display with variant-specific messaging, retry actions, and expandable error details.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-error-state
```

## Usage

```tsx
import { ErrorState } from '@/components/docyrus-native/error-state';

<ErrorState variant="network" onRetry={() => refetch()} />

<ErrorState
  variant="server"
  errorCode={500}
  errorMessage="Internal Server Error: Connection refused at db:5432"
  onRetry={() => refetch()}
  onBack={() => navigation.goBack()}
/>
```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `variant` | `'default' \| 'network' \| 'server' \| 'timeout' \| 'not-found' \| 'forbidden' \| 'maintenance'` | `'default'` | Preset variant with default icon, title, and description |
| `icon` | `ReactNode` | — | Custom icon to display (overrides variant emoji) |
| `title` | `string` | — | Custom title (overrides variant default) |
| `description` | `string \| ErrorObject` | — | Custom description or error object with message/code |
| `errorMessage` | `string` | — | Detailed error message shown in expandable details section |
| `errorCode` | `string \| number` | — | Error code displayed as a badge |
| `onRetry` | `() => void` | — | Retry button press handler |
| `retryLabel` | `string` | `'Try again'` | Custom retry button label |
| `isRetrying` | `boolean` | `false` | Show retrying state with spinner animation |
| `onBack` | `() => void` | — | Back button press handler |
| `backLabel` | `string` | `'Go back'` | Custom back button label |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Component size |
| `className` | `string` | — | Additional CSS classes |
| `accessibilityLabel` | `string` | — | Accessibility label override |

## Type Exports

| Type | Description |
|------|-------------|
| `ErrorStateProps` | Props for ErrorState component |
| `ErrorStateVariant` | `'default' \| 'network' \| 'server' \| 'timeout' \| 'not-found' \| 'forbidden' \| 'maintenance'` |
| `ErrorStateSize` | `'sm' \| 'md' \| 'lg'` |

---

# rn-fab
URL: /docs/native/docyrus/fab

Floating action button with ActionSheet menu, position control, and variant colors.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-fab
```

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

## Usage

```tsx
import { Fab } from '@/components/docyrus-native/fab';

<Fab onPress={() => console.log('pressed')} />

<Fab
  variant="secondary"
  items={[
    { label: 'Camera', onPress: () => {} },
    { label: 'Gallery', onPress: () => {} },
  ]}
/>
```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `onPress` | `() => void` | — | Press handler (when no items provided) |
| `label` | `string` | — | Extended label text next to icon |
| `icon` | `ReactNode` | — | Custom icon element |
| `position` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | `'bottom-right'` | Screen position |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Button size |
| `variant` | `'primary' \| 'secondary' \| 'success' \| 'warning' \| 'destructive'` | `'primary'` | Color variant |
| `disabled` | `boolean` | `false` | Disabled state |
| `items` | `FabItem[]` | — | Menu items (opens ActionSheet when pressed) |
| `menuTitle` | `string` | — | Title for the ActionSheet menu |
| `className` | `string` | — | Additional CSS classes |
| `textClassName` | `string` | — | Label text CSS classes |

### FabItem

| Prop | Type | Description |
|------|------|-------------|
| `label` | `string` | Menu item label |
| `icon` | `ReactNode` | Menu item icon |
| `onPress` | `() => void` | Menu item press handler |

## Type Exports

| Type | Description |
|------|-------------|
| `FabProps` | Props for Fab component |
| `FabItem` | Menu item configuration object |
| `FabSize` | `'sm' \| 'md' \| 'lg'` |
| `FabPosition` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` |
| `FabVariant` | `'primary' \| 'secondary' \| 'success' \| 'warning' \| 'destructive'` |

---

# rn-file-attachment-panel
URL: /docs/native/docyrus/file-attachment-panel

File browser and upload panel with thumbnails, file type icons, and delete support.

## Installation

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

## Usage

```tsx
import { FileAttachmentPanel } from '@/components/docyrus-native/file-attachment-panel';

<FileAttachmentPanel
  files={files}
  editable
  maxFiles={10}
  onUploadFile={async (file) => uploadFile(file)}
  onDeleteFile={(id) => deleteFile(id)}
  onFileOpen={(file) => openFile(file)}
/>
```

## API Reference

### FileAttachmentPanelProps

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `files` | `DocyrusFile[]` | - | Array of attached files |
| `editable` | `boolean` | `true` | Enable add and delete file actions |
| `isLoading` | `boolean` | `false` | Show loading state |
| `maxFiles` | `number` | - | Maximum number of files allowed (hides add button when reached) |
| `onUploadFile` | `(file: { uri: string; name: string; type: string }) => Promise<DocyrusFile>` | - | Async callback to upload a file. Consumer handles file picking externally. |
| `onDeleteFile` | `(id: string) => void` | - | Callback when a file is deleted (with confirmation alert) |
| `onFileOpen` | `(file: DocyrusFile) => void` | - | Callback when a file row is tapped |
| `className` | `string` | - | Additional CSS classes |

### DocyrusFile

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `id` | `string` | - | Unique identifier |
| `file_name` | `string` | - | File name (displayed in list) |
| `file_type` | `string` | - | MIME type (used for icon and thumbnail detection) |
| `file_size` | `number` | - | File size in bytes (formatted as B/KB/MB/GB) |
| `signed_url` | `string` | - | Signed URL for file access and image thumbnails |

## Type Exports

| Type | Description |
|------|-------------|
| `FileAttachmentPanelProps` | Props for FileAttachmentPanel component |
| `DocyrusFile` | File data structure |

---

# rn-form-fields
URL: /docs/native/docyrus/form-fields

Dynamic form field system with validation, theming, and 30+ field types for React Native.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-form-fields
```

**Dependencies:**
- [expo-document-picker](https://www.npmjs.com/package/expo-document-picker)
- [@react-native-community/datetimepicker](https://www.npmjs.com/package/@react-native-community/datetimepicker)
- [@react-native-community/geolocation](https://www.npmjs.com/package/@react-native-community/geolocation)
- [react-native-geocoding](https://www.npmjs.com/package/react-native-geocoding)

## Overview

The form fields system provides two core components:

- **DocyFieldBase** — The wrapper component used by all field types. Renders label, help text, error state, and layout according to shared props.
- **DocyFieldDynamic** — Renders any field type dynamically based on a `fieldType` string prop.

## Usage

```tsx
import { DocyFieldText } from '@/components/docyrus-native/form-fields/docy-field-text';
import { DocyFieldDynamic } from '@/components/docyrus-native/form-fields/docy-field-dynamic';

{/* Static usage */}

{/* Dynamic usage */}

```

## Base Props (DocyFieldBaseProps)

All field types inherit these props.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `name` | `string` | — | Field identifier (required) |
| `label` | `string` | — | Label text displayed above or beside the field |
| `placeholder` | `string` | — | Placeholder text when empty |
| `helpText` | `string` | — | Helper text displayed below the field |
| `required` | `boolean` | `false` | Whether the field is required |
| `disabled` | `boolean` | `false` | Disables interaction |
| `readOnly` | `boolean` | `false` | Prevents editing while keeping visual style |
| `hidden` | `boolean` | `false` | Hides the field entirely |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Field size |
| `variant` | `'default' \| 'filled' \| 'outlined'` | `'default'` | Visual variant |
| `labelAlignment` | `'top' \| 'left' \| 'right'` | `'top'` | Label position relative to the field |
| `showLabel` | `boolean` | `true` | Whether to show the label |
| `validations` | `DocyFieldValidationRule[]` | — | Validation rules array |
| `error` | `string` | — | External error message to display |
| `className` | `string` | — | Custom container style |
| `labelClassName` | `string` | — | Custom label text style |
| `errorClassName` | `string` | — | Custom error text style |
| `helpTextClassName` | `string` | — | Custom help text style |

## Value Props (DocyFieldProps\<V\>)

Fields that accept a value extend DocyFieldBaseProps with these additional props.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `V` | — | Current field value |
| `onChange` | `(value: V) => void` | — | Callback when value changes |
| `onBlur` | `() => void` | — | Callback when field loses focus |
| `onFocus` | `() => void` | — | Callback when field receives focus |

---

## Text Input Fields

### DocyFieldText

Single-line text input.

```tsx
import { DocyFieldText } from '@/components/docyrus-native/form-fields/docy-field-text';

```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `string` | — | Current text value |
| `onChange` | `(value: string) => void` | — | Callback when text changes |
| `keyboardType` | `KeyboardTypeOptions` | — | Keyboard type (from React Native TextInput) |
| `maxLength` | `number` | — | Maximum character count |
| `autoCapitalize` | `'none' \| 'sentences' \| 'words' \| 'characters'` | — | Auto-capitalization behavior |
| `autoCorrect` | `boolean` | — | Enable auto-correct |
| `secureTextEntry` | `boolean` | — | Mask input text |
| `multiline` | `boolean` | — | Allow multiple lines |

### DocyFieldTextarea

Multi-line text input with configurable row count.

```tsx
import { DocyFieldTextarea } from '@/components/docyrus-native/form-fields/docy-field-textarea';

```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `string` | — | Current text value |
| `onChange` | `(value: string) => void` | — | Callback when text changes |
| `numberOfLines` | `number` | `4` | Visible line count |
| `maxLength` | `number` | — | Maximum character count |
| `autoCapitalize` | `'none' \| 'sentences' \| 'words' \| 'characters'` | — | Auto-capitalization behavior |

### DocyFieldNumber

Numeric input with optional min/max bounds and precision.

```tsx
import { DocyFieldNumber } from '@/components/docyrus-native/form-fields/docy-field-number';

```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `number` | — | Current numeric value |
| `onChange` | `(value: number) => void` | — | Callback when value changes |
| `min` | `number` | — | Minimum allowed value |
| `max` | `number` | — | Maximum allowed value |
| `step` | `number` | — | Increment/decrement step |
| `precision` | `number` | — | Decimal precision |

### DocyFieldEmail

Email input with email-optimized keyboard. No additional props beyond base — uses `email-address` keyboard type automatically.

```tsx
import { DocyFieldEmail } from '@/components/docyrus-native/form-fields/docy-field-email';

```

### DocyFieldUrl

URL input with URL-optimized keyboard. No additional props beyond base — uses `url` keyboard type automatically.

```tsx
import { DocyFieldUrl } from '@/components/docyrus-native/form-fields/docy-field-url';

```

### DocyFieldPercent

Percentage input with optional precision and bounds.

```tsx
import { DocyFieldPercent } from '@/components/docyrus-native/form-fields/docy-field-percent';

```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `number` | — | Current percentage value |
| `onChange` | `(value: number) => void` | — | Callback when value changes |
| `precision` | `number` | — | Decimal precision |
| `min` | `number` | — | Minimum allowed value |
| `max` | `number` | — | Maximum allowed value |

### DocyFieldPassword

Password input with visibility toggle and optional strength indicator.

```tsx
import { DocyFieldPassword } from '@/components/docyrus-native/form-fields/docy-field-password';

```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `string` | — | Current password value |
| `onChange` | `(value: string) => void` | — | Callback when value changes |
| `showStrength` | `boolean` | `false` | Show password strength indicator bar |
| `minLength` | `number` | `4` | Minimum length for strength calculation. Passwords shorter than this are always rated "weak" |
| `maxLength` | `number` | — | Maximum character count passed to the underlying text input |

---

## Boolean & Misc Fields

### DocyFieldCheckbox

Boolean checkbox field.

```tsx
import { DocyFieldCheckbox } from '@/components/docyrus-native/form-fields/docy-field-checkbox';

```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `boolean` | — | Checked state |
| `onChange` | `(value: boolean) => void` | — | Callback when toggled |

### DocyFieldSwitch

Boolean toggle switch.

```tsx
import { DocyFieldSwitch } from '@/components/docyrus-native/form-fields/docy-field-switch';

```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `boolean` | — | Toggle state |
| `onChange` | `(value: boolean) => void` | — | Callback when toggled |

### DocyFieldRating

Star-based rating input.

```tsx
import { DocyFieldRating } from '@/components/docyrus-native/form-fields/docy-field-rating';

```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `number` | — | Current rating value |
| `onChange` | `(value: number) => void` | — | Callback when rating changes |
| `maxStars` | `number` | `5` | Maximum number of stars |
| `starSize` | `number` | — | Size of each star in pixels |

### DocyFieldDuration

Duration input where the value is stored in seconds.

```tsx
import { DocyFieldDuration } from '@/components/docyrus-native/form-fields/docy-field-duration';

```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `number` | — | Duration in seconds |
| `onChange` | `(value: number) => void` | — | Callback when duration changes |

### DocyFieldPhone

Phone number input.

```tsx
import { DocyFieldPhone } from '@/components/docyrus-native/form-fields/docy-field-phone';

```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `string` | — | Phone number string |
| `onChange` | `(value: string) => void` | — | Callback when value changes |

### DocyFieldColor

Color picker with optional predefined swatches.

```tsx
import { DocyFieldColor } from '@/components/docyrus-native/form-fields/docy-field-color';

```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `string` | — | Hex color string |
| `onChange` | `(value: string) => void` | — | Callback when color changes |
| `swatches` | `string[]` | — | Predefined color swatches to display |

### DocyFieldCurrencyCode

Currency code selector.

```tsx
import { DocyFieldCurrencyCode } from '@/components/docyrus-native/form-fields/docy-field-currency-code';

```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `string` | — | ISO 4217 currency code (e.g. `"USD"`) |
| `onChange` | `(value: string) => void` | — | Callback when currency changes |

---

## Select-Based Fields

### Select Base Props (DocyFieldSelectProps)

All select-based fields share these additional props on top of the base.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `enumOptions` | `EnumOption[]` | — | Array of `{ label, value, color? }` options |
| `searchable` | `boolean` | — | Enable search/filter within options |
| `searchPlaceholder` | `string` | — | Placeholder for search input |
| `onLoadMore` | `() => void` | — | Callback for infinite scroll pagination |
| `hasMore` | `boolean` | — | Whether more items are available to load |
| `onSearch` | `(query: string) => void` | — | Callback for server-side search |
| `searching` | `boolean` | — | Show loading state during search |

### DocyFieldSelect

Single-value dropdown select. Uses `DocyFieldSelectProps<string>`.

```tsx
import { DocyFieldSelect } from '@/components/docyrus-native/form-fields/docy-field-select';

```

### DocyFieldMultiSelect

Multi-value select with chip display. Uses `DocyFieldMultiSelectProps` (`DocyFieldSelectProps<string[]>`).

```tsx
import { DocyFieldMultiSelect } from '@/components/docyrus-native/form-fields/docy-field-multi-select';

```

### DocyFieldTagSelect

Multi-select with tag-style chips and optional create-new support. Extends `DocyFieldMultiSelectProps`.

```tsx
import { DocyFieldTagSelect } from '@/components/docyrus-native/form-fields/docy-field-tag-select';

```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `allowCreate` | `boolean` | — | Allow users to create new tags inline |

### DocyFieldRadioGroup

Single-select rendered as a radio button group. Uses `DocyFieldSelectProps<string>`.

```tsx
import { DocyFieldRadioGroup } from '@/components/docyrus-native/form-fields/docy-field-radio-group';

```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `direction` | `'vertical' \| 'horizontal'` | — | Layout direction of radio items |

### DocyFieldEnum

Enum-styled single select with colored badges. Uses `DocyFieldSelectProps<string>`.

```tsx
import { DocyFieldEnum } from '@/components/docyrus-native/form-fields/docy-field-enum';

```

### DocyFieldStatus

Status selector with colored status badges. Uses `DocyFieldSelectProps<string>`.

```tsx
import { DocyFieldStatus } from '@/components/docyrus-native/form-fields/docy-field-status';

```

### DocyFieldUserSelect

Single user selector with avatar display. Uses `DocyFieldSelectProps<string>`.

```tsx
import { DocyFieldUserSelect } from '@/components/docyrus-native/form-fields/docy-field-user-select';

```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `avatarField` | `string` | — | Key in option data to use as avatar URL |

### DocyFieldUserMultiSelect

Multi-user selector with avatar chips. Uses `DocyFieldMultiSelectProps`.

```tsx
import { DocyFieldUserMultiSelect } from '@/components/docyrus-native/form-fields/docy-field-user-multi-select';

```

### DocyFieldRelation

Relation field linking to another data source. Uses `DocyFieldSelectProps<string>`.

```tsx
import { DocyFieldRelation } from '@/components/docyrus-native/form-fields/docy-field-relation';

```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `dataSourceId` | `string` | — | Identifier for the related data source |

---

## Complex Fields

### DocyFieldDate

> **Requires native module** — Uses `@react-native-community/datetimepicker`. Not available in Expo Go. See [Expo > DocyFieldDate](/docs/native/expo/date).

**Dependencies:**
- [@react-native-community/datetimepicker](https://www.npmjs.com/package/@react-native-community/datetimepicker)

```tsx
import { DocyFieldDate } from '@/components/docyrus-native/form-fields/docy-field-date';

```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `Date \| null` | `null` | Selected date value |
| `onChange` | `(value: Date \| null) => void` | — | Callback when date changes |
| `mode` | `'date' \| 'datetime' \| 'time'` | `'date'` | Picker mode |
| `minimumDate` | `Date` | — | Minimum selectable date |
| `maximumDate` | `Date` | — | Maximum selectable date |
| `dateFormat` | `'short' \| 'medium' \| 'long' \| 'full'` | `'medium'` | Date format preset |
| `timeFormat` | `'12h' \| '24h'` | `'12h'` | Time format |
| `format` | `string` | — | Custom format pattern (e.g. `"dd/MM/yyyy HH:mm"`) |
| `clearable` | `boolean` | `true` | Show clear button when value is set |
| `calendarIcon` | `ReactNode` | — | Custom calendar icon |
| `clearIcon` | `ReactNode` | — | Custom clear icon |
| `iconSize` | `number` | `20` | Icon size |
| `iconColor` | `string` | — | Icon color override |

### DocyFieldDatetime

> **Requires native module** — Uses `@react-native-community/datetimepicker`. Not available in Expo Go. See [Expo > DocyFieldDatetime](/docs/native/expo/datetime).

Combined date and time picker. Wrapper around `DocyFieldDate` with `mode="datetime"`.

```tsx
import { DocyFieldDatetime } from '@/components/docyrus-native/form-fields/docy-field-datetime';

```

Inherits all DocyFieldDate props except `mode` (always `'datetime'`).

### DocyFieldTime

Time-only text input field (HH:mm format).

```tsx
import { DocyFieldTime } from '@/components/docyrus-native/form-fields/docy-field-time';

```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `string` | — | Time string (HH:mm) |
| `onChange` | `(value: string) => void` | — | Callback when time changes |
| `minuteInterval` | `number` | — | Minute step interval |
| `is24Hour` | `boolean` | — | Use 24-hour format |

### DocyFieldDateRange

> **Requires native module** — Uses `@react-native-community/datetimepicker`. Not available in Expo Go. See [Expo > DocyFieldDateRange](/docs/native/expo/date-range).

**Dependencies:**
- [@react-native-community/datetimepicker](https://www.npmjs.com/package/@react-native-community/datetimepicker)

```tsx
import { DocyFieldDateRange } from '@/components/docyrus-native/form-fields/docy-field-date-range';

```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `{ startDate: Date \| null; endDate: Date \| null }` | — | Start and end dates |
| `onChange` | `(value: DocyFieldDateRangeValue) => void` | — | Callback when range changes |
| `minimumDate` | `Date` | — | Minimum selectable date |
| `maximumDate` | `Date` | — | Maximum selectable date |
| `dateFormat` | `'short' \| 'medium' \| 'long' \| 'full'` | `'medium'` | Date format preset |
| `format` | `string` | — | Custom format pattern |
| `separator` | `string` | `' – '` | Separator between start and end dates |
| `clearable` | `boolean` | `true` | Show clear button |
| `allowSameDate` | `boolean` | `true` | Allow same start and end date |
| `calendarIcon` | `ReactNode` | — | Custom calendar icon |
| `clearIcon` | `ReactNode` | — | Custom clear icon |
| `iconSize` | `number` | `20` | Icon size |
| `iconColor` | `string` | — | Icon color override |

### DocyFieldMoney

Currency amount input with a selectable companion currency.

```tsx
import { DocyFieldMoney } from '@/components/docyrus-native/form-fields/docy-field-money';

```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `number` | — | Monetary amount |
| `onChange` | `(value: number) => void` | — | Callback when amount changes |
| `currency` | `string` | `'USD'` | ISO 4217 currency code |
| `onCurrencyChange` | `(currency: string) => void` | — | Enables currency selection and receives the next code |
| `currencyOptions` | `{ code: string; name: string }[]` | `COMMON_CURRENCIES` | Selectable currency list shown in the sheet |

### DocyFieldIcon

Icon picker field.

```tsx
import { DocyFieldIcon } from '@/components/docyrus-native/form-fields/docy-field-icon';

```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `string` | — | Selected icon identifier |
| `onChange` | `(value: string) => void` | — | Callback when icon changes |

### DocyFieldFile

File attachment field.

```tsx
import { DocyFieldFile } from '@/components/docyrus-native/form-fields/docy-field-file';

```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `FileFieldValue` | — | File value object |
| `onChange` | `(value: FileFieldValue) => void` | — | Callback when file changes |
| `accept` | `string[]` | — | Accepted file extensions |
| `maxSize` | `number` | — | Maximum file size in bytes |

### DocyFieldImage

Image picker with optional aspect ratio constraint.

```tsx
import { DocyFieldImage } from '@/components/docyrus-native/form-fields/docy-field-image';

```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `ImageFieldValue` | — | Image value object |
| `onChange` | `(value: ImageFieldValue) => void` | — | Callback when image changes |
| `accept` | `string[]` | — | Accepted image formats |
| `maxSize` | `number` | — | Maximum file size in bytes |
| `aspectRatio` | `number` | — | Enforced aspect ratio for cropping |

### DocyFieldAvatar

Avatar image picker with shape options.

```tsx
import { DocyFieldAvatar } from '@/components/docyrus-native/form-fields/docy-field-avatar';

```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `AvatarFieldValue` | — | Avatar value object |
| `onChange` | `(value: AvatarFieldValue) => void` | — | Callback when avatar changes |
| `shape` | `string` | — | Avatar shape (e.g. `"circle"`, `"square"`) |

### DocyFieldTaskList

Checklist/task list field with interactive items.

```tsx
import { DocyFieldTaskList } from '@/components/docyrus-native/form-fields/docy-field-task-list';

```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `TaskItem[]` | — | Array of task items |
| `onChange` | `(value: TaskItem[]) => void` | — | Callback when tasks change |

### DocyFieldLocationSelect

> **Requires native module** — Uses `@react-native-community/geolocation` + `react-native-geocoding`. Not available in Expo Go. See [Expo > DocyFieldLocationSelect](/docs/native/expo/location-select).

**Dependencies:**
- [@react-native-community/geolocation](https://www.npmjs.com/package/@react-native-community/geolocation)
- [react-native-geocoding](https://www.npmjs.com/package/react-native-geocoding)

Location/address selector with GPS geolocation and reverse geocoding. Uses ActionSheet for picker UI with predefined locations and current location detection.

```tsx
import { DocyFieldLocationSelect } from '@/components/docyrus-native/form-fields/docy-field-location-select';

```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `LocationInfo` | — | Location value object |
| `onChange` | `(value: LocationInfo) => void` | — | Callback when location changes |
| `allowCurrentLocation` | `boolean` | `true` | Show "Use Current Location" option |
| `showCoordinates` | `boolean` | `false` | Display coordinates in the display |
| `predefinedLocations` | `LocationInfo[]` | — | Custom predefined location list |
| `requestLocationPermission` | `() => Promise<boolean>` | — | Custom permission request handler |
| `googleMapsApiKey` | `string` | — | Google Maps API key for reverse geocoding |

### DocyFieldApprovalStatus

Approval workflow status field.

```tsx
import { DocyFieldApprovalStatus } from '@/components/docyrus-native/form-fields/docy-field-approval-status';

```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `string` | — | Current approval status |
| `onChange` | `(value: string) => void` | — | Callback when status changes |

### DocyFieldSlider

Numeric slider input with optional value display.

```tsx
import { DocyFieldSlider } from '@/components/docyrus-native/form-fields/docy-field-slider';

```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `number` | — | Current slider value |
| `onChange` | `(value: number) => void` | — | Callback when value changes |
| `min` | `number` | — | Minimum value |
| `max` | `number` | — | Maximum value |
| `step` | `number` | — | Step increment |
| `showValue` | `boolean` | — | Display current value label |

### DocyFieldUpload

> **Requires Expo module** — Uses `expo-document-picker`. Works in Expo Go. See [Expo > DocyFieldUpload](/docs/native/expo/upload).

**Dependencies:**
- [expo-document-picker](https://www.npmjs.com/package/expo-document-picker)

```tsx
import { DocyFieldUpload } from '@/components/docyrus-native/form-fields/docy-field-upload';

```

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `UploadedFile[]` | `[]` | Array of uploaded files |
| `onChange` | `(value: UploadedFile[]) => void` | — | Callback when files change |
| `maxFiles` | `number` | `10` | Maximum number of files |
| `maxSizeBytes` | `number` | — | Maximum file size in bytes per file |
| `allowedTypes` | `string[]` | `['*/*']` | MIME type filters |
| `onUpload` | `(files: UploadedFile[]) => Promise<void>` | — | Optional upload handler |
| `uploadLabel` | `string` | `'Select files'` | Custom button label |

---

## Components

| Component | Description |
|-----------|-------------|
| `DocyFieldBase` | Shared wrapper rendering label, help text, error, and layout |
| `DocyFieldDynamic` | Dynamic field renderer — resolves `fieldType` to the correct component |

## Type Exports

| Type | Description |
|------|-------------|
| `DocyFieldBaseProps` | Base props shared by all field types |
| `DocyFieldProps<V>` | Value-aware props extending base |
| `DocyFieldSelectProps<V>` | Select-specific props extending value props |
| `DocyFieldMultiSelectProps` | Alias for `DocyFieldSelectProps<string[]>` |
| `DocyFieldValidationRule` | Validation rule definition |
| `EnumOption` | Option item for select-based fields |
| `DocyFieldDateProps` | Props for DocyFieldDate component |
| `DocyFieldDatetimeProps` | Props for DocyFieldDatetime component |
| `DocyFieldDateRangeProps` | Props for DocyFieldDateRange component |
| `DocyFieldDateRangeValue` | Value type for date range (`{ startDate: Date \| null; endDate: Date \| null }`) |
| `FileFieldValue` | Value type for file fields |
| `ImageFieldValue` | Value type for image fields |
| `AvatarFieldValue` | Value type for avatar fields |
| `TaskItem` | Single task item (`{ id, text, completed }`) |
| `LocationInfo` | Location value object (`{ name, address?, coordinates?, country?, city?, region?, postalCode?, type? }`) |
| `UploadedFile` | Uploaded file metadata |

---

# rn-form
URL: /docs/native/docyrus/form

Form-library-agnostic form wrapper that connects DocyField components to any state management library.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-form
```

## Overview

`DocyForm` is a form-library-agnostic wrapper that connects `DocyField*` components to any form state management library via the **adapter pattern**. You implement a `FormAdapter` interface for your chosen library (react-hook-form, TanStack Form, etc.), and `DocyForm` handles the wiring.

## Usage

### With react-hook-form

```tsx
import { DocyForm, DocyFormField } from '@/components/docyrus-native/form';
import { DocyFieldText } from '@/components/docyrus-native/form-fields/docy-field-text';
import { DocyFieldEmail } from '@/components/docyrus-native/form-fields/docy-field-email';

// Create adapter from your form library
const adapter = createReactHookFormAdapter({
  defaultValues: { name: '', email: '' },
  onSubmit: (data) => console.log(data),
});

      

      
    </>
  )}

```

### Compound Fields

For fields that manage multiple form values (e.g. `DocyFieldMoney` needs both amount and currency):

```tsx

```

## API Reference

### DocyForm

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `adapter` | `FormAdapter<T>` | — | **Required.** Form library adapter |
| `children` | `ReactNode \| (methods) => ReactNode` | — | Form content. Render-prop provides `handleSubmit` and `reset` |
| `className` | `string` | — | Container style |

### DocyFormField

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `name` | `string` | — | **Required.** Field name in the form |
| `children` | `ReactElement` | — | **Required.** DocyField component to connect |
| `validations` | `DocyFieldValidationRule[]` | — | Additional validation rules |
| `defaultValue` | `unknown` | — | Default value for this field |
| `compoundFields` | `Record<string, string>` | — | Maps prop names to additional form field names |

### FormAdapter Interface

Implement this interface to plug in your form library:

| Method | Signature | Description |
|--------|-----------|-------------|
| `FormWrapper` | `(props: { children: ReactNode }) => ReactElement` | Wraps children with library-specific provider |
| `getValue` | `(name: string) => unknown` | Get current field value |
| `setValue` | `(name: string, value: unknown) => void` | Set field value programmatically |
| `getError` | `(name: string) => string \| undefined` | Get field error message |
| `getFieldProps` | `(name: string) => FormAdapterFieldProps` | Get props for a field (value, onChange, onBlur, error) |
| `handleSubmit` | `() => void \| Promise<void>` | Run validation and submit |
| `reset` | `(values?: Partial<T>) => void` | Reset form to defaults |
| `getValues` | `() => T` | Get all current form values |

## Hooks

| Hook | Returns | Description |
|------|---------|-------------|
| `useFormAdapter<T>()` | `FormAdapter<T>` | Access the form adapter from within DocyForm |

## Components

| Component | Description |
|-----------|-------------|
| `DocyForm` | Form wrapper with adapter context |
| `DocyFormField` | Connects a DocyField component to the form adapter |

## Type Exports

| Type | Description |
|------|-------------|
| `DocyFormProps` | Props for DocyForm component |
| `DocyFormFieldProps` | Props for DocyFormField component |
| `FormAdapter` | Form library adapter interface |
| `FormAdapterFieldProps` | Field props returned by adapter (`{ name, value, onChange, onBlur, error }`) |

---

# rn-gantt
URL: /docs/native/docyrus/gantt

Gantt chart with timeline visualization, grouped features, drag-to-move, date markers, and zoom control.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-gantt
```

**Dependencies:**
- [react-native-reanimated](https://www.npmjs.com/package/react-native-reanimated)
- [react-native-gesture-handler](https://www.npmjs.com/package/react-native-gesture-handler)

## Usage

```tsx
import { GanttView, type GanttGroup } from '@/components/docyrus-native/gantt';

const groups: GanttGroup[] = [
  {
    id: 'frontend',
    name: 'Frontend',
    features: [
      {
        id: 'f1',
        name: 'Auth Flow',
        startAt: new Date(2026, 2, 1),
        endAt: new Date(2026, 2, 15),
        status: { id: 'done', name: 'Done', color: '#22c55e' }
      }
    ]
  }
];

<GanttView
  groups={groups}
  range="monthly"
  showToday
  onFeaturePress={(feature) => console.log(feature.name)} />
```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `groups` | `GanttGroup[]` | — | Feature groups (required) |
| `range` | `'daily' \| 'monthly' \| 'quarterly'` | `'monthly'` | Timeline range mode |
| `zoom` | `number` | `100` | Zoom level percentage |
| `markers` | `GanttMarkerData[]` | — | Date markers on timeline |
| `onFeatureMove` | `(id: string, startAt: Date, endAt: Date) => void` | — | Feature drag callback |
| `onFeaturePress` | `(feature: GanttFeature) => void` | — | Feature tap callback |
| `onMarkerRemove` | `(id: string) => void` | — | Marker remove callback |
| `readOnly` | `boolean` | `false` | Disable drag interactions |
| `showToday` | `boolean` | `true` | Show today marker |
| `className` | `string` | — | Additional CSS classes |
| `style` | `ViewStyle` | — | Style override |

### GanttGroup

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | Unique group identifier |
| `name` | `string` | Group display name |
| `features` | `GanttFeature[]` | Features in this group |

### GanttFeature

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | Unique feature identifier |
| `name` | `string` | Feature display name |
| `startAt` | `Date` | Start date |
| `endAt` | `Date` | End date |
| `status` | `GanttStatus` | Status with id, name, and color |

### GanttStatus

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | Status identifier |
| `name` | `string` | Status display name |
| `color` | `string` | Status bar color |

### GanttMarkerData

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | Marker identifier |
| `date` | `Date` | Marker date |
| `label` | `string` | Marker label |
| `color` | `string` | Marker color (optional) |

## Components

| Component | Description |
|-----------|-------------|
| `GanttView` | Main Gantt chart component |

## Type Exports

| Type | Description |
|------|-------------|
| `GanttViewProps` | Props for GanttView |
| `GanttGroup` | Group with features |
| `GanttFeature` | Individual timeline feature |
| `GanttStatus` | Feature status definition |
| `GanttMarkerData` | Timeline date marker |
| `GanttRange` | Range mode type |

---

# rn-grid
URL: /docs/native/docyrus/grid

Responsive grid layout with configurable columns, gap control, and spanning grid items.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-grid
```

## Usage

```tsx
import { Grid, GridItem } from '@/components/docyrus-native/grid';

  
  
  

```

## API Reference

### Grid

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode` | — | Grid items |
| `columns` | `number` | `2` | Number of grid columns |
| `gap` | `number` | `0` | Gap size (theme spacing key or pixel value) |
| `columnGap` | `number` | — | Column gap override |
| `rowGap` | `number` | — | Row gap override |
| `alignItems` | `ViewStyle['alignItems']` | — | Cross-axis alignment |
| `justifyContent` | `ViewStyle['justifyContent']` | — | Main-axis alignment |
| `className` | `string` | — | Additional CSS classes |

### GridItem

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode` | — | Item content |
| `span` | `number` | `1` | Number of columns to span |
| `className` | `string` | — | Item CSS classes |

## Type Exports

| Type | Description |
|------|-------------|
| `GridProps` | Props for Grid component |
| `GridItemProps` | Props for GridItem component |

---

# rn-image-editor
URL: /docs/native/docyrus/image-editor

An image editing interface with preview, rotation and crop tools, and save/cancel actions.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-image-editor
```

## Usage

```tsx
import { ImageEditor } from '@/components/docyrus-native/image-editor';

<ImageEditor
  source={{ uri: 'https://example.com/photo.jpg' }}
  onSave={(result) => console.log(result)}
  onCancel={() => console.log('cancelled')}
  onAction={(action) => console.log(action)}
/>
```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `source` | `{ uri: string }` | — | Image source object with a URI string. |
| `onSave` | `(result: ImageEditorResult) => void` | — | Callback fired when the user presses Save. Receives the image result with URI and dimensions. |
| `onCancel` | `() => void` | — | Callback fired when the user presses Cancel. The Cancel button is only rendered when this prop is provided. |
| `onAction` | `(action: ImageEditorAction) => void` | — | Callback fired when a toolbar action is pressed (rotate-left, rotate-right, crop). |
| `aspectRatio` | `number` | — | Aspect ratio for the image preview. Defaults to `16/9` when not provided. |
| `className` | `string` | — | Additional CSS classes |

### ImageEditorResult

| Property | Type | Description |
|----------|------|-------------|
| `uri` | `string` | The URI of the edited image. |
| `width` | `number` | Width of the image in pixels. |
| `height` | `number` | Height of the image in pixels. |

## Type Exports

| Type | Description |
|------|-------------|
| `ImageEditorProps` | Props for the ImageEditor component. |
| `ImageEditorResult` | Result object returned on save (uri, width, height). |
| `ImageEditorAction` | `'rotate-left' \| 'rotate-right' \| 'crop'` — available toolbar actions. |

---

# Overview
URL: /docs/native/docyrus

Docyrus business components for building data-driven mobile applications.

Browse all available Docyrus native business components. These components are purpose-built for Docyrus applications — forms, data tables, record management, scheduling, and more.

## Available Docyrus Components

| Component | Description |
|-----------|-------------|
| [rn-avatar-select](/docs/native/docyrus/avatar-select) | Avatar picker with color palette and emoji tabs, previewing the selected avatar in real time. |
| [rn-avatar-thumbnail](/docs/native/docyrus/avatar-thumbnail) | Avatar display component with image, emoji, or icon text fallback and configurable shape. |
| [rn-awesome-card](/docs/native/docyrus/awesome-card) | Multi-purpose stat card with collapsible body, compound component pattern for flexible layout. |
| [rn-awesome-dialog](/docs/native/docyrus/awesome-dialog) | Compound modal dialog system with header, body, footer, and toolbar sub-components. |
| [rn-awesome-stats](/docs/native/docyrus/awesome-stats) | Statistics display component with horizontal scroll or grid layouts, number formatting, and comparison indicators. |
| [rn-calendar](/docs/native/docyrus/calendar) | Full-featured calendar with month, week, day, and agenda views with event display. |
| [rn-chart](/docs/native/docyrus/chart) | SVG chart library with 13 chart types (line, bar, area, pie, radar, scatter, candlestick, gauge, funnel, heatmap, treemap, sparkline, combo). |
| [rn-checkin](/docs/native/docyrus/checkin) | Location-based check-in/check-out system with timer, option selection, and check-out form. |
| [rn-comments-panel](/docs/native/docyrus/comments-panel) | Threaded comments panel with replies, editing, deletion, and attachments. |
| [rn-contact-activity-panel](/docs/native/docyrus/contact-activity-panel) | A timeline panel for displaying and adding contact activities with type-specific icons, user badges, and an inline add form. |
| [rn-create-record-dialog](/docs/native/docyrus/create-record-dialog) | A bottom-sheet dialog for creating new records with configurable selector fields, toggles, subject, and description inputs. |
| [rn-data-grid](/docs/native/docyrus/data-grid) | Spreadsheet-like data grid with inline cell editing, sorting, filtering, gallery mode, and bulk actions. |
| [rn-data-grid-view-select](/docs/native/docyrus/data-grid-view-select) | A view selector component for data grids with tabs and dropdown variants, supporting view creation, deletion, and renaming. |
| [rn-data-table](/docs/native/docyrus/data-table) | Full-featured data table with sorting, filtering, pagination, grouping, and pinning. |
| [rn-data-table-filter](/docs/native/docyrus/data-table-filter) | Filter builder for data tables with column selection, operator matching, and filter pills. |
| [rn-delete-confirm-dialog](/docs/native/docyrus/delete-confirm-dialog) | Modal confirmation dialog for delete operations with customizable title, description, and pending state. |
| [rn-editable-record-detail](/docs/native/docyrus/editable-record-detail) | An inline-editable record detail view that tracks field changes and supports custom renderers for both display and edit modes. |
| [rn-editable-value](/docs/native/docyrus/editable-value) | Inline editable text field with view/edit mode toggle and optional save/cancel actions. |
| [rn-file-attachment-panel](/docs/native/docyrus/file-attachment-panel) | File browser and upload panel with thumbnails, file type icons, and delete support. |
| [rn-form](/docs/native/docyrus/form) | Form-library-agnostic form wrapper that connects DocyField components to any state management library. |
| [rn-gantt](/docs/native/docyrus/gantt) | Gantt chart with timeline visualization, grouped features, drag-to-move, date markers, and zoom control. |
| [rn-form-fields](/docs/native/docyrus/form-fields) | Dynamic form field system with validation, theming, and 30+ field types for React Native. |
| [rn-image-editor](/docs/native/docyrus/image-editor) | An image editing interface with preview, rotation and crop tools, and save/cancel actions. |
| [rn-kanban](/docs/native/docyrus/kanban) | Horizontally scrollable kanban board with columns, cards, priorities and tags. |
| [rn-list-box](/docs/native/docyrus/list-box) | Grid-capable list component with client/server pagination and infinite scroll support. |
| [rn-list-view](/docs/native/docyrus/list-view) | Feature-rich list with search, filters, sorting, list/grid display toggle, and pagination. |
| [rn-log-activity-form](/docs/native/docyrus/log-activity-form) | A form component for logging various activity types with type-specific fields for calls, emails, meetings, tasks, status updates, and comments. |
| [rn-map](/docs/native/docyrus/map) | A map component powered by react-native-maps with marker support and graceful fallback. |
| [rn-mega-select](/docs/native/docyrus/mega-select) | Large-scale searchable select with categories, images, and double-tap to choose. |
| [rn-notifications-panel](/docs/native/docyrus/notifications-panel) | Notification list panel with tabs, per-item actions, and customizable header and footer. |
| [rn-pivot-grid](/docs/native/docyrus/pivot-grid) | A pivot table component that cross-tabulates data by row and column fields with aggregation and totals. |
| [rn-place-autocomplete](/docs/native/docyrus/place-autocomplete) | A location search input with autocomplete suggestions powered by the Photon geocoding API. |
| [rn-pricing-engine-panel](/docs/native/docyrus/pricing-engine-panel) | A pricing calculator panel with editable line items, automatic totals calculation, VAT, and discount support. |
| [rn-query-builder](/docs/native/docyrus/query-builder) | A visual query builder with nestable groups, combinators, field/operator pickers, and value inputs. |
| [rn-rate-limit-banner](/docs/native/docyrus/rate-limit-banner) | Rate limit notification with banner, modal, and toast modes, countdown timer, and retry/reload actions. |
| [rn-rating](/docs/native/docyrus/rating) | Star rating input with customizable max stars, half-star support, and size variants. |
| [rn-record-activity-panel](/docs/native/docyrus/record-activity-panel) | A timeline-style panel that displays record activity history with color-coded operations and actor information. |
| [rn-record-delete-confirm-dialog](/docs/native/docyrus/record-delete-confirm-dialog) | Delete confirmation dialog with cascade relation management for related data. |
| [rn-record-sharing](/docs/native/docyrus/record-sharing) | Share panel with search, permission management, and entity list. |
| [rn-resource-scheduler-panel](/docs/native/docyrus/resource-scheduler-panel) | A horizontal timeline scheduler that displays events across multiple resources in a day view. |
| [rn-schema-repeater](/docs/native/docyrus/schema-repeater) | A generic repeater component for managing dynamic lists of items with reordering, adding, and removing capabilities. |
| [rn-time-slot-scheduler](/docs/native/docyrus/time-slot-scheduler) | A grid-based time slot scheduler for selecting available slots across multiple days. |
| [rn-value-renderers](/docs/native/docyrus/value-renderers) | Read-only display components for rendering field values by type. |

---

# rn-kanban
URL: /docs/native/docyrus/kanban

Horizontally scrollable kanban board with columns, cards, priorities and tags.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-kanban
```

**Dependencies:**
- [react-native-gesture-handler](https://www.npmjs.com/package/react-native-gesture-handler)
- [react-native-reanimated](https://www.npmjs.com/package/react-native-reanimated)

## Usage

```tsx
import { DocyKanban, type DocyKanbanColumn, type DocyKanbanItem } from '@/components/docyrus-native/kanban';

const columns: DocyKanbanColumn[] = [
  { id: 'todo', title: 'To Do', color: '#6366f1' },
  { id: 'progress', title: 'In Progress', color: '#f59e0b' },
  { id: 'review', title: 'Review', color: '#8b5cf6' },
];

const items: DocyKanbanItem[] = [
  { id: 1, title: 'Setup CI', columnId: 'todo', priority: 'high', tag: 'DevOps' },
  { id: 2, title: 'Auth flow', columnId: 'progress', priority: 'medium', assignee: 'John' },
];

// Static board

// With drag-and-drop + Done/Archive sections
<DocyKanban
  columns={columns}
  items={items}
  draggable
  showDoneSection
  showArchiveSection
  onMoveCard={(item, from, to) => console.log(`Moved ${item.title} from ${from} to ${to}`)}
/>
```

## API Reference

### DocyKanban

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `columns` | `DocyKanbanColumn[]` | — | Column definitions |
| `items` | `DocyKanbanItem[]` | — | Card items |
| `columnOrder` | `string[]` | — | Custom column ordering by ID |
| `variant` | `'default' \| 'outlined' \| 'elevated'` | `'default'` | Visual style |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Column width and card padding |
| `showCounts` | `boolean` | `true` | Show item count in column headers |
| `showDoneSection` | `boolean` | `false` | Show Done drop zone below columns |
| `showArchiveSection` | `boolean` | `false` | Show Archive drop zone below columns |
| `draggable` | `boolean` | `false` | Enable drag-and-drop to move cards between columns |
| `onCardPress` | `(item: DocyKanbanItem) => void` | — | Card press callback |
| `onAddCard` | `(columnId: string) => void` | — | Add card button callback (shows button when set) |
| `onMoveCard` | `(item: DocyKanbanItem, fromColumnId: string, toColumnId: string) => void` | — | Card move handler for controlled drag mode |
| `renderCard` | `(item: DocyKanbanItem, index: number) => ReactNode` | — | Custom card renderer |
| `renderColumnHeader` | `(column: DocyKanbanColumn, count: number) => ReactNode` | — | Custom column header renderer |

### DocyKanbanColumn

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | Unique column identifier |
| `title` | `string` | Column display title |
| `color` | `string` | Accent color for column header dot and count badge |

### DocyKanbanItem

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string \| number` | Unique item identifier |
| `title` | `string` | Card title |
| `description` | `string` | Card description (max 2 lines) |
| `columnId` | `string` | Column to place card in |
| `tag` | `string` | Tag label |
| `priority` | `'low' \| 'medium' \| 'high'` | Priority level (color-coded) |
| `assignee` | `string` | Assignee name |
| `dueDate` | `Date \| string` | Due date |
| `done` | `boolean` | Mark item as done (moves to Done section when `showDoneSection` is true) |
| `archived` | `boolean` | Mark item as archived (moves to Archive section when `showArchiveSection` is true) |

## Components

| Component | Description |
|-----------|-------------|
| `DocyKanban` | Main kanban board with horizontal scrolling columns |

## Type Exports

| Type | Description |
|------|-------------|
| `DocyKanbanProps` | Props for DocyKanban component |
| `DocyKanbanColumn` | Column definition type |
| `DocyKanbanItem` | Card item type |

---

# rn-list-box
URL: /docs/native/docyrus/list-box

Grid-capable list component with client/server pagination and infinite scroll support.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-list-box
```

## Usage

```tsx
import { ListBox } from '@/components/docyrus-native/list-box';

const items = [
  { id: '1', name: 'Item 1' },
  { id: '2', name: 'Item 2' },
];

}
/>
```

### Grid Layout

```tsx
}
  columns={2}
  gap={12}
/>
```

### Client-Side Pagination

```tsx
}
  pageSize={10}
/>
```

### Server-Side Pagination

```tsx
}
  serverPagination
  totalItems={100}
  currentPage={page}
  onPageChange={setPage}
  pageSize={10}
/>
```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `T[]` | — | Array of items to display |
| `renderItem` | `(item: T, index: number) => ReactNode` | — | Render function for each item |
| `keyExtractor` | `(item: T, index: number) => string` | — | Function to extract unique key per item |
| `columns` | `1 \| 2 \| 3` | `1` | Number of columns in the grid |
| `gap` | `number` | `8` | Gap between items in pixels |
| `pageSize` | `number` | — | Items per page (enables pagination) |
| `serverPagination` | `boolean` | `false` | Use server-controlled pagination |
| `totalItems` | `number` | — | Total item count for server pagination |
| `currentPage` | `number` | `1` | Current page for server pagination |
| `onPageChange` | `(page: number) => void` | — | Page change callback for server pagination |
| `onEndReached` | `() => void` | — | Infinite scroll callback when reaching end |
| `loading` | `boolean` | `false` | Show loading indicator in footer |
| `emptyMessage` | `string` | `'No items to display'` | Message when list is empty |
| `emptyIcon` | `string` | — | Emoji displayed above empty message |
| `className` | `string` | — | FlatList CSS classes |
| `contentContainerClassName` | `string` | — | Content area CSS classes |

## Type Exports

| Type | Description |
|------|-------------|
| `ListBoxProps<T>` | Props for ListBox component |
| `ListBoxColumns` | `1 \| 2 \| 3` |

---

# rn-list-view
URL: /docs/native/docyrus/list-view

Feature-rich list with search, filters, sorting, list/grid display toggle, and pagination.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-list-view
```

## Usage

```tsx
import { ListView } from '@/components/docyrus-native/list-view';

type Contact = { id: string; name: string; email: string };

const contacts: Contact[] = [
  { id: '1', name: 'Alice', email: 'alice@example.com' },
  { id: '2', name: 'Bob', email: 'bob@example.com' },
];

}
  searchKeys={['name', 'email']}
/>
```

### With Filters and Sort

```tsx
}
  searchKeys={['name']}
  filters={[
    { key: 'active', label: 'Active' },
    { key: 'inactive', label: 'Inactive' },
  ]}
  filterFn={(item, filter) => item.status === filter}
  sortOptions={[
    { key: 'name', label: 'Name', compareFn: (a, b) => a.name.localeCompare(b.name) },
    { key: 'email', label: 'Email', compareFn: (a, b) => a.email.localeCompare(b.email) },
  ]}
/>
```

### List/Grid Toggle

```tsx
<ListView
  data={items}
  keyExtractor={(item) => item.id}
  renderItem={(item) => }
  renderGridItem={(item) => }
  showDisplayToggle
  gridColumns={2}
/>
```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `T[]` | — | Array of items to display |
| `renderItem` | `(item: T, index: number) => ReactNode` | — | Render function for list mode |
| `renderGridItem` | `(item: T, index: number) => ReactNode` | — | Render function for grid mode |
| `keyExtractor` | `(item: T, index: number) => string` | — | Function to extract unique key per item |
| `searchKeys` | `(keyof T)[]` | — | Object keys to search against |
| `filterFn` | `(item: T, activeFilter: string \| null) => boolean` | — | Custom filter function |
| `filters` | `ListViewFilterOption[]` | — | Filter chip options |
| `sortOptions` | `ListViewSortOption<T>[]` | — | Sort dropdown options |
| `defaultSort` | `string` | — | Default active sort key |
| `defaultDisplayMode` | `'list' \| 'grid'` | `'list'` | Initial display mode |
| `showSearch` | `boolean` | `true` | Show search input |
| `showDisplayToggle` | `boolean` | `false` | Show list/grid toggle button |
| `gridColumns` | `2 \| 3` | `2` | Number of columns in grid mode |
| `pageSize` | `number` | — | Items per page (enables pagination) |
| `emptyMessage` | `string` | `'No items found'` | Empty state message |
| `emptyIcon` | `string` | — | Emoji displayed above empty message |
| `searchPlaceholder` | `string` | `'Search...'` | Custom search input placeholder |
| `title` | `string` | — | Header title text |
| `headerRight` | `ReactNode` | — | Custom content on the right side of the header |
| `className` | `string` | — | Additional CSS classes |

### ListViewFilterOption

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `key` | `string` | — | Unique filter identifier |
| `label` | `string` | — | Display label for the filter chip |
| `icon` | `string` | — | Emoji icon shown before label |

### ListViewSortOption\<T\>

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `key` | `string` | — | Unique sort identifier |
| `label` | `string` | — | Display label in sort dropdown |
| `compareFn` | `(a: T, b: T) => number` | — | Comparison function for sorting |

## Type Exports

| Type | Description |
|------|-------------|
| `ListViewProps<T>` | Props for ListView component |
| `ListViewDisplayMode` | `'list' \| 'grid'` |
| `ListViewSortOption<T>` | Sort option configuration |
| `ListViewFilterOption` | Filter option configuration |

---

# rn-log-activity-form
URL: /docs/native/docyrus/log-activity-form

A form component for logging various activity types with type-specific fields for calls, emails, meetings, tasks, status updates, and comments.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-log-activity-form
```

## Usage

```tsx
import { LogActivityForm } from '@/components/docyrus-native/log-activity-form';

<LogActivityForm
  onSubmit={(payload) => console.log(payload)}
  placeholder="Write something..."
/>
```

## API Reference

### LogActivityFormProps

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `activityType` | `LoggableActivityType` | — | Controlled activity type. Overrides internal state when provided |
| `defaultActivityType` | `LoggableActivityType` | `'comment'` | Initial activity type for uncontrolled usage |
| `onTypeChange` | `(type: LoggableActivityType) => void` | — | Called when the activity type changes |
| `onSubmit` | `(payload: LogActivityPayload) => void \| Promise<void>` | — | Called when the form is submitted |
| `isSubmitting` | `boolean` | `false` | Shows a loading indicator and disables submit |
| `placeholder` | `string` | `'Write something...'` | Placeholder text for the body input |
| `submitLabel` | `string` | `'Submit'` | Label text for the submit button |
| `disabled` | `boolean` | `false` | Disables all form interactions |
| `statusOptions` | `StatusOption[]` | `[]` | Options shown when activity type is `status_update` |
| `className` | `string` | — | Additional CSS classes |

### LoggableActivityType

```ts
type LoggableActivityType = 'call' | 'email' | 'meeting' | 'task' | 'status_update' | 'comment';
```

### LogActivityPayload

| Field | Type | Description |
|-------|------|-------------|
| `type` | `LoggableActivityType` | The selected activity type |
| `body` | `string` | Main text content of the activity |
| `subject` | `string` | Subject line (email, meeting, task) |
| `to` | `string[]` | Recipient emails (email type) |
| `cc` | `string[]` | CC recipients (email type) |
| `bcc` | `string[]` | BCC recipients (email type) |
| `eventSubject` | `string` | Meeting event subject |
| `startDate` | `Date` | Event start date |
| `endDate` | `Date` | Event end date |
| `taskSubject` | `string` | Task subject |
| `statusId` | `string` | Selected status ID (status_update type) |
| `statusDescription` | `string` | Status description |
| `followupDate` | `Date \| null` | Optional follow-up date |

### StatusOption

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | Unique identifier for the status |
| `label` | `string` | Display label for the status |
| `color` | `string` | Optional color for the status chip |

## Type Exports

| Type | Description |
|------|-------------|
| `LogActivityFormProps` | Props for LogActivityForm component |
| `LoggableActivityType` | Union of supported activity types |
| `LogActivityPayload` | Payload object returned on form submit |
| `StatusOption` | Status option configuration |

---

# rn-map
URL: /docs/native/docyrus/map

A map component powered by react-native-maps with marker support and graceful fallback.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-map
```

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

## Usage

```tsx
import { Map } from '@/components/docyrus-native/map';

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `latitude` | `number` | `0` | Center latitude of the map. |
| `longitude` | `number` | `0` | Center longitude of the map. |
| `zoom` | `number` | `10` | Zoom level of the map. Higher values zoom in closer. |
| `markers` | `MapMarker[]` | `[]` | Array of markers to display on the map. |
| `onMarkerPress` | `(index: number) => void` | — | Callback fired when a marker is pressed, receiving the marker index. |
| `className` | `string` | — | Custom styles applied to the map container. |

### MapMarker

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `latitude` | `number` | — | Latitude coordinate of the marker. |
| `longitude` | `number` | — | Longitude coordinate of the marker. |
| `title` | `string` | — | Title displayed in the marker callout. |
| `description` | `string` | — | Description displayed in the marker callout. |

## Type Exports

| Type | Description |
|------|-------------|
| `MapProps` | Props for the Map component. |
| `MapMarker` | Shape of a marker object (latitude, longitude, title, description). |

---

# rn-mega-select
URL: /docs/native/docyrus/mega-select

Large-scale searchable select with categories, images, and double-tap to choose.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-mega-select
```

## Usage

```tsx
import { MegaSelect } from '@/components/docyrus-native/mega-select';

<MegaSelect
  items={[
    { id: '1', label: 'Option A', description: 'First option' },
    { id: '2', label: 'Option B', description: 'Second option' },
  ]}
  value={selectedId}
  onSelectionChange={(value) => setSelectedId(value)}
  onChoose={(value) => handleChoose(value)}
/>
```

## API Reference

### MegaSelectProps

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `items` | `MegaSelectItem<T>[]` | - | Array of selectable items |
| `categories` | `MegaSelectCategory[]` | - | Category tabs for filtering items |
| `value` | `string \| null` | - | Currently selected item ID |
| `onSelectionChange` | `(value: string \| null, item?: MegaSelectItem<T>) => void` | - | Callback on single-tap selection |
| `onChoose` | `(value: string, item?: MegaSelectItem<T>) => void` | - | Callback on double-tap or "Choose" button press |
| `searchable` | `boolean` | `true` | Enable search input in the sheet |
| `placeholder` | `string` | `'Select an item...'` | Trigger button placeholder text |
| `className` | `string` | - | Additional styles for the trigger button |

### MegaSelectItem\<T\>

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `id` | `string` | - | Unique identifier |
| `label` | `string` | - | Display text |
| `description` | `string` | - | Secondary description text |
| `icon` | `ReactNode` | - | Custom icon element |
| `image` | `string` | - | Image URL for thumbnail |
| `color` | `string` | - | Color for icon background or letter avatar |
| `content` | `ReactNode` | - | Custom content replacing label/description |
| `data` | `T` | - | Arbitrary data attached to the item |

### MegaSelectCategory

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `id` | `string` | - | Category identifier (matched against `item.data.category`) |
| `label` | `string` | - | Category tab label |
| `icon` | `ReactNode` | - | Icon element for the category tab |

## Type Exports

| Type | Description |
|------|-------------|
| `MegaSelectProps<T>` | Props for MegaSelect component |
| `MegaSelectItem<T>` | Selectable item configuration |
| `MegaSelectCategory` | Category tab configuration |

---

# rn-mini-calendar
URL: /docs/native/docyrus/mini-calendar

Compact date picker calendar with month navigation and locale-aware day names.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-mini-calendar
```

### Expo Configuration

`react-native-localize` requires plugin configuration in your `app.config.ts`:

```ts
{
  plugins: [
    [
      'react-native-localize',
      { locales: ['en', 'tr'] } // list your supported locales
    ]
  ]
}
```

## Usage

```tsx
import { MiniCalendar } from '@/components/docyrus-native/mini-calendar';

const [date, setDate] = useState<Date | undefined>();

```

### Marked Dates (Dot Indicators)

Show dot indicators on dates that have events, tasks, or other data:

```tsx
const taskDates = [
  new Date(2026, 2, 3),
  new Date(2026, 2, 7),
  new Date(2026, 2, 15),
  new Date(2026, 2, 20),
];

{/* Custom dot color */}

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `Date` | — | Currently selected date |
| `onChange` | `(date: Date) => void` | — | Callback when a date is selected |
| `minDate` | `Date` | — | Minimum selectable date |
| `maxDate` | `Date` | — | Maximum selectable date |
| `disabled` | `boolean` | `false` | Disable all interactions |
| `firstDayOfWeek` | `0 \| 1` | `1` | First day of the week (0 = Sunday, 1 = Monday) |
| `markedDates` | `Date[]` | — | Dates to show dot indicators on |
| `markedDotColor` | `string` | theme primary | Custom color for dot indicators |
| `className` | `string` | — | Additional CSS classes |

## Features

- **Locale-aware**: Day names and month names automatically adapt to the device locale via `Intl.DateTimeFormat`
- **Today button**: Quick-navigate to the current date
- **Date range constraints**: Supports `minDate` and `maxDate` to restrict selectable dates
- **Today highlight**: Current date is highlighted with a border ring
- **Month navigation**: Previous/next month navigation arrows
- **Marked dates**: Show dot indicators on specific dates (e.g. dates with tasks/events). Uses O(1) Set lookup for performance

## Type Exports

| Type | Description |
|------|-------------|
| `MiniCalendarProps` | Props for MiniCalendar component |

---

# rn-network-banner
URL: /docs/native/docyrus/network-banner

Animated banner for displaying network connectivity status with retry and dismiss actions.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-network-banner
```

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

## Usage

```tsx
import { NetworkBanner } from '@/components/docyrus-native/network-banner';

<NetworkBanner
  visible={!isOnline}
  variant="offline"
  onRetry={() => checkConnection()}
  onDismiss={() => setDismissed(true)}
/>
```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `visible` | `boolean` | — | Whether the banner is visible |
| `variant` | `'offline' \| 'slow' \| 'reconnecting'` | `'offline'` | Network status variant |
| `message` | `string` | — | Custom message (overrides variant default) |
| `onRetry` | `() => void` | — | Retry button handler (shows button when provided) |
| `retryLabel` | `string` | `'Retry'` | Retry button text |
| `onDismiss` | `() => void` | — | Dismiss button handler (shows X when provided) |
| `position` | `'top' \| 'bottom'` | `'top'` | Banner position on screen |
| `className` | `string` | — | Additional CSS classes |

## Type Exports

| Type | Description |
|------|-------------|
| `NetworkBannerProps` | Props for NetworkBanner component |
| `NetworkBannerVariant` | `'offline' \| 'slow' \| 'reconnecting'` |

---

# rn-notification-stack
URL: /docs/native/docyrus/notification-stack

Stacked notification cards with dismiss, load more, and action buttons.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-notification-stack
```

## Usage

```tsx
import { NotificationStack } from '@/components/docyrus-native/notification-stack';

<NotificationStack
  notifications={notifications}
  maxVisible={10}
  onDismiss={(id) => console.log('dismissed', id)}
  onClick={(id) => console.log('clicked', id)}
/>
```

## API Reference

### NotificationStackProps

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `notifications` | `NotificationItem[]` | - | Array of notification items to display |
| `maxVisible` | `number` | `10` | Maximum number of visible notifications |
| `loadMoreThreshold` | `number` | `2` | Number of remaining items before triggering load more |
| `onLoadMore` | `() => void` | - | Callback when more notifications should be loaded |
| `onDismiss` | `(id: string) => void` | - | Callback when a notification is dismissed |
| `onClick` | `(id: string) => void` | - | Callback when a notification is tapped |
| `onAction` | `(id: string, action: string) => void` | - | Callback when a notification action button is pressed |
| `variant` | `'default' \| 'bordered'` | `'default'` | Visual variant. `bordered` adds shadow and elevation |
| `size` | `'sm' \| 'default' \| 'lg'` | `'default'` | Controls text size, icon size, and padding |
| `emptyState` | `ReactNode` | - | Custom empty state content |
| `className` | `string` | - | Additional CSS classes |

### NotificationItem

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `id` | `string` | - | Unique identifier |
| `type` | `NotificationType` | - | Notification type: `'comment' \| 'approval' \| 'status' \| 'info' \| 'success' \| 'warning' \| 'error'` |
| `variant` | `'default' \| 'unread' \| 'highlighted'` | `'default'` | Visual variant affecting background color |
| `icon` | `ReactNode` | - | Custom icon element |
| `title` | `string` | - | Notification title text |
| `subtitle` | `string` | - | Secondary text below the title |
| `content` | `string` | - | Additional content text |
| `timestamp` | `string` | - | Timestamp display text |
| `showUnreadIndicator` | `boolean` | - | Shows an orange dot indicator |
| `actions` | `NotificationAction[]` | - | Array of action buttons |

### NotificationAction

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `label` | `string` | - | Button label text |
| `variant` | `'default' \| 'primary' \| 'danger'` | `'default'` | Button color variant |
| `onClick` | `() => void` | - | Button press callback |

## Type Exports

| Type | Description |
|------|-------------|
| `NotificationStackProps` | Props for NotificationStack component |
| `NotificationStackVariant` | `'default' \| 'bordered'` |
| `NotificationStackSize` | `'sm' \| 'default' \| 'lg'` |

---

# rn-notifications-panel
URL: /docs/native/docyrus/notifications-panel

Notification list panel with tabs, per-item actions, and customizable header and footer.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-notifications-panel
```

## Usage

```tsx
import { NotificationsPanel } from '@/components/docyrus-native/notifications-panel';
import type { NotificationItem } from '@/components/docyrus-native/notifications-panel';

const notifications: NotificationItem[] = [
  {
    id: '1',
    type: 'comment',
    title: 'New comment on your post',
    subtitle: 'John left a comment',
    timestamp: '2m ago',
  },
  {
    id: '2',
    type: 'approval',
    variant: 'unread',
    title: 'Approval requested',
    content: 'Please review the Q4 budget proposal.',
    showUnreadIndicator: true,
    actions: [
      { label: 'Approve', variant: 'primary' },
      { label: 'Reject', variant: 'danger' },
    ],
  },
];

<NotificationsPanel
  notifications={notifications}
  onNotificationAction={(id, action) => console.log(id, action)}
/>
```

### With Tabs

```tsx
<NotificationsPanel
  tabs={[
    { label: 'All', count: 12, active: true, onPress: () => setTab('all') },
    { label: 'Unread', count: 3, onPress: () => setTab('unread') },
  ]}
  notifications={notifications}
/>
```

### Bordered Variant

```tsx

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `title` | `string` | `'Notifications'` | Header title text. |
| `headerAction` | `ReactNode` | — | Custom element rendered in the header beside the title. |
| `tabs` | `NotificationTab[]` | — | Array of tab definitions for filtering notifications. |
| `notifications` | `NotificationItem[]` | — | Array of notification items to render. |
| `footer` | `ReactNode` | — | Custom element rendered in the panel footer. |
| `onNotificationAction` | `(notificationId: string, action: string) => void` | — | Callback when a notification action button is pressed. |
| `variant` | `'default' \| 'bordered'` | `'default'` | Visual variant. `'bordered'` adds shadow and elevation. |
| `size` | `'sm' \| 'default' \| 'lg'` | `'default'` | Controls font sizes, icon size, and padding. |
| `className` | `string` | — | Additional CSS classes |

### NotificationItem

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `id` | `string` | — | Unique identifier for the notification. |
| `type` | `NotificationType` | — | Notification type, determines icon color. |
| `variant` | `'default' \| 'unread' \| 'highlighted'` | `'default'` | Row background variant. |
| `icon` | `ReactNode` | — | Custom icon element. Falls back to a letter badge based on `type`. |
| `title` | `string` | — | Primary notification text. |
| `subtitle` | `string` | — | Secondary text below the title. |
| `content` | `string` | — | Additional content text. |
| `timestamp` | `string` | — | Timestamp label displayed on the right side. |
| `showUnreadIndicator` | `boolean` | — | When true, shows an orange dot indicator. |
| `actions` | `NotificationAction[]` | — | Action buttons rendered below the content. |

### NotificationAction

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `label` | `string` | — | Button label text. |
| `variant` | `'default' \| 'primary' \| 'danger'` | `'default'` | Button color variant. |
| `onClick` | `() => void` | — | Callback when the action button is pressed. |

### NotificationTab

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `label` | `string` | — | Tab label text. |
| `count` | `number` | — | Optional count badge displayed next to the label. |
| `active` | `boolean` | — | When true, the tab is visually highlighted. |
| `onPress` | `() => void` | — | Callback when the tab is pressed. |

## Type Exports

| Type | Description |
|------|-------------|
| `NotificationsPanelProps` | Props for the NotificationsPanel component. |
| `NotificationItem` | Notification item data shape. |
| `NotificationType` | Notification type: `'comment' \| 'approval' \| 'status' \| 'info' \| 'success' \| 'warning' \| 'error'`. |
| `NotificationItemVariant` | Row variant: `'default' \| 'unread' \| 'highlighted'`. |
| `NotificationAction` | Action button definition. |
| `NotificationTab` | Tab definition. |
| `NotificationsPanelSize` | Size variant: `'sm' \| 'default' \| 'lg'`. |
| `NotificationsPanelVariant` | Panel variant: `'default' \| 'bordered'`. |

---

# rn-phone-input
URL: /docs/native/docyrus/phone-input

Phone number input with country code picker and search.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-phone-input
```

## Usage

```tsx
import { PhoneInput } from '@/components/docyrus-native/phone-input';

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `string` | `''` | Phone number |
| `onValueChange` | `(value: string) => void` | — | Value change handler |
| `countryCode` | `string` | `'US'` | Selected country code |
| `onCountryCodeChange` | `(code: string) => void` | — | Country change handler |
| `countries` | `CountryCode[]` | 15 defaults | Country list |
| `placeholder` | `string` | `'Phone number'` | Placeholder text |
| `disabled` | `boolean` | `false` | Disable interaction |
| `invalid` | `boolean` | `false` | Show invalid state |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Input size |
| `className` | `string` | — | Additional CSS classes |
| `inputClassName` | `string` | — | TextInput CSS classes |
| `accessibilityLabel` | `string` | — | Accessibility label |

### CountryCode

| Property | Type | Description |
|----------|------|-------------|
| `code` | `string` | ISO country code (e.g. `'US'`) |
| `dialCode` | `string` | Dial code (e.g. `'+1'`) |
| `flag` | `string` | Flag emoji |
| `name` | `string` | Country name |

## Type Exports

| Type | Description |
|------|-------------|
| `PhoneInputProps` | Props for PhoneInput component |
| `PhoneInputSize` | `'sm' \| 'md' \| 'lg'` |
| `CountryCode` | Country code entry type |

---

# rn-pivot-grid
URL: /docs/native/docyrus/pivot-grid

Full-featured cross-tabulation pivot grid with multi-dimension rows/columns, aggregation, conditional cell coloring, row/column expand-collapse, drilldown action sheet, toolbar, and CSV export.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-pivot-grid
```

**Dependencies:**
- [jsonata](https://www.npmjs.com/package/jsonata)
- [expo-file-system](https://www.npmjs.com/package/expo-file-system)
- [expo-sharing](https://www.npmjs.com/package/expo-sharing)

## Usage

```tsx
import {
  PivotGrid,
  PivotGridToolbar,
  PivotGridDrilldownModal,
  usePivotGrid,
  type PivotGridDimension,
  type PivotGridMeasure,
} from '@/components/docyrus-native/pivot-grid';

interface SalesRow {
  region: string;
  product: string;
  revenue: number;
}

const data: SalesRow[] = [
  { region: 'North', product: 'Widget A', revenue: 1200 },
  { region: 'North', product: 'Widget B', revenue: 850 },
  { region: 'South', product: 'Widget A', revenue: 960 },
  { region: 'South', product: 'Widget B', revenue: 1100 },
];

const rowDimensions: PivotGridDimension<SalesRow>[] = [
  { id: 'region', label: 'Region', getValue: (row) => row.region },
];

const columnDimensions: PivotGridDimension<SalesRow>[] = [
  { id: 'product', label: 'Product', getValue: (row) => row.product },
];

const measures: PivotGridMeasure<SalesRow>[] = [
  {
    id: 'revenue',
    label: 'Revenue',
    getValue: (row) => row.revenue,
    aggregate: 'sum',
    formatValue: (v) => `$${v.toLocaleString()}`,
  },
];

function SalesPivot() {
  const controller = usePivotGrid({
    data,
    rowDimensions,
    columnDimensions,
    measures,
    height: 400,
  });

  return (
    <>
      
      
      
    </>
  );
}
```

## Features

- **Multi-dimension pivoting** — 1-3 row/column dimensions with nested grouping
- **Aggregation** — sum, count, avg, min, max
- **Expand/collapse** — toggle individual rows/columns or expand/collapse all
- **Conditional coloring** — JSONata-based cell color rules with Tailwind color support
- **Drilldown** — tap a leaf cell to see contributing source rows in an action sheet
- **Toolbar** — built-in expand/collapse/export controls
- **CSV export** — share via native share sheet (uses expo-file-system + expo-sharing when available)
- **Virtualized scrolling** — FlatList windowing for large datasets
- **Synchronized scroll** — row headers and column headers stay in sync with the data grid

## API Reference

### PivotGrid

The self-contained component — creates its own controller internally.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `TData[]` | — | Source data array. Required. |
| `rowDimensions` | `PivotGridDimension<TData>[]` | — | Row grouping dimension definitions. Required. |
| `columnDimensions` | `PivotGridDimension<TData>[]` | — | Column grouping dimension definitions. Required. |
| `measures` | `PivotGridMeasure<TData>[]` | — | Aggregation measure definitions. Required. |
| `getRowId` | `(row: TData, index: number) => string` | — | Custom row ID accessor. |
| `initialState` | `Partial<PivotGridState>` | — | Initial expanded row/column IDs. |
| `cellColorRules` | `PivotGridCellColorRule[]` | — | JSONata-based conditional cell coloring rules. |
| `drilldown` | `PivotGridDrilldown<TData>` | — | Drilldown configuration (columns, title getter). |
| `height` | `number` | `480` | Grid container height. |
| `rowHeaderWidth` | `number` | `140` | First row header column width. |
| `childRowHeaderWidth` | `number` | `110` | Subsequent row header column width. |
| `valueColumnWidth` | `number` | `100` | Leaf value column width. |
| `subtotalColumnWidth` | `number` | `108` | Subtotal column width. |
| `grandTotalColumnWidth` | `number` | `120` | Grand total column width. |
| `rowHeight` | `number` | `40` | Data row height. |
| `headerRowHeight` | `number` | `40` | Header row height. |
| `exportFileName` | `string` | `'pivot-grid'` | CSV export file name. |
| `className` | `string` | — | Additional container styles. |

### PivotGridView

Accepts an external controller for advanced use cases (e.g., sharing controller with toolbar).

| Prop | Type | Description |
|------|------|-------------|
| `controller` | `PivotGridController<TData>` | Controller instance from `usePivotGrid`. Required. |
| `className` | `string` | Additional CSS classes. |

### PivotGridToolbar

Horizontal toolbar with expand/collapse all and CSV export buttons.

| Prop | Type | Description |
|------|------|-------------|
| `controller` | `PivotGridController<TData>` | Controller instance. Required. |

### PivotGridDrilldownModal

Action sheet showing source rows for a drilled-down cell.

| Prop | Type | Description |
|------|------|-------------|
| `controller` | `PivotGridController<TData>` | Controller instance. Required. |
| `columns` | `NativeDrilldownColumn<TData>[]` | Custom column definitions for the drilldown table. |

### PivotGridDimension

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | Unique dimension identifier. |
| `label` | `string` | Display label. |
| `getValue` | `(row: TData) => unknown` | Accessor function to extract dimension value. |
| `formatValue` | `(value: unknown) => string` | Optional value formatter. |
| `sort` | `(a: unknown, b: unknown) => number` | Optional custom sort comparator. |
| `emptyLabel` | `string` | Label for empty/null values. |

### PivotGridMeasure

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | Unique measure identifier. |
| `label` | `string` | Display label. |
| `getValue` | `(row: TData) => number \| null \| undefined` | Optional value accessor (defaults to counting). |
| `aggregate` | `PivotGridAggregate` | Aggregation method: `'sum' \| 'count' \| 'avg' \| 'min' \| 'max'`. |
| `formatValue` | `(value: number) => string` | Optional formatted output. |

### PivotGridCellColorRule

| Field | Type | Description |
|-------|------|-------------|
| `formula` | `string` | JSONata expression (receives `value`, `measureId`, `rowPath`, `columnPath`, etc.). |
| `color` | `string` | Tailwind color name (e.g., `'green-100'`) or hex value. |
| `scope` | `PivotGridColorScope` | Optional: `'leaf' \| 'subtotal' \| 'total' \| 'grand-total'`. |

## Hooks

### usePivotGrid

```tsx
const controller = usePivotGrid<TData>(props: UsePivotGridProps<TData>);
```

Returns a `PivotGridController` with the full view model and all action callbacks. Use this when you need to share the controller between `PivotGridView`, `PivotGridToolbar`, and `PivotGridDrilldownModal`.

## Type Exports

| Type | Description |
|------|-------------|
| `PivotGridProps` | Props for PivotGrid (alias of UsePivotGridProps). |
| `UsePivotGridProps` | Props accepted by the `usePivotGrid` hook. |
| `PivotGridController` | Full controller interface returned by `usePivotGrid`. |
| `PivotGridDimension` | Dimension definition (row or column). |
| `PivotGridMeasure` | Measure/aggregation definition. |
| `PivotGridAggregate` | `'sum' \| 'count' \| 'avg' \| 'min' \| 'max'`. |
| `PivotGridCellColorRule` | Conditional cell coloring rule. |
| `PivotGridColorScope` | `'leaf' \| 'subtotal' \| 'total' \| 'grand-total'`. |
| `PivotGridState` | Expanded row/column IDs state. |
| `PivotGridDrilldown` | Drilldown configuration type. |
| `PivotGridDrilldownState` | Drilldown open/cell state. |
| `PivotGridHeaderRow` | Header row data structure. |
| `PivotGridHeaderCell` | Header cell data structure. |
| `PivotGridLeafColumn` | Leaf column data structure. |
| `PivotGridRenderedRow` | Rendered row with cell map. |
| `PivotGridRenderedCell` | Rendered cell with value/formatting. |
| `PivotGridColumnWidths` | Row header + value column width map. |
| `NativeDrilldownColumn` | Drilldown table column definition. |

---

# rn-place-autocomplete
URL: /docs/native/docyrus/place-autocomplete

A location search input with autocomplete suggestions powered by the Photon geocoding API.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-place-autocomplete
```

## Usage

```tsx
import { PlaceAutocomplete } from '@/components/docyrus-native/place-autocomplete';

<PlaceAutocomplete
  onPlaceSelect={(feature) => console.log(feature)}
  placeholder="Search location..."
/>
```

## API Reference

### PlaceAutocompleteProps

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `string` | — | Controlled search query value |
| `onValueChange` | `(value: string) => void` | — | Called when the search query changes |
| `onPlaceSelect` | `(feature: PlaceFeature) => void` | — | Called when a place is selected from suggestions |
| `placeholder` | `string` | `'Search location...'` | Placeholder text for the search input |
| `debounceMs` | `number` | `300` | Debounce delay in milliseconds before triggering search |
| `disabled` | `boolean` | `false` | Disables the input and prevents search |
| `lang` | `string` | `'en'` | Language code for search results |
| `limit` | `number` | `5` | Maximum number of search results to return |
| `lat` | `number` | — | Latitude for location-biased search |
| `lon` | `number` | — | Longitude for location-biased search |
| `className` | `string` | — | Additional CSS classes |

### PlaceFeature

| Field | Type | Description |
|-------|------|-------------|
| `type` | `'Feature'` | GeoJSON feature type |
| `geometry` | `{ type: 'Point'; coordinates: [number, number] }` | GeoJSON point geometry with `[longitude, latitude]` |
| `properties` | `PlaceFeatureProperties` | Address and metadata properties |

### PlaceFeatureProperties

| Field | Type | Description |
|-------|------|-------------|
| `osm_id` | `number` | OpenStreetMap ID |
| `osm_type` | `'N' \| 'W' \| 'R'` | OSM element type (Node, Way, Relation) |
| `name` | `string` | Place name |
| `housenumber` | `string` | House number |
| `street` | `string` | Street name |
| `city` | `string` | City name |
| `state` | `string` | State or province |
| `country` | `string` | Country name |
| `postcode` | `string` | Postal code |

## Type Exports

| Type | Description |
|------|-------------|
| `PlaceAutocompleteProps` | Props for PlaceAutocomplete component |
| `PlaceFeature` | GeoJSON feature returned by the geocoding API |
| `PlaceFeatureProperties` | Address properties of a place feature |

---

# rn-pricing-engine-panel
URL: /docs/native/docyrus/pricing-engine-panel

A pricing calculator panel with editable line items, automatic totals calculation, VAT, and discount support.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-pricing-engine-panel
```

## Usage

```tsx
import { PricingEnginePanel } from '@/components/docyrus-native/pricing-engine-panel';

<PricingEnginePanel
  currency="USD"
  enableVat
  enableDiscount
  onSave={(data) => console.log(data)}
/>
```

## API Reference

### PricingEnginePanelProps

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `lineItems` | `PricingLineItem[]` | — | Controlled line items array. Uses internal state when not provided |
| `onLineItemsChange` | `(items: PricingLineItem[]) => void` | — | Called when line items are added, removed, or updated |
| `onTotalsChange` | `(totals: PricingTotals) => void` | — | Called when calculated totals change |
| `currency` | `string` | `'USD'` | ISO 4217 currency code for formatting |
| `enableVat` | `boolean` | `true` | Enables VAT rate input and VAT total calculation |
| `enableDiscount` | `boolean` | `true` | Enables discount percentage input and discount calculation |
| `defaultVatRate` | `number` | `18` | Default VAT rate for new line items |
| `readOnly` | `boolean` | `false` | Disables editing of all fields and hides add/remove controls |
| `title` | `string` | — | Optional header title displayed above line items |
| `onSave` | `(data: { lineItems: PricingLineItem[]; totals: PricingTotals }) => void` | — | Called when the save button is pressed. Save button only renders when this prop is provided and `readOnly` is false |
| `className` | `string` | — | Additional CSS classes |

### PricingLineItem

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | Unique identifier for the line item |
| `position` | `number` | Display order position |
| `name` | `string` | Item name or description |
| `quantity` | `number` | Item quantity |
| `unitPrice` | `number` | Price per unit |
| `vatRate` | `number` | VAT percentage rate |
| `discountPercent` | `number` | Discount percentage |

### PricingTotals

| Field | Type | Description |
|-------|------|-------------|
| `subtotal` | `number` | Sum of all line item totals before discount |
| `discountTotal` | `number` | Total discount amount |
| `netTotal` | `number` | Subtotal minus discount |
| `vatTotal` | `number` | Total VAT amount |
| `grandTotal` | `number` | Net total plus VAT |

## Type Exports

| Type | Description |
|------|-------------|
| `PricingEnginePanelProps` | Props for PricingEnginePanel component |
| `PricingLineItem` | Line item data shape |
| `PricingTotals` | Calculated totals data shape |

---

# rn-qr-code
URL: /docs/native/docyrus/qr-code

QR code display component with size variants and optional logo overlay.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-qr-code
```

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

## Usage

```tsx
import { QrCode } from '@/components/docyrus-native/qr-code';

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `string` | — | QR code content (required) |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | QR code size |
| `color` | `string` | theme `black` | QR code color |
| `backgroundColor` | `string` | theme `white` | Background color |
| `logo` | `ReactNode` | — | Center logo overlay |
| `className` | `string` | — | Additional CSS classes |

## Type Exports

| Type | Description |
|------|-------------|
| `QrCodeProps` | Props for QrCode component |
| `QrCodeSize` | `'sm' \| 'md' \| 'lg'` |

---

# rn-query-builder
URL: /docs/native/docyrus/query-builder

A visual query builder with nestable groups, combinators, field/operator pickers, and value inputs.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-query-builder
```

## Usage

```tsx
import { QueryBuilder } from '@/components/docyrus-native/query-builder';
import type { QueryField, QueryGroup } from '@/components/docyrus-native/query-builder';

const fields: QueryField[] = [
  { id: 'name', label: 'Name', type: 'text' },
  { id: 'age', label: 'Age', type: 'number' },
  { id: 'active', label: 'Active', type: 'boolean' },
  { id: 'status', label: 'Status', type: 'select', options: [
    { label: 'Active', value: 'active' },
    { label: 'Inactive', value: 'inactive' },
  ]},
];

const [query, setQuery] = useState<QueryGroup>({
  id: '1',
  combinator: 'and',
  rules: [],
});

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `fields` | `QueryField[]` | — | Available fields that rules can filter on. |
| `query` | `QueryGroup` | — | The current query state (root group with nested rules/groups). |
| `onChange` | `(query: QueryGroup) => void` | — | Callback fired when the query changes. |
| `maxDepth` | `number` | `3` | Maximum nesting depth for sub-groups. |
| `className` | `string` | — | Custom styles applied to the outer ScrollView. |

### QueryField

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `id` | `string` | — | Unique identifier for the field. |
| `label` | `string` | — | Display label for the field. |
| `type` | `'text' \| 'number' \| 'date' \| 'boolean' \| 'select'` | — | Field data type. Determines the value input UI. |
| `options` | `{ label: string; value: string }[]` | — | Options for `select` type fields. |

### QueryGroup

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `id` | `string` | — | Unique identifier for the group. |
| `combinator` | `'and' \| 'or'` | — | Logical combinator for the group's rules. |
| `rules` | `(QueryRule \| QueryGroup)[]` | — | Array of rules and nested sub-groups. |

### QueryRule

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `id` | `string` | — | Unique identifier for the rule. |
| `field` | `string` | — | Field ID this rule filters on. |
| `operator` | `QueryOperator` | — | Comparison operator for the rule. |
| `value` | `unknown` | — | The value to compare against. |

## Type Exports

| Type | Description |
|------|-------------|
| `QueryBuilderProps` | Props for the QueryBuilder component. |
| `QueryField` | Field definition (id, label, type, options). |
| `QueryOperator` | `'equals' \| 'not_equals' \| 'contains' \| 'gt' \| 'lt' \| 'between' \| 'in' \| 'is_empty'` |
| `QueryRule` | A single filter rule (id, field, operator, value). |
| `QueryGroup` | A group of rules with a combinator (and/or) and nestable sub-groups. |

---

# rn-rate-limit-banner
URL: /docs/native/docyrus/rate-limit-banner

Animated banner for displaying API rate limiting and circuit breaker states with retry countdown.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-rate-limit-banner
```

**Dependencies:**
- [react-native-reanimated](https://www.npmjs.com/package/react-native-reanimated)
- [react-native-safe-area-context](https://www.npmjs.com/package/react-native-safe-area-context)

## Usage

```tsx
import { RateLimitBanner } from '@/components/docyrus-native/rate-limit-banner';

<RateLimitBanner
  visible={isBlocked}
  blockReason="rate_limited"
  retryAfterSeconds={retryAfter}
  onRetry={() => retryRequest()}
  onDismiss={() => setBlocked(false)}
/>
```

### Modal mode

```tsx
<RateLimitBanner
  visible={isBlocked}
  mode="modal"
  blockReason="circuit_open"
  retryAfterSeconds={30}
  onRetry={() => retryRequest()}
  onReload={() => reloadApp()}
/>
```

### Toast mode

```tsx
<RateLimitBanner
  visible={isBlocked}
  mode="toast"
  blockReason="rate_limited"
  retryAfterSeconds={5}
  onDismiss={() => dismiss()}
/>
```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `visible` | `boolean` | — | Whether the banner is visible |
| `blockReason` | `'rate_limited' \| 'circuit_open'` | `'rate_limited'` | Why the request was blocked |
| `retryAfterSeconds` | `number` | `0` | Seconds remaining before retry is allowed (0 = ready) |
| `mode` | `'banner' \| 'modal' \| 'toast'` | `'banner'` | Display mode |
| `rateLimitTitle` | `string` | `'Too Many Requests'` | Title when rate limited |
| `rateLimitMessage` | `string` | `'Please slow down...'` | Message when rate limited |
| `circuitOpenTitle` | `string` | `'Service Temporarily Unavailable'` | Title when circuit is open |
| `circuitOpenMessage` | `string` | `'We are experiencing issues...'` | Message when circuit is open |
| `retryButtonText` | `string` | `'Try again'` | Retry button label |
| `reloadButtonText` | `string` | `'Reload App'` | Reload button label |
| `showReloadButton` | `boolean` | `true` | Show reload action button |
| `autoHideDelay` | `number` | `2000` | Auto-hide delay after recovery (ms), 0 to disable |
| `onRetry` | `() => void` | — | Retry button handler |
| `onReload` | `() => void` | — | Reload button handler |
| `onDismiss` | `() => void` | — | Dismiss/close handler |
| `className` | `string` | — | Additional CSS classes |

## Display Modes

| Mode | Description |
|------|-------------|
| `banner` | Full-width top banner with slide-in animation. Shows title, message, countdown, retry and reload buttons. |
| `modal` | Centered modal overlay with icon, title, message, countdown badge, and action buttons. |
| `toast` | Bottom floating toast with compact layout, title, countdown, and dismiss button. |

## Type Exports

| Type | Description |
|------|-------------|
| `RateLimitBannerProps` | Props for RateLimitBanner component |
| `RateLimitBannerMode` | `'banner' \| 'modal' \| 'toast'` |
| `RateLimitBlockReason` | `'rate_limited' \| 'circuit_open'` |

---

# rn-rating
URL: /docs/native/docyrus/rating

Star rating input with half-star support and custom icon rendering.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-rating
```

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

## Usage

```tsx
import { Rating } from '@/components/docyrus-native/rating';

<Rating value={3} onChange={(v) => console.log(v)} />

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `number` | `0` | Current rating value |
| `onChange` | `(value: number) => void` | — | Callback when rating changes |
| `max` | `number` | `5` | Maximum number of stars |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Star size |
| `readonly` | `boolean` | `false` | Whether the rating is read-only |
| `disabled` | `boolean` | `false` | Whether the rating is disabled |
| `allowHalf` | `boolean` | `false` | Enable half-star ratings |
| `showValue` | `boolean` | `false` | Show numeric value next to stars |
| `color` | `string` | `'#fbbf24'` | Fill color for active stars |
| `emptyColor` | `string` | — | Color for empty stars (defaults to theme mutedForeground) |
| `renderIcon` | `(props: { filled: boolean; half: boolean; color: string; size: number }) => ReactNode` | — | Custom icon render function |
| `className` | `string` | — | Additional CSS classes |
| `accessibilityLabel` | `string` | `'Rating'` | Accessibility label |

## Type Exports

| Type | Description |
|------|-------------|
| `RatingProps` | Props for Rating component |
| `RatingSize` | `'sm' \| 'md' \| 'lg'` |

---

# rn-record-activity-panel
URL: /docs/native/docyrus/record-activity-panel

A reusable record activity feed with timeline markers and app-controlled localized copy.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-record-activity-panel
```

## Usage

```tsx
import { RecordActivityPanel } from '@/components/docyrus-native/record-activity-panel';

<RecordActivityPanel
  activities={activities}
  messages={{
    empty: t('activity.empty', 'No activity recorded'),
    loading: t('activity.loading', 'Loading activity...'),
    system: t('common.system', 'System')
  }}
  maxItems={8}
  operationLabelFormatter={(operation) => operation.toLowerCase().replace('_', ' ')}
/>
```

## API Reference

### RecordActivityPanelProps

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `activities` | `RecordActivity[]` | — | Array of activity records to render |
| `messages` | `RecordActivityPanelMessages` | — | Required localized labels passed from the app |
| `isLoading` | `boolean` | `false` | Shows the loading state |
| `emptyMessage` | `string` | — | Optional empty state override |
| `maxItems` | `number` | — | Limits the number of rendered activity rows after sorting by newest first |
| `showConnector` | `boolean` | `true` | Hides or shows the vertical timeline connector |
| `dateFormatter` | `(date: string) => string` | — | Overrides the default timestamp formatter |
| `operationLabelFormatter` | `(operation: RecordActivityOperation) => string` | — | Customizes operation label text |
| `className` | `string` | — | Additional container classes |
| `contentContainerClassName` | `string` | — | Additional classes for the list content wrapper |

### RecordActivityPanelMessages

| Field | Type | Description |
|-------|------|-------------|
| `empty` | `string` | Empty state label |
| `loading` | `string` | Loading label |
| `system` | `string` | Fallback actor label when no user is available |

---

# rn-record-delete-confirm-dialog
URL: /docs/native/docyrus/record-delete-confirm-dialog

Delete confirmation dialog with cascade relation management for related data.

## Installation

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

## Usage

```tsx
import { RecordDeleteConfirmDialog } from '@/components/docyrus-native/record-delete-confirm-dialog';

<RecordDeleteConfirmDialog
  open={isOpen}
  onOpenChange={setIsOpen}
  recordCount={3}
  relations={relations}
  onConfirm={(childActions) => handleDelete(childActions)}
/>
```

## API Reference

### RecordDeleteConfirmDialogProps

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `open` | `boolean` | - | Controls dialog visibility |
| `onOpenChange` | `(open: boolean) => void` | - | Callback when dialog open state changes |
| `recordCount` | `number` | - | Number of records being deleted (shown in title) |
| `relations` | `DataSourceRelation[]` | - | Array of related data sources with cascade options |
| `isLoadingRelations` | `boolean` | `false` | Shows loading indicator while relations are being fetched |
| `onConfirm` | `(childActions: Record<string, ChildAction>) => void` | - | Callback with per-relation keep/delete decisions |
| `isPending` | `boolean` | `false` | Disables buttons and shows loading state during deletion |
| `className` | `string` | - | Additional CSS classes |

### DataSourceRelation

| Field | Type | Description |
|-------|------|-------------|
| `dataSourceId` | `string` | Unique identifier of the related data source |
| `dataSourceName` | `string` | Display name of the related data source |
| `dataSourceSlug` | `string` | URL slug of the related data source |
| `appSlug` | `string` | Application slug |
| `dataSourceType` | `string` | Type of the data source |
| `fieldId` | `string` | ID of the linking field |
| `fieldSlug` | `string` | Slug of the linking field |
| `fieldName` | `string` | Display name of the linking field |
| `fieldType` | `string` | Type of the linking field |

### ChildAction

```tsx
type ChildAction = 'keep' | 'delete';
```

Action to take on related records: keep them intact or delete them along with the parent.

## Type Exports

| Type | Description |
|------|-------------|
| `RecordDeleteConfirmDialogProps` | Props for RecordDeleteConfirmDialog component |
| `DataSourceRelation` | Related data source information |
| `ChildAction` | `'keep' \| 'delete'` |

---

# rn-record-sharing
URL: /docs/native/docyrus/record-sharing

Share panel with search, permission management, and entity list.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-record-sharing
```

## Usage

```tsx
import { RecordSharingPanel } from '@/components/docyrus-native/record-sharing';

<RecordSharingPanel
  sharedEntities={entities}
  onSearch={async (query) => searchUsers(query)}
  onAdd={(result, permission) => handleAdd(result, permission)}
  onPermissionChange={(id, permission) => handlePermissionChange(id, permission)}
  onRemove={(id) => handleRemove(id)}
/>
```

## API Reference

### RecordSharingPanelProps

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `sharedEntities` | `SharedEntity[]` | - | Array of currently shared entities |
| `resources` | `SharingResourceType[]` | - | Allowed resource types for filtering |
| `permissionPresets` | `PermissionPresetOption[]` | Default presets | Custom permission preset options |
| `defaultPermission` | `number` | `1` (CAN_VIEW) | Default permission value when adding a new entity |
| `onSearch` | `(query: string) => Promise<SharingSearchResult[]>` | - | Async search callback returning matching results |
| `onAdd` | `(result: SharingSearchResult, permission: number) => void` | - | Callback when a search result is added |
| `onPermissionChange` | `(entityId: string, permission: number) => void` | - | Callback when an entity's permission changes |
| `onRemove` | `(entityId: string) => void` | - | Callback when an entity is removed |
| `isLoading` | `boolean` | `false` | Shows loading indicator instead of entity list |
| `title` | `string` | `'Share'` | Panel header title |
| `className` | `string` | - | Additional CSS classes |

### SharedEntity

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `id` | `string` | - | Unique identifier |
| `name` | `string` | - | Display name |
| `description` | `string` | - | Secondary description text |
| `type` | `SharingResourceType` | - | Resource type: `'user' \| 'team' \| 'role' \| 'tenant' \| 'public'` |
| `avatarUrl` | `string` | - | URL for avatar image |
| `initials` | `string` | - | Initials displayed in avatar circle |
| `permission` | `number` | - | Bitmask permission value |

### SharingSearchResult

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `id` | `string` | - | Unique identifier |
| `name` | `string` | - | Display name |
| `description` | `string` | - | Secondary description text |
| `type` | `SharingResourceType` | - | Resource type |
| `avatarUrl` | `string` | - | URL for avatar image |
| `initials` | `string` | - | Initials for avatar fallback |

### PermissionPresetOption

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `label` | `string` | - | Display label |
| `value` | `number` | - | Bitmask permission value |
| `description` | `string` | - | Description shown in permission picker |

### Permission Constants

| Constant | Value | Description |
|----------|-------|-------------|
| `SharingPermission.READ` | `1` | Read permission |
| `SharingPermission.WRITE` | `2` | Write permission |
| `SharingPermission.COMMENT` | `4` | Comment permission |
| `SharingPermission.SHARE` | `8` | Share permission |
| `SharingPermission.DELETE` | `16` | Delete permission |

### Permission Presets

| Preset | Value | Includes |
|--------|-------|----------|
| `SharingPermissionPreset.CAN_VIEW` | `1` | Read |
| `SharingPermissionPreset.CAN_COMMENT` | `5` | Read + Comment |
| `SharingPermissionPreset.CAN_EDIT` | `7` | Read + Write + Comment |
| `SharingPermissionPreset.CAN_SHARE` | `15` | Read + Write + Comment + Share |
| `SharingPermissionPreset.FULL_ACCESS` | `31` | All permissions |

## Type Exports

| Type | Description |
|------|-------------|
| `RecordSharingPanelProps` | Props for RecordSharingPanel component |
| `SharedEntity` | Shared entity with permission data |
| `SharingSearchResult` | Search result item |
| `SharingResourceType` | `'user' \| 'team' \| 'role' \| 'tenant' \| 'public'` |
| `PermissionPresetOption` | Permission preset configuration |
| `SharingPermission` | Permission bitmask constants |
| `SharingPermissionPreset` | Permission preset constants |

---

# rn-resource-scheduler-panel
URL: /docs/native/docyrus/resource-scheduler-panel

A horizontal timeline scheduler that displays events across multiple resources in a day view.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-resource-scheduler-panel
```

## Usage

```tsx
import { ResourceSchedulerPanel } from '@/components/docyrus-native/resource-scheduler-panel';
import type { SchedulerResource, SchedulerEvent } from '@/components/docyrus-native/resource-scheduler-panel';

const resources: SchedulerResource[] = [
  { id: '1', name: 'Room A', color: '#3b82f6' },
  { id: '2', name: 'Room B', color: '#10b981' },
];

const events: SchedulerEvent[] = [
  {
    id: 'e1',
    resourceId: '1',
    title: 'Meeting',
    start: new Date(2025, 0, 1, 9, 0),
    end: new Date(2025, 0, 1, 10, 30),
  },
];

<ResourceSchedulerPanel
  resources={resources}
  events={events}
  startDate={new Date(2025, 0, 1)}
  onEventPress={(event) => console.log(event)}
  onSlotPress={(resourceId, date) => console.log(resourceId, date)}
/>
```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `resources` | `SchedulerResource[]` | — | Array of resources (rows) to display. |
| `events` | `SchedulerEvent[]` | — | Array of events to place on the timeline. |
| `startDate` | `Date` | — | The date to display. Defaults to today when not provided. |
| `onEventPress` | `(event: SchedulerEvent) => void` | — | Callback fired when an event bar is pressed. |
| `onSlotPress` | `(resourceId: string, date: Date) => void` | — | Callback fired when an empty hour slot is pressed. |
| `className` | `string` | — | Additional CSS classes |

### SchedulerResource

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `id` | `string` | — | Unique identifier for the resource. |
| `name` | `string` | — | Display name shown in the resource column. |
| `color` | `string` | — | Optional color indicator dot for the resource. |

### SchedulerEvent

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `id` | `string` | — | Unique identifier for the event. |
| `resourceId` | `string` | — | The resource this event belongs to. |
| `title` | `string` | — | Title displayed on the event bar. |
| `start` | `Date` | — | Start date/time of the event. |
| `end` | `Date` | — | End date/time of the event. |
| `color` | `string` | — | Custom color for the event bar. Falls back to the resource color, then to primary. |

## Type Exports

| Type | Description |
|------|-------------|
| `ResourceSchedulerPanelProps` | Props for the ResourceSchedulerPanel component. |
| `SchedulerResource` | Resource definition (id, name, color). |
| `SchedulerEvent` | Event definition (id, resourceId, title, start, end, color). |

---

# rn-schema-repeater
URL: /docs/native/docyrus/schema-repeater

A generic repeater component for managing dynamic lists of items with reordering, adding, and removing capabilities.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-schema-repeater
```

## Usage

```tsx
import { SchemaRepeater } from '@/components/docyrus-native/schema-repeater';

type LineItem = { id: string; name: string; quantity: number };

<SchemaRepeater<LineItem>
  value={items}
  onValueChange={setItems}
  createItem={() => ({ id: String(Date.now()), name: '', quantity: 1 })}
  renderItem={(item, index, helpers) => (
    <TextInput
      value={item.name}
      onChangeText={(text) => helpers.update({ name: text })}
    />
  )}
/>
```

## API Reference

### SchemaRepeaterProps\<T\>

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `T[]` | — | Array of items to render. Each item must have an `id: string` field |
| `onValueChange` | `(items: T[]) => void` | — | Called when items are added, removed, reordered, or updated |
| `renderItem` | `(item: T, index: number, helpers: SchemaRepeaterHelpers<T>) => ReactNode` | — | Render function for each item. Receives the item, its index, and helper functions |
| `createItem` | `() => T` | — | Factory function to create a new item when the add button is pressed |
| `maxItems` | `number` | — | Maximum number of items allowed. Add button hides when reached |
| `minItems` | `number` | `0` | Minimum number of items required. Remove button disables when reached |
| `addLabel` | `string` | `'Add Item'` | Label text for the add button |
| `disabled` | `boolean` | `false` | Disables all interactions including add, remove, and reorder |
| `className` | `string` | — | Additional CSS classes |

### SchemaRepeaterItem

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | Unique identifier required for each item |

### SchemaRepeaterHelpers\<T\>

| Field | Type | Description |
|-------|------|-------------|
| `remove` | `() => void` | Removes the current item |
| `update` | `(updates: Partial<T>) => void` | Partially updates the current item |
| `moveUp` | `() => void` | Moves the current item up by one position |
| `moveDown` | `() => void` | Moves the current item down by one position |
| `isFirst` | `boolean` | Whether this is the first item in the list |
| `isLast` | `boolean` | Whether this is the last item in the list |

## Type Exports

| Type | Description |
|------|-------------|
| `SchemaRepeaterProps<T>` | Props for SchemaRepeater component |
| `SchemaRepeaterItem` | Base interface for repeater items (requires `id`) |
| `SchemaRepeaterHelpers<T>` | Helper object passed to renderItem callback |

---

# rn-search-input
URL: /docs/native/docyrus/search-input

Search input with debounce and clear button, supporting manual and automatic search modes.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-search-input
```

## Usage

```tsx
import { SearchInput } from '@/components/docyrus-native/search-input';

const [query, setQuery] = useState('');

<SearchInput
  value={query}
  onValueChange={setQuery}
  onSearch={(value) => fetchResults(value)}
/>
```

### Manual Mode

In manual mode, `onSearch` is only triggered when the user submits (presses the return key).

```tsx

```

### Custom Debounce

```tsx

```

### Sizes

```tsx

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `string` | — | The current input value (controlled). |
| `onValueChange` | `(value: string) => void` | — | Callback when the input value changes. |
| `onSearch` | `(value: string) => void` | — | Callback when a search should be executed. In debounce mode, called after the debounce delay. In manual mode, called on submit. |
| `mode` | `'debounce' \| 'manual'` | `'debounce'` | Search trigger mode. `'debounce'` triggers automatically after typing stops; `'manual'` triggers on submit only. |
| `debounceMs` | `number` | `300` | Debounce delay in milliseconds (only used in debounce mode). |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Controls the height, font size, icon size, and padding of the input. |
| `placeholder` | `string` | `'Search...'` | Placeholder text displayed when the input is empty. |
| `disabled` | `boolean` | `false` | When true, the input is non-editable and visually dimmed. |
| `autoFocus` | `boolean` | `false` | When true, the input is focused on mount. |
| `className` | `string` | — | Additional CSS classes |
| `inputClassName` | `string` | — | Custom style applied to the TextInput element. |

## Type Exports

| Type | Description |
|------|-------------|
| `SearchInputProps` | Props for the SearchInput component. |
| `SearchInputSize` | Size variant: `'sm' \| 'md' \| 'lg'`. |
| `SearchInputMode` | Search mode: `'debounce' \| 'manual'`. |

---

# rn-status-chip
URL: /docs/native/docyrus/status-chip

A reusable tone-based chip for status, priority, and other compact enum labels.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-status-chip
```

## Usage

```tsx
import { StatusChip } from '@/components/docyrus-native/status-chip';

```

## API Reference

### StatusChipProps

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `label` | `string` | — | Text rendered inside the chip |
| `tone` | `'neutral' \| 'info' \| 'success' \| 'warning' \| 'danger' \| 'accent' \| 'purple'` | `'neutral'` | Semantic color tone |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Chip density |
| `emphasis` | `'soft' \| 'solid'` | `'soft'` | Filled vs tinted presentation |
| `className` | `string` | — | Additional wrapper classes |
| `labelClassName` | `string` | — | Additional label classes |

---

# rn-status
URL: /docs/native/docyrus/status

Status indicator badge with dot and colored variants.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-status
```

## Usage

```tsx
import { Status } from '@/components/docyrus-native/status';

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `text` | `string` | — | Status text to display |
| `variant` | `'success' \| 'warning' \| 'error' \| 'info' \| 'pending' \| 'default'` | `'default'` | Visual style variant |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Component size |
| `showDot` | `boolean` | `true` | Show status dot indicator |
| `className` | `string` | — | Additional CSS classes |
| `textClassName` | `string` | — | Text CSS classes |

## Type Exports

| Type | Description |
|------|-------------|
| `StatusProps` | Props for Status component |
| `StatusVariant` | `'success' \| 'warning' \| 'error' \| 'info' \| 'pending' \| 'default'` |
| `StatusSize` | `'sm' \| 'md' \| 'lg'` |

---

# rn-stepper
URL: /docs/native/docyrus/stepper

Step indicator component for multi-step wizards and onboarding flows.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-stepper
```

## Usage

```tsx
import { Stepper } from '@/components/docyrus-native/stepper';

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `steps` | `StepItem[]` | — | Array of steps (required) |
| `currentStep` | `number` | `0` | Current active step index |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout direction |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Stepper size |
| `className` | `string` | — | Additional CSS classes |
| `labelClassName` | `string` | — | Label CSS classes |
| `descriptionClassName` | `string` | — | Description CSS classes |

### StepItem

| Property | Type | Description |
|----------|------|-------------|
| `label` | `string` | Step label |
| `description` | `string` | Optional description |

## Type Exports

| Type | Description |
|------|-------------|
| `StepperProps` | Props for Stepper component |
| `StepItem` | Step item type |
| `StepperSize` | `'sm' \| 'md' \| 'lg'` |
| `StepperOrientation` | `'horizontal' \| 'vertical'` |
| `StepStatus` | `'completed' \| 'current' \| 'upcoming'` |

---

# rn-time-entry-list
URL: /docs/native/docyrus/time-entry-list

A reusable mobile list for time entries with app-controlled localized labels.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-time-entry-list
```

## Usage

```tsx
import { TimeEntryList } from '@/components/docyrus-native/time-entry-list';

```

## API Reference

### TimeEntryListProps

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `entries` | `TimeEntryListItem[]` | — | Time entry rows to render |
| `messages` | `TimeEntryListMessages` | — | Required localized labels passed from the app |
| `isLoading` | `boolean` | `false` | Shows loading state |
| `emptyMessage` | `string` | — | Optional empty state override |
| `size` | `'sm' \| 'md'` | `'md'` | Controls row density |
| `showStatus` | `boolean` | `true` | Displays the status chip |
| `showBillable` | `boolean` | `true` | Displays the billable/non-billable chip |
| `onEntryPress` | `(entry: TimeEntryListItem) => void` | — | Row press handler |
| `dateFormatter` | `(date: string) => string` | — | Overrides the default date formatting |
| `className` | `string` | — | Additional wrapper classes |
| `contentContainerClassName` | `string` | — | Additional content container classes |

### TimeEntryListMessages

| Field | Type | Description |
|-------|------|-------------|
| `loading` | `string` | Loading label |
| `empty` | `string` | Empty state label |
| `billable` | `string` | Billable badge label |
| `nonBillable` | `string` | Non-billable badge label |
| `statusLabels` | `Record<TimeEntryListStatus, string>` | Localized labels for every status variant |

---

# rn-time-slot-scheduler
URL: /docs/native/docyrus/time-slot-scheduler

A grid-based time slot scheduler for selecting available slots across multiple days.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-time-slot-scheduler
```

## Usage

```tsx
import { TimeSlotScheduler } from '@/components/docyrus-native/time-slot-scheduler';
import type { TimeSlot } from '@/components/docyrus-native/time-slot-scheduler';

const slots: TimeSlot[] = [
  { date: '2025-01-06', startTime: '09:00', endTime: '10:00', available: true },
  { date: '2025-01-06', startTime: '10:00', endTime: '11:00', available: true },
  { date: '2025-01-06', startTime: '11:00', endTime: '12:00', available: false },
  { date: '2025-01-07', startTime: '09:00', endTime: '10:00', available: true },
];

const [selected, setSelected] = useState<string[]>([]);

<TimeSlotScheduler
  slots={slots}
  selectedSlots={selected}
  onSlotSelect={(key) => setSelected((prev) => [...prev, key])}
  onSlotDeselect={(key) => setSelected((prev) => prev.filter((k) => k !== key))}
/>
```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `slots` | `TimeSlot[]` | — | Array of time slots to display in the grid. |
| `selectedSlots` | `string[]` | `[]` | Array of selected slot keys (format: `"{date}-{startTime}"`). |
| `onSlotSelect` | `(slotKey: string) => void` | — | Callback fired when an available slot is selected. |
| `onSlotDeselect` | `(slotKey: string) => void` | — | Callback fired when a selected slot is deselected. |
| `className` | `string` | — | Additional CSS classes |

### TimeSlot

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `date` | `string` | — | Date string in `YYYY-MM-DD` format. |
| `startTime` | `string` | — | Start time string (e.g. `"09:00"`). Used as the row key. |
| `endTime` | `string` | — | End time string (e.g. `"10:00"`). |
| `available` | `boolean` | — | Whether the slot is available for selection. Defaults to `true` when omitted. |

## Type Exports

| Type | Description |
|------|-------------|
| `TimeSlotSchedulerProps` | Props for the TimeSlotScheduler component. |
| `TimeSlot` | Slot definition (date, startTime, endTime, available). |

---

# rn-timeline
URL: /docs/native/docyrus/timeline

Vertical timeline component with status indicators, alternate layout, animated entrance, and interactive items.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-timeline
```

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

## Usage

```tsx
import { Timeline } from '@/components/docyrus-native/timeline';

```

### Alternate Layout

```tsx

```

### With Item Press

```tsx
,
    },
  ]}
/>
```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `items` | `TimelineItem[]` | — | Array of timeline events (required) |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Timeline size |
| `variant` | `'default' \| 'outline'` | `'default'` | Dot style variant |
| `lineStyle` | `'solid' \| 'dashed'` | `'solid'` | Global connector line style |
| `layout` | `'left' \| 'alternate'` | `'left'` | Content layout position |
| `animated` | `boolean` | `false` | Staggered fade-in entrance animation |
| `onItemPress` | `(item: TimelineItem, index: number) => void` | — | Item press handler |
| `className` | `string` | — | Container class override |
| `titleClassName` | `string` | — | Title text class override |
| `descriptionClassName` | `string` | — | Description text class override |
| `timeClassName` | `string` | — | Time text class override |

### TimelineItem

| Property | Type | Description |
|----------|------|-------------|
| `title` | `string` | Event title |
| `description` | `string` | Optional description text |
| `time` | `string` | Optional time label |
| `icon` | `ReactNode` | Custom icon (replaces dot) |
| `dotColor` | `string` | Custom dot color (ignored when `status` is set) |
| `status` | `TimelineStatus` | Item status — controls dot icon, line style, and content opacity |
| `content` | `ReactNode` | Rich content slot rendered below description |
| `lineStyle` | `TimelineLineStyle` | Per-item line style override |

## Status

When `status` is set on an item, the dot, line, and content are styled automatically:

| Status | Dot | Line Below | Content |
|--------|-----|------------|---------|
| `completed` | Green circle with check icon | Solid primary | Normal |
| `active` | Primary circle with inner ring | Dashed primary | Normal |
| `pending` | Small muted circle | Dashed muted | Reduced opacity (60%) |
| `error` | Red circle with X icon | Solid red | Normal |

Items without `status` use the `variant` prop for dot styling (backward compatible).

## Type Exports

| Type | Description |
|------|-------------|
| `TimelineProps` | Props for Timeline component |
| `TimelineItem` | Timeline event item type |
| `TimelineSize` | `'sm' \| 'md' \| 'lg'` |
| `TimelineVariant` | `'default' \| 'outline'` |
| `TimelineStatus` | `'completed' \| 'active' \| 'pending' \| 'error'` |
| `TimelineLineStyle` | `'solid' \| 'dashed'` |
| `TimelineLayout` | `'left' \| 'alternate'` |

---

# rn-timesheet-pivot
URL: /docs/native/docyrus/timesheet-pivot

A horizontal pivot table for time tracking with heatmap coloring, column totals, and striped rows.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-timesheet-pivot
```

## Usage

```tsx
import { TimesheetPivot } from '@/components/docyrus-native/timesheet-pivot';

const columns = [
  { key: 'mon', label: 'Mon' },
  { key: 'tue', label: 'Tue' },
  { key: 'wed', label: 'Wed' },
  { key: 'thu', label: 'Thu' },
  { key: 'fri', label: 'Fri' },
];

const rows = [
  {
    id: 'project-1',
    title: 'Project Atlas',
    subtitle: 'Mobile sprint',
    values: { mon: 2.5, tue: 1.5, wed: 4, thu: 3.5, fri: 2 },
  },
  {
    id: 'project-2',
    title: 'Project Northwind',
    values: { mon: 1, tue: 2, wed: 0, thu: 2.5, fri: 3 },
  },
];

```

## Features

- **Heatmap coloring** — cells are tinted based on value intensity relative to the max value
- **Column totals footer** — a summary row showing totals per column and a grand total
- **Striped rows** — alternating row backgrounds for readability
- **FlatList rendering** — virtualized row rendering with `getItemLayout` for O(1) scroll performance
- **Three value formats** — `raw`, `hours` (`2.5h`), `minutes` (`2h 30m`)
- **Custom formatter** — override cell display with `valueFormatter`
- **Row press** — optional `onRowPress` callback for navigation
- **Dark mode** — fully theme-aware with light/dark opacity adjustments

## API Reference

### TimesheetPivotProps

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `columns` | `TimesheetPivotColumn[]` | — | Column definitions (key + label) |
| `rows` | `TimesheetPivotRow[]` | — | Row data with values per column |
| `messages` | `TimesheetPivotMessages` | — | Required localized labels |
| `isLoading` | `boolean` | `false` | Shows loading state |
| `emptyMessage` | `string` | — | Optional empty state override |
| `showTotals` | `boolean` | `true` | Shows total column per row + footer totals row |
| `emptyValue` | `string` | `'—'` | Placeholder for empty/zero cells |
| `valueKind` | `'raw' \| 'hours' \| 'minutes'` | `'raw'` | Default numeric formatter |
| `onRowPress` | `(row: TimesheetPivotRow) => void` | — | Row press callback |
| `valueFormatter` | `(value, columnKey, row) => string` | — | Custom cell value formatter |
| `className` | `string` | — | Additional wrapper className |

### TimesheetPivotColumn

| Field | Type | Description |
|-------|------|-------------|
| `key` | `string` | Unique column identifier (used as key in `values`) |
| `label` | `string` | Display label in header |

### TimesheetPivotRow

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | Unique row identifier |
| `title` | `string` | Primary row label |
| `subtitle` | `string?` | Secondary label (shown below title) |
| `values` | `Record<string, CellValue>` | Cell values keyed by column key |
| `total` | `CellValue?` | Explicit total (auto-computed if omitted) |

### TimesheetPivotMessages

| Field | Type | Description |
|-------|------|-------------|
| `loading` | `string` | Loading state label |
| `empty` | `string` | Empty state label |
| `total` | `string` | Total column/row header label |
| `row` | `string` | First column header label |

### TimesheetPivotCellValue

```ts
type TimesheetPivotCellValue = number | string | null | undefined;
```

## Value Formatting

The component supports three built-in formatters via `valueKind`:

| Kind | Input | Output |
|------|-------|--------|
| `raw` | `2.5` | `2.5` |
| `hours` | `2.5` | `2.5h` |
| `minutes` | `150` | `2h 30m` |

For custom formatting, use `valueFormatter`:

```tsx
<TimesheetPivot
  valueFormatter={(value, columnKey, row) => {
    if (columnKey === '__total__') return `${value}h total`;
    return typeof value === 'number' ? `${value}h` : '—';
  }}
/>
```

---

# rn-tree-view
URL: /docs/native/docyrus/tree-view

Hierarchical tree component with expand/collapse, search, and optional checkboxes.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-tree-view
```

## Usage

```tsx
import { TreeView } from '@/components/docyrus-native/tree-view';

<TreeView
  data={[
    {
      id: '1', name: 'Documents', type: 'folder',
      children: [
        { id: '1-1', name: 'Report.pdf', type: 'file' },
        { id: '1-2', name: 'Notes.txt', type: 'file' },
      ]
    },
  ]}
  showCheckboxes
  showExpandAll
  onCheckChange={(checkedIds) => console.log(checkedIds)}
/>
```

## API Reference

### TreeViewProps

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `TreeViewItem[]` | - | Hierarchical tree data |
| `showCheckboxes` | `boolean` | `false` | Show checkboxes next to each node |
| `showExpandAll` | `boolean` | `false` | Show expand/collapse all button |
| `searchPlaceholder` | `string` | `'Search...'` | Placeholder text for the search input |
| `onSelectionChange` | `(selectedId: string) => void` | - | Callback when a node is tapped |
| `onCheckChange` | `(checkedIds: Set<string>) => void` | - | Callback when checkbox state changes |
| `className` | `string` | - | Additional CSS classes |

### TreeViewItem

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `id` | `string` | - | Unique identifier |
| `name` | `string` | - | Display name |
| `type` | `string` | - | Node type (shown as a badge, e.g. `'folder'`, `'file'`) |
| `children` | `TreeViewItem[]` | - | Child nodes (presence enables expand/collapse) |
| `checked` | `boolean` | - | Initial checked state |

## Type Exports

| Type | Description |
|------|-------------|
| `TreeViewProps` | Props for TreeView component |
| `TreeViewItem` | Tree node data structure |

---

# rn-value-renderers
URL: /docs/native/docyrus/value-renderers

Read-only display components for rendering field values by type.

## Overview

Value renderers are read-only display components that format and present field values based on their type. Each renderer accepts a shared `DocyValueProps` interface and outputs a styled representation of the value.

Two key components orchestrate value rendering:

- **DocyValueBase** --- Wrapper component that handles empty state display and provides consistent sizing/styling to all renderers.
- **DocyValueDynamic** --- Renders any value type dynamically by resolving the appropriate renderer from `field.type`.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-value-renderers
```

## Usage

```tsx
import { DocyValueDynamic } from '@/components/docyrus-native/value-renderers/docy-value-dynamic';
import { DocyValueText } from '@/components/docyrus-native/value-renderers/docy-value-text';

// Dynamic rendering based on field.type

// Direct renderer usage

```

## API Reference

### DocyValueProps

All value renderers share the following base props:

| 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[]` | — | Enum options for select-based fields |
| `className` | `string` | — | Additional CSS classes |
| `textClassName` | `string` | — | Text CSS classes |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size variant |

### IField

| Property | Type | Description |
|----------|------|-------------|
| `id` | `string` | Unique field identifier |
| `name` | `string` | Display name |
| `slug` | `string` | URL-safe field key |
| `type` | `IFieldType` | Field type used to resolve the renderer |
| `defaultValue` | `string \| null` | Default value |
| `readOnly` | `boolean \| null` | Whether the field is read-only |
| `options` | `Record<string, unknown> \| null` | Additional field options |

---

## Text & Number Renderers

### DocyValueText

Plain text display. Renders the value as-is.

```tsx
import { DocyValueText } from '@/components/docyrus-native/value-renderers/docy-value-text';

```

### DocyValueNumber

Number with locale-aware formatting.

```tsx
import { DocyValueNumber } from '@/components/docyrus-native/value-renderers/docy-value-number';

```

### DocyValuePercent

Percentage display with `%` symbol.

```tsx
import { DocyValuePercent } from '@/components/docyrus-native/value-renderers/docy-value-percent';

```

### DocyValueEmail

Clickable email link.

```tsx
import { DocyValueEmail } from '@/components/docyrus-native/value-renderers/docy-value-email';

```

### DocyValueUrl

Clickable URL link.

```tsx
import { DocyValueUrl } from '@/components/docyrus-native/value-renderers/docy-value-url';

```

### DocyValuePhone

Formatted phone number display.

```tsx
import { DocyValuePhone } from '@/components/docyrus-native/value-renderers/docy-value-phone';

```

### DocyValueColor

Color swatch with hex value.

```tsx
import { DocyValueColor } from '@/components/docyrus-native/value-renderers/docy-value-color';

```

### DocyValueIcon

Icon display based on field value.

```tsx
import { DocyValueIcon } from '@/components/docyrus-native/value-renderers/docy-value-icon';

```

### DocyValueCurrencyCode

Currency code badge.

```tsx
import { DocyValueCurrencyCode } from '@/components/docyrus-native/value-renderers/docy-value-currency-code';

```

### DocyValueMoney

Formatted money display with currency symbol and amount.

```tsx
import { DocyValueMoney } from '@/components/docyrus-native/value-renderers/docy-value-money';

```

### DocyValueDuration

Formatted duration in hours, minutes, and seconds.

```tsx
import { DocyValueDuration } from '@/components/docyrus-native/value-renderers/docy-value-duration';

```

| Renderer | Value Type | Output |
|----------|-----------|--------|
| `DocyValueText` | `string` | Plain text |
| `DocyValueNumber` | `number` | Locale-formatted number |
| `DocyValuePercent` | `number` | Number with % symbol |
| `DocyValueEmail` | `string` | Tappable email link |
| `DocyValueUrl` | `string` | Tappable URL link |
| `DocyValuePhone` | `string` | Formatted phone number |
| `DocyValueColor` | `string` | Color swatch + hex code |
| `DocyValueIcon` | `string` | Icon glyph |
| `DocyValueCurrencyCode` | `string` | Currency code badge |
| `DocyValueMoney` | `number` | Currency symbol + formatted amount |
| `DocyValueDuration` | `number` | HH:MM:SS formatted duration |

---

## Select & Status Renderers

Most renderers in this group rely on `enumOptions` to resolve display labels and colors from the value.

### DocyValueSelect

Single select badge with color from enum options.

```tsx
import { DocyValueSelect } from '@/components/docyrus-native/value-renderers/docy-value-select';

```

### DocyValueMultiSelect

Multiple badges/chips for multi-select values.

```tsx
import { DocyValueMultiSelect } from '@/components/docyrus-native/value-renderers/docy-value-multi-select';

```

### DocyValueStatus

Status badge with colored dot indicator.

```tsx
import { DocyValueStatus } from '@/components/docyrus-native/value-renderers/docy-value-status';

```

### DocyValueRadioGroup

Displays the selected radio option label.

```tsx
import { DocyValueRadioGroup } from '@/components/docyrus-native/value-renderers/docy-value-radio-group';

```

### DocyValueUser

User avatar with name.

```tsx
import { DocyValueUser } from '@/components/docyrus-native/value-renderers/docy-value-user';

```

### DocyValueUserMulti

Multiple user avatars in a stacked row.

```tsx
import { DocyValueUserMulti } from '@/components/docyrus-native/value-renderers/docy-value-user-multi';

```

### DocyValueRelation

Related record display.

```tsx
import { DocyValueRelation } from '@/components/docyrus-native/value-renderers/docy-value-relation';

```

### DocyValueApprovalStatus

Approval status badge with icon.

```tsx
import { DocyValueApprovalStatus } from '@/components/docyrus-native/value-renderers/docy-value-approval-status';

```

### DocyValueList

List of values displayed as a vertical list.

```tsx
import { DocyValueList } from '@/components/docyrus-native/value-renderers/docy-value-list';

```

### DocyValueConversationChannel

Conversation channel display.

```tsx
import { DocyValueConversationChannel } from '@/components/docyrus-native/value-renderers/docy-value-conversation-channel';

```

### DocyValueFileStorageFolder

File storage folder path display.

```tsx
import { DocyValueFileStorageFolder } from '@/components/docyrus-native/value-renderers/docy-value-file-storage-folder';

```

### DocyValueRelatedField

Related field reference display.

```tsx
import { DocyValueRelatedField } from '@/components/docyrus-native/value-renderers/docy-value-related-field';

```

### DocyValueIdentity

Identity display.

```tsx
import { DocyValueIdentity } from '@/components/docyrus-native/value-renderers/docy-value-identity';

```

| Renderer | Value Type | Requires `enumOptions` |
|----------|-----------|----------------------|
| `DocyValueSelect` | `string` | Yes |
| `DocyValueMultiSelect` | `string[]` | Yes |
| `DocyValueStatus` | `string` | Yes |
| `DocyValueRadioGroup` | `string` | Yes |
| `DocyValueUser` | `{ name: string; avatar?: string }` | No |
| `DocyValueUserMulti` | `Array<{ name: string; avatar?: string }>` | No |
| `DocyValueRelation` | `{ id: string; title: string }` | No |
| `DocyValueApprovalStatus` | `string` | No |
| `DocyValueList` | `string[]` | No |
| `DocyValueConversationChannel` | `string` | No |
| `DocyValueFileStorageFolder` | `string` | No |
| `DocyValueRelatedField` | `{ field: string; value: unknown }` | No |
| `DocyValueIdentity` | `{ provider: string; identifier: string }` | No |

---

## Complex Renderers

### DocyValueDate

Formatted date display.

```tsx
import { DocyValueDate } from '@/components/docyrus-native/value-renderers/docy-value-date';

```

### DocyValueDatetime

Formatted date and time display.

```tsx
import { DocyValueDatetime } from '@/components/docyrus-native/value-renderers/docy-value-datetime';

```

### DocyValueTime

Formatted time display.

```tsx
import { DocyValueTime } from '@/components/docyrus-native/value-renderers/docy-value-time';

```

### DocyValueDateRange

Date range display with start and end dates.

```tsx
import { DocyValueDateRange } from '@/components/docyrus-native/value-renderers/docy-value-date-range';

```

### DocyValueFile

File display with name, icon, and size.

```tsx
import { DocyValueFile } from '@/components/docyrus-native/value-renderers/docy-value-file';

```

### DocyValueImage

Image thumbnail with dimensions.

```tsx
import { DocyValueImage } from '@/components/docyrus-native/value-renderers/docy-value-image';

```

### DocyValueAvatar

Avatar display with image or initials fallback.

```tsx
import { DocyValueAvatar } from '@/components/docyrus-native/value-renderers/docy-value-avatar';

```

### DocyValueCode

Code snippet display with syntax formatting.

```tsx
import { DocyValueCode } from '@/components/docyrus-native/value-renderers/docy-value-code';

```

### DocyValueJson

Formatted JSON display.

```tsx
import { DocyValueJson } from '@/components/docyrus-native/value-renderers/docy-value-json';

```

### DocyValueRichText

Rendered rich text content.

```tsx
import { DocyValueRichText } from '@/components/docyrus-native/value-renderers/docy-value-rich-text';

<DocyValueRichText field={richTextField} value="<p>Formatted <strong>content</strong></p>" />
```

### DocyValueDocEditor

Document editor content preview.

```tsx
import { DocyValueDocEditor } from '@/components/docyrus-native/value-renderers/docy-value-doc-editor';

```

### DocyValueTaskList

Task list with completion status indicators.

```tsx
import { DocyValueTaskList } from '@/components/docyrus-native/value-renderers/docy-value-task-list';

```

### DocyValueTodo

Single todo item with completion state.

```tsx
import { DocyValueTodo } from '@/components/docyrus-native/value-renderers/docy-value-todo';

```

### DocyValueInlineData

Inline data table display.

```tsx
import { DocyValueInlineData } from '@/components/docyrus-native/value-renderers/docy-value-inline-data';

```

### DocyValueCheckbox

Checkbox state display.

```tsx
import { DocyValueCheckbox } from '@/components/docyrus-native/value-renderers/docy-value-checkbox';

```

### DocyValueSwitch

Switch toggle state display.

```tsx
import { DocyValueSwitch } from '@/components/docyrus-native/value-renderers/docy-value-switch';

```

### DocyValueRating

Star rating display.

```tsx
import { DocyValueRating } from '@/components/docyrus-native/value-renderers/docy-value-rating';

```

### DocyValueButton

Button action display.

```tsx
import { DocyValueButton } from '@/components/docyrus-native/value-renderers/docy-value-button';

```

### DocyValueFormula

Formula result display.

```tsx
import { DocyValueFormula } from '@/components/docyrus-native/value-renderers/docy-value-formula';

```

### DocyValueLocation

Location or address display.

```tsx
import { DocyValueLocation } from '@/components/docyrus-native/value-renderers/docy-value-location';

```

| Renderer | Value Type | Output |
|----------|-----------|--------|
| `DocyValueDate` | `string` | Formatted date |
| `DocyValueDatetime` | `string` | Formatted date + time |
| `DocyValueTime` | `string` | Formatted time |
| `DocyValueDateRange` | `{ start: string; end: string }` | Date range with arrow |
| `DocyValueFile` | `{ name: string; size?: number }` | File icon + name + size |
| `DocyValueImage` | `{ url: string; width?: number; height?: number }` | Image thumbnail |
| `DocyValueAvatar` | `{ name: string; url?: string }` | Avatar circle |
| `DocyValueCode` | `string` | Formatted code block |
| `DocyValueJson` | `object` | Pretty-printed JSON |
| `DocyValueRichText` | `string` | Rendered HTML/rich text |
| `DocyValueDocEditor` | `object` | Document content preview |
| `DocyValueTaskList` | `Array<{ title: string; completed: boolean }>` | Checklist display |
| `DocyValueTodo` | `{ title: string; completed: boolean }` | Single todo item |
| `DocyValueInlineData` | `Array<Record<string, unknown>>` | Inline data table |
| `DocyValueCheckbox` | `boolean` | Checkbox icon |
| `DocyValueSwitch` | `boolean` | Switch toggle icon |
| `DocyValueRating` | `number` | Star rating |
| `DocyValueButton` | `{ label: string; url?: string }` | Button display |
| `DocyValueFormula` | `string \| number` | Formula result |
| `DocyValueLocation` | `{ address?: string; city?: string; lat?: number; lng?: number }` | Address/map display |

---

## Type Exports

| Type | Description |
|------|-------------|
| `DocyValueProps` | Shared props interface for all value renderers |
| `IField` | Field configuration type |
| `IFieldType` | Union of all supported field types |
| `EnumOption` | Enum option for select-based fields |

---

# rn-wheel-picker
URL: /docs/native/docyrus/wheel-picker

Scrollable wheel picker for selecting from a list of options with snap-to-item behavior.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-wheel-picker
```

## Usage

```tsx
import { WheelPicker } from '@/components/docyrus-native/wheel-picker';

const options = [
  { label: 'Red', value: 'red' },
  { label: 'Green', value: 'green' },
  { label: 'Blue', value: 'blue' },
];

<WheelPicker
  options={options}
  value={selected}
  onChange={(val) => setSelected(val)}
/>
```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `options` | `WheelPickerOption[]` | — | Array of selectable options |
| `value` | `string` | — | Currently selected value |
| `onChange` | `(value: string) => void` | — | Selection change handler |
| `itemHeight` | `number` | `44` | Height of each option row in pixels |
| `visibleItems` | `number` | `5` | Number of visible items in the wheel |
| `className` | `string` | — | Additional CSS classes |

### WheelPickerOption

| Prop | Type | Description |
|------|------|-------------|
| `label` | `string` | Display text |
| `value` | `string` | Option value |
| `disabled` | `boolean` | Whether the option is disabled |
| `icon` | `string` | Image URI for an icon |
| `initials` | `string` | Custom initials (auto-generated from label if not provided) |

## Type Exports

| Type | Description |
|------|-------------|
| `WheelPickerProps` | Props for WheelPicker component |
| `WheelPickerOption` | Option item configuration |

---

# ActionSheet
URL: /docs/native/expo/action-sheet

iOS-style bottom sheet with gesture-driven interactions, multiple detents, and optional Liquid Glass effect.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-action-sheet
```

```bash
# Optional: expo-glass-effect (for Liquid Glass variant on iOS 26+)
npx expo install expo-glass-effect
```

**Dependencies:**
- [react-native-gesture-handler](https://www.npmjs.com/package/react-native-gesture-handler)
- [react-native-reanimated](https://www.npmjs.com/package/react-native-reanimated)
- [react-native-worklets](https://www.npmjs.com/package/react-native-worklets)
- [expo-glass-effect](https://www.npmjs.com/package/expo-glass-effect)

> **Note:** `expo-glass-effect` is optional. ActionSheet works fully without it — the `glass` variant gracefully falls back to the `default` variant when the module is not installed or when running on non-iOS 26+ devices.

## Usage

```tsx
import { ActionSheet } from '@/components/docyrus-native/action-sheet';

const [visible, setVisible] = useState(false);

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `visible` | `boolean` | — | Whether the sheet is visible |
| `onClose` | `() => void` | — | Callback when the sheet is closed |
| `sheetId` | `string` | — | Unique ID for programmatic control via `SheetManager` |
| `variant` | `'default' \| 'elevated' \| 'minimal' \| 'glass'` | `'default'` | Sheet visual style variant |
| `detent` | `'small' \| 'medium' \| 'large' \| 'fit'` | `'medium'` | Sheet height detent |
| `detents` | `ActionSheetDetent[]` | — | Array of detents for multi-stop snapping |
| `title` | `string` | — | Sheet header title |
| `message` | `string` | — | Sheet header message below the title |
| `actions` | `ActionSheetAction[]` | — | Array of action items to display |
| `showCancel` | `boolean` | `true` | Show the cancel button at the bottom |
| `cancelLabel` | `string` | `'Cancel'` | Custom label for the cancel button |
| `showHandle` | `boolean` | `true` | Show the drag handle at the top |
| `closeOnBackdrop` | `boolean` | `true` | Close when tapping the backdrop |
| `glassEffectStyle` | `'regular' \| 'prominent' \| 'clear'` | — | Glass blur style (only with `variant="glass"`) |
| `glassTintColor` | `string` | — | Glass tint color override (only with `variant="glass"`) |
| `children` | `ReactNode` | — | Custom content instead of actions |
| `className` | `string` | — | Additional CSS classes |

### ActionSheetAction

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `key` | `string` | — | Unique identifier for the action |
| `label` | `string` | — | Action button text |
| `icon` | `string` | — | Emoji or text icon displayed before label |
| `destructive` | `boolean` | `false` | Style as destructive (red text) |
| `disabled` | `boolean` | `false` | Disable the action |
| `onPress` | `() => void` | — | Callback when the action is pressed |

## Type Exports

| Type | Description |
|------|-------------|
| `ActionSheetProps` | Props for ActionSheet component |
| `ActionSheetAction` | Action item configuration |
| `ActionSheetDetent` | `'small' \| 'medium' \| 'large' \| 'fit'` |

## Compatibility

| Platform | Support |
|----------|---------|
| Expo Go | Yes (glass variant falls back to default) |
| Dev Client | Yes |
| Bare RN | Yes (glass variant requires expo-glass-effect config plugin) |

---

# DocyFieldDateRange
URL: /docs/native/expo/date-range

Date range picker form field with start/end selector using native date picker.

## Overview

`DocyFieldDateRange` provides a start and end date picker. On iOS it uses an ActionSheet with tab-based Start/End switching; on Android it opens sequential native date picker dialogs.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-form-fields
```

```bash
# Required: @react-native-community/datetimepicker
npx expo install @react-native-community/datetimepicker
```

**Dependencies:**
- [@react-native-community/datetimepicker](https://www.npmjs.com/package/@react-native-community/datetimepicker)

## Usage

```tsx
import { DocyFieldDateRange } from '@/components/docyrus-native/form-fields/docy-field-date-range';

const [range, setRange] = useState<{
  startDate: Date | null;
  endDate: Date | null;
}>({ startDate: null, endDate: null });

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `DocyFieldDateRangeValue` | `{ startDate: null, endDate: null }` | Start and end dates |
| `onChange` | `(value: DocyFieldDateRangeValue) => void` | — | Called when value changes |
| `onBlur` | `() => void` | — | Blur handler |
| `onFocus` | `() => void` | — | Focus handler |
| `minimumDate` | `Date` | — | Minimum selectable date |
| `maximumDate` | `Date` | — | Maximum selectable date |
| `dateFormat` | `'short' \| 'medium' \| 'long' \| 'full'` | `'medium'` | Date format preset |
| `format` | `string` | — | Custom date pattern |
| `separator` | `string` | `' – '` | Separator between start and end display |
| `clearable` | `boolean` | `true` | Show clear button |
| `allowSameDate` | `boolean` | `true` | Allow start and end to be the same date |
| `calendarIcon` | `ReactNode` | — | Custom calendar icon |
| `clearIcon` | `ReactNode` | — | Custom clear icon |
| `iconSize` | `number` | `20` | Icon size in pixels |
| `iconColor` | `string` | — | Icon color override |

Inherits all [rn-form-fields](/docs/native/docyrus/form-fields) (name, label, placeholder, helpText, required, disabled, readOnly, error, size, variant, etc.)

## Platform Behavior

| Platform | Behavior |
|----------|----------|
| iOS | ActionSheet with Start/End tabs + spinner picker |
| Android | Sequential native date picker dialogs |
| Web | Fallback message (native picker not available) |

## Type Exports

| Type | Description |
|------|-------------|
| `DocyFieldDateRangeValue` | `{ startDate: Date \| null; endDate: Date \| null }` |
| `DocyFieldDateRangeProps` | Props for DocyFieldDateRange component |

## Compatibility

| Platform | Support |
|----------|---------|
| Expo Go | Yes |
| Dev Client | Yes |
| Bare RN | Yes (auto-linked) |

---

# DocyFieldDate
URL: /docs/native/expo/date

Native date/time picker form field using @react-native-community/datetimepicker.

## Overview

`DocyFieldDate` provides a native date, time, or datetime picker. On iOS it uses an ActionSheet with a spinner picker; on Android it opens the native dialog.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-form-fields
```

```bash
# Required: @react-native-community/datetimepicker
npx expo install @react-native-community/datetimepicker
```

**Dependencies:**
- [@react-native-community/datetimepicker](https://www.npmjs.com/package/@react-native-community/datetimepicker)

## Usage

```tsx
import { DocyFieldDate } from '@/components/docyrus-native/form-fields/docy-field-date';

const [date, setDate] = useState<Date | null>(null);

```

### Time Picker

```tsx

```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `Date \| null` | `null` | Selected date |
| `onChange` | `(date: Date \| null) => void` | — | Called when date changes |
| `onBlur` | `() => void` | — | Blur handler |
| `onFocus` | `() => void` | — | Focus handler |
| `mode` | `'date' \| 'datetime' \| 'time'` | `'date'` | Picker mode |
| `minimumDate` | `Date` | — | Minimum selectable date |
| `maximumDate` | `Date` | — | Maximum selectable date |
| `dateFormat` | `'short' \| 'medium' \| 'long' \| 'full'` | `'medium'` | Date format preset |
| `timeFormat` | `'12h' \| '24h'` | `'12h'` | Time format |
| `format` | `string` | — | Custom pattern (e.g., `"dd/MM/yyyy HH:mm"`) |
| `clearable` | `boolean` | `true` | Show clear button |
| `calendarIcon` | `ReactNode` | — | Custom calendar icon |
| `clearIcon` | `ReactNode` | — | Custom clear icon |
| `iconSize` | `number` | `20` | Icon size in pixels |
| `iconColor` | `string` | — | Icon color override |

Inherits all [rn-form-fields](/docs/native/docyrus/form-fields) (name, label, placeholder, helpText, required, disabled, readOnly, error, size, variant, etc.)

## Platform Behavior

| Platform | Behavior |
|----------|----------|
| iOS | ActionSheet with spinner picker + Cancel/Done buttons |
| Android | Native date picker dialog |
| Web | Fallback message (native picker not available) |

## Type Exports

| Type | Description |
|------|-------------|
| `DocyFieldDateProps` | Props for DocyFieldDate component |

## Compatibility

| Platform | Support |
|----------|---------|
| Expo Go | Yes |
| Dev Client | Yes |
| Bare RN | Yes (auto-linked) |

---

# DocyFieldDatetime
URL: /docs/native/expo/datetime

Combined date and time picker form field — thin wrapper around DocyFieldDate.

## Overview

`DocyFieldDatetime` is a convenience wrapper around [`DocyFieldDate`](/docs/native/expo/date) with `mode="datetime"` always set. It presents both a date and time picker in a single interaction.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-form-fields
```

```bash
# Required: @react-native-community/datetimepicker
npx expo install @react-native-community/datetimepicker
```

**Dependencies:**
- [@react-native-community/datetimepicker](https://www.npmjs.com/package/@react-native-community/datetimepicker)

## Usage

```tsx
import { DocyFieldDatetime } from '@/components/docyrus-native/form-fields/docy-field-datetime';

const [dateTime, setDateTime] = useState<Date | null>(null);

```

## API Reference

All props from [`DocyFieldDate`](/docs/native/expo/date) except `mode` (always `'datetime'`).

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `Date \| null` | `null` | Selected date and time |
| `onChange` | `(date: Date \| null) => void` | — | Called when value changes |
| `minimumDate` | `Date` | — | Minimum selectable date |
| `maximumDate` | `Date` | — | Maximum selectable date |
| `dateFormat` | `'short' \| 'medium' \| 'long' \| 'full'` | `'medium'` | Date format preset |
| `timeFormat` | `'12h' \| '24h'` | `'12h'` | Time format |
| `clearable` | `boolean` | `true` | Show clear button |

Inherits all [rn-form-fields](/docs/native/docyrus/form-fields) (name, label, placeholder, helpText, required, disabled, readOnly, error, size, variant, etc.)

## Type Exports

| Type | Description |
|------|-------------|
| `DocyFieldDatetimeProps` | `Omit<DocyFieldDateProps, 'mode'>` |

---

# Expo & Native Modules
URL: /docs/native/expo

Components that require Expo SDK modules or community native modules as additional dependencies.

## Overview

Some `@docyrus/ui-native` components depend on **Expo SDK modules** or **community native modules** for platform-specific features like file picking, date/time pickers, geolocation, or glass effects. These components work in Expo managed workflow projects and require the listed packages as additional dependencies.

If you're using a **bare React Native** project (without Expo), community native modules will auto-link, but Expo SDK modules require manual installation.

## Expo SDK Modules

| Component | Module | Purpose |
|-----------|--------|---------|
| [`ActionSheet`](/docs/native/expo/action-sheet) | `expo-glass-effect` | iOS Liquid Glass bottom sheet variant (iOS 26+) |
| [`DocyFieldUpload`](/docs/native/expo/upload) | `expo-document-picker` | File picking from device storage |

```bash
# expo-glass-effect (for ActionSheet glass variant, optional)
npx expo install expo-glass-effect

# expo-document-picker (for DocyFieldUpload)
npx expo install expo-document-picker
```

## Community Native Modules

| Component | Module | Purpose |
|-----------|--------|---------|
| [`DocyFieldDate`](/docs/native/expo/date) | `@react-native-community/datetimepicker` | Native date/time picker (iOS spinner, Android dialog) |
| [`DocyFieldDatetime`](/docs/native/expo/datetime) | `@react-native-community/datetimepicker` | Combined date & time picker |
| [`DocyFieldDateRange`](/docs/native/expo/date-range) | `@react-native-community/datetimepicker` | Date range picker with start/end selector |
| [`DocyFieldLocationSelect`](/docs/native/expo/location-select) | `@react-native-community/geolocation` + `react-native-geocoding` | Device GPS location + reverse geocoding |
| `localize` utilities | `react-native-localize` | Device locale, timezone, 24h clock detection |

```bash
# @react-native-community/datetimepicker (for DocyFieldDate, DocyFieldDatetime, DocyFieldDateRange)
npx expo install @react-native-community/datetimepicker

# @react-native-community/geolocation (for DocyFieldLocationSelect)
npx expo install @react-native-community/geolocation

# react-native-geocoding (for DocyFieldLocationSelect reverse geocoding)
npm install react-native-geocoding

# react-native-localize (for enhanced locale detection in localize utilities)
npx expo install react-native-localize
```

## Compatibility

| Module | Expo Go | Dev Client | Bare RN |
|--------|---------|------------|---------|
| `expo-glass-effect` | Yes | Yes | Requires config plugin |
| `expo-document-picker` | Yes | Yes | Requires config plugin |
| `@react-native-community/datetimepicker` | Yes | Yes | Yes (auto-linked) |
| `@react-native-community/geolocation` | No | Yes | Yes (auto-linked) |
| `react-native-geocoding` | Yes (JS only) | Yes | Yes |
| `react-native-localize` | Yes | Yes | Yes (auto-linked) |

All modules listed here are declared as **optional peer dependencies** in `@docyrus/ui-native`. Components gracefully handle missing modules at runtime — they won't crash your app if the module isn't installed, but the related functionality will be unavailable.

---

# Localize Utilities
URL: /docs/native/expo/localize

Device locale, timezone, and formatting utilities with react-native-localize fallback.

## Overview

The `localize` module provides device locale detection, timezone, date/number/currency formatting, and measurement system detection. It requires `react-native-localize` for accurate native locale data and falls back to `Intl` APIs when unavailable.

## Installation

```bash
npx expo install react-native-localize
```

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

### Expo Configuration

Add `react-native-localize` as a plugin in your `app.config.ts` with the locales your app supports:

```ts
{
  plugins: [
    [
      'react-native-localize',
      { locales: ['en', 'tr', 'de', 'fr'] }
    ]
  ]
}
```

> **Note:** Without this plugin config, locale detection may not work correctly on iOS. The `locales` array determines which languages your app declares support for.

## Usage

```tsx
import {
  getDeviceLocale,
  getDeviceLanguage,
  getDeviceCountry,
  getDeviceTimeZone,
  uses24HourClock,
  usesMetricSystem,
  formatDate,
  formatNumber,
  formatCurrency,
} from '@/lib/localize';

// Device info
const locale = getDeviceLocale();        // 'tr-TR'
const lang = getDeviceLanguage();        // 'tr'
const country = getDeviceCountry();      // 'TR'
const tz = getDeviceTimeZone();          // 'Europe/Istanbul'
const is24h = uses24HourClock();         // true
const metric = usesMetricSystem();       // true

// Formatting
formatDate(new Date(), { dateStyle: 'long' });   // '5 Mart 2026'
formatNumber(1234.56);                            // '1.234,56'
formatCurrency(99.99, 'TRY');                     // '₺99,99'
```

## API Reference

### Device Info

| Function | Return Type | Description |
|----------|-------------|-------------|
| `getDeviceLocale()` | `string` | Full locale tag (e.g., `'tr-TR'`). Falls back to `'en-US'` |
| `getDeviceLanguage()` | `string` | Language code (e.g., `'tr'`). Falls back to `'en'` |
| `getDeviceCountry()` | `string \| undefined` | Country code (e.g., `'TR'`) |
| `getDeviceTimeZone()` | `string` | IANA timezone (e.g., `'Europe/Istanbul'`). Falls back to `'UTC'` |
| `uses24HourClock()` | `boolean` | Whether device uses 24-hour clock |
| `usesMetricSystem()` | `boolean` | Whether device uses metric system |
| `getPreferredLocales()` | `string[]` | All preferred locale tags |

### Formatting

| Function | Parameters | Description |
|----------|-----------|-------------|
| `formatNumber(value, options?, locale?)` | `number, Intl.NumberFormatOptions?, string?` | Locale-aware number formatting |
| `formatDate(date, options?, locale?)` | `Date, Intl.DateTimeFormatOptions?, string?` | Locale-aware date formatting |
| `formatCurrency(value, currencyCode?, locale?)` | `number, string?, string?` | Currency formatting (default: `'USD'`) |
| `getCurrencySymbol(currencyCode)` | `string` | Get currency symbol (e.g., `'₺'` for `'TRY'`) |

## Fallback Behavior

| Feature | With `react-native-localize` | Without (Intl fallback) |
|---------|------------------------------|------------------------|
| Locale detection | Device's preferred locale list | `Intl.DateTimeFormat` resolved locale |
| Timezone | `RNLocalize.getTimeZone()` | `Intl.DateTimeFormat` resolved timezone |
| 24h clock | `RNLocalize.uses24HourClock()` | AM/PM presence check |
| Metric system | `RNLocalize.usesMetricSystem()` | Country code heuristic (US, LR, MM → imperial) |

## Compatibility

| Platform | Support |
|----------|---------|
| Expo Go | Yes |
| Dev Client | Yes |
| Bare RN | Yes (auto-linked) |

---

# Location Select
URL: /docs/native/expo/location-select

Location picker field with device geolocation and reverse geocoding support.

## Overview

`DocyFieldLocationSelect` uses **community native modules** for device-specific location features:

- **`@react-native-community/geolocation`** — Access device GPS to get current coordinates
- **`react-native-geocoding`** — Reverse geocode coordinates to human-readable addresses (requires Google Maps API key)

Without these modules installed, the location picker still works with manual text search and predefined locations — but the "Use Current Location" button will be unavailable.

## Installation

```bash
# Geolocation (for "Use Current Location" feature)
npx expo install @react-native-community/geolocation

# Reverse geocoding (for converting coordinates to addresses)
npm install react-native-geocoding
```

### Google Maps API Key

Reverse geocoding requires a Google Maps Geocoding API key. Pass it as a prop or set the `EXPO_PUBLIC_GOOGLE_MAPS_API_KEY` environment variable:

```tsx

```

## Compatibility

| Module | Expo Go | Dev Client | Bare RN |
|--------|---------|------------|---------|
| `@react-native-community/geolocation` | No | Yes | Yes (auto-linked) |
| `react-native-geocoding` | Yes (JS only) | Yes | Yes |

> **Note:** `@react-native-community/geolocation` requires a **development build** — it does not work in Expo Go. The component handles this gracefully at runtime.

## Usage

```tsx
import { DocyFieldLocationSelect } from '@/components/docyrus-native/form-fields/docy-field-location-select';

<DocyFieldLocationSelect
  label="Office Location"
  allowCurrentLocation
  showCoordinates
  requestLocationPermission={async () => {
    // Your permission handling logic
    return 'granted';
  }}
  onChange={(location) => console.log(location)}
/>
```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `LocationInfo` | — | Current location value |
| `onChange` | `(value: LocationInfo) => void` | — | Called when location changes |
| `placeholder` | `string` | `'Select location'` | Placeholder text |
| `allowCurrentLocation` | `boolean` | `true` | Show "Use Current Location" button |
| `showCoordinates` | `boolean` | `true` | Show coordinates under location items |
| `predefinedLocations` | `LocationInfo[]` | Popular cities | Custom location list |
| `requestLocationPermission` | `() => Promise<'granted' \| 'denied'>` | — | Permission request callback |
| `googleMapsApiKey` | `string` | `EXPO_PUBLIC_GOOGLE_MAPS_API_KEY` | Google Maps API key for geocoding |

### LocationInfo Type

| Field | Type | Description |
|-------|------|-------------|
| `name` | `string` | Display name |
| `address` | `string?` | Full address |
| `coordinates` | `{ latitude: number; longitude: number }?` | GPS coordinates |
| `country` | `string?` | Country name |
| `city` | `string?` | City name |
| `region` | `string?` | Region/state |
| `postalCode` | `string?` | Postal code |
| `type` | `'current' \| 'saved' \| 'search'?` | Location source |

---

# DocyFieldUpload
URL: /docs/native/expo/upload

File upload form field using expo-document-picker for native file selection.

## Overview

`DocyFieldUpload` provides a native file picker using `expo-document-picker`. Users can select single or multiple files from device storage with configurable file type filters and size limits.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-form-fields
```

```bash
# Required: expo-document-picker
npx expo install expo-document-picker
```

**Dependencies:**
- [expo-document-picker](https://www.npmjs.com/package/expo-document-picker)

## Usage

```tsx
import { DocyFieldUpload } from '@/components/docyrus-native/form-fields/docy-field-upload';

<DocyFieldUpload
  name="attachments"
  label="Attachments"
  maxFiles={5}
  maxSizeBytes={10 * 1024 * 1024}
  allowedTypes={['application/pdf', 'image/*']}
  onChange={(files) => console.log(files)}
/>
```

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `UploadedFile[]` | `[]` | Array of uploaded files |
| `onChange` | `(files: UploadedFile[]) => void` | — | Called when files change |
| `maxFiles` | `number` | `10` | Maximum number of files allowed |
| `maxSizeBytes` | `number` | — | Max size per file in bytes |
| `allowedTypes` | `string[]` | `['*/*']` | MIME type filters |
| `onUpload` | `(files: UploadedFile[]) => Promise<void>` | — | Optional upload handler |
| `uploadLabel` | `string` | `'Select files'` | Custom button label |

Inherits all [rn-form-fields](/docs/native/docyrus/form-fields) (name, label, placeholder, helpText, required, disabled, readOnly, error, size, variant, etc.)

## Type Exports

| Type | Description |
|------|-------------|
| `UploadedFile` | `{ uri: string; name: string; size: number; mimeType: string }` |
| `DocyFieldUploadProps` | Props for DocyFieldUpload component |

## Compatibility

| Platform | Support |
|----------|---------|
| Expo Go | Yes |
| Dev Client | Yes |
| Bare RN | Requires config plugin |

---

# Distributions
URL: /docs/native/guide/distributions

Core libraries that power Docyrus UI native components.

Docyrus UI native components are built on top of the React Native and Expo ecosystems. Most dependencies are **optional peer dependencies** — you only need to install them if you use the components that require them.

## Core Libraries

| Library | Description | Used In |
|---------|-------------|---------|
| [TanStack Table](https://tanstack.com/table) | Headless table library with sorting, filtering, grouping, and virtualization. | Data Table |
| [JSONata](https://jsonata.org) | Lightweight query and transformation language for JSON data. | Pivot Grid |

## UI & Graphics

| Library | Description | Required |
|---------|-------------|----------|
| [React Native SVG](https://github.com/software-mansion/react-native-svg) | SVG support for icons, charts, and vector graphics. | Optional |
| [React Native Safe Area Context](https://github.com/th3rdwave/react-native-safe-area-context) | Safe area insets for notches and system bars. | Optional |
| [React Native QRCode SVG](https://github.com/nicholaslee119/react-native-qrcode-svg) | QR code generation as SVG. | Optional |
| [Expo Glass Effect](https://docs.expo.dev/versions/latest/sdk/glass-effect) | Glassmorphism blur effects for overlays and panels. | Optional |

## Animation & Gestures

| Library | Description | Required |
|---------|-------------|----------|
| [React Native Reanimated](https://docs.swmansion.com/react-native-reanimated) | High-performance animation library running on the UI thread. | Optional |
| [React Native Gesture Handler](https://docs.swmansion.com/react-native-gesture-handler) | Native gesture system for swipe, pinch, and drag interactions. | Optional |
| [React Native Worklets](https://github.com/nicholasgasior/react-native-worklets) | Worklet runtime for running JS on the UI thread. | Optional |

## Expo Modules

| Module | Description | Required |
|--------|-------------|----------|
| [Expo Document Picker](https://docs.expo.dev/versions/latest/sdk/document-picker) | Native file picker with multi-file support. | Optional |
| [Expo File System](https://docs.expo.dev/versions/latest/sdk/filesystem) | File system access for reading, writing, and managing files. | Optional |
| [Expo Sharing](https://docs.expo.dev/versions/latest/sdk/sharing) | Native share dialog for sharing files and content. | Optional |

## Maps & Location

| Library | Description | Required |
|---------|-------------|----------|
| [React Native Maps](https://github.com/react-native-maps/react-native-maps) | Google Maps and Apple Maps integration for React Native. | Optional |
| [@react-native-community/geolocation](https://github.com/michalchudziak/react-native-geolocation) | Geolocation API for accessing device location. | Optional |
| [React Native Geocoding](https://github.com/marlove/react-native-geocoding) | Geocoding and reverse geocoding services. | Optional |

## Date & Localization

| Module | Description | Required |
|--------|-------------|----------|
| [DateTimePicker](https://github.com/react-native-datetimepicker/datetimepicker) | Native date and time picker for iOS and Android. | Optional |
| [React Native Localize](https://github.com/zoontek/react-native-localize) | Locale detection and internationalization utilities. | Optional |

---

# Examples & Recipes
URL: /docs/native/guide/examples

Practical patterns and recipes for building React Native apps with Docyrus UI Native.

Real-world patterns that combine multiple Docyrus UI Native components. These examples assume you have the Expo + Docyrus UI Native setup from the [installation guide](/docs/native/guide/installation).

## List with Search and Filters

A searchable list view with pull-to-refresh and empty state handling:

```tsx
import { useState, useCallback } from 'react';
import { View, FlatList, RefreshControl } from 'react-native';

import { SearchInput } from '@/components/docyrus-native/search-input';
import { ListBox } from '@/components/docyrus-native/list-box';
import { EmptyState } from '@/components/docyrus-native/empty-state';
import { Badge } from '@/components/docyrus-native/badge';
import { Spinner } from '@/components/docyrus-native/spinner';

export function ContactList() {
  const [search, setSearch] = useState('');
  const [refreshing, setRefreshing] = useState(false);

  const filtered = contacts.filter((c) =>
    c.name.toLowerCase().includes(search.toLowerCase())
  );

  const onRefresh = useCallback(async () => {
    setRefreshing(true);
    await fetchContacts();
    setRefreshing(false);
  }, []);

  return (
    

      {filtered.length === 0 ? (
        
      ) : (
        
              }
              onPress={() => router.push(`/contact/${item.id}`)}
            />
          )}
        />
      )}
    
  );
}
```

## Form Screen

A multi-field form with validation using Docyrus form fields:

```tsx
import { View, ScrollView, KeyboardAvoidingView, Platform } from 'react-native';

import { Input } from '@/components/docyrus-native/input';
import { Textarea } from '@/components/docyrus-native/textarea';
import { Select } from '@/components/docyrus-native/select';
import { Switch } from '@/components/docyrus-native/switch';
import { Button } from '@/components/docyrus-native/button';
import { Label } from '@/components/docyrus-native/label';

const priorities = [
  { label: 'Low', value: 'low' },
  { label: 'Medium', value: 'medium' },
  { label: 'High', value: 'high' },
];

export function CreateTaskScreen() {
  const [title, setTitle] = useState('');
  const [description, setDescription] = useState('');
  const [priority, setPriority] = useState('medium');
  const [notify, setNotify] = useState(true);

  return (
    
            
          

          
            
          

          
            
          

          
            
          
        
      

      
      
    
  );
}
```

## Dashboard with Stats and Charts

A mobile dashboard combining stats cards, charts, and quick actions:

```tsx
import { ScrollView, View } from 'react-native';

import { AwesomeStats } from '@/components/docyrus-native/awesome-stats';
import { AwesomeCard } from '@/components/docyrus-native/awesome-card';
import { Button } from '@/components/docyrus-native/button';
import { Badge } from '@/components/docyrus-native/badge';
import { Separator } from '@/components/docyrus-native/separator';

export function DashboardScreen() {
  return (
    

      

      {/* Quick actions */}
      
        
        
      

      {/* Recent activity */}
      
              
                
              
            
          ))}
        
      
    
  );
}
```

## Data Table with Actions

A native data table with sorting, row actions, and delete confirmation:

```tsx
import { View } from 'react-native';

import { DataTable } from '@/components/docyrus-native/data-table';
import { DeleteConfirmDialog } from '@/components/docyrus-native/delete-confirm-dialog';
import { ActionSheet } from '@/components/docyrus-native/action-sheet';
import { Toast } from '@/components/docyrus-native/toast';

export function ProductsScreen() {
  const [deleteId, setDeleteId] = useState<string | null>(null);
  const [actionItem, setActionItem] = useState
  );
}
```

## Tab Navigation with Stepper

Multi-step wizard flow using tabs and a stepper component:

```tsx
import { useState } from 'react';
import { View, ScrollView } from 'react-native';

import { Tabs } from '@/components/docyrus-native/tabs';
import { Stepper } from '@/components/docyrus-native/stepper';
import { Button } from '@/components/docyrus-native/button';
import { Input } from '@/components/docyrus-native/input';
import { Label } from '@/components/docyrus-native/label';

const steps = [
  { title: 'Account', description: 'Basic info' },
  { title: 'Profile', description: 'Your details' },
  { title: 'Review', description: 'Confirm' },
];

export function OnboardingScreen() {
  const [step, setStep] = useState(0);

  return (
    

      
              
            
            
              
            
          
        )}

        {step === 1 && (
          
              
            
            
              
            
          
        )}

        {step === 2 && (
          
        )}
      

      
        )}
        
      
    
  );
}
```

## Related

- [Installation](/docs/native/guide/installation) — Set up Docyrus UI Native in your Expo project
- [Components](/docs/native/components) — Browse all native components
- [Theming](/docs/native/guide/theming) — Customize the native theme

---

# Installation
URL: /docs/native/guide/installation

How to install and set up Docyrus UI native components in your Expo project.

## Preview App Install

Scan the QR code to open the Expo install page. This installs the latest internal development build on a provisioned device.

## Prerequisites

Docyrus UI native components require an Expo project with React Native. Make sure your environment meets these requirements:

| Dependency | Minimum Version |
|---|---|
| React | 19 |
| React Native | 0.79 |
| Expo SDK | 53 |
| Node.js | 18 |

## Install the CLI

Install the Docyrus CLI globally or use it via npx:

```bash
npm install -g @docyrus/cli
```

## Add native components

Install native components using the `rn-` prefix:

```bash
# Install a native component
npx @docyrus/cli add rn-button

# Install multiple native components
npx @docyrus/cli add rn-button rn-input rn-card

# Install all native components
npx @docyrus/cli add --all-rn
```

Components are installed to your `components/docyrus-native/` directory.

## Install peer dependencies

Native components require Tailwind CSS v4 for React Native via **Uniwind**, plus common React Native libraries:

```bash
# Tailwind CSS v4 for React Native (required)
npx expo install uniwind tailwindcss

# Common peer dependencies
npx expo install react-native-svg
npx expo install react-native-reanimated
npx expo install react-native-gesture-handler
```

Component styling also uses these packages (installed automatically by the CLI):

```bash
npm install tailwind-variants clsx tailwind-merge
```

## Set up Uniwind

Docyrus Native components use `className` prop for styling via Uniwind — a build-time Tailwind CSS v4 integration for React Native.

### 1. Configure Metro

Add the Uniwind Metro plugin to your `metro.config.js`:

```js title="metro.config.js"
const { getDefaultConfig } = require('expo/metro-config');
const { withUniwindConfig } = require('uniwind/metro');

const config = getDefaultConfig(__dirname);

module.exports = withUniwindConfig(config, {
  cssEntryFile: './src/styles/global.css'
});
```

### 2. Create global CSS

Create a `src/styles/global.css` file with Tailwind and Uniwind directives:

```css title="src/styles/global.css"
@import "tailwindcss";
@import "uniwind";
```

### 3. Import in your app entry

Import the global CSS at the top of your root layout:

```tsx title="app/_layout.tsx"
import '../styles/global.css';

import { DocyThemeProvider } from '@/lib/theme';

export default function RootLayout() {
  return (
    
  );
}
```

## Set up the theme

Wrap your app with `DocyThemeProvider` at the root level. See the [Theming](/docs/native/guide/theming) guide for full configuration options.

```tsx title="app/_layout.tsx"
import { DocyThemeProvider } from '@/lib/theme';

export default function RootLayout() {
  return (
    
  );
}
```

## Keyboard handling (recommended)

Form components like Input, Textarea, and Modal work best with `react-native-keyboard-controller`. It prevents inputs from being hidden behind the keyboard and provides smooth animated transitions.

```bash
npx expo install react-native-keyboard-controller
```

Wrap your app with `KeyboardProvider` at the root level:

```tsx title="app/_layout.tsx"
import '../styles/global.css';

import { KeyboardProvider } from 'react-native-keyboard-controller';

import { DocyThemeProvider } from '@/lib/theme';

export default function RootLayout() {
  return (
    
    
  );
}
```

Once the provider is active, all screens — including modals with `KeyboardAvoidingView` — automatically benefit from improved keyboard behavior.

## Import and use

Once installed, import native components and use them in your screens. All components accept a `className` prop for Tailwind-based styling:

```tsx title="app/index.tsx"
import { View } from 'react-native';

import { Button } from '@/components/docyrus-native/button';

export default function Home() {
  return (
    
    
  );
}
```

Components are installed as source code — you can freely modify, extend, or restyle them to fit your needs.

---

# Releases
URL: /docs/native/guide/releases

Latest releases and updates for Docyrus UI Native components.

Track the latest changes, features, and bug fixes for the `@docyrus/ui-native` React Native component library.

---

# RN Assistant
URL: /docs/native/guide/rn-assistant

Install, configure, and integrate DocyrusRNAssistant in an Expo or React Native app.

[![npm version](https://img.shields.io/npm/v/%40docyrus%2Frn-assistant?label=npm&logo=npm&color=16a34a)](https://www.npmjs.com/package/@docyrus/rn-assistant)

`@docyrus/rn-assistant` is a standalone React Native assistant package for Docyrus-compatible backends. It is designed to be embedded into an existing host app without depending on app-local aliases, project-specific folders, or direct `.env` reads inside the package.

The package includes:

- Chat UI with streaming responses
- Session/thread management
- Model and reasoning selection
- File attachments and voice recording
- Built-in theme surface

## Installation

```bash tab="pnpm"
pnpm add @docyrus/rn-assistant
pnpm add react react-native expo react-native-keyboard-controller react-native-safe-area-context react-native-svg
```

```bash tab="npm"
npm install @docyrus/rn-assistant react react-native expo react-native-keyboard-controller react-native-safe-area-context react-native-svg
```

| Dependency | Version |
|---|---|
| React | 19+ |
| React Native | 0.83+ |
| Expo | 55+ |
| `react-native-keyboard-controller` | 1.20.7+ |
| `react-native-safe-area-context` | 5.6.2+ |
| `react-native-svg` | 15.15.3+ |

### Root providers

Wrap your app root with these providers:

```tsx title="app/_layout.tsx"
import { SafeAreaProvider } from 'react-native-safe-area-context';
import { KeyboardProvider } from 'react-native-keyboard-controller';

export default function RootLayout() {
  return (
    
    
  );
}
```

## Configuration

### Environment variables

The package does not read env values itself. Your host app should read env variables and turn them into props/config.

```txt
EXPO_PUBLIC_API_BASE_URL=
EXPO_PUBLIC_ASSISTANT_AGENT_ID=
EXPO_PUBLIC_ASSISTANT_DATA_SOURCE_ID=
EXPO_PUBLIC_OAUTH2_CLIENT_ID=
EXPO_PUBLIC_OAUTH2_SCOPES=openid profile offline_access User.Read Users.Read.All DS.Read.All DS.ReadWrite.All AI.Read.All AI.ReadWrite.All
EXPO_PUBLIC_OAUTH2_CALLBACK_URL=appName://auth/callback
```

### Create assistant config

```tsx
import { createDocyrusRNAssistantConfig } from '@docyrus/rn-assistant';

const assistantConfig = createDocyrusRNAssistantConfig({
  baseUrl: process.env.EXPO_PUBLIC_API_BASE_URL || '',
  getToken: async () => auth.tokens?.accessToken || null,
});
```

You can also pass a direct `token`, but `getToken` is better for host-managed auth refresh.

### Authentication and scopes

The assistant requires a valid authenticated token from the host app.

Recommended scope set:

- `User.Read`, `Users.Read.All`
- `DS.Read.All`, `DS.ReadWrite.All`
- `AI.Read.All`, `AI.ReadWrite.All`

At minimum, assistant deployment loading requires `AI.Read.All` or `AI.ReadWrite.All`.

> If you change OAuth scopes, the user must **sign out and sign in again**. Changing env values alone does not upgrade an already-issued token.

## Usage

  
  

The host app should choose one presentation path at a time. Avoid rendering a page assistant and opening a second assistant sheet on top of it.

## iOS Permissions

If voice recording or media attachments are enabled, define native permission strings in the **host app**:

```ts title="app.config.ts"
export default {
  expo: {
    ios: {
      infoPlist: {
        NSMicrophoneUsageDescription: 'Uses the microphone for voice prompts.',
        NSCameraUsageDescription: 'Uses the camera to attach photos.',
        NSPhotoLibraryUsageDescription: 'Uses your photo library to attach images.',
      }
    }
  }
};
```

- These keys belong to the host app, not the package
- After changing permission strings, rebuild with `run:ios`
- Microphone permission is requested when recording starts, not on first render

## API Reference

  

## Troubleshooting

### 403 on deployment fetch

```txt
Client is not authorized to access this resource. One of the following scopes is required: AI.Read.All, AI.ReadWrite.All
```

Fix: add `AI.Read.All` or `AI.ReadWrite.All` to your OAuth scopes, sign out, and sign in again.

### iOS crashes on microphone access

Fix: add the required `ios.infoPlist` keys in the host app and rebuild with `run:ios`.

### Env changes do not apply

For Expo apps, restart the dev server after changing `EXPO_PUBLIC_*` values.

## Related

- [Native Installation](/docs/native/guide/installation)
- [Native Theming](/docs/native/guide/theming)
- [API Reference](/docs/guide/api-reference)

---

# Theming
URL: /docs/native/guide/theming

Customize the look and feel of Docyrus UI Native components with DocyThemeProvider, color schemes, and Tailwind CSS.

## Overview

Docyrus UI Native uses **Tailwind CSS v4** via Uniwind for component styling. Static styles are expressed as `className` using Tailwind utility classes and semantic color tokens (`bg-card`, `text-foreground`, `border-border`). Dynamic values that can't be expressed as className (DocyrusIcon colors, platform shadows, runtime color lookups) are accessed via the `useDocyTheme()` hook.

## Setup

Wrap your app root with `DocyThemeProvider`:

```tsx title="app/_layout.tsx"
import '../src/global.css';

import { DocyThemeProvider } from '@/lib/theme';

export default function RootLayout() {
  return (
    
  );
}
```

### Provider Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `colorScheme` | `ColorScheme` | — | Controlled color scheme |
| `mode` | `ThemeMode` | — | Controlled theme mode |
| `lang` | `ThemeLanguage` | — | Controlled language |
| `defaultColorScheme` | `ColorScheme` | `'docyrus'` | Initial color scheme |
| `defaultMode` | `ThemeMode` | `'system'` | Initial theme mode |
| `defaultLang` | `ThemeLanguage` | `'en'` | Initial language |
| `brand` | `Record<string, string>` | — | Custom brand colors |
| `fontFamily` | `ThemeFontFamily` | System fonts | Custom font family |
| `messages` | `Record<string, any>` | — | Custom i18n messages |

## Styling with Tailwind className

All components accept a `className` prop for Tailwind-based styling. Use semantic color tokens for theme-aware colors:

```tsx
import { View, Text } from 'react-native';

function MyCard() {
  return (
    
      
    
  );
}
```

### className vs style Decision Guide

| Use Case | Approach | Example |
|----------|----------|---------|
| Static layout/colors | `className` | `className="flex-1 p-4 bg-card rounded-lg"` |
| Semantic colors | `className` | `className="text-foreground bg-primary/10"` |
| Dark mode | `className` | `className="bg-muted dark:bg-background"` |
| Pressable states | `className` | `className="active:opacity-70 active:scale-95"` |
| Animated values | `style` | `style={{ opacity: fadeAnim }}` |
| Platform shadows | `style` | `style={cardShadow(isDark, colors.border)}` |
| DocyrusIcon color | `color` prop | `color={colors.primary}` |
| Dynamic theme lookup | `style` | `style={{ backgroundColor: colors[key] }}` |

## useDocyTheme Hook

Access theme values for **dynamic use cases only** — static styling should use Tailwind className:

```tsx
import { useDocyTheme } from '@/lib/theme';
import { DocyrusIcon } from '@/components/docyrus-native/docyrus-icon';

function MyComponent() {
  const { colors, isDark } = useDocyTheme();

  return (
    
    
  );
}
```

### Theme Object

```tsx
const theme = useDocyTheme();

theme.colors        // ThemeColors — semantic + Tailwind palette
theme.spacing       // ThemeSpacing — numeric scale
theme.borderRadius  // ThemeBorderRadius
theme.fieldHeight   // ThemeFieldHeight
theme.fontFamily    // ThemeFontFamily
theme.isDark        // boolean — for conditional logic
theme.colorScheme   // 'docyrus' | 'slate' | 'gray' | 'zinc' | ...
theme.mode          // 'light' | 'dark' | 'system'
theme.lang          // 'en' | 'tr'
theme.brand         // Custom brand object
theme.messages      // i18n messages
```

## Color Schemes

Docyrus UI Native ships with **13 color schemes**, each providing light and dark variants:

### Base Schemes (Neutral)

| Scheme | Description |
|--------|-------------|
| `slate` | Blue-gray neutral tones |
| `gray` | Pure gray neutral tones |
| `zinc` | Warm gray neutral tones |
| `stone` | Warm beige neutral tones |
| `neutral` | True neutral (no hue) |

### Accent Schemes

| Scheme | Primary Color | Base |
|--------|--------------|------|
| `docyrus` | Slate + Blue accent | Slate |
| `red` | Red 600 | Zinc |
| `rose` | Rose 600 | Zinc |
| `orange` | Orange 500 | Stone |
| `green` | Green 600 | Zinc |
| `blue` | Blue 500 | Slate |
| `yellow` | Yellow 500 | Stone |
| `violet` | Violet 500 | Gray |

```tsx

```

## Semantic Color Tokens

Every color scheme provides these semantic tokens, available as both Tailwind classes and `colors.*` values:

| Token | Tailwind Class | JS Access | Description |
|-------|---------------|-----------|-------------|
| `background` | `bg-background` | `colors.background` | App background |
| `foreground` | `text-foreground` | `colors.foreground` | Primary text |
| `card` | `bg-card` | `colors.card` | Card surfaces |
| `primary` | `bg-primary` | `colors.primary` | Primary actions |
| `secondary` | `bg-secondary` | `colors.secondary` | Secondary surfaces |
| `muted` | `bg-muted` | `colors.muted` | Muted backgrounds |
| `destructive` | `bg-destructive` | `colors.destructive` | Destructive actions |
| `border` | `border-border` | `colors.border` | Borders |
| `success` | `bg-success` | `colors.success` | Success states |
| `warning` | `bg-warning` | `colors.warning` | Warning states |
| `info` | `bg-info` | `colors.info` | Info states |

**Use Tailwind classes for static colors** (`className="bg-card text-foreground"`). **Use `colors.*` only when a raw color string is needed** (DocyrusIcon, chart libraries, `cardShadow()`, runtime lookups).

### Tailwind Color Palette

In addition to semantic tokens, `colors` includes the full Tailwind palette (50–950 shades):

```tsx
const { colors } = useDocyTheme();

// Only needed for dynamic runtime lookups — prefer className for static colors
colors.blue[500]    // '#3b82f6'
colors.red[600]     // '#dc2626'
colors.emerald[400] // '#34d399'
```

Available palettes: `red`, `orange`, `amber`, `yellow`, `lime`, `green`, `emerald`, `teal`, `cyan`, `sky`, `blue`, `indigo`, `violet`, `purple`, `fuchsia`, `pink`, `rose`.

## Dark Mode

### With Tailwind Classes

Components support dark mode variants via Tailwind:

```tsx

```

### System-Based (Default)

```tsx

      
      
    
  );
}
```

### Checking Dark Mode

Use `isDark` for logic that can't be expressed as className (platform shadows, conditional rendering):

```tsx
const { isDark, colors } = useDocyTheme();

// Platform shadows need style prop — no Tailwind equivalent

  );
}
```

## Brand Colors

Add custom brand-specific colors available throughout the theme:

```tsx
type MyBrand = {
  accentBlue: string;
  accentGold: string;
  headerBg: string;
};

<DocyThemeProvider<MyBrand>
  brand={{
    accentBlue: '#1E90FF',
    accentGold: '#FFD700',
    headerBg: '#0A1128',
  }}
>
```

Access brand colors in components:

```tsx
const { brand } = useDocyTheme<MyBrand>();

// Brand colors are dynamic — use style prop
<View style={{ backgroundColor: brand?.headerBg }}>
```

## Localization

The provider supports language via the `lang` prop:

```tsx
<DocyThemeProvider lang="tr">
```

Currently supported: `'en'` (English), `'tr'` (Turkish).

```tsx
const { lang, messages } = useDocyTheme();
```

## Web vs Native Comparison

| Feature | Web (CSS Variables) | Native (Tailwind + Theme) |
|---------|--------------------|-----------------------|
| Static styling | `className="bg-primary p-4"` | `className="bg-primary p-4"` |
| Token access | `var(--primary)` in CSS | `className="bg-primary"` or `colors.primary` |
| Dark mode | `.dark` class + CSS | `className="dark:bg-background"` or `isDark` |
| Color scheme | CSS variable swap | `colorScheme` prop on provider |
| Custom colors | CSS variable override | `brand` prop |
| Fonts | CSS `font-family` | `fontFamily` prop |
| Animated values | CSS transitions / motion | `style` prop with Animated/Reanimated |
| 3rd-party colors | CSS variable reference | `colors.*` from `useDocyTheme()` |

---

# Troubleshooting
URL: /docs/native/guide/troubleshooting

Common issues and solutions when using Docyrus UI native components.

## Verify your versions

Make sure your environment meets or exceeds these minimum versions.

| Dependency | Minimum Version |
|---|---|
| React | 19 |
| React Native | 0.79 |
| Expo SDK | 53 |
| Node.js | 18 |

## Theme not applying

Make sure your app is wrapped with `DocyThemeProvider` at the root level. Without this provider, components will fall back to default styles. If using Expo Router, wrap it in your root `_layout.tsx`.

```tsx title="app/_layout.tsx"
import { DocyThemeProvider } from '@/lib/theme';

export default function RootLayout() {
  return (
    
  );
}
```

## Expo Go compatibility

Some native components require a development build and won't work in Expo Go. Check the component's documentation for Expo Go compatibility. Components that use native modules require `npx expo prebuild` and a custom dev client:

```bash
npx expo prebuild
npx expo run:ios
```

## Missing peer dependencies

Native components declare peer dependencies for packages like `react-native-svg`, `expo-document-picker`, and `expo-localization`. If you see module resolution errors, install the required dependency:

```bash
npx expo install react-native-svg
npx expo install expo-document-picker
npx expo install expo-localization
```

## Font Awesome icons not loading

If `DocyrusIcon` is not rendering icons, make sure you've configured the icon CDN path correctly. Native icons are loaded from the Docyrus CDN — verify your network connectivity and that the icon name matches the registry.

## React Native Reanimated errors

If you see errors related to Reanimated, make sure you've added the Babel plugin:

```js title="babel.config.js"
module.exports = function(api) {
  api.cache(true);
  return {
    presets: ['babel-preset-expo'],
    plugins: ['react-native-reanimated/plugin'],
  };
};
```

## Metro bundler cache issues

If you're seeing stale code or unexpected errors after installing new components, clear the Metro cache:

```bash
npx expo start --clear
```

## 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/native/hooks

Reusable React hooks for common patterns.

Reusable React hooks for common UI patterns. Each hook is installed as source code into your project, fully typed with TypeScript.

## Available Hooks

No public hooks yet.

---

# Overview
URL: /docs/native/utilities

Helper functions and data utilities for Docyrus UI.

Browse all available Docyrus UI utilities. Each utility is installed as source code into your project.

## Available Utilities

No public utilities yet.

---

# 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 }`