# ObjectUI Documentation



# ObjectUI Documentation [#objectui-documentation]

ObjectUI is a schema-driven UI engine for React. It renders JSON metadata into accessible, themeable components built with Tailwind CSS, Shadcn UI, and Radix primitives.

Use it when your application needs server-driven pages, metadata-defined forms, reusable enterprise views, or an embeddable renderer that stays independent from any single backend.

## Start Here [#start-here]

1. [Quick Start](/docs/guide/quick-start) - install ObjectUI and render a first schema.
2. [Schema Rendering](/docs/guide/schema-rendering) - learn how JSON becomes React UI.
3. [Data Connectivity](/docs/guide/data-source) - connect a backend through the `DataSource` contract.
4. [Schema Reference](/docs/api/schema-reference) - inspect the supported schema shapes.

## A Small Schema [#a-small-schema]

```json
{
  "type": "data-table",
  "caption": "Users",
  "className": "rounded-lg border",
  "columns": [
    {
      "header": "Name",
      "accessorKey": "name",
      "sortable": true
    },
    {
      "header": "Email",
      "accessorKey": "email"
    }
  ],
  "data": [
    {
      "name": "Ada Lovelace",
      "email": "ada@example.com"
    },
    {
      "name": "Grace Hopper",
      "email": "grace@example.com"
    }
  ]
}
```

That schema renders through `SchemaRenderer` after the component package is imported once for registration side effects.

## Build Paths [#build-paths]

### Render Schemas [#render-schemas]

* [Schema Renderer](/docs/core/schema-renderer) explains the runtime component.
* [Component Registry](/docs/guide/component-registry) explains how `type` maps to React components.
* [Expressions](/docs/guide/expressions) covers visibility, disabled state, and dynamic values.

### Build Applications [#build-applications]

* [App Schema](/docs/core/app-schema) defines app navigation, branding, and layout.
* [Layout Guide](/docs/guide/layout) covers page structure and layout primitives.
* [Building a CRUD App](/docs/guide/building-crud-app) walks through a full task manager.

### Connect Data [#connect-data]

* [Data Connectivity](/docs/guide/data-source) covers the backend adapter contract.
* [ObjectStack Adapter](/docs/utilities/data-objectstack) connects ObjectUI to ObjectStack backends.
* [User State Persistence](/docs/guide/user-state-persistence) covers favorites and recent items.

### Extend ObjectUI [#extend-objectui]

* [Plugin Guide](/docs/guide/plugins) explains lazy-loaded feature packages.
* [Plugin Development](/docs/guide/plugin-development) walks through a custom plugin.
* [Theming](/docs/guide/theming) covers design tokens, Tailwind, and runtime themes.

## Reference [#reference]

* [Components](/docs/components) - core renderers grouped by category.
* [Fields](/docs/guide/fields) - field widgets and cell renderers.
* [Plugins](/docs/plugins) - heavier views such as grids, kanban, charts, maps, and reports.
* [Utilities](/docs/utilities) - CLI, runner, plugin scaffolding, and editor tooling.

## Console [#console]

The ObjectUI Console is the reference application for rendering ObjectStack metadata as an admin UI. Start with [Console](/docs/guide/console), then use [Console Architecture](/docs/guide/console-architecture) and [Metadata Diagnostics](/docs/guide/metadata-diagnostics) when integrating a real backend.


# API Reference



# API Reference [#api-reference]

Comprehensive reference documentation for all ObjectUI types, schemas, and APIs.

## Schema Types [#schema-types]

### [Schema Type Reference](/docs/api/schema-reference) [#schema-type-reference]

Complete reference for every ObjectUI schema type with annotated JSON examples covering:

* **Base** — `SchemaNode`, `BaseSchema`
* **Layout** — `PageSchema`, `DivSchema`, `CardSchema`, `GridSchema`, `TabsSchema`
* **Forms** — `FormSchema`, `InputSchema`, `SelectSchema`, `ButtonSchema`
* **Data Display** — `TableSchema`, `ChartSchema`, `TreeViewSchema`
* **CRUD** — `CRUDSchema`, `ActionSchema`, `DetailSchema`
* **ObjectQL** — `ObjectGridSchema`, `ObjectFormSchema`, `ObjectViewSchema`
* **Complex** — `KanbanSchema`, `DashboardSchema`, `CalendarViewSchema`
* **Views** — `DetailViewSchema`, `ViewSwitcherSchema`


# Schema Type Reference



# Schema Type Reference [#schema-type-reference]

This reference documents every ObjectUI schema type with annotated JSON examples. Each schema extends `BaseSchema` and can be rendered by the ObjectUI engine from pure JSON.

> **Import:** All types are available from `@object-ui/types`.
>
> ```typescript
> import type { PageSchema, FormSchema, TableSchema, /* ... */ } from '@object-ui/types';
> ```

***

## Base Schema [#base-schema]

### SchemaNode [#schemanode]

The foundational building block of ObjectUI. Every component in the system is described by a `SchemaNode`. It can be a full schema object, or a primitive value rendered as text.

```typescript
// Type definition
type SchemaNode = BaseSchema | string | number | boolean | null | undefined;
```

### BaseSchema [#baseschema]

All schema types extend `BaseSchema`. These shared properties are available on every component.

```json
{
  "type": "div",
  "id": "my-component",
  "name": "wrapper",
  "label": "Wrapper",
  "description": "A container element",
  "className": "p-4 bg-white rounded-lg",
  "visible": true,
  "visibleOn": "${data.showWrapper}",
  "disabled": false,
  "disabledOn": "${data.isLocked}",
  "testId": "wrapper-element",
  "ariaLabel": "Content wrapper",
  "body": []
}
```

| Property                  | Type                         | Description                                                                   |
| ------------------------- | ---------------------------- | ----------------------------------------------------------------------------- |
| `type`                    | `string`                     | **Required.** Component type identifier (e.g. `"page"`, `"form"`, `"table"`). |
| `id`                      | `string`                     | Unique instance identifier.                                                   |
| `name`                    | `string`                     | Component name, used for form fields and data binding.                        |
| `label`                   | `string`                     | Human-readable display label.                                                 |
| `description`             | `string`                     | Help text or tooltip content.                                                 |
| `className`               | `string`                     | Tailwind CSS utility classes.                                                 |
| `body`                    | `SchemaNode \| SchemaNode[]` | Child components rendered inside this component.                              |
| `children`                | `SchemaNode \| SchemaNode[]` | Alias for `body`.                                                             |
| `visible` / `visibleOn`   | `boolean` / `string`         | Control visibility. `visibleOn` accepts expression strings.                   |
| `hidden` / `hiddenOn`     | `boolean` / `string`         | Inverse of visible.                                                           |
| `disabled` / `disabledOn` | `boolean` / `string`         | Control disabled state.                                                       |
| `testId`                  | `string`                     | Test identifier for automated testing.                                        |
| `ariaLabel`               | `string`                     | Accessibility label.                                                          |

***

## Layout Schemas [#layout-schemas]

### PageSchema [#pageschema]

Top-level page container. Defines a full page with optional regions (header, sidebar, footer).

```json
{
  "type": "page",
  "title": "User Dashboard",
  "icon": "LayoutDashboard",
  "description": "Overview of user activity",
  "pageType": "detail",
  "object": "User",
  "variables": [
    { "name": "userId", "type": "string", "defaultValue": "current" }
  ],
  "regions": [
    {
      "name": "header",
      "body": [{ "type": "text", "body": "Welcome back" }]
    }
  ],
  "body": [
    { "type": "card", "title": "Activity", "body": [] }
  ]
}
```

| Property           | Type             | Description                                                                          |
| ------------------ | ---------------- | ------------------------------------------------------------------------------------ |
| `title`            | `string`         | Page title displayed in the header.                                                  |
| `icon`             | `string`         | Lucide icon name for the page.                                                       |
| `pageType`         | `PageType`       | Page purpose: `"list"`, `"detail"`, `"form"`, `"dashboard"`, `"report"`, `"custom"`. |
| `object`           | `string`         | ObjectQL object name this page operates on.                                          |
| `template`         | `string`         | Template name for page layout.                                                       |
| `variables`        | `PageVariable[]` | Page-level variables with types and defaults.                                        |
| `regions`          | `PageRegion[]`   | Named layout regions (header, sidebar, footer).                                      |
| `body`             | `SchemaNode[]`   | Main page content.                                                                   |
| `isDefault`        | `boolean`        | Whether this is the default page for the object.                                     |
| `assignedProfiles` | `string[]`       | Security profiles that can access this page.                                         |

**Related:** [AppSchema](/docs/core/app-schema), [DivSchema](#divschema), [GridSchema](#gridschema)

***

### DivSchema [#divschema]

A generic container element. The simplest layout primitive.

```json
{
  "type": "div",
  "className": "flex items-center gap-4 p-6",
  "children": [
    { "type": "text", "body": "Hello World" },
    { "type": "button", "label": "Click me" }
  ]
}
```

| Property   | Type                         | Description                              |
| ---------- | ---------------------------- | ---------------------------------------- |
| `children` | `SchemaNode \| SchemaNode[]` | Child elements to render inside the div. |

**Related:** [GridSchema](#gridschema), [CardSchema](#cardschema)

***

### CardSchema [#cardschema]

A styled container with optional header, body, and footer regions.

```json
{
  "type": "card",
  "title": "Revenue Summary",
  "description": "Monthly revenue breakdown",
  "variant": "outline",
  "hoverable": true,
  "header": [
    { "type": "badge", "label": "Live", "variant": "success" }
  ],
  "body": [
    { "type": "statistic", "label": "Total Revenue", "value": "$12,400" }
  ],
  "footer": [
    { "type": "button", "label": "View Details", "variant": "ghost" }
  ]
}
```

| Property      | Type                                | Description                          |
| ------------- | ----------------------------------- | ------------------------------------ |
| `title`       | `string`                            | Card title text.                     |
| `description` | `string`                            | Subtitle / description text.         |
| `variant`     | `"default" \| "outline" \| "ghost"` | Visual style variant.                |
| `hoverable`   | `boolean`                           | Add hover elevation effect.          |
| `clickable`   | `boolean`                           | Make the entire card a click target. |
| `header`      | `SchemaNode \| SchemaNode[]`        | Content rendered in the card header. |
| `body`        | `SchemaNode \| SchemaNode[]`        | Main card content.                   |
| `footer`      | `SchemaNode \| SchemaNode[]`        | Content rendered in the card footer. |

**Related:** [DivSchema](#divschema), [GridSchema](#gridschema)

***

### GridSchema [#gridschema]

A responsive grid layout. Columns can be a fixed number or responsive breakpoints.

```json
{
  "type": "grid",
  "columns": { "sm": 1, "md": 2, "lg": 3 },
  "gap": 6,
  "children": [
    { "type": "card", "title": "Card 1", "body": [] },
    { "type": "card", "title": "Card 2", "body": [] },
    { "type": "card", "title": "Card 3", "body": [] }
  ]
}
```

| Property   | Type                               | Description                                                            |
| ---------- | ---------------------------------- | ---------------------------------------------------------------------- |
| `columns`  | `number \| Record<string, number>` | Number of columns, or responsive map (e.g. `{ sm: 1, md: 2, lg: 3 }`). |
| `gap`      | `number`                           | Gap between grid items (Tailwind spacing scale).                       |
| `children` | `SchemaNode \| SchemaNode[]`       | Grid items.                                                            |

**Related:** [DivSchema](#divschema), [CardSchema](#cardschema), [DashboardSchema](#dashboardschema)

***

### TabsSchema [#tabsschema]

A tabbed interface for organizing content into switchable panels.

```json
{
  "type": "tabs",
  "defaultValue": "overview",
  "orientation": "horizontal",
  "items": [
    {
      "value": "overview",
      "label": "Overview",
      "icon": "Info",
      "content": { "type": "div", "body": [{ "type": "text", "body": "Overview content" }] }
    },
    {
      "value": "settings",
      "label": "Settings",
      "icon": "Settings",
      "content": { "type": "form", "fields": [] }
    }
  ]
}
```

| Property       | Type                         | Description                                                                              |
| -------------- | ---------------------------- | ---------------------------------------------------------------------------------------- |
| `defaultValue` | `string`                     | Initially active tab value.                                                              |
| `value`        | `string`                     | Controlled active tab value.                                                             |
| `orientation`  | `"horizontal" \| "vertical"` | Tab bar orientation.                                                                     |
| `items`        | `TabItem[]`                  | Tab definitions, each with `value`, `label`, `icon`, `content`, and optional `disabled`. |

**Related:** [CardSchema](#cardschema), [PageSchema](#pageschema)

***

## Form Schemas [#form-schemas]

### FormSchema [#formschema]

A complete form with fields, validation, layout, and actions.

```json
{
  "type": "form",
  "layout": "horizontal",
  "columns": 2,
  "validationMode": "onBlur",
  "submitLabel": "Save Changes",
  "showCancel": true,
  "cancelLabel": "Discard",
  "defaultValues": {
    "name": "",
    "email": "",
    "role": "viewer"
  },
  "fields": [
    { "name": "name", "label": "Full Name", "type": "text", "required": true },
    { "name": "email", "label": "Email", "type": "email", "required": true },
    { "name": "role", "label": "Role", "type": "select", "options": [
      { "label": "Admin", "value": "admin" },
      { "label": "Editor", "value": "editor" },
      { "label": "Viewer", "value": "viewer" }
    ]}
  ]
}
```

| Property         | Type                                                           | Description                                |
| ---------------- | -------------------------------------------------------------- | ------------------------------------------ |
| `fields`         | `FormField[]`                                                  | Field definitions for the form.            |
| `defaultValues`  | `Record<string, any>`                                          | Initial form values.                       |
| `layout`         | `"vertical" \| "horizontal"`                                   | Field label placement.                     |
| `columns`        | `number`                                                       | Number of columns for field layout.        |
| `validationMode` | `"onSubmit" \| "onBlur" \| "onChange" \| "onTouched" \| "all"` | When validation triggers.                  |
| `submitLabel`    | `string`                                                       | Text for the submit button.                |
| `cancelLabel`    | `string`                                                       | Text for the cancel button.                |
| `showCancel`     | `boolean`                                                      | Whether to show a cancel button.           |
| `showActions`    | `boolean`                                                      | Whether to show the action buttons row.    |
| `resetOnSubmit`  | `boolean`                                                      | Reset form after successful submit.        |
| `mode`           | `"edit" \| "read" \| "disabled"`                               | Form interaction mode.                     |
| `actions`        | `SchemaNode[]`                                                 | Custom action buttons to replace defaults. |

**Related:** [InputSchema](#inputschema), [SelectSchema](#selectschema), [ObjectFormSchema](#objectformschema)

***

### InputSchema [#inputschema]

A text input field supporting multiple input types with validation.

```json
{
  "type": "input",
  "name": "email",
  "label": "Email Address",
  "inputType": "email",
  "placeholder": "you@example.com",
  "required": true,
  "description": "We'll never share your email",
  "maxLength": 255
}
```

| Property      | Type      | Description                                                                                                                           |
| ------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `name`        | `string`  | Field name for form data binding.                                                                                                     |
| `inputType`   | `string`  | HTML input type: `"text"`, `"email"`, `"password"`, `"number"`, `"tel"`, `"url"`, `"search"`, `"date"`, `"time"`, `"datetime-local"`. |
| `placeholder` | `string`  | Placeholder text.                                                                                                                     |
| `required`    | `boolean` | Whether the field is required.                                                                                                        |
| `readOnly`    | `boolean` | Render as read-only.                                                                                                                  |
| `error`       | `string`  | Error message to display.                                                                                                             |
| `min` / `max` | `number`  | Numeric range constraints.                                                                                                            |
| `step`        | `number`  | Step increment for number inputs.                                                                                                     |
| `maxLength`   | `number`  | Maximum character length.                                                                                                             |
| `pattern`     | `string`  | Regex pattern for validation.                                                                                                         |

**Related:** [FormSchema](#formschema), [SelectSchema](#selectschema)

***

### SelectSchema [#selectschema]

A dropdown select field with predefined options.

```json
{
  "type": "select",
  "name": "priority",
  "label": "Priority",
  "placeholder": "Choose priority...",
  "required": true,
  "options": [
    { "label": "🔴 Critical", "value": "critical" },
    { "label": "🟠 High", "value": "high" },
    { "label": "🟡 Medium", "value": "medium" },
    { "label": "🟢 Low", "value": "low" }
  ],
  "defaultValue": "medium"
}
```

| Property       | Type             | Description                              |
| -------------- | ---------------- | ---------------------------------------- |
| `name`         | `string`         | Field name for form data binding.        |
| `options`      | `SelectOption[]` | Array of `{ label, value }` objects.     |
| `placeholder`  | `string`         | Placeholder text when no value selected. |
| `required`     | `boolean`        | Whether selection is required.           |
| `defaultValue` | `string`         | Initial selected value.                  |
| `error`        | `string`         | Error message to display.                |

**Related:** [FormSchema](#formschema), [InputSchema](#inputschema)

***

### ButtonSchema [#buttonschema]

An interactive button with variants, icons, and loading states.

```json
{
  "type": "button",
  "label": "Deploy to Production",
  "variant": "default",
  "size": "lg",
  "icon": "Rocket",
  "iconPosition": "left",
  "loading": false,
  "buttonType": "submit"
}
```

| Property       | Type                                                                          | Description                                   |
| -------------- | ----------------------------------------------------------------------------- | --------------------------------------------- |
| `label`        | `string`                                                                      | Button text.                                  |
| `variant`      | `"default" \| "secondary" \| "destructive" \| "outline" \| "ghost" \| "link"` | Visual style.                                 |
| `size`         | `"default" \| "sm" \| "lg" \| "icon"`                                         | Button size.                                  |
| `icon`         | `string`                                                                      | Lucide icon name.                             |
| `iconPosition` | `"left" \| "right"`                                                           | Icon placement relative to label.             |
| `loading`      | `boolean`                                                                     | Show loading spinner and disable interaction. |
| `buttonType`   | `"button" \| "submit" \| "reset"`                                             | HTML button type.                             |

**Related:** [ActionSchema](#actionschema), [FormSchema](#formschema)

***

## Data Display Schemas [#data-display-schemas]

### TableSchema [#tableschema]

A data table with columns, optional striping, and hover effects.

```json
{
  "type": "table",
  "caption": "Recent Orders",
  "hoverable": true,
  "striped": true,
  "columns": [
    { "name": "id", "label": "#", "width": 60 },
    { "name": "customer", "label": "Customer" },
    { "name": "amount", "label": "Amount", "align": "right" },
    { "name": "status", "label": "Status" }
  ],
  "data": [
    { "id": 1, "customer": "Acme Corp", "amount": "$1,200", "status": "Paid" },
    { "id": 2, "customer": "Globex Inc", "amount": "$3,400", "status": "Pending" }
  ],
  "footer": { "type": "text", "body": "Showing 2 of 156 orders" }
}
```

| Property    | Type                   | Description                                                                      |
| ----------- | ---------------------- | -------------------------------------------------------------------------------- |
| `caption`   | `string`               | Table caption / title text.                                                      |
| `columns`   | `TableColumn[]`        | Column definitions with `name`, `label`, `width`, `align`, `sortable`, `render`. |
| `data`      | `any[]`                | Array of row data objects.                                                       |
| `footer`    | `SchemaNode \| string` | Footer content below the table.                                                  |
| `hoverable` | `boolean`              | Highlight rows on hover.                                                         |
| `striped`   | `boolean`              | Alternate row background colors.                                                 |

**Related:** [CRUDSchema](#crudschema), [ObjectGridSchema](#objectgridschema)

***

### ChartSchema [#chartschema]

A chart visualization supporting multiple chart types.

```json
{
  "type": "chart",
  "chartType": "bar",
  "title": "Monthly Revenue",
  "description": "Revenue by month for 2024",
  "height": 350,
  "showLegend": true,
  "showGrid": true,
  "animate": true,
  "categories": ["Jan", "Feb", "Mar", "Apr", "May", "Jun"],
  "series": [
    {
      "name": "Revenue",
      "data": [4200, 5100, 4800, 6200, 5800, 7100],
      "color": "#3b82f6"
    },
    {
      "name": "Expenses",
      "data": [3100, 3400, 3200, 3800, 3600, 4000],
      "color": "#ef4444"
    }
  ]
}
```

| Property           | Type                  | Description                                                                                         |
| ------------------ | --------------------- | --------------------------------------------------------------------------------------------------- |
| `chartType`        | `ChartType`           | **Required.** `"bar"`, `"line"`, `"area"`, `"pie"`, `"donut"`, `"radar"`, `"scatter"`, `"heatmap"`. |
| `title`            | `string`              | Chart title.                                                                                        |
| `description`      | `string`              | Chart description / subtitle.                                                                       |
| `categories`       | `string[]`            | X-axis category labels.                                                                             |
| `series`           | `ChartSeries[]`       | Data series, each with `name`, `data` array, and optional `color`.                                  |
| `height` / `width` | `string \| number`    | Chart dimensions.                                                                                   |
| `showLegend`       | `boolean`             | Display the legend.                                                                                 |
| `showGrid`         | `boolean`             | Display grid lines.                                                                                 |
| `animate`          | `boolean`             | Enable entry animations.                                                                            |
| `config`           | `Record<string, any>` | Additional chart library configuration.                                                             |

**Related:** [DashboardSchema](#dashboardschema), [CardSchema](#cardschema)

***

### TreeViewSchema [#treeviewschema]

A hierarchical tree component for nested data with expand/collapse and selection.

```json
{
  "type": "tree-view",
  "multiSelect": false,
  "showLines": true,
  "defaultExpandedIds": ["root", "src"],
  "data": [
    {
      "id": "root",
      "label": "project",
      "icon": "Folder",
      "children": [
        {
          "id": "src",
          "label": "src",
          "icon": "Folder",
          "children": [
            { "id": "app", "label": "App.tsx", "icon": "FileCode" },
            { "id": "index", "label": "index.ts", "icon": "FileCode" }
          ]
        },
        { "id": "readme", "label": "README.md", "icon": "FileText" }
      ]
    }
  ]
}
```

| Property             | Type         | Description                                                                                  |
| -------------------- | ------------ | -------------------------------------------------------------------------------------------- |
| `data`               | `TreeNode[]` | **Required.** Nested tree data. Each node has `id`, `label`, optional `icon` and `children`. |
| `defaultExpandedIds` | `string[]`   | Node IDs expanded on initial render.                                                         |
| `defaultSelectedIds` | `string[]`   | Node IDs selected on initial render.                                                         |
| `expandedIds`        | `string[]`   | Controlled expanded state.                                                                   |
| `selectedIds`        | `string[]`   | Controlled selection state.                                                                  |
| `multiSelect`        | `boolean`    | Allow selecting multiple nodes.                                                              |
| `showLines`          | `boolean`    | Show tree connector lines.                                                                   |

**Related:** [TableSchema](#tableschema)

***

## CRUD Schemas [#crud-schemas]

### CRUDSchema [#crudschema]

A complete CRUD (Create, Read, Update, Delete) interface with table, toolbar, filters, pagination, and batch/row actions.

```json
{
  "type": "crud",
  "title": "Products",
  "resource": "products",
  "api": "/api/products",
  "selectable": "multiple",
  "defaultSort": "name",
  "defaultSortOrder": "asc",
  "columns": [
    { "name": "name", "label": "Product Name", "sortable": true },
    { "name": "price", "label": "Price", "align": "right" },
    { "name": "stock", "label": "Stock", "sortable": true },
    { "name": "status", "label": "Status" }
  ],
  "fields": [
    { "name": "name", "label": "Product Name", "type": "text", "required": true },
    { "name": "price", "label": "Price", "type": "number", "required": true },
    { "name": "stock", "label": "Stock", "type": "number" },
    { "name": "status", "label": "Status", "type": "select", "options": [
      { "label": "Active", "value": "active" },
      { "label": "Draft", "value": "draft" }
    ]}
  ],
  "operations": {
    "create": true,
    "read": true,
    "update": true,
    "delete": true,
    "export": true
  },
  "toolbar": {
    "showSearch": true,
    "showFilters": true,
    "showExport": true,
    "actions": [
      { "type": "action", "label": "Add Product", "level": "primary", "icon": "Plus" }
    ]
  },
  "filters": [
    { "name": "status", "label": "Status", "type": "select", "options": [
      { "label": "Active", "value": "active" },
      { "label": "Draft", "value": "draft" }
    ]}
  ],
  "pagination": {
    "pageSize": 20,
    "pageSizeOptions": [10, 20, 50, 100]
  },
  "rowActions": [
    { "type": "action", "label": "Edit", "icon": "Pencil", "actionType": "dialog" },
    { "type": "action", "label": "Delete", "icon": "Trash2", "level": "danger", "actionType": "confirm" }
  ],
  "batchActions": [
    { "type": "action", "label": "Delete Selected", "level": "danger", "actionType": "confirm" }
  ]
}
```

| Property                           | Type                                      | Description                                                                       |
| ---------------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------- |
| `title`                            | `string`                                  | CRUD view title.                                                                  |
| `resource`                         | `string`                                  | Resource identifier for API calls.                                                |
| `api`                              | `string`                                  | Base API endpoint URL.                                                            |
| `columns`                          | `TableColumn[]`                           | **Required.** Column definitions for the table view.                              |
| `fields`                           | `FormField[]`                             | Field definitions for create/edit forms.                                          |
| `operations`                       | `object`                                  | Toggle CRUD operations: `create`, `read`, `update`, `delete`, `export`, `import`. |
| `toolbar`                          | `CRUDToolbar`                             | Toolbar configuration with search, filters, and custom actions.                   |
| `filters`                          | `CRUDFilter[]`                            | Filter definitions.                                                               |
| `pagination`                       | `CRUDPagination`                          | Pagination settings with `pageSize` and `pageSizeOptions`.                        |
| `selectable`                       | `boolean \| "single" \| "multiple"`       | Row selection mode.                                                               |
| `rowActions`                       | `ActionSchema[]`                          | Actions available on each row.                                                    |
| `batchActions`                     | `ActionSchema[]`                          | Actions for selected rows.                                                        |
| `defaultSort` / `defaultSortOrder` | `string` / `"asc" \| "desc"`              | Default sort field and direction.                                                 |
| `mode`                             | `"table" \| "grid" \| "list" \| "kanban"` | Display mode for the CRUD view.                                                   |
| `emptyState`                       | `SchemaNode`                              | Custom empty state content.                                                       |

**Related:** [ActionSchema](#actionschema), [TableSchema](#tableschema), [ObjectGridSchema](#objectgridschema)

***

### ActionSchema [#actionschema]

A powerful action definition supporting API calls, confirmations, dialogs, chaining, and conditional execution.

```json
{
  "type": "action",
  "label": "Submit Order",
  "level": "primary",
  "icon": "Send",
  "actionType": "ajax",
  "api": "/api/orders",
  "method": "POST",
  "data": { "status": "submitted" },
  "confirm": {
    "title": "Submit Order?",
    "message": "This will send the order to the warehouse.",
    "confirmText": "Yes, Submit",
    "confirmVariant": "default"
  },
  "successMessage": "Order submitted successfully",
  "errorMessage": "Failed to submit order",
  "chain": [
    {
      "type": "action",
      "label": "Refresh",
      "actionType": "button",
      "reload": true
    }
  ],
  "chainMode": "sequential",
  "condition": {
    "expression": "${data.items.length > 0}"
  },
  "retry": {
    "maxAttempts": 3,
    "delay": 1000
  }
}
```

| Property                          | Type                         | Description                                                                                 |
| --------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------- |
| `label`                           | `string`                     | **Required.** Action display text.                                                          |
| `level`                           | `string`                     | Semantic level: `"primary"`, `"secondary"`, `"success"`, `"warning"`, `"danger"`, `"info"`. |
| `icon`                            | `string`                     | Lucide icon name.                                                                           |
| `actionType`                      | `string`                     | Action kind: `"button"`, `"link"`, `"dropdown"`, `"ajax"`, `"confirm"`, `"dialog"`.         |
| `api`                             | `string`                     | API endpoint for `ajax` actions.                                                            |
| `method`                          | `string`                     | HTTP method: `"GET"`, `"POST"`, `"PUT"`, `"DELETE"`, `"PATCH"`.                             |
| `data`                            | `any`                        | Request body data.                                                                          |
| `confirm`                         | `object`                     | Confirmation dialog with `title`, `message`, `confirmText`, `cancelText`.                   |
| `dialog`                          | `object`                     | Modal dialog with `title`, `content`, `size`, `actions`.                                    |
| `chain`                           | `ActionSchema[]`             | Actions to execute after this action completes.                                             |
| `chainMode`                       | `"sequential" \| "parallel"` | How chained actions execute.                                                                |
| `condition`                       | `ActionCondition`            | Conditional execution with `expression`, `then`, `else`.                                    |
| `successMessage` / `errorMessage` | `string`                     | Toast messages on success/failure.                                                          |
| `reload`                          | `boolean`                    | Reload data after action completes.                                                         |
| `redirect`                        | `string`                     | URL to navigate to after action.                                                            |
| `retry`                           | `object`                     | Retry config with `maxAttempts` and `delay`.                                                |

**Related:** [CRUDSchema](#crudschema), [ButtonSchema](#buttonschema)

***

### DetailSchema [#detailschema]

A single-record detail view with grouped fields, actions, and tabs.

```json
{
  "type": "detail",
  "title": "Order #1042",
  "api": "/api/orders/1042",
  "showBack": true,
  "groups": [
    {
      "title": "Customer Info",
      "fields": [
        { "name": "customer", "label": "Customer", "type": "text" },
        { "name": "email", "label": "Email", "type": "link" },
        { "name": "created", "label": "Created", "type": "date", "format": "MMM d, yyyy" }
      ]
    },
    {
      "title": "Order Details",
      "fields": [
        { "name": "total", "label": "Total", "type": "text" },
        { "name": "status", "label": "Status", "type": "badge" }
      ]
    }
  ],
  "actions": [
    { "type": "action", "label": "Edit", "icon": "Pencil", "level": "primary" },
    { "type": "action", "label": "Delete", "icon": "Trash2", "level": "danger", "actionType": "confirm" }
  ],
  "tabs": [
    {
      "key": "items",
      "label": "Line Items",
      "content": { "type": "table", "columns": [], "data": [] }
    },
    {
      "key": "history",
      "label": "History",
      "content": { "type": "timeline", "events": [] }
    }
  ]
}
```

| Property     | Type               | Description                                                   |
| ------------ | ------------------ | ------------------------------------------------------------- |
| `title`      | `string`           | Detail page title.                                            |
| `api`        | `string`           | API endpoint to fetch record data.                            |
| `resourceId` | `string \| number` | ID of the record to display.                                  |
| `groups`     | `array`            | Field groups, each with `title`, `description`, and `fields`. |
| `actions`    | `ActionSchema[]`   | Available actions (edit, delete, etc.).                       |
| `tabs`       | `array`            | Additional tabbed content with `key`, `label`, and `content`. |
| `showBack`   | `boolean`          | Show a back navigation button.                                |
| `loading`    | `boolean`          | Show loading state.                                           |

**Related:** [DetailViewSchema](#detailviewschema), [CRUDSchema](#crudschema)

***

## ObjectQL Schemas [#objectql-schemas]

These schemas integrate with [ObjectStack](https://objectstack.ai) for automatic data fetching, but work with any backend through the `data` prop.

### ObjectGridSchema [#objectgridschema]

A data grid that auto-fetches from an ObjectQL object definition. Includes search, filters, pagination, grouping, and inline editing.

```json
{
  "type": "object-grid",
  "objectName": "Contact",
  "title": "All Contacts",
  "description": "Manage your contacts",
  "showSearch": true,
  "showFilters": true,
  "showPagination": true,
  "pageSize": 25,
  "resizableColumns": true,
  "striped": true,
  "columns": [
    "name",
    "email",
    "company",
    "phone",
    { "name": "status", "label": "Status", "sortable": true }
  ],
  "defaultSort": { "field": "name", "order": "asc" },
  "operations": {
    "create": true,
    "read": true,
    "update": true,
    "delete": true,
    "export": true
  },
  "rowActions": ["edit", "delete"],
  "selection": {
    "enabled": true,
    "mode": "multiple"
  },
  "pagination": {
    "enabled": true,
    "pageSize": 25,
    "pageSizeOptions": [10, 25, 50, 100]
  }
}
```

| Property                     | Type                       | Description                                                                                                                                                       |
| ---------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `objectName`                 | `string`                   | **Required.** ObjectQL object API name.                                                                                                                           |
| `columns`                    | `string[] \| ListColumn[]` | Columns to display. Strings auto-resolve from object metadata.                                                                                                    |
| `filter`                     | `any[]`                    | Pre-applied filter conditions.                                                                                                                                    |
| `sort`                       | `string \| SortConfig[]`   | Default sort configuration.                                                                                                                                       |
| `searchableFields`           | `string[]`                 | Fields included in search.                                                                                                                                        |
| `selection`                  | `SelectionConfig`          | Row selection configuration.                                                                                                                                      |
| `pagination`                 | `PaginationConfig`         | Pagination settings.                                                                                                                                              |
| `operations`                 | `object`                   | Enabled CRUD operations.                                                                                                                                          |
| `rowActions` / `bulkActions` | `string[]`                 | Action identifiers for rows and batch selection. `bulkActions` is the spec-aligned key; `batchActions` is a legacy alias that takes precedence when both are set. |
| `editable`                   | `boolean`                  | Enable inline cell editing.                                                                                                                                       |
| `grouping`                   | `GroupingConfig`           | Row grouping configuration.                                                                                                                                       |
| `frozenColumns`              | `number`                   | Number of columns frozen on scroll.                                                                                                                               |
| `navigation`                 | `ViewNavigationConfig`     | SPA navigation configuration.                                                                                                                                     |

**Related:** [ObjectViewSchema](#objectviewschema), [CRUDSchema](#crudschema), [TableSchema](#tableschema)

***

### ObjectFormSchema [#objectformschema]

A smart form that auto-generates fields from an ObjectQL object. Supports simple, tabbed, wizard, split, drawer, and modal layouts.

```json
{
  "type": "object-form",
  "objectName": "Contact",
  "mode": "create",
  "formType": "tabbed",
  "title": "New Contact",
  "layout": "vertical",
  "columns": 2,
  "fields": ["firstName", "lastName", "email", "phone", "company"],
  "sections": [
    {
      "label": "Basic Info",
      "fields": ["firstName", "lastName", "email"]
    },
    {
      "label": "Details",
      "fields": ["phone", "company", "address"]
    }
  ],
  "showSubmit": true,
  "submitText": "Create Contact",
  "showCancel": true,
  "cancelText": "Cancel"
}
```

| Property                                  | Type                           | Description                                                                                                                                                                                          |
| ----------------------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `objectName`                              | `string`                       | **Required.** ObjectQL object API name.                                                                                                                                                              |
| `mode`                                    | `"create" \| "edit" \| "view"` | **Required.** Form interaction mode.                                                                                                                                                                 |
| `formType`                                | `string`                       | Layout type: `"simple"`, `"tabbed"`, `"wizard"`, `"split"`, `"drawer"`, `"modal"`. Aligned with `@objectstack/spec` `FormViewSchema.type`.                                                           |
| `recordId`                                | `string \| number`             | Record ID for edit/view modes.                                                                                                                                                                       |
| `fields`                                  | `string[]`                     | Field API names to include (auto-resolved from object metadata).                                                                                                                                     |
| `customFields`                            | `FormField[]`                  | Manually defined fields that override auto-generated ones.                                                                                                                                           |
| `sections`                                | `ObjectFormSection[]`          | Field sections (simple groups, tabs, or wizard steps depending on `formType`). Spec-aligned key.                                                                                                     |
| `groups`                                  | `array`                        | **Deprecated.** Legacy alias of `sections` (spec defines `groups` as an alias); normalized into `sections` when `sections` is absent. Legacy shape: `title`→`label`, `defaultCollapsed`→`collapsed`. |
| `layout`                                  | `string`                       | Label layout: `"vertical"`, `"horizontal"`, `"inline"`, `"grid"`.                                                                                                                                    |
| `columns`                                 | `number`                       | Number of form columns.                                                                                                                                                                              |
| `submitText` / `cancelText`               | `string`                       | Button labels.                                                                                                                                                                                       |
| `showSubmit` / `showCancel` / `showReset` | `boolean`                      | Toggle action buttons.                                                                                                                                                                               |
| `drawerSide`                              | `string`                       | Drawer position: `"top"`, `"bottom"`, `"left"`, `"right"`.                                                                                                                                           |
| `modalSize`                               | `string`                       | Modal size: `"sm"`, `"default"`, `"lg"`, `"xl"`, `"full"`.                                                                                                                                           |

#### Spec alignment & extension keys [#spec-alignment--extension-keys]

`ObjectFormSchema` keys fall into three classes (#2545):

* **Spec-aligned** — same name and semantics as `@objectstack/spec` `FormViewSchema`: `title`, `description`, `layout`, `columns`, `sections`, `defaultTab`, `tabPosition`, `allowSkip`, `showStepIndicator`, `splitDirection`/`splitSize`/`splitResizable`, `drawerSide`/`drawerWidth`, `modalSize`, `subforms`, `submitBehavior` (plus `formType` ↔ spec `type`). Metadata using these keys round-trips through the SpecBridge without loss.
* **ObjectUI extensions** — serializable extras with no spec backing yet: `showSubmit`/`submitText`, `showCancel`/`cancelText`, `showReset`, `nextText`/`prevText`, `successMessage`, `navigateOnSuccess`, `resetOnSuccess`, `modalCloseButton`, `className`, `initialValues`, `fields`, `customFields`. Sanctioned and documented here; candidates for upstreaming into the spec are tracked in #2545.
* **Runtime-only** — non-serializable renderer concerns that never appear in view metadata: `mode`, `recordId`, `open`/`onOpenChange`, `readOnly`, and all callbacks (`onSuccess`, `onError`, `onCancel`, `onStepChange`, `submitHandler`).

**Related:** [FormSchema](#formschema), [ObjectViewSchema](#objectviewschema)

***

### ObjectViewSchema [#objectviewschema]

A complete object management interface combining grid, form, search, filters, and view switching.

```json
{
  "type": "object-view",
  "objectName": "Deal",
  "title": "Sales Pipeline",
  "description": "Manage your deals",
  "defaultViewType": "kanban",
  "showSearch": true,
  "showFilters": true,
  "showCreate": true,
  "showRefresh": true,
  "showViewSwitcher": true,
  "operations": {
    "create": true,
    "read": true,
    "update": true,
    "delete": true
  },
  "searchableFields": ["name", "company", "owner"],
  "filterableFields": ["stage", "owner", "value"],
  "listViews": {
    "all": {
      "label": "All Deals",
      "filter": [],
      "sort": [{ "field": "value", "order": "desc" }]
    },
    "my-deals": {
      "label": "My Deals",
      "filter": [["owner", "=", "${currentUser.id}"]],
      "default": true
    }
  },
  "table": {
    "columns": ["name", "stage", "value", "owner", "closeDate"],
    "pageSize": 25
  },
  "form": {
    "formType": "drawer",
    "drawerSide": "right",
    "fields": ["name", "stage", "value", "owner", "closeDate", "notes"]
  }
}
```

| Property                                                    | Type                            | Description                                                                                      |
| ----------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------ |
| `objectName`                                                | `string`                        | **Required.** ObjectQL object API name.                                                          |
| `title`                                                     | `string`                        | View title.                                                                                      |
| `defaultViewType`                                           | `string`                        | Initial view: `"grid"`, `"kanban"`, `"gallery"`, `"calendar"`, `"timeline"`, `"gantt"`, `"map"`. |
| `listViews`                                                 | `Record<string, NamedListView>` | Named list views with filters and sort.                                                          |
| `defaultListView`                                           | `string`                        | Key of the default list view.                                                                    |
| `table`                                                     | `Partial<ObjectGridSchema>`     | Grid configuration overrides.                                                                    |
| `form`                                                      | `Partial<ObjectFormSchema>`     | Form configuration overrides.                                                                    |
| `showSearch` / `showFilters` / `showCreate` / `showRefresh` | `boolean`                       | Toggle toolbar features.                                                                         |
| `showViewSwitcher`                                          | `boolean`                       | Show view type toggle (grid, kanban, etc.).                                                      |
| `operations`                                                | `object`                        | Enabled CRUD operations.                                                                         |
| `navigation`                                                | `ViewNavigationConfig`          | SPA-aware navigation.                                                                            |

**Related:** [ObjectGridSchema](#objectgridschema), [ObjectFormSchema](#objectformschema), [ViewSwitcherSchema](#viewswitcherschema)

***

## Complex Schemas [#complex-schemas]

### KanbanSchema [#kanbanschema]

A drag-and-drop Kanban board with columns and cards.

```json
{
  "type": "kanban",
  "draggable": true,
  "columns": [
    {
      "id": "todo",
      "title": "To Do",
      "color": "#6366f1",
      "cards": [
        { "id": "task-1", "title": "Design mockups", "description": "Create wireframes for new feature" },
        { "id": "task-2", "title": "Write tests", "description": "Unit tests for auth module" }
      ]
    },
    {
      "id": "in-progress",
      "title": "In Progress",
      "color": "#f59e0b",
      "cards": [
        { "id": "task-3", "title": "API integration", "description": "Connect to payment gateway" }
      ]
    },
    {
      "id": "done",
      "title": "Done",
      "color": "#22c55e",
      "cards": []
    }
  ]
}
```

| Property      | Type             | Description                                                                 |
| ------------- | ---------------- | --------------------------------------------------------------------------- |
| `columns`     | `KanbanColumn[]` | **Required.** Board columns, each with `id`, `title`, `color`, and `cards`. |
| `draggable`   | `boolean`        | Enable drag-and-drop between columns.                                       |
| `onCardMove`  | `function`       | Callback when a card is moved: `(cardId, fromColumn, toColumn, position)`.  |
| `onCardClick` | `function`       | Callback when a card is clicked.                                            |
| `onColumnAdd` | `function`       | Callback when a new column is added.                                        |
| `onCardAdd`   | `function`       | Callback when a new card is added to a column.                              |

**Related:** [ObjectViewSchema](#objectviewschema), [CRUDSchema](#crudschema)

***

### DashboardSchema [#dashboardschema]

A widget-based dashboard with configurable grid layout and auto-refresh.

```json
{
  "type": "dashboard",
  "columns": 4,
  "gap": 6,
  "refreshInterval": 30000,
  "widgets": [
    {
      "id": "revenue",
      "title": "Total Revenue",
      "description": "Monthly revenue",
      "colSpan": 1,
      "rowSpan": 1,
      "body": {
        "type": "statistic",
        "label": "Revenue",
        "value": "$48,200",
        "trend": { "value": 12, "direction": "up" }
      }
    },
    {
      "id": "chart",
      "title": "Sales Trend",
      "colSpan": 2,
      "rowSpan": 1,
      "body": {
        "type": "chart",
        "chartType": "area",
        "categories": ["Mon", "Tue", "Wed", "Thu", "Fri"],
        "series": [{ "name": "Sales", "data": [120, 180, 150, 210, 190] }]
      }
    },
    {
      "id": "tasks",
      "title": "Recent Tasks",
      "colSpan": 1,
      "rowSpan": 1,
      "body": {
        "type": "list",
        "items": []
      }
    }
  ]
}
```

| Property          | Type                      | Description                                                                            |
| ----------------- | ------------------------- | -------------------------------------------------------------------------------------- |
| `columns`         | `number`                  | Number of grid columns.                                                                |
| `gap`             | `number`                  | Gap between widgets (Tailwind spacing scale).                                          |
| `widgets`         | `DashboardWidgetSchema[]` | **Required.** Widget definitions with `id`, `title`, `colSpan`, `rowSpan`, and `body`. |
| `refreshInterval` | `number`                  | Auto-refresh interval in milliseconds.                                                 |

Each widget supports `colSpan` and `rowSpan` to control its size in the grid. The `body` can be any `SchemaNode`.

**Related:** [GridSchema](#gridschema), [ChartSchema](#chartschema), [CardSchema](#cardschema)

***

### CalendarViewSchema [#calendarviewschema]

A multi-view calendar for displaying and managing events.

```json
{
  "type": "calendar-view",
  "defaultView": "month",
  "views": ["month", "week", "day", "agenda"],
  "editable": true,
  "events": [
    {
      "id": "evt-1",
      "title": "Team Standup",
      "start": "2024-03-15T09:00:00",
      "end": "2024-03-15T09:30:00",
      "color": "#3b82f6"
    },
    {
      "id": "evt-2",
      "title": "Sprint Review",
      "start": "2024-03-15T14:00:00",
      "end": "2024-03-15T15:00:00",
      "color": "#8b5cf6",
      "allDay": false
    }
  ]
}
```

| Property        | Type                 | Description                                                                             |
| --------------- | -------------------- | --------------------------------------------------------------------------------------- |
| `events`        | `CalendarEvent[]`    | **Required.** Events with `id`, `title`, `start`, `end`, optional `color` and `allDay`. |
| `defaultView`   | `CalendarViewMode`   | Initial view: `"month"`, `"week"`, `"day"`, `"agenda"`.                                 |
| `views`         | `CalendarViewMode[]` | Available view modes the user can switch between.                                       |
| `editable`      | `boolean`            | Allow creating and modifying events.                                                    |
| `defaultDate`   | `string \| Date`     | Initial calendar date.                                                                  |
| `onEventClick`  | `function`           | Callback when an event is clicked.                                                      |
| `onEventCreate` | `function`           | Callback for new event creation: `(start, end)`.                                        |
| `onEventUpdate` | `function`           | Callback when an event is modified.                                                     |
| `onDateChange`  | `function`           | Callback when the visible date range changes.                                           |

**Related:** [ObjectViewSchema](#objectviewschema), [DashboardSchema](#dashboardschema)

***

## View Schemas [#view-schemas]

### DetailViewSchema [#detailviewschema]

An enhanced detail view for a single record with sections, tabs, related records, and navigation.

```json
{
  "type": "detail-view",
  "title": "Contact Details",
  "objectName": "Contact",
  "resourceId": "contact-123",
  "layout": "grid",
  "columns": 2,
  "showBack": true,
  "backUrl": "/contacts",
  "showEdit": true,
  "editUrl": "/contacts/contact-123/edit",
  "showDelete": true,
  "deleteConfirmation": "Are you sure you want to delete this contact?",
  "sections": [
    {
      "title": "Personal Information",
      "icon": "User",
      "columns": 2,
      "collapsible": true,
      "fields": [
        { "name": "firstName", "label": "First Name", "type": "text" },
        { "name": "lastName", "label": "Last Name", "type": "text" },
        { "name": "email", "label": "Email", "type": "link" },
        { "name": "avatar", "label": "Photo", "type": "image" }
      ]
    }
  ],
  "tabs": [
    {
      "key": "activities",
      "label": "Activities",
      "icon": "Activity",
      "badge": 5,
      "content": { "type": "timeline", "events": [] }
    }
  ],
  "related": [
    {
      "title": "Recent Orders",
      "type": "table",
      "api": "/api/contacts/contact-123/orders",
      "columns": [
        { "name": "id", "label": "Order #" },
        { "name": "total", "label": "Total" },
        { "name": "status", "label": "Status" }
      ]
    }
  ],
  "actions": [
    { "type": "action", "label": "Send Email", "icon": "Mail", "level": "primary" }
  ]
}
```

| Property                            | Type                                   | Description                                                     |
| ----------------------------------- | -------------------------------------- | --------------------------------------------------------------- |
| `title`                             | `string`                               | Detail page title.                                              |
| `objectName`                        | `string`                               | ObjectQL object name for data binding.                          |
| `resourceId`                        | `string \| number`                     | Record ID to display.                                           |
| `api`                               | `string`                               | API endpoint to fetch record data.                              |
| `data`                              | `any`                                  | Static data (if not fetching from API).                         |
| `layout`                            | `"vertical" \| "horizontal" \| "grid"` | Field layout mode.                                              |
| `columns`                           | `number`                               | Grid columns (for grid layout).                                 |
| `sections`                          | `DetailViewSection[]`                  | Field groups with `title`, `icon`, `fields`, `collapsible`.     |
| `fields`                            | `DetailViewField[]`                    | Direct fields (without sections).                               |
| `tabs`                              | `DetailViewTab[]`                      | Tabbed content with `key`, `label`, `icon`, `badge`, `content`. |
| `related`                           | `array`                                | Related record sections with `title`, `type`, `api`, `columns`. |
| `actions`                           | `ActionSchema[]`                       | Available actions.                                              |
| `showBack` / `backUrl`              | `boolean` / `string`                   | Back navigation.                                                |
| `showEdit` / `editUrl`              | `boolean` / `string`                   | Edit navigation.                                                |
| `showDelete` / `deleteConfirmation` | `boolean` / `string`                   | Delete with confirmation message.                               |
| `header` / `footer`                 | `SchemaNode`                           | Custom header/footer content.                                   |

**Related:** [DetailSchema](#detailschema), [ObjectViewSchema](#objectviewschema)

***

### ViewSwitcherSchema [#viewswitcherschema]

A toggle control that switches between different view types (list, grid, kanban, calendar, etc.).

```json
{
  "type": "view-switcher",
  "defaultView": "list",
  "variant": "tabs",
  "position": "top",
  "persistPreference": true,
  "storageKey": "contacts-view-pref",
  "views": [
    {
      "type": "list",
      "label": "List View",
      "icon": "List",
      "schema": {
        "type": "object-grid",
        "objectName": "Contact",
        "columns": ["name", "email", "phone"]
      }
    },
    {
      "type": "grid",
      "label": "Card View",
      "icon": "LayoutGrid",
      "schema": {
        "type": "grid",
        "columns": 3,
        "children": []
      }
    },
    {
      "type": "kanban",
      "label": "Kanban",
      "icon": "Kanban",
      "schema": {
        "type": "kanban",
        "columns": []
      }
    }
  ]
}
```

| Property            | Type                                     | Description                                                                                             |
| ------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `views`             | `array`                                  | **Required.** Available views, each with `type`, `label`, `icon`, and `schema`.                         |
| `defaultView`       | `ViewType`                               | Initially active view: `"list"`, `"detail"`, `"grid"`, `"kanban"`, `"calendar"`, `"timeline"`, `"map"`. |
| `activeView`        | `ViewType`                               | Controlled active view.                                                                                 |
| `variant`           | `"tabs" \| "buttons" \| "dropdown"`      | Switcher UI style.                                                                                      |
| `position`          | `"top" \| "bottom" \| "left" \| "right"` | Switcher position relative to content.                                                                  |
| `persistPreference` | `boolean`                                | Save the user's view preference to storage.                                                             |
| `storageKey`        | `string`                                 | Storage key for persisting the preference.                                                              |
| `onViewChange`      | `string`                                 | Expression or callback invoked on view change.                                                          |

**Related:** [ObjectViewSchema](#objectviewschema), [KanbanSchema](#kanbanschema), [CalendarViewSchema](#calendarviewschema)

***

## Schema Composition [#schema-composition]

Schemas are designed to compose. Nest any `SchemaNode` inside another to build complex interfaces:

```json
{
  "type": "page",
  "title": "CRM Dashboard",
  "body": [
    {
      "type": "grid",
      "columns": { "sm": 1, "lg": 2 },
      "gap": 6,
      "children": [
        {
          "type": "card",
          "title": "Quick Stats",
          "body": {
            "type": "dashboard",
            "columns": 2,
            "widgets": [
              { "id": "w1", "title": "Leads", "body": { "type": "statistic", "value": "142" } },
              { "id": "w2", "title": "Revenue", "body": { "type": "statistic", "value": "$24k" } }
            ]
          }
        },
        {
          "type": "card",
          "title": "Recent Activity",
          "body": {
            "type": "tabs",
            "items": [
              { "value": "deals", "label": "Deals", "content": { "type": "table", "columns": [], "data": [] } },
              { "value": "tasks", "label": "Tasks", "content": { "type": "table", "columns": [], "data": [] } }
            ]
          }
        }
      ]
    },
    {
      "type": "object-grid",
      "objectName": "Lead",
      "title": "All Leads",
      "showSearch": true,
      "columns": ["name", "company", "status", "value"]
    }
  ]
}
```

## Type Imports [#type-imports]

Import only the types you need:

```typescript
// Layout
import type { PageSchema, DivSchema, CardSchema, GridSchema, TabsSchema } from '@object-ui/types';

// Forms
import type { FormSchema, InputSchema, SelectSchema, ButtonSchema } from '@object-ui/types';

// Data Display
import type { TableSchema, ChartSchema, TreeViewSchema } from '@object-ui/types';

// CRUD
import type { CRUDSchema, ActionSchema, DetailSchema } from '@object-ui/types';

// ObjectQL
import type { ObjectGridSchema, ObjectFormSchema, ObjectViewSchema } from '@object-ui/types';

// Complex
import type { KanbanSchema, DashboardSchema, CalendarViewSchema } from '@object-ui/types';

// Views
import type { DetailViewSchema, ViewSwitcherSchema } from '@object-ui/types';

// Base
import type { BaseSchema, SchemaNode } from '@object-ui/types';
```

## Next Steps [#next-steps]

* **[Schema Overview](/docs/guide/schema-overview)** — High-level guide to ObjectUI schemas
* **[Quick Start](/docs/guide/quick-start)** — Build your first ObjectUI application
* **[Expressions](/docs/guide/expressions)** — Dynamic expressions with `visibleOn`, `disabledOn`
* **[Fields Guide](/docs/guide/fields)** — Deep dive into form fields
* **[Plugin Development](/docs/guide/plugin-development)** — Build custom schema renderers


# Component Gallery



# Component Gallery [#component-gallery]

ObjectUI provides a comprehensive set of components built on React, Tailwind CSS, and Shadcn UI. All components are defined through JSON schemas and rendered with pixel-perfect quality.

## Quick Navigation [#quick-navigation]

Browse components by category to find what you need:

### [Basic Components](/docs/components/basic/text) [#basic-components]

Essential building blocks: Text, Icon, Image, Separator, HTML

### [Form Components](/docs/components/form/button) [#form-components]

Interactive inputs: Button, Input, Select, Checkbox, Switch, Textarea, Slider

### [Layout Components](/docs/components/layout/container) [#layout-components]

Structure your UI: Container, Card, Grid, Flex, Stack, Tabs

### [Data Display](/docs/components/data-display/badge) [#data-display]

Show information: Badge, Avatar, Alert, List

### [Feedback Components](/docs/components/feedback/loading) [#feedback-components]

User feedback: Loading, Progress, Skeleton

### [Overlay Components](/docs/components/overlay/dialog) [#overlay-components]

Floating elements: Dialog, Drawer, Tooltip, Popover

### [Disclosure Components](/docs/components/disclosure/accordion) [#disclosure-components]

Show/hide content: Accordion, Collapsible

### [Complex Components](/docs/components/complex/table) [#complex-components]

Advanced patterns: Table (with sorting, filtering, pagination)

## Component Categories [#component-categories]

### Basic Components [#basic-components-1]

The foundation of your UI. These are simple, single-purpose components:

* **[Text](/docs/components/basic/text)** - Display text with typography control
* **[Icon](/docs/components/basic/icon)** - Render icons from Lucide React
* **[Image](/docs/components/basic/image)** - Display images with lazy loading
* **[Separator](/docs/components/basic/separator)** - Visual divider between content
* **[HTML](/docs/components/basic/html)** - Render raw HTML content

### Form Components [#form-components-1]

Interactive elements for user input:

* **[Button](/docs/components/form/button)** - Trigger actions with multiple variants
* **[Input](/docs/components/form/input)** - Text input with validation
* **[Select](/docs/components/form/select)** - Dropdown selection
* **[Checkbox](/docs/components/form/checkbox)** - Boolean selection
* **[Switch](/docs/components/form/switch)** - Toggle switch
* **[Textarea](/docs/components/form/textarea)** - Multi-line text input
* **[Slider](/docs/components/form/slider)** - Numeric range selection

### Layout Components [#layout-components-1]

Structure and organize your interface:

* **[Container](/docs/components/layout/container)** - Responsive container with max-width
* **[Card](/docs/components/layout/card)** - Content card with header and footer
* **[Grid](/docs/components/layout/grid)** - CSS Grid layout
* **[Flex](/docs/components/layout/flex)** - Flexbox layout
* **[Stack](/docs/components/layout/stack)** - Vertical or horizontal stack
* **[Tabs](/docs/components/layout/tabs)** - Tabbed interface

### Data Display [#data-display-1]

Present data to users:

* **[Badge](/docs/components/data-display/badge)** - Small status indicators
* **[Avatar](/docs/components/data-display/avatar)** - User profile images
* **[Alert](/docs/components/data-display/alert)** - Contextual messages
* **[List](/docs/components/data-display/list)** - Ordered or unordered lists

### Feedback Components [#feedback-components-1]

Provide visual feedback:

* **[Loading](/docs/components/feedback/loading)** - Loading spinner
* **[Progress](/docs/components/feedback/progress)** - Progress bar
* **[Skeleton](/docs/components/feedback/skeleton)** - Loading placeholder

### Overlay Components [#overlay-components-1]

Floating UI elements:

* **[Dialog](/docs/components/overlay/dialog)** - Modal dialog
* **[Drawer](/docs/components/overlay/drawer)** - Slide-out drawer
* **[Tooltip](/docs/components/overlay/tooltip)** - Hover tooltips
* **[Popover](/docs/components/overlay/popover)** - Floating popover

### Disclosure Components [#disclosure-components-1]

Expandable content:

* **[Accordion](/docs/components/disclosure/accordion)** - Expandable sections
* **[Collapsible](/docs/components/disclosure/collapsible)** - Toggle content visibility

### Complex Components [#complex-components-1]

Advanced, feature-rich components:

* **[Table](/docs/components/complex/table)** - Data table with sorting, filtering, and pagination

## Usage Pattern [#usage-pattern]

All ObjectUI components follow the same schema-based pattern:

```json
{
  "type": "component-name",
  "className": "tailwind-classes",
  "componentSpecificProperty": "value"
}
```

### Example: Button [#example-button]

```json
{
  "type": "button",
  "label": "Click Me",
  "variant": "default",
  "size": "md",
  "className": "mt-4"
}
```

### Example: Card with Form [#example-card-with-form]

```json
{
  "type": "card",
  "title": "User Profile",
  "className": "max-w-md",
  "body": {
    "type": "form",
    "fields": [
      {
        "type": "input",
        "name": "name",
        "label": "Full Name"
      },
      {
        "type": "input",
        "name": "email",
        "label": "Email",
        "inputType": "email"
      }
    ]
  }
}
```

## Features [#features]

All ObjectUI components share these characteristics:

* ✅ **Schema-Driven** - Define with JSON, not code
* ✅ **Tailwind CSS** - Use utility classes directly in schemas
* ✅ **Accessible** - WCAG 2.1 AA compliant
* ✅ **Responsive** - Mobile-first design
* ✅ **Themeable** - Light/dark mode support
* ✅ **Type-Safe** - Full TypeScript support
* ✅ **Performant** - Lazy-loaded and tree-shakable

## Next Steps [#next-steps]

* **[Quick Start Guide](/docs/guide/quick-start)** - Build your first ObjectUI app
* **[Schema Rendering](/docs/guide/schema-rendering)** - Learn how the engine works
* **[Component Registry](/docs/guide/component-registry)** - Register custom components
* **[Expressions](/docs/guide/expressions)** - Dynamic values with expressions

## Need Help? [#need-help]

Can't find what you're looking for? Check out:

* [Architecture](/docs/guide/architecture) - Core concepts and package boundaries
* [API Reference](/docs/api) - Schema documentation and protocol specs
* [GitHub](https://github.com/objectstack-ai/objectui) - Report issues or contribute


# Authentication Blocks





# Authentication Blocks [#authentication-blocks]

Beautiful, accessible authentication forms and flows. Every block below is
sourced from the canonical schema catalog (`@object-ui/example-schema-catalog`),
which is smoke-tested on every CI run — if a schema breaks, the build fails.

Copy the JSON from the **Code** tab and drop it into your application.

## Login Form [#login-form]

A clean login form with email and password fields, "remember me", and a
social-provider button.

<SchemaExample id="auth/login-simple" />

## Sign Up Form [#sign-up-form]

Two-column registration form with terms acceptance.

<SchemaExample id="auth/signup" />

## Forgot Password [#forgot-password]

Request a password reset link by email.

<SchemaExample id="auth/forgot-password" />

## Two-Factor Authentication [#two-factor-authentication]

Six-digit code verification with a resend link.

<SchemaExample id="auth/two-factor" />

## Customizing [#customizing]

All authentication blocks are plain JSON — tweak any node to change the look or
behaviour. Common customisations:

### Change Colors [#change-colors]

```json
{
  "type": "button",
  "className": "bg-blue-600 hover:bg-blue-700"
}
```

### Wire Up Submission [#wire-up-submission]

```json
{
  "type": "button",
  "label": "Sign In",
  "action": {
    "type": "submit",
    "endpoint": "/api/auth/login",
    "method": "POST"
  }
}
```

### Adjust Layout [#adjust-layout]

```json
{
  "type": "card",
  "className": "max-w-lg p-8"
}
```

## Next Steps [#next-steps]

* Browse [Dashboard Blocks](/docs/blocks/dashboard)
* Explore [Form Blocks](/docs/blocks/forms)
* Learn about [Actions](/docs/core/enhanced-actions)


# Block Schema (BlockSchema)





# Block Schema [#block-schema]

The `BlockSchema` defines reusable component blocks that can be configured with variables, support content injection through slots, and shared via a marketplace.

## Overview [#overview]

BlockSchema enables:

* **Reusable components** - Create once, use everywhere
* **Variable system** - Typed props for customization
* **Slot system** - Content injection points
* **Block templates** - Predefined component trees
* **Marketplace support** - Share and discover blocks
* **Version control** - Track block versions

## Interactive Examples [#interactive-examples]

### Feature Card Block [#feature-card-block]

<SchemaExample id="block-schema/feature-card-block" />

### Block Variations [#block-variations]

<SchemaExample id="block-schema/block-with-variable-overrides-security-feature" />

<SchemaExample id="block-schema/block-with-variable-overrides-analytics-feature" />

### Block Marketplace Card [#block-marketplace-card]

<SchemaExample id="block-schema/block-marketplace-listing" />

## Basic Usage [#basic-usage]

```plaintext
import type { BlockSchema } from '@object-ui/types';

const heroBlock: BlockSchema = {
  type: 'block',
  
  meta: {
    name: 'hero-section',
    label: 'Hero Section',
    description: 'A customizable hero banner with image and CTA',
    category: 'Marketing'
  },
  
  variables: [
    {
      name: 'title',
      type: 'string',
      defaultValue: 'Welcome',
      required: true
    },
    {
      name: 'showButton',
      type: 'boolean',
      defaultValue: true
    }
  ],
  
  slots: [
    {
      name: 'content',
      label: 'Content Area'
    }
  ],
  
  template: {
    type: 'div',
    className: 'hero-section',
    children: []
  }
};
```

## Properties [#properties]

### Block Metadata [#block-metadata]

```plaintext
interface BlockMetadata {
  name: string;              // Block identifier
  label?: string;            // Display name
  description?: string;      // Block description
  category?: string;         // Category for organization
  icon?: string;             // Icon name
  tags?: string[];           // Search tags
  author?: string;           // Creator
  version?: string;          // Version number
  license?: string;          // License type
  repository?: string;       // Source code URL
  preview?: string;          // Preview image URL
  premium?: boolean;         // Premium/paid block
}
```

### Block Variables [#block-variables]

Variables define configurable properties:

```plaintext
interface BlockVariable {
  name: string;                    // Variable name
  label?: string;                  // Display label
  type?: 'string' | 'number' | 'boolean' | 'object' | 'array' | 'component';
  defaultValue?: any;              // Default value
  description?: string;            // Help text
  required?: boolean;              // Is required?
  validation?: any;                // Validation rules
  enum?: any[];                    // Allowed values
}
```

### Block Slots [#block-slots]

Slots define content injection points:

```plaintext
interface BlockSlot {
  name: string;                    // Slot name
  label?: string;                  // Display label
  description?: string;            // Description
  defaultContent?: SchemaNode | SchemaNode[];
  allowedTypes?: string[];         // Allowed component types
  maxChildren?: number;            // Maximum children
  required?: boolean;              // Is required?
}
```

## Complete Example [#complete-example]

```plaintext
const cardBlock: BlockSchema = {
  type: 'block',
  
  // Metadata
  meta: {
    name: 'feature-card',
    label: 'Feature Card',
    description: 'A card component for highlighting product features',
    category: 'Marketing',
    icon: 'box',
    tags: ['card', 'feature', 'marketing', 'product'],
    author: 'ObjectUI Team',
    version: '1.0.0',
    license: 'MIT',
    repository: 'https://github.com/objectui/blocks',
    preview: '/blocks/feature-card-preview.png'
  },
  
  // Variables (configurable props)
  variables: [
    {
      name: 'title',
      label: 'Title',
      type: 'string',
      defaultValue: 'Feature Title',
      description: 'The card title text',
      required: true
    },
    {
      name: 'description',
      label: 'Description',
      type: 'string',
      defaultValue: 'Feature description goes here',
      description: 'The card description text'
    },
    {
      name: 'icon',
      label: 'Icon',
      type: 'string',
      defaultValue: 'star',
      description: 'Lucide icon name',
      enum: ['star', 'heart', 'check', 'zap', 'shield']
    },
    {
      name: 'variant',
      label: 'Variant',
      type: 'string',
      defaultValue: 'default',
      enum: ['default', 'outline', 'filled']
    },
    {
      name: 'showButton',
      label: 'Show Button',
      type: 'boolean',
      defaultValue: true,
      description: 'Show the action button'
    },
    {
      name: 'buttonText',
      label: 'Button Text',
      type: 'string',
      defaultValue: 'Learn More'
    }
  ],
  
  // Slots (content injection points)
  slots: [
    {
      name: 'header',
      label: 'Header Content',
      description: 'Optional header above the card',
      allowedTypes: ['text', 'image', 'icon'],
      maxChildren: 1
    },
    {
      name: 'content',
      label: 'Additional Content',
      description: 'Extra content below description',
      allowedTypes: ['text', 'list', 'div']
    }
  ],
  
  // Template (component tree)
  template: {
    type: 'card',
    className: 'feature-card ${variant}',
    children: [
      {
        type: 'div',
        className: 'card-icon',
        children: [
          {
            type: 'icon',
            name: '${icon}',
            size: 48,
            className: 'text-primary'
          }
        ]
      },
      {
        type: 'div',
        className: 'card-content',
        children: [
          {
            type: 'text',
            variant: 'h3',
            value: '${title}',
            className: 'card-title'
          },
          {
            type: 'text',
            value: '${description}',
            className: 'card-description'
          },
          {
            type: 'slot',
            name: 'content'
          },
          {
            type: 'button',
            label: '${buttonText}',
            variant: 'outline',
            visible: '${showButton}',
            className: 'card-button'
          }
        ]
      }
    ]
  },
  
  editable: true
};
```

## Using Blocks [#using-blocks]

### Block Instance [#block-instance]

Use `BlockInstanceSchema` to instantiate a block:

```plaintext
import type { BlockInstanceSchema } from '@object-ui/types';

const instance: BlockInstanceSchema = {
  type: 'block-instance',
  blockId: 'feature-card',
  
  // Override variable values
  values: {
    title: 'Fast Performance',
    description: 'Lightning-fast response times',
    icon: 'zap',
    variant: 'filled',
    showButton: true,
    buttonText: 'See Benchmarks'
  },
  
  // Provide slot content
  slotContent: {
    content: [
      {
        type: 'list',
        items: [
          'Sub-second page loads',
          'Optimized bundle size',
          'Edge caching'
        ]
      }
    ]
  }
};
```

## Block Library [#block-library]

Use `BlockLibrarySchema` to browse available blocks:

```plaintext
import type { BlockLibrarySchema } from '@object-ui/types';

const library: BlockLibrarySchema = {
  type: 'block-library',
  apiEndpoint: '/api/blocks',
  category: 'Marketing',
  searchQuery: 'hero',
  showPremium: true,
  loading: false,
  
  blocks: [
    {
      id: 'hero-section-1',
      meta: {
        name: 'hero-section',
        label: 'Hero Section',
        category: 'Marketing',
        // ... other metadata
      },
      schema: heroBlock,
      installs: 1234,
      rating: 4.8,
      ratingCount: 156
    }
  ],
  
  onInstall: 'handleInstallBlock',
  onPreview: 'handlePreviewBlock'
};
```

## Block Editor [#block-editor]

Use `BlockEditorSchema` to create/edit blocks:

```plaintext
import type { BlockEditorSchema } from '@object-ui/types';

const editor: BlockEditorSchema = {
  type: 'block-editor',
  
  block: cardBlock,
  
  showVariables: true,
  showSlots: true,
  showTemplate: true,
  showPreview: true,
  
  onSave: 'handleSaveBlock',
  onCancel: 'handleCancel'
};
```

## Marketplace Example [#marketplace-example]

```plaintext
const marketplace: BlockLibrarySchema = {
  type: 'block-library',
  apiEndpoint: 'https://blocks.objectui.com/api',
  
  blocks: [
    {
      id: 'pricing-table-pro',
      meta: {
        name: 'pricing-table-pro',
        label: 'Pricing Table Pro',
        description: 'Professional pricing comparison table',
        category: 'Marketing',
        icon: 'dollar-sign',
        tags: ['pricing', 'saas', 'comparison'],
        author: 'ObjectUI Team',
        version: '2.1.0',
        license: 'MIT',
        premium: false,
        preview: 'https://blocks.objectui.com/previews/pricing-table.png'
      },
      schema: { /* block schema */ },
      installs: 5420,
      rating: 4.9,
      ratingCount: 234,
      updatedAt: '2024-01-15T10:00:00Z'
    },
    {
      id: 'testimonial-slider',
      meta: {
        name: 'testimonial-slider',
        label: 'Testimonial Slider',
        description: 'Animated testimonial carousel',
        category: 'Marketing',
        icon: 'Quote',
        tags: ['testimonial', 'slider', 'social-proof'],
        author: 'Community',
        version: '1.3.0',
        premium: true
      },
      schema: { /* block schema */ },
      installs: 2150,
      rating: 4.7,
      ratingCount: 89
    }
  ]
};
```

## Runtime Validation [#runtime-validation]

```plaintext
import { BlockSchema } from '@object-ui/types/zod';

const result = BlockSchema.safeParse(myBlock);

if (result.success) {
  console.log('Valid block configuration');
} else {
  console.error('Validation errors:', result.error);
}
```

## Best Practices [#best-practices]

1. **Clear naming** - Use descriptive names for blocks, variables, and slots
2. **Provide defaults** - Set sensible default values for all variables
3. **Document thoroughly** - Add descriptions for variables and slots
4. **Use enums for choices** - Limit options with enum arrays
5. **Version carefully** - Use semantic versioning (1.0.0)
6. **Test variations** - Try different variable combinations
7. **Add previews** - Include preview images for marketplace listings
8. **Tag appropriately** - Use relevant tags for discoverability

## Use Cases [#use-cases]

### Landing Page Components [#landing-page-components]

* Hero sections
* Feature grids
* Pricing tables
* Testimonial carousels
* Call-to-action blocks

### Dashboard Widgets [#dashboard-widgets]

* Metric cards
* Chart containers
* Data tables
* Status indicators

### Form Sections [#form-sections]

* Multi-step wizards
* Address forms
* Payment forms
* Survey sections

### Content Blocks [#content-blocks]

* Blog post templates
* Documentation sections
* FAQ accordions
* Timeline components

## Related [#related]

* [Component Registry](/docs/guide/component-registry) - Registering components
* [Schema Rendering](/docs/guide/schema-rendering) - Rendering blocks
* [Plugins](/docs/guide/plugins) - Extending ObjectUI


# Dashboard Blocks





# Dashboard Blocks [#dashboard-blocks]

Professional dashboard components for displaying metrics, statistics, and data visualizations.

## Stats Card [#stats-card]

Display key metrics with trend indicators.

<SchemaExample id="dashboard/stats-cards-grid" />

## Recent Activity [#recent-activity]

Display recent user activities or transactions.

<SchemaExample id="dashboard/recent-activity-card" />

## Overview Dashboard [#overview-dashboard]

Complete dashboard layout with multiple sections.

<SchemaExample id="dashboard/dashboard-overview" />

## Usage [#usage]

Customize dashboard blocks for your needs:

### Add Real Data [#add-real-data]

```json
{
  "type": "card",
  "dataSource": {
    "api": "/api/stats/revenue",
    "method": "GET"
  }
}
```

### Customize Colors [#customize-colors]

```json
{
  "type": "text",
  "content": "+20.1%",
  "className": "text-emerald-500"
}
```

### Add Actions [#add-actions]

```json
{
  "type": "button",
  "label": "View Details",
  "action": {
    "type": "navigate",
    "path": "/dashboard/details"
  }
}
```

## Next Steps [#next-steps]

* Explore [Form Blocks](/docs/blocks/forms)
* View [Marketing Blocks](/docs/blocks/marketing)
* Learn about [Data Sources](/docs/guide/data-source)


# E-commerce Blocks





# E-commerce Blocks [#e-commerce-blocks]

Professional e-commerce components for online stores and marketplaces.

## Product Card [#product-card]

Product display with image, title, price, and actions.

<SchemaExample id="ecommerce/product-card" />

## Product Grid [#product-grid]

Multiple products in a responsive grid.

<SchemaExample id="ecommerce/product-grid" />

## Shopping Cart [#shopping-cart]

Cart summary with items and checkout.

<SchemaExample id="ecommerce/shopping-cart" />

## Order Summary [#order-summary]

Checkout order review.

<SchemaExample id="ecommerce/order-summary" />

## Usage [#usage]

Customize e-commerce blocks for your store:

### Add Product Data [#add-product-data]

```json
{
  "type": "card",
  "dataSource": {
    "api": "/api/products",
    "method": "GET"
  }
}
```

### Add to Cart Action [#add-to-cart-action]

```json
{
  "type": "button",
  "label": "Add to Cart",
  "action": {
    "type": "submit",
    "endpoint": "/api/cart",
    "method": "POST"
  }
}
```

### Customize Pricing Display [#customize-pricing-display]

```json
{
  "type": "text",
  "content": "$299.99",
  "className": "text-2xl font-bold text-primary"
}
```

## Next Steps [#next-steps]

* Browse [Authentication Blocks](/docs/blocks/authentication)
* Explore [Dashboard Blocks](/docs/blocks/dashboard)
* Learn about [Actions](/docs/core/enhanced-actions)


# Form Blocks





# Form Blocks [#form-blocks]

Professional form layouts for various use cases. All forms are accessible and include proper validation.

## Contact Form [#contact-form]

Simple contact form with name, email, and message fields.

<SchemaExample id="forms/contact-form" />

## Settings Form [#settings-form]

User settings panel with various input types.

<SchemaExample id="forms/settings-form" />

## Newsletter Signup [#newsletter-signup]

Simple newsletter subscription form.

<SchemaExample id="forms/newsletter-signup" />

## Payment Form [#payment-form]

Payment details form with card information.

<SchemaExample id="forms/payment-form" />

## Usage [#usage]

Customize form blocks for your application:

### Add Validation [#add-validation]

```json
{
  "type": "input",
  "name": "email",
  "inputType": "email",
  "required": true,
  "validation": {
    "pattern": "^[a-z0-9._%+-]+@[a-z0-9.-]+\\.[a-z]{2,}$",
    "message": "Please enter a valid email address"
  }
}
```

### Add Submit Action [#add-submit-action]

```json
{
  "type": "button",
  "label": "Submit",
  "action": {
    "type": "submit",
    "endpoint": "/api/contact",
    "method": "POST"
  }
}
```

### Customize Layout [#customize-layout]

```json
{
  "type": "div",
  "className": "grid grid-cols-1 md:grid-cols-2 gap-6"
}
```

## Next Steps [#next-steps]

* Browse [Marketing Blocks](/docs/blocks/marketing)
* Explore [E-commerce Blocks](/docs/blocks/ecommerce)
* Learn about [Form Validation](/docs/guide/fields)


# Building Blocks





# Building Blocks for the Web [#building-blocks-for-the-web]

Pre-built, production-ready UI blocks powered by ObjectUI's schema-driven architecture. Copy the JSON, paste into your application, and ship faster.

## What are Blocks? [#what-are-blocks]

Blocks are complete, ready-to-use UI patterns built with ObjectUI components. Unlike individual components, blocks are composed sections like login forms, pricing tables, dashboard cards, and more—ready to be dropped into your application.

### Quick Preview [#quick-preview]

<SchemaExample id="blocks-gallery/block-gallery-stats-card" />

<SchemaExample id="blocks-gallery/block-gallery-login-card" />

<SchemaExample id="blocks-gallery/block-gallery-notification-item" />

### Why Use Blocks? [#why-use-blocks]

* 🚀 **Ship Faster** - Start with working examples instead of building from scratch
* 📋 **Copy & Paste** - Simple JSON schemas you can copy directly into your project
* 🎨 **Beautiful Design** - Built with Tailwind CSS and Shadcn UI
* ♿️ **Accessible** - WCAG 2.1 AA compliant
* 🌓 **Theme Ready** - Supports light and dark modes out of the box
* 📱 **Responsive** - Mobile-first design that works everywhere

## Available Block Categories [#available-block-categories]

### [Authentication Blocks](/docs/blocks/authentication) [#authentication-blocks]

Login forms, signup pages, password reset flows, and more.

### [Dashboard Blocks](/docs/blocks/dashboard) [#dashboard-blocks]

Stats cards, metric displays, chart layouts for admin panels and dashboards.

### [Form Blocks](/docs/blocks/forms) [#form-blocks]

Contact forms, multi-step wizards, settings panels, and profile editors.

### [Marketing Blocks](/docs/blocks/marketing) [#marketing-blocks]

Pricing tables, feature grids, testimonials, CTAs, and hero sections.

### [E-commerce Blocks](/docs/blocks/ecommerce) [#e-commerce-blocks]

Product cards, shopping carts, checkout flows, and order summaries.

## How to Use Blocks [#how-to-use-blocks]

1. **Browse** the block categories to find what you need
2. **Preview** the block in action with live examples
3. **Copy** the JSON schema from the code tab
4. **Paste** into your ObjectUI application
5. **Customize** by modifying the schema to match your needs

### Example: Using a Block [#example-using-a-block]

All blocks are defined as JSON schemas. Here's how simple it is:

```tsx
import { SchemaRenderer } from '@object-ui/react';

// Copy this JSON from any block
const loginBlockSchema = {
  type: "card",
  className: "max-w-md mx-auto",
  children: [
    // ... block schema here
  ]
};

// Render it in your app
function App() {
  return <SchemaRenderer schema={loginBlockSchema} />;
}
```

## Customization [#customization]

Every block is fully customizable:

* **Styling**: Add or modify `className` properties with Tailwind classes
* **Content**: Change text, labels, and placeholders
* **Layout**: Adjust spacing, sizing, and arrangement
* **Behavior**: Add actions, data sources, and expressions
* **Themes**: Works automatically with your theme configuration

## Block Architecture [#block-architecture]

All blocks follow ObjectUI best practices:

* Built with composable components
* Use semantic HTML structure
* Follow accessibility guidelines
* Leverage Tailwind utility classes
* Support responsive breakpoints
* Include proper ARIA attributes

## Open Source & Free Forever [#open-source--free-forever]

All blocks are open source under the MIT license. Use them in personal projects, commercial applications, or as inspiration for your own designs.

## Next Steps [#next-steps]

* Browse [Authentication Blocks](/docs/blocks/authentication)
* Explore [Dashboard Blocks](/docs/blocks/dashboard)
* Check out [Form Blocks](/docs/blocks/forms)
* View [Marketing Blocks](/docs/blocks/marketing)
* Discover [E-commerce Blocks](/docs/blocks/ecommerce)

## Contributing [#contributing]

Have a block idea? We'd love to see it! Check out our [contribution guidelines](https://github.com/objectstack-ai/objectui/blob/main/CONTRIBUTING.md) to submit your own blocks.


# Marketing Blocks





# Marketing Blocks [#marketing-blocks]

Professional marketing components for landing pages and promotional content.

## Pricing Cards [#pricing-cards]

Responsive pricing table with three tiers.

<SchemaExample id="marketing/pricing-table" />

## Feature Grid [#feature-grid]

Showcase product features in a grid layout.

<SchemaExample id="marketing/features-grid" />

## CTA Section [#cta-section]

Call-to-action section for conversions.

<SchemaExample id="marketing/call-to-action" />

## Testimonials [#testimonials]

Customer testimonials and social proof.

<SchemaExample id="marketing/testimonials" />

## Usage [#usage]

Customize marketing blocks for your campaigns:

### Update Colors [#update-colors]

```json
{
  "type": "card",
  "className": "bg-gradient-to-r from-blue-600 to-purple-600"
}
```

### Add Analytics [#add-analytics]

```json
{
  "type": "button",
  "label": "Get Started",
  "action": {
    "type": "analytics",
    "event": "cta_clicked"
  }
}
```

### Customize Content [#customize-content]

```json
{
  "type": "text",
  "content": "Your custom headline here",
  "className": "text-4xl font-bold"
}
```

## Next Steps [#next-steps]

* Browse [E-commerce Blocks](/docs/blocks/ecommerce)
* Explore [Authentication Blocks](/docs/blocks/authentication)
* Learn about [Theming](/docs/guide/theming)


# Application Schema (AppSchema)





# Application Schema [#application-schema]

The `AppSchema` defines the top-level configuration for your entire ObjectUI application, including navigation menus, branding, layout strategies, and global actions.

## Overview [#overview]

AppSchema provides a declarative way to configure:

* **Navigation menus** - Hierarchical menu structures with icons and badges
* **Branding** - Logo, title, favicon
* **Layout strategies** - Sidebar, header, or empty layout
* **Global actions** - User menu, global toolbar buttons

## Interactive Examples [#interactive-examples]

### Navigation Menu Preview [#navigation-menu-preview]

<SchemaExample id="app/sidebar-navigation" />

### Application Header Bar [#application-header-bar]

<SchemaExample id="app/application-header" />

## Basic Usage [#basic-usage]

```plaintext
import type { AppSchema } from '@object-ui/types';

const app: AppSchema = {
  type: 'app',
  name: 'my-crm',
  title: 'My CRM Application',
  logo: '/logo.svg',
  favicon: '/favicon.ico',
  layout: 'sidebar',
  
  menu: [
    {
      type: 'item',
      label: 'Dashboard',
      icon: 'layout-dashboard',
      path: '/dashboard'
    }
  ],
  
  actions: [
    {
      type: 'user',
      label: 'John Doe',
      avatar: '/avatar.jpg'
    }
  ]
};
```

## Properties [#properties]

### Basic Configuration [#basic-configuration]

| Property      | Type     | Description                          |
| ------------- | -------- | ------------------------------------ |
| `type`        | `'app'`  | Component type identifier (required) |
| `name`        | `string` | Application system identifier        |
| `title`       | `string` | Display title shown in browser       |
| `description` | `string` | Application description              |
| `logo`        | `string` | Logo URL or icon name                |
| `favicon`     | `string` | Favicon URL                          |

### Layout Configuration [#layout-configuration]

| Property | Type                               | Default     | Description            |
| -------- | ---------------------------------- | ----------- | ---------------------- |
| `layout` | `'sidebar' \| 'header' \| 'empty'` | `'sidebar'` | Global layout strategy |

**Layout Options:**

* **`sidebar`** - Standard admin layout with left sidebar navigation
* **`header`** - Top navigation bar only
* **`empty`** - No layout, pages handle their own structure

### Navigation Menu [#navigation-menu]

The `menu` property accepts an array of `MenuItem` objects:

```plaintext
interface MenuItem {
  type?: 'item' | 'group' | 'separator';
  label?: string;
  icon?: string;          // Lucide icon name
  path?: string;          // Route path
  href?: string;          // External link
  children?: MenuItem[];  // Submenu items
  badge?: string | number;
  hidden?: boolean | string; // Visibility condition
}
```

#### Menu Types [#menu-types]

**Item** - Single navigation link

```json
{
  "type": "item",
  "label": "Dashboard",
  "icon": "layout-dashboard",
  "path": "/dashboard",
  "badge": "New"
}
```

**Group** - Collapsible menu group

```json
{
  "type": "group",
  "label": "Sales",
  "icon": "dollar-sign",
  "children": [
    { "type": "item", "label": "Leads", "path": "/leads" },
    { "type": "item", "label": "Deals", "path": "/deals" }
  ]
}
```

**Separator** - Visual separator

```json
{
  "type": "separator"
}
```

### Global Actions [#global-actions]

The `actions` property defines global toolbar buttons:

```plaintext
interface AppAction {
  type: 'button' | 'dropdown' | 'user';
  label?: string;
  icon?: string;
  onClick?: string;
  avatar?: string;        // For type='user'
  description?: string;   // For type='user'
  items?: MenuItem[];     // For type='dropdown' or 'user'
  shortcut?: string;      // Keyboard shortcut
  variant?: 'default' | 'destructive' | 'outline' | 'secondary' | 'ghost' | 'link';
  size?: 'default' | 'sm' | 'lg' | 'icon';
}
```

## Complete Example [#complete-example]

```plaintext
const crm: AppSchema = {
  type: 'app',
  name: 'acme-crm',
  title: 'Acme CRM',
  description: 'Customer Relationship Management System',
  logo: '/acme-logo.svg',
  favicon: '/favicon.ico',
  layout: 'sidebar',
  
  menu: [
    {
      type: 'item',
      label: 'Dashboard',
      icon: 'layout-dashboard',
      path: '/dashboard'
    },
    {
      type: 'separator'
    },
    {
      type: 'group',
      label: 'Sales',
      icon: 'dollar-sign',
      children: [
        {
          type: 'item',
          label: 'Leads',
          icon: 'users',
          path: '/leads',
          badge: 12
        },
        {
          type: 'item',
          label: 'Opportunities',
          icon: 'target',
          path: '/opportunities'
        },
        {
          type: 'item',
          label: 'Quotes',
          icon: 'file-text',
          path: '/quotes'
        }
      ]
    },
    {
      type: 'group',
      label: 'Marketing',
      icon: 'megaphone',
      children: [
        {
          type: 'item',
          label: 'Campaigns',
          path: '/campaigns'
        },
        {
          type: 'item',
          label: 'Email Templates',
          path: '/templates'
        }
      ]
    },
    {
      type: 'separator'
    },
    {
      type: 'item',
      label: 'Settings',
      icon: 'settings',
      path: '/settings',
      hidden: '${user.role !== "admin"}'
    }
  ],
  
  actions: [
    {
      type: 'button',
      label: 'Quick Actions',
      icon: 'zap',
      variant: 'outline',
      onClick: 'openQuickActions'
    },
    {
      type: 'user',
      label: 'John Doe',
      avatar: '/avatars/john.jpg',
      description: 'john@acme.com',
      items: [
        {
          type: 'item',
          label: 'Profile',
          icon: 'user',
          path: '/profile'
        },
        {
          type: 'item',
          label: 'Settings',
          icon: 'settings',
          path: '/settings'
        },
        {
          type: 'separator'
        },
        {
          type: 'item',
          label: 'Logout',
          icon: 'log-out',
          path: '/logout'
        }
      ]
    }
  ]
};
```

## Runtime Validation [#runtime-validation]

Use Zod validation to ensure your app configuration is correct:

```plaintext
import { AppSchema } from '@object-ui/types/zod';

const result = AppSchema.safeParse(myAppConfig);

if (result.success) {
  console.log('Valid app configuration');
} else {
  console.error('Validation errors:', result.error);
}
```

## Conditional Navigation [#conditional-navigation]

Use expression syntax to show/hide menu items based on user permissions:

```json
{
  "type": "item",
  "label": "Admin Panel",
  "path": "/admin",
  "hidden": "${user.role !== 'admin'}"
}
```

## Use Cases [#use-cases]

AppSchema is ideal for:

* **Multi-page applications** - Configure complex application structures with multiple routes
* **Admin dashboards** - Create comprehensive admin panels with role-based navigation
* **CRM systems** - Build customer relationship management interfaces
* **Internal tools** - Develop enterprise internal tools with centralized navigation
* **SaaS products** - Configure multi-tenant applications with customizable layouts

## Best Practices [#best-practices]

1. **Use semantic icons** - Choose Lucide icons that clearly represent the section
2. **Group related items** - Use menu groups to organize navigation
3. **Limit top-level items** - Keep the main menu concise (5-7 items)
4. **Add badges for notifications** - Show counts or status indicators
5. **Hide admin features** - Use conditional visibility for role-based access
6. **Provide keyboard shortcuts** - Add shortcuts for frequently used actions

## Related [#related]

* [Layout Schema](/docs/guide/layout) - Page layout configuration
* [Navigation Components](/docs/components/basic/navigation-menu) - Navigation UI components
* [Theme Schema](/docs/core/theme-schema) - Application theming


# Enhanced Actions





# Enhanced Actions [#enhanced-actions]

ObjectUI's action system has been significantly enhanced to support complex workflows, including AJAX API calls, confirmation dialogs, action chaining, conditional execution, and comprehensive tracking.

## Overview [#overview]

The enhanced `ActionSchema` provides:

* **New action types**: `ajax`, `confirm`, `dialog`
* **Action chaining**: Execute multiple actions sequentially or in parallel
* **Conditional logic**: If/then/else execution based on data
* **Callbacks**: Success and failure handlers
* **Tracking**: Event logging and analytics
* **Retry logic**: Automatic retry with configurable backoff

## Interactive Examples [#interactive-examples]

### Action Buttons [#action-buttons]

<SchemaExample id="actions/action-button-variants" />

### Confirmation Dialog Pattern [#confirmation-dialog-pattern]

<SchemaExample id="actions/confirmation-dialog" />

### Action Toolbar [#action-toolbar]

<SchemaExample id="actions/action-toolbar" />

## Action Types [#action-types]

### Ajax Actions [#ajax-actions]

Execute API calls with full request configuration:

```plaintext
const ajaxAction: ActionSchema = {
  type: 'action',
  label: 'Load Data',
  actionType: 'ajax',
  api: '/api/users',
  method: 'GET',
  headers: {
    'Authorization': 'Bearer token'
  },
  data: {
    filter: 'active'
  },
  onSuccess: {
    type: 'toast',
    message: 'Data loaded successfully'
  },
  onFailure: {
    type: 'message',
    message: 'Failed to load data'
  }
};
```

**Ajax Properties:**

* `api` - API endpoint URL
* `method` - HTTP method (GET, POST, PUT, DELETE, PATCH)
* `data` - Request body/payload
* `headers` - Custom HTTP headers
* `timeout` - Request timeout in milliseconds
* `retry` - Retry configuration

### Confirm Actions [#confirm-actions]

Show confirmation dialog before executing:

```plaintext
const confirmAction: ActionSchema = {
  type: 'action',
  label: 'Delete Record',
  actionType: 'confirm',
  confirm: {
    title: 'Confirm Deletion',
    message: 'Are you sure you want to delete this record?',
    confirmText: 'Yes, Delete',
    cancelText: 'Cancel',
    confirmVariant: 'destructive'
  },
  api: '/api/records/123',
  method: 'DELETE'
};
```

**Confirm Properties:**

* `title` - Dialog title
* `message` - Confirmation message
* `confirmText` - Confirm button text
* `cancelText` - Cancel button text
* `confirmVariant` - Button style

### Dialog Actions [#dialog-actions]

Open a modal or dialog:

```plaintext
const dialogAction: ActionSchema = {
  type: 'action',
  label: 'Edit Details',
  actionType: 'dialog',
  dialog: {
    title: 'Edit Record',
    size: 'lg',
    content: {
      type: 'form',
      fields: [
        { name: 'name', type: 'input', label: 'Name' },
        { name: 'email', type: 'input', label: 'Email' }
      ]
    },
    actions: [
      {
        type: 'action',
        label: 'Save',
        actionType: 'ajax',
        api: '/api/records/123',
        method: 'PUT'
      }
    ]
  }
};
```

## Action Chaining [#action-chaining]

Execute multiple actions in sequence or parallel:

```plaintext
const chainedAction: ActionSchema = {
  type: 'action',
  label: 'Process Order',
  actionType: 'ajax',
  api: '/api/orders/process',
  method: 'POST',
  
  chain: [
    {
      type: 'action',
      label: 'Send Email',
      actionType: 'ajax',
      api: '/api/emails/send',
      method: 'POST'
    },
    {
      type: 'action',
      label: 'Update Inventory',
      actionType: 'ajax',
      api: '/api/inventory/update',
      method: 'PUT'
    },
    {
      type: 'action',
      label: 'Log Event',
      actionType: 'ajax',
      api: '/api/events/log',
      method: 'POST'
    }
  ],
  
  chainMode: 'sequential'  // or 'parallel'
};
```

**Chain Modes:**

* `sequential` - Execute actions one after another (default)
* `parallel` - Execute all actions simultaneously

## Conditional Execution [#conditional-execution]

Execute different actions based on conditions:

```plaintext
const conditionalAction: ActionSchema = {
  type: 'action',
  label: 'Approve',
  actionType: 'button',
  
  condition: {
    expression: '${data.amount > 1000}',
    then: {
      type: 'action',
      label: 'Require Manager Approval',
      actionType: 'confirm',
      confirm: {
        title: 'Manager Approval Required',
        message: 'Amount exceeds $1000. Manager approval needed.'
      }
    },
    else: {
      type: 'action',
      label: 'Auto Approve',
      actionType: 'ajax',
      api: '/api/approve',
      method: 'POST'
    }
  }
};
```

**Condition Properties:**

* `expression` - JavaScript expression to evaluate
* `then` - Action(s) to execute if true
* `else` - Action(s) to execute if false

## Callbacks [#callbacks]

Handle success and failure scenarios:

```plaintext
const actionWithCallbacks: ActionSchema = {
  type: 'action',
  label: 'Submit',
  actionType: 'ajax',
  api: '/api/submit',
  method: 'POST',
  
  onSuccess: {
    type: 'toast',
    message: 'Submitted successfully!'
  },
  
  onFailure: {
    type: 'dialog',
    dialog: {
      title: 'Submission Failed',
      content: {
        type: 'text',
        value: 'Please try again or contact support.'
      }
    }
  }
};
```

**Callback Types:**

* `toast` - Show toast notification
* `message` - Show message dialog
* `redirect` - Navigate to URL
* `reload` - Reload data
* `ajax` - Execute another API call
* `dialog` - Open dialog
* `custom` - Custom handler

## Action Tracking [#action-tracking]

Track actions for analytics:

```plaintext
const trackedAction: ActionSchema = {
  type: 'action',
  label: 'Download Report',
  actionType: 'ajax',
  api: '/api/reports/download',
  
  tracking: {
    enabled: true,
    event: 'report_downloaded',
    metadata: {
      reportType: 'sales',
      format: 'pdf',
      dateRange: '2024-01'
    }
  }
};
```

## Retry Logic [#retry-logic]

Automatically retry failed requests:

```plaintext
const retryAction: ActionSchema = {
  type: 'action',
  label: 'Submit',
  actionType: 'ajax',
  api: '/api/submit',
  method: 'POST',
  
  timeout: 30000,  // 30 seconds
  
  retry: {
    maxAttempts: 3,
    delay: 1000  // 1 second between retries
  }
};
```

## Complete Example [#complete-example]

A comprehensive action combining multiple features:

```plaintext
const complexAction: ActionSchema = {
  type: 'action',
  label: 'Process Order',
  icon: 'shopping-cart',
  variant: 'default',
  
  // Confirm before processing
  actionType: 'confirm',
  confirm: {
    title: 'Confirm Order',
    message: 'Process this order for ${data.customerName}?',
    confirmText: 'Process Order',
    confirmVariant: 'default'
  },
  
  // Conditional logic
  condition: {
    expression: '${data.totalAmount > 1000}',
    then: {
      type: 'action',
      actionType: 'ajax',
      api: '/api/orders/process-premium',
      method: 'POST'
    },
    else: {
      type: 'action',
      actionType: 'ajax',
      api: '/api/orders/process-standard',
      method: 'POST'
    }
  },
  
  // Action chain
  chain: [
    {
      type: 'action',
      label: 'Send Confirmation Email',
      actionType: 'ajax',
      api: '/api/emails/order-confirmation',
      method: 'POST',
      data: {
        orderId: '${data.id}',
        customerEmail: '${data.customerEmail}'
      }
    },
    {
      type: 'action',
      label: 'Update Inventory',
      actionType: 'ajax',
      api: '/api/inventory/update',
      method: 'PUT',
      data: {
        items: '${data.items}'
      }
    },
    {
      type: 'action',
      label: 'Create Invoice',
      actionType: 'ajax',
      api: '/api/invoices/create',
      method: 'POST'
    }
  ],
  chainMode: 'sequential',
  
  // Callbacks
  onSuccess: {
    type: 'toast',
    message: 'Order processed successfully!'
  },
  onFailure: {
    type: 'dialog',
    dialog: {
      title: 'Order Processing Failed',
      content: {
        type: 'text',
        value: 'Unable to process order. Please try again.'
      }
    }
  },
  
  // Tracking
  tracking: {
    enabled: true,
    event: 'order_processed',
    metadata: {
      source: 'web_app',
      amount: '${data.totalAmount}'
    }
  },
  
  // Retry
  timeout: 60000,
  retry: {
    maxAttempts: 3,
    delay: 2000
  },
  
  // Post-action behavior
  reload: true,
  close: true,
  redirect: '/orders/success'
};
```

## Runtime Validation [#runtime-validation]

```plaintext
import { ActionSchema } from '@object-ui/types/zod';

const result = ActionSchema.safeParse(myAction);

if (result.success) {
  console.log('Valid action configuration');
} else {
  console.error('Validation errors:', result.error);
}
```

## Use Cases [#use-cases]

Enhanced Actions are ideal for:

* **API integration** - Connect to backend services and external APIs
* **Multi-step processes** - Execute complex workflows with multiple stages
* **Form submissions** - Handle form data with validation and callbacks
* **Confirmation dialogs** - Add safety checks for critical operations
* **Event tracking** - Monitor user interactions for analytics
* **Batch operations** - Process multiple items in sequence or parallel

## Best Practices [#best-practices]

1. **Use confirm for destructive actions** - Always confirm delete, archive, etc.
2. **Provide clear feedback** - Use callbacks to inform users of success/failure
3. **Chain related operations** - Group logically related API calls
4. **Track important events** - Enable tracking for business-critical actions
5. **Set appropriate timeouts** - Don't let users wait indefinitely
6. **Retry transient failures** - Use retry for network-related errors
7. **Keep chains short** - Long chains can be hard to debug

## Related [#related]

* [Building a CRUD App](/docs/guide/building-crud-app) - CRUD operations with actions
* [Form](/docs/components/form) - Form submission actions
* [Data Source](/docs/guide/data-source) - API integration


# Report Schema (ReportSchema)





# Report Schema [#report-schema]

The `ReportSchema` enables creating comprehensive data reports with field aggregation, multiple export formats, and automated scheduling.

## Overview [#overview]

ReportSchema provides:

* **Field aggregation** - Sum, average, count, min, max, distinct
* **Export formats** - PDF, Excel, CSV, JSON, HTML
* **Scheduled reports** - Daily, weekly, monthly, quarterly, yearly
* **Email distribution** - Automatic report delivery
* **Interactive builder** - Report configuration UI
* **Data filtering** - Complex filter criteria

## Interactive Examples [#interactive-examples]

### Sales Report Header [#sales-report-header]

<SchemaExample id="report/report-header-with-kpis" />

### Report Data Table [#report-data-table]

<SchemaExample id="report/report-breakdown-table" />

### Schedule Configuration Preview [#schedule-configuration-preview]

<SchemaExample id="report/report-scheduling" />

## Basic Usage [#basic-usage]

```plaintext
import type { ReportSchema } from '@object-ui/types';

const salesReport: ReportSchema = {
  type: 'report',
  title: 'Monthly Sales Report',
  description: 'Sales performance analysis',
  
  fields: [
    {
      name: 'total_sales',
      label: 'Total Sales',
      type: 'number',
      aggregation: 'sum',
      format: 'currency'
    },
    {
      name: 'order_count',
      label: 'Orders',
      type: 'number',
      aggregation: 'count'
    }
  ],
  
  filters: [
    {
      field: 'date',
      operator: 'between',
      values: ['2024-01-01', '2024-01-31']
    }
  ],
  
  showExportButtons: true
};
```

## Properties [#properties]

### Basic Configuration [#basic-configuration]

| Property      | Type         | Description                          |
| ------------- | ------------ | ------------------------------------ |
| `type`        | `'report'`   | Component type identifier (required) |
| `title`       | `string`     | Report title                         |
| `description` | `string`     | Report description                   |
| `dataSource`  | `DataSource` | Data source configuration            |

### Report Fields [#report-fields]

```plaintext
interface ReportField {
  name: string;                    // Field name
  label?: string;                  // Display label

  // Drives type-aware cell rendering. Auto-hydrated from the bound
  // object's ObjectField when the report has an `objectName`.
  type?:
    | 'string' | 'text' | 'number' | 'date' | 'datetime' | 'time' | 'boolean'
    | 'select' | 'multi_select' | 'status'
    | 'lookup' | 'reference' | 'master_detail'
    | 'email' | 'url' | 'phone' | 'currency' | 'percent'
    | 'image' | 'file' | 'user' | 'owner'
    | 'richtext' | 'html' | 'markdown' | 'json' | 'tags';

  // Used when type is select / multi_select / status.
  options?: Array<{ value: string | number; label: string; color?: string }>;

  // Used when type is lookup / reference / master_detail. Enables
  // deep-links to the related record's detail page.
  referenceTo?: string;

  aggregation?: 'sum' | 'avg' | 'min' | 'max' | 'count' | 'distinct';
  format?: string;                 // Display format
  showInSummary?: boolean;         // Show in summary section
  sortOrder?: number;              // Sort order

  // Legacy opt-in: render a plain string cell as a Badge.
  // For most cases prefer `type: 'select'` + `options`.
  renderAs?: 'badge' | 'text';
  colorMap?: Record<string, string>; // value → CSS class
}
```

#### Type-aware rendering [#type-aware-rendering]

The runtime maps `field.type` to a cell renderer from
`@object-ui/fields`'s `getCellRenderer` registry. Examples: `select`
becomes a coloured `Badge`, `lookup` becomes a deep link to the
related record, `boolean` becomes ✓/✗, `email`/`url`/`phone` become
`mailto:`/external/`tel:` links, `image` becomes a thumbnail. Any
unknown type falls back to plain text.

When the report binds an `objectName`, columns inherit `type`,
`options`, `referenceTo`, and `label` from the corresponding
`ObjectField` automatically — author-provided values always win.

### Aggregation Types [#aggregation-types]

* **`sum`** - Total of all values
* **`avg`** - Average value
* **`min`** - Minimum value
* **`max`** - Maximum value
* **`count`** - Count of records
* **`distinct`** - Count of unique values

### Filters [#filters]

```plaintext
interface ReportFilter {
  field: string;
  operator: 'equals' | 'not_equals' | 'contains' | 'greater_than' | 
            'less_than' | 'between' | 'in' | 'not_in';
  value?: any;
  values?: any[];  // For 'between' and 'in' operators
}
```

### Group By [#group-by]

```plaintext
interface ReportGroupBy {
  field: string;
  label?: string;
  sort?: 'asc' | 'desc';
}
```

## Report Sections [#report-sections]

Define report structure with sections:

```plaintext
interface ReportSection {
  type: 'header' | 'summary' | 'chart' | 'table' | 'text' | 'page-break';
  title?: string;
  content?: SchemaNode | SchemaNode[];
  chart?: ChartSchema;        // For type='chart'
  columns?: ReportField[];    // For type='table'
  text?: string;              // For type='text'
  visible?: boolean | string; // Visibility condition
}
```

## Export Configuration [#export-configuration]

```plaintext
interface ReportExportConfig {
  format: 'pdf' | 'excel' | 'csv' | 'json' | 'html';
  filename?: string;
  includeHeaders?: boolean;
  orientation?: 'portrait' | 'landscape';  // PDF only
  pageSize?: 'A4' | 'A3' | 'Letter' | 'Legal';  // PDF only
  options?: Record<string, any>;
}
```

## Scheduling [#scheduling]

```plaintext
interface ReportSchedule {
  enabled?: boolean;
  frequency?: 'once' | 'daily' | 'weekly' | 'monthly' | 'quarterly' | 'yearly';
  dayOfWeek?: number;          // For weekly (0-6)
  dayOfMonth?: number;         // For monthly (1-31)
  time?: string;               // HH:mm format
  timezone?: string;
  recipients?: string[];       // Email addresses
  subject?: string;
  body?: string;
  formats?: ReportExportFormat[];  // Formats to attach
}
```

## Complete Example [#complete-example]

```plaintext
const comprehensiveReport: ReportSchema = {
  type: 'report',
  title: 'Quarterly Sales Analysis',
  description: 'Comprehensive sales performance analysis by region and product',
  
  // Data source
  dataSource: {
    provider: 'api',
    read: {
      url: '/api/sales',
      method: 'GET'
    }
  },
  
  // Report fields
  fields: [
    {
      name: 'region',
      label: 'Region',
      type: 'string'
    },
    {
      name: 'product',
      label: 'Product',
      type: 'string'
    },
    {
      name: 'revenue',
      label: 'Revenue',
      type: 'number',
      aggregation: 'sum',
      format: 'currency',
      showInSummary: true
    },
    {
      name: 'units_sold',
      label: 'Units Sold',
      type: 'number',
      aggregation: 'sum',
      showInSummary: true
    },
    {
      name: 'avg_price',
      label: 'Average Price',
      type: 'number',
      aggregation: 'avg',
      format: 'currency'
    }
  ],
  
  // Filters
  filters: [
    {
      field: 'date',
      operator: 'between',
      values: ['2024-01-01', '2024-03-31']
    },
    {
      field: 'status',
      operator: 'equals',
      value: 'completed'
    }
  ],
  
  // Grouping
  groupBy: [
    {
      field: 'region',
      label: 'Region',
      sort: 'asc'
    },
    {
      field: 'product',
      label: 'Product',
      sort: 'desc'
    }
  ],
  
  // Report sections
  sections: [
    {
      type: 'header',
      title: 'Executive Summary'
    },
    {
      type: 'summary',
      title: 'Key Metrics'
    },
    {
      type: 'chart',
      title: 'Revenue Trend',
      chart: {
        type: 'chart',
        chartType: 'line',
        data: [],
        series: [
          {
            name: 'Revenue',
            type: 'line',
            dataKey: 'revenue'
          }
        ]
      }
    },
    {
      type: 'table',
      title: 'Detailed Breakdown',
      columns: [
        { name: 'region', label: 'Region' },
        { name: 'product', label: 'Product' },
        { name: 'revenue', label: 'Revenue', aggregation: 'sum' },
        { name: 'units_sold', label: 'Units', aggregation: 'sum' }
      ]
    },
    {
      type: 'page-break'
    },
    {
      type: 'text',
      text: 'Report generated on ${new Date().toLocaleDateString()}'
    }
  ],
  
  // Schedule configuration
  schedule: {
    enabled: true,
    frequency: 'monthly',
    dayOfMonth: 1,
    time: '09:00',
    timezone: 'America/New_York',
    recipients: [
      'sales-team@company.com',
      'management@company.com'
    ],
    subject: 'Monthly Sales Report - ${date}',
    body: 'Please find attached the monthly sales report.',
    formats: ['pdf', 'excel']
  },
  
  // Export configuration
  defaultExportFormat: 'pdf',
  exportConfigs: {
    pdf: {
      format: 'pdf',
      filename: 'sales-report-${date}.pdf',
      orientation: 'landscape',
      pageSize: 'A4',
      includeHeaders: true
    },
    excel: {
      format: 'excel',
      filename: 'sales-report-${date}.xlsx',
      includeHeaders: true
    },
    csv: {
      format: 'csv',
      filename: 'sales-data-${date}.csv',
      includeHeaders: true
    }
  },
  
  // UI options
  showExportButtons: true,
  showPrintButton: true,
  showScheduleButton: true,
  refreshInterval: 300  // Auto-refresh every 5 minutes
};
```

## Report Builder [#report-builder]

Use `ReportBuilderSchema` for interactive report creation:

```plaintext
import type { ReportBuilderSchema } from '@object-ui/types';

const builder: ReportBuilderSchema = {
  type: 'report-builder',
  
  report: {
    // Initial report configuration
  },
  
  dataSources: [
    { provider: 'api', read: { url: '/api/sales' } },
    { provider: 'api', read: { url: '/api/customers' } }
  ],
  
  availableFields: [
    { name: 'revenue', label: 'Revenue', type: 'number' },
    { name: 'units', label: 'Units Sold', type: 'number' }
  ],
  
  showPreview: true,
  onSave: 'handleSaveReport',
  onCancel: 'handleCancel'
};
```

## Report Viewer [#report-viewer]

Use `ReportViewerSchema` to display generated reports:

```plaintext
import type { ReportViewerSchema } from '@object-ui/types';

const viewer: ReportViewerSchema = {
  type: 'report-viewer',
  report: salesReport,
  data: reportData,
  showToolbar: true,
  allowExport: true,
  allowPrint: true,
  loading: false
};
```

## Runtime Validation [#runtime-validation]

```plaintext
import { ReportSchema } from '@object-ui/types/zod';

const result = ReportSchema.safeParse(myReport);

if (result.success) {
  console.log('Valid report configuration');
} else {
  console.error('Validation errors:', result.error);
}
```

## Use Cases [#use-cases]

ReportSchema is perfect for:

* **Analytics dashboards** - Display key business metrics and KPIs
* **Business intelligence** - Generate insights from operational data
* **Automated reporting** - Schedule regular reports for stakeholders
* **Data exports** - Provide data in multiple formats (PDF, Excel, CSV)
* **Compliance reporting** - Generate audit trails and regulatory reports
* **Executive summaries** - Create high-level overviews for management

## Best Practices [#best-practices]

1. **Use meaningful aggregations** - Choose aggregation types that make sense for the data
2. **Limit field count** - Too many fields make reports hard to read
3. **Group logically** - Group by dimensions that provide insights
4. **Test exports** - Verify all export formats render correctly
5. **Set reasonable schedules** - Don't over-email recipients
6. **Include filters** - Allow users to customize date ranges
7. **Add summary sections** - Provide key metrics at the top

## Related [#related]

* [Charts Plugin](/docs/plugins/plugin-charts) - Data visualization
* [Data Table](/docs/components/complex/data-table) - Tabular data display
* [Data Source](/docs/guide/data-source) - Data integration


# SchemaRenderer





The SchemaRenderer is the heart of ObjectUI. It takes a JSON schema and dynamically renders the appropriate React components based on the schema's `type` field.

## How It Works [#how-it-works]

The SchemaRenderer uses the Component Registry to look up the appropriate component for each schema type and renders it with the provided props.

```plaintext
import { SchemaRenderer } from '@object-ui/react';

<SchemaRenderer schema={{
  type: 'card',
  title: 'Hello World',
  children: [
    { type: 'text', content: 'This is rendered from JSON!' }
  ]
}} />
```

## Basic Example [#basic-example]

<SchemaExample id="core-schema-renderer/schemarenderer-in-action" />

## Nested Schemas [#nested-schemas]

The SchemaRenderer automatically handles nested schemas:

<SchemaExample id="core-schema-renderer/nested-schema-example" />

## Schema Structure [#schema-structure]

```plaintext
interface SchemaNode {
  type: string;                  // Component type (e.g., 'card', 'button', 'text')
  id?: string;                   // Unique identifier
  className?: string;            // Tailwind CSS classes
  children?: SchemaNode | SchemaNode[]; // Child components
  props?: Record<string, any>;   // Component-specific props
  [key: string]: any;            // Any other component props
}
```

## Error Handling [#error-handling]

When an unknown component type is encountered, SchemaRenderer displays a helpful error message:

<SchemaExample id="core-schema-renderer/unknown-component-type" />

## Component Registry [#component-registry]

The SchemaRenderer uses the Component Registry to resolve component types:

```plaintext
import { ComponentRegistry } from '@object-ui/core';

// Register a custom component
ComponentRegistry.register('my-widget', MyWidgetComponent);

// Now you can use it in schemas
<SchemaRenderer schema={{
  type: 'my-widget',
  customProp: 'value'
}} />
```

## Usage in Applications [#usage-in-applications]

### Simple Rendering [#simple-rendering]

```plaintext
import { SchemaRenderer } from '@object-ui/react';

function App() {
  const schema = {
    type: 'page',
    title: 'Dashboard',
    body: [
      { type: 'text', content: 'Welcome to your dashboard' }
    ]
  };

  return <SchemaRenderer schema={schema} />;
}
```

### Dynamic Schemas [#dynamic-schemas]

```plaintext
import { SchemaRenderer } from '@object-ui/react';
import { useState, useEffect } from 'react';

function DynamicPage() {
  const [schema, setSchema] = useState(null);

  useEffect(() => {
    // Fetch schema from API
    fetch('/api/page-schema')
      .then(res => res.json())
      .then(setSchema);
  }, []);

  if (!schema) return <div>Loading...</div>;

  return <SchemaRenderer schema={schema} />;
}
```

### With Props [#with-props]

You can pass additional props to the rendered component:

```plaintext
<SchemaRenderer 
  schema={{ type: 'button', label: 'Click Me' }}
  onClick={() => console.log('Clicked!')}
  className="extra-classes"
/>
```

## Data Attributes [#data-attributes]

SchemaRenderer automatically adds data attributes for debugging:

* `data-obj-id`: The schema's id field
* `data-obj-type`: The schema's type field

These can be used for debugging, testing, or styling:

```css
[data-obj-type="card"] {
  /* Target all card components */
}
```

## Advanced Features [#advanced-features]

### String Rendering [#string-rendering]

If a schema is just a string, it's rendered as text:

```plaintext
<SchemaRenderer schema="Hello World" />
// Renders: Hello World
```

### Null/Undefined Handling [#nullundefined-handling]

Null or undefined schemas render nothing:

```plaintext
<SchemaRenderer schema={null} />
// Renders: null
```

## Related [#related]

* [Component Registry](/docs/guide/component-registry) - Register custom components
* [Schema Rendering Guide](/docs/guide/schema-rendering) - Deep dive into schema rendering


# Theme Schema (ThemeSchema)





# Theme Schema [#theme-schema]

The `ThemeSchema` provides a comprehensive theming system for ObjectUI applications, supporting light/dark modes, custom color palettes, typography, and CSS variable integration.

## Overview [#overview]

ThemeSchema enables:

* **Multiple theme definitions** - Create and switch between custom themes
* **Light/Dark modes** - Automatic mode switching with persistence
* **Color palettes** - 20+ semantic colors for consistent design
* **Typography system** - Font families, sizes, weights, and line heights
* **Tailwind integration** - Direct integration with Tailwind CSS
* **CSS variables** - Custom CSS variable support

## Interactive Examples [#interactive-examples]

### Color Palette Preview [#color-palette-preview]

<SchemaExample id="theme/semantic-color-palette" />

### Theme-Aware Components [#theme-aware-components]

<SchemaExample id="theme/theme-aware-ui-elements" />

## Basic Usage [#basic-usage]

```plaintext
import type { ThemeSchema } from '@object-ui/types';

const theme: ThemeSchema = {
  type: 'theme',
  mode: 'dark',
  themes: [
    {
      name: 'professional',
      label: 'Professional',
      light: {
        primary: '#3b82f6',
        background: '#ffffff',
        foreground: '#0f172a'
      },
      dark: {
        primary: '#60a5fa',
        background: '#0f172a',
        foreground: '#f1f5f9'
      }
    }
  ],
  activeTheme: 'professional',
  allowSwitching: true,
  persistPreference: true
};
```

## Properties [#properties]

### Theme Configuration [#theme-configuration]

| Property            | Type                            | Default   | Description                           |
| ------------------- | ------------------------------- | --------- | ------------------------------------- |
| `type`              | `'theme'`                       | -         | Component type identifier (required)  |
| `mode`              | `'light' \| 'dark' \| 'system'` | `'light'` | Current theme mode                    |
| `themes`            | `ThemeDefinition[]`             | -         | Available theme definitions           |
| `activeTheme`       | `string`                        | -         | Currently active theme name           |
| `allowSwitching`    | `boolean`                       | `false`   | Allow users to switch themes          |
| `persistPreference` | `boolean`                       | `false`   | Save theme preference to localStorage |
| `storageKey`        | `string`                        | `'theme'` | Storage key for persisting theme      |

## Theme Definition [#theme-definition]

```plaintext
interface ThemeDefinition {
  name: string;           // Theme identifier
  label?: string;         // Display name
  light?: ColorPalette;   // Light mode colors
  dark?: ColorPalette;    // Dark mode colors
  typography?: Typography;
  spacing?: SpacingScale;
  radius?: BorderRadius;
  cssVariables?: Record<string, string>;
  tailwind?: Record<string, any>;
}
```

## Color Palette [#color-palette]

Semantic color tokens for consistent design:

```plaintext
interface ColorPalette {
  // Brand colors
  primary?: string;
  secondary?: string;
  accent?: string;
  
  // Base colors
  background?: string;
  foreground?: string;
  muted?: string;
  mutedForeground?: string;
  
  // Component colors
  card?: string;
  cardForeground?: string;
  popover?: string;
  popoverForeground?: string;
  
  // UI elements
  border?: string;
  input?: string;
  ring?: string;
  
  // Status colors
  success?: string;
  warning?: string;
  destructive?: string;
  info?: string;
}
```

### Example Color Palette [#example-color-palette]

```json
{
  "light": {
    "primary": "#3b82f6",
    "secondary": "#64748b",
    "accent": "#8b5cf6",
    "background": "#ffffff",
    "foreground": "#0f172a",
    "muted": "#f1f5f9",
    "mutedForeground": "#64748b",
    "border": "#e2e8f0",
    "input": "#e2e8f0",
    "ring": "#3b82f6",
    "success": "#10b981",
    "warning": "#f59e0b",
    "destructive": "#ef4444",
    "info": "#3b82f6"
  },
  "dark": {
    "primary": "#60a5fa",
    "secondary": "#94a3b8",
    "accent": "#a78bfa",
    "background": "#0f172a",
    "foreground": "#f1f5f9",
    "muted": "#1e293b",
    "mutedForeground": "#94a3b8",
    "border": "#334155",
    "input": "#334155",
    "ring": "#60a5fa",
    "success": "#34d399",
    "warning": "#fbbf24",
    "destructive": "#f87171",
    "info": "#60a5fa"
  }
}
```

## Typography System [#typography-system]

```plaintext
interface Typography {
  fontSans?: string[];    // Sans-serif font stack
  fontSerif?: string[];   // Serif font stack
  fontMono?: string[];    // Monospace font stack
  fontSize?: number;      // Base font size (rem)
  lineHeight?: number;    // Base line height
  headingWeight?: number; // Font weight for headings
  bodyWeight?: number;    // Font weight for body text
}
```

### Example Typography [#example-typography]

```json
{
  "typography": {
    "fontSans": ["Inter", "system-ui", "sans-serif"],
    "fontSerif": ["Merriweather", "Georgia", "serif"],
    "fontMono": ["JetBrains Mono", "monospace"],
    "fontSize": 16,
    "lineHeight": 1.5,
    "headingWeight": 600,
    "bodyWeight": 400
  }
}
```

## Spacing Scale [#spacing-scale]

```plaintext
interface SpacingScale {
  base?: number;               // Base spacing unit (rem)
  scale?: Record<string, string>;  // Custom spacing values
}
```

## Border Radius [#border-radius]

```plaintext
interface BorderRadius {
  sm?: string;
  default?: string;
  md?: string;
  lg?: string;
  xl?: string;
}
```

## Complete Theme Example [#complete-theme-example]

```plaintext
const professionalTheme: ThemeSchema = {
  type: 'theme',
  mode: 'system',
  
  themes: [
    {
      name: 'professional',
      label: 'Professional',
      
      light: {
        primary: '#3b82f6',
        secondary: '#64748b',
        accent: '#8b5cf6',
        background: '#ffffff',
        foreground: '#0f172a',
        muted: '#f1f5f9',
        mutedForeground: '#64748b',
        card: '#ffffff',
        cardForeground: '#0f172a',
        popover: '#ffffff',
        popoverForeground: '#0f172a',
        border: '#e2e8f0',
        input: '#e2e8f0',
        ring: '#3b82f6',
        success: '#10b981',
        warning: '#f59e0b',
        destructive: '#ef4444',
        info: '#3b82f6'
      },
      
      dark: {
        primary: '#60a5fa',
        secondary: '#94a3b8',
        accent: '#a78bfa',
        background: '#0f172a',
        foreground: '#f1f5f9',
        muted: '#1e293b',
        mutedForeground: '#94a3b8',
        card: '#1e293b',
        cardForeground: '#f1f5f9',
        popover: '#1e293b',
        popoverForeground: '#f1f5f9',
        border: '#334155',
        input: '#334155',
        ring: '#60a5fa',
        success: '#34d399',
        warning: '#fbbf24',
        destructive: '#f87171',
        info: '#60a5fa'
      },
      
      typography: {
        fontSans: ['Inter', 'system-ui', 'sans-serif'],
        fontSize: 16,
        lineHeight: 1.5,
        headingWeight: 600,
        bodyWeight: 400
      },
      
      spacing: {
        base: 0.25,
        scale: {
          '0': '0',
          '1': '0.25rem',
          '2': '0.5rem',
          '4': '1rem',
          '8': '2rem'
        }
      },
      
      radius: {
        sm: '0.25rem',
        default: '0.5rem',
        md: '0.75rem',
        lg: '1rem',
        xl: '1.5rem'
      },
      
      cssVariables: {
        '--header-height': '4rem',
        '--sidebar-width': '16rem'
      }
    }
  ],
  
  activeTheme: 'professional',
  allowSwitching: true,
  persistPreference: true,
  storageKey: 'app-theme'
};
```

## Theme Switcher [#theme-switcher]

Use `ThemeSwitcherSchema` to add a theme switcher UI:

```plaintext
import type { ThemeSwitcherSchema } from '@object-ui/types';

const switcher: ThemeSwitcherSchema = {
  type: 'theme-switcher',
  variant: 'dropdown',
  showMode: true,      // Show light/dark mode toggle
  showThemes: true,    // Show theme selector
  lightIcon: 'Sun',
  darkIcon: 'Moon'
};
```

### Switcher Variants [#switcher-variants]

* **`dropdown`** - Dropdown menu with theme options
* **`toggle`** - Simple light/dark toggle button
* **`buttons`** - Button group with all options

## Theme Preview [#theme-preview]

Use `ThemePreviewSchema` to preview themes:

```plaintext
import type { ThemePreviewSchema } from '@object-ui/types';

const preview: ThemePreviewSchema = {
  type: 'theme-preview',
  theme: professionalTheme.themes[0],
  mode: 'light',
  showColors: true,
  showTypography: true,
  showComponents: true
};
```

## Runtime Validation [#runtime-validation]

```plaintext
import { ThemeSchema } from '@object-ui/types/zod';

const result = ThemeSchema.safeParse(myTheme);

if (result.success) {
  console.log('Valid theme configuration');
} else {
  console.error('Validation errors:', result.error);
}
```

## Use Cases [#use-cases]

ThemeSchema is perfect for:

* **Brand consistency** - Maintain consistent visual identity across applications
* **White-labeling** - Enable multi-tenant applications with custom branding
* **Accessibility** - Provide light/dark modes for user preference
* **Design systems** - Implement comprehensive design tokens
* **A/B testing** - Test different color schemes and typography

## Best Practices [#best-practices]

1. **Use semantic colors** - Stick to the semantic color tokens for consistency
2. **Test both modes** - Always test light and dark modes
3. **Maintain contrast** - Ensure sufficient color contrast for accessibility
4. **Limit custom themes** - Offer 2-3 well-designed themes max
5. **Respect system preferences** - Use `mode: 'system'` by default
6. **Persist preferences** - Enable `persistPreference` for better UX

## Related [#related]

* [App Schema](/docs/core/app-schema) - Application configuration
* [CSS Variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) - MDN documentation
* [Tailwind Theming](https://tailwindcss.com/docs/theme) - Tailwind CSS theming guide


# AutoNumber Field





The AutoNumber Field component displays auto-generated sequence numbers. This is a read-only field where the value is automatically generated by the backend when records are created.

## Basic Usage [#basic-usage]

<SchemaExample id="fields-auto-number/basic-autonumber" />

## Custom Format [#custom-format]

<SchemaExample id="fields-auto-number/invoice-number-format" />

## Date-Based Format [#date-based-format]

<SchemaExample id="fields-auto-number/date-based-ticket-id" />

## Field Schema [#field-schema]

```plaintext
interface AutoNumberFieldSchema {
  type: 'auto_number';
  name: string;                  // Field name/ID
  label?: string;                // Field label
  value?: string | number;       // Generated value (read-only)
  readonly: true;                // Always read-only
  className?: string;            // Additional CSS classes
  
  // AutoNumber Configuration
  format?: string;               // Number format template
  starting_number?: number;      // Starting sequence number
}
```

## Format Templates [#format-templates]

Common format patterns:

### Simple Sequential [#simple-sequential]

```plaintext
format: '{0000}'           // 0001, 0002, 0003...
format: '{00000}'          // 00001, 00002, 00003...
```

### With Prefix [#with-prefix]

```plaintext
format: 'ORD-{0000}'       // ORD-0001, ORD-0002...
format: 'INV-{00000}'      // INV-00001, INV-00002...
format: 'CUST-{000}'       // CUST-001, CUST-002...
```

### Date-Based [#date-based]

```plaintext
format: '{YYYY}-{0000}'    // 2024-0001, 2024-0002...
format: '{YY}{MM}-{000}'   // 2403-001, 2403-002...
format: 'ORD-{YYYYMMDD}-{00}'  // ORD-20240315-01...
```

### Mixed Format [#mixed-format]

```plaintext
format: 'PO-{YYYY}-{MM}-{0000}'  // PO-2024-03-0001
format: '{YY}Q{Q}-{000}'         // 24Q1-001, 24Q1-002...
```

## Format Placeholders [#format-placeholders]

* `{0}`, `{00}`, `{000}`, etc. - Sequential number with padding
* `{YYYY}` - Four-digit year (2024)
* `{YY}` - Two-digit year (24)
* `{MM}` - Two-digit month (03)
* `{DD}` - Two-digit day (15)
* `{Q}` - Quarter (1-4)

## Backend Implementation [#backend-implementation]

AutoNumber values are generated on record creation:

```plaintext
const generateAutoNumber = (format: string, sequence: number) => {
  const now = new Date();
  
  return format
    .replace('{YYYY}', now.getFullYear().toString())
    .replace('{YY}', now.getFullYear().toString().slice(-2))
    .replace('{MM}', (now.getMonth() + 1).toString().padStart(2, '0'))
    .replace('{DD}', now.getDate().toString().padStart(2, '0'))
    .replace('{Q}', Math.ceil((now.getMonth() + 1) / 3).toString())
    .replace(/\{0+\}/, (match) => {
      const padding = match.length - 2;
      return sequence.toString().padStart(padding, '0');
    });
};

// Example usage
generateAutoNumber('ORD-{YYYY}-{0000}', 42);
// Returns: "ORD-2024-0042"
```

## Sequence Management [#sequence-management]

The backend maintains sequence counters:

```plaintext
interface SequenceCounter {
  object: string;           // Object name
  field: string;            // Field name
  current_value: number;    // Current sequence number
  prefix?: string;          // Optional prefix for partitioning
}

// Increment sequence atomically
const getNextSequence = async (object: string, field: string) => {
  return await db.transaction(async (tx) => {
    const counter = await tx.findOne('sequences', { object, field });
    const nextValue = (counter?.current_value || 0) + 1;
    await tx.upsert('sequences', { object, field }, { current_value: nextValue });
    return nextValue;
  });
};
```

## Use Cases [#use-cases]

* **Order Management**: Order numbers, PO numbers
* **Invoicing**: Invoice IDs, receipt numbers
* **Ticketing**: Support ticket IDs, case numbers
* **Customer Management**: Customer IDs, account numbers
* **Inventory**: SKU numbers, serial numbers
* **Document Management**: Document IDs, revision numbers

## Best Practices [#best-practices]

1. **Choose appropriate padding**: Use enough digits for expected volume
2. **Include year for long-running systems**: Helps with archival and partitioning
3. **Use meaningful prefixes**: Makes numbers self-documenting
4. **Don't expose internal IDs**: Use auto-numbers for user-facing identifiers
5. **Consider reset policies**: Decide if/when sequences reset (yearly, monthly, etc.)


# Boolean Field





The Boolean Field component provides a switch or checkbox input for collecting true/false boolean values.

## Basic Usage [#basic-usage]

<SchemaExample id="fields-boolean/basic-switch" />

## With Description [#with-description]

<SchemaExample id="fields-boolean/with-description" />

## Default Value [#default-value]

<SchemaExample id="fields-boolean/pre-checked" />

## Field Schema [#field-schema]

```plaintext
interface BooleanFieldSchema {
  type: 'boolean';
  name: string;                  // Field name/ID
  label?: string;                // Field label
  description?: string;          // Helper text
  value?: boolean;               // Default value
  required?: boolean;            // Is field required
  readonly?: boolean;            // Read-only mode
  disabled?: boolean;            // Disabled state
  className?: string;            // Additional CSS classes
}
```

## Use Cases [#use-cases]

* **Feature Toggles**: Enable/disable features
* **Preferences**: User settings and preferences
* **Permissions**: Access control flags
* **Status**: Active/inactive, published/draft states
* **Agreements**: Terms acceptance, consent flags

## Cell Renderer [#cell-renderer]

In tables/grids, boolean values are displayed as badges:

```plaintext
import { BooleanCellRenderer } from '@object-ui/fields';

// Renders:
// ✓ True (green badge)
// ✗ False (gray badge)
```

## Styling [#styling]

The boolean field uses the Switch component from Shadcn UI, providing:

* Smooth animations
* Accessible keyboard navigation
* Focus states
* Disabled states


# Currency Field





The Currency Field component provides a formatted currency input with proper locale formatting and currency symbol display.

## Basic Usage [#basic-usage]

<SchemaExample id="fields-currency/usd-currency" />

## Different Currencies [#different-currencies]

<SchemaExample id="fields-currency/euro-currency" />

## Field Schema [#field-schema]

```plaintext
interface CurrencyFieldSchema {
  type: 'currency';
  name: string;                  // Field name/ID
  label?: string;                // Field label
  placeholder?: string;          // Placeholder text
  value?: number;                // Default value
  currency?: string;             // Currency code (default: 'USD')
  required?: boolean;            // Is field required
  readonly?: boolean;            // Read-only mode
  disabled?: boolean;            // Disabled state
  className?: string;            // Additional CSS classes
  
  // Validation
  min?: number;                  // Minimum value
  max?: number;                  // Maximum value
}
```

## Supported Currencies [#supported-currencies]

* **USD**: US Dollar ($)
* **EUR**: Euro (€)
* **GBP**: British Pound (£)
* **JPY**: Japanese Yen (¥)
* And all other ISO 4217 currency codes

## Cell Renderer [#cell-renderer]

In tables/grids, currency values are formatted with the appropriate symbol:

```plaintext
import { CurrencyCellRenderer } from '@object-ui/fields';

// Renders: $1,234.56 or €1.234,56 based on locale
```

## Use Cases [#use-cases]

* **Pricing**: Product prices, service costs
* **Financial Data**: Revenue, expenses, budgets
* **Transactions**: Payment amounts, invoice totals
* **Salaries**: Compensation amounts


# Date Field





The Date Field component provides a date picker for selecting dates and optionally times.

## Basic Usage [#basic-usage]

<SchemaExample id="fields-date/basic-date-picker" />

## With Default Value [#with-default-value]

<SchemaExample id="fields-date/with-default-date" />

## Field Schema [#field-schema]

```plaintext
interface DateFieldSchema {
  type: 'date' | 'datetime';
  name: string;                  // Field name/ID
  label?: string;                // Field label
  placeholder?: string;          // Placeholder text
  value?: string | Date;         // Default value (ISO string or Date)
  required?: boolean;            // Is field required
  readonly?: boolean;            // Read-only mode
  disabled?: boolean;            // Disabled state
  className?: string;            // Additional CSS classes
  
  // Validation
  min?: string | Date;           // Minimum date
  max?: string | Date;           // Maximum date
  format?: string;               // Display format
}
```

## Date Formats [#date-formats]

The date field supports various display formats:

* **Short**: 12/31/2024
* **Medium**: Dec 31, 2024 (default)
* **Long**: December 31, 2024
* **Full**: Monday, December 31, 2024

## Use Cases [#use-cases]

* **Birthdates**: User birth dates
* **Deadlines**: Task or project deadlines
* **Events**: Event start/end dates
* **Appointments**: Meeting or appointment scheduling
* **Releases**: Product or content release dates

## Cell Renderer [#cell-renderer]

In tables/grids, dates are formatted consistently:

```plaintext
import { DateCellRenderer } from '@object-ui/fields';

// Renders: Dec 31, 2024
// Or: Dec 31, 2024 2:30 PM (for datetime)
```

## DateTime Variant [#datetime-variant]

For collecting both date and time:

```plaintext
{
  type: 'datetime',
  name: 'appointment',
  label: 'Appointment Time'
}
```


# DateTime Field





The DateTime Field component provides a combined date and time input for collecting both date and time information in a single field.

## Basic Usage [#basic-usage]

<SchemaExample id="fields-datetime/basic-datetime-field" />

## With Default Value [#with-default-value]

<SchemaExample id="fields-datetime/with-default-value" />

## Required Field [#required-field]

<SchemaExample id="fields-datetime/required-datetime" />

## Read-Only [#read-only]

<SchemaExample id="fields-datetime/read-only-datetime" />

## Field Schema [#field-schema]

```plaintext
interface DateTimeFieldSchema {
  type: 'datetime';
  name: string;                  // Field name/ID
  label?: string;                // Field label
  placeholder?: string;          // Placeholder text
  value?: string;                // Default value (ISO 8601 format)
  required?: boolean;            // Is field required
  readonly?: boolean;            // Read-only mode
  disabled?: boolean;            // Disabled state
  className?: string;            // Additional CSS classes
  
  // Validation
  format?: string;               // Display format
  min_date?: string | Date;      // Minimum date/time
  max_date?: string | Date;      // Maximum date/time
}
```

## Date Format [#date-format]

The datetime field stores values in ISO 8601 format: `YYYY-MM-DDTHH:mm`

Example: `2024-03-15T14:30` represents March 15, 2024 at 2:30 PM

## Cell Renderer [#cell-renderer]

When used in data tables or grids:

```plaintext
import { DateTimeCellRenderer } from '@object-ui/fields';

// Renders: Mar 15, 2024, 02:30 PM
```

## Use Cases [#use-cases]

* **Event Scheduling**: Meeting times, appointments
* **Timestamps**: Order placed, task deadline
* **Booking Systems**: Reservation date and time
* **Notifications**: Scheduled notification time


# Email Field





The Email Field component provides a text input with built-in email validation and formatting.

## Basic Usage [#basic-usage]

<SchemaExample id="fields-email/basic-email-field" />

## Required Email [#required-email]

<SchemaExample id="fields-email/required-email" />

## Field Schema [#field-schema]

```plaintext
interface EmailFieldSchema {
  type: 'email';
  name: string;                  // Field name/ID
  label?: string;                // Field label
  placeholder?: string;          // Placeholder text
  value?: string;                // Default value
  required?: boolean;            // Is field required
  readonly?: boolean;            // Read-only mode
  disabled?: boolean;            // Disabled state
  className?: string;            // Additional CSS classes
}
```

## Validation [#validation]

The email field automatically validates:

* Proper email format ([user@domain.com](mailto:user@domain.com))
* Presence of @ symbol
* Valid domain structure
* No spaces or invalid characters

## Cell Renderer [#cell-renderer]

In tables/grids, email addresses are clickable links:

```plaintext
import { EmailCellRenderer } from '@object-ui/fields';

// Renders as: <a href="mailto:user@example.com">user@example.com</a>
// Clicking opens default email client
```

## Use Cases [#use-cases]

* **User Registration**: Account email addresses
* **Contact Forms**: Customer contact information
* **Support**: Support ticket emails
* **Notifications**: Email notification addresses
* **Team Members**: Team member email addresses

## Features [#features]

* **Autocomplete**: Browser email autocomplete
* **Validation**: Real-time email format validation
* **Clickable Links**: Email links in read-only mode
* **Accessible**: Proper ARIA labels and keyboard navigation


# File Field





The File Field component provides a file upload interface with support for multiple files, file type filtering, and file metadata display.

## Basic Usage [#basic-usage]

<SchemaExample id="fields-file/basic-file-upload" />

## Multiple Files [#multiple-files]

<SchemaExample id="fields-file/multiple-file-upload" />

## File Type Restrictions [#file-type-restrictions]

<SchemaExample id="fields-file/pdf-files-only" />

## Field Schema [#field-schema]

```plaintext
interface FileFieldSchema {
  type: 'file';
  name: string;                  // Field name/ID
  label?: string;                // Field label
  value?: FileMetadata | FileMetadata[];  // Current file(s)
  required?: boolean;            // Is field required
  readonly?: boolean;            // Read-only mode
  disabled?: boolean;            // Disabled state
  className?: string;            // Additional CSS classes
  
  // File Options
  multiple?: boolean;            // Allow multiple files
  accept?: string[];             // Accepted MIME types
  max_size?: number;             // Max file size in bytes
  max_files?: number;            // Max number of files
}

interface FileMetadata {
  name: string;                  // File name
  original_name?: string;        // Original file name
  size?: number;                 // File size in bytes
  mime_type?: string;            // MIME type
  url?: string;                  // File URL
}
```

## Accepted File Types [#accepted-file-types]

Common MIME type examples:

```plaintext
// Documents
accept: ['application/pdf', 'application/msword']

// Images
accept: ['image/png', 'image/jpeg', 'image/gif']

// Archives
accept: ['application/zip', 'application/x-rar']

// Spreadsheets
accept: ['application/vnd.ms-excel', 'text/csv']

// Wildcards
accept: ['image/*']  // All images
```

## Features [#features]

* **File List Display**: Shows uploaded files with names and sizes
* **Remove Files**: Individual file removal with X button
* **Size Display**: File sizes shown in KB/MB
* **Upload Button**: Clear upload interface
* **Multiple Selection**: Support for batch file uploads

## Cell Renderer [#cell-renderer]

In tables/grids, displays file count:

```plaintext
import { FileCellRenderer } from '@object-ui/fields';

// Renders: "3 files" or "document.pdf"
```

## Integration Notes [#integration-notes]

This component creates object URLs for file preview. Actual file upload requires backend integration:

```plaintext
// Frontend creates preview
const fileData = {
  name: 'document.pdf',
  size: 1024000,
  mime_type: 'application/pdf',
  url: URL.createObjectURL(file)
};

// Backend handles actual upload
const uploadToServer = async (file) => {
  const formData = new FormData();
  formData.append('file', file);
  const response = await fetch('/api/upload', {
    method: 'POST',
    body: formData
  });
  return response.json();
};
```

## Use Cases [#use-cases]

* **Document Management**: PDF uploads, contracts
* **File Attachments**: Email attachments, support tickets
* **Media Libraries**: Asset uploads, resources
* **Data Import**: CSV files, batch uploads


# Formula Field





The Formula Field component displays computed values calculated from other fields. This is a read-only field where the value is automatically calculated by the backend.

## Basic Usage [#basic-usage]

<SchemaExample id="fields-formula/numeric-formula" />

## Text Formula [#text-formula]

<SchemaExample id="fields-formula/text-concatenation" />

## Date Formula [#date-formula]

<SchemaExample id="fields-formula/date-calculation" />

## Field Schema [#field-schema]

```plaintext
interface FormulaFieldSchema {
  type: 'formula';
  name: string;                  // Field name/ID
  label?: string;                // Field label
  value?: any;                   // Computed value (read-only)
  readonly: true;                // Always read-only
  className?: string;            // Additional CSS classes
  
  // Formula Configuration
  formula?: string;              // Formula expression
  return_type?: string;          // Return type (text, number, boolean, date, currency)
}
```

## Return Types [#return-types]

The formula field formats values based on return type:

* **number**: Displays with decimal precision
* **currency**: Displays with currency symbol
* **boolean**: Displays as Yes/No
* **date**: Displays formatted date
* **text**: Displays as string

## Formula Examples [#formula-examples]

Common formula patterns:

```plaintext
// Arithmetic
formula: 'price * quantity'
formula: '(subtotal - discount) * tax_rate'

// Text concatenation
formula: 'first_name + " " + last_name'
formula: 'city + ", " + state + " " + zip'

// Conditional
formula: 'IF(age >= 18, "Adult", "Minor")'
formula: 'IF(status == "closed", completed_at, null)'

// Date calculations
formula: 'created_at + 7 days'
formula: 'end_date - start_date'
```

## Cell Renderer [#cell-renderer]

In tables/grids, displays with monospace font:

```plaintext
import { FormulaCellRenderer } from '@object-ui/fields';

// Renders computed value in monospace font
```

## Backend Implementation [#backend-implementation]

Formula fields are computed on the backend:

```plaintext
// Example backend calculation
const calculateFormula = (formula: string, record: any) => {
  // Parse and evaluate formula
  if (formula === 'quantity * price') {
    return record.quantity * record.price;
  }
  // Use expression parser for complex formulas
  return evaluateExpression(formula, record);
};
```

## Use Cases [#use-cases]

* **Calculations**: Totals, subtotals, tax amounts
* **Aggregations**: Sum of related records
* **Concatenations**: Full names, addresses
* **Derived Values**: Age from birthdate, days until deadline
* **Conditional Logic**: Status based on other fields


# Grid Field





The Grid Field component provides an inline table for managing related records or tabular data within a parent record. It displays data in rows and columns with optional editing capabilities.

## Basic Usage [#basic-usage]

<SchemaExample id="fields-grid/basic-grid" />

## With Data [#with-data]

<SchemaExample id="fields-grid/grid-with-data" />

## Read-Only [#read-only]

<SchemaExample id="fields-grid/read-only-grid" />

## Field Schema [#field-schema]

```plaintext
interface GridFieldSchema {
  type: 'grid';
  name: string;                  // Field name/ID
  label?: string;                // Field label
  value?: any[];                 // Array of row objects
  required?: boolean;            // Is field required
  readonly?: boolean;            // Read-only mode
  disabled?: boolean;            // Disabled state
  className?: string;            // Additional CSS classes
  
  // Grid Options
  columns?: ColumnDefinition[];  // Column definitions
}

interface ColumnDefinition {
  name: string;                  // Column field name
  label: string;                 // Column header label
  type: string;                  // Field type (text, number, etc.)
  width?: string;                // Column width
  editable?: boolean;            // Is column editable
  required?: boolean;            // Is column required
  [key: string]: any;            // Additional field-specific props
}
```

## Column Types [#column-types]

Columns can use any field type:

```plaintext
columns: [
  { name: 'name', label: 'Name', type: 'text', required: true },
  { name: 'quantity', label: 'Qty', type: 'number', min: 1 },
  { name: 'price', label: 'Price', type: 'currency', currency: 'USD' },
  { name: 'date', label: 'Date', type: 'date' },
  { name: 'status', label: 'Status', type: 'select', options: [...] },
  { name: 'active', label: 'Active', type: 'boolean' },
  { name: 'receipt', label: 'Receipt', type: 'file', accept: ['image/*', '.pdf'] }
]
```

### File / image columns [#file--image-columns]

A `file` column renders a real upload control inside the cell — a compact
"Upload" button that opens the native file picker, with uploaded files shown
as removable chips (image files show a thumbnail). This covers the common
"attach a receipt per expense line" pattern without opening the per-row form.

* `accept?: string[]` — restrict the picker (e.g. `['image/*', '.pdf']`).
* `multiple?: boolean` — allow several files per cell.
* Uploads go through the configured `UploadProvider` adapter, exactly like the
  full-size file field.

When grid columns are auto-derived from a child object's schema (master-detail
subforms), `file` / `image` / `avatar` fields map to `file` columns
automatically — image-flavoured fields default to `accept: ['image/*']`.

Because file/image/avatar now render in-grid, a child object with a *single*
such field keeps the inline **grid** form factor by default (the smart
`inlineEdit` heuristic no longer forces a per-row form for one attachment
column). Only a truly form-only field (textarea / rich text / JSON / location)
or **several** rich fields tips the default to the per-row form; an explicit
`inlineEdit: 'grid' | 'form'` always wins.

## Data Format [#data-format]

Grid data is stored as an array of objects:

```plaintext
const gridValue = [
  { product: 'Item 1', quantity: 2, price: 29.99 },
  { product: 'Item 2', quantity: 1, price: 49.99 },
  { product: 'Item 3', quantity: 5, price: 9.99 }
];
```

## Common Patterns [#common-patterns]

### Invoice Line Items [#invoice-line-items]

```plaintext
{
  type: 'grid',
  name: 'line_items',
  label: 'Line Items',
  columns: [
    { name: 'description', label: 'Description', type: 'text', required: true },
    { name: 'quantity', label: 'Quantity', type: 'number', min: 1, required: true },
    { name: 'unit_price', label: 'Unit Price', type: 'currency', required: true },
    { name: 'amount', label: 'Amount', type: 'currency', readonly: true }
  ]
}
```

### Order Details [#order-details]

```plaintext
{
  type: 'grid',
  name: 'order_details',
  label: 'Order Details',
  columns: [
    { name: 'sku', label: 'SKU', type: 'text' },
    { name: 'product', label: 'Product', type: 'lookup', reference_to: 'products' },
    { name: 'quantity', label: 'Qty', type: 'number' },
    { name: 'price', label: 'Price', type: 'currency' },
    { name: 'discount', label: 'Discount', type: 'percent' },
    { name: 'total', label: 'Total', type: 'currency', readonly: true }
  ]
}
```

### Task Checklist [#task-checklist]

```plaintext
{
  type: 'grid',
  name: 'tasks',
  label: 'Tasks',
  columns: [
    { name: 'task', label: 'Task', type: 'text', required: true },
    { name: 'assigned_to', label: 'Assigned To', type: 'user' },
    { name: 'due_date', label: 'Due Date', type: 'date' },
    { name: 'completed', label: 'Done', type: 'boolean' }
  ]
}
```

## Features [#features]

* **Table Display**: Clean tabular layout
* **Pagination Preview**: Shows first 5 rows with "Showing X of Y" indicator
* **Type-Specific Rendering**: Each column renders according to its type
* **Read-Only Mode**: Full table view without editing
* **Responsive**: Scrollable for many columns

## Cell Renderer [#cell-renderer]

In tables/grids, displays row count:

```plaintext
import { GridCellRenderer } from '@object-ui/fields';

// Renders: "5 rows"
```

## Full Grid Functionality [#full-grid-functionality]

For advanced grid features, use the grid plugin (`@object-ui/plugin-grid`):

```plaintext
// Basic inline grid (simple display)
{ type: 'grid', name: 'items', columns: [...] }

// Advanced grid with full features (requires plugin)
{
  type: 'plugin:grid',
  bind: 'items',
  props: {
    columns: [...],
    editable: true,      // Plugin feature: inline editing
    sortable: true,      // Plugin feature: column sorting
    filterable: true,    // Plugin feature: filtering
    pagination: { pageSize: 20 }  // Plugin feature: pagination
  }
}
```

**Note**: Features like `editable`, `sortable`, `filterable`, and advanced `pagination` are provided by the `@object-ui/plugin-grid` package, not the basic grid field.

## Use Cases [#use-cases]

* **Invoice/Order Line Items**: Product lines, services
* **Expense Reports**: Expense entries, receipts
* **Time Tracking**: Time entries, work logs
* **Inventory**: Stock items, materials
* **Checklists**: Task lists, requirements
* **Schedules**: Appointments, bookings
* **Configurations**: Settings lists, parameters

## Backend Storage [#backend-storage]

Grid data is typically stored as JSON:

```plaintext
// Database column type: JSONB (PostgreSQL)
interface OrderRecord {
  id: string;
  customer_id: string;
  line_items: Array<{
    product: string;
    quantity: number;
    price: number;
  }>;
}

// Store in database
const order = {
  customer_id: 'CUST-123',
  line_items: [
    { product: 'Widget A', quantity: 2, price: 29.99 },
    { product: 'Widget B', quantity: 1, price: 49.99 }
  ]
};

await db.insert('orders', order);
```

## Validation [#validation]

Example validation for grid data:

```plaintext
const validateGridData = (data: any[], columns: ColumnDefinition[]) => {
  const errors: string[] = [];
  
  data.forEach((row, index) => {
    columns.forEach(col => {
      // Check required columns
      if (col.required && !row[col.name]) {
        errors.push(`Row ${index + 1}: ${col.label} is required`);
      }
      
      // Validate by type
      if (col.type === 'number' && isNaN(row[col.name])) {
        errors.push(`Row ${index + 1}: ${col.label} must be a number`);
      }
      
      // Check min/max
      if (col.min !== undefined && row[col.name] < col.min) {
        errors.push(`Row ${index + 1}: ${col.label} must be >= ${col.min}`);
      }
    });
  });
  
  return errors;
};
```

## Integration with Advanced Grid [#integration-with-advanced-grid]

For full-featured grids, use the `@object-ui/plugin-grid` package which provides:

* Inline editing
* Add/remove rows
* Sorting and filtering
* Drag-and-drop reordering
* Export functionality
* Formula columns
* Aggregation rows


# Image Field





The Image Field component provides an image upload interface with thumbnail previews, multiple image support, and visual file management.

## Basic Usage [#basic-usage]

<SchemaExample id="fields-image/basic-image-upload" />

## Multiple Images [#multiple-images]

<SchemaExample id="fields-image/multiple-image-upload" />

## Field Schema [#field-schema]

```plaintext
interface ImageFieldSchema {
  type: 'image';
  name: string;                  // Field name/ID
  label?: string;                // Field label
  value?: FileMetadata | FileMetadata[];  // Current image(s)
  required?: boolean;            // Is field required
  readonly?: boolean;            // Read-only mode
  disabled?: boolean;            // Disabled state
  className?: string;            // Additional CSS classes
  
  // Image Options
  multiple?: boolean;            // Allow multiple images
  accept?: string[];             // Accepted image types
  max_size?: number;             // Max file size in bytes
  max_files?: number;            // Max number of images
  max_width?: number;            // Max image width
  max_height?: number;           // Max image height
}
```

## Accepted Image Types [#accepted-image-types]

By default, accepts all common image formats:

```plaintext
// Default: 'image/*'
// Specific formats:
accept: ['image/png', 'image/jpeg', 'image/gif', 'image/webp']
```

## Features [#features]

* **Thumbnail Grid**: Images displayed in 4-column grid
* **Preview**: Visual thumbnails for uploaded images
* **Hover to Remove**: Delete button appears on hover
* **Batch Upload**: Multiple image selection
* **Size Restrictions**: Configurable file size limits

## Cell Renderer [#cell-renderer]

In tables/grids, displays image thumbnails:

```plaintext
import { ImageCellRenderer } from '@object-ui/fields';

// Shows up to 3 thumbnails plus count if more
```

## Image Optimization [#image-optimization]

For best results, consider:

```plaintext
{
  type: 'image',
  name: 'product_images',
  label: 'Product Photos',
  multiple: true,
  max_size: 5242880,        // 5MB
  max_files: 10,
  max_width: 2048,
  max_height: 2048,
  accept: ['image/jpeg', 'image/png', 'image/webp']
}
```

## Integration Notes [#integration-notes]

This component creates object URLs for preview. For production use, implement server-side upload:

```plaintext
const uploadImage = async (file: File) => {
  // Validate dimensions
  const img = new Image();
  img.src = URL.createObjectURL(file);
  await new Promise((resolve) => {
    img.onload = resolve;
  });
  
  if (img.width > maxWidth || img.height > maxHeight) {
    throw new Error('Image dimensions too large');
  }
  
  // Upload to server
  const formData = new FormData();
  formData.append('image', file);
  const response = await fetch('/api/images', {
    method: 'POST',
    body: formData
  });
  
  return response.json();
};
```

## Use Cases [#use-cases]

* **User Profiles**: Avatar/profile pictures
* **Product Catalogs**: Product images, SKU photos
* **Photo Galleries**: Image collections, portfolios
* **Content Management**: Blog post images, media assets
* **Real Estate**: Property photos, listings


# Location Field





The Location Field component provides an input for geographic coordinates, storing latitude and longitude as a structured object.

## Basic Usage [#basic-usage]

<SchemaExample id="fields-location/basic-location-field" />

## With Default Value [#with-default-value]

<SchemaExample id="fields-location/san-francisco-coordinates" />

## Read-Only [#read-only]

<SchemaExample id="fields-location/read-only-location" />

## Field Schema [#field-schema]

```plaintext
interface LocationFieldSchema {
  type: 'location';
  name: string;                  // Field name/ID
  label?: string;                // Field label
  placeholder?: string;          // Placeholder text
  value?: LocationValue;         // Default coordinates
  required?: boolean;            // Is field required
  readonly?: boolean;            // Read-only mode
  disabled?: boolean;            // Disabled state
  className?: string;            // Additional CSS classes
  
  // Map Options
  default_zoom?: number;         // Default map zoom level
}

interface LocationValue {
  latitude: number;              // -90 to 90
  longitude: number;             // -180 to 180
}
```

## Data Format [#data-format]

The location field stores coordinates as an object:

```plaintext
{
  latitude: 37.7749,
  longitude: -122.4194
}
```

Input format: `latitude, longitude`

* Example: `37.7749, -122.4194`

## Coordinate Ranges [#coordinate-ranges]

* **Latitude**: -90 to 90 (negative = South, positive = North)
* **Longitude**: -180 to 180 (negative = West, positive = East)

Examples:

* New York: `40.7128, -74.0060`
* Tokyo: `35.6762, 139.6503`
* Sydney: `-33.8688, 151.2093`
* London: `51.5074, -0.1278`

## Use Cases [#use-cases]

* **Store Locator**: Retail locations, branch offices
* **Delivery Zones**: Service areas, delivery points
* **Event Venues**: Conference locations, meeting points
* **Asset Tracking**: Equipment locations, vehicle tracking
* **Real Estate**: Property coordinates, land parcels

## Integration with Maps [#integration-with-maps]

For full map functionality, consider integrating with map services:

```plaintext
import { LocationField } from '@object-ui/fields';

// Basic coordinates input
<LocationField {...props} />

// With map visualization (using map plugin)
{
  type: 'plugin:map',
  bind: 'location',
  props: {
    center: location,
    zoom: 12,
    markers: [location]
  }
}
```

## Validation [#validation]

The field validates coordinate ranges:

```plaintext
// Valid coordinates
{ latitude: 37.7749, longitude: -122.4194 } ✓

// Invalid - latitude out of range
{ latitude: 95, longitude: -122.4194 } ✗

// Invalid - longitude out of range
{ latitude: 37.7749, longitude: 200 } ✗
```


# Lookup Field





The Lookup Field component provides a reference field for creating relationships between objects and records. It supports dynamic data loading from a DataSource with debounced search, loading/error/empty states, keyboard navigation, and optional quick-create entry.

## Basic Usage [#basic-usage]

<SchemaExample id="fields-lookup/basic-lookup" />

## Multiple References [#multiple-references]

<SchemaExample id="fields-lookup/multi-select-lookup" />

## Field Schema [#field-schema]

```plaintext
interface LookupFieldSchema {
  type: 'lookup' | 'master_detail';
  name: string;                  // Field name/ID
  label?: string;                // Field label
  placeholder?: string;          // Placeholder text
  value?: string | string[];     // Default value(s)
  multiple?: boolean;            // Allow multiple selections
  required?: boolean;            // Is field required
  readonly?: boolean;            // Read-only mode
  disabled?: boolean;            // Disabled state
  className?: string;            // Additional CSS classes
  
  // Reference Configuration
  reference_to: string;          // Referenced object/table name
  reference_field?: string;      // Field to display (default: 'name')
  description_field?: string;    // Secondary field shown below label
  id_field?: string;             // ID field on records (default: '_id')
  options?: LookupOption[];      // Available options (if static)
  
  // Data Source (automatic via SchemaRendererContext, or explicit)
  // When a DataSource is available, the popup dynamically loads
  // records from the referenced object on open, with debounced search.
  dataSource?: DataSource;

  // Quick-create callback (shown when no results found)
  onCreateNew?: (searchQuery: string) => void;

  // === Record Picker Configuration (Enterprise) ===
  
  // Columns to show in the Record Picker dialog table.
  // Accepts field names or { field, label, width } objects.
  // When omitted, auto-infers from reference_field.
  lookup_columns?: Array<string | { field: string; label?: string; width?: string }>;

  // Custom page size for the Record Picker dialog (default: 10)
  lookup_page_size?: number;
}

interface LookupOption {
  label: string;                 // Display label
  value: string;                 // Record ID
  description?: string;          // Secondary text below label
  _id?: string;                  // Alternative ID field
  name?: string;                 // Alternative label field
}
```

## Dynamic Data Source [#dynamic-data-source]

When a `DataSource` is available (via `SchemaRendererContext`, explicit prop, or field config), the Lookup popup **automatically** fetches records from the referenced object:

```plaintext
// Automatic — DataSource from SchemaRendererContext
// (works out-of-the-box in ObjectForm, DrawerForm, etc.)
{
  type: 'lookup',
  name: 'customer',
  label: 'Customer',
  reference_to: 'customers',
  reference_field: 'name',        // Display field (default: 'name')
  description_field: 'industry',  // Optional secondary field
}
```

The popup will:

1. Fetch records via `dataSource.find(reference_to, { $top: 50 })` on open
2. Send `$search` queries with 300ms debounce as the user types
3. Show loading spinner, error state with retry, and empty state
4. Display "Showing X of Y" when more records exist than the page size
5. Show a &#x2A;*"Show All Results"** button (inside the popover) to open the full Record Picker dialog when total exceeds page size

## Browse All Button [#browse-all-button]

Every Lookup field with a `dataSource&#x60; always renders a &#x2A;*"Browse All"** button (table icon) next to the quick-select trigger. This button opens the full **RecordPickerDialog** directly, regardless of dataset size — ensuring enterprise features like multi-column tables, sort/filter bar, and cell renderers are always discoverable.

* Always visible when `dataSource` is configured
* Opens the Record Picker dialog without needing to open the popover first
* Keyboard accessible and screen-reader friendly (`aria-label="Browse all records"`)

## Record Picker Dialog (Enterprise) [#record-picker-dialog-enterprise]

The full **RecordPickerDialog** can be opened in two ways:

1. **"Browse All" button** (table icon) — always visible next to the quick-select trigger
2. **"Show All Results"** link inside the popover — shown when total records exceed the page size

```plaintext
// Configure the Record Picker with lookup_columns
{
  type: 'lookup',
  name: 'order',
  label: 'Order',
  reference_to: 'orders',
  reference_field: 'order_number',
  description_field: 'customer_name',
  lookup_columns: [
    { field: 'order_number', label: 'Order #' },
    { field: 'customer_name', label: 'Customer' },
    { field: 'total_amount', label: 'Amount' },
    { field: 'status', label: 'Status' },
  ],
  lookup_page_size: 15,
}
```

The Record Picker dialog provides:

* **Multi-column table** with configurable columns via `lookup_columns`
* **Search** with debounced server-side querying
* **Column sorting** via clickable headers (sends `$orderby` to DataSource)
* **Pagination** with page-by-page navigation
* **Keyboard navigation** — Arrow keys to move between rows, Enter/Space to select
* **Single/Multi-select** with visual check indicators and confirmation flow
* **Responsive layout** — Mobile-friendly width (95vw on small screens)
* **Loading, error, and empty states**
* Auto-inferred columns from `reference_field` when `lookup_columns` is not set

## Lookup vs Master-Detail [#lookup-vs-master-detail]

* **Lookup**: Standard reference field, can be deleted independently
* **Master-Detail**: Parent-child relationship, deleting parent deletes children

## Cell Renderer [#cell-renderer]

In tables/grids, lookup values display the referenced record name:

```plaintext
import { LookupCellRenderer } from '@object-ui/fields';

// Single value: Display name/label
// Multiple values: Multiple chips/badges
```

## Use Cases [#use-cases]

* **Assignments**: Assign tasks to users
* **Relationships**: Link related records
* **Categories**: Reference to category objects
* **Parent Records**: Master-detail relationships
* **Team Members**: Multi-user references

## Features [#features]

* **Two-Level Interaction**: Popover typeahead (Level 1) + full Record Picker dialog (Level 2)
* **Record Picker Dialog**: Enterprise-grade table with multi-column, pagination, search, sorting
* **Inline Popover**: Level 1 opens as anchored dropdown (non-modal) for fast typeahead
* **Column Sorting**: Clickable column headers with `$orderby` server-side sort
* **Dynamic DataSource Loading**: Automatically fetches records from referenced objects
* **Search**: Debounced type-ahead search with `$search` parameter
* **Multi-Select**: Support for multiple references with confirmation flow
* **Keyboard Navigation**: Arrow keys to navigate rows, Enter to select in both levels
* **Responsive**: Mobile-friendly width, adapts to screen size
* **Loading/Error/Empty States**: Friendly feedback for all states
* **Secondary Field Display**: Show description/subtitle per option
* **Quick-Create Entry**: Optional "Create new" button when no results
* **Configurable Columns**: `lookup_columns` for multi-column picker display
* **Base Filters**: `lookup_filters` to restrict selectable records
* **Pagination**: Page-by-page navigation in Record Picker dialog
* **Backward Compatible**: Falls back to static options when no DataSource


# Number Field





The Number Field component provides a numeric input for collecting integer or decimal numbers with optional precision control.

## Basic Usage [#basic-usage]

<SchemaExample id="fields-number/basic-number-field" />

## With Precision [#with-precision]

<SchemaExample id="fields-number/decimal-numbers" />

## With Min/Max [#with-minmax]

<SchemaExample id="fields-number/range-validation" />

## Field Schema [#field-schema]

```plaintext
interface NumberFieldSchema {
  type: 'number';
  name: string;                  // Field name/ID
  label?: string;                // Field label
  placeholder?: string;          // Placeholder text
  value?: number;                // Default value
  required?: boolean;            // Is field required
  readonly?: boolean;            // Read-only mode
  disabled?: boolean;            // Disabled state
  className?: string;            // Additional CSS classes
  
  // Validation
  min?: number;                  // Minimum value
  max?: number;                  // Maximum value
  precision?: number;            // Decimal places (default: 0)
  step?: number;                 // Increment/decrement step
}
```

## Use Cases [#use-cases]

* **Quantities**: Order quantities, stock levels
* **Measurements**: Dimensions, weights, distances
* **Ratings**: Numeric ratings or scores
* **Ages**: User age or duration values

## Cell Renderer [#cell-renderer]

In tables/grids, numbers are displayed with tabular formatting:

```plaintext
import { NumberCellRenderer } from '@object-ui/fields';

// Renders with precision and tabular-nums font
// Example: 1,234.56
```


# Object Field





The Object Field component provides a JSON editor for storing and editing structured data objects. It validates JSON syntax and provides a textarea interface for complex data.

## Basic Usage [#basic-usage]

<SchemaExample id="fields-object/basic-object-editor" />

## With Schema [#with-schema]

<SchemaExample id="fields-object/structured-configuration" />

## Nested Data [#nested-data]

<SchemaExample id="fields-object/nested-object-data" />

## Read-Only [#read-only]

<SchemaExample id="fields-object/read-only-json-display" />

## Field Schema [#field-schema]

```plaintext
interface ObjectFieldSchema {
  type: 'object';
  name: string;                  // Field name/ID
  label?: string;                // Field label
  placeholder?: string;          // Placeholder text
  value?: Record<string, any>;   // JSON object value
  required?: boolean;            // Is field required
  readonly?: boolean;            // Read-only mode
  disabled?: boolean;            // Disabled state
  className?: string;            // Additional CSS classes
  
  // Object Options
  schema?: Record<string, any>;  // Optional schema definition
}
```

## JSON Validation [#json-validation]

The field validates JSON syntax in real-time:

* **Valid JSON**: Updates the value immediately
* **Invalid JSON**: Maintains current valid value, doesn't update
* **Empty Input**: Sets value to `null`

## Data Format [#data-format]

The object field stores data as parsed JSON:

```plaintext
// Input (string)
'{"name": "John", "age": 30}'

// Stored (object)
{ name: "John", age: 30 }

// Display (formatted)
{
  "name": "John",
  "age": 30
}
```

## Common Patterns [#common-patterns]

### Configuration Objects [#configuration-objects]

```plaintext
{
  type: 'object',
  name: 'api_config',
  label: 'API Configuration',
  value: {
    endpoint: 'https://api.example.com',
    timeout: 5000,
    retries: 3,
    headers: {
      'Content-Type': 'application/json'
    }
  }
}
```

### Metadata [#metadata]

```plaintext
{
  type: 'object',
  name: 'custom_metadata',
  label: 'Custom Metadata',
  value: {
    tags: ['important', 'urgent'],
    priority: 'high',
    department: 'engineering'
  }
}
```

### Preferences [#preferences]

```plaintext
{
  type: 'object',
  name: 'user_preferences',
  label: 'Preferences',
  value: {
    theme: 'dark',
    language: 'en',
    notifications: {
      email: true,
      push: false,
      sms: false
    }
  }
}
```

## Cell Renderer [#cell-renderer]

In tables/grids, displays formatted JSON preview:

```plaintext
import { ObjectCellRenderer } from '@object-ui/fields';

// Shows: [Object] or truncated JSON in read-only mode
```

## Schema Validation [#schema-validation]

For typed object fields, you can define a schema in two formats:

**Simplified Format** (for documentation):

```plaintext
{
  type: 'object',
  name: 'product_specs',
  label: 'Product Specifications',
  schema: {
    weight: 'number',
    dimensions: {
      width: 'number',
      height: 'number',
      depth: 'number'
    },
    materials: 'array'
  }
}
```

**JSON Schema Format** (for validation):

```plaintext
{
  type: 'object',
  name: 'product_specs',
  label: 'Product Specifications',
  schema: {
    type: 'object',
    properties: {
      weight: { type: 'number' },
      dimensions: {
        type: 'object',
        properties: {
          width: { type: 'number' },
          height: { type: 'number' },
          depth: { type: 'number' }
        }
      },
      materials: { type: 'array' }
    }
  }
}
```

## Use Cases [#use-cases]

* **Configuration**: Application settings, API configurations
* **Metadata**: Custom properties, tags, attributes
* **API Responses**: Storing API response data
* **Preferences**: User preferences, feature flags
* **Structured Data**: Any complex structured information
* **JSON Storage**: Raw JSON data storage

## Best Practices [#best-practices]

1. **Use for Flexible Data**: When schema changes frequently
2. **Validate on Backend**: Always validate structure server-side
3. **Consider Alternatives**: Use typed fields when structure is fixed
4. **Document Schema**: Provide clear documentation for expected structure
5. **Size Limits**: Set reasonable size limits for JSON data

## Backend Validation [#backend-validation]

Example backend validation:

```plaintext
import Ajv from 'ajv';

const ajv = new Ajv();

const validateObjectField = (value: any, schema: any) => {
  if (!schema) return { valid: true };
  
  const validate = ajv.compile(schema);
  const valid = validate(value);
  
  return {
    valid,
    errors: validate.errors
  };
};

// Example schema
const configSchema = {
  type: 'object',
  properties: {
    api_key: { type: 'string', minLength: 1 },
    timeout: { type: 'number', minimum: 0 },
    enabled: { type: 'boolean' }
  },
  required: ['api_key']
};
```


# Password Field





The Password Field component provides a secure text input for passwords with a toggle button to show/hide the password text.

## Basic Usage [#basic-usage]

<SchemaExample id="fields-password/basic-password-field" />

## With Validation [#with-validation]

<SchemaExample id="fields-password/with-minimum-length" />

## Confirm Password [#confirm-password]

<SchemaExample id="fields-password/password-confirmation" />

## Field Schema [#field-schema]

```plaintext
interface PasswordFieldSchema {
  type: 'password';
  name: string;                  // Field name/ID
  label?: string;                // Field label
  placeholder?: string;          // Placeholder text
  value?: string;                // Default value
  required?: boolean;            // Is field required
  readonly?: boolean;            // Read-only mode (shows ••••••)
  disabled?: boolean;            // Disabled state
  className?: string;            // Additional CSS classes
  
  // Validation
  min_length?: number;           // Minimum character length
  max_length?: number;           // Maximum character length
}
```

## Features [#features]

* **Masked Input**: Password is hidden by default with bullet points (•)
* **Toggle Visibility**: Eye icon button to show/hide password
* **Secure Display**: Read-only mode always shows ••••••••
* **Validation**: Built-in support for length requirements

## Security Best Practices [#security-best-practices]

When using password fields:

1. **Never log passwords**: Don't log form values containing passwords
2. **Use HTTPS**: Always transmit over secure connections
3. **Validation**: Enforce minimum length and complexity requirements
4. **Storage**: Never store passwords in plain text on the backend
5. **Auto-complete**: Consider disabling auto-complete for sensitive passwords

## Use Cases [#use-cases]

* **User Registration**: New account password
* **Login Forms**: User authentication
* **Password Change**: Updating existing passwords
* **Security Settings**: API keys, tokens (when masked input is appropriate)


# Percent Field





The Percent Field component provides a percentage input that automatically converts between stored decimal values (0-1) and displayed percentage values (0-100).

## Basic Usage [#basic-usage]

<SchemaExample id="fields-percent/basic-percent-field" />

## With Precision [#with-precision]

<SchemaExample id="fields-percent/with-decimal-precision" />

## Required Field [#required-field]

<SchemaExample id="fields-percent/required-percent" />

## Read-Only [#read-only]

<SchemaExample id="fields-percent/read-only-percent" />

## Field Schema [#field-schema]

```plaintext
interface PercentFieldSchema {
  type: 'percent';
  name: string;                  // Field name/ID
  label?: string;                // Field label
  placeholder?: string;          // Placeholder text
  value?: number;                // Default value (0-1 decimal)
  required?: boolean;            // Is field required
  readonly?: boolean;            // Read-only mode
  disabled?: boolean;            // Disabled state
  className?: string;            // Additional CSS classes
  
  // Validation
  precision?: number;            // Decimal places (default: 2)
  min?: number;                  // Minimum value (0-1)
  max?: number;                  // Maximum value (0-1)
}
```

## Value Conversion [#value-conversion]

The percent field handles automatic conversion:

* **Stored Value**: Decimal between 0 and 1 (e.g., `0.75`)
* **Display Value**: Percentage between 0 and 100 (e.g., `75%`)

Example:

```plaintext
// Stored in database: 0.85
// Displayed to user: 85%
// User enters: 90
// Stored as: 0.90
```

## Cell Renderer [#cell-renderer]

In tables/grids, values are formatted with percentage symbol:

```plaintext
import { PercentCellRenderer } from '@object-ui/fields';

// Renders: 85.50%
```

## Use Cases [#use-cases]

* **Progress Tracking**: Task completion, project progress
* **Analytics**: Conversion rates, success metrics
* **Financial Data**: Interest rates, discount percentages
* **Statistics**: Performance scores, efficiency ratings


# Phone Field





The Phone Field component provides a text input optimized for phone number entry with proper formatting.

## Basic Usage [#basic-usage]

<SchemaExample id="fields-phone/basic-phone-field" />

## Required Phone [#required-phone]

<SchemaExample id="fields-phone/required-phone" />

## Field Schema [#field-schema]

```plaintext
interface PhoneFieldSchema {
  type: 'phone';
  name: string;                  // Field name/ID
  label?: string;                // Field label
  placeholder?: string;          // Placeholder text
  value?: string;                // Default value
  required?: boolean;            // Is field required
  readonly?: boolean;            // Read-only mode
  disabled?: boolean;            // Disabled state
  className?: string;            // Additional CSS classes
}
```

## Cell Renderer [#cell-renderer]

In tables/grids, phone numbers are clickable tel: links:

```plaintext
import { PhoneCellRenderer } from '@object-ui/fields';

// Renders as: <a href="tel:+15551234567">+1 (555) 123-4567</a>
// Clicking initiates a phone call on mobile devices
```

## Use Cases [#use-cases]

* **Contact Information**: Customer phone numbers
* **Support**: Support line numbers
* **Emergency Contacts**: Emergency contact numbers
* **Delivery**: Delivery contact numbers
* **Appointments**: Callback numbers

## Features [#features]

* **Mobile Optimized**: Opens phone dialer on mobile
* **Clickable Links**: tel: links in read-only mode
* **International Support**: Supports international formats
* **Accessible**: Proper input type for mobile keyboards


# Rich Text Field





The Rich Text Field component provides a WYSIWYG editor for creating formatted text content with markdown or HTML support.

## Basic Usage [#basic-usage]

<SchemaExample id="fields-rich-text/markdown-editor" />

## HTML Editor [#html-editor]

<SchemaExample id="fields-rich-text/html-editor" />

## Field Schema [#field-schema]

```plaintext
interface RichTextFieldSchema {
  type: 'markdown' | 'html';
  name: string;                  // Field name/ID
  label?: string;                // Field label
  placeholder?: string;          // Placeholder text
  value?: string;                // Default value
  rows?: number;                 // Editor height in rows
  required?: boolean;            // Is field required
  readonly?: boolean;            // Read-only mode
  disabled?: boolean;            // Disabled state
  className?: string;            // Additional CSS classes
  
  // Editor Configuration
  toolbar?: boolean;             // Show formatting toolbar
  preview?: boolean;             // Show preview panel
  minHeight?: number;            // Minimum height in pixels
  maxHeight?: number;            // Maximum height in pixels
}
```

## Supported Formats [#supported-formats]

### Markdown [#markdown]

* **Headings**: `# H1`, `## H2`, `### H3`
* **Bold/Italic**: `**bold**`, `*italic*`
* **Lists**: Ordered and unordered
* **Links**: `[text](url)`
* **Images**: `![alt](url)`
* **Code**: Inline and blocks
* **Tables**: Markdown tables

### HTML [#html]

* Full HTML editing support
* Sanitization for security
* Style preservation
* Embedded media support

## Cell Renderer [#cell-renderer]

In tables/grids, rich text is shown as plain text:

```plaintext
import { TextCellRenderer } from '@object-ui/fields';

// Strips formatting, shows plain text only
// Long content is truncated
```

## Use Cases [#use-cases]

* **Blog Posts**: Article content, blog posts
* **Documentation**: Technical documentation
* **Descriptions**: Product or feature descriptions
* **Comments**: Rich formatted comments
* **Emails**: Email templates, rich email content
* **Pages**: CMS page content

## Features [#features]

* **WYSIWYG**: What you see is what you get editing
* **Markdown Support**: For lightweight formatting
* **HTML Support**: For advanced formatting
* **Preview Mode**: See formatted output
* **Syntax Highlighting**: For code blocks
* **Image Upload**: Embed images (when configured)
* **Auto-save**: Prevent data loss

## Editor Modes [#editor-modes]

The rich text field can operate in different modes:

1. **Markdown Mode** (`type: 'markdown'`)
   * Lightweight markup
   * Easy to write and read
   * Great for documentation

2. **HTML Mode** (`type: 'html'`)
   * Full HTML editing
   * Advanced formatting
   * Embedded content support


# Select Field





The Select Field component provides a dropdown for selecting one or more options from a predefined list.

## Basic Usage [#basic-usage]

<SchemaExample id="fields-select/basic-select" />

## With Colors [#with-colors]

<SchemaExample id="fields-select/colored-options" />

## Multiple Selection [#multiple-selection]

<SchemaExample id="fields-select/multi-select" />

## Cascading & Role-Gated Options [#cascading--role-gated-options]

An option can carry a `visibleWhen` CEL predicate — it is offered only when the
predicate is TRUE. The predicate is evaluated against the **live record*&#x2A; plus
&#x2A;*`current_user`**, the same engine and binding environment as a field-level
`visibleWhen`. This single mechanism covers two needs:

* **Cascading / dependent options** — narrow a child list by a parent field
  (country → province → city).
* **Role / context gating** — offer an option only to certain users.

Declare the sibling field(s) a select reacts to with `dependsOn`. While any is
empty the control is **gated** (a "Select country first" hint) instead of
showing an unfiltered list; once the parent changes, the list re-evaluates and
any now-invalid selection is **cleared automatically** (no stale "China +
California" pair).

### Cascading (country → province) [#cascading-country--province]

<SchemaExample id="fields-select/cascading-options" />

```json
{
  "type": "form",
  "fields": [
    { "name": "country", "label": "Country", "type": "select", "options": [
      { "label": "China", "value": "cn" },
      { "label": "United States", "value": "us" }
    ]},
    { "name": "province", "label": "Province", "type": "select", "dependsOn": "country", "options": [
      { "label": "Zhejiang",   "value": "zj", "visibleWhen": "record.country == 'cn'" },
      { "label": "Guangdong",  "value": "gd", "visibleWhen": "record.country == 'cn'" },
      { "label": "California",  "value": "ca", "visibleWhen": "record.country == 'us'" },
      { "label": "Texas",       "value": "tx", "visibleWhen": "record.country == 'us'" }
    ]}
  ]
}
```

Chain a third level (`city`, `dependsOn: "province"`) the same way — the gate and
cascade-clear propagate down the chain.

### Role-gated option [#role-gated-option]

<SchemaExample id="fields-select/role-gated-options" />

```json
{ "name": "visibility", "type": "select", "options": [
  { "label": "Private (only me)", "value": "private" },
  { "label": "My team", "value": "team" },
  { "label": "Whole organization", "value": "org" },
  { "label": "Public — external", "value": "public", "visibleWhen": "'admin' in current_user.positions" }
]}
```

> **Security — hiding is UX, not authorization.** A `visibleWhen` on an option
> only removes it from the dropdown on the client; a determined caller can still
> submit the value. When an option is gated for **access-control** reasons the
> **server must also reject** writes of that value (the rule-validator evaluates
> the picked value's `visibleWhen`). Use option `visibleWhen` for convenience and
> cascades freely; for real authorization, pair it with server-side enforcement.

### When to use options vs. a lookup [#when-to-use-options-vs-a-lookup]

`visibleWhen` options are for **small, static dictionaries*&#x2A; (category →
subcategory, a handful of provinces). When the data is large, changes over time,
or is shared across forms (real country/province/city tables, org units, product
catalogs), model each level as a &#x2A;*`lookup`** with `depends_on` instead — the
candidate query is filtered server-side and paginated. See
[Lookup Field](/docs/fields/lookup).

## Field Schema [#field-schema]

```plaintext
interface SelectFieldSchema {
  type: 'select';
  name: string;                  // Field name/ID
  label?: string;                // Field label
  placeholder?: string;          // Placeholder text
  value?: string | string[];     // Default value(s)
  multiple?: boolean;            // Allow multiple selections
  required?: boolean;            // Is field required
  readonly?: boolean;            // Read-only mode
  disabled?: boolean;            // Disabled state
  className?: string;            // Additional CSS classes

  // Options
  options: SelectOption[];       // Available options

  // Cascading: sibling field(s) whose value drives this option list. While any
  // is empty the field is gated ("Select <parent> first"); it re-evaluates as
  // they change. Same knob dependent lookups use.
  dependsOn?: string | string[];
}

interface SelectOption {
  label: string;                 // Display label
  value: string;                 // Option value
  color?: string;                // Badge color (gray, red, blue, etc.)
  disabled?: boolean;            // Disable specific option

  // Per-option visibility predicate (CEL). The option is offered only when TRUE,
  // evaluated against the live record + current_user (same engine/env as a
  // field-level visibleWhen). Omit = always available.
  visibleWhen?: string;
}
```

## Available Colors [#available-colors]

* `gray` - Default neutral color
* `red` - For errors, urgent items
* `orange` - For warnings, high priority
* `yellow` - For pending, attention needed
* `green` - For success, completed
* `blue` - For info, in progress
* `indigo` - For special items
* `purple` - For creative, design
* `pink` - For featured items

## Cell Renderer [#cell-renderer]

In tables/grids, select values are displayed as colored badges:

```plaintext
import { SelectCellRenderer } from '@object-ui/fields';

// Single value: Colored badge
// Multiple values: Multiple badges in a row
```

## Use Cases [#use-cases]

* **Status Fields**: Order status, task status
* **Categories**: Product categories, content types
* **Tags**: Multi-tag selection
* **Priorities**: Task or ticket priorities
* **Roles**: User roles or permissions


# Summary Field





The Summary Field component displays aggregated values from related records. This is a read-only field where the value is automatically calculated by the backend through rollup aggregations.

## Count Summary [#count-summary]

<SchemaExample id="fields-summary/count-of-related-records" />

## Sum Summary [#sum-summary]

<SchemaExample id="fields-summary/sum-of-field-values" />

## Average Summary [#average-summary]

<SchemaExample id="fields-summary/average-of-field-values" />

## Field Schema [#field-schema]

```plaintext
interface SummaryFieldSchema {
  type: 'summary';
  name: string;                  // Field name/ID
  label?: string;                // Field label
  value?: number;                // Computed value (read-only)
  readonly: true;                // Always read-only
  className?: string;            // Additional CSS classes
  
  // Summary Configuration
  summary_object?: string;       // Related object name
  summary_field?: string;        // Field to aggregate
  summary_type?: 'count' | 'sum' | 'avg' | 'min' | 'max';
}
```

## Summary Types [#summary-types]

* **count**: Count of related records
* **sum**: Sum of numeric field values
* **avg**: Average of numeric field values
* **min**: Minimum value in the field
* **max**: Maximum value in the field

## Examples [#examples]

### Count Related Records [#count-related-records]

```plaintext
{
  type: 'summary',
  name: 'task_count',
  label: 'Open Tasks',
  summary_object: 'tasks',
  summary_field: 'id',
  summary_type: 'count'
}
```

### Sum Amounts [#sum-amounts]

```plaintext
{
  type: 'summary',
  name: 'total_sales',
  label: 'Total Sales',
  summary_object: 'invoices',
  summary_field: 'amount',
  summary_type: 'sum'
}
```

### Average Value [#average-value]

```plaintext
{
  type: 'summary',
  name: 'avg_response_time',
  label: 'Avg Response Time',
  summary_object: 'support_tickets',
  summary_field: 'response_time_hours',
  summary_type: 'avg'
}
```

### Min/Max Values [#minmax-values]

```plaintext
{
  type: 'summary',
  name: 'highest_bid',
  label: 'Highest Bid',
  summary_object: 'bids',
  summary_field: 'amount',
  summary_type: 'max'
}
```

## Cell Renderer [#cell-renderer]

In tables/grids, displays with tabular numbers:

```plaintext
import { SummaryCellRenderer } from '@object-ui/fields';

// Renders: 15,750.50 (formatted with proper precision)
```

## Backend Implementation [#backend-implementation]

Summary fields are calculated through database aggregations:

```plaintext
// Example backend aggregation
const calculateSummary = async (config: SummaryConfig, parentId: string) => {
  const { summary_object, summary_field, summary_type } = config;
  
  switch (summary_type) {
    case 'count':
      return db.count(summary_object, { parent_id: parentId });
    
    case 'sum':
      return db.sum(summary_object, summary_field, { parent_id: parentId });
    
    case 'avg':
      return db.avg(summary_object, summary_field, { parent_id: parentId });
    
    case 'min':
      return db.min(summary_object, summary_field, { parent_id: parentId });
    
    case 'max':
      return db.max(summary_object, summary_field, { parent_id: parentId });
  }
};
```

## Use Cases [#use-cases]

* **Order Management**: Total order value, order count
* **CRM**: Number of contacts, total deal value
* **Project Management**: Task count, total hours
* **Analytics**: Average ratings, min/max values
* **Financial**: Sum of expenses, average transaction size


# Text Field





The Text Field component provides a single-line text input for collecting basic text data from users. It's the most commonly used field type for names, titles, and short text entries.

## Basic Usage [#basic-usage]

<SchemaExample id="fields-text/basic-text-field" />

## With Placeholder [#with-placeholder]

<SchemaExample id="fields-text/with-placeholder" />

## Required Field [#required-field]

<SchemaExample id="fields-text/required-field" />

## Read-Only [#read-only]

<SchemaExample id="fields-text/read-only-field" />

## Field Schema [#field-schema]

```plaintext
interface TextFieldSchema {
  type: 'text';
  name: string;                  // Field name/ID
  label?: string;                // Field label
  placeholder?: string;          // Placeholder text
  value?: string;                // Default value
  required?: boolean;            // Is field required
  readonly?: boolean;            // Read-only mode
  disabled?: boolean;            // Disabled state
  className?: string;            // Additional CSS classes
  
  // Validation
  min_length?: number;           // Minimum character length
  max_length?: number;           // Maximum character length
  pattern?: string | RegExp;     // Validation pattern
}
```

## Use Cases [#use-cases]

* **User Names**: Collecting first names, last names, or usernames
* **Titles**: Post titles, document names, or product names
* **Short Text**: Any short text input that doesn't require multiple lines
* **IDs**: Custom identifiers or reference numbers

## Cell Renderer [#cell-renderer]

When used in data tables or grids, the text field is rendered as simple truncated text:

```plaintext
import { TextCellRenderer } from '@object-ui/fields';

// Automatically used for type: 'text' in grids/tables
// Displays value or '-' if empty
```


# TextArea Field





The TextArea Field component provides a multi-line text input for collecting longer text content from users, such as descriptions, comments, or notes.

## Basic Usage [#basic-usage]

<SchemaExample id="fields-textarea/basic-textarea" />

## Custom Rows [#custom-rows]

<SchemaExample id="fields-textarea/larger-textarea" />

## Required Field [#required-field]

<SchemaExample id="fields-textarea/required-textarea" />

## Field Schema [#field-schema]

```plaintext
interface TextAreaFieldSchema {
  type: 'textarea';
  name: string;                  // Field name/ID
  label?: string;                // Field label
  placeholder?: string;          // Placeholder text
  rows?: number;                 // Number of visible rows (default: 3)
  value?: string;                // Default value
  required?: boolean;            // Is field required
  readonly?: boolean;            // Read-only mode
  disabled?: boolean;            // Disabled state
  className?: string;            // Additional CSS classes
  
  // Validation
  min_length?: number;           // Minimum character length
  max_length?: number;           // Maximum character length
}
```

## Use Cases [#use-cases]

* **Descriptions**: Product descriptions, bio information
* **Comments**: User feedback, review comments
* **Notes**: Meeting notes, task descriptions
* **Messages**: Contact form messages, support tickets

## Cell Renderer [#cell-renderer]

When displayed in tables or grids, long text is truncated:

```plaintext
import { TextCellRenderer } from '@object-ui/fields';

// Same renderer as text field - truncates long content
```


# Time Field





The Time Field component provides a time-only input for collecting hour and minute information without a date component.

## Basic Usage [#basic-usage]

<SchemaExample id="fields-time/basic-time-field" />

## With Default Value [#with-default-value]

<SchemaExample id="fields-time/with-default-value" />

## Required Field [#required-field]

<SchemaExample id="fields-time/required-time" />

## Read-Only [#read-only]

<SchemaExample id="fields-time/read-only-time" />

## Field Schema [#field-schema]

```plaintext
interface TimeFieldSchema {
  type: 'time';
  name: string;                  // Field name/ID
  label?: string;                // Field label
  placeholder?: string;          // Placeholder text
  value?: string;                // Default value (HH:mm format)
  required?: boolean;            // Is field required
  readonly?: boolean;            // Read-only mode
  disabled?: boolean;            // Disabled state
  className?: string;            // Additional CSS classes
  
  // Validation
  format?: string;               // Display format
}
```

## Time Format [#time-format]

The time field uses 24-hour format: `HH:mm`

Examples:

* `09:00` - 9:00 AM
* `14:30` - 2:30 PM
* `23:45` - 11:45 PM

## Use Cases [#use-cases]

* **Operating Hours**: Business hours, shift times
* **Scheduling**: Daily task times, recurring events
* **Alarms**: Reminder times, notification schedules
* **Time Tracking**: Work start/end times


# URL Field





The URL Field component provides a text input with URL validation and clickable link rendering.

## Basic Usage [#basic-usage]

<SchemaExample id="fields-url/basic-url-field" />

## Required URL [#required-url]

<SchemaExample id="fields-url/required-url" />

## Field Schema [#field-schema]

```plaintext
interface UrlFieldSchema {
  type: 'url';
  name: string;                  // Field name/ID
  label?: string;                // Field label
  placeholder?: string;          // Placeholder text
  value?: string;                // Default value
  required?: boolean;            // Is field required
  readonly?: boolean;            // Read-only mode
  disabled?: boolean;            // Disabled state
  className?: string;            // Additional CSS classes
}
```

## Validation [#validation]

The URL field automatically validates:

* Proper URL protocol (http\:// or https\://)
* Valid domain structure
* No invalid characters

## Cell Renderer [#cell-renderer]

In tables/grids, URLs are clickable external links:

```plaintext
import { UrlCellRenderer } from '@object-ui/fields';

// Renders as: <a href="https://example.com" target="_blank">https://example.com</a>
// Opens in new tab with security attributes
```

## Use Cases [#use-cases]

* **Websites**: Company or personal websites
* **Social Media**: Social media profile links
* **Documentation**: External documentation links
* **Resources**: Reference materials, articles
* **Portfolios**: Portfolio or project links

## Features [#features]

* **Link Preview**: Clickable links in read-only mode
* **New Tab**: External links open in new tab
* **Security**: Proper rel="noopener noreferrer" attributes
* **Validation**: Real-time URL format validation
* **Accessible**: Proper ARIA labels for screen readers


# User Field





The User Field component provides a user selector for assigning users or owners to records. It displays user avatars and supports both single and multiple user selection.

## Basic Usage [#basic-usage]

<SchemaExample id="fields-user/single-user-selection" />

## Multiple Users [#multiple-users]

<SchemaExample id="fields-user/multiple-user-selection" />

## Owner Field [#owner-field]

<SchemaExample id="fields-user/record-owner-read-only" />

## Field Schema [#field-schema]

```plaintext
interface UserFieldSchema {
  type: 'user' | 'owner';
  name: string;                  // Field name/ID
  label?: string;                // Field label
  value?: User | User[];         // Selected user(s)
  required?: boolean;            // Is field required
  readonly?: boolean;            // Read-only mode
  disabled?: boolean;            // Disabled state
  className?: string;            // Additional CSS classes
  
  // User Options
  multiple?: boolean;            // Allow multiple users
}

interface User {
  id: string;                    // User ID
  name?: string;                 // Display name
  username?: string;             // Username
  email?: string;                // Email address
  avatar?: string;               // Avatar URL
}
```

## User vs Owner [#user-vs-owner]

* **User Field**: Selectable user field for assignments, team members, etc.
* **Owner Field**: Typically read-only, automatically set to the record creator

## Display Features [#display-features]

* **Avatar Badges**: User avatars with initials if no image
* **Color Coding**: Consistent colors for user avatars
* **Multiple Display**: Shows up to 3 users, then "+N more"
* **Hover Info**: User details on avatar hover

## Cell Renderer [#cell-renderer]

In tables/grids, displays avatar with name:

```plaintext
import { UserCellRenderer } from '@object-ui/fields';

// Single user: Avatar + name
// Multiple users: Overlapping avatars + count
```

## How it works [#how-it-works]

`user` / `owner` fields are a **lookup specialized to the framework's `sys_user`
object** — there is no custom user API to wire up. The `UserField` widget
delegates to the shared lookup picker with the reference fixed to `sys_user`,
reusing the same debounced search, record-picker dialog and id resolution as any
lookup field:

* The field stores the selected user's **id** (a foreign key to `sys_user`);
  `multiple: true` stores an array of ids.
* A `dataSource` (provided by `SchemaRenderer` / the app shell) supplies the
  candidate search — the picker queries `sys_user` by name/email as you type.
* On read, `$expand` resolves the id(s) to the full user record so cells and
  read-only views show the name/avatar (via `UserCellRenderer`).

No custom user-management integration is required when a `dataSource` is present.

## Permission Patterns [#permission-patterns]

Common permission configurations:

```plaintext
// Record owner only
{
  type: 'owner',
  name: 'owner',
  label: 'Owner',
  readonly: true,
  defaultValue: 'current_user'
}

// Assignable user
{
  type: 'user',
  name: 'assigned_to',
  label: 'Assigned To',
  required: true
}

// Team members
{
  type: 'user',
  name: 'collaborators',
  label: 'Collaborators',
  multiple: true
}
```

## Use Cases [#use-cases]

* **Task Management**: Task assignee, reviewer
* **CRM**: Account owner, opportunity owner
* **Support**: Ticket assignee, support agent
* **Project Management**: Project members, task owners
* **Approval Workflows**: Approvers, reviewers
* **Collaboration**: Document collaborators, editors

## Backend behavior [#backend-behavior]

The platform handles the common cases natively — you generally don't write
backend code for user fields:

* **Owner stamping** — declare `defaultValue: 'current_user'` and the acting
  user's id is filled in at insert time (no create hook required).
* **Display resolution** — request `expand=<field>` and the stored id(s) resolve
  to the full `sys_user` record (name / avatar) for rendering.
* **Ownership & permissions** — record ownership and row-level security continue
  to use the platform's `owner_id` convention and security rules.


# Vector Field





The Vector Field component displays vector embeddings used in AI/ML applications. This is a read-only field that shows a preview of the embedding values and dimensionality.

## Basic Usage [#basic-usage]

<SchemaExample id="fields-vector/basic-vector-display" />

## Different Dimensions [#different-dimensions]

<SchemaExample id="fields-vector/high-dimensional-vector" />

## Field Schema [#field-schema]

```plaintext
interface VectorFieldSchema {
  type: 'vector';
  name: string;                  // Field name/ID
  label?: string;                // Field label
  value?: number[];              // Vector array
  readonly: true;                // Always read-only
  className?: string;            // Additional CSS classes
  
  // Vector Options
  dimensions?: number;           // Vector dimensionality
}
```

## Display Format [#display-format]

Vectors are displayed with a preview:

```
[0.1234, -0.5678, 0.9012...] (768D)
```

Shows:

* First 3 values (formatted to 4 decimal places)
* Total dimensionality in parentheses

## Common Embedding Dimensions [#common-embedding-dimensions]

Different AI models use different embedding sizes:

* **OpenAI text-embedding-3-small**: 512, 1536, or 3072 dimensions (configurable)
* **OpenAI text-embedding-3-large**: 256, 1024, or 3072 dimensions (configurable)
* **OpenAI text-embedding-ada-002**: 1536 dimensions (fixed)
* **Sentence Transformers (BERT)**: 768 dimensions
* **OpenAI CLIP**: 512 dimensions
* **Word2Vec**: 100-300 dimensions
* **Custom Models**: Variable dimensions

## Data Format [#data-format]

Vectors are stored as arrays of floating-point numbers:

```plaintext
// Example embedding
const embedding: number[] = [
  0.1234, -0.5678, 0.9012, 0.3456, -0.7890,
  // ... 763 more values for 768D embedding
];
```

## Cell Renderer [#cell-renderer]

In tables/grids, displays compact preview:

```plaintext
import { VectorCellRenderer } from '@object-ui/fields';

// Renders: [0.1234, -0.5678, 0.9012...] (768D)
```

## Vector Operations [#vector-operations]

Common operations with vector fields (performed on backend):

### Similarity Search [#similarity-search]

```plaintext
// Find similar vectors using cosine similarity
const findSimilar = async (queryVector: number[], limit: number = 10) => {
  return await db.raw(`
    SELECT 
      id,
      1 - (embedding <=> $1) as similarity
    FROM documents
    ORDER BY embedding <=> $1
    LIMIT $2
  `, [queryVector, limit]);
};
```

### Distance Metrics [#distance-metrics]

* **Cosine Similarity**: Measures angle between vectors
* **Euclidean Distance**: Straight-line distance
* **Dot Product**: Inner product of vectors

## Use Cases [#use-cases]

* **Semantic Search**: Find similar documents, products, or content
* **Recommendation Systems**: Product recommendations, content suggestions
* **Text Analysis**: Document clustering, topic modeling
* **Image Search**: Similar image finding, visual search
* **Anomaly Detection**: Identify outliers in data
* **AI Applications**: Any machine learning feature vectors

## Backend Implementation [#backend-implementation]

Example vector storage and search:

```plaintext
// PostgreSQL with pgvector extension
import { Client } from 'pg';

// Create table with vector column
const createTable = async () => {
  await db.raw(`
    CREATE TABLE IF NOT EXISTS documents (
      id SERIAL PRIMARY KEY,
      content TEXT,
      embedding vector(768)
    );
    
    CREATE INDEX ON documents 
    USING ivfflat (embedding vector_cosine_ops);
  `);
};

// Generate embedding (using OpenAI)
const generateEmbedding = async (text: string): Promise<number[]> => {
  const response = await openai.embeddings.create({
    model: 'text-embedding-3-small',
    input: text
  });
  return response.data[0].embedding;
};

// Store document with embedding
const storeDocument = async (content: string) => {
  const embedding = await generateEmbedding(content);
  return db.insert('documents', {
    content,
    embedding
  });
};

// Search similar documents
const searchSimilar = async (query: string, limit = 10) => {
  const queryEmbedding = await generateEmbedding(query);
  return db.raw(`
    SELECT 
      id,
      content,
      1 - (embedding <=> $1::vector) as similarity
    FROM documents
    ORDER BY embedding <=> $1::vector
    LIMIT $2
  `, [queryEmbedding, limit]);
};
```

## Database Support [#database-support]

Vector storage is supported by:

* **PostgreSQL**: pgvector extension
* **Pinecone**: Specialized vector database
* **Weaviate**: Vector search engine
* **Milvus**: Open-source vector database
* **Qdrant**: Vector similarity search engine
* **Chroma**: AI-native embedding database

## Performance Considerations [#performance-considerations]

1. **Indexing**: Use approximate nearest neighbor (ANN) indices
2. **Quantization**: Consider dimension reduction for storage
3. **Batch Operations**: Generate embeddings in batches
4. **Caching**: Cache frequently used embeddings
5. **Async Generation**: Generate embeddings asynchronously

## Example: Semantic Search [#example-semantic-search]

```plaintext
// 1. Generate embedding for user query
const query = "Find documentation about authentication";
const queryEmbedding = await generateEmbedding(query);

// 2. Search for similar documents
const results = await db.raw(`
  SELECT 
    id,
    title,
    content,
    1 - (embedding <=> $1::vector) as similarity
  FROM documents
  WHERE 1 - (embedding <=> $1::vector) > 0.7
  ORDER BY embedding <=> $1::vector
  LIMIT 10
`, [queryEmbedding]);

// 3. Display results with similarity scores
results.forEach(doc => {
  console.log(`${doc.title} (${(doc.similarity * 100).toFixed(1)}% match)`);
});
```


# Agent Skills



# Agent Skills [#agent-skills]

ObjectUI ships an official **Agent Skill** — a structured bundle of rules, guides, and evals that teaches AI coding agents how to build pages, plugins, and integrations the *right* way (schema-first, no-touch zones respected, English-only, expression-aware).

The skill is published on [skills.sh](https://skills.sh/objectstack-ai/objectui) and lives in [`skills/objectui/`](https://github.com/objectstack-ai/objectui/tree/main/skills/objectui) inside this repository.

[![skills.sh](https://skills.sh/b/objectstack-ai/objectui)](https://skills.sh/objectstack-ai/objectui)

## Install [#install]

One command, in your project root:

```bash
npx skills add objectstack-ai/objectui
```

The `skills` CLI auto-detects which AI agent you're using and writes the skill to the location that agent reads from — for example:

| Agent                                                | Install location                   |
| ---------------------------------------------------- | ---------------------------------- |
| Claude Code                                          | `.claude/skills/objectui/`         |
| GitHub Copilot                                       | `.github/copilot/skills/objectui/` |
| Cursor                                               | `.cursor/skills/objectui/`         |
| Codex                                                | `.codex/skills/objectui/`          |
| Windsurf, Gemini, Cline, Goose, Kilo, Droid, Trae, … | per-agent path                     |

See [skills.sh/docs](https://skills.sh/docs) for the full, up-to-date list of supported agents.

## What you get [#what-you-get]

Once installed the skill activates automatically whenever you describe ObjectUI work in chat. Nothing to import, nothing to configure.

The skill is structured as a single entry point plus deep-dive guides:

```
skills/objectui/
├── SKILL.md         # Entry point — core principles, tech stack, scope
├── rules/           # Non-negotiable global constraints
│   ├── protocol.md
│   ├── styling.md
│   ├── composition.md
│   └── no-touch-zones.md
├── guides/          # Domain-specific deep dives, loaded on demand
│   ├── architecture.md
│   ├── page-builder.md
│   ├── plugin-development.md
│   ├── schema-expressions.md
│   ├── data-integration.md
│   ├── project-setup.md
│   ├── testing.md
│   ├── i18n.md
│   ├── mobile.md
│   ├── auth-permissions.md
│   └── console-development.md
└── evals/           # Machine-checkable prompts (one per guide)
```

When the agent picks up a task it:

1. Reads `SKILL.md` for core principles, scope boundaries, and the package map.
2. Loads the relevant `rules/*.md` so non-negotiables (Shadcn purity, expression syntax, layout composition) are respected.
3. Pulls the matching `guides/*.md` for the task at hand.

## What the skill enforces [#what-the-skill-enforces]

The skill bakes the ObjectUI worldview into every answer your agent gives you:

* **Schema-first**: page output is JSON for `<SchemaRenderer>`, not bespoke React.
* **Shadcn-native aesthetics**: components stay in Tailwind + `cn()` + `cva`; no inline styles, no CSS-in-JS.
* **Protocol agnostic**: data goes through the `DataSource` interface, not raw `fetch`/`axios`.
* **Expression-aware**: `visible`, `hidden`, `disabled` use `${data.*}` / `${props.*}` templates, never raw JS.
* **No-touch zones**: upstream Shadcn primitives in `packages/components/src/ui/**` are never edited — extensions live in `custom/` wrappers.
* **English-only**: all generated component text, labels, comments, and docs are English.
* **Scope discipline**: the skill explicitly defers backend/data-modelling questions to the `objectstack-*` skills, so it stays focused on the UI engine.

Each rule has a machine-checkable eval under `evals/`, so regressions in agent behaviour are caught the same way regressions in code are.

## When *not* to use it [#when-not-to-use-it]

If your question is purely about data modelling, kernel plugins, ObjectQL queries, CEL formulas, or server-side automation, prefer the matching `objectstack-*` skill. The ObjectUI skill's frontmatter explicitly defers those topics so multiple skills can coexist cleanly in your agent.

## Updating [#updating]

To pull the latest version of the skill after we ship improvements:

```bash
npx skills add objectstack-ai/objectui
```

The CLI is idempotent — running it again refreshes the local copy in place.

## Contributing [#contributing]

The skill source lives in [`skills/objectui/`](https://github.com/objectstack-ai/objectui/tree/main/skills/objectui). PRs are welcome — see [`skills/objectui/README.md`](https://github.com/objectstack-ai/objectui/blob/main/skills/objectui/README.md) for the maintenance rules (guide ↔ eval naming, English-only, eval assertion format).


# Architecture Overview



# Architecture Overview [#architecture-overview]

ObjectUI is a **Server-Driven UI (SDUI) engine** that transforms JSON schemas into fully interactive React interfaces built on Shadcn/Tailwind. This document covers the internal architecture, data flow, and extension points.

## The 3-Layer Architecture [#the-3-layer-architecture]

ObjectUI enforces a strict separation across three layers. Each layer has clear constraints on what it may import and what it may contain.

```
┌─────────────────────────────────────────────────────────────────────┐
│  Layer 1: @objectstack/spec ^4.0.4 (The Protocol)                  │
│  Pure TypeScript type definitions — 12 export modules               │
│  ❌ No runtime code. No React. No dependencies.                    │
└──────────────────────────────┬──────────────────────────────────────┘
                               │ imports (never redefines)
┌──────────────────────────────▼──────────────────────────────────────┐
│  Layer 2: @object-ui/types (The Bridge)                             │
│  Re-exports spec types + ObjectUI-specific schemas                  │
│  ❌ No runtime code. Zero runtime dependencies.                    │
└──────────────────────────────┬──────────────────────────────────────┘
                               │ consumed by
┌──────────────────────────────▼──────────────────────────────────────┐
│  Layer 3: Implementations (The Runtime)                             │
│  core, react, components (91+), fields (35+), plugins, etc.        │
└─────────────────────────────────────────────────────────────────────┘
```

### Layer 1 — `@objectstack/spec` (The Protocol) [#layer-1--objectstackspec-the-protocol]

The upstream JSON specification for all ObjectStack products. ObjectUI **imports** these types but never redefines them. Located externally; consumed as `@objectstack/spec ^4.0.0`.

### Layer 2 — `@object-ui/types` (The Bridge) [#layer-2--object-uitypes-the-bridge]

Lives in `packages/types/`. Re-exports spec types and adds ObjectUI-specific schemas (component schemas, widget props, field props). Has **zero** runtime dependencies — only type-level imports of `@objectstack/spec` and `zod` for validation schemas. Marked `sideEffects: false`.

### Layer 3 — Implementations (The Runtime) [#layer-3--implementations-the-runtime]

All packages that ship runnable code: `core`, `react`, `components`, `fields`, `layout`, `i18n`, `auth`, `permissions`, and every `plugin-*` package.

## Package Dependency Graph [#package-dependency-graph]

```
@objectstack/spec
       │
       ▼
@object-ui/types ◄─────────────────────────────────────┐
       │                                                │
       ▼                                                │
@object-ui/core                                         │
       │  (registry, evaluator, actions, validation)    │
       ▼                                                │
@object-ui/react ──────► @object-ui/i18n                │
       │  (SchemaRenderer, hooks, contexts)             │
       ├──────────────────────────────────────┐         │
       ▼                                      ▼         │
@object-ui/components              @object-ui/fields    │
       │  (91+ Shadcn atoms)          (35+ inputs)      │
       ▼                                      ▼         │
@object-ui/layout           @object-ui/plugin-*         │
  (AppShell, Header,          (grid, kanban, charts,    │
   Sidebar, routing)           dashboard, form, etc.)   │
                                      │                 │
                                      └─────────────────┘
                                   (all packages import types)
```

**Strict rules:**

| Package      | May Import                       | Must NOT Import          |
| ------------ | -------------------------------- | ------------------------ |
| `types`      | `@objectstack/spec`              | Any runtime package      |
| `core`       | `types`, `lodash`, `zod`         | React, any UI library    |
| `react`      | `core`, `types`, `i18n`          | Plugin packages directly |
| `components` | `types` (for props)              | `core`, `react`          |
| `fields`     | `types` (for `FieldWidgetProps`) | `core` business logic    |
| `plugin-*`   | Any package                      | Other plugins            |

## Data Flow: Schema → Screen [#data-flow-schema--screen]

The rendering pipeline transforms a JSON schema into a live React component tree:

```
  JSON Schema (from API or static file)
       │
       ▼
  ┌─────────────┐     ┌──────────────────┐
  │ SchemaRenderer │───►│ ExpressionEvaluator │
  │ (packages/     │     │ Resolves ${...}     │
  │  react/src/)   │     │ expressions         │
  └──────┬────────┘     └──────────────────┘
         │
         ▼
  ┌─────────────────┐
  │ ComponentRegistry │  ← registry.resolve(schema.type)
  │ (packages/core/  │
  │  src/registry/)  │
  └──────┬──────────┘
         │
         ▼
  ┌──────────────────┐
  │ React Component   │  ← Wrapped in ErrorBoundary
  │ (Button, Grid,    │     with ARIA attributes
  │  Kanban, etc.)    │
  └──────────────────┘
```

1. **SchemaRenderer** (`packages/react/src/SchemaRenderer.tsx`) receives a JSON schema object.
2. It evaluates dynamic expressions via `ExpressionEvaluator` (`packages/core/src/evaluator/`).
3. It looks up the component type in the `ComponentRegistry` (`packages/core/src/registry/Registry.ts`).
4. The matched component renders with schema props, wrapped in a per-component `ErrorBoundary` with ARIA accessibility attributes (`aria-label`, `aria-describedby`, `role`).

## The Plugin System [#the-plugin-system]

Plugins are self-contained packages that register heavy or complex views (grids, kanbans, charts). They follow a consistent pattern defined in `packages/core/src/registry/PluginSystem.ts`.

### Plugin Lifecycle [#plugin-lifecycle]

```
  import 'plugin-kanban'
       │
       ▼
  PluginSystem.load(plugin)
       │  ├─ Check dependencies
       │  ├─ Prevent duplicate loading
       │  └─ Call plugin.register(scope)
       ▼
  PluginScope.registerComponent(type, Component, meta)
       │  └─ Auto-prefixes with plugin namespace
       ▼
  ComponentRegistry.register('kanban-ui', KanbanRenderer, {
    namespace: 'plugin-kanban',
    category: 'plugin'
  })
```

### Lazy Loading [#lazy-loading]

Plugins use `React.lazy()` wrapped by `LazyPluginLoader` (`packages/react/src/LazyPluginLoader.tsx`):

* **Retry logic**: 2 retries with 1-second delay by default
* **Custom fallbacks**: Loading skeleton + error boundary
* **Tree-shaking**: Plugins are code-split from the initial bundle

### Plugin Registration Pattern [#plugin-registration-pattern]

Every plugin follows the same structure (see `packages/plugin-kanban/`, `packages/plugin-grid/`):

```typescript
// 1. Lazy-load the heavy implementation
const LazyKanban = React.lazy(() => import('./KanbanImpl'));

// 2. Define a thin wrapper with Suspense
const KanbanRenderer: React.FC<Props> = ({ schema }) => (
  <Suspense fallback={<Skeleton />}>
    <LazyKanban schema={schema} />
  </Suspense>
);

// 3. Register in the global registry
ComponentRegistry.register('kanban-ui', KanbanRenderer, {
  namespace: 'plugin-kanban',
  label: 'Kanban Board',
  category: 'plugin',
  inputs: [/* schema config */]
});
```

Scaffold a new plugin with `npx @object-ui/create-plugin`.

## State Management [#state-management]

ObjectUI uses **React Context** for all state management, with contexts scoped to specific concerns:

### Core Contexts (`packages/react/src/context/`) [#core-contexts-packagesreactsrccontext]

| Context                 | Purpose                                               |
| ----------------------- | ----------------------------------------------------- |
| `SchemaRendererContext` | Data scope + debug mode for the rendering tree        |
| `ActionContext`         | Action runner instance for handling user interactions |
| `ThemeContext`          | Theme tokens and dark/light mode                      |
| `NotificationContext`   | Toast and notification system                         |
| `DndContext`            | Drag-and-drop state for sortable views                |

### Domain Contexts (separate packages) [#domain-contexts-separate-packages]

| Context             | Package                 | Purpose                 |
| ------------------- | ----------------------- | ----------------------- |
| `AuthContext`       | `packages/auth/`        | Authentication state    |
| `PermissionContext` | `packages/permissions/` | RBAC/ABAC permissions   |
| `I18nProvider`      | `packages/i18n/`        | Locale and translations |

Contexts are composed at the application root and consumed by plugins and components via hooks (e.g., `useActionRunner`, `useExpression`, `useViewData`).

## Expression Evaluation [#expression-evaluation]

The expression engine lives in `packages/core/src/evaluator/` and powers dynamic schemas:

### Components [#components]

* **`ExpressionEvaluator.ts`** — Main engine: parses and evaluates `${...}` template expressions.
* **`ExpressionContext.ts`** — Variable scope: provides `data`, `user`, `params` to expressions.
* **`ExpressionCache.ts`** — Caches parsed expressions for repeated evaluations.
* **`FormulaFunctions.ts`** — Built-in functions available inside expressions.

### Expression Types [#expression-types]

```json
{
  "visible": "${data.role === 'admin'}",
  "label": "Hello, ${data.user.name}!",
  "disabled": "${data.status !== 'draft'}",
  "className": "${data.priority === 'high' ? 'text-red-500' : 'text-gray-500'}"
}
```

Expressions support:

* **String interpolation**: `"Welcome, ${data.name}"`
* **Conditionals**: `"${data.age > 18}"`
* **Ternary operators**: `"${data.active ? 'Yes' : 'No'}"`
* **Variable references**: `data.*`, `user.*`, `params.*`

## Action System [#action-system]

The action system (`packages/core/src/actions/`) handles user interactions defined in schemas.

### ActionRunner (`ActionRunner.ts`) [#actionrunner-actionrunnerts]

Executes action schemas and returns directives:

```
  User Click → Schema Action
       │
       ▼
  ActionRunner.execute(action, context)
       │  ├─ Check confirmation dialog
       │  ├─ Evaluate conditions
       │  └─ Execute by action type
       ▼
  ActionResult
    ├─ reload: boolean
    ├─ redirect: string
    ├─ modal: SchemaObject
    └─ toast: { message, type }
```

### Supported Action Types [#supported-action-types]

| Type     | Description                          |
| -------- | ------------------------------------ |
| `script` | Execute inline JavaScript            |
| `url`    | Navigate to a URL                    |
| `api`    | Make an API request (AJAX)           |
| `modal`  | Open a modal with a nested schema    |
| `flow`   | Execute a multi-step action sequence |

### TransactionManager (`TransactionManager.ts`) [#transactionmanager-transactionmanagerts]

Wraps multi-step actions in transactions for consistency, supporting rollback on failure.

## Key Directories Reference [#key-directories-reference]

```
packages/
├── types/src/           # Layer 2 — Pure type definitions
├── core/src/
│   ├── evaluator/       # Expression engine
│   ├── registry/        # Component & plugin registries
│   ├── actions/         # ActionRunner, TransactionManager
│   ├── validation/      # Schema validation engine
│   ├── adapters/        # Data source adapters (API, Value)
│   ├── data-scope/      # DataScopeManager
│   ├── query/           # Query AST (filtering/sorting)
│   ├── theme/           # ThemeEngine
│   └── builder/         # Schema builder utilities
├── react/src/
│   ├── SchemaRenderer.tsx
│   ├── LazyPluginLoader.tsx
│   ├── context/         # All React contexts
│   └── hooks/           # 20+ hooks (useExpression, useActionRunner, etc.)
├── components/          # 91+ Shadcn UI atoms
├── fields/              # 35+ field renderers
├── layout/              # AppShell, Header, Sidebar
├── i18n/                # Internationalization
├── auth/                # AuthContext + providers
├── permissions/         # RBAC/ABAC
└── plugin-*/            # 20 plugin packages
    ├── plugin-grid/
    ├── plugin-kanban/
    ├── plugin-charts/
    ├── plugin-dashboard/
    ├── plugin-form/
    └── ... (15 more)
```

## Further Reading [#further-reading]

* [Schema Overview](/docs/guide/schema-overview) — JSON schema structure
* [Schema Rendering](/docs/guide/schema-rendering) — How schemas become UI
* [Component Registry](/docs/guide/component-registry) — Registering components
* [Plugin Development](/docs/guide/plugin-development) — Building plugins
* [Expressions](/docs/guide/expressions) — Expression syntax reference
* [Theming](/docs/guide/theming) — Theme configuration


# Architecture Overview



# Architecture Overview [#architecture-overview]

ObjectUI is a universal, server-driven UI (SDUI) engine built on React, Tailwind CSS, and Shadcn UI. This guide explains the core architecture and how all the pieces work together.

## Core Philosophy [#core-philosophy]

ObjectUI follows three fundamental principles:

1. **JSON-First**: Every UI element is described as JSON metadata, not hardcoded React components
2. **Backend Agnostic**: Works with any backend system (ObjectStack, custom APIs, etc.)
3. **Component Library Quality**: Combines low-code speed with Shadcn/Tailwind design quality

## Architecture Layers [#architecture-layers]

```
┌─────────────────────────────────────────────┐
│         JSON Schema (Protocol)              │  ← Backend sends this
├─────────────────────────────────────────────┤
│      @object-ui/react (Renderer)            │  ← Interprets schema
├─────────────────────────────────────────────┤
│  Component Registry + Field Registry        │  ← Lookup system
├─────────────────────────────────────────────┤
│    @object-ui/components (UI Primitives)    │  ← Buttons, Cards, etc.
│    @object-ui/fields (Form Inputs)          │  ← Text, Date, Select
│    @object-ui/layout (Page Structure)       │  ← AppShell, Sidebar
│    @object-ui/plugin-* (Advanced Widgets)   │  ← Grid, Charts, Kanban
├─────────────────────────────────────────────┤
│   Shadcn UI + Radix UI (Primitives)         │  ← Accessible components
│   Tailwind CSS (Styling)                    │  ← Utility-first CSS
└─────────────────────────────────────────────┘
```

## Package Structure [#package-structure]

ObjectUI is organized as a PNPM monorepo with clear separation of concerns:

### Core Packages [#core-packages]

#### `@object-ui/types` [#object-uitypes]

* **Role**: The Protocol
* **Contains**: Pure TypeScript interfaces for JSON schemas
* **Constraint**: ZERO dependencies, no React code
* **Example**: `ComponentSchema`, `ActionSchema`, `FieldSchema`

#### `@object-ui/core` [#object-uicore]

* **Role**: The Engine
* **Contains**: Schema validation, expression evaluation, registries
* **Constraint**: No UI library dependencies, logic only
* **Features**:
  * Expression engine (`visible: "${data.age > 18}"`)
  * Schema registry and validation
  * Event system

#### `@object-ui/react` [#object-uireact]

* **Role**: The Runtime
* **Contains**: `SchemaRenderer` and React integration
* **Purpose**: Transforms JSON schemas into live React components

### UI Packages [#ui-packages]

#### `@object-ui/components` [#object-uicomponents]

* **Role**: The Atoms
* **Contains**: Shadcn primitives (Button, Badge, Card, Dialog, etc.)
* **Constraint**: Pure UI, no business logic
* **Style**: Tailwind CSS with `class-variance-authority`

#### `@object-ui/fields` [#object-uifields]

* **Role**: The Inputs
* **Contains**: Standard field renderers (Text, Number, Select, Date, etc.)
* **Implements**: `FieldWidgetProps` interface
* **Purpose**: Reusable form inputs with consistent API

#### `@object-ui/layout` [#object-uilayout]

* **Role**: The Shell
* **Contains**: Page structure components (AppShell, Page, Sidebar, Header)
* **Purpose**: Routing-aware composition and app scaffolding

### Plugin Packages [#plugin-packages]

Each plugin provides specialized, complex widgets:

* `@object-ui/plugin-grid` - Data tables with ObjectStack integration
* `@object-ui/plugin-kanban` - Kanban board view
* `@object-ui/plugin-charts` - Recharts-based visualizations
* `@object-ui/plugin-calendar` - Calendar and event views
* `@object-ui/plugin-map` - Map visualization
* `@object-ui/plugin-form` - Advanced forms
* `@object-ui/plugin-editor` - Code editor (Monaco)
* `@object-ui/plugin-markdown` - Markdown renderer
* `@object-ui/plugin-gantt` - Gantt chart timeline
* `@object-ui/plugin-timeline` - Event timeline
* `@object-ui/plugin-dashboard` - Dashboard layouts
* `@object-ui/plugin-chatbot` - Chat interface

**Important**: Heavy dependencies (like Monaco, Recharts) are only allowed in plugin packages to keep the core bundle small.

### Utility Packages [#utility-packages]

Development tools and integration utilities:

* `@object-ui/cli` - Command-line tool for building apps from schemas
* `@object-ui/create-plugin` - Interactive plugin scaffolder
* `@object-ui/runner` - Universal runtime for testing and demos
* `@object-ui/data-objectstack` - ObjectStack data backend adapter
* `vscode-extension` - VS Code extension for schema development

[Learn more about utilities →](/docs/utilities)

## How Schema Rendering Works [#how-schema-rendering-works]

### 1. JSON Schema Input [#1-json-schema-input]

A backend system sends a JSON schema:

```json
{
  "type": "card",
  "title": "Welcome",
  "body": {
    "type": "text",
    "value": "Hello, ${user.name}!"
  }
}
```

### 2. SchemaRenderer Processing [#2-schemarenderer-processing]

The `SchemaRenderer` component:

1. Receives the schema + data context
2. Evaluates expressions (`${user.name}`)
3. Looks up the component type in the registry
4. Recursively renders child schemas
5. Handles events and state updates

```tsx
import { SchemaRenderer } from '@object-ui/react'

function App() {
  const data = { user: { name: "Alice" } }
  
  return <SchemaRenderer schema={schema} data={data} />
}
```

### 3. Component Registry Lookup [#3-component-registry-lookup]

The registry maps type strings to React components:

```typescript
// During app initialization
ComponentRegistry.register('card', CardComponent)
ComponentRegistry.register('text', TextComponent)

// At runtime
const Component = ComponentRegistry.get('card') // → CardComponent
```

### 4. React Component Rendering [#4-react-component-rendering]

The registered component renders with evaluated props:

```tsx
<CardComponent title="Welcome">
  <TextComponent value="Hello, Alice!" />
</CardComponent>
```

## The Registry Pattern [#the-registry-pattern]

ObjectUI uses two registry systems for extensibility:

### Component Registry [#component-registry]

Maps schema types to React components:

```tsx
import { ComponentRegistry } from '@object-ui/core'

// Register a component
ComponentRegistry.register('my-widget', MyWidgetComponent, {
  label: 'My Widget',
  category: 'Custom',
  icon: 'box',
  inputs: [
    { name: 'title', type: 'string', label: 'Title' }
  ]
})
```

### Field Registry [#field-registry]

Maps field types to input components:

```tsx
import { registerFieldRenderer } from '@object-ui/fields'

// Register a field renderer
registerFieldRenderer('rating', RatingFieldComponent)
```

This allows:

* ✅ Overriding standard components
* ✅ Adding custom field types
* ✅ Plugin system for complex widgets
* ✅ Keeping bundles small (lazy loading)

## Expression System [#expression-system]

ObjectUI includes a powerful expression engine for dynamic UIs:

### String Interpolation [#string-interpolation]

```json
{
  "type": "text",
  "value": "Welcome, ${user.firstName} ${user.lastName}!"
}
```

### Conditional Rendering [#conditional-rendering]

```json
{
  "type": "button",
  "text": "Submit",
  "visible": "${form.isValid && !form.isSubmitting}",
  "disabled": "${form.isSubmitting}"
}
```

### Data Transformations [#data-transformations]

```json
{
  "type": "badge",
  "text": "${orders.length} Orders",
  "variant": "${orders.length > 10 ? 'success' : 'warning'}"
}
```

See the [Expressions Guide](/docs/guide/expressions) for complete details.

## Data Flow [#data-flow]

```
Backend API
    ↓
JSON Schema + Data
    ↓
SchemaRenderer (evaluates expressions)
    ↓
Component Registry (maps types)
    ↓
React Components (render UI)
    ↓
User Interactions (events)
    ↓
Event Handlers (update data)
    ↓
Re-render (React state updates)
```

## Styling System [#styling-system]

ObjectUI uses **Tailwind CSS** exclusively for styling:

### Class-Variance-Authority (CVA) [#class-variance-authority-cva]

All component variants use `cva` for type-safe variants:

```tsx
import { cva } from 'class-variance-authority'

const buttonVariants = cva(
  'inline-flex items-center justify-center rounded-md',
  {
    variants: {
      variant: {
        default: 'bg-primary text-primary-foreground',
        destructive: 'bg-destructive text-destructive-foreground',
      },
      size: {
        default: 'h-10 px-4 py-2',
        sm: 'h-9 px-3',
        lg: 'h-11 px-8',
      }
    }
  }
)
```

### Class Merging [#class-merging]

Use `cn()` helper (tailwind-merge + clsx) for class overrides:

```tsx
import { cn } from '@/lib/utils'

<Button className={cn('default-classes', props.className)} />
```

### ❌ Forbidden [#-forbidden]

* Inline styles (`style={{}}`) - except for dynamic values
* CSS Modules
* Styled-components
* Any CSS-in-JS library

## Type Safety [#type-safety]

ObjectUI is built with &#x2A;*TypeScript 5.0+** in strict mode:

```typescript
import type { ComponentSchema, ButtonSchema } from '@object-ui/types'

const schema: ButtonSchema = {
  type: 'button',
  text: 'Click me',
  variant: 'default', // ✅ Type-checked
  onClick: 'handleClick'
}
```

## Testing Strategy [#testing-strategy]

* **Unit Tests**: Vitest + React Testing Library
* **Type Tests**: TypeScript strict mode

## Best Practices [#best-practices]

### 1. Keep Core Light [#1-keep-core-light]

Heavy dependencies only go in plugins:

* ✅ `@object-ui/plugin-charts` can import Recharts
* ❌ `@object-ui/components` cannot import Recharts

### 2. Use Registries [#2-use-registries]

Don't import components directly - use registries:

```tsx
// ❌ Bad
import { MyGrid } from './MyGrid'
<MyGrid data={data} />

// ✅ Good
ComponentRegistry.register('my-grid', MyGrid)
{ type: 'my-grid', data: [...] }
```

### 3. Tailwind Only [#3-tailwind-only]

Never use inline styles or CSS-in-JS:

```tsx
// ❌ Bad
<div style={{ backgroundColor: 'red' }}>

// ✅ Good
<div className="bg-red-500">
```

### 4. Expressions for Dynamic Values [#4-expressions-for-dynamic-values]

Use expressions for dynamic content:

```tsx
// ❌ Bad - hardcoded
{ type: 'text', value: 'Hello, John!' }

// ✅ Good - dynamic
{ type: 'text', value: 'Hello, ${user.name}!' }
```

## Plugin Development [#plugin-development]

When creating a plugin:

1. Create package in `packages/plugin-{name}/`
2. Export components and types
3. Register components with ComponentRegistry
4. Add documentation in `content/docs/plugins/`
5. Add to plugins meta.json

```typescript
// packages/plugin-mywidget/src/index.tsx
import { ComponentRegistry } from '@object-ui/core'
import { MyWidget } from './MyWidget'

export { MyWidget }

ComponentRegistry.register('my-widget', MyWidget, {
  label: 'My Widget',
  category: 'Plugins',
  icon: 'box'
})
```

## Related Documentation [#related-documentation]

* [Schema Rendering](/docs/guide/schema-rendering) - How schemas become React components
* [Component Registry](/docs/guide/component-registry) - Registering custom components
* [Field Registry](/docs/guide/fields) - Custom field types
* [Expressions](/docs/guide/expressions) - Dynamic expressions
* [Plugins](/docs/guide/plugins) - Plugin system
* [Data Sources](/docs/guide/data-source) - Data integration
* [Utilities](/docs/utilities) - Development tools and CLI utilities


# Building a CRUD App



# Building a CRUD App [#building-a-crud-app]

This tutorial walks you through building a **Task Manager** CRUD application with ObjectUI — from schema definition to data source setup to deployment.

## Prerequisites [#prerequisites]

* **Node.js** 20+ and **pnpm** 9+
* Basic knowledge of **React** and **TypeScript**

## Step 1: Project Setup [#step-1-project-setup]

Create a new React project and install the required ObjectUI packages:

```bash
pnpm create vite task-manager --template react-ts
cd task-manager
```

Install ObjectUI core packages and the plugins you need:

```bash
pnpm add @object-ui/react @object-ui/core @object-ui/types @object-ui/components @object-ui/fields
pnpm add @object-ui/plugin-grid @object-ui/plugin-form
```

Install Tailwind CSS:

```bash
pnpm add -D tailwindcss @tailwindcss/vite
```

Add Tailwind to your `vite.config.ts`:

```ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  plugins: [react(), tailwindcss()],
});
```

Add to your `src/index.css`:

```css
@import "tailwindcss";
```

## Step 2: Register Components [#step-2-register-components]

Create `src/setup.ts` to register the built-in component and field renderers:

```ts
import { Registry } from '@object-ui/core';
import { registerAllComponents } from '@object-ui/components';
import { registerAllFields } from '@object-ui/fields';

registerAllComponents(Registry);
registerAllFields(Registry);
```

Import this file once at the top of your app entry point (`src/main.tsx` or `src/App.tsx`).

## Step 3: Define the Object Schema [#step-3-define-the-object-schema]

Create `src/schemas/task.ts`. This is the metadata that drives the entire UI — grid columns, form fields, validation, and views are all derived from this schema:

```ts
import { ObjectSchema, Field } from '@object-ui/types';

export const TaskSchema = ObjectSchema.create({
  name: 'task',
  label: 'Task',
  icon: 'check-circle-2',
  titleFormat: '{title}',
  fields: {
    title: Field.text({
      label: 'Title',
      required: true,
      searchable: true,
    }),
    status: Field.select(
      ['Backlog', 'Todo', 'In Progress', 'Review', 'Done'],
      { label: 'Status', defaultValue: 'Todo' }
    ),
    priority: Field.select(
      ['Critical', 'High', 'Medium', 'Low'],
      { label: 'Priority', defaultValue: 'Medium' }
    ),
    assignee: Field.text({ label: 'Assignee' }),
    due_date: Field.date({ label: 'Due Date' }),
    description: Field.textarea({ label: 'Description' }),
  },
  list_views: {
    all: {
      label: 'All Tasks',
      columns: ['title', 'status', 'priority', 'assignee', 'due_date'],
    },
    active: {
      label: 'Active',
      columns: ['title', 'status', 'priority', 'assignee', 'due_date'],
      filter: [['status', '!=', 'Done']],
      sort: [['priority', 'asc']],
    },
  },
});
```

Each `Field.*()` call produces a `FieldMetadata` entry that ObjectUI uses to choose the correct renderer, apply validation, and generate form controls automatically.

## Step 4: Create a Data Source [#step-4-create-a-data-source]

ObjectUI never hardcodes `fetch` calls inside components. Instead, it communicates with your backend through the `DataSource` interface. Create `src/data/rest-data-source.ts`:

```ts
import type { DataSource, QueryParams, QueryResult } from '@object-ui/types';

export class RestDataSource implements DataSource {
  constructor(private baseUrl: string) {}

  async find(resource: string, params?: QueryParams): Promise<QueryResult> {
    const query = new URLSearchParams();
    if (params?.$top) query.set('$top', String(params.$top));
    if (params?.$skip) query.set('$skip', String(params.$skip));
    if (params?.$orderby) query.set('$orderby', params.$orderby);
    if (params?.$search) query.set('$search', params.$search);
    const res = await fetch(`${this.baseUrl}/${resource}?${query}`);
    const data = await res.json();
    return { data: data.items, total: data.total };
  }

  async findOne(resource: string, id: string | number) {
    return (await fetch(`${this.baseUrl}/${resource}/${id}`)).json();
  }

  async create(resource: string, data: Partial<any>) {
    const res = await fetch(`${this.baseUrl}/${resource}`, {
      method: 'POST', headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(data),
    });
    return res.json();
  }

  async update(resource: string, id: string | number, data: Partial<any>) {
    const res = await fetch(`${this.baseUrl}/${resource}/${id}`, {
      method: 'PATCH', headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(data),
    });
    return res.json();
  }

  async delete(resource: string, id: string | number) {
    return (await fetch(`${this.baseUrl}/${resource}/${id}`, { method: 'DELETE' })).ok;
  }

  async getObjectSchema(objectName: string) {
    return (await fetch(`${this.baseUrl}/schema/${objectName}`)).json();
  }
}
```

> **Tip:** For the ObjectStack backend, use the official `@object-ui/data-objectstack` adapter instead of writing your own. See the [Data Connectivity](/docs/guide/data-source) guide for details.

## Step 5: Render a CRUD Grid View [#step-5-render-a-crud-grid-view]

Wire everything together in `src/App.tsx`. The `SchemaRenderer` takes your schema and data source and renders the appropriate view:

```tsx
import './setup';
import { SchemaRenderer } from '@object-ui/react';
import { TaskSchema } from './schemas/task';
import { RestDataSource } from './data/rest-data-source';

const dataSource = new RestDataSource('https://api.example.com/v1');

function App() {
  return (
    <div className="min-h-screen bg-background p-6">
      <SchemaRenderer
        schema={{
          type: 'ObjectGrid',
          object: 'task',
          view: 'all',
          data: { objectSchema: TaskSchema },
        }}
        dataSource={dataSource}
      />
    </div>
  );
}

export default App;
```

This renders a fully interactive data grid with sortable columns, pagination, and row actions — all driven by the `TaskSchema` you defined.

## Step 6: Add Create and Edit Forms [#step-6-add-create-and-edit-forms]

ObjectUI generates forms directly from your schema. Extend `App.tsx` with form state:

```tsx
const [showForm, setShowForm] = useState(false);
const [editId, setEditId] = useState<string | null>(null);
```

Add a "New Task" button and handle row clicks to open the edit form:

```tsx
<SchemaRenderer
  schema={{ type: 'ObjectGrid', object: 'task', view: 'all', data: { objectSchema: TaskSchema } }}
  dataSource={dataSource}
  onRowClick={(row: any) => { setEditId(row.id); setShowForm(true); }}
/>

{showForm && (
  <SchemaRenderer
    schema={{
      type: 'ObjectForm',
      object: 'task',
      mode: editId ? 'edit' : 'create',
      recordId: editId,
      data: { objectSchema: TaskSchema },
    }}
    dataSource={dataSource}
    onSubmit={() => setShowForm(false)}
    onCancel={() => setShowForm(false)}
  />
)}
```

The form automatically renders the correct field widgets (text inputs, select dropdowns, date pickers) based on your `FieldMetadata` definitions. Validation rules like `required` are enforced out of the box.

## Step 7: Add Filters and Search [#step-7-add-filters-and-search]

Leverage the `active` list view you defined in Step 3, or add dynamic search:

```tsx
const [activeView, setActiveView] = useState('all');
const [searchQuery, setSearchQuery] = useState('');

// View switcher buttons
<button onClick={() => setActiveView('all')}>All Tasks</button>
<button onClick={() => setActiveView('active')}>Active</button>
<input
  placeholder="Search tasks..."
  value={searchQuery}
  onChange={(e) => setSearchQuery(e.target.value)}
/>

// Grid responds to view and search changes
<SchemaRenderer
  schema={{
    type: 'ObjectGrid',
    object: 'task',
    view: activeView,
    data: {
      objectSchema: TaskSchema,
      queryParams: searchQuery ? { $search: searchQuery } : undefined,
    },
  }}
  dataSource={dataSource}
/>
```

The `filter` and `sort` arrays defined in the `active` list view are applied automatically when that view is selected. The `$search` query param is passed through to your `DataSource.find()` method.

## Step 8: Add a Detail View [#step-8-add-a-detail-view]

Create a detail page that renders a single record with all its fields:

```tsx
function TaskDetail({ taskId, onBack }: { taskId: string; onBack: () => void }) {
  return (
    <div className="min-h-screen bg-background p-6">
      <button onClick={onBack} className="mb-4 text-sm text-muted-foreground">
        ← Back to list
      </button>
      <SchemaRenderer
        schema={{
          type: 'ObjectDetail',
          object: 'task',
          recordId: taskId,
          data: { objectSchema: TaskSchema },
        }}
        dataSource={dataSource}
      />
    </div>
  );
}
```

Use this component in your main app with simple routing state, or integrate with a router like React Router or TanStack Router for URL-based navigation.

## Deployment Considerations [#deployment-considerations]

**Environment config** — Keep your API URL configurable:

```ts
const dataSource = new RestDataSource(
  import.meta.env.VITE_API_URL || 'http://localhost:3000/api'
);
```

**Performance** — Use server-side pagination via `$top`/`$skip` query params. ObjectUI plugins support lazy loading via `LazyPluginLoader` from `@object-ui/react`. Set `cache: { enabled: true, ttl: 300 }` on your schema for client-side caching.

**Production build** — Run `pnpm build` and deploy the `dist/` folder to any static host (Vercel, Netlify, Cloudflare Pages).

**Authentication** — Extend `RestDataSource` to inject auth headers:

```ts
class AuthenticatedDataSource extends RestDataSource {
  constructor(baseUrl: string, private getToken: () => string) {
    super(baseUrl);
  }
  // Override fetch calls to include: Authorization: `Bearer ${this.getToken()}`
}
```

## Next Steps [#next-steps]

* Explore the [Schema Overview](/docs/guide/schema-overview) for advanced schema features
* Add a Kanban board view using `@object-ui/plugin-kanban` (see the [Todo example](https://github.com/objectstack-ai/objectui/tree/main/examples/todo))
* Connect to a production backend with the [Data Connectivity](/docs/guide/data-source) guide
* Build multi-object apps with relationships (see the [CRM example](https://github.com/objectstack-ai/objectui/tree/main/examples/crm))


# CI/CD Pipeline



# CI/CD Pipeline [#cicd-pipeline]

ObjectUI uses **11 GitHub Actions workflows** to automate testing, quality checks, security scanning, releases, and repository maintenance. All workflow files live in `.github/workflows/`.

## Workflow Overview [#workflow-overview]

```
┌─────────────────────────────────────────────────────────────────┐
│                     Push / PR to main/develop                   │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌──────────┐  ┌──────────────┐  ┌──────────────┐             │
│  │  ci.yml   │  │ size-check   │  │ performance- │             │
│  │ (test,    │  │   .yml       │  │ budget.yml   │             │
│  │  lint,    │  │              │  │              │             │
│  │  build)   │  │              │  │              │             │
│  └──────────┘  └──────────────┘  └──────────────┘             │
│                                                                 │
│  ┌──────────────┐                                              │
│  │  labeler.yml │                                              │
│  │              │                                              │
│  └──────────────┘                                              │
│                                                                 │
├─────────────────────────────────────────────────────────────────┤
│                        Push to main                             │
│  ┌───────────────────┐                                         │
│  │ changeset-release  │ → npm publish via changesets            │
│  │      .yml          │                                         │
│  └───────────────────┘                                         │
│                                                                 │
├─────────────────────────────────────────────────────────────────┤
│                      Tag push (v*)                              │
│  ┌──────────┐  ┌───────────────┐                               │
│  │ release  │  │ changelog.yml │                               │
│  │  .yml    │  │ (git-cliff)   │                               │
│  └──────────┘  └───────────────┘                               │
│                                                                 │
├─────────────────────────────────────────────────────────────────┤
│                        Scheduled                                │
│  ┌──────────┐  ┌───────────────────┐  ┌──────────────────┐    │
│  │ stale    │  │ shadcn-check.yml  │  │  dependabot-     │    │
│  │  .yml    │  │ (weekly Mon 9AM)  │  │  auto-merge.yml  │    │
│  └──────────┘  └───────────────────┘  └──────────────────┘    │
│                                                                 │
├─────────────────────────────────────────────────────────────────┤
│                    Manual dispatch                              │
│  ┌──────────────┐                                              │
│  │ check-links  │ → Lychee link validation                     │
│  │    .yml      │                                              │
│  └──────────────┘                                              │
└─────────────────────────────────────────────────────────────────┘
```

## Core CI Workflow (`ci.yml`) [#core-ci-workflow-ciyml]

**Triggers:** Push and PR to `main` and `develop` branches.

Runs five parallel jobs:

| Job            | Description                                                                        |
| -------------- | ---------------------------------------------------------------------------------- |
| **Test**       | Runs `vitest` across all packages with Turbo caching. Uploads coverage to Codecov. |
| **Lint**       | Runs ESLint via `eslint.config.js` (flat config) and TypeScript type-checking.     |
| **Build Core** | Builds all packages using `turbo run build`.                                       |
| **E2E Tests**  | Runs Playwright end-to-end tests from the `e2e/` directory.                        |
| **Build Docs** | Builds the documentation site (`apps/site`).                                       |

Uses: Node 20, pnpm (via `corepack`), Turbo remote caching.

## Performance Budget (`performance-budget.yml`) [#performance-budget-performance-budgetyml]

**Triggers:** Push and PR when changes touch `packages/`, `apps/console/`, or `pnpm-lock.yaml`.

**Enforced limits:**

| Bundle             | Max gzip size |
| ------------------ | ------------- |
| Console main entry | 60 KB         |

* Builds the console app and measures bundle sizes.
* Posts a PR comment with the budget report and pass/fail status.

## Size Check (`size-check.yml`) [#size-check-size-checkyml]

**Triggers:** Push to `main`/`develop` with changes in `packages/`.

**Enforced limits:**

| Package Category                     | Max Size    |
| ------------------------------------ | ----------- |
| Core (`@object-ui/core`)             | 50 KB       |
| Components (`@object-ui/components`) | 100 KB      |
| Plugins (`@object-ui/plugin-*`)      | 150 KB each |

* Generates a markdown table with raw and gzipped sizes for each package.
* Posts the size report as a PR comment.

## Link Checking (`check-links.yml`) [#link-checking-check-linksyml]

**Trigger:** Manual workflow dispatch (`workflow_dispatch`).

Uses [Lychee](https://github.com/lycheeverse/lychee) with configuration from `lychee.toml`:

* Scans markdown files in `docs/` and `README.md`
* Max concurrency: 10, timeout: 20s, retries: 3
* Excludes: localhost, example.com, Twitter/X, GitHub compare/commit URLs
* Remaps internal `/docs/*` paths to `file://./docs/*` for local resolution

## Release Workflows [#release-workflows]

### Tag Release (`release.yml`) [#tag-release-releaseyml]

**Trigger:** Push of version tags matching `v*`.

1. Runs the full test suite.
2. Builds all packages.
3. Creates a GitHub Release with auto-generated release notes.

> Note: npm publish is currently handled by `changeset-release.yml` instead.

### Changeset Release (`changeset-release.yml`) [#changeset-release-changeset-releaseyml]

**Trigger:** Push to `main`.

Uses [Changesets](https://github.com/changesets/changesets) for automated versioning and npm publishing:

1. Detects pending changesets.
2. Bumps package versions.
3. Publishes to npm.
4. Configures a pnpm-lock.yaml merge driver to prevent lock file conflicts.

### Changelog Generation (`changelog.yml`) [#changelog-generation-changelogyml]

**Trigger:** `release` event (when a GitHub Release is published), or manual dispatch.

Uses [git-cliff](https://git-cliff.org/) with `cliff.toml` configuration to auto-generate `CHANGELOG.md` and commit it to the repository.

## Repository Maintenance [#repository-maintenance]

### Auto-Labeler (`labeler.yml`) [#auto-labeler-labeleryml]

**Trigger:** PR opened, synchronized, or reopened.

Automatically labels PRs based on file path patterns defined in `.github/labeler.yml`. Syncs labels on each push to the PR.

### Stale Issues (`stale.yml`) [#stale-issues-staleyml]

**Trigger:** Daily at 00:00 UTC (cron), or manual dispatch.

| Resource      | Stale after | Close after |
| ------------- | ----------- | ----------- |
| Issues        | 60 days     | 7 days      |
| Pull Requests | 45 days     | 14 days     |

Exempt labels: `pinned`, `security`, `critical`, `in-progress`.

### Dependabot Auto-Merge (`dependabot-auto-merge.yml`) [#dependabot-auto-merge-dependabot-auto-mergeyml]

**Trigger:** PRs on `main`/`develop` authored by `dependabot[bot]`.

* **Patch/minor updates**: Auto-approved and squash-merged.
* **Major updates**: Approved with a comment for manual review.
* Configures a pnpm-lock.yaml merge driver for conflict resolution.

### Shadcn Component Check (`shadcn-check.yml`) [#shadcn-component-check-shadcn-checkyml]

**Trigger:** Weekly on Monday at 9:00 AM UTC, or manual dispatch.

* Runs offline and online analysis of shadcn/ui components.
* Creates or updates a GitHub issue if components need review or updating.
* Uploads analysis artifacts for reference.

## Adding a New Workflow [#adding-a-new-workflow]

1. Create a new `.yml` file in `.github/workflows/`.
2. Follow the existing pattern for pnpm + Turbo setup:

```yaml
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
- uses: actions/setup-node@v4
  with:
    node-version: 20
    cache: 'pnpm'
- run: pnpm install --frozen-lockfile
```

3. Use Turbo for any build/test/lint steps to leverage caching:

```yaml
- run: pnpm turbo run build --filter=@object-ui/core
```

4. For PR workflows, consider adding path filters to avoid unnecessary runs:

```yaml
on:
  pull_request:
    paths:
      - 'packages/**'
      - 'pnpm-lock.yaml'
```

## Environment Variables and Secrets [#environment-variables-and-secrets]

| Secret / Variable | Used By                 | Purpose                            |
| ----------------- | ----------------------- | ---------------------------------- |
| `GITHUB_TOKEN`    | All workflows           | GitHub API access (automatic)      |
| `NPM_TOKEN`       | `changeset-release.yml` | npm package publishing             |
| `CODECOV_TOKEN`   | `ci.yml`                | Coverage upload to Codecov         |
| `TURBO_TOKEN`     | Build workflows         | Turbo remote cache authentication  |
| `TURBO_TEAM`      | Build workflows         | Turbo remote cache team identifier |

Secrets are configured in the repository settings under **Settings → Secrets and variables → Actions**.


# Component Registry



The Component Registry is Object UI's system for mapping schema types to React components. Understanding the registry is key to extending Object UI with custom components.

## Overview [#overview]

The registry acts as a lookup table that the `SchemaRenderer` uses to determine which React component to render for each schema type:

```
Schema Type → Component Registry → React Component
```

## Getting the Registry [#getting-the-registry]

```tsx
import { getComponentRegistry } from '@object-ui/react'

const registry = getComponentRegistry()
```

## Registering Components [#registering-components]

### Using Default Components [#using-default-components]

The easiest way to get started is to register all default components:

```tsx
import { registerDefaultRenderers } from '@object-ui/components'

// Call once at app initialization
registerDefaultRenderers()
```

This registers all built-in components like:

* Forms: `input`, `textarea`, `select`, `checkbox`, etc.
* Data: `table`, `list`, `card`, `tree`, etc.
* Layout: `page`, `grid`, `flex`, `container`, etc.
* Feedback: `alert`, `dialog`, `toast`, etc.

### Registering Individual Components [#registering-individual-components]

Register specific components one at a time:

```tsx
import { getComponentRegistry } from '@object-ui/react'
import { InputRenderer } from '@object-ui/components'

const registry = getComponentRegistry()

registry.register('input', InputRenderer)
```

### Registering Custom Components [#registering-custom-components]

Create and register your own components:

```tsx
import { getComponentRegistry } from '@object-ui/react'
import type { BaseSchema } from '@object-ui/core'

interface MyComponentSchema extends BaseSchema {
  type: 'my-component'
  title: string
  content: string
}

function MyComponent(props: MyComponentSchema) {
  return (
    <div className="my-component">
      <h3>{props.title}</h3>
      <p>{props.content}</p>
    </div>
  )
}

const registry = getComponentRegistry()
registry.register('my-component', MyComponent)
```

Now you can use it in schemas:

```json
{
  "type": "my-component",
  "title": "Hello",
  "content": "This is my custom component!"
}
```

## Component Interface [#component-interface]

All registered components receive the schema as props:

```tsx
interface ComponentProps<T extends BaseSchema = BaseSchema> {
  // The complete schema object
  schema: T
  
  // Data context (optional)
  data?: Record<string, any>
  
  // Event handlers (optional)
  onAction?: (action: any, context: any) => void
  onChange?: (value: any) => void
  onSubmit?: (data: any) => void
}

function MyRenderer(props: ComponentProps<MyComponentSchema>) {
  const { schema, data, onChange } = props
  
  return (
    <div className={schema.className}>
      {/* Your component implementation */}
    </div>
  )
}
```

## Advanced Registration [#advanced-registration]

### With Metadata [#with-metadata]

Register components with additional metadata:

```tsx
registry.register('my-component', MyComponent, {
  displayName: 'My Custom Component',
  category: 'Custom',
  icon: 'component-icon',
  description: 'A custom component for special use cases',
  schema: {
    type: 'object',
    properties: {
      title: { type: 'string' },
      content: { type: 'string' }
    }
  }
})
```

This metadata is used by the Visual Designer to provide better editing experience.

### Lazy Loading [#lazy-loading]

Register components that load on demand:

```tsx
import { lazy } from 'react'

const HeavyComponent = lazy(() => import('./HeavyComponent'))

registry.register('heavy-component', HeavyComponent, {
  lazy: true
})
```

### Overriding Built-in Components [#overriding-built-in-components]

Override default components with your own:

```tsx
import { registerDefaultRenderers } from '@object-ui/components'

// Register defaults first
registerDefaultRenderers()

// Override specific component
registry.register('button', MyCustomButton)
```

## Component Categories [#component-categories]

Default components are organized by category:

### Form Components [#form-components]

```tsx
- input
- textarea
- select
- checkbox
- radio
- switch
- slider
- date-picker
- time-picker
- file-upload
- color-picker
```

### Data Display [#data-display]

```tsx
- table
- list
- card
- tree
- timeline
- calendar
- kanban
```

### Layout [#layout]

```tsx
- page
- container
- grid
- flex
- tabs
- accordion
- divider
- spacer
```

### Feedback [#feedback]

```tsx
- alert
- toast
- dialog
- drawer
- popover
- tooltip
- progress
- skeleton
- spinner
```

### Navigation [#navigation]

```tsx
- menu
- breadcrumb
- pagination
- steps
```

### Other [#other]

```tsx
- button
- link
- text
- icon
- image
- video
- badge
- avatar
```

## Checking Registered Components [#checking-registered-components]

### Get All Registered Types [#get-all-registered-types]

```tsx
const types = registry.getRegisteredTypes()
console.log(types) // ['input', 'button', 'form', ...]
```

### Check if Type is Registered [#check-if-type-is-registered]

```tsx
if (registry.has('my-component')) {
  console.log('Component is registered')
}
```

### Get Component Metadata [#get-component-metadata]

```tsx
const metadata = registry.getMetadata('input')
console.log(metadata)
// {
//   displayName: 'Input',
//   category: 'Form',
//   icon: 'input-icon',
//   ...
// }
```

## Best Practices [#best-practices]

### 1. Register Once at App Initialization [#1-register-once-at-app-initialization]

```tsx
// main.tsx or App.tsx
import { registerDefaultRenderers } from '@object-ui/components'

registerDefaultRenderers()

function App() {
  // Your app code
}
```

### 2. Use TypeScript for Custom Components [#2-use-typescript-for-custom-components]

```tsx
import type { BaseSchema } from '@object-ui/core'

interface CustomSchema extends BaseSchema {
  type: 'custom'
  customProp: string
}

function CustomComponent(props: { schema: CustomSchema }) {
  // TypeScript ensures type safety
}
```

### 3. Follow Naming Conventions [#3-follow-naming-conventions]

Use kebab-case for component types:

* ✅ `my-component`, `custom-button`, `data-table`
* ❌ `MyComponent`, `customButton`, `DataTable`

### 4. Provide Meaningful Metadata [#4-provide-meaningful-metadata]

```tsx
registry.register('rating', RatingComponent, {
  displayName: 'Star Rating',
  category: 'Form',
  icon: 'star',
  description: 'A 5-star rating input component',
  tags: ['form', 'input', 'rating']
})
```

### 5. Handle Missing Props Gracefully [#5-handle-missing-props-gracefully]

```tsx
function MyComponent(props: ComponentProps<MySchema>) {
  const { schema } = props
  const title = schema.title || 'Default Title'
  const content = schema.content || ''
  
  return (
    <div>
      <h3>{title}</h3>
      <p>{content}</p>
    </div>
  )
}
```

## Creating Plugin Packages [#creating-plugin-packages]

Group related components into plugin packages:

```tsx
// @my-org/objectui-plugin-charts
import { getComponentRegistry } from '@object-ui/react'
import { BarChart } from './BarChart'
import { LineChart } from './LineChart'
import { PieChart } from './PieChart'

export function registerChartComponents() {
  const registry = getComponentRegistry()
  
  registry.register('bar-chart', BarChart)
  registry.register('line-chart', LineChart)
  registry.register('pie-chart', PieChart)
}
```

Usage:

```tsx
import { registerDefaultRenderers } from '@object-ui/components'
import { registerChartComponents } from '@my-org/objectui-plugin-charts'

registerDefaultRenderers()
registerChartComponents()
```

## Example: Custom Form Component [#example-custom-form-component]

Here's a complete example of a custom form component:

```tsx
import { forwardRef } from 'react'
import { getComponentRegistry } from '@object-ui/react'
import type { BaseSchema } from '@object-ui/core'
import { cn } from '@/lib/utils'

interface RatingSchema extends BaseSchema {
  type: 'rating'
  name: string
  label?: string
  maxStars?: number
  required?: boolean
  disabled?: boolean
  onChange?: (value: number) => void
}

const RatingComponent = forwardRef<HTMLDivElement, { schema: RatingSchema }>(
  ({ schema }, ref) => {
    const [value, setValue] = useState(0)
    const maxStars = schema.maxStars || 5

    const handleClick = (rating: number) => {
      if (schema.disabled) return
      setValue(rating)
      schema.onChange?.(rating)
    }

    return (
      <div ref={ref} className={cn('flex flex-col gap-2', schema.className)}>
        {schema.label && (
          <label className="text-sm font-medium">
            {schema.label}
            {schema.required && <span className="text-red-500">*</span>}
          </label>
        )}
        <div className="flex gap-1">
          {Array.from({ length: maxStars }).map((_, index) => (
            <button
              key={index}
              type="button"
              onClick={() => handleClick(index + 1)}
              disabled={schema.disabled}
              className={cn(
                'text-2xl transition-colors',
                index < value ? 'text-yellow-400' : 'text-gray-300',
                !schema.disabled && 'hover:text-yellow-300 cursor-pointer'
              )}
            >
              ★
            </button>
          ))}
        </div>
      </div>
    )
  }
)

RatingComponent.displayName = 'Rating'

// Register the component
const registry = getComponentRegistry()
registry.register('rating', RatingComponent, {
  displayName: 'Star Rating',
  category: 'Form',
  description: 'A star rating input component',
  schema: {
    type: 'object',
    properties: {
      name: { type: 'string' },
      label: { type: 'string' },
      maxStars: { type: 'number', default: 5 },
      required: { type: 'boolean' },
      disabled: { type: 'boolean' }
    },
    required: ['name']
  }
})

export { RatingComponent }
```

## Next Steps [#next-steps]

* [Expression System](./expressions.md) - Learn about dynamic expressions
* [Schema Rendering](./schema-rendering.md) - Understand the rendering engine
* [Creating Custom Components](/spec/component-package.md) - Deep dive into component creation

## Related Documentation [#related-documentation]

* [Core API](/api/core) - Component registry API
* [React API](/api/react) - React integration
* [Component Specification](/spec/component.md) - Component metadata spec


# Console Architecture



# Console Architecture [#console-architecture]

This document describes the internal architecture of the Console app (`apps/console`).

## Data Flow [#data-flow]

```
┌─────────────────────────────────────────────────────────┐
│  objectstack.config.ts                                  │
│  (defineStack → apps, objects, views)                   │
└────────────────────┬────────────────────────────────────┘
                     │ MSW / Real Server
                     ▼
┌─────────────────────────────────────────────────────────┐
│  ObjectStackAdapter  (@object-ui/data-objectstack)      │
│  • discovery() → apps[], objects[]                      │
│  • find / findOne / create / update / delete            │
│  • getView / getApp (optional metadata cache)           │
└────────────────────┬────────────────────────────────────┘
                     │ DataSource interface
                     ▼
┌─────────────────────────────────────────────────────────┐
│  SchemaRendererProvider  (@object-ui/react)              │
│  • provides dataSource + registry to all children       │
└────────────────────┬────────────────────────────────────┘
                     │ React Context
                     ▼
┌─────────────────────────────────────────────────────────┐
│  App.tsx                                                │
│  ├── ExpressionProvider  (user, app, evaluator)         │
│  ├── ConsoleLayout                                      │
│  │   ├── AppShell (@object-ui/layout)                   │
│  │   │   └── useAppShellBranding (CSS vars)             │
│  │   ├── AppSidebar (navigation tree)                   │
│  │   └── AppHeader (breadcrumbs, status)                │
│  └── Routes                                             │
│      ├── /apps/:appName/:objectName  → ObjectView       │
│      ├── /apps/:appName/:objectName/record/:id → Detail │
│      └── /apps/:appName  → Home Page                    │
└─────────────────────────────────────────────────────────┘
```

## Routing [#routing]

The console uses React Router DOM v7 with a simple flat route structure:

| Route Pattern                                 | Component          | Purpose                                                                                              |
| --------------------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------- |
| `/apps/:appName`                              | Home redirect      | Redirects to the first object in navigation                                                          |
| `/apps/:appName/:objectName`                  | `ObjectView`       | Object list with view switcher                                                                       |
| `/apps/:appName/:objectName/view/:viewId`     | `ObjectView`       | Specific view for an object                                                                          |
| `/apps/:appName/:objectName/data`             | `ObjectDataPage`   | Bare data surface — URL `filter[<field>]=<value>` conditions, not bound to any saved view (ADR-0055) |
| `/apps/:appName/:objectName/record/:recordId` | `RecordDetailView` | Single-record detail                                                                                 |
| `/apps/:appName/create-app`                   | `CreateAppPage`    | App creation wizard (4-step)                                                                         |
| `/apps/:appName/edit-app/:editAppName`        | `EditAppPage`      | Edit existing app configuration                                                                      |

## Key Patterns [#key-patterns]

### 1. Expression-Based Visibility [#1-expression-based-visibility]

Navigation items can be conditionally hidden using expressions:

```json
{
  "type": "object",
  "objectName": "admin_settings",
  "visible": "${user.role === 'admin'}"
}
```

The `ExpressionProvider` wraps the layout and provides an `ExpressionEvaluator` that resolves `${}` templates against context variables (`user`, `app`, `data`).

### 2. Action System [#2-action-system]

Actions are typed with `ActionDef` from `@object-ui/core`:

```ts
const { execute } = useActionRunner({
  context: { objectName: 'contacts' },
});

await execute({
  type: 'delete',
  confirmText: 'Are you sure?',
  params: { recordId: '123' },
});
```

The `ActionRunner` supports:

* **Confirmation** — async `ConfirmationHandler` (default: `window.confirm`, override with Shadcn AlertDialog)
* **Toast notifications** — `ToastHandler` for success/error messages
* **Custom handlers** — register domain-specific action types (e.g., `'create'`, `'delete'`, `'refresh'`)

### 3. Plugin ObjectView Delegation [#3-plugin-objectview-delegation]

The console's `ObjectView` is a **thin wrapper** around `@object-ui/plugin-view`'s `ObjectView`:

* Resolves views from the object definition's `list_views`
* Passes a `renderListView` callback for multi-view rendering (kanban, calendar, chart)
* Handles console-specific concerns: URL routing, MetadataInspector, record detail Sheet

### 4. App Creation & Editing [#4-app-creation--editing]

The console integrates the `AppCreationWizard` from `@object-ui/plugin-designer` for creating and editing apps:

* **Create App** — `CreateAppPage` at `/apps/:appName/create-app`. Passes metadata objects as `availableObjects`, handles `onComplete` (converts draft via `wizardDraftToAppSchema()`, navigates to new app), `onCancel` (navigate back), and `onSaveDraft` (localStorage persistence).
* **Edit App** — `EditAppPage` at `/apps/:appName/edit-app/:editAppName`. Loads existing app config as `initialDraft` and updates on completion.

**Entry Points:**

* AppSidebar app switcher → "Add App" / "Edit App" buttons
* CommandPalette (⌘+K) → "Create New App" command in Actions group
* Empty state CTA → "Create Your First App" button when no apps are configured

### 5. Branding [#5-branding]

Per-app branding is applied via `AppShell`'s `branding` prop:

```tsx
<AppShell branding={{
  primaryColor: '#3B82F6',
  accentColor: '#10B981',
  favicon: '/custom-favicon.ico',
  title: 'CRM — ObjectStack Console',
}}>
```

This sets CSS custom properties (`--brand-primary`, `--brand-primary-hsl`, etc.) on the document root.

## MSW Mock Mode [#msw-mock-mode]

In development, the console uses MSW (Mock Service Worker) to simulate an ObjectStack backend:

1. `objectstack.config.ts` defines apps and objects via `@objectstack/spec`
2. `@objectstack/runtime` boots an `ObjectKernel` with `MSWPlugin`
3. MSW intercepts `/api/v1/*` requests and serves in-memory data
4. The `ObjectStackAdapter` connects to this mock server transparently

This allows full offline development without a real backend.


# Console App



# ObjectStack Console [#objectstack-console]

The **Console** is the reference application for [ObjectUI](/docs/guide). It renders a full-featured admin interface from JSON metadata — objects, views, dashboards, and actions — with zero custom pages required.

## Quick Start [#quick-start]

```bash
# From the repository root
pnpm install
pnpm console        # starts the dev server (Vite)
```

The console opens at &#x2A;*[http://localhost:5175](http://localhost:5175)** with MSW (Mock Service Worker) providing a simulated backend.

## Key Features [#key-features]

| Feature                   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Multi-App Switcher**    | Switch between apps defined in `objectstack.config.ts`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| **Dynamic Navigation**    | Sidebar renders from the app's `navigation` tree (objects, groups, URLs, pages).                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| **Object Views**          | List / Grid / Kanban / Calendar — backed by `@object-ui/plugin-view`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **CRUD Dialogs**          | Create & edit records via schema-driven forms.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| **Expression Visibility** | Show/hide navigation items using `visible: "${data.role === 'admin'}"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| **Branding**              | Per-app colors, favicons, and logos via `AppShell` branding.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| **Command Palette**       | `⌘+K` opens a searchable command bar for quick navigation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| **Studio Package Scope**  | Studio home, metadata counts, quick-create links, and diagnostics follow the selected package.                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| **Design in Studio**      | Workspace admins get a top-bar entry inside a running app that opens its owning package on the Studio design surface. On an interface route — a dashboard, page, or report — it deep-links straight to that surface's design page in the Interfaces pillar (`/studio/:packageId/interfaces?surface=<type>:<name>`, e.g. `surface=page:showcase_crm_workbench`); elsewhere (objects, the app root) it opens the package's Data tab (`/studio/:packageId/data`). These interfaces are authored in Studio — there is no in-page edit panel. |
| **App Creation Wizard**   | 4-step wizard (Basic Info → Objects → Navigation → Branding) to create or edit apps.                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| **Error Boundary**        | Graceful error handling with a retry button.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

### Object design (Studio Data tab) [#object-design-studio-data-tab]

Selecting an object in Studio's **Data** pillar (`/studio/:packageId/data`) opens a
tab strip over that object — **Records · Form · Validations · Hooks · Actions ·
API · Settings**. Each of Validations, Hooks and Actions is a no-code **config
panel driven by the corresponding metadata**, and each supports **adding** new
entries — no code round-trip required:

| Tab             | Edits                                                             | Panel                                                                                                                                                                                                                                                                                                                                  |
| --------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Validations** | the object's inline `validations[]` (spec `ValidationRuleSchema`) | Master-detail covering **every** rule type — `script`, `cross_field`, `state_machine`, `format`, `json_schema`, `conditional`. The **New** menu adds any type (seeded with a valid, never-firing skeleton); a rule's type can be switched in place. CEL predicates reuse the shared `ConditionBuilder`, fed the object's draft fields. |
| **Hooks**       | the separate `hook` metadata type targeting this object           | Master-detail whose editor is the platform `SchemaForm` &#x2A;*driven by the live `hook` JSONSchema from `/meta/types`**, so its fields and enums always match the running server's contract.                                                                                                                                          |
| **Actions**     | the object's inline `actions[]` (spec `ActionSchema`)             | Master-detail using the type-aware `ActionDefaultInspector&#x60;; anything not curated falls through to a &#x2A;*"More fields"** form fed the live `action` JSONSchema, so no spec property is un-editable.                                                                                                                            |

Validations and Actions persist with the object's own **Save draft**; Hooks (a
distinct metadata type) save per-hook. Nothing goes live until the package is
published from the top-bar **Publish** flow.

## Configuration [#configuration]

The console reads its configuration from `objectstack.config.ts`:

```ts
import { defineStack } from '@objectstack/spec';
import { ObjectSchema, App, Field } from '@objectstack/spec';

export default defineStack({
  apps: [
    App.create({
      name: 'crm',
      label: 'CRM',
      icon: 'briefcase',
      navigation: [
        { type: 'object', objectName: 'contacts', label: 'Contacts', icon: 'users' },
        { type: 'object', objectName: 'deals', label: 'Deals', icon: 'dollar-sign' },
      ],
      branding: { primaryColor: '#3B82F6' },
    }),
  ],
  objects: [
    ObjectSchema.create({
      name: 'contacts',
      label: 'Contacts',
      fields: [
        Field.text('name', { label: 'Name', required: true }),
        Field.email('email', { label: 'Email' }),
      ],
    }),
  ],
});
```

## Running with a Real Backend [#running-with-a-real-backend]

To connect to a real ObjectStack server instead of MSW:

1. Set the `VITE_API_URL` environment variable:
   ```bash
   VITE_API_URL=http://localhost:3000 pnpm console
   ```
2. The console will use the ObjectStack client to discover metadata and perform CRUD operations against the server.

## Folder Structure [#folder-structure]

```
apps/console/
  src/
    App.tsx                    # Root component + routing
    dataSource.ts              # ObjectStackAdapter wrapper
    components/
      AppHeader.tsx            # Top navbar (breadcrumbs, connection status)
      AppSidebar.tsx           # Left sidebar (app switcher, navigation tree)
      CommandPalette.tsx       # ⌘+K command bar
      ConsoleLayout.tsx        # AppShell wrapper
      ObjectView.tsx           # Object list view (wraps plugin-view)
      RecordDetailView.tsx     # Single-record detail view
    pages/
      CreateAppPage.tsx        # App creation wizard page
      EditAppPage.tsx          # Edit existing app page
    context/
      ExpressionProvider.tsx   # Expression evaluation context
    hooks/
      useBranding.ts           # Delegates to @object-ui/layout
      useObjectActions.ts      # CRUD action handlers
    mocks/
      browser.ts               # MSW browser worker
```

## See Also [#see-also]

* [Console Architecture](/docs/guide/console-architecture) — data flow, routing, and plugin integration
* [Schema Overview](/docs/guide/schema-overview) — the JSON protocol that drives the console
* [Data Source](/docs/guide/data-source) — how the adapter fetches and caches data


# Dashboard-Level Filters









A dashboard often needs one top-level filter — a date range, a region select —
that drives **several charts at once**. ObjectUI models this as a
**dashboard-level parameter**, not a shared dataset:

* The **filter control and its value live on the dashboard** — hosted as
  dashboard-level variables (the page/dashboard variables primitive).
* Each widget declares which of **its own** fields a filter binds to via
  `filterBindings` — a small mapping, not a copied query.
* At render time the dashboard **broadcasts** the active values into every
  bound widget's inline query, `AND`-combined with the widget's own `filter`.

Charts stay inline and self-contained; one place owns the filter; each chart
edit stays local.

> Working examples: the schema catalog ships a `plugin-dashboard/filtered-dashboard`
> example plus variants for dynamic options, text/number/lookup filter types,
> dataset widgets, the `targetWidgets` allow-list, and date presets with a
> custom range.

## Tutorial: from zero to a filtered dashboard [#tutorial-from-zero-to-a-filtered-dashboard]

### Step 1 — a plain dashboard [#step-1--a-plain-dashboard]

Start from two charts over **different** objects. Without filters they always
show everything:

```json
{
  "type": "dashboard",
  "columns": 2,
  "widgets": [
    {
      "id": "invoices_by_status",
      "title": "Invoices by Status",
      "type": "bar",
      "object": "invoices",
      "categoryField": "status",
      "aggregate": "count"
    },
    {
      "id": "accounts_signed",
      "title": "Accounts Signed",
      "type": "line",
      "object": "accounts",
      "categoryField": "signed_at",
      "categoryGranularity": "month",
      "aggregate": "count"
    }
  ]
}
```

### Step 2 — add the built-in date range [#step-2--add-the-built-in-date-range]

Declare `dateRange` at the dashboard level. A preset/custom date-range control
appears in the filter bar above the widgets:

```json
{
  "dateRange": {
    "field": "created_at",
    "defaultRange": "last_30_days",
    "allowCustomRange": true
  }
}
```

* `field` — the **default** field the range applies to on every bound widget
  (falls back to `created_at` when omitted).
* `defaultRange` — the initially selected preset: `today`, `yesterday`,
  `this_week`, `last_week`, `this_month`, `last_month`, `this_quarter`,
  `last_quarter`, `this_year`, `last_year`, `last_7_days`, `last_30_days`,
  `last_90_days`, or `custom` (starts empty and lets the user pick).
* `allowCustomRange` — offer a "Custom…" item that opens a from/to calendar
  (default `true`).

Presets stay **symbolic** until query time: they compile to date-macro tokens
(`{30_days_ago}`, `{current_month_start}`, …) that each widget resolves
exactly like hand-authored widget filters — so a dashboard saved today still
means "last 30 days" tomorrow.

### Step 3 — add a global filter [#step-3--add-a-global-filter]

Add a `globalFilters` entry. Each entry renders one control in the filter bar:

```json
{
  "globalFilters": [
    {
      "name": "region",
      "field": "region",
      "label": "Region",
      "type": "select",
      "options": ["EMEA", "APAC", "AMER"]
    }
  ]
}
```

* `name` — the **stable filter name**: the variable key the value is published
  under, and the key widgets reference in `filterBindings`. Defaults to
  `field`. (`"dateRange"` is reserved for the built-in date range.)
* `field` — the default field the filter applies to on bound widgets.
* `type` — the control type: `text`, `number`, `select`, `lookup`, or `date`.

| Type                | Control             | Generated condition                       |
| ------------------- | ------------------- | ----------------------------------------- |
| `text`              | input               | `{ field: { "$contains": value } }`       |
| `number`            | numeric input       | `{ field: value }` (equality)             |
| `select` / `lookup` | dropdown            | `{ field: value }` (or `$in` for arrays)  |
| `date`              | preset/custom range | `{ field: { "$gte": from, "$lte": to } }` |

Static `options` accept the `@objectstack/spec` object form
(`{ "value": "amer", "label": "AMER" }` — canonical, and what the spec
validates) or a bare-string shorthand (`["EMEA", "APAC"]`); the runtime
normalizes both to value/label pairs. Options can also be fetched from an
object at runtime:

```json
{
  "name": "industry",
  "field": "industry",
  "label": "Industry",
  "type": "select",
  "optionsFrom": {
    "object": "accounts",
    "valueField": "industry",
    "labelField": "industry"
  }
}
```

With a dataset-capable data source, `optionsFrom` resolves distinct values
**server-side** (a GROUP BY over the source object), so the option list is
complete regardless of row count. Data sources without dataset queries fall
back to a best-effort client-side dedupe over the first 200 records.

### Step 4 — bind each widget's own fields [#step-4--bind-each-widgets-own-fields]

By default every filter applies to its own `field` on every widget. When a
widget stores the concept under a different field — or should ignore a filter
— declare `filterBindings` on the widget:

```json
{
  "widgets": [
    {
      "id": "invoices_by_status",
      "type": "bar",
      "object": "invoices",
      "categoryField": "status",
      "aggregate": "count"
    },
    {
      "id": "accounts_signed",
      "type": "line",
      "object": "accounts",
      "categoryField": "signed_at",
      "categoryGranularity": "month",
      "aggregate": "count",
      "filterBindings": { "dateRange": "signed_at", "region": "sales_region" }
    },
    {
      "id": "total_invoices",
      "title": "Total Invoices (all regions)",
      "type": "metric",
      "object": "invoices",
      "aggregate": "count",
      "filterBindings": { "region": false }
    }
  ]
}
```

Binding rules, in precedence order:

1. `filterBindings[name]` as a **string** — apply the filter to that field.
2. `filterBindings[name]: false` — opt this widget out of that filter.
3. Legacy `targetWidgets` on the filter — when set, only listed widget ids get
   the default binding (an explicit `filterBindings` entry still wins).
4. Otherwise the filter applies to its own `field` (the built-in date range
   defaults to `dateRange.field ?? 'created_at'`).

That's the whole feature: changing any filter live re-scopes every bound
widget, each against **its own** field. Here it is running in the showcase
app's *Revenue Pulse* dashboard — the date range's default field is the
invoice `issued_on`, account widgets re-map it to `signed_on`, and the
"Accounts (all time)" KPI opts out of both filters:

<img alt="Revenue Pulse — dashboard-level date + region filters over two objects" src="__img0" />

Selecting **EMEA** re-scopes every bound widget live (invoices via their own
`region`, accounts via `sales_region`), while the opted-out KPI holds steady —
and a Reset button appears once any filter deviates from its default:

<img alt="Revenue Pulse re-scoped to EMEA — bound widgets update, the opted-out KPI holds" src="__img1" />

Bindings can also be edited visually: the Studio dashboard widget inspector
shows a **Dashboard filter bindings** section (one row per declared filter)
with an Apply toggle (opt-out) and a field picker for the override — no JSON
editing required.

<img alt="The widget inspector's Dashboard filter bindings section" src="__img2" />

## Reading filter values in expressions [#reading-filter-values-in-expressions]

Filter values are hosted as dashboard variables, so any widget expression can
read them under the `page.` scope, keyed by the filter's `name`:

```json
{
  "type": "text",
  "value": "Region: ${page.region || 'All'}"
}
```

```json
{
  "id": "emea_playbook",
  "component": {
    "type": "card",
    "title": "EMEA Playbook",
    "hidden": "${page.region !== 'EMEA'}"
  }
}
```

The built-in date range is an object under `page.dateRange` — a preset selection
is `{ "preset": "last_30_days" }`, a custom range is
`{ "from": "2026-01-01", "to": "2026-03-31" }` (either bound may be absent).

## Dataset widgets [#dataset-widgets]

Widgets bound to a semantic-layer `dataset` participate the same way: the
dashboard merges the scoped filter into the widget's `filter`, which the
dataset widget forwards to the dataset query as `runtimeFilter`. Inline
(`object`-based) and dataset-bound widgets can mix freely on one filtered
dashboard.

## Nested variable scopes [#nested-variable-scopes]

When a filtered dashboard is embedded inside a Page that declares its own
`variables`, the two scopes **merge**: inside the dashboard subtree, `page.*`
resolves the outer Page's variables plus the dashboard's filter values, and a
dashboard filter only shadows an outer variable that has the **same name**.
Writes route to the scope that defines the variable — setting an outer-page
variable from inside the dashboard updates the outer scope, so both subtrees
stay in sync.

## Known limitations [#known-limitations]

* **Static-data widgets are not filtered** — a widget with an inline `data`
  array has no query to scope, so dashboard filters do not apply to it. Bind
  the widget to an `object` (or a `dataset`) if it should respond to filters.
* **Default bindings are metadata-checked for `object` widgets only** — when
  a filter's default `field` does not exist on an inline widget's object, the
  binding is skipped with a console warning instead of issuing a query that
  matches nothing. Dataset-bound widgets can't be checked this way (the
  dashboard doesn't know the dataset's base-object fields), so map their
  filters explicitly with `filterBindings: { "<name>": "<field>" }` or opt
  out with `false`. Explicit string bindings are always honoured as written —
  a typo shows up as a visibly empty widget rather than a silently dropped
  filter.

## i18n [#i18n]

The filter bar's strings resolve from the `dashboard.filters.*` keys
(`@object-ui/i18n` ships `en` and `zh` entries — control labels come from each
filter's `label`, so translate those in your schema metadata).

## Spec alignment [#spec-alignment]

`DashboardSchema.dateRange`, `GlobalFilterSchema` (including `name`) and
`DashboardWidgetSchema.filterBindings` are part of `@objectstack/spec`
(framework#2501). Author dashboards against the spec shapes; ObjectUI renders
them.


# Data Connectivity



ObjectUI follows the **Universal Adapter Pattern**. UI components do not hardcode transport details. They receive a `DataSource` implementation from `SchemaRendererProvider` and call a stable CRUD/query contract.

This keeps the renderer backend-agnostic: ObjectStack, REST, GraphQL, and proprietary backends can all be adapted behind the same interface.

## The Interface [#the-interface]

The canonical interface lives in `@object-ui/types`:

```typescript
import type { QueryParams, QueryResult } from '@object-ui/types';

export interface DataSource<T = unknown> {
  find(resource: string, params?: QueryParams): Promise<QueryResult<T>>;
  findOne(resource: string, id: string | number, params?: QueryParams): Promise<T | null>;
  create(resource: string, data: Partial<T>): Promise<T>;
  update(
    resource: string,
    id: string | number,
    data: Partial<T>,
    opts?: { ifMatch?: string },
  ): Promise<T>;
  delete(
    resource: string,
    id: string | number,
    opts?: { ifMatch?: string },
  ): Promise<boolean>;

  getObjectSchema(objectName: string): Promise<unknown>;
}
```

`find()` returns a `QueryResult<T>` so components can receive both rows and pagination metadata:

```typescript
interface QueryResult<T = unknown> {
  data: T[];
  total?: number;
  page?: number;
  pageSize?: number;
  hasMore?: boolean;
  cursor?: string;
  metadata?: Record<string, unknown>;
}
```

## Available Adapters [#available-adapters]

### ObjectStack Adapter (Official) [#objectstack-adapter-official]

Use `@object-ui/data-objectstack` for ObjectStack-compatible backends.

```bash
pnpm add @object-ui/data-objectstack
```

```typescript
import { createObjectStackAdapter } from '@object-ui/data-objectstack';

const dataSource = createObjectStackAdapter({
  baseUrl: 'https://api.your-instance.com'
});
```

## Usage [#usage]

Inject the data source at the renderer boundary:

```tsx
import '@object-ui/components';
import '@object-ui/fields';
import { SchemaRenderer, SchemaRendererProvider } from '@object-ui/react';
import { createObjectStackAdapter } from '@object-ui/data-objectstack';

const dataSource = createObjectStackAdapter({
  baseUrl: 'https://api.example.com'
});

function App() {
  return (
    <SchemaRendererProvider dataSource={dataSource}>
      <SchemaRenderer schema={mySchema} />
    </SchemaRendererProvider>
  );
}
```

## Creating a Custom Adapter [#creating-a-custom-adapter]

If you have a proprietary backend, wrap its SDK or client in a `DataSource` implementation. Keep transport details in the adapter, not in renderers.

```typescript
import type { DataSource, QueryParams, QueryResult } from '@object-ui/types';

type User = {
  id: string;
  name: string;
  email: string;
};

type BackendClient = {
  listUsers(params?: QueryParams): Promise<{ rows: User[]; total?: number }>;
  getUser(id: string | number): Promise<User | null>;
  createUser(data: Partial<User>): Promise<User>;
  updateUser(id: string | number, data: Partial<User>): Promise<User>;
  deleteUser(id: string | number): Promise<boolean>;
  describeObject(name: string): Promise<unknown>;
};

class UserDataSource implements DataSource<User> {
  constructor(private readonly client: BackendClient) {}

  async find(resource: string, params?: QueryParams): Promise<QueryResult<User>> {
    if (resource !== 'users') {
      return { data: [], total: 0 };
    }

    const result = await this.client.listUsers(params);
    return {
      data: result.rows,
      total: result.total,
    };
  }

  findOne(_resource: string, id: string | number): Promise<User | null> {
    return this.client.getUser(id);
  }

  create(_resource: string, data: Partial<User>): Promise<User> {
    return this.client.createUser(data);
  }

  update(_resource: string, id: string | number, data: Partial<User>): Promise<User> {
    return this.client.updateUser(id, data);
  }

  delete(_resource: string, id: string | number): Promise<boolean> {
    return this.client.deleteUser(id);
  }

  getObjectSchema(objectName: string): Promise<unknown> {
    return this.client.describeObject(objectName);
  }
}
```

## Query Parameters [#query-parameters]

ObjectUI uses OData-style query keys for broad compatibility:

```typescript
await dataSource.find('users', {
  $select: ['id', 'name', 'email'],
  $filter: { status: 'active' },
  $orderby: { name: 'asc' },
  $skip: 0,
  $top: 25,
  $count: true,
});
```

Data-aware plugins may also use optional methods such as `bulkUpdate`, `bulkDelete`, `getView`, or `listViewOverrides` when an adapter supports them. Keep the required CRUD methods implemented first, then add optional capabilities as your UI needs them.


# Deployment



# Deployment [#deployment]

ObjectUI apps are standard Vite + React applications, so they can be deployed anywhere that serves static files or runs Node.js containers. This guide provides copy-paste-ready configurations for the most popular platforms.

## Prerequisites [#prerequisites]

* A production build: `pnpm build` (runs `turbo run build` across all packages)
* The build output lives in `apps/console/dist/` (or your app's `dist/` folder)
* Environment variables configured for your target environment

## Docker [#docker]

Create a multi-stage `Dockerfile` at the project root:

```dockerfile
# Stage 1: Build
FROM node:20-alpine AS builder
RUN corepack enable && corepack prepare pnpm@9 --activate
WORKDIR /app

COPY pnpm-lock.yaml pnpm-workspace.yaml package.json ./
COPY packages/ packages/
COPY apps/ apps/
RUN pnpm install --frozen-lockfile
RUN pnpm build

# Stage 2: Serve
FROM nginx:alpine AS runner
COPY --from=builder /app/apps/console/dist /usr/share/nginx/html
COPY <<'EOF' /etc/nginx/conf.d/default.conf
server {
    listen 80;
    root /usr/share/nginx/html;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff2?)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml;
}
EOF

EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
```

Build and run:

```bash
docker build -t objectui-app .
docker run -p 3000:80 objectui-app
```

## Vercel [#vercel]

Create `vercel.json` in the project root:

```json
{
  "buildCommand": "pnpm build",
  "outputDirectory": "apps/console/dist",
  "installCommand": "pnpm install --frozen-lockfile",
  "framework": "vite",
  "rewrites": [
    { "source": "/(.*)", "destination": "/index.html" }
  ],
  "headers": [
    {
      "source": "/assets/(.*)",
      "headers": [
        { "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }
      ]
    }
  ]
}
```

Deploy with the Vercel CLI:

```bash
npx vercel --prod
```

> **Note:** Set the **Root Directory** to the repository root so the monorepo workspace resolves correctly.

## Railway [#railway]

Create `railway.json` in the project root:

```json
{
  "$schema": "https://railway.com/railway.schema.json",
  "build": {
    "builder": "NIXPACKS",
    "buildCommand": "corepack enable && pnpm install --frozen-lockfile && pnpm build"
  },
  "deploy": {
    "startCommand": "npx serve apps/console/dist -s -l tcp://0.0.0.0:$PORT",
    "healthcheckPath": "/",
    "restartPolicyType": "ON_FAILURE",
    "restartPolicyMaxRetries": 3
  }
}
```

Push to your linked Railway project:

```bash
railway up
```

## Netlify [#netlify]

Create `netlify.toml` in the project root:

```toml
[build]
  command = "pnpm install --frozen-lockfile && pnpm build"
  publish = "apps/console/dist"

[build.environment]
  NODE_VERSION = "20"
  PNPM_VERSION = "9"

# SPA fallback — redirect all routes to index.html
[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

[[headers]]
  for = "/assets/*"
  [headers.values]
    Cache-Control = "public, max-age=31536000, immutable"
```

Deploy with the Netlify CLI:

```bash
npx netlify deploy --prod
```

## Environment Variables [#environment-variables]

ObjectUI uses Vite's `import.meta.env` for build-time configuration. Prefix all custom variables with `VITE_`.

| Variable               | Default         | Description                                                                                               |
| ---------------------- | --------------- | --------------------------------------------------------------------------------------------------------- |
| `VITE_USE_MOCK_SERVER` | `"true"`        | Enable MSW mock server for local development. Set to `"false"` for production builds that hit a real API. |
| `VITE_API_URL`         | —               | Base URL for the ObjectStack API (e.g. `https://api.example.com`).                                        |
| `NODE_ENV`             | `"development"` | Set automatically to `"production"` by `vite build`.                                                      |

Create a `.env.production` file for production defaults:

```bash
VITE_USE_MOCK_SERVER=false
VITE_API_URL=https://api.example.com
```

For platform-specific configuration, set environment variables in each platform's dashboard or CLI:

```bash
# Vercel
vercel env add VITE_API_URL production

# Railway
railway variables set VITE_API_URL=https://api.example.com

# Netlify
netlify env:set VITE_API_URL https://api.example.com
```

> **Tip:** The console app ships with MSW enabled by default. Always set `VITE_USE_MOCK_SERVER=false` in production to disable the mock service worker.

## Build Optimization [#build-optimization]

### Gzip and Brotli Compression [#gzip-and-brotli-compression]

Add the `vite-plugin-compression` plugin for pre-compressed assets:

```bash
pnpm add -D vite-plugin-compression
```

```ts
// vite.config.ts
import compression from 'vite-plugin-compression';

export default defineConfig({
  plugins: [
    react(),
    tailwindcss(),
    compression({ algorithm: 'gzip' }),       // .gz files
    compression({ algorithm: 'brotliCompress', ext: '.br' }),  // .br files
  ],
});
```

### Code Splitting [#code-splitting]

Vite splits chunks automatically. For ObjectUI plugins, use dynamic imports to keep the initial bundle small:

```tsx
import { createLazyPlugin } from '@object-ui/react';

const ObjectGrid = createLazyPlugin(
  () => import('@object-ui/plugin-grid'),
  { fallback: <div>Loading grid...</div> }
);
```

### Bundle Analysis [#bundle-analysis]

Visualize your bundle to find optimization opportunities:

```bash
pnpm add -D rollup-plugin-visualizer
```

```ts
// vite.config.ts
import { visualizer } from 'rollup-plugin-visualizer';

export default defineConfig({
  plugins: [
    react(),
    tailwindcss(),
    visualizer({ open: true, gzipSize: true }),
  ],
});
```

### Production Build Command [#production-build-command]

Build without the mock server and verify the output:

```bash
VITE_USE_MOCK_SERVER=false pnpm build
```

This is equivalent to the `build:server` script defined in the console app.

## Health Checks [#health-checks]

For containerized deployments, add a lightweight health check endpoint. Create `public/health.json` in your app:

```json
{ "status": "ok" }
```

This file is copied to the build output as-is by Vite. Point your health check to `/health.json`:

```dockerfile
# Docker HEALTHCHECK
HEALTHCHECK --interval=30s --timeout=3s --retries=3 \
  CMD wget -qO- http://localhost:80/health.json || exit 1
```

```json
// railway.json (excerpt)
{
  "deploy": {
    "healthcheckPath": "/health.json"
  }
}
```

For platforms that expect an HTTP 200 on `/`, the SPA `index.html` fallback already handles this.

## Next Steps [#next-steps]

* [CI/CD Pipeline](/docs/guide/ci-cd-pipeline) — Understand the automated build and release workflows
* [Architecture Overview](/docs/guide/architecture) — How ObjectUI packages fit together
* [Quick Start](/docs/guide/quick-start) — Set up a new ObjectUI project from scratch
* [Theming](/docs/guide/theming) — Customize the look-and-feel before deploying


# Designing App Navigation



# Designing App Navigation [#designing-app-navigation]

When you compose an app, the same requirement can often be expressed three
ways: a plain object menu entry, an object entry pinned to a named view, or a
custom page that embeds views. They are **not** interchangeable — this guide
gives you the decision rules. (The canonical, agent-facing version lives in
`skills/objectui/guides/app-composition.md`; keep the two in sync.)

## The Three Ways to Reach a List [#the-three-ways-to-reach-a-list]

Say your app has a `project` object:

| You write                                                                        | User lands on                                                               | You get for free                                                                                                                                                                                                            |
| -------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `{ "type": "object", "objectName": "project" }`                                  | `/apps/my_app/project` — the object's **default view**                      | The full object shell: view switcher, object actions, a create button, record detail routing, search and recent-items integration                                                                                           |
| `{ "type": "object", "objectName": "project", "viewName": "project.by_status" }` | `/apps/my_app/project/view/project.by_status`                               | The same shell, with the entry **anchored** to a named view — users can still switch                                                                                                                                        |
| `{ "type": "object", "objectName": "project", "filters": { "status": "open" } }` | `/apps/my_app/project/data?filter[status]=open` — the **bare data surface** | URL-defined conditions over everything permissions allow, bound to **no saved view**. Conditions show as removable chips; the full filter/sort/group toolbar is available; "Save as view" turns the slice into a named view |
| `{ "type": "page", "pageName": "project_overview" }`                             | `/apps/my_app/page/project_overview`                                        | Nothing but your page schema. View switching, actions, and record links must be assembled by hand                                                                                                                           |

The key asymmetry: a page can imitate the other two, but it **loses the object
shell** — and every future improvement to that shell (new actions, better view
switching, permission trimming) will skip your page.

## The Rule of Least Power [#the-rule-of-least-power]

Use the least powerful construct that expresses the requirement:

1. **Default: one plain `object` entry per core business object.**
   No `viewName`. The default view is defined by view metadata, so the
   navigation layer stays decoupled from presentation.

2. **Add `viewName` when the menu item is a named slice.**
   If the label is a *perspective* — "By Status", "Due This Week",
   "My Tasks" — create a named view (convention: `<object>.<key>`, e.g.
   `project.by_status`) and anchor the entry to it. `viewName` sets the
   entry point; it does not lock the user in.

3. **Use `filters` for one-off or parameterized slices.**
   A dashboard drill-through, a shared link, "records assigned to me" — put
   the condition in the URL (`filters: { "owner_id": "{current_user_id}" }`)
   and let it land on the bare data surface instead of authoring a view.
   Promote the slice to a named view only when it's curated and reused.
   Note the surface is not a security feature: it shows exactly what
   row-level permissions already allow.

4. **Create a page only for composition a single object view cannot express.**
   Multiple objects side by side or in tabs, KPI cards mixed with lists,
   onboarding or static content, parameterized pages. A page that wraps a
   single object's single view is an anti-pattern.

5. **Use `dashboard` for metric/chart aggregation and `report` for tabular
   analysis** — don't rebuild them as pages of chart blocks.

6. **One entry per target.** Don't offer the same object through both a plain
   entry and a page that wraps its default view. If one object needs several
   menu entries, make all of them named-view entries — mixing styles breaks
   active-state highlighting in the sidebar.

As a rule of thumb, in a typical business app about 80% of navigation entries
should be `object` entries (with or without `viewName`); pages are for the
home screen, onboarding, and cross-object workbenches.

## Write Spec-Shaped Items [#write-spec-shaped-items]

Navigation is a discriminated union on `type`. Each type has its own target
field — there is no generic `path` and no `kind`:

```json
{
  "navigation": [
    { "id": "nav_projects", "type": "object", "objectName": "project", "label": "Projects" },
    { "id": "nav_by_status", "type": "object", "objectName": "project", "viewName": "project.by_status", "label": "By Status" },
    { "id": "nav_my_open", "type": "object", "objectName": "project", "filters": { "owner_id": "{current_user_id}", "status": "open" }, "label": "My Open Projects" },
    { "id": "nav_kpis", "type": "dashboard", "dashboardName": "company_kpis", "label": "KPIs" },
    { "id": "nav_workbench", "type": "page", "pageName": "cross_object_workbench", "label": "Workbench" },
    { "id": "nav_docs", "type": "url", "url": "https://docs.example.com", "target": "_blank", "label": "Docs" }
  ]
}
```

Requirements:

* `id` (snake\_case), `type`, and `label` are mandatory on every item.
* The target field must match the type: `objectName`, `pageName`,
  `dashboardName`, `reportName`, or `url`. Keys like `path` or `kind` are
  ignored at runtime and rejected at save.
* Put items under the `navigation` key. `menu` is deprecated legacy and only
  kept for backward compatibility.

Object entries also support record deep-links — `recordId` (with template
variables like `{current_user_id}`) opens a specific record, which is how
"My Profile"-style entries are built.

## Quick Checklist [#quick-checklist]

Before publishing an app, scan the navigation for:

* Pages that merely wrap a single object view → replace with an object entry.
* Items carrying `path`/`kind` → rewrite as typed items.
* The same object reachable twice (plain entry + wrapper page) → keep one.
* View names not following `<object>.<key>`, ids not snake\_case → rename.


# Expression System



Object UI includes a powerful expression system that enables dynamic, data-driven UIs. Expressions allow you to reference data, compute values, and create conditional logic directly in your JSON schemas.

## Overview [#overview]

Expressions are JavaScript-like code snippets embedded in schemas using the `${}` syntax:

```json
{
  "type": "text",
  "value": "Hello, ${user.name}!"
}
```

With data:

```tsx
const data = { user: { name: "Alice" } }
```

This renders: &#x2A;*"Hello, Alice!"**

## Basic Syntax [#basic-syntax]

### Simple Property Access [#simple-property-access]

Access data properties using dot notation:

```json
{
  "type": "text",
  "value": "${user.firstName}"
}
```

### Nested Properties [#nested-properties]

Access nested objects:

```json
{
  "type": "text",
  "value": "${user.address.city}"
}
```

### Array Access [#array-access]

Access array elements:

```json
{
  "type": "text",
  "value": "${users[0].name}"
}
```

### String Interpolation [#string-interpolation]

Mix expressions with static text:

```json
{
  "type": "text",
  "value": "Welcome, ${user.firstName} ${user.lastName}!"
}
```

## Operators [#operators]

### Arithmetic Operators [#arithmetic-operators]

```json
{
  "type": "text",
  "value": "Total: ${price * quantity}"
}
```

Supported: `+`, `-`, `*`, `/`, `%`

### Comparison Operators [#comparison-operators]

```json
{
  "type": "badge",
  "variant": "${score >= 90 ? 'success' : 'default'}"
}
```

Supported: `>`, `<`, `>=`, `<=`, `==`, `===`, `!=`, `!==`

### Logical Operators [#logical-operators]

```json
{
  "type": "button",
  "visibleOn": "${user.isAdmin && user.isActive}"
}
```

Supported: `&&`, `||`, `!`

### Ternary Operator [#ternary-operator]

```json
{
  "type": "text",
  "value": "${count > 0 ? count + ' items' : 'No items'}"
}
```

## Conditional Properties [#conditional-properties]

### visibleOn [#visibleon]

Show component when expression is true:

```json
{
  "type": "button",
  "label": "Admin Panel",
  "visibleOn": "${user.role === 'admin'}"
}
```

### hiddenOn [#hiddenon]

Hide component when expression is true:

```json
{
  "type": "section",
  "hiddenOn": "${user.settings.hideSection}"
}
```

### disabledOn [#disabledon]

Disable component when expression is true:

```json
{
  "type": "button",
  "label": "Submit",
  "disabledOn": "${form.submitting || !form.isValid}"
}
```

## Data Context [#data-context]

### Accessing Root Data [#accessing-root-data]

The root data object is available directly:

```tsx
const data = {
  user: { name: "Alice" },
  settings: { theme: "dark" }
}

<SchemaRenderer schema={schema} data={data} />
```

```json
{
  "type": "text",
  "value": "Theme: ${settings.theme}"
}
```

### Scoped Data [#scoped-data]

Some components provide scoped data:

```json
{
  "type": "list",
  "items": "${users}",
  "itemTemplate": {
    "type": "card",
    "title": "${item.name}",    // 'item' is scoped data
    "body": "${item.email}"
  }
}
```

### Index in Loops [#index-in-loops]

Access the current index in loops:

```json
{
  "type": "list",
  "items": "${users}",
  "itemTemplate": {
    "type": "text",
    "value": "#${index + 1}: ${item.name}"
  }
}
```

## Built-in Functions [#built-in-functions]

### String Functions [#string-functions]

```json
{
  "type": "text",
  "value": "${user.name.toUpperCase()}"
}
```

Available:

* `toUpperCase()`, `toLowerCase()`
* `trim()`, `trimStart()`, `trimEnd()`
* `substring(start, end)`
* `replace(search, replace)`
* `split(separator)`
* `includes(substring)`
* `startsWith(prefix)`, `endsWith(suffix)`

### Array Functions [#array-functions]

```json
{
  "type": "text",
  "value": "Total users: ${users.length}"
}
```

```json
{
  "type": "text",
  "value": "${users.map(u => u.name).join(', ')}"
}
```

Available:

* `length`
* `map(fn)`, `filter(fn)`, `reduce(fn, initial)`
* `join(separator)`
* `slice(start, end)`
* `includes(item)`
* `find(fn)`, `findIndex(fn)`
* `some(fn)`, `every(fn)`

### Number Functions [#number-functions]

```json
{
  "type": "text",
  "value": "Price: ${price.toFixed(2)}"
}
```

Available:

* `toFixed(decimals)`
* `toPrecision(digits)`
* `toString()`

### Math Functions [#math-functions]

```json
{
  "type": "text",
  "value": "${Math.round(average)}"
}
```

Available: All standard `Math` functions

* `Math.round()`, `Math.floor()`, `Math.ceil()`
* `Math.min()`, `Math.max()`
* `Math.abs()`
* `Math.random()`

### Date Functions [#date-functions]

```json
{
  "type": "text",
  "value": "${new Date().toLocaleDateString()}"
}
```

## Complex Expressions [#complex-expressions]

### Nested Ternary [#nested-ternary]

```json
{
  "type": "badge",
  "variant": "${
    status === 'active' ? 'success' :
    status === 'pending' ? 'warning' :
    status === 'error' ? 'destructive' :
    'default'
  }"
}
```

### Combining Operators [#combining-operators]

```json
{
  "type": "alert",
  "visibleOn": "${
    (user.role === 'admin' || user.role === 'moderator') &&
    user.isActive &&
    !user.isSuspended
  }"
}
```

### Array Methods [#array-methods]

```json
{
  "type": "text",
  "value": "${
    users
      .filter(u => u.isActive)
      .map(u => u.name)
      .join(', ')
  }"
}
```

## Practical Examples [#practical-examples]

### User Greeting [#user-greeting]

```json
{
  "type": "text",
  "value": "${
    new Date().getHours() < 12 ? 'Good morning' :
    new Date().getHours() < 18 ? 'Good afternoon' :
    'Good evening'
  }, ${user.firstName}!"
}
```

### Status Badge [#status-badge]

```json
{
  "type": "badge",
  "text": "${status}",
  "variant": "${
    status === 'completed' ? 'success' :
    status === 'in_progress' ? 'info' :
    status === 'pending' ? 'warning' :
    'default'
  }"
}
```

### Price Formatting [#price-formatting]

```json
{
  "type": "text",
  "value": "$${(price * quantity).toFixed(2)}"
}
```

### Empty State [#empty-state]

```json
{
  "type": "empty-state",
  "visibleOn": "${items.length === 0}",
  "message": "No items to display",
  "description": "Start by adding your first item"
}
```

### Percentage Bar [#percentage-bar]

```json
{
  "type": "progress",
  "value": "${(completed / total) * 100}",
  "label": "${completed} of ${total} completed"
}
```

### Conditional Styling [#conditional-styling]

```json
{
  "type": "card",
  "className": "${
    isPriority ? 'border-red-500 border-2' :
    isCompleted ? 'opacity-50' :
    'border-gray-200'
  }"
}
```

## Form Expressions [#form-expressions]

### Dependent Fields [#dependent-fields]

```json
{
  "type": "form",
  "body": [
    {
      "type": "select",
      "name": "country",
      "label": "Country",
      "options": ["USA", "Canada", "Mexico"]
    },
    {
      "type": "select",
      "name": "state",
      "label": "State/Province",
      "visibleOn": "${form.country === 'USA'}",
      "options": ["CA", "NY", "TX"]
    }
  ]
}
```

### Dynamic Validation [#dynamic-validation]

```json
{
  "type": "input",
  "name": "email",
  "label": "Email",
  "required": true,
  "validations": {
    "isEmail": true,
    "errorMessage": "Please enter a valid email"
  }
}
```

### Computed Fields [#computed-fields]

```json
{
  "type": "input",
  "name": "total",
  "label": "Total",
  "value": "${form.price * form.quantity}",
  "disabled": true
}
```

## Performance Considerations [#performance-considerations]

### Expensive Computations [#expensive-computations]

Expressions are re-evaluated when data changes. Avoid expensive operations:

```json
// ❌ Bad: Complex computation in expression
{
  "type": "text",
  "value": "${users.map(u => expensiveOperation(u)).join(', ')}"
}

// ✅ Good: Pre-compute in data
```

```tsx
const data = {
  processedUsers: users.map(u => expensiveOperation(u))
}
```

### Caching [#caching]

The expression engine automatically caches results when data doesn't change.

## Security [#security]

### Sandboxed Execution [#sandboxed-execution]

Expressions run in a sandboxed environment and can only access:

* The data context you provide
* Built-in JavaScript functions (Math, Date, String, Array methods)

They **cannot** access:

* Browser APIs (window, document, localStorage)
* Node.js APIs (fs, path, etc.)
* Global variables
* Function constructors

### Sanitization [#sanitization]

All expression outputs are automatically sanitized to prevent XSS attacks.

## Debugging Expressions [#debugging-expressions]

### Expression Errors [#expression-errors]

Invalid expressions show helpful error messages:

```json
{
  "type": "text",
  "value": "${user.invalidProperty}"
}
```

Error: "Cannot read property 'invalidProperty' of undefined"

### Debug Mode [#debug-mode]

Enable debug mode to see expression evaluation:

```tsx
<SchemaRenderer 
  schema={schema} 
  data={data}
  debug={true}
/>
```

This logs all expression evaluations to the console.

## Advanced Usage [#advanced-usage]

### Custom Functions [#custom-functions]

Extend the expression context with custom functions:

```tsx
import { getExpressionEvaluator } from '@object-ui/core'

const evaluator = getExpressionEvaluator()

evaluator.registerFunction('formatCurrency', (value: number) => {
  return new Intl.NumberFormat('en-US', {
    style: 'currency',
    currency: 'USD'
  }).format(value)
})
```

Use in schemas:

```json
{
  "type": "text",
  "value": "${formatCurrency(price)}"
}
```

### Custom Operators [#custom-operators]

Register custom operators for domain-specific logic:

```tsx
evaluator.registerOperator('contains', (array, item) => {
  return array.includes(item)
})
```

```json
{
  "type": "button",
  "visibleOn": "${user.permissions contains 'admin'}"
}
```

## Best Practices [#best-practices]

### 1. Keep Expressions Simple [#1-keep-expressions-simple]

```json
// ❌ Bad: Too complex
{
  "value": "${users.filter(u => u.age > 18).map(u => ({...u, isAdult: true})).reduce((acc, u) => acc + u.score, 0)}"
}

// ✅ Good: Pre-compute complex logic
{
  "value": "${adultUsersScore}"
}
```

### 2. Use Meaningful Variable Names [#2-use-meaningful-variable-names]

```json
// ❌ Bad
{
  "visibleOn": "${x && y || z}"
}

// ✅ Good
{
  "visibleOn": "${isAdmin && isActive || isSuperUser}"
}
```

### 3. Handle Null/Undefined [#3-handle-nullundefined]

```json
// ❌ Bad: Might throw error
{
  "value": "${user.address.city}"
}

// ✅ Good: Safe access
{
  "value": "${user.address?.city || 'N/A'}"
}
```

### 4. Use TypeScript [#4-use-typescript]

Define your data types:

```tsx
interface UserData {
  user: {
    name: string
    role: 'admin' | 'user'
    isActive: boolean
  }
}

const data: UserData = { /* ... */ }
<SchemaRenderer schema={schema} data={data} />
```

## Next Steps [#next-steps]

* [Schema Rendering](./schema-rendering.md) - Learn the rendering engine
* [Component Registry](./component-registry.md) - Understand components
* [Protocol Overview](/protocol/overview) - Explore schema specifications

## Related Documentation [#related-documentation]

* [Core API](/api/core) - Expression evaluator API
* [Form Protocol](/protocol/form) - Form-specific expressions
* [View Protocol](/protocol/view) - Data view expressions


# Field Registry



Object UI uses a **Field Registry** system to decouple the core engine from specific UI implementations of fields. This allows for rich extensibility and plugin support.

## Concept [#concept]

The `@object-ui/fields` package serves as the "Universal Language" for rendering values.

When a component like `<ObjectGrid>` needs to render a `date` field, it doesn't import a DatePicker directly. Instead, it asks the registry:

> *"Hey, give me the component responsible for rendering type 'date'."*

This architecture allows you to:

1. **Override standard fields** (e.g. replace the native date picker with a fancy one).
2. **Add new field types** (e.g. add a `rating` or `signature` field).
3. **Keep bundles small** (heavy components like Code Editors are loaded only if their plugin is registered).

## Usage [#usage]

### 1. Registering a Custom Field [#1-registering-a-custom-field]

You can register a custom renderer globally, typically at your app's entry point.

```tsx
// src/setup.tsx
import { registerFieldRenderer, type CellRendererProps } from '@object-ui/fields';

const MyRatingField = ({ value, onChange }: CellRendererProps) => {
  return (
    <div className="rating">
      {[1, 2, 3, 4, 5].map(star => (
        <span 
          key={star} 
          onClick={() => onChange(star)}
          style={{ color: star <= value ? 'gold' : 'grey' }}
        >
          ★
        </span>
      ))}
    </div>
  );
};

// Register it
registerFieldRenderer('rating', MyRatingField);
```

### 2. Using in Schema [#2-using-in-schema]

Once registered, you can simply use the new type in your JSON schema.

```json
{
  "type": "form",
  "fields": [
    {
      "name": "customer_satisfaction",
      "type": "rating", 
      "label": "Satisfaction"
    }
  ]
}
```

## Standard Fields [#standard-fields]

Object UI comes with built-in support for the standard [ObjectStack Protocol](/protocol) types:

| Type            | Description                                                                          |
| --------------- | ------------------------------------------------------------------------------------ |
| `text`          | Single line text                                                                     |
| `textarea`      | Multi-line text                                                                      |
| `number`        | Numeric input                                                                        |
| `currency`      | Currency formatting                                                                  |
| `percent`       | Percentage values                                                                    |
| `date`          | Date picker                                                                          |
| `datetime`      | Date & Time picker                                                                   |
| `boolean`       | Checkbox / Switch                                                                    |
| `select`        | Dropdown                                                                             |
| `lookup`        | Reference to another object                                                          |
| `master_detail` | Parent-child relationship                                                            |
| `user`          | Person picker — searches the `sys_user` object (a lookup specialized to users)       |
| `owner`         | Record owner — a `user` field, typically read-only and stamped with the current user |

## Using Renderers in Custom Components [#using-renderers-in-custom-components]

If you are building your own custom component (like a Kanban board card), you can leverage the registry to render fields without reinventing the wheel.

```tsx
import { getCellRenderer } from '@object-ui/fields';

export const KanbanCard = ({ task }) => {
  // Get the standard renderer for a 'user' type field
  const UserRenderer = getCellRenderer('user');
  
  return (
    <div className="card">
      <h3>{task.name}</h3>
      <div className="assignee">
        <UserRenderer 
          value={task.assignee} 
          field={{ type: 'user' }} 
        />
      </div>
    </div>
  );
};
```


# Flow Designer



# Flow Designer [#flow-designer]

The **Flow Designer** is the visual editor for `flow` metadata in the console's
metadata admin. It renders a flow's nodes and edges on a pan/zoom canvas so you
can assemble automation — create/update records, branch on conditions, wait for
events, call APIs, route for approval — without hand-editing JSON. The designer
is a thin, **spec-driven** view over `flow` metadata: everything you drop on the
canvas is a node in the flow's schema, so the same document runs unchanged on
the automation engine.

Open it from a `flow` record's **Design** tab. The **Form** tab holds the same
flow as an editable tree; the two stay in sync.

## The canvas [#the-canvas]

Each node is a card showing its icon, label, `type`, and a one-line summary of
its config. Edges are the arrows between them.

| Gesture                                    | Result                               |
| ------------------------------------------ | ------------------------------------ |
| Click a card                               | Select it (opens the node inspector) |
| Drag a card                                | Reposition it                        |
| Hover a card → click the bottom &#x2A;*+** | Append a connected child node        |
| Zoom controls / **Fit**                    | Scale and re-center the graph        |

Structural problems (an undeclared cycle, an unreachable node) surface three
ways at once: a red ring on the offending card, a badge in its corner, and an
inline banner at the top-left of the canvas. Clicking a banner row selects and
pans to the element it refers to.

## Adding nodes — the palette [#adding-nodes--the-palette]

The **Add node** button (top-right, edit mode only) opens the node palette: a
searchable, grouped list of every node type the flow can use.

### Search and keyboard [#search-and-keyboard]

Type in the box at the top to filter across **all** categories at once — the
match is a case-insensitive substring test over each node's **label**, **hint**,
and **type**, so `scr` finds *Screen*, `http` finds *HTTP request*, and a word
that only appears in a hint (`concurrently` → *Parallel*) still surfaces the
node. Clearing the box restores the full grouped list.

The palette is keyboard-navigable end to end:

| Key       | Action                            |
| --------- | --------------------------------- |
| `↑` / `↓` | Move the highlight (wraps around) |
| `Enter`   | Insert the highlighted node       |
| `Esc`     | Close the palette                 |

The search box autofocuses when the palette opens, so you can open, type a few
letters, and press `Enter` without touching the mouse.

### Categories [#categories]

Nodes are grouped into five sections, in this order:

| Category        | Node types                                           |
| --------------- | ---------------------------------------------------- |
| **Data**        | Create / Update / Get / Delete record                |
| **Logic**       | Decision, Loop, Set variables, Parallel, Try / Catch |
| **Human**       | Approval, Screen                                     |
| **Integration** | HTTP request, Connector, Script                      |
| **Flow**        | Subflow, Wait, End                                   |

Section headings are localized to the active console language (e.g. *数据 /
逻辑 / 人工 / 集成 / 流程* in Chinese); the underlying node types are unchanged.

### Recently used [#recently-used]

When the search box is empty, a **Recently used** group tops the list with the
node types you inserted most recently (up to five, most-recent first) — so the
nodes you reach for repeatedly stop needing a scroll or a search. The list is
per-user and, when the console is connected to a backend, syncs across devices
(see [User-Scoped State Persistence](/docs/guide/user-state-persistence)); it
falls back to browser-local storage when offline. Types from a plugin that was
since uninstalled drop out of the list automatically.

### Server-merged, plugin-extensible [#server-merged-plugin-extensible]

The palette is **server-driven**. Beyond the built-in node types, the running
engine publishes its registered actions at `GET /api/v1/automation/actions`, and
plugins contribute their own node types there (for example an `approval` node
from an approvals plugin, or third-party `connector_action` providers). The
designer overlays those descriptors onto the built-in list — adopting the
engine's labels and descriptions and appending engine-only types — so the
palette always matches what the connected backend actually supports. Plugin
nodes are searchable exactly like built-ins, including by their registered
`type`. When the endpoint is unreachable the designer falls back to its
built-in defaults, so authoring still works offline.

## The node inspector [#the-node-inspector]

Selecting a node opens its inspector: **ID**, **Label**, **Node Type**, an
optional **Description**, and a **Configuration** section. New nodes start with
spec-valid defaults (a *Wait* node already carries a timer config, an *HTTP*
node defaults to `GET`) so a freshly dropped block is never in a broken
intermediate state.

For node types whose engine executor publishes a `configSchema` (ADR-0018), the
inspector renders a **server-driven property form** from that schema — so a
plugin's node gets a real config UI without the designer hardcoding its fields.

A **Decision** node's Branches editor defines each branch's label, CEL
expression, **and target node** in one table: the **Target** column picks the
downstream node, wiring (creating, retargeting, or detaching) the branch's
outgoing edge with its condition, label, and default flag. The same binding can
also be edited from the edge side — select a connector and use its **Branch**
picker — and the two stay in sync, because the routing always lives on the
edges.

## Validate, simulate, inspect runs [#validate-simulate-inspect-runs]

The toolbar toggles four side panels:

| Panel         | What it shows                                                                               |
| ------------- | ------------------------------------------------------------------------------------------- |
| **Variables** | The flow's declared variables                                                               |
| **Problems**  | Structural + server validation issues, each clickable to reveal on canvas                   |
| **Debug**     | A step-through **simulator** that walks the graph and highlights the active / visited nodes |
| **Runs**      | Execution history for the published flow, fetched from the engine                           |

## See also [#see-also]

* [User-Scoped State Persistence](/docs/guide/user-state-persistence) — how the
  "Recently used" list is stored and synced.
* [Console App](/docs/guide/console) — the reference app that hosts the metadata
  admin and its designers.


# Guide



# ObjectUI Guide [#objectui-guide]

Welcome to the ObjectUI Guide! This comprehensive guide covers everything you need to know to build powerful server-driven UIs with ObjectUI.

## Examples [#examples]

* [examples/server](examples/server) - Run a metadata app using @objectstack/cli.

### Run the ObjectStack Server Example [#run-the-objectstack-server-example]

```bash
pnpm --filter @object-ui/example-objectstack-server serve
```


# Layout System



# Layout System [#layout-system]

ObjectUI provides a comprehensive layout system through the `@object-ui/layout` package. This guide explains how to use layout components to build professional application structures.

## Overview [#overview]

The layout system provides:

* **AppShell** - Full application container with header, sidebar, and content areas
* **Page** - Individual page wrapper with header and body
* **PageHeader** - Consistent page headers with title, breadcrumbs, and actions
* **SidebarNav** - Navigation sidebar with menu items

## Installation [#installation]

The layout package is included in the core ObjectUI installation:

```bash
npm install @object-ui/react
```

Layout components are automatically registered when you import ObjectUI.

## AppShell Component [#appshell-component]

The `AppShell` provides a complete application structure with header, sidebar, and main content area.

### Basic Usage [#basic-usage]

```json
{
  "type": "app-shell",
  "header": {
    "type": "header-bar",
    "title": "My Application"
  },
  "sidebar": {
    "type": "sidebar-nav",
    "items": [
      { "label": "Dashboard", "href": "/dashboard", "icon": "layout-dashboard" },
      { "label": "Users", "href": "/users", "icon": "users" },
      { "label": "Settings", "href": "/settings", "icon": "settings" }
    ]
  },
  "body": {
    "type": "page",
    "title": "Dashboard",
    "body": {
      "type": "text",
      "value": "Welcome to the dashboard!"
    }
  }
}
```

### Schema API [#schema-api]

```typescript
{
  type: 'app-shell',
  
  // Header configuration
  header?: ComponentSchema,
  
  // Sidebar configuration  
  sidebar?: ComponentSchema,
  sidebarCollapsible?: boolean,  // Allow sidebar collapse
  sidebarDefaultOpen?: boolean,  // Initial sidebar state
  
  // Main content
  body: ComponentSchema,
  
  // Styling
  className?: string,
  headerClassName?: string,
  sidebarClassName?: string,
  contentClassName?: string
}
```

### Features [#features]

* Responsive layout that adapts to mobile/tablet/desktop
* Collapsible sidebar with state management
* Sticky header
* Scroll management for content area
* Consistent spacing and structure

## Page Component [#page-component]

The `Page` component provides a consistent wrapper for individual pages with optional headers.

### Basic Usage [#basic-usage-1]

```json
{
  "type": "page",
  "title": "User Management",
  "description": "Manage users and permissions",
  "body": {
    "type": "container",
    "children": [
      { "type": "text", "value": "User list goes here" }
    ]
  }
}
```

### With Action Buttons [#with-action-buttons]

```json
{
  "type": "page",
  "title": "Products",
  "actions": [
    {
      "type": "button",
      "text": "Add Product",
      "variant": "default",
      "icon": "plus"
    },
    {
      "type": "button", 
      "text": "Export",
      "variant": "outline",
      "icon": "download"
    }
  ],
  "body": {
    "type": "object-grid",
    "object": "products"
  }
}
```

### Schema API [#schema-api-1]

```typescript
{
  type: 'page',
  
  // Header
  title?: string,               // Page title
  description?: string,         // Page description/subtitle
  icon?: string,               // Optional icon
  breadcrumbs?: Array<{        // Breadcrumb navigation
    label: string,
    href?: string
  }>,
  actions?: ComponentSchema[], // Action buttons
  
  // Content
  body: ComponentSchema,       // Main page content
  
  // Layout options
  maxWidth?: 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'full',
  padding?: boolean,           // Add padding (default: true)
  
  // Styling
  className?: string,
  headerClassName?: string,
  bodyClassName?: string
}
```

### Max Width Options [#max-width-options]

Control page content width:

```json
{
  "type": "page",
  "title": "Settings",
  "maxWidth": "lg",  // Centered content with max width
  "body": {
    "type": "form",
    "fields": [...]
  }
}
```

Available values:

* `sm` - 640px
* `md` - 768px
* `lg` - 1024px
* `xl` - 1280px
* `2xl` - 1536px
* `full` - No maximum width (default)

## PageHeader Component [#pageheader-component]

The `PageHeader` provides consistent page headers with title, breadcrumbs, and actions.

### Usage [#usage]

```json
{
  "type": "page-header",
  "title": "Customer Details",
  "description": "View and edit customer information",
  "breadcrumbs": [
    { "label": "Home", "href": "/" },
    { "label": "Customers", "href": "/customers" },
    { "label": "John Doe" }
  ],
  "actions": [
    {
      "type": "button",
      "text": "Edit",
      "variant": "default",
      "icon": "pencil"
    },
    {
      "type": "button",
      "text": "Delete",
      "variant": "destructive",
      "icon": "trash"
    }
  ]
}
```

### Schema API [#schema-api-2]

```typescript
{
  type: 'page-header',
  
  title: string,
  description?: string,
  icon?: string,
  
  breadcrumbs?: Array<{
    label: string,
    href?: string,
    icon?: string
  }>,
  
  actions?: ComponentSchema[],
  
  className?: string
}
```

## SidebarNav Component [#sidebarnav-component]

The `SidebarNav` provides a collapsible navigation sidebar with menu items.

### Basic Usage [#basic-usage-2]

```json
{
  "type": "sidebar-nav",
  "items": [
    {
      "label": "Dashboard",
      "href": "/dashboard",
      "icon": "layout-dashboard"
    },
    {
      "label": "Users",
      "href": "/users", 
      "icon": "users",
      "badge": "12"
    },
    {
      "label": "Reports",
      "icon": "bar-chart",
      "items": [
        { "label": "Sales", "href": "/reports/sales" },
        { "label": "Analytics", "href": "/reports/analytics" }
      ]
    }
  ]
}
```

### Schema API [#schema-api-3]

```typescript
{
  type: 'sidebar-nav',
  
  items: Array<{
    label: string,
    href?: string,
    icon?: string,
    badge?: string | number,
    badgeVariant?: 'default' | 'destructive' | 'outline',
    items?: Array<...>,  // Nested menu items (collapsible children)
    active?: boolean,
    disabled?: boolean
  }>,
  
  // Items can also be grouped using NavGroup:
  // items: Array<{ label: string, items: NavItem[] }>

  collapsible?: boolean,
  defaultOpen?: boolean,
  searchEnabled?: boolean,        // Show search input to filter navigation
  searchPlaceholder?: string,     // Placeholder for search input
  
  className?: string
}
```

### Features [#features-1]

* Nested menu items (2 levels) with collapsible expand/collapse
* Active state highlighting via React Router
* Icon support (Lucide icons)
* Badge/counter support with variant styling (`default`, `destructive`, `outline`)
* NavGroup support for grouped navigation sections
* Built-in search filtering (`searchEnabled`) across all items and children
* Collapse/expand animation

## Common Layout Patterns [#common-layout-patterns]

### Full Application Layout [#full-application-layout]

```json
{
  "type": "app-shell",
  "header": {
    "type": "header-bar",
    "title": "My App",
    "logo": "/logo.png",
    "actions": [
      { "type": "button", "text": "Profile", "variant": "ghost" }
    ]
  },
  "sidebar": {
    "type": "sidebar-nav",
    "items": [
      { "label": "Home", "href": "/", "icon": "home" },
      { "label": "Products", "href": "/products", "icon": "package" },
      { "label": "Orders", "href": "/orders", "icon": "shopping-cart" }
    ]
  },
  "sidebarCollapsible": true,
  "sidebarDefaultOpen": true,
  "body": {
    "type": "page",
    "title": "Dashboard",
    "body": {
      "type": "object-grid",
      "object": "orders"
    }
  }
}
```

### Landing Page (No Sidebar) [#landing-page-no-sidebar]

```json
{
  "type": "app-shell",
  "header": {
    "type": "header-bar",
    "title": "Welcome"
  },
  "body": {
    "type": "container",
    "className": "mx-auto py-12",
    "children": [
      { "type": "text", "value": "Landing page content" }
    ]
  }
}
```

### Settings Page with Tabs [#settings-page-with-tabs]

```json
{
  "type": "page",
  "title": "Settings",
  "maxWidth": "2xl",
  "body": {
    "type": "tabs",
    "tabs": [
      {
        "label": "General",
        "value": "general",
        "content": { "type": "form", "fields": [...] }
      },
      {
        "label": "Security", 
        "value": "security",
        "content": { "type": "form", "fields": [...] }
      },
      {
        "label": "Notifications",
        "value": "notifications", 
        "content": { "type": "form", "fields": [...] }
      }
    ]
  }
}
```

### Detail Page with Actions [#detail-page-with-actions]

```json
{
  "type": "page",
  "title": "${record.name}",
  "breadcrumbs": [
    { "label": "Home", "href": "/" },
    { "label": "Customers", "href": "/customers" },
    { "label": "${record.name}" }
  ],
  "actions": [
    {
      "type": "button",
      "text": "Edit",
      "variant": "default",
      "icon": "pencil",
      "onClick": "editRecord"
    },
    {
      "type": "button",
      "text": "Delete",
      "variant": "destructive",
      "icon": "trash",
      "onClick": "deleteRecord"
    }
  ],
  "body": {
    "type": "card",
    "children": [
      { "type": "text", "value": "Record details..." }
    ]
  }
}
```

## Responsive Behavior [#responsive-behavior]

Layout components automatically adapt to different screen sizes:

### Desktop (≥1024px) [#desktop-1024px]

* Full sidebar visible
* Header spans full width
* Content area uses remaining space

### Tablet (768px - 1023px) [#tablet-768px---1023px]

* Collapsible sidebar (overlay mode)
* Full header
* Content uses most of screen

### Mobile (\<768px) [#mobile-768px]

* Hidden sidebar (toggle button in header)
* Compact header
* Full-width content

## Styling and Customization [#styling-and-customization]

### Custom Classes [#custom-classes]

Add Tailwind classes to layout components:

```json
{
  "type": "app-shell",
  "className": "custom-app",
  "headerClassName": "bg-primary text-primary-foreground",
  "sidebarClassName": "bg-muted",
  "contentClassName": "bg-background",
  "body": {...}
}
```

### Page Padding [#page-padding]

Control page content padding:

```json
{
  "type": "page",
  "padding": false,  // Remove default padding
  "body": {
    "type": "container",
    "className": "p-8",  // Custom padding
    "children": [...]
  }
}
```

## Best Practices [#best-practices]

### 1. Consistent Structure [#1-consistent-structure]

Use the same layout structure across your app:

```json
// Every page should follow this pattern
{
  "type": "app-shell",
  "header": { ... },
  "sidebar": { ... },
  "body": {
    "type": "page",
    "title": "...",
    "body": { ... }
  }
}
```

### 2. Breadcrumbs for Deep Navigation [#2-breadcrumbs-for-deep-navigation]

Add breadcrumbs to help users navigate:

```json
{
  "breadcrumbs": [
    { "label": "Home", "href": "/" },
    { "label": "Products", "href": "/products" },
    { "label": "Electronics", "href": "/products/electronics" },
    { "label": "Laptops" }
  ]
}
```

### 3. Action Buttons in Headers [#3-action-buttons-in-headers]

Place primary actions in page headers:

```json
{
  "type": "page",
  "title": "Orders",
  "actions": [
    { "type": "button", "text": "New Order", "variant": "default" }
  ]
}
```

### 4. Max Width for Forms [#4-max-width-for-forms]

Use constrained width for forms and reading content:

```json
{
  "type": "page",
  "maxWidth": "lg",  // Better for forms
  "body": {
    "type": "form",
    "fields": [...]
  }
}
```

### 5. Sidebar Organization [#5-sidebar-organization]

Group related items in the sidebar:

```json
{
  "items": [
    { "label": "Dashboard", "icon": "home", "href": "/" },
    { "label": "divider" },  // Visual separator
    { "label": "Sales", "icon": "dollar-sign", "items": [
      { "label": "Orders", "href": "/orders" },
      { "label": "Invoices", "href": "/invoices" }
    ]},
    { "label": "divider" },
    { "label": "Settings", "icon": "settings", "href": "/settings" }
  ]
}
```

## Related Documentation [#related-documentation]

* [Components Overview](/docs/components) - All available components
* [Schema Rendering](/docs/guide/schema-rendering) - How schemas work
* [Architecture Overview](/docs/guide/architecture) - System architecture


# Metadata Diagnostics



# Metadata Diagnostics [#metadata-diagnostics]

Every metadata item shipped by a package — `object`, `view`, `report`,
`dashboard`, `flow`, `app`, … — is validated against its Zod schema when
the framework loads it. The validation result travels alongside the
item as a `_diagnostics` envelope, and Studio surfaces it at four levels
so authors and operators can fix problems without grepping logs.

> **Backend agnostic.** The shape and the REST endpoint described below
> are part of the ObjectStack protocol. Studio is one consumer; any
> custom UI built on `@object-ui/data-objectstack` can render the same
> envelope.

## The `_diagnostics` envelope [#the-_diagnostics-envelope]

```ts
interface MetadataDiagnostics {
  valid: boolean;
  errors?:   Array<{ path: string; message: string; code?: string }>;
  warnings?: Array<{ path: string; message: string; code?: string }>;
}
```

* `valid === false` means **at least one error** — features that depend
  on the item (rendering, queries, automation) are unsafe to use.
* `warnings[]` is advisory — items remain `valid: true` but operators
  should review (deprecations, performance hints, missing-but-defaultable
  fields).
* `path` is dot-delimited, matching the same convention Zod uses
  (`fields.email.type`, `columns.0.bind`).

The envelope is attached to:

| Endpoint                                          | Where the envelope lives              |
| :------------------------------------------------ | :------------------------------------ |
| `GET /api/v1/meta/items/:type`                    | Each list entry (`item._diagnostics`) |
| `GET /api/v1/meta/items/:type/:name`              | Top-level (`item._diagnostics`)       |
| `GET /api/v1/meta/items/:type/:name?layered=true` | `effective._diagnostics`              |
| `GET /api/v1/meta/diagnostics`                    | Sweep — see next section              |

## The diagnostics sweep endpoint [#the-diagnostics-sweep-endpoint]

`GET /api/v1/meta/diagnostics` runs validation across **every metadata
type and item** in one round-trip. It powers the governance overview
page and the per-type tile badges.

```http
GET /api/v1/meta/diagnostics?severity=error
```

| Query      | Default | Effect                                                                               |
| :--------- | :------ | :----------------------------------------------------------------------------------- |
| `severity` | `error` | `error` returns invalid items only; `warning` also returns items with only warnings. |
| `type`     | —       | Limit to a single metadata type.                                                     |
| `package`  | —       | Limit to one package id.                                                             |

Response:

```ts
interface MetadataDiagnosticsSummary {
  entries: Array<{
    type: string;
    name: string;
    diagnostics: MetadataDiagnostics;
  }>;
  total: number;          // entries.length
  scannedTypes: number;   // how many metadata types were checked
  scannedItems: number;   // how many items were checked in total
  /**
   * Per-type aggregate stats — count of items and the list of
   * packages contributing to each type. Computed in the same sweep so
   * directory tiles render counts and a package filter without
   * additional round-trips. Empty `{}` on framework versions older
   * than the 7.x line.
   */
  stats: Record<string, { count: number; packages: string[] }>;
}
```

Use this as a CI gate too — `total === 0` is the green-build condition.

## Studio UI surfaces [#studio-ui-surfaces]

### 1. Directory page badges [#1-directory-page-badges]

`/apps/<app>/metadata` — the directory is **scoped to the active project
software package** (the sidebar `active_package` selector, published as
`?package=`). Only metadata types that the selected project package
contributes are listed — system/cloud types never appear, and there is no
in-page "All packages" dropdown. If the URL holds no valid project
package the page repairs it to the first available one. Each visible type
tile shows:

* A neutral count badge with the total items of that type. (Note: this
  total spans all packages — the per-type *list* page it links to is
  strictly scoped to the active project package.)
* A red ⚠ + count when any items fail validation (errors).
* An amber ⚠ + count when items have warnings but no errors.

Tiles deep-link into the list page carrying the active `?package=`, so the
scope survives navigation.

The "View all issues (N)" link in the filter row jumps straight to the
governance page.

### 2. Resource list rows [#2-resource-list-rows]

`/apps/<app>/metadata/<type>` — invalid rows get a red ⚠ icon next to
the name and a destructive-tinted background; warning-only rows get an
amber ⚠ and amber tint. The list header shows aggregate "Invalid N" and
"Warnings N" chips. Hover the ⚠ for the first three messages.

The list page is **always scoped to a single project software package**.
Studio's sidebar exposes a mandatory **Package** scope selector (the app's
`active_package` context selector) whose options are the installed
*project* packages — system/cloud packages are never offered and there is
no "All" choice. The selection is published as the `?package=` URL
parameter, which every metadata list reads to filter rows by their
`_packageId`. If the URL holds no valid project package the list repairs
it to the first available one, so system metadata never leaks into the
view. (The page no longer renders its own per-type package dropdown —
scope is owned solely by the sidebar selector.)

### 3. Resource edit banners [#3-resource-edit-banners]

`/apps/<app>/metadata/<type>/<name>` — a destructive banner at the top
of the edit page lists the first three errors with their paths; the
same errors are also threaded into the form so the offending fields
get inline messages **without** the user having to click Save first.
Warnings, when present, render as a parallel amber banner.

Edits clear the matching diagnostic immediately — the inline error on a
field disappears as soon as you start typing in it, then re-validates
on save.

For **object** drafts the live validation goes beyond the Zod shape check:
every field conditional rule (`visibleWhen` / `readonlyWhen` / `requiredWhen`,
plus the deprecated `conditionalRequired` alias) is linted as a CEL predicate
with the same `@objectstack/formula` validators the server uses. A predicate
that parses but references an unknown field, or references a field bare
instead of as `record.<field>`, surfaces under its `fields.<field>.<rule>`
path in the banner. The field inspector's *Conditional rules* editors give
the same verdict inline as you type — with autocomplete for the object's
fields (after `record.` / `previous.`), the runtime-bound scope roots
(`record`, `previous`, `parent`), and the CEL stdlib.

Formula fields get the same treatment for their value `expression`: the
inline editor lints it in `role: 'value'` mode and shows the **inferred
result type** (only a proven-Number formula is offered as a dataset
measure), while the draft-wide pass surfaces a broken formula on any field
under its `fields.<field>.expression` path.

### 4. Governance overview page [#4-governance-overview-page]

`/apps/<app>/metadata/_diagnostics` — a single sortable table of every
invalid item across every type, grouped by type, with deep-links to the
offending edit page. Toggle the severity tab to include
warning-only items. This is the page to open during a release readiness
review.

## Authoring metadata that validates cleanly [#authoring-metadata-that-validates-cleanly]

Validation rules are defined by the Zod schemas in `@objectstack/spec`.
A few high-leverage patterns:

* **Use `defineObject`, `defineView`, … helpers** from `@objectstack/spec` —
  TypeScript catches most shape issues at compile time before they ever
  reach the diagnostics path.
* **Run `os check`** locally before publishing. It calls the same
  validators the server uses on load.
* **Treat warnings like errors in CI.** Pass `severity=warning` to the
  sweep endpoint and assert `total === 0`.
* **Layered overlays merge first, then validate.** If only your runtime
  overlay fails, the source artifact is fine — the bad value is in the
  overlay. The edit banner reflects the *effective* item, so what you
  see is what features will get.

## Client SDK [#client-sdk]

```ts
import { MetadataClient } from '@object-ui/data-objectstack';

const client = new MetadataClient(/* config */);
const summary = await client.diagnostics({ severity: 'error' });
console.log(summary.total, 'invalid item(s)');
```

The hook used by the Studio surfaces:

```ts
import { useGlobalDiagnostics, useMetadataClient } from '@object-ui/app-shell';

const client = useMetadataClient();
const {
  loading,
  error,
  summary,
  byType,         // Record<type, invalid-item-count>
  warnByType,     // Record<type, warn-only-item-count> (severity='warning' only)
  countsByType,   // Record<type, total-item-count>
  packagesByType, // Record<type, packageId[]>
  allPackages,    // packageId[] — deduped union for filter dropdowns
  reload,
} = useGlobalDiagnostics(client, 'warning');
```

Pass `severity: 'warning'` when you need `warnByType` populated — the
server omits warning-only entries when the default `'error'` severity
is in effect.


# ObjectOS Integration Guide



# ObjectOS Integration Guide [#objectos-integration-guide]

ObjectUI is designed to be the official frontend renderer for the **ObjectOS** ecosystem. This guide provides comprehensive instructions for integrating ObjectUI components with ObjectOS, ObjectStack, and building enterprise applications.

## Overview [#overview]

ObjectUI serves as the **UI Layer** in the ObjectOS architecture:

```
┌─────────────────────────────────────────────────┐
│               ObjectUI (UI Layer)                │
│  React Components + Tailwind + Schema Rendering │
└──────────────────┬──────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────┐
│          ObjectStack (Runtime Layer)             │
│   Kernel + Plugins + ObjectQL + Data Drivers    │
└──────────────────┬──────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────┐
│           ObjectOS (Platform Layer)              │
│  Multi-tenant + RBAC + System Objects + APIs    │
└─────────────────────────────────────────────────┘
```

## Quick Start Integration [#quick-start-integration]

### 1. Install Dependencies [#1-install-dependencies]

```bash
# Core ObjectUI packages
pnpm add @object-ui/react @object-ui/components @object-ui/fields

# ObjectStack runtime
pnpm add @objectstack/core @objectstack/runtime @objectstack/objectql

# Data adapter
pnpm add @object-ui/data-objectstack

# Optional: Plugins as needed
pnpm add @object-ui/plugin-form @object-ui/plugin-grid
```

### 2. Set Up ObjectStack Kernel [#2-set-up-objectstack-kernel]

```typescript
// src/kernel.ts
import { Kernel } from '@objectstack/runtime';
import { ObjectQLPlugin } from '@objectstack/objectql';
import { AppPlugin } from '@objectstack/plugin-app';
import { HonoServerPlugin } from '@objectstack/plugin-hono-server';

export async function createKernel() {
  const kernel = new Kernel();

  // Register essential plugins
  kernel.registerPlugin(new ObjectQLPlugin());
  kernel.registerPlugin(new AppPlugin());
  kernel.registerPlugin(new HonoServerPlugin({
    port: 3000,
    cors: true
  }));

  await kernel.start();
  return kernel;
}
```

### 3. Create ObjectStack Configuration [#3-create-objectstack-configuration]

```typescript
// objectstack.config.ts
import type { AppManifest } from '@objectstack/spec';

export const manifest: AppManifest = {
  name: 'my-app',
  version: '1.0.0',
  description: 'My ObjectUI + ObjectOS Application',
  
  // Define your data objects
  objects: {
    contact: {
      name: 'contact',
      label: 'Contact',
      fields: {
        name: { name: 'name', label: 'Name', type: 'text', required: true },
        email: { name: 'email', label: 'Email', type: 'email', required: true },
        phone: { name: 'phone', label: 'Phone', type: 'phone' },
        company: { name: 'company', label: 'Company', type: 'text' },
        status: {
          name: 'status',
          label: 'Status',
          type: 'select',
          options: [
            { label: 'Active', value: 'active' },
            { label: 'Inactive', value: 'inactive' }
          ]
        }
      }
    }
  },

  // Define UI pages
  pages: [
    {
      name: 'contacts',
      label: 'Contacts',
      path: '/contacts',
      icon: 'users',
      component: {
        type: 'object-view',
        objectName: 'contact',
        viewTypes: ['grid', 'kanban', 'calendar']
      }
    }
  ],

  // Define app navigation
  navigation: {
    items: [
      {
        label: 'Dashboard',
        path: '/',
        icon: 'home'
      },
      {
        label: 'Contacts',
        path: '/contacts',
        icon: 'users'
      }
    ]
  }
};

export default manifest;
```

### 4. Set Up Frontend with Console [#4-set-up-frontend-with-console]

```typescript
// src/index.tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import { SchemaRenderer } from '@object-ui/react';
import { ObjectStackAdapter } from '@object-ui/data-objectstack';

// Import required plugins
import '@object-ui/components';
import '@object-ui/fields';
import '@object-ui/plugin-form';
import '@object-ui/plugin-grid';

// Initialize ObjectStack adapter
const dataSource = new ObjectStackAdapter({
  baseUrl: 'http://localhost:3000/api'
});

function App() {
  return (
    <div className="min-h-screen bg-background">
      <SchemaRenderer
        schema={{
          type: 'page',
          template: 'header-sidebar-main',
          header: {
            type: 'header-bar',
            title: 'My App',
            navigation: {
              items: [
                { label: 'Dashboard', path: '/', icon: 'home' },
                { label: 'Contacts', path: '/contacts', icon: 'users' }
              ]
            }
          },
          sidebar: {
            type: 'navigation-menu',
            items: [
              { label: 'Dashboard', path: '/', icon: 'home' },
              { label: 'Contacts', path: '/contacts', icon: 'users' }
            ]
          },
          main: {
            type: 'object-view',
            objectName: 'contact',
            dataSource,
            viewTypes: ['grid', 'kanban']
          }
        }}
      />
    </div>
  );
}

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);
```

## ObjectOS-Specific Features [#objectos-specific-features]

### Multi-Tenancy Support [#multi-tenancy-support]

```typescript
// Configure tenant isolation
const adapter = new ObjectStackAdapter({
  baseUrl: 'http://localhost:3000/api',
  headers: {
    'X-Tenant-ID': 'tenant-123',
    'X-Workspace-ID': 'workspace-456'
  }
});
```

### Role-Based Access Control (RBAC) [#role-based-access-control-rbac]

```typescript
// Define permissions in object schema
{
  objects: {
    contact: {
      name: 'contact',
      label: 'Contact',
      permissions: {
        create: ['admin', 'sales'],
        read: ['admin', 'sales', 'support'],
        update: ['admin', 'sales'],
        delete: ['admin']
      },
      fields: {
        salary: {
          name: 'salary',
          label: 'Salary',
          type: 'currency',
          permissions: {
            read: ['admin', 'hr'],
            update: ['admin', 'hr']
          }
        }
      }
    }
  }
}
```

### System Objects Integration [#system-objects-integration]

ObjectOS provides system objects like `sys_user`, `sys_organization`, `sys_role`, etc. Integrate them in your UI:

```typescript
{
  type: 'object-view',
  objectName: 'sys_user',
  dataSource: objectStackAdapter,
  viewTypes: ['grid'],
  fieldNames: ['username', 'email', 'role', 'status', 'last_login']
}
```

### Workflow Integration [#workflow-integration]

```typescript
// Define workflow-enabled object
{
  objects: {
    opportunity: {
      name: 'opportunity',
      label: 'Opportunity',
      workflow: {
        enabled: true,
        states: ['lead', 'qualified', 'proposal', 'negotiation', 'closed_won', 'closed_lost'],
        transitions: [
          { from: 'lead', to: 'qualified', label: 'Qualify', role: ['sales'] },
          { from: 'qualified', to: 'proposal', label: 'Create Proposal', role: ['sales'] },
          { from: 'proposal', to: 'negotiation', label: 'Negotiate', role: ['sales', 'manager'] },
          { from: 'negotiation', to: 'closed_won', label: 'Close Won', role: ['manager'] },
          { from: 'negotiation', to: 'closed_lost', label: 'Close Lost', role: ['manager'] }
        ]
      },
      fields: {
        // ... field definitions
      }
    }
  }
}
```

## Data Layer Integration [#data-layer-integration]

### Using ObjectQL for Queries [#using-objectql-for-queries]

```typescript
import { ObjectStackAdapter } from '@object-ui/data-objectstack';

const dataSource = new ObjectStackAdapter({
  baseUrl: 'http://localhost:3000/api'
});

// ObjectQL queries are automatically handled
const schema = {
  type: 'object-grid',
  objectName: 'contact',
  dataSource,
  // ObjectQL filter syntax
  filter: {
    and: [
      { field: 'status', operator: 'eq', value: 'active' },
      { field: 'created_date', operator: 'gte', value: '2024-01-01' }
    ]
  },
  // ObjectQL sorting
  sort: [
    { field: 'created_date', order: 'desc' }
  ]
};
```

### Custom Data Hooks [#custom-data-hooks]

```typescript
// Implement custom hooks for data operations
import { useObjectQuery, useObjectMutation } from '@object-ui/data-objectstack';

function ContactList() {
  const { data, loading, error } = useObjectQuery('contact', {
    filter: { field: 'status', operator: 'eq', value: 'active' },
    sort: [{ field: 'name', order: 'asc' }],
    page: 1,
    pageSize: 20
  });

  const { mutate: createContact } = useObjectMutation('contact', 'create');
  
  const handleCreate = async (formData: any) => {
    await createContact(formData);
  };

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <SchemaRenderer
      schema={{
        type: 'object-grid',
        rowData: data.records,
        // ... other props
      }}
    />
  );
}
```

## Deployment Strategies [#deployment-strategies]

### Strategy 1: Monolithic Deployment [#strategy-1-monolithic-deployment]

Deploy ObjectUI and ObjectStack together in a single Node.js process:

```typescript
// server.ts
import { createKernel } from './kernel';
import { ConsolePlugin } from './console-plugin';

async function start() {
  const kernel = await createKernel();
  
  // Register console UI plugin
  kernel.registerPlugin(new ConsolePlugin());
  
  console.log('🚀 Server started at http://localhost:3000');
  console.log('📊 Console UI at http://localhost:3000/console');
}

start();
```

### Strategy 2: Microservices Deployment [#strategy-2-microservices-deployment]

Deploy ObjectUI (frontend) and ObjectStack (backend) separately:

**Backend (ObjectStack API):**

```typescript
// backend/server.ts
import { createKernel } from './kernel';

async function start() {
  const kernel = await createKernel();
  console.log('🚀 API Server started at http://localhost:3000');
}

start();
```

**Frontend (ObjectUI):**

```typescript
// frontend/src/config.ts
export const config = {
  apiBaseUrl: process.env.VITE_API_URL || 'http://localhost:3000/api'
};

// frontend/src/index.tsx
const dataSource = new ObjectStackAdapter({
  baseUrl: config.apiBaseUrl
});
```

### Strategy 3: Cloud-Native Deployment [#strategy-3-cloud-native-deployment]

Deploy on Kubernetes with separate services:

```yaml
# k8s/deployment.yaml
apiVersion: v1
kind: Service
metadata:
  name: objectstack-api
spec:
  selector:
    app: objectstack-api
  ports:
  - port: 3000
---
apiVersion: v1
kind: Service
metadata:
  name: objectui-frontend
spec:
  selector:
    app: objectui-frontend
  ports:
  - port: 80
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: objectstack-api
spec:
  replicas: 3
  template:
    spec:
      containers:
      - name: api
        image: myregistry/objectstack-api:latest
        env:
        - name: DATABASE_URL
          value: postgresql://...
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: objectui-frontend
spec:
  replicas: 2
  template:
    spec:
      containers:
      - name: frontend
        image: myregistry/objectui-frontend:latest
        env:
        - name: API_URL
          value: http://objectstack-api:3000
```

## Advanced Integration Patterns [#advanced-integration-patterns]

### Custom Component Registration [#custom-component-registration]

```typescript
// Register custom components with ObjectUI
import { ComponentRegistry } from '@object-ui/core';

ComponentRegistry.register('my-custom-widget', MyCustomWidget, {
  namespace: 'custom',
  lazy: true
});

// Use in schema
{
  type: 'my-custom-widget',
  config: {
    // custom props
  }
}
```

### Event Handling & Callbacks [#event-handling--callbacks]

```typescript
{
  type: 'object-grid',
  objectName: 'contact',
  dataSource,
  callbacks: {
    onRowClicked: (event) => {
      // Navigate to detail page
      window.location.href = `/contact/${event.data.id}`;
    },
    onCellValueChanged: async (event) => {
      // Auto-save on edit
      await dataSource.update('contact', event.data.id, {
        [event.column.field]: event.newValue
      });
    }
  }
}
```

### Real-time Updates with WebSockets [#real-time-updates-with-websockets]

```typescript
// Configure WebSocket connection
const adapter = new ObjectStackAdapter({
  baseUrl: 'http://localhost:3000/api',
  websocket: {
    enabled: true,
    url: 'ws://localhost:3000/ws'
  }
});

// Subscribe to real-time updates
adapter.subscribe('contact', (event) => {
  if (event.type === 'create' || event.type === 'update') {
    // Refresh grid
    gridRef.current?.refresh();
  }
});
```

## Migration from Other Platforms [#migration-from-other-platforms]

### From Retool [#from-retool]

```typescript
// Retool table → ObjectUI Grid
{
  type: 'object-grid',
  objectName: 'users',
  dataSource,
  editable: true,
  rowSelection: 'multiple',
  exportConfig: { enabled: true }
}
```

### From Appsmith [#from-appsmith]

```typescript
// Appsmith form → ObjectUI form
{
  type: 'object-form',
  objectName: 'contact',
  dataSource,
  mode: 'create',
  fieldNames: ['name', 'email', 'phone', 'company'],
  onSubmit: async (data) => {
    await dataSource.create('contact', data);
  }
}
```

### From Mendix [#from-mendix]

```typescript
// Mendix page → ObjectUI page
{
  type: 'page',
  template: 'header-sidebar-main',
  header: { /* ... */ },
  sidebar: { /* ... */ },
  main: {
    type: 'tabs',
    items: [
      { label: 'Overview', content: { /* ... */ } },
      { label: 'Details', content: { /* ... */ } }
    ]
  }
}
```

## Performance Optimization [#performance-optimization]

### Bundle Optimization [#bundle-optimization]

```typescript
// Lazy load plugins
const plugins = {
  grid: () => import('@object-ui/plugin-grid'),
  charts: () => import('@object-ui/plugin-charts'),
  kanban: () => import('@object-ui/plugin-kanban')
};

// Load on demand
await plugins.grid();
```

### Caching Strategy [#caching-strategy]

```typescript
const adapter = new ObjectStackAdapter({
  baseUrl: 'http://localhost:3000/api',
  cache: {
    enabled: true,
    ttl: 60000, // 1 minute
    strategies: {
      'contact': 'stale-while-revalidate',
      'sys_user': 'cache-first'
    }
  }
});
```

## Testing & Quality Assurance [#testing--quality-assurance]

### Unit Tests [#unit-tests]

```typescript
import { render } from '@testing-library/react';
import { SchemaRenderer } from '@object-ui/react';

test('renders contact grid', () => {
  const { getByText } = render(
    <SchemaRenderer
      schema={{
        type: 'object-grid',
        objectName: 'contact',
        dataSource: mockDataSource
      }}
    />
  );
  expect(getByText('Contact')).toBeInTheDocument();
});
```

### Integration Tests [#integration-tests]

```typescript
import { test, expect } from '@playwright/test';

test('create contact workflow', async ({ page }) => {
  await page.goto('http://localhost:3000/console/contacts');
  await page.click('button:has-text("New Contact")');
  await page.fill('[name="name"]', 'John Doe');
  await page.fill('[name="email"]', 'john@example.com');
  await page.click('button:has-text("Save")');
  await expect(page.locator('text=John Doe')).toBeVisible();
});
```

## Resources [#resources]

* [ObjectStack Documentation](https://docs.objectstack.ai)
* [ObjectUI Components Reference](/docs/components)
* [ObjectQL Schemas](/docs/api/schema-reference#objectql-schemas)
* [Example: CRM Application](/examples/crm)
* [Example: Kitchen Sink](/examples/kitchen-sink)

## Support [#support]

* GitHub Issues: [https://github.com/objectstack-ai/objectui/issues](https://github.com/objectstack-ai/objectui/issues)
* Discord Community: [https://discord.gg/objectui](https://discord.gg/objectui)
* Email: [hello@objectui.org](mailto:hello@objectui.org)


# Custom Plugin Development



This guide walks you through creating custom ObjectUI plugins — from scaffolding to publishing. Plugins extend ObjectUI with new view types, field widgets, or complex interactive components while keeping your application bundle lean through lazy loading.

## What Is an ObjectUI Plugin? [#what-is-an-objectui-plugin]

A plugin is a self-contained package that registers one or more components into the [Component Registry](./component-registry.md). When a JSON schema references a plugin's component type, the renderer resolves and renders it automatically.

Plugins differ from regular components in two ways:

* **Lazy-loaded** — heavy dependencies are code-split and fetched on demand.
* **Self-registering** — importing the package is enough; no manual wiring required.

Official plugins (`@object-ui/plugin-grid`, `@object-ui/plugin-kanban`, `@object-ui/plugin-charts`, etc.) all follow this pattern, and your custom plugins should too.

## Plugin Anatomy [#plugin-anatomy]

Every plugin has three key parts:

```
packages/plugin-board/
├── src/
│   ├── index.tsx          # Entry point: lazy wrapper + ComponentRegistry.register()
│   ├── BoardImpl.tsx      # Heavy implementation (imported lazily)
│   ├── BoardImpl.test.tsx # Tests
│   └── types.ts           # TypeScript interfaces & schema types
├── package.json
├── vite.config.ts
├── tsconfig.json
└── README.md
```

| File            | Role                                                                                                       |
| --------------- | ---------------------------------------------------------------------------------------------------------- |
| `index.tsx`     | Lightweight entry — sets up `React.lazy()`, `Suspense` fallback, and calls `ComponentRegistry.register()`. |
| `BoardImpl.tsx` | The actual renderer. All heavy dependencies live here so they are tree-shaken from the initial bundle.     |
| `types.ts`      | Schema interfaces extending `BaseSchema` from `@object-ui/types`.                                          |

## Scaffolding With the CLI [#scaffolding-with-the-cli]

The fastest way to start is the `create-plugin` generator:

```bash
npx @object-ui/create-plugin board --description "Kanban-style board view"

# Or with pnpm / npm create aliases:
pnpm create @object-ui/plugin board
npm create @object-ui/plugin board
```

This produces a ready-to-build plugin under `packages/plugin-board/` with the correct `package.json`, Vite config, test file, and registry call already in place.

After scaffolding, install dependencies:

```bash
pnpm install
```

## Implementing a Custom View Plugin [#implementing-a-custom-view-plugin]

Let's build a **board** view plugin that renders items in columns (similar to a Kanban but simplified).

### 1. Define the Schema Types [#1-define-the-schema-types]

```typescript
// src/types.ts
import type { BaseSchema } from '@object-ui/types';

export interface BoardColumn {
  id: string;
  title: string;
}

export interface BoardItem {
  id: string;
  columnId: string;
  title: string;
  description?: string;
}

export interface BoardSchema extends BaseSchema {
  type: 'board';
  columns: BoardColumn[];
  items: BoardItem[];
  onItemMove?: (itemId: string, toColumnId: string) => void;
}

export interface BoardProps {
  schema: BoardSchema;
  className?: string;
}
```

### 2. Build the Implementation [#2-build-the-implementation]

```tsx
// src/BoardImpl.tsx
import React from 'react';
import { Card, CardHeader, CardTitle, CardContent } from '@object-ui/components';
import { cn } from '@object-ui/components';
import type { BoardProps } from './types';

export default function BoardImpl({ schema, className }: BoardProps) {
  const { columns, items } = schema;

  return (
    <div className={cn('grid gap-4', className)} style={{ gridTemplateColumns: `repeat(${columns.length}, 1fr)` }}>
      {columns.map((col) => (
        <div key={col.id} className="flex flex-col gap-2">
          <h3 className="text-sm font-semibold text-muted-foreground">{col.title}</h3>
          {items
            .filter((item) => item.columnId === col.id)
            .map((item) => (
              <Card key={item.id}>
                <CardHeader className="p-3">
                  <CardTitle className="text-sm">{item.title}</CardTitle>
                </CardHeader>
                {item.description && (
                  <CardContent className="p-3 pt-0 text-xs text-muted-foreground">
                    {item.description}
                  </CardContent>
                )}
              </Card>
            ))}
        </div>
      ))}
    </div>
  );
}
```

### 3. Create the Entry Point [#3-create-the-entry-point]

```tsx
// src/index.tsx
import React, { Suspense } from 'react';
import { ComponentRegistry } from '@object-ui/core';
import { Skeleton } from '@object-ui/components';

const LazyBoard = React.lazy(() => import('./BoardImpl'));

export const BoardRenderer: React.FC<{ schema: any; [key: string]: any }> = ({
  schema,
  ...props
}) => (
  <Suspense fallback={<Skeleton className="w-full h-[300px]" />}>
    <LazyBoard schema={schema} {...props} />
  </Suspense>
);

// Auto-register on import
ComponentRegistry.register('board', BoardRenderer, {
  namespace: 'plugin-board',
  label: 'Board View',
  category: 'plugin',
  inputs: [
    { name: 'columns', type: 'array', label: 'Columns', required: true },
    { name: 'items', type: 'array', label: 'Items', required: true },
  ],
  defaultProps: {
    columns: [
      { id: 'todo', title: 'To Do' },
      { id: 'done', title: 'Done' },
    ],
    items: [],
  },
});

export { default as BoardImpl } from './BoardImpl';
export type { BoardSchema, BoardProps, BoardColumn, BoardItem } from './types';
```

Now any schema with `"type": "board"` will resolve to your component.

## Implementing a Custom Field Widget [#implementing-a-custom-field-widget]

Field widgets follow the `FieldWidgetProps` interface from `@object-ui/fields`.

```typescript
// FieldWidgetProps<T> shape (from packages/fields/src/widgets/types.ts)
type FieldWidgetProps<T = any> = {
  value: T;
  onChange: (val: T) => void;
  field: FieldMetadata;
  readonly?: boolean;
  disabled?: boolean;
  className?: string;
  errorMessage?: string;
};
```

### Example: Color Picker Field [#example-color-picker-field]

```tsx
// src/ColorPickerField.tsx
import React from 'react';
import { Input } from '@object-ui/components';
import type { FieldWidgetProps } from '@object-ui/fields';

export function ColorPickerField({
  value,
  onChange,
  field,
  readonly,
  disabled,
  errorMessage,
}: FieldWidgetProps<string>) {
  if (readonly) {
    return (
      <div className="flex items-center gap-2">
        <span
          className="inline-block h-4 w-4 rounded-full border"
          style={{ backgroundColor: value || '#000' }}
        />
        <span className="text-sm">{value || '—'}</span>
      </div>
    );
  }

  return (
    <div className="flex flex-col gap-1">
      <div className="flex items-center gap-2">
        <input
          type="color"
          value={value || '#000000'}
          onChange={(e) => onChange(e.target.value)}
          disabled={disabled}
          className="h-8 w-8 cursor-pointer rounded border-0 p-0"
        />
        <Input
          value={value || ''}
          onChange={(e) => onChange(e.target.value)}
          placeholder={field?.placeholder || '#000000'}
          disabled={disabled}
          className="font-mono text-sm"
        />
      </div>
      {errorMessage && (
        <span className="text-xs text-destructive">{errorMessage}</span>
      )}
    </div>
  );
}
```

Register it as a field widget:

```tsx
// src/index.tsx
import { ComponentRegistry } from '@object-ui/core';
import { ColorPickerField } from './ColorPickerField';

ComponentRegistry.register('field-color', ColorPickerField, {
  namespace: 'plugin-board',
  label: 'Color Picker',
  category: 'field',
  inputs: [
    { name: 'value', type: 'string', label: 'Value' },
    { name: 'placeholder', type: 'string', label: 'Placeholder' },
  ],
});

export { ColorPickerField };
```

## Using the ComponentRegistry [#using-the-componentregistry]

### Namespaced Registration [#namespaced-registration]

Namespaces prevent type collisions between plugins:

```tsx
import { ComponentRegistry } from '@object-ui/core';

// Register with a namespace — accessible as 'plugin-board:board' AND 'board'
ComponentRegistry.register('board', BoardRenderer, {
  namespace: 'plugin-board',
});

// Explicit lookup by namespace
ComponentRegistry.get('board', 'plugin-board');

// Fallback lookup (works when the type is unambiguous)
ComponentRegistry.get('board');
```

Use `skipFallback: true` in the metadata if you do **not** want the component to be available without a namespace prefix.

### Querying Registered Components [#querying-registered-components]

```tsx
ComponentRegistry.has('board');                              // boolean
ComponentRegistry.getAllTypes();                              // string[]
ComponentRegistry.getNamespaceComponents('plugin-board');     // ComponentConfig[]
```

## Plugin Configuration & Schema Types [#plugin-configuration--schema-types]

Define your schema interface in `types.ts` and extend `BaseSchema`:

```typescript
import type { BaseSchema } from '@object-ui/types';

export interface BoardSchema extends BaseSchema {
  type: 'board';
  columns: BoardColumn[];
  items: BoardItem[];
}
```

Declare `ComponentInput` entries when registering so the visual designer can offer a property panel:

```tsx
ComponentRegistry.register('board', BoardRenderer, {
  inputs: [
    { name: 'columns', type: 'array', label: 'Columns', required: true },
    { name: 'items', type: 'array', label: 'Items', required: true },
    {
      name: 'layout',
      type: 'enum',
      label: 'Layout',
      enum: ['horizontal', 'vertical'],
      defaultValue: 'horizontal',
    },
  ],
});
```

## Testing Plugins [#testing-plugins]

ObjectUI uses **Vitest + React Testing Library**. Place tests next to the implementation.

```tsx
// src/BoardImpl.test.tsx
import { describe, it, expect } from 'vitest';
import { render, screen } from '@testing-library/react';
import BoardImpl from './BoardImpl';

const schema = {
  type: 'board' as const,
  columns: [
    { id: 'todo', title: 'To Do' },
    { id: 'done', title: 'Done' },
  ],
  items: [
    { id: '1', columnId: 'todo', title: 'Write tests' },
    { id: '2', columnId: 'done', title: 'Ship plugin' },
  ],
};

describe('BoardImpl', () => {
  it('renders all columns', () => {
    render(<BoardImpl schema={schema} />);
    expect(screen.getByText('To Do')).toBeInTheDocument();
    expect(screen.getByText('Done')).toBeInTheDocument();
  });

  it('renders items in correct columns', () => {
    render(<BoardImpl schema={schema} />);
    expect(screen.getByText('Write tests')).toBeInTheDocument();
    expect(screen.getByText('Ship plugin')).toBeInTheDocument();
  });

  it('handles empty items gracefully', () => {
    render(<BoardImpl schema={{ ...schema, items: [] }} />);
    expect(screen.getByText('To Do')).toBeInTheDocument();
  });
});
```

Run tests:

```bash
pnpm vitest run packages/plugin-board
```

## Publishing Guidelines [#publishing-guidelines]

### Package Checklist [#package-checklist]

Before publishing, verify:

* [ ] `package.json` has correct `name`, `version`, `exports`, and `peerDependencies`.
* [ ] `react` and `react-dom` are **peer** dependencies, not direct dependencies.
* [ ] `@object-ui/core` and `@object-ui/components` are in `devDependencies` (or `peerDependencies`).
* [ ] `vite.config.ts` marks React and ObjectUI packages as **external**.
* [ ] Types are exported via `"types"` field in `package.json`.
* [ ] All tests pass (`pnpm vitest run`).
* [ ] The entry point is lightweight — heavy code lives in `*Impl.tsx` files.

### Build & Verify [#build--verify]

```bash
pnpm build --filter @object-ui/plugin-board
ls -lh packages/plugin-board/dist/
```

The entry chunk should be under 1 KB; the lazy chunk carries the bulk.

### Publish [#publish]

```bash
cd packages/plugin-board
npm publish --access public
```

### Consumers Install & Use [#consumers-install--use]

```bash
pnpm add @object-ui/plugin-board
```

```tsx
// app/main.tsx — import once, auto-registers
import '@object-ui/plugin-board';
```

```json
{
  "type": "board",
  "columns": [
    { "id": "todo", "title": "To Do" },
    { "id": "done", "title": "Done" }
  ],
  "items": [
    { "id": "1", "columnId": "todo", "title": "Write docs" }
  ]
}
```

## Related Documentation [#related-documentation]

* [Component Registry](./component-registry.md) — registry internals and advanced usage
* [Plugins Overview](./plugins.md) — official plugin catalog
* [Schema Rendering](./schema-rendering.md) — how schemas become UI
* [Fields Guide](./fields.md) — built-in field widgets and `FieldWidgetProps`


# Plugins



Object UI supports a powerful plugin system that allows you to extend the framework with additional components. Plugins are separate packages that load on-demand, keeping your main application bundle small while providing rich functionality.

## Overview [#overview]

Plugins are lazy-loaded component packages that:

* **Auto-register** components when imported
* **Lazy-load** heavy dependencies on-demand
* **Keep bundles small** - only load when needed
* **Are type-safe** with full TypeScript support
* **Follow best practices** with built-in loading states

## Official Plugins [#official-plugins]

Object UI provides 14+ official plugins for common use cases:

### Data Visualization & Dashboards [#data-visualization--dashboards]

#### [@object-ui/plugin-charts](../plugins/plugin-charts.md) [#object-uiplugin-charts]

Data visualization components powered by Recharts.

* Bar, line, area, and pie charts
* Responsive design
* Customizable colors
* Lazy-loaded (\~80 KB)

[Read full documentation →](../plugins/plugin-charts.md)

***

#### [@object-ui/plugin-dashboard](../plugins/plugin-dashboard.md) [#object-uiplugin-dashboard]

Dashboard layouts with metric cards and widgets.

* Dashboard grid layouts
* Metric/KPI cards with trends
* Widget system
* Lazy-loaded (\~22 KB)

[Read full documentation →](../plugins/plugin-dashboard.md)

***

#### [@object-ui/plugin-timeline](../plugins/plugin-timeline.md) [#object-uiplugin-timeline]

Timeline component with multiple layout variants.

* Vertical, horizontal layouts
* Customizable markers
* Date formatting
* Lazy-loaded (\~20 KB)

[Read full documentation →](../plugins/plugin-timeline.md)

***

#### [@object-ui/plugin-gantt](../plugins/plugin-gantt.md) [#object-uiplugin-gantt]

Gantt chart for project visualization.

* Task dependencies
* Progress tracking
* ObjectQL integration
* Lazy-loaded (\~40 KB)

[Read full documentation →](../plugins/plugin-gantt.md)

***

#### [@object-ui/plugin-calendar](../plugins/plugin-calendar.md) [#object-uiplugin-calendar]

Calendar visualization for events.

* Month/week/day views
* Event management
* ObjectQL integration
* Lazy-loaded (\~25 KB)

[Read full documentation →](../plugins/plugin-calendar.md)

***

#### [@object-ui/plugin-map](../plugins/plugin-map.md) [#object-uiplugin-map]

Map visualization with markers.

* Interactive maps
* Location markers
* ObjectQL integration
* Lazy-loaded (\~60 KB)

[Read full documentation →](../plugins/plugin-map.md)

***

### Data Management [#data-management]

#### [@object-ui/plugin-grid](../plugins/plugin-grid.md) [#object-uiplugin-grid]

Advanced data grid with sorting, filtering, and pagination.

* Column sorting and filtering
* Pagination controls
* Row selection
* Lazy-loaded (\~45 KB)

[Read full documentation →](../plugins/plugin-grid.md)

***

#### [@object-ui/plugin-form](../plugins/plugin-form.md) [#object-uiplugin-form]

Advanced form builder with validation.

* Multi-step forms
* Field validation
* Custom field types
* Lazy-loaded (\~28 KB)

[Read full documentation →](../plugins/plugin-form.md)

***

#### [@object-ui/plugin-view](../plugins/plugin-view.md) [#object-uiplugin-view]

ObjectQL-integrated views for automatic CRUD.

* Auto-generated forms and grids
* CRUD operations
* Field mapping
* Lazy-loaded (\~35 KB)

[Read full documentation →](../plugins/plugin-view.md)

***

### Content & Editing [#content--editing]

#### [@object-ui/plugin-editor](../plugins/plugin-editor.md) [#object-uiplugin-editor]

Code editor component powered by Monaco Editor.

* Syntax highlighting for 100+ languages
* IntelliSense and code completion
* Multiple themes
* Lazy-loaded (\~120 KB)

[Read full documentation →](../plugins/plugin-editor.md)

***

#### [@object-ui/plugin-markdown](../plugins/plugin-markdown.md) [#object-uiplugin-markdown]

Markdown renderer with GitHub Flavored Markdown support.

* GitHub Flavored Markdown
* XSS protection
* Code syntax highlighting
* Lazy-loaded (\~30 KB)

[Read full documentation →](../plugins/plugin-markdown.md)

***

#### [@object-ui/plugin-chatbot](../plugins/plugin-chatbot.md) [#object-uiplugin-chatbot]

Chat interface component.

* Message history
* User and assistant roles
* Timestamps and avatars
* Responsive floating panel for console assistants
* Inline responding, stop, and retry states
* Lazy-loaded (\~35 KB)

[Read full documentation →](../plugins/plugin-chatbot.md)

***

### Workflows & Tasks [#workflows--tasks]

#### [@object-ui/plugin-kanban](../plugins/plugin-kanban.md) [#object-uiplugin-kanban]

Kanban board component with drag-and-drop powered by @dnd-kit.

* Drag and drop cards between columns
* Column limits (WIP limits)
* Card badges for status/priority
* Lazy-loaded (\~100 KB)

[Read full documentation →](../plugins/plugin-kanban.md)

***

## How Plugins Work [#how-plugins-work]

### Lazy Loading Architecture [#lazy-loading-architecture]

Plugins use React's `lazy()` and `Suspense` to load heavy dependencies on-demand:

```typescript
// The plugin structure
import React, { Suspense } from 'react'
import { Skeleton } from '@object-ui/components'

// Lazy load the heavy implementation
const LazyEditor = React.lazy(() => import('./MonacoImpl'))

export const CodeEditorRenderer = (props) => (
  <Suspense fallback={<Skeleton className="w-full h-[400px]" />}>
    <LazyEditor {...props} />
  </Suspense>
)
```

**Benefits:**

* **Smaller initial bundle**: Main app loads faster
* **Progressive loading**: Components load when needed
* **Better UX**: Loading skeletons while chunks download
* **Automatic code splitting**: Vite handles chunking

### Bundle Impact [#bundle-impact]

| Plugin           | Initial Load | Lazy Load | Description            |
| ---------------- | ------------ | --------- | ---------------------- |
| plugin-editor    | \~0.2 KB     | \~120 KB  | Monaco editor          |
| plugin-charts    | \~0.2 KB     | \~80 KB   | Recharts visualization |
| plugin-kanban    | \~0.2 KB     | \~100 KB  | Drag-and-drop board    |
| plugin-markdown  | \~0.2 KB     | \~30 KB   | Markdown rendering     |
| plugin-dashboard | \~0.2 KB     | \~22 KB   | Dashboard layouts      |
| plugin-form      | \~0.2 KB     | \~28 KB   | Form builder           |
| plugin-grid      | \~0.2 KB     | \~45 KB   | Data grid              |
| plugin-view      | \~0.2 KB     | \~35 KB   | ObjectQL views         |
| plugin-timeline  | \~0.2 KB     | \~20 KB   | Timeline layouts       |
| plugin-chatbot   | \~0.2 KB     | \~35 KB   | Chat interface         |
| plugin-calendar  | \~0.2 KB     | \~25 KB   | Calendar views         |
| plugin-gantt     | \~0.2 KB     | \~40 KB   | Gantt charts           |
| plugin-map       | \~0.2 KB     | \~60 KB   | Map visualization      |

Without lazy loading, all this code would be in your main bundle!

### Auto-Registration [#auto-registration]

Plugins automatically register their components when imported:

```typescript
// In the plugin's index.tsx
import { ComponentRegistry } from '@object-ui/core'

ComponentRegistry.register('code-editor', CodeEditorRenderer)
```

You just need to import the plugin once:

```typescript
// In your App.tsx or main.tsx
import '@object-ui/plugin-editor'
import '@object-ui/plugin-charts'
import '@object-ui/plugin-kanban'
import '@object-ui/plugin-markdown'
import '@object-ui/plugin-dashboard'
import '@object-ui/plugin-form'
import '@object-ui/plugin-grid'
// ... import other plugins as needed
```

Now all plugin components are available in your schemas!

## Creating Custom Plugins [#creating-custom-plugins]

You can create your own plugins following the same pattern:

### 1. Create Package Structure [#1-create-package-structure]

```bash
mkdir -p packages/plugin-myfeature/src
cd packages/plugin-myfeature
```

### 2. Create Heavy Implementation [#2-create-heavy-implementation]

```typescript
// src/MyFeatureImpl.tsx
import HeavyLibrary from 'heavy-library'

export default function MyFeatureImpl(props) {
  return <HeavyLibrary {...props} />
}
```

### 3. Create Lazy Wrapper [#3-create-lazy-wrapper]

```typescript
// src/index.tsx
import React, { Suspense } from 'react'
import { ComponentRegistry } from '@object-ui/core'
import { Skeleton } from '@object-ui/components'

// Lazy load implementation
const LazyFeature = React.lazy(() => import('./MyFeatureImpl'))

// Create renderer with Suspense
export const MyFeatureRenderer = (props) => (
  <Suspense fallback={<Skeleton className="w-full h-[300px]" />}>
    <LazyFeature {...props} />
  </Suspense>
)

// Auto-register
ComponentRegistry.register('my-feature', MyFeatureRenderer)

// Export for manual use
export const myFeatureComponents = {
  'my-feature': MyFeatureRenderer
}
```

### 4. Add TypeScript Types [#4-add-typescript-types]

```typescript
// src/types.ts
import type { BaseSchema } from '@object-ui/types'

export interface MyFeatureSchema extends BaseSchema {
  type: 'my-feature'
  customProp?: string
}
```

### 5. Configure Build [#5-configure-build]

```typescript
// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { resolve } from 'path'

export default defineConfig({
  plugins: [react()],
  build: {
    lib: {
      entry: resolve(__dirname, 'src/index.tsx'),
      name: 'ObjectUIPluginMyFeature',
      fileName: (format) => `index.${format}.js`
    },
    rollupOptions: {
      external: [
        'react',
        'react-dom',
        '@object-ui/components',
        '@object-ui/core'
      ],
      output: {
        globals: {
          react: 'React',
          'react-dom': 'ReactDOM'
        }
      }
    }
  }
})
```

### 6. Add Package.json [#6-add-packagejson]

```json
{
  "name": "@object-ui/plugin-myfeature",
  "version": "1.0.0",
  "type": "module",
  "main": "./dist/index.umd.js",
  "module": "./dist/index.es.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.es.js",
      "require": "./dist/index.umd.js",
      "types": "./dist/index.d.ts"
    }
  },
  "files": ["dist"],
  "scripts": {
    "build": "vite build && tsc --emitDeclarationOnly"
  },
  "peerDependencies": {
    "react": "^18.0.0 || ^19.0.0",
    "react-dom": "^18.0.0 || ^19.0.0"
  },
  "dependencies": {
    "heavy-library": "^1.0.0"
  },
  "devDependencies": {
    "@object-ui/components": "workspace:*",
    "@object-ui/core": "workspace:*",
    "@object-ui/types": "workspace:*",
    "typescript": "^5.0.0",
    "vite": "^5.0.0"
  }
}
```

## Best Practices [#best-practices]

### 1. Keep Entry Point Light [#1-keep-entry-point-light]

The main index file should only contain:

* Lazy loading wrapper
* Component registration
* Type exports

Heavy imports go in the `*Impl.tsx` file.

### 2. Provide Good Loading States [#2-provide-good-loading-states]

Always show a meaningful skeleton while loading:

```typescript
<Suspense fallback={
  <Skeleton className="w-full h-[400px]" />
}>
  <LazyComponent {...props} />
</Suspense>
```

### 3. Export Types [#3-export-types]

Make your plugin type-safe:

```typescript
export type { MyFeatureSchema } from './types'
```

### 4. Document Your Plugin [#4-document-your-plugin]

Include a README with:

* Installation instructions
* Usage examples
* Schema API reference
* Bundle size information

### 5. Test Lazy Loading [#5-test-lazy-loading]

Verify that:

* The main bundle is small (\~200 bytes)
* The lazy chunk is separate
* Components load correctly when rendered

```bash
pnpm build
ls -lh dist/
```

## Plugin vs Component Package [#plugin-vs-component-package]

**Use a Plugin when:**

* The component depends on large libraries (>50 KB)
* Not all apps will use this component
* You want on-demand loading

**Use regular Components when:**

* The component is lightweight
* Most apps will use it
* It's part of core functionality

## Troubleshooting [#troubleshooting]

### Plugin not loading [#plugin-not-loading]

Check that you imported it in your app:

```typescript
import '@object-ui/plugin-myfeature'
```

### TypeScript errors [#typescript-errors]

Make sure types are exported:

```typescript
export type { MyFeatureSchema } from '@object-ui/plugin-myfeature'
```

### Bundle size too large [#bundle-size-too-large]

Check that the implementation is in a separate file:

```
✅ src/index.tsx        (light, uses React.lazy)
✅ src/MyFeatureImpl.tsx (heavy, imported lazily)
```

### Component not registering [#component-not-registering]

Check that ComponentRegistry.register() is called at the module level:

```typescript
// ✅ Good - runs on import
ComponentRegistry.register('my-feature', MyFeatureRenderer)

// ❌ Bad - never runs
export function registerComponents() {
  ComponentRegistry.register('my-feature', MyFeatureRenderer)
}
```

## Related Documentation [#related-documentation]

* [Component Registry](./component-registry.md) - Understanding the registry
* [Schema Rendering](./schema-rendering.md) - How schemas become UI
* [Lazy-Loaded Plugins Architecture](./lazy-loading.md) - Deep dive
* [Creating Components](/spec/component-package.md) - Component development
* **[Create Plugin Utility](/docs/utilities/create-plugin)** - Scaffold new plugins quickly
* **[CLI Tool](/docs/utilities/cli)** - Test plugins with the CLI
* **[All Utilities](/docs/utilities)** - Complete toolkit for development

## Next Steps [#next-steps]

1. Install official plugins you need
2. Try creating a custom plugin
3. Share your plugins with the community
4. Contribute new plugins to Object UI


# Public Forms



# Public Forms [#public-forms]

`@object-ui/plugin-form` ships an `EmbeddableForm` component that renders a
public-facing form (contact us, lead capture, signup, RSVP) with the security
defaults you'd expect from Airtable Forms, Typeform or HubSpot Forms — without
asking app authors to bolt them on themselves.

The console exposes a turnkey route at `/f/:slug` (`FormPage`) that loads
a `FormView` spec from the server's `GET /api/v1/forms/:slug` resolver and
renders the merged form. The same component also serves authed internal
forms at `/forms/:name` (`mode="internal"`), reading the FormView spec
from `/api/v1/meta/view/:name` and posting to `/api/v1/data/:object`.

## Quick start [#quick-start]

```tsx
import { EmbeddableForm } from '@object-ui/plugin-form';
import { restDataSource } from '@object-ui/data-rest';

<EmbeddableForm
  config={{
    formId: 'contact-us',
    objectName: 'lead',
    title: 'Contact us',
    description: "We'd love to hear from you.",
    customFields: [
      { name: 'name',    label: 'Full name', type: 'text',  required: true },
      { name: 'email',   label: 'Email',     type: 'email', required: true },
      { name: 'message', label: 'Message',   type: 'textarea', rows: 4 },
    ],
    consent: { required: true },
    privacyPolicyUrl: '/legal/privacy',
    allowedPrefillFields: ['email'],
    allowedRedirectHosts: ['example.com', '*.example.com'],
    thankYouPage: {
      title: 'Thanks!',
      message: "We'll get back to you shortly.",
      redirectUrl: 'https://example.com/thank-you',
    },
  }}
  dataSource={restDataSource}
/>
```

## Security defaults (at a glance) [#security-defaults-at-a-glance]

| Defence                                          | Default                                                                  | Config key                                                   |
| ------------------------------------------------ | ------------------------------------------------------------------------ | ------------------------------------------------------------ |
| **Honeypot field** (silent fake-success on bots) | On                                                                       | `honeypot` (string to rename, `false` to disable)            |
| **Min-fill-time guard**                          | 1500 ms                                                                  | `minFillTime` (ms, `0` to disable)                           |
| **URL prefill whitelist**                        | *none* — prefill is fully off                                            | `allowedPrefillFields: string[]`                             |
| **Open-redirect guard**                          | Same-origin only                                                         | `allowedRedirectHosts: string[]` (supports `*.example.com`)  |
| **Default `maxLength`**                          | text 200 · email 254 · url 2048 · phone 32 · textarea/markdown/html 5000 | Per-field `maxLength` overrides                              |
| **GDPR consent gate**                            | Off (opt-in)                                                             | `consent: { required, label }` + `privacyPolicyUrl`          |
| **CAPTCHA token**                                | Off (opt-in)                                                             | `captchaToken` (string sent as `_captcha`)                   |
| **Demo mode (`?demo=1`)**                        | DEV only                                                                 | gated by `import.meta.env.DEV` in `EmbeddableForm` consumers |

All gates run **before** the network call. If the consent gate or min-fill
timer trips, the backend is never contacted. The honeypot silently shows the
thank-you page so bots can't tell they failed.

## Configuration reference [#configuration-reference]

```ts
interface EmbeddableFormConfig {
  formId: string;
  objectName: string;
  title?: string;
  description?: string;

  // Fields — either from a registered schema or inline
  fields?: string[];
  customFields?: FormField[];

  // Anti-spam
  honeypot?: string | false;            // field name (default '_company_website_2'), false disables
  minFillTime?: number;                 // ms before submit allowed (default 1500)
  captchaToken?: string;                // forwarded as payload._captcha

  // Prefill & redirect hardening
  allowedPrefillFields?: string[];      // empty/undefined → no URL prefill
  allowedRedirectHosts?: string[];      // supports '*.example.com'

  // GDPR
  consent?: { required?: boolean; label?: string };
  privacyPolicyUrl?: string;

  // UI
  branding?: { logo?: string; primaryColor?: string; coverImage?: string };
  thankYouPage?: { title?: string; message?: string; redirectUrl?: string; redirectDelay?: number };
  texts?: EmbeddableFormTexts;          // i18n-friendly string overrides
}
```

### URL prefill (safe-by-default) [#url-prefill-safe-by-default]

Public form URLs are user-controlled, so prefill is **off** unless you
explicitly opt fields in:

```tsx
<EmbeddableForm
  config={{
    /* … */
    allowedPrefillFields: ['email', 'utm_source'],
  }}
/>
```

With the snippet above, visiting `/f/contact?email=alice@x.com&secret=foo`
fills the `email` field and silently ignores `secret`. The
`prefillParams` prop (used by trusted hosts such as the console)
bypasses this whitelist.

### Open-redirect guard [#open-redirect-guard]

`thankYouPage.redirectUrl` is validated against the current origin **plus**
`allowedRedirectHosts` before navigation. Wildcards like `*.example.com`
match subdomains; the apex itself must be listed explicitly. Dangerous
schemes (`javascript:`, `data:`) are always rejected.

### GDPR consent [#gdpr-consent]

```tsx
consent: { required: true, label: 'I agree to the privacy policy.' }
privacyPolicyUrl: '/legal/privacy'
```

When `required: true`, submitting before the box is ticked shows
`texts.consentRequired` and the network call is suppressed.

### Honeypot [#honeypot]

The hidden input is rendered off-screen with `tabIndex={-1}` and
`autocomplete="off"`. Bots that blindly fill every field trigger a
**silent fake-success** — the visitor sees the thank-you screen, but
`dataSource.create()` is never called. Honeypot data is also stripped
from the payload defensively.

### Min-fill-time [#min-fill-time]

Genuine users take more than \~1.5 s to read and fill a form. Faster
submissions are soft-rejected with `texts.rateLimited` rather than a
hard error, so legit speed-typers can simply retry.

### CAPTCHA hook [#captcha-hook]

`EmbeddableForm` doesn't bundle a specific provider. Mount your
preferred widget (hCaptcha, Turnstile, reCAPTCHA) and feed the token in:

```tsx
const [token, setToken] = useState<string>();
<EmbeddableForm config={{ /* … */ captchaToken: token }} dataSource={ds} />
```

The token is forwarded as `payload._captcha` for server-side validation.

## i18n [#i18n]

`EmbeddableForm` is i18n-agnostic — every user-visible string is
overridable via `config.texts: EmbeddableFormTexts`. The console wires
this up through `@object-ui/i18n`:

```tsx
const { t } = useObjectTranslation();
<EmbeddableForm config={{
  /* … */
  texts: {
    submit:           t('publicForm.submit'),
    submitting:       t('publicForm.submitting'),
    consentRequired:  t('publicForm.consentRequired'),
    rateLimited:      t('publicForm.rateLimited'),
    redirectBlocked:  t('publicForm.redirectBlocked'),
    requiredHint:     t('publicForm.requiredHint'),
    /* … */
  },
}} />
```

## Console route — `/f/:slug` and `/forms/:name` [#console-route--fslug-and-formsname]

The console's `FormPage` component renders both modes from the same
spec-merging code path:

* **`/f/:slug`** (public, anonymous) — loads `GET /api/v1/forms/:slug` which
  resolves the `FormView` whose `sharing.publicLink` matches the slug, then
  submits to `POST /api/v1/forms/:slug/submit`.
* **`/forms/:name`** (internal, authed) — loads `GET /api/v1/meta/view/:name`
  for the FormView spec plus `GET /api/v1/meta/object/:object` for field
  metadata, then submits to `POST /api/v1/data/:object` with the
  authenticated session cookie.

URL parameters of the form `?prefill_<field>=<value>` populate the matching
fields on mount; the rest of the chrome (label, section columns, post-submit
behaviour) comes from the `FormView` spec itself.

For richer public forms with anti-spam, GDPR consent, prefill whitelisting
and open-redirect protection, host `EmbeddableForm` directly inside your own
route — see the Quick start above.

## Testing [#testing]

Pure helpers (`isRedirectUrlSafe`, `applyDefaultMaxLengths`) are exported
from `@object-ui/plugin-form` for unit testing. See
`packages/plugin-form/src/__tests__/EmbeddableForm.test.tsx` for the
reference test suite covering all gates.


# Quick Start



# Quick Start [#quick-start]

Get up and running with ObjectUI in a small Vite app. This guide installs the core renderer, registers the built-in component packages, and renders a first JSON schema.

## Prerequisites [#prerequisites]

* **Node.js** 20+
* **pnpm** 9+ or npm/yarn
* Basic knowledge of **React** and **TypeScript**

## Step 1: Create a React Project [#step-1-create-a-react-project]

If you don't have an existing React project, create one with Vite:

```bash
pnpm create vite my-app --template react-ts
cd my-app
```

## Step 2: Install ObjectUI [#step-2-install-objectui]

Install the core ObjectUI packages:

```bash
pnpm add @object-ui/react @object-ui/core @object-ui/types @object-ui/components @object-ui/fields
```

Install Tailwind CSS for styling:

```bash
pnpm add -D tailwindcss @tailwindcss/vite
```

## Step 3: Configure Tailwind CSS [#step-3-configure-tailwind-css]

Add Tailwind to your `vite.config.ts`:

```ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  plugins: [react(), tailwindcss()],
});
```

Add to your `src/index.css`:

```css
@import "tailwindcss";
@import "@object-ui/components/style.css";
@import "@object-ui/fields/style.css";

@source "../node_modules/@object-ui/components/**/*.{js,ts,tsx}";
@source "../node_modules/@object-ui/fields/**/*.{js,ts,tsx}";
```

The `@source` lines let Tailwind see the utility classes used by ObjectUI packages.

## Step 4: Render Your First Schema [#step-4-render-your-first-schema]

Replace `src/App.tsx` with:

```tsx
import '@object-ui/components';
import '@object-ui/fields';
import { SchemaRenderer, SchemaRendererProvider } from '@object-ui/react';

const schema = {
  type: 'card',
  title: 'Team Directory',
  description: 'Rendered from JSON metadata',
  className: 'mx-auto max-w-3xl',
  body: {
    type: 'data-table',
    caption: 'Users',
    columns: [
      { header: 'Name', accessorKey: 'name', sortable: true },
      { header: 'Email', accessorKey: 'email' },
      { header: 'Role', accessorKey: 'role' },
    ],
    data: [
      { name: 'Ada Lovelace', email: 'ada@example.com', role: 'Admin' },
      { name: 'Grace Hopper', email: 'grace@example.com', role: 'Editor' },
      { name: 'Katherine Johnson', email: 'katherine@example.com', role: 'Viewer' },
    ],
    pagination: false,
    searchable: false,
  },
} as const;

function App() {
  return (
    <div className="min-h-screen bg-background p-8 text-foreground">
      <SchemaRendererProvider dataSource={{}}>
        <SchemaRenderer schema={schema} />
      </SchemaRendererProvider>
    </div>
  );
}

export default App;
```

Importing `@object-ui/components` and `@object-ui/fields` registers their renderers with the shared `ComponentRegistry`. `SchemaRendererProvider` supplies the data scope used by expressions, smart fields, and data-aware plugins.

## Step 5: Run the App [#step-5-run-the-app]

```bash
pnpm dev
```

Open [http://localhost:5173](http://localhost:5173). You should see a card and data table rendered from JSON.

## What Just Happened? [#what-just-happened]

1. **Schema** - the UI was described as JSON with `type`, visual props, and nested `body`.
2. **Registry** - importing the component packages registered renderers for `card` and `data-table`.
3. **Renderer** - `SchemaRenderer` resolved each `type` and rendered React components.
4. **Provider** - `SchemaRendererProvider` made a data scope available for expressions and plugins.

## Next Steps [#next-steps]

### Add Actions [#add-actions]

Actions are data, not inline functions. Define them in schema events:

```json
{
  "type": "button",
  "label": "Open details",
  "events": {
    "onClick": [
      {
        "action": "navigate",
        "params": {
          "url": "/users/ada"
        }
      }
    ]
  }
}
```

Learn the full action model in [Enhanced Actions](/docs/core/enhanced-actions).

### Connect a Data Source [#connect-a-data-source]

```bash
pnpm add @object-ui/data-objectstack
```

```tsx
import { createObjectStackAdapter } from '@object-ui/data-objectstack';

const dataSource = createObjectStackAdapter({
  baseUrl: 'https://api.example.com'
});
```

Pass the adapter to `SchemaRendererProvider` and let data-aware renderers call the `DataSource` interface. See [Data Connectivity](/docs/guide/data-source).

### Learn More [#learn-more]

* [Architecture Overview](/docs/guide/architecture) — Understand how ObjectUI works
* [Schema Rendering](/docs/guide/schema-rendering) — Deep dive into schema rendering
* [Component Registry](/docs/guide/component-registry) — Customize and extend components
* [Plugins](/docs/guide/plugins) — Add views like Grid, Kanban, Charts
* [Fields Guide](/docs/guide/fields) — Field widgets and cell renderers


# Record Edit Modes



# Record Edit Modes [#record-edit-modes]

ObjectUI's default console shell (`@object-ui/app-shell`) supports two ways
to render the create/edit form for a record:

* **Modal** (default) — the form opens in an overlay dialog above the
  current view. Best for short forms, quick edits, and contextual data
  entry.
* **Page** — the form takes over a full route. Best for long forms,
  multi-tab or wizard layouts, or anywhere you need a deep-linkable URL
  that survives a refresh and integrates with the browser back button.

Both modes use the same `<ObjectForm>` pipeline under the hood, so all
field types, sections, validations, and visibility expressions work
identically in either mode.

## Choosing a mode [#choosing-a-mode]

Set `editMode` on the object metadata:

```jsonc
// metadata/objects/account.json
{
  "name": "account",
  "label": "Account",
  "editMode": "page",       // "modal" (default) | "page"
  "fields": {
    "name":     { "type": "text",     "label": "Name", "required": true },
    "industry": { "type": "picklist", "label": "Industry" },
    "owner":    { "type": "lookup",   "label": "Owner", "reference_to": "user" }
  }
}
```

Omitting `editMode` (or setting it to `"modal"`) keeps the existing
behavior — clicking **Create** or **Edit** opens the global `ModalForm`
overlay.

## URL patterns [#url-patterns]

When `editMode: "page"` is set, the console renders the form on a
dedicated route under the active app:

| Action | URL                                                |
| ------ | -------------------------------------------------- |
| Create | `/apps/:appName/:objectName/new`                   |
| Edit   | `/apps/:appName/:objectName/record/:recordId/edit` |

Examples (for an app `sales` and an object `account`):

* Create: `https://your-console.example/apps/sales/account/new`
* Edit:   `https://your-console.example/apps/sales/account/record/0015e000abcd/edit`

These URLs are stable. Users can bookmark them, share them in chat, or
refresh the page mid-edit (the form rehydrates from the URL `:recordId`).

## Triggering the routes from JSON [#triggering-the-routes-from-json]

In addition to the implicit "click create/edit on a list" entry point,
two declarative actions let you open the page-mode routes from any
`<action:button>` in metadata:

```jsonc
{
  "type": "action:button",
  "label": "New Account",
  "icon":  "plus",
  "action": {
    "action": "navigate_create",
    "params": { "objectName": "account" }
  }
}
```

```jsonc
{
  "type": "action:button",
  "label": "Edit",
  "icon":  "pencil",
  "action": {
    "action": "navigate_edit",
    "params": {
      "objectName": "account",
      "recordId":   "${record.id}"
    }
  }
}
```

When invoked from inside an `ObjectView`, the action context already
carries the active `objectName`, so `objectName` may be omitted from the
`params`:

```jsonc
{
  "type": "action:button",
  "label": "New",
  "action": { "action": "navigate_create" }
}
```

## Behavior summary [#behavior-summary]

| Aspect                  | Modal       | Page                       |
| ----------------------- | ----------- | -------------------------- |
| Default                 | ✅           | —                          |
| Deep-linkable URL       | ❌           | ✅                          |
| Survives refresh        | ❌           | ✅                          |
| Back button closes form | n/a         | ✅                          |
| Best for                | quick edits | long / multi-section forms |

## Migrating an existing object [#migrating-an-existing-object]

The change is additive — existing apps continue to work unchanged. To
migrate a single object to page mode:

1. Add `"editMode": "page"` to the object metadata.
2. (Optional) Adjust the form layout — page mode pairs well with
   `formType: "tabbed"` or `formType: "wizard"` for long forms.
3. Reload the console. Existing **Create** / **Edit** entry points
   automatically route to the new pages; no UI code changes required.

## See also [#see-also]

* [`@object-ui/app-shell` README](https://www.objectui.org/docs/layout/app-shell)
* [`ObjectForm` API](../plugins/plugin-form.md)
* [Schema rendering](./schema-rendering.md)


# Release Notes



# Release Notes [#release-notes]

This page summarises every released version of ObjectUI. For the granular
package-level changelog, see the monorepo
[CHANGELOG.md](https://github.com/objectstack-ai/objectui/blob/main/CHANGELOG.md).

## v3.3.0 — 2026-04-17 · First Official Release 🚀 [#v330--2026-04-17--first-official-release-]

v3.3.0 is the **first official release** of ObjectUI published for third-party
consumption. All 39 packages under `packages/*` are now published to npm with
complete release metadata and aligned with `@objectstack/spec` ^4.0.4 and
`@objectstack/client` v3.3.0.

### Highlights [#highlights]

* **39 published packages** (`@object-ui/*`) with
  standardized `package.json` metadata, per-package `LICENSE` and
  `CHANGELOG.md`.
* **Standard README template** applied across every package (Installation →
  Quick Start → API → Compatibility → Links → License).
* **Refreshed docs site** with up-to-date architecture overview, plugin
  coverage and schema reference.
* **Thin integration packages** — `@object-ui/app-shell` (\~50 KB) and
  `@object-ui/providers` (\~10 KB) enable third-party integrations without
  inheriting the full console.
* **Spec v4 alignment** — plain-string `label` types across Navigation
  schemas; Protocol bridges (`DndProtocol`, `KeyboardProtocol`,
  `NotificationProtocol`) updated.
* **Unified Copilot Skills** — single `skills/objectui/` tree aligned with
  shadcn/ui best practices.

### Upgrade Notes [#upgrade-notes]

If you were pinning to the earlier `0.x` prerelease tags:

1. Bump every `@object-ui/*` dependency to `^3.3.0`.
2. Ensure peer dependencies match the new baselines
   (`react ^18 || ^19`, `react-dom ^18 || ^19`, TypeScript `>=5.0`).
3. Replace any `i18n` label objects (`{ key, defaultValue }`) on Navigation
   schemas with plain strings — runtime `resolveI18nLabel()` still handles
   both formats for backward compatibility.
4. Remove imports of the deprecated `ViewDesigner` — its capabilities are now
   delivered by `ViewConfigPanel`.

### Compatibility Matrix [#compatibility-matrix]

| Package               | Version          |
| --------------------- | ---------------- |
| `@object-ui/*`        | `3.3.0`          |
| `@objectstack/spec`   | `^4.0.4`         |
| `@objectstack/client` | `3.3.0`          |
| React                 | `18.x` or `19.x` |
| Node.js               | `≥ 18`           |
| TypeScript            | `≥ 5.0` (strict) |
| Tailwind CSS          | `≥ 3.4`          |

## Previous Versions [#previous-versions]

See the [monorepo CHANGELOG](https://github.com/objectstack-ai/objectui/blob/main/CHANGELOG.md)
for the full history, including the `0.x` development series.


# Schema Catalog





# Schema Catalog [#schema-catalog]

Every interactive demo on this site renders a JSON schema that lives in
[`@object-ui/example-schema-catalog`](https://github.com/objectstack-ai/objectui/tree/main/examples/schema-catalog).
This page is the visual gallery over that catalog — live thumbnails for
every entry, grouped by domain. Click a card to open a full interactive
preview with the JSON, copy a stable id, or grab a ready-to-paste
`<SchemaExample id="…" />` snippet for any MDX page.

## How the catalog works [#how-the-catalog-works]

* **Source of truth.** Each schema lives as a single `.json` file under
  `examples/schema-catalog/src/schemas/<category>/<id>.json` and is
  imported into the registry by `examples/schema-catalog/src/index.ts`.
* **One id, one schema.** Ids are stable (e.g. `auth/login-simple`). MDX
  pages reference schemas with `<SchemaExample id="auth/login-simple" />`,
  which looks the schema up via `getExample(id)` from the catalog package.
* **Smoke-tested.** The catalog ships a Vitest suite that resolves every
  id and instantiates every schema; CI fails if any entry breaks. Adding a
  schema is a one-file change; renaming or deleting one fails CI loudly.
* **Not published.** The catalog package is `private: true` — it is a
  test/docs fixture, not a runtime dependency for consuming apps.

## Browse [#browse]

<SchemaCatalogIndex />

## Adding a new example [#adding-a-new-example]

1. Drop the JSON under
   `examples/schema-catalog/src/schemas/<category>/<your-id>.json`.

2. Run `pnpm -F @object-ui/example-schema-catalog regenerate` to update
   `src/index.ts` (the import map is generated).

3. Reference it from any MDX page:

   ```mdx
   <SchemaExample id="<category>/<your-id>" />
   ```

4. `pnpm -F @object-ui/example-schema-catalog test` smoke-tests the new
   entry; the same test runs in CI on every push.


# Schema Overview



# Schema Overview [#schema-overview]

ObjectUI provides powerful schemas that enable you to build sophisticated enterprise applications with advanced features like theming, reporting, reusable components, and complex workflows. This guide provides an overview of all available schemas and helps you get started quickly.

## Key Capabilities [#key-capabilities]

ObjectUI includes enterprise-grade capabilities to build production-ready applications:

* **Application Structure** - Define complete multi-page applications with navigation
* **Dynamic Theming** - Brand your applications with custom themes and light/dark modes
* **Advanced Actions** - Build complex workflows with API calls, chaining, and conditions
* **Enterprise Reporting** - Generate, schedule, and export comprehensive reports
* **Reusable Components** - Create and share component blocks across projects

## Core Schemas [#core-schemas]

### Application Configuration [#application-configuration]

#### [App Schema](/docs/core/app-schema) [#app-schema]

Define your entire application structure with navigation, branding, and global settings.

```typescript
const app: AppSchema = {
  type: 'app',
  title: 'My Application',
  layout: 'sidebar',
  menu: [...],
  actions: [...]
};
```

**Use Cases:**

* Multi-page applications
* Admin dashboards
* CRM systems
* Internal tools

***

### Theming & Branding [#theming--branding]

#### [Theme Schema](/docs/core/theme-schema) [#theme-schema]

Dynamic theming with light/dark modes, color palettes, and typography.

```typescript
const theme: ThemeSchema = {
  type: 'theme',
  mode: 'dark',
  themes: [{
    name: 'professional',
    light: { primary: '#3b82f6', ... },
    dark: { primary: '#60a5fa', ... }
  }]
};
```

**Features:**

* Light/dark mode switching
* 20+ semantic colors
* Typography system
* CSS variables
* Tailwind integration

***

### Advanced Actions [#advanced-actions]

#### [Enhanced Actions](/docs/core/enhanced-actions) [#enhanced-actions]

Powerful action system with AJAX calls, chaining, conditions, and callbacks.

```typescript
const action: ActionSchema = {
  type: 'action',
  actionType: 'ajax',
  api: '/api/submit',
  chain: [...],
  condition: { expression: '${...}', then: {...} },
  onSuccess: {...},
  tracking: {...}
};
```

**New Action Types:**

* **`ajax`** - API calls with full request configuration
* **`confirm`** - Confirmation dialogs
* **`dialog`** - Modal/dialog actions

**Key Features:**

* Action chaining (sequential/parallel)
* Conditional execution (if/then/else)
* Success/failure callbacks
* Event tracking
* Retry logic

***

### Reporting [#reporting]

#### [Report Schema](/docs/core/report-schema) [#report-schema]

Enterprise reports with aggregation, export, and scheduling.

```typescript
const report: ReportSchema = {
  type: 'report',
  title: 'Sales Report',
  fields: [
    { name: 'revenue', aggregation: 'sum' },
    { name: 'orders', aggregation: 'count' }
  ],
  schedule: {
    frequency: 'monthly',
    recipients: ['team@company.com']
  }
};
```

**Features:**

* Field aggregation (sum, avg, count, min, max)
* Multiple export formats (PDF, Excel, CSV)
* Scheduled reports
* Email distribution
* Interactive builder

***

### Reusable Components [#reusable-components]

#### [Block Schema](/docs/blocks/block-schema) [#block-schema]

Reusable component blocks with variables, slots, and marketplace support.

```typescript
const block: BlockSchema = {
  type: 'block',
  meta: { name: 'hero-section', category: 'Marketing' },
  variables: [
    { name: 'title', type: 'string', defaultValue: 'Welcome' }
  ],
  slots: [
    { name: 'content', label: 'Content Area' }
  ],
  template: { type: 'div', children: [...] }
};
```

**Features:**

* Typed variables (props)
* Content slots
* Block templates
* Marketplace support
* Version control

***

## Quick Comparison [#quick-comparison]

| Schema               | Purpose               | Best For                              |
| -------------------- | --------------------- | ------------------------------------- |
| **AppSchema**        | Application structure | Multi-page apps, dashboards           |
| **ThemeSchema**      | Visual theming        | Brand consistency, white-labeling     |
| **Enhanced Actions** | Complex workflows     | API integration, multi-step processes |
| **ReportSchema**     | Data reporting        | Analytics, business intelligence      |
| **BlockSchema**      | Reusable components   | Marketing pages, component libraries  |

## View Components [#view-components]

ObjectUI also includes enhanced view components:

### [Detail View](/docs/plugins/plugin-detail) [#detail-view]

Rich detail pages with sections, tabs, and related records.

### [View Switcher](/docs/components/complex/view-switcher) [#view-switcher]

Toggle between list, grid, kanban, calendar, timeline, and map views.

### [Filter UI](/docs/components/complex/filter-ui) [#filter-ui]

Advanced filtering interface with multiple field types.

### [Sort UI](/docs/components/complex/sort-ui) [#sort-ui]

Sort configuration with multiple fields.

## Installation & Setup [#installation--setup]

### Package Installation [#package-installation]

All schemas are included in `@object-ui/types`. Install it in your project:

```bash
npm install @object-ui/types
# or
pnpm add @object-ui/types
# or
yarn add @object-ui/types
```

### TypeScript Usage [#typescript-usage]

Import the type definitions you need:

```typescript
import type { 
  AppSchema, 
  ThemeSchema, 
  ActionSchema,
  ReportSchema,
  BlockSchema 
} from '@object-ui/types';
```

### Runtime Validation [#runtime-validation]

For runtime validation, use the included Zod schemas:

```typescript
import { 
  AppSchema,
  ThemeSchema,
  ActionSchema,
  ReportSchema,
  BlockSchema
} from '@object-ui/types/zod';

const result = AppSchema.safeParse(myConfig);
if (result.success) {
  // Valid configuration
  const app = result.data;
} else {
  // Handle validation errors
  console.error(result.error);
}
```

## Quick Start Example [#quick-start-example]

Here's a complete example showing how to build a simple CRM application using ObjectUI schemas:

```typescript
import type { AppSchema, ThemeSchema } from '@object-ui/types';

// Define your application structure
const app: AppSchema = {
  type: 'app',
  name: 'enterprise-crm',
  title: 'Enterprise CRM',
  layout: 'sidebar',
  
  menu: [
    {
      type: 'item',
      label: 'Dashboard',
      icon: 'LayoutDashboard',
      path: '/dashboard'
    },
    {
      type: 'group',
      label: 'Sales',
      children: [
        { type: 'item', label: 'Leads', path: '/leads' },
        { type: 'item', label: 'Deals', path: '/deals' }
      ]
    }
  ],
  
  actions: [
    {
      type: 'user',
      label: 'User Name',
      items: [
        { type: 'item', label: 'Profile', path: '/profile' },
        { type: 'item', label: 'Logout', path: '/logout' }
      ]
    }
  ]
};

// Configure your theme
const theme: ThemeSchema = {
  type: 'theme',
  mode: 'system',
  themes: [{
    name: 'professional',
    light: { primary: '#3b82f6', background: '#fff' },
    dark: { primary: '#60a5fa', background: '#0f172a' }
  }],
  allowSwitching: true,
  persistPreference: true
};
```

This creates a professional-looking CRM application with:

* A sidebar layout with navigation menu
* Sales section with leads and deals
* User menu with profile and logout options
* Professional theme with light/dark mode support

## Advanced Features [#advanced-features]

ObjectUI provides advanced schemas and capabilities for enterprise applications:

### Core Schemas [#core-schemas-1]

ObjectUI includes these top-level schemas:

* **`AppSchema`** - Define your entire application structure
* **`ThemeSchema`** - Configure themes and color palettes
* **`ReportSchema`** - Create data reports with aggregation
* **`BlockSchema`** - Build reusable component blocks

### Enhanced ActionSchema [#enhanced-actionschema]

The `ActionSchema` provides comprehensive action handling:

* ✅ Action types: `ajax`, `confirm`, `dialog`
* ✅ Action chaining via the `chain` array (sequential or parallel)
* ✅ Conditional execution with the `condition` property
* ✅ Success/failure callbacks: `onSuccess` and `onFailure`
* ✅ Event tracking with the `tracking` configuration
* ✅ Automatic retry logic

### View Components [#view-components-1]

ObjectUI includes enhanced view components:

* **`DetailViewSchema`** - Rich detail pages with sections and tabs
* **`ViewSwitcherSchema`** - Toggle between list, grid, kanban, calendar views
* **`FilterUISchema`** - Advanced filtering interface
* **`SortUISchema`** - Multi-field sort configuration

## Getting Started [#getting-started]

### Installation Steps [#installation-steps]

1. **Install package** - Add `@object-ui/types` to your project
   ```bash
   npm install @object-ui/types@latest
   ```

2. **Configure application** - Define your app structure with AppSchema (optional)

3. **Set up theming** - Add a ThemeSchema for consistent styling (optional)

4. **Implement actions** - Use advanced action features like `confirm` and callbacks

5. **Test your application** - Verify all functionality works as expected

## Learning Resources [#learning-resources]

* **[Schema Type Reference](/docs/api/schema-reference)** - Complete schema reference with JSON examples.
* **[Quick Start](/docs/guide/quick-start)** - Render your first ObjectUI schema.
* **[Schema Rendering](/docs/guide/schema-rendering)** - Understand the renderer pipeline.
* **[Component Registry](/docs/guide/component-registry)** - Learn how schema `type` values resolve to components.

## Getting Help [#getting-help]

### Community Support [#community-support]

* **[GitHub Discussions](https://github.com/objectstack-ai/objectui/discussions)** - Ask questions and share ideas
* **[GitHub Issues](https://github.com/objectstack-ai/objectui/issues)** - Report bugs and request features

### Official Documentation [#official-documentation]

* **[Documentation Site](https://www.objectui.org/docs)** - Full documentation and guides
* **[Schema Reference](/docs/api/schema-reference)** - Detailed schema documentation

## Next Steps [#next-steps]

Ready to build with ObjectUI? Here's what to do next:

1. **[Review schema documentation](/docs/api/schema-reference)** - Learn about each schema in detail
2. **[Try the Quick Start](/docs/guide/quick-start)** - Build your first ObjectUI application
3. **[Explore components](/docs/components)** - See the core renderer catalog
4. **[Explore plugins](/docs/plugins)** - Add heavier widgets such as grids, kanban, charts, maps, and reports


# Schema Playground



# Schema Playground [#schema-playground]

The Schema Playground is the fastest way to learn ObjectUI. Write JSON schemas in an editor, see the rendered UI instantly, and iterate on your designs without setting up a project.

## How It Works [#how-it-works]

The playground follows the core ObjectUI rendering pipeline:

```
JSON Editor → Schema Validation → SchemaRenderer → Live Preview
```

1. **Write** a JSON schema in the left panel
2. **Preview** the rendered UI in the right panel in real-time
3. **Iterate** by modifying properties and seeing changes instantly

## Setting Up the Playground [#setting-up-the-playground]

Add the playground to any React project with ObjectUI installed:

```tsx
import { useState } from 'react';
import { SchemaRenderer } from '@object-ui/react';
import { registerDefaultRenderers } from '@object-ui/components';
import { registerAllFields } from '@object-ui/fields';
import { Registry } from '@object-ui/core';

registerDefaultRenderers();
registerAllFields(Registry);

function SchemaPlayground() {
  const [schema, setSchema] = useState('{\n  "type": "button",\n  "label": "Click me"\n}');
  const [error, setError] = useState<string | null>(null);

  const parsed = (() => {
    try {
      const obj = JSON.parse(schema);
      if (error) setError(null);
      return obj;
    } catch (e) {
      setError((e as Error).message);
      return null;
    }
  })();

  return (
    <div className="grid grid-cols-2 gap-4 h-[600px]">
      <div className="flex flex-col gap-2">
        <h3 className="text-sm font-medium">JSON Schema</h3>
        <textarea
          className="flex-1 rounded-md border bg-muted p-3 font-mono text-sm"
          value={schema}
          onChange={(e) => setSchema(e.target.value)}
        />
        {error && (
          <p className="text-sm text-destructive">{error}</p>
        )}
      </div>
      <div className="flex flex-col gap-2">
        <h3 className="text-sm font-medium">Live Preview</h3>
        <div className="flex-1 rounded-md border bg-background p-4 overflow-auto">
          {parsed && <SchemaRenderer schema={parsed} />}
        </div>
      </div>
    </div>
  );
}
```

## Example Schemas [#example-schemas]

Try pasting any of the following schemas into the playground to see them rendered.

### Button [#button]

A simple button with a variant and icon:

```json
{
  "type": "button",
  "label": "Save Changes",
  "variant": "default",
  "icon": "save",
  "size": "default"
}
```

Try changing `"variant"` to `"destructive"`, `"outline"`, `"secondary"`, or `"ghost"` to see different styles.

### Card [#card]

A content card with a header, description, and body:

```json
{
  "type": "card",
  "title": "Monthly Revenue",
  "description": "Revenue summary for the current month",
  "icon": "dollar-sign",
  "body": {
    "type": "stack",
    "direction": "vertical",
    "gap": "md",
    "items": [
      {
        "type": "text",
        "content": "$48,250",
        "className": "text-3xl font-bold"
      },
      {
        "type": "badge",
        "label": "+12.5% from last month",
        "variant": "secondary"
      }
    ]
  }
}
```

### Form [#form]

A complete form with validation, driven entirely by schema:

```json
{
  "type": "form",
  "title": "Create Account",
  "fields": [
    {
      "name": "fullName",
      "type": "text",
      "label": "Full Name",
      "required": true,
      "placeholder": "Jane Doe"
    },
    {
      "name": "email",
      "type": "text",
      "label": "Email",
      "required": true,
      "placeholder": "jane@example.com",
      "validation": {
        "pattern": "^[^@]+@[^@]+\\.[^@]+$",
        "message": "Enter a valid email address"
      }
    },
    {
      "name": "role",
      "type": "select",
      "label": "Role",
      "options": ["Admin", "Editor", "Viewer"],
      "defaultValue": "Viewer"
    },
    {
      "name": "bio",
      "type": "textarea",
      "label": "Bio",
      "placeholder": "Tell us about yourself..."
    }
  ],
  "actions": [
    { "type": "submit", "label": "Create Account", "variant": "default" },
    { "type": "reset", "label": "Reset", "variant": "outline" }
  ]
}
```

### Grid [#grid]

A data grid with sortable columns and row actions:

```json
{
  "type": "grid",
  "title": "Team Members",
  "columns": [
    { "field": "name", "label": "Name", "sortable": true },
    { "field": "role", "label": "Role", "sortable": true },
    { "field": "status", "label": "Status", "sortable": true },
    { "field": "joined", "label": "Joined", "type": "date" }
  ],
  "rows": [
    { "name": "Alice Chen", "role": "Engineer", "status": "Active", "joined": "2024-01-15" },
    { "name": "Bob Smith", "role": "Designer", "status": "Active", "joined": "2024-03-22" },
    { "name": "Carol Jones", "role": "PM", "status": "Away", "joined": "2023-11-08" }
  ],
  "actions": [
    { "label": "Edit", "icon": "pencil", "action": "edit" },
    { "label": "Delete", "icon": "trash-2", "action": "delete", "variant": "destructive" }
  ],
  "pagination": {
    "pageSize": 10,
    "showPageSizeOptions": true
  }
}
```

### Composing Schemas [#composing-schemas]

Schemas can be nested to build complex layouts. Here is a dashboard that combines multiple components:

```json
{
  "type": "page",
  "title": "Project Dashboard",
  "body": {
    "type": "grid-layout",
    "columns": 3,
    "gap": "md",
    "items": [
      {
        "type": "card",
        "title": "Open Issues",
        "body": {
          "type": "text",
          "content": "24",
          "className": "text-4xl font-bold text-primary"
        }
      },
      {
        "type": "card",
        "title": "Pull Requests",
        "body": {
          "type": "text",
          "content": "8",
          "className": "text-4xl font-bold text-primary"
        }
      },
      {
        "type": "card",
        "title": "Deployments",
        "body": {
          "type": "text",
          "content": "142",
          "className": "text-4xl font-bold text-primary"
        }
      }
    ]
  }
}
```

## Schema → Rendered UI Flow [#schema--rendered-ui-flow]

Every schema goes through the following pipeline before becoming visible UI:

```
┌─────────────┐     ┌──────────────┐     ┌────────────────┐     ┌──────────┐
│  JSON Schema │────▶│  Validation  │────▶│ Registry Lookup│────▶│ React UI │
└─────────────┘     └──────────────┘     └────────────────┘     └──────────┘
```

1. **Parse** — The JSON string is parsed into a JavaScript object.
2. **Validate** — The `type` field is checked against the component registry. Required fields are verified.
3. **Resolve** — The registry maps the `type` to a React component. Expressions like `"visibleOn": "${data.role === 'admin'}"` are evaluated.
4. **Render** — The matched component receives the schema properties as props and renders Shadcn primitives with Tailwind classes.

In code, this is a single call:

```tsx
import { SchemaRenderer } from '@object-ui/react';

// The schema object (from your editor, API, or file)
const schema = {
  type: 'card',
  title: 'Hello',
  body: { type: 'text', content: 'World' },
};

// One line to go from JSON to UI
<SchemaRenderer schema={schema} />
```

## Tips for the Playground [#tips-for-the-playground]

* **Start simple** — Begin with a single `button` or `text` schema and add complexity incrementally.
* **Use `className`** — Any schema object accepts a `className` property for Tailwind utility classes.
* **Check the `type`** — If nothing renders, verify the `type` value matches a registered component.
* **Nest schemas** — Use container types like `stack`, `grid-layout`, and `page` to compose multiple components.
* **Add expressions** — Use `visibleOn` and `disabledOn` for dynamic behavior: `"visibleOn": "${data.showAdvanced}"`.

## Related Resources [#related-resources]

* [Schema Rendering](/docs/guide/schema-rendering) — How the rendering engine works in detail
* [Schema Overview](/docs/guide/schema-overview) — Full catalog of all available schema types
* [Component Registry](/docs/guide/component-registry) — How components are registered and resolved
* [Expressions](/docs/guide/expressions) — Dynamic expressions for conditional rendering
* [Building a CRUD App](/docs/guide/building-crud-app) — End-to-end tutorial using schemas in a real project
* [Type Documentation](/docs/api) — Full API reference for `@object-ui/types`


# Schema Rendering



Object UI's schema rendering system is the core mechanism that transforms JSON configurations into live React components. This guide explains how it works and how to use it effectively.

## Overview [#overview]

The schema rendering engine follows a simple principle:

```
JSON Schema → SchemaRenderer → React Components → Beautiful UI
```

Every visual element in Object UI starts as a JSON object that describes what should be rendered, not how it should be rendered.

## The SchemaRenderer Component [#the-schemarenderer-component]

The `SchemaRenderer` is the primary component that interprets your JSON schemas:

```tsx
import { SchemaRenderer } from '@object-ui/react'
import { registerDefaultRenderers } from '@object-ui/components'

// Register components once at app initialization
registerDefaultRenderers()

function App() {
  const schema = {
    type: "page",
    title: "My Dashboard",
    body: { /* ... */ }
  }
  
  return <SchemaRenderer schema={schema} />
}
```

## Schema Structure [#schema-structure]

Every schema object must have at minimum a `type` field:

```typescript
interface BaseSchema {
  type: string           // Component type identifier
  id?: string           // Optional unique identifier
  className?: string    // Tailwind CSS classes
  style?: CSSProperties // Inline styles (use sparingly)
  visibleOn?: string    // Expression for conditional visibility
  hiddenOn?: string     // Expression for conditional hiding
  disabledOn?: string   // Expression for conditional disabling
}
```

### Example Schema [#example-schema]

```json
{
  "type": "card",
  "id": "stats-card",
  "className": "p-6 shadow-lg",
  "title": "User Statistics",
  "visibleOn": "${user.role === 'admin'}",
  "body": {
    "type": "text",
    "value": "Total Users: ${stats.totalUsers}"
  }
}
```

## Data Context [#data-context]

The `SchemaRenderer` accepts a `data` prop that provides context for expressions:

```tsx
const data = {
  user: { name: "John", role: "admin" },
  stats: { totalUsers: 1234 }
}

<SchemaRenderer schema={schema} data={data} />
```

### Accessing Data in Schemas [#accessing-data-in-schemas]

Use expression syntax `${}` to reference data:

```json
{
  "type": "text",
  "value": "Welcome, ${user.name}!"
}
```

## Component Registry [#component-registry]

The schema renderer uses a component registry to map schema types to React components:

```tsx
import { getComponentRegistry } from '@object-ui/react'

const registry = getComponentRegistry()

// Register a custom component
registry.register('my-component', MyComponent)

// Now you can use it in schemas
const schema = {
  type: "my-component",
  // ... component props
}
```

## Nested Schemas [#nested-schemas]

Schemas can be nested to create complex UIs:

```json
{
  "type": "page",
  "title": "Dashboard",
  "body": {
    "type": "grid",
    "columns": 2,
    "items": [
      {
        "type": "card",
        "title": "Card 1",
        "body": {
          "type": "text",
          "value": "Nested content"
        }
      },
      {
        "type": "card",
        "title": "Card 2",
        "body": {
          "type": "chart",
          "chartType": "bar",
          "data": "${chartData}"
        }
      }
    ]
  }
}
```

## Array Rendering [#array-rendering]

Use arrays for multiple items:

```json
{
  "type": "container",
  "body": [
    { "type": "text", "value": "First item" },
    { "type": "text", "value": "Second item" },
    { "type": "text", "value": "Third item" }
  ]
}
```

## Expression System [#expression-system]

Object UI includes a powerful expression system for dynamic behavior:

### Simple Expressions [#simple-expressions]

```json
{
  "type": "text",
  "value": "${user.firstName} ${user.lastName}"
}
```

### Conditional Expressions [#conditional-expressions]

```json
{
  "type": "badge",
  "text": "${status === 'active' ? 'Active' : 'Inactive'}",
  "variant": "${status === 'active' ? 'success' : 'default'}"
}
```

### Visibility Control [#visibility-control]

```json
{
  "type": "button",
  "label": "Delete",
  "visibleOn": "${user.role === 'admin'}"
}
```

### Complex Logic [#complex-logic]

```json
{
  "type": "alert",
  "message": "Welcome!",
  "variant": "${
    user.isNew ? 'info' :
    user.tasks.length === 0 ? 'warning' :
    'success'
  }"
}
```

## Event Handling [#event-handling]

Components can emit events that you handle in React:

```tsx
<SchemaRenderer 
  schema={schema}
  onAction={(action, context) => {
    console.log('Action:', action)
    console.log('Context:', context)
  }}
  onSubmit={(data) => {
    console.log('Form submitted:', data)
  }}
/>
```

Reference actions in schemas:

```json
{
  "type": "button",
  "label": "Click Me",
  "onClick": {
    "actionType": "ajax",
    "api": "/api/action"
  }
}
```

## Performance Optimization [#performance-optimization]

### Lazy Loading [#lazy-loading]

Large schemas are automatically optimized:

```json
{
  "type": "tabs",
  "lazyLoad": true,
  "tabs": [
    { "title": "Tab 1", "body": { /* Loaded when tab is clicked */ } },
    { "title": "Tab 2", "body": { /* Loaded when tab is clicked */ } }
  ]
}
```

### Memoization [#memoization]

The renderer automatically memoizes components to prevent unnecessary re-renders.

### Code Splitting [#code-splitting]

Use dynamic imports for heavy components:

```tsx
import { lazy } from 'react'

const HeavyChart = lazy(() => import('./HeavyChart'))

registry.register('heavy-chart', HeavyChart)
```

## Error Handling [#error-handling]

The renderer includes built-in error boundaries:

```tsx
<SchemaRenderer 
  schema={schema}
  onError={(error, errorInfo) => {
    console.error('Rendering error:', error)
    // Log to error tracking service
  }}
/>
```

## TypeScript Support [#typescript-support]

Full type safety for your schemas:

```tsx
import type { PageSchema, FormSchema } from '@object-ui/core'

const schema: PageSchema = {
  type: "page",
  title: "Typed Page",
  body: {
    type: "form",
    // TypeScript will validate this entire structure
    body: [
      // ...
    ]
  }
}
```

## Best Practices [#best-practices]

### 1. Keep Schemas Simple [#1-keep-schemas-simple]

Break complex UIs into smaller, reusable schemas:

```tsx
// ❌ Bad: One massive schema
const massiveSchema = { /* 500 lines of JSON */ }

// ✅ Good: Composed schemas
const headerSchema = { /* ... */ }
const contentSchema = { /* ... */ }
const footerSchema = { /* ... */ }

const pageSchema = {
  type: "page",
  body: [headerSchema, contentSchema, footerSchema]
}
```

### 2. Use Data Context Effectively [#2-use-data-context-effectively]

Pass all necessary data upfront:

```tsx
// ✅ Good
const data = {
  user: userData,
  settings: userSettings,
  stats: dashboardStats
}

<SchemaRenderer schema={schema} data={data} />
```

### 3. Leverage Expressions [#3-leverage-expressions]

Move logic to expressions instead of creating conditional schemas:

```tsx
// ❌ Bad
const schema = user.isAdmin ? adminSchema : userSchema

// ✅ Good
const schema = {
  type: "page",
  body: [
    { 
      type: "admin-panel",
      visibleOn: "${user.isAdmin}"
    },
    {
      type: "user-panel",
      visibleOn: "${!user.isAdmin}"
    }
  ]
}
```

### 4. Use TypeScript [#4-use-typescript]

Always type your schemas for better IDE support and fewer runtime errors.

## Common Patterns [#common-patterns]

### Loading States [#loading-states]

```json
{
  "type": "container",
  "body": {
    "type": "spinner",
    "visibleOn": "${loading}"
  }
}
```

### Empty States [#empty-states]

```json
{
  "type": "empty-state",
  "visibleOn": "${items.length === 0}",
  "message": "No items found",
  "action": {
    "type": "button",
    "label": "Create New"
  }
}
```

### Error States [#error-states]

```json
{
  "type": "alert",
  "variant": "error",
  "visibleOn": "${error}",
  "message": "${error.message}"
}
```

## Next Steps [#next-steps]

* [Component Registry](./component-registry.md) - Learn about component registration
* [Expression System](./expressions.md) - Master expressions
* [Protocol Overview](/protocol/overview) - Explore all available schemas

## Related Documentation [#related-documentation]

* [Schema Specification](/spec/schema-rendering) - Technical specification
* [Architecture](/spec/architecture) - System architecture
* [Core API](/api/core) - Core package API reference
* [React API](/api/react) - React package API reference


# Slotted Pages



# Slotted Pages [#slotted-pages]

Every record detail page in ObjectUI is **synthesized from the object
definition by default** (see `buildDefaultPageSchema`). You get a
Lightning-style page — header, highlights, tabs, related lists,
history — without writing a single line of page schema.

When you want to customize part of that page, you have two options:

1. **Full page** (`kind: "full"`, the default): author the entire
   `regions[].components[]` tree. Total control, total responsibility
   — you re-author every region.
2. **Slotted page** (`kind: "slotted"`): provide overrides for only
   the slots you care about. The default-page synthesizer fills in
   every slot you didn't override.

For "I love the default page but want to customize just the header,"
slotted pages are the right tool.

## Slot menu (v1) [#slot-menu-v1]

| Slot         | Replaces                                                                       |
| ------------ | ------------------------------------------------------------------------------ |
| `header`     | `page:header`                                                                  |
| `actions`    | `record:quick_actions` (the action bar)                                        |
| `highlights` | The chips + chevron path strip                                                 |
| `details`    | The Details tab body (other tabs stay synthesized)                             |
| `tabs`       | The entire `page:tabs` node — use to add or reorder tabs (wins over `details`) |
| `discussion` | `record:discussion` (the inline conversation footer)                           |

Each slot accepts a single component schema or an array (arrays are
flattened in place). Each slot is a **full replacement at the slot
boundary** — there is no deep-merge or JSON-Patch in v1.

## Example: customize only the header [#example-customize-only-the-header]

```ts
import type { Page } from '@objectstack/spec/ui';

export const AccountDetailPage: Page = {
  name: 'account_detail_page',
  label: 'Account Detail',
  type: 'record',
  object: 'account',
  kind: 'slotted',
  regions: [], // slotted pages don't author regions
  slots: {
    header: {
      type: 'page:header',
      id: 'account_header_slotted',
      properties: {
        title: '{name}',
        subtitle: '{industry} · {type}',
        eyebrow: 'ACCOUNT',
        icon: 'building-2',
        breadcrumb: true,
      },
    },
  },
};
```

Result: the account record page renders with your custom header, and
the synthesizer fills in the highlights, tabs, and discussion regions as
if you'd authored nothing else. The default tab strip is **Details** → one
tab per related list flagged `relatedList: 'primary'` on its relationship → a
shared **Related** tab for the rest → **History**; so promoting a child table to
its own tab is a one-word change on the relationship, not a page-authoring task.
`relatedLayout: 'tabs' | 'stack'` remains an app-level override (force
all-own-tabs / all-stacked).

Related lists are additionally gated on the current user's **object-level
read permission** for the child object: a relationship whose child the user
cannot read produces no section and no tab (and the `record:related_list`
renderer suppresses itself the same way on hand-authored pages). The server
always enforced data access — this keeps the UI from rendering an empty
grid with a "New" button that would be rejected on save.

## Header actions: inline vs. overflow [#header-actions-inline-vs-overflow]

`page:header` renders the record's `record_header&#x60; actions (authored
business actions plus the host-injected system set — Edit / Share /
Delete) as a button row. Up to &#x2A;*`maxVisible`** actions render inline,
side by side (default **3*&#x2A; on desktop, &#x2A;*`mobileMaxVisible`**, default
**1**, on mobile); the rest collapse into a `⋯` "More actions" menu.

Which actions claim the inline slots is declared in metadata, using the
same rules as `action:bar`:

* **`order`** (number, default `0`) — actions are stable-sorted
  ascending before the split, so a lower `order` promotes an action
  into the inline slots and a higher `order` pushes it toward the `⋯`
  menu. The synthesized system actions use `order: 100+`, so authored
  business actions outrank them by default.
* **`variant: 'primary'`** — tie-break within equal `order`: a primary
  action outranks its unordered siblings without needing an explicit
  `order`.
* **`component: 'action:menu'`** — pins the action inside the `⋯` menu
  regardless of how few actions exist (the synthesized Share / Delete
  use this).

```ts
slots: {
  header: {
    type: 'page:header',
    properties: {
      title: '{name}',
      maxVisible: 4, // allow four inline buttons on this page
    },
  },
},
```

## Composing default + custom [#composing-default--custom]

When you want "the default actions plus one custom button," you have
to replace the whole `actions` slot — there's no append/insert
operation in v1. To avoid copying the synthesizer's internals,
`@object-ui/plugin-detail` exports the **sub-builders** the
synthesizer uses internally:

```ts
import {
  buildDefaultHeader,
  buildDefaultActions,
  buildDefaultHighlights,
  buildDefaultDetails,
  buildDefaultTabs,
  buildDefaultDiscussion,
} from '@object-ui/plugin-detail';
```

You can call them with the object definition (and any options you'd
normally pass to `buildDefaultPageSchema`) and spread the result into
your slot override.

## When to use slotted vs full [#when-to-use-slotted-vs-full]

* **Slotted** — customizing 1–2 regions of an otherwise standard
  detail page. Most "I want a fancier header" / "add a banner" /
  "swap the Details layout" requests.
* **Full** — building a record page that doesn't look like the
  default at all (e.g. a multi-column dashboard-style record). Author
  every region yourself.

The two modes are mutually exclusive: a page either has `kind: "full"`
(default) and uses `regions[]`, or `kind: "slotted"` and uses
`slots`.

> **Note:** the default-page synthesizer is the only render path for
> record detail pages. The legacy monolithic DetailView fallback and its
> `renderViaSchema` kill-switch (`objectDef.detail.renderViaSchema`,
> `?renderViaSchema=0`) were removed by ADR-0085 PR4.


# Theming & Customization



# Theming & Customization [#theming--customization]

ObjectUI's theming system is built on three layers: **CSS custom properties** (design tokens), **Tailwind CSS** (utility classes), and **class-variance-authority** (component variants). Together they give you full control over appearance — from global palettes down to individual component states.

## How Theming Works [#how-theming-works]

```
Theme JSON  →  ThemeProvider  →  CSS Custom Properties  →  Tailwind utilities  →  Components
```

1. You define a **Theme** object (colors, fonts, radii, spacing).
2. `ThemeProvider` from `@object-ui/react` resolves inheritance and converts the theme to CSS custom properties injected on `document.documentElement`.
3. Tailwind classes reference those properties (e.g. `bg-primary` maps to `hsl(var(--primary))`).
4. Components use `cva()` for variant logic and `cn()` for class merging.

## CSS Custom Properties [#css-custom-properties]

ObjectUI follows the Shadcn convention. Design tokens are defined as HSL channel values on `:root` and `.dark`:

```css
/* globals.css */
@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 222.2 84% 4.9%;
    --primary: 222.2 47.4% 11.2%;
    --primary-foreground: 210 40% 98%;
    --secondary: 210 40% 96.1%;
    --secondary-foreground: 222.2 47.4% 11.2%;
    --accent: 210 40% 96.1%;
    --accent-foreground: 222.2 47.4% 11.2%;
    --destructive: 0 84.2% 60.2%;
    --destructive-foreground: 210 40% 98%;
    --muted: 210 40% 96.1%;
    --muted-foreground: 215.4 16.3% 46.9%;
    --border: 214.3 31.8% 91.4%;
    --ring: 222.2 84% 4.9%;
    --radius: 0.5rem;
  }

  .dark {
    --background: 222.2 84% 4.9%;
    --foreground: 210 40% 98%;
    --primary: 210 40% 98%;
    --primary-foreground: 222.2 47.4% 11.2%;
    /* ... remaining dark tokens */
  }
}
```

Components reference these tokens through Tailwind:

```tsx
<div className="bg-background text-foreground border-border" />
<button className="bg-primary text-primary-foreground" />
```

## Tailwind Configuration [#tailwind-configuration]

Extend your `tailwind.config.js` to map tokens to Tailwind utilities:

```js
// tailwind.config.js
export default {
  darkMode: "class",
  content: [
    "./src/**/*.{ts,tsx}",
    "./node_modules/@object-ui/components/dist/**/*.js",
  ],
  theme: {
    extend: {
      colors: {
        background: "hsl(var(--background))",
        foreground: "hsl(var(--foreground))",
        primary: {
          DEFAULT: "hsl(var(--primary))",
          foreground: "hsl(var(--primary-foreground))",
        },
        secondary: {
          DEFAULT: "hsl(var(--secondary))",
          foreground: "hsl(var(--secondary-foreground))",
        },
        destructive: {
          DEFAULT: "hsl(var(--destructive))",
          foreground: "hsl(var(--destructive-foreground))",
        },
        muted: {
          DEFAULT: "hsl(var(--muted))",
          foreground: "hsl(var(--muted-foreground))",
        },
        accent: {
          DEFAULT: "hsl(var(--accent))",
          foreground: "hsl(var(--accent-foreground))",
        },
        border: "hsl(var(--border))",
        ring: "hsl(var(--ring))",
      },
      borderRadius: {
        lg: "var(--radius)",
        md: "calc(var(--radius) - 2px)",
        sm: "calc(var(--radius) - 4px)",
      },
      fontFamily: {
        sans: ["Inter", "ui-sans-serif", "system-ui"],
      },
    },
  },
};
```

## Component Variants with `cva` [#component-variants-with-cva]

ObjectUI uses [class-variance-authority](https://cva.style) to define type-safe component variants. Each component exports a `*Variants` function alongside the component itself:

```tsx
import { cva, type VariantProps } from "class-variance-authority";
import { cn } from "@object-ui/components";

const badgeVariants = cva(
  "inline-flex items-center rounded-full border px-2.5 py-0.5 text-xs font-semibold transition-colors",
  {
    variants: {
      variant: {
        default: "border-transparent bg-primary text-primary-foreground",
        secondary: "border-transparent bg-secondary text-secondary-foreground",
        destructive: "border-transparent bg-destructive text-destructive-foreground",
        outline: "text-foreground",
      },
    },
    defaultVariants: {
      variant: "default",
    },
  }
);

interface BadgeProps
  extends React.HTMLAttributes<HTMLDivElement>,
    VariantProps<typeof badgeVariants> {}

function Badge({ className, variant, ...props }: BadgeProps) {
  return <div className={cn(badgeVariants({ variant }), className)} {...props} />;
}
```

To add a custom variant to an existing component, wrap it:

```tsx
const statusVariants = cva("", {
  variants: {
    status: {
      active: "bg-green-500/15 text-green-700 border-green-500/25",
      pending: "bg-yellow-500/15 text-yellow-700 border-yellow-500/25",
      inactive: "bg-gray-500/15 text-gray-500 border-gray-500/25",
    },
  },
});

function StatusBadge({ status, className, ...props }: { status: "active" | "pending" | "inactive" } & React.HTMLAttributes<HTMLDivElement>) {
  return <Badge className={cn(statusVariants({ status }), className)} variant="outline" {...props} />;
}
```

## Class Overrides with `cn()` [#class-overrides-with-cn]

The `cn()` utility from `@object-ui/components` combines `clsx` and `tailwind-merge` so that later classes win over earlier ones without producing duplicate utilities:

```tsx
import { cn } from "@object-ui/components";

// tailwind-merge resolves conflicts: "p-4" wins over "p-2"
cn("p-2 bg-red-500", "p-4");
// → "bg-red-500 p-4"

// Conditional classes with clsx syntax
cn("base-class", isActive && "bg-primary", className);
```

Every ObjectUI component accepts a `className` prop that is merged via `cn()`, so consumers can always override styles:

```tsx
<Button className="rounded-full px-8" variant="outline">
  Custom Shape
</Button>
```

## Dark Mode [#dark-mode]

ObjectUI supports three modes: `light`, `dark`, and `auto` (follows system preference). The `ThemeProvider` applies a `light` or `dark` class to the root element and listens for `prefers-color-scheme` changes.

```tsx
import { ThemeProvider } from "@object-ui/react";

function App() {
  return (
    <ThemeProvider defaultMode="auto">
      <MyApp />
    </ThemeProvider>
  );
}
```

Toggle mode at runtime with the `useTheme` hook:

```tsx
import { useTheme } from "@object-ui/react";

function ModeToggle() {
  const { resolvedMode, setMode } = useTheme();

  return (
    <button onClick={() => setMode(resolvedMode === "dark" ? "light" : "dark")}>
      {resolvedMode === "dark" ? "☀️ Light" : "🌙 Dark"}
    </button>
  );
}
```

Ensure your Tailwind config uses `darkMode: "class"` so that `.dark` scoped utilities work correctly.

## Custom Component Themes [#custom-component-themes]

Register one or more theme definitions with `ThemeProvider`. Each theme is a plain JSON object:

```tsx
import type { Theme } from "@object-ui/types";

const corporateTheme: Theme = {
  name: "corporate",
  colors: {
    primary: "220 70% 50%",
    "primary-foreground": "0 0% 100%",
    background: "0 0% 100%",
    foreground: "220 20% 10%",
    accent: "200 80% 55%",
    "accent-foreground": "0 0% 100%",
  },
  fonts: {
    sans: "IBM Plex Sans, system-ui",
  },
  radius: "0.375rem",
};

<ThemeProvider themes={[corporateTheme]} defaultTheme="corporate">
  <App />
</ThemeProvider>
```

Themes support **inheritance** via the `extends` field. A child theme only needs to declare its overrides:

```tsx
const darkCorporate: Theme = {
  name: "corporate-dark",
  extends: "corporate",
  colors: {
    background: "220 20% 8%",
    foreground: "0 0% 95%",
  },
};

<ThemeProvider themes={[corporateTheme, darkCorporate]} defaultTheme="corporate-dark">
  <App />
</ThemeProvider>
```

## Creating a Custom Color Palette [#creating-a-custom-color-palette]

Start from HSL values and define both light and dark variants:

```tsx
const brand: Theme = {
  name: "brand",
  colors: {
    // Light palette
    primary: "262 83% 58%",        // Purple
    "primary-foreground": "0 0% 100%",
    secondary: "262 30% 94%",
    "secondary-foreground": "262 83% 30%",
    accent: "160 84% 39%",          // Teal accent
    "accent-foreground": "0 0% 100%",
    background: "0 0% 100%",
    foreground: "262 20% 10%",
    muted: "262 20% 95%",
    "muted-foreground": "262 10% 45%",
    border: "262 20% 90%",
    ring: "262 83% 58%",
    destructive: "0 84% 60%",
    "destructive-foreground": "0 0% 100%",
  },
  radius: "0.5rem",
};
```

> **Tip:** Use the [Shadcn Themes tool](https://ui.shadcn.com/themes) to generate a full palette, then paste the HSL values into your Theme object.

## Runtime Theme Switching [#runtime-theme-switching]

`ThemeProvider` accepts multiple themes. Switch between them at runtime with `setTheme`:

```tsx
import { useTheme } from "@object-ui/react";

function ThemeSwitcher() {
  const { activeTheme, themes, setTheme } = useTheme();

  return (
    <select value={activeTheme ?? ""} onChange={(e) => setTheme(e.target.value)}>
      {themes.map((t) => (
        <option key={t.name} value={t.name}>{t.name}</option>
      ))}
    </select>
  );
}
```

Enable **persistence** so the user's choice survives page reloads:

```tsx
<ThemeProvider
  themes={[lightTheme, darkTheme, brandTheme]}
  defaultTheme="light"
  persist
  storageKey="my-app-theme"
>
  <App />
</ThemeProvider>
```

The provider stores the active theme name and mode in `localStorage` under the keys `<storageKey>-name` and `<storageKey>-mode`.

## RTL Support [#rtl-support]

ObjectUI components use **logical CSS properties** (`ms-`, `me-`, `ps-`, `pe-`) where available via Tailwind's logical utilities. For full RTL support:

1. Set the `dir` attribute on your root element:

```tsx
<html dir="rtl" lang="ar">
```

2. Use Tailwind's RTL modifier for directional overrides:

```tsx
<div className="ps-4 pe-2 rtl:ps-2 rtl:pe-4">
  Directional padding
</div>
```

3. Avoid `left` / `right` utilities — prefer `start` / `end` equivalents (`text-start`, `ms-4`, `rounded-s-lg`).

> **Note:** RTL support requires Tailwind CSS v3.3+ or v4 with logical property utilities enabled.


# Troubleshooting



# Troubleshooting [#troubleshooting]

This guide covers the most common issues you may encounter when working with ObjectUI, along with their solutions.

## 1. "Component type X not found" [#1-component-type-x-not-found]

**Symptom:** The `SchemaRenderer` renders nothing or shows a fallback, and the console logs `component type "kanban-ui" not found in registry`.

**Cause:** The plugin that provides the component type has not been imported, so it never registered itself with the `ComponentRegistry`.

**Fix:**

```typescript
// Import the plugin package — registration happens on import
import '@object-ui/plugin-kanban';
import '@object-ui/plugin-grid';
```

If you are using a custom component, register it explicitly:

```typescript
import { ComponentRegistry } from '@object-ui/core';
import { MyCustomWidget } from './MyCustomWidget';

ComponentRegistry.register('my-widget', MyCustomWidget, {
  namespace: 'custom',
  label: 'My Widget',
  category: 'plugin',
});
```

Verify what is registered by running:

```bash
npx objectui doctor
```

## 2. Build Errors with Tailwind CSS [#2-build-errors-with-tailwind-css]

**Symptom:** Tailwind utility classes are not applied. Components render without styling.

**Cause:** The `content` paths in your Tailwind config do not include ObjectUI package files.

**Fix:** Update your `tailwind.config.ts` (or `postcss.config.mjs`) to scan ObjectUI packages inside `node_modules`:

```typescript
// tailwind.config.ts
export default {
  content: [
    './src/**/*.{ts,tsx}',
    './node_modules/@object-ui/components/**/*.{js,ts,tsx}',
    './node_modules/@object-ui/fields/**/*.{js,ts,tsx}',
    './node_modules/@object-ui/layout/**/*.{js,ts,tsx}',
    './node_modules/@object-ui/plugin-*/**/*.{js,ts,tsx}',
  ],
  // ...
};
```

Also ensure `postcss.config.mjs` is present at the project root (see `postcss.config.mjs` in the monorepo root for reference).

## 3. Missing Peer Dependencies [#3-missing-peer-dependencies]

**Symptom:** Build or runtime errors about missing modules like `react`, `react-dom`, or `react-hook-form`.

**Cause:** ObjectUI packages declare React 18+ as a **peer dependency**. Your host project must provide them.

**Fix:**

```bash
# Run the built-in doctor command to detect missing dependencies
npx objectui doctor

# Or install manually
pnpm add react react-dom react-hook-form
```

The `objectui doctor` command checks:

* Peer dependency versions
* Package compatibility
* Registry health
* Missing plugins referenced in schemas

## 4. Expression Evaluation Errors [#4-expression-evaluation-errors]

**Symptom:** Expressions like `${data.user.name}` render as literal strings or throw runtime errors.

**Cause:** Malformed expression syntax, missing context variables, or unclosed brackets.

**Fix:**

| Problem            | Bad           | Good                               |
| ------------------ | ------------- | ---------------------------------- |
| Missing `$` prefix | `{data.name}` | `${data.name}`                     |
| Unclosed bracket   | `${data.name` | `${data.name}`                     |
| Wrong context var  | `${row.name}` | `${data.name}`                     |
| Nested quotes      | `${"hello"}`  | `${'hello'}` or `${data.greeting}` |

Available context variables:

* `data.*` — Current data scope
* `user.*` — Authenticated user
* `params.*` — URL/query parameters

Debug expressions by enabling debug mode in `SchemaRendererContext`:

```tsx
<SchemaRenderer schema={schema} debug={true} />
```

This logs each expression evaluation to the browser console.

## 5. Schema Validation Errors [#5-schema-validation-errors]

**Symptom:** Schema renders incorrectly or `ValidationEngine` throws errors about invalid schema structure.

**Fix:** Validate your schema before passing it to the renderer:

```bash
# CLI validation (checks against @objectstack/spec)
npx objectui validate ./path/to/schema.json
```

Common schema issues:

* Missing required `type` field on components
* Invalid action type (must be one of: `script`, `url`, `api`, `modal`, `flow`)
* Referencing a field type that doesn't exist (e.g., `rich-text` without importing `plugin-editor`)

The validation engine lives in `packages/core/src/validation/` and uses Zod schemas from `@object-ui/types`.

## 6. TypeScript Errors with Schema Types [#6-typescript-errors-with-schema-types]

**Symptom:** TypeScript cannot find types like `ComponentSchema`, `ActionSchema`, or `FieldWidgetProps`.

**Cause:** `@object-ui/types` is not installed, or the version is mismatched.

**Fix:**

```bash
pnpm add @object-ui/types
```

Then import types from the correct entry points:

```typescript
// Base types
import type { ComponentSchema } from '@object-ui/types';

// Category-specific types
import type { FormSchema } from '@object-ui/types/form';
import type { LayoutSchema } from '@object-ui/types/layout';
import type { DataDisplaySchema } from '@object-ui/types/data-display';

// Zod validation schemas
import { componentSchema } from '@object-ui/types/zod';
```

The `@object-ui/types` package exports multiple entry points (`base`, `layout`, `form`, `data-display`, `feedback`, `overlay`, `navigation`, `complex`, `data`, `zod`). Check `packages/types/package.json` for the full list.

## 7. Dark Mode Flickering [#7-dark-mode-flickering]

**Symptom:** Page flashes white before switching to dark mode on initial load.

**Cause:** The `ThemeProvider` (`packages/react/src/context/ThemeContext`) is mounted too late, or the theme preference is read asynchronously after first paint.

**Fix:**

1. Place the `ThemeProvider` as high as possible in your component tree — ideally wrapping your entire app:

```tsx
import { ThemeProvider } from '@object-ui/react';

function App() {
  return (
    <ThemeProvider defaultTheme="system">
      <YourApp />
    </ThemeProvider>
  );
}
```

2. Add a blocking script in your HTML `<head>` to set the `class` attribute before React hydrates:

```html
<script>
  const theme = localStorage.getItem('object-ui-theme') || 'system';
  if (theme === 'dark' || (theme === 'system' && matchMedia('(prefers-color-scheme: dark)').matches)) {
    document.documentElement.classList.add('dark');
  }
</script>
```

## 8. i18n Missing Translations [#8-i18n-missing-translations]

**Symptom:** UI shows raw translation keys like `common.save` instead of localized text.

**Cause:** Locale files are missing or the `I18nProvider` is not configured.

**Fix:**

1. Ensure the `I18nProvider` from `packages/i18n/` wraps your app:

```tsx
import { I18nProvider } from '@object-ui/i18n';

<I18nProvider locale="en" messages={messages}>
  <App />
</I18nProvider>
```

2. Check that locale files follow the expected structure. Each locale file should export a flat or nested object of key-value pairs.

3. Verify the locale code matches exactly (e.g., `en`, `fr`, `de` — not `en-US` unless your locale files use that format).

## 9. Performance Issues with Large Datasets [#9-performance-issues-with-large-datasets]

**Symptom:** Grid, table, or list views become slow with 1,000+ rows.

**Cause:** All rows are being rendered in the DOM at once.

**Fix:**

* **Grid Plugin** (`packages/plugin-grid/`): Built-in grid supports virtualization out of the box for large datasets.
* **Paginate server-side**: Configure your data source adapter (`packages/core/src/adapters/`) to fetch data in pages rather than loading everything at once.

For custom views, use the `usePerformance` hook from `@object-ui/react` to monitor render times:

```typescript
import { usePerformance } from '@object-ui/react';

const { startMeasure, endMeasure } = usePerformance('MyWidget');
```

## 10. Plugin Conflicts [#10-plugin-conflicts]

**Symptom:** Two plugins register the same component type and one silently overrides the other.

**Cause:** Plugins registered without namespaces collide on the same type key.

**Fix:** Always use namespaced registrations:

```typescript
ComponentRegistry.register('grid', MyGridComponent, {
  namespace: 'my-plugin',  // ← prevents collision
  label: 'Custom Grid',
  category: 'plugin',
});
```

The `PluginSystem` (`packages/core/src/registry/PluginSystem.ts`) uses `PluginScopeImpl` to auto-prefix registrations with the plugin name. If you register manually, always provide a `namespace`.

To debug conflicts:

```bash
npx objectui doctor
```

This reports duplicate registrations and namespace collisions.

## 10. `react-day-picker` v9 prop / classNames errors [#10-react-day-picker-v9-prop--classnames-errors]

**Symptom:** After upgrading `react-day-picker` (a transitive dependency of `@object-ui/components`) you see TypeScript errors such as:

* `Property 'initialFocus' does not exist on type 'DayPickerProps'`
* `Property 'fromYear' does not exist on type 'DayPickerProps'`
* `'table' does not exist in type 'Partial<ClassNames>'`

**Cause:** v9 removed several legacy props/classnames slots inherited from the v7 API.

**Fix:** Apply the v8 → v9 mapping below in any file that consumes `<Calendar>` / `<DayPicker>` directly:

| v8 / earlier       | v9 replacement                                                 |
| ------------------ | -------------------------------------------------------------- |
| `initialFocus`     | `autoFocus`                                                    |
| `fromYear={2000}`  | `startMonth={new Date(2000, 0)}`                               |
| `toYear={2050}`    | `endMonth={new Date(2050, 11)}`                                |
| `classNames.table` | removed — drop the entry (the table wrapper now styles itself) |

The components shipped in `@object-ui/components` and `@object-ui/plugin-calendar` already use the v9 API; this note exists so downstream apps with their own `<Calendar>` wrappers can apply the same migration.

## Getting Help [#getting-help]

If none of the above resolves your issue:

1. Search [existing issues](https://github.com/objectstack-ai/objectui/issues)
2. Run `npx objectui doctor` and include the output in your report
3. Open an issue with your schema JSON, error message, and ObjectUI package versions


# User-Scoped State Persistence



Object UI keeps per-user UI state — **Favorites** (pinned apps, starred records, and pinned navigation entries), **Recent Items** (last visited entities), and **Flow-palette recents** (node types recently added in the flow designer) — alive across reloads, devices, and accounts. The persistence layer is **backend-agnostic**: drop in an adapter, or just let it run on localStorage.

## Design [#design]

The shell exposes a small injection contract:

```typescript
export interface UserDataAdapter<T> {
  /** Load the persisted list for the current user. Resolve to [] when absent. */
  load(): Promise<T[]>;
  /** Persist the full list (debounced upstream). Errors are silently ignored. */
  save(items: T[]): Promise<void>;
}

export type UserStateKind = 'favorites' | 'recent' | 'flowPaletteRecents';
```

Three layers, top-down:

| Layer                                                                                    | Package                               | Role                                                                                            |
| ---------------------------------------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------- |
| **Providers** (`FavoritesProvider`, `RecentItemsProvider`, `FlowPaletteRecentsProvider`) | `@object-ui/app-shell`                | Own the state, debounce writes, scope storage by user.                                          |
| **Adapter registry** (`UserStateAdaptersProvider`)                                       | `@object-ui/app-shell`                | Lets a bridge component inject adapters at runtime once `dataSource` + `user.id` are available. |
| **Adapters** (`createObjectStackUserStateAdapter`, your own)                             | `@object-ui/data-objectstack`, custom | Translate `load/save` into HTTP / GraphQL / ObjectQL calls.                                     |

### Three guarantees [#three-guarantees]

1. **localStorage-first.** First paint never blocks on the network. If no adapter is attached, persistence is purely local.
2. **Scoped per `user.id`.** Storage key is `objectui-favorites:u:<id>` (and `objectui-recent-items:u:<id>`, `flow-palette-recents:u:<id>`). Two accounts on the same browser never see each other's state.
3. **Silent degrade.** Adapters must never throw. A 404 / network error means "behave like there is no backend"; the UI keeps working from localStorage.

## Provider tree [#provider-tree]

`ConsoleShell` wires everything up in this order:

```tsx
<ThemeProvider>
  <NavigationProvider>
    <UserStateAdaptersProvider>      {/* adapter registry */}
      <FavoritesProvider>            {/* consumes adapter via context */}
        <RecentItemsProvider>
          <Suspense fallback={...}>
            {children /* ConnectedShellInner mounts the bridge */}
          </Suspense>
        </RecentItemsProvider>
      </FavoritesProvider>
    </UserStateAdaptersProvider>
  </NavigationProvider>
</ThemeProvider>
```

`ConnectedShellInner` mounts a tiny `UserStateBridge` component that calls `useAttachUserStateAdapters()` to plug in adapters once both `user.id` and `dataSource` are ready.

## Using the official ObjectStack adapter [#using-the-official-objectstack-adapter]

The companion adapter is shipped in `@object-ui/data-objectstack`:

```typescript
import { createObjectStackUserStateAdapter } from '@object-ui/data-objectstack';
import { useAttachUserStateAdapters } from '@object-ui/app-shell';
import { useAuth } from '@object-ui/auth';

function UserStateBridge({ dataSource }) {
  const { user } = useAuth();
  const attach = useAttachUserStateAdapters();

  useEffect(() => {
    if (!user?.id || !dataSource) return;
    const favorites = createObjectStackUserStateAdapter({
      dataSource, userId: user.id, kind: 'favorites',
    });
    const recent = createObjectStackUserStateAdapter({
      dataSource, userId: user.id, kind: 'recent',
    });
    attach('favorites', favorites);
    attach('recent', recent);
    return () => {
      attach('favorites', null);
      attach('recent', null);
    };
  }, [user?.id, dataSource, attach]);

  return null;
}
```

### Required backend object [#required-backend-object]

The official adapter stores **one row per (user\_id, kind) pair** holding the full list as a JSON blob.

```yaml
object: user_app_state
fields:
  - name: user_id
    type: string
    indexed: true
  - name: kind
    type: string
    indexed: true
  - name: payload
    type: json
  - name: updated_at
    type: datetime
unique: [user_id, kind]
```

If this object doesn't exist on your backend, every call simply 404s — the UI keeps running from localStorage. There is no migration to roll out.

### What the adapter does [#what-the-adapter-does]

1. **load()**
   * `find('user_app_state', { filter: { user_id, kind }, limit: 1 })`
   * Parses `payload` (tolerates already-parsed JSON or string-encoded JSON).
   * Caches the returned row id for fast subsequent saves.
   * Any error → returns `[]`.

2. **save(items)**
   * If we have a cached row id → `update('user_app_state', id, { payload, updated_at })`.
   * Otherwise → `find` then `create`.
   * If update fails (e.g. row was deleted server-side) → falls back to create.
   * Any error → resolves silently.

## Writing a custom adapter [#writing-a-custom-adapter]

```typescript
import type { UserDataAdapter } from '@object-ui/app-shell';
import type { FavoriteItem } from '@object-ui/app-shell';

export function createMyApiAdapter(userId: string): UserDataAdapter<FavoriteItem> {
  const url = `/api/users/${userId}/favorites`;
  return {
    async load() {
      try {
        const res = await fetch(url);
        if (!res.ok) return [];
        return (await res.json()) as FavoriteItem[];
      } catch {
        return [];
      }
    },
    async save(items) {
      try {
        await fetch(url, {
          method: 'PUT',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify(items),
        });
      } catch {
        /* silent */
      }
    },
  };
}
```

Plug it in with `attach('favorites', createMyApiAdapter(user.id))`.

## How writes are batched [#how-writes-are-batched]

The providers debounce backend writes with a 500ms window via `createDebouncedFlush`. A burst of mutations (e.g. drag-reordering ten favorites) results in a single `save()` call carrying the final list. The provider flushes pending writes on unmount and on user-change so nothing is lost during navigation.

`localStorage` is written **synchronously** on every mutation, so reloads always show the latest state immediately even if the debounced backend write hasn't fired yet.

## Race-safety [#race-safety]

Each provider keeps a monotonic `hydrationToken`. If the user switches accounts while a `load()` is in flight, the late response is discarded. This prevents seeing User A's favorites flash into User B's session.

## Reference [#reference]

| Symbol                                    | Package                       | Description                                                                                                                 |
| ----------------------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `UserStateAdaptersProvider`               | `@object-ui/app-shell`        | Adapter registry; place above the providers.                                                                                |
| `useAttachUserStateAdapters()`            | `@object-ui/app-shell`        | Imperative API for a bridge component to attach/detach adapters.                                                            |
| `useUserStateAdapter(kind)`               | `@object-ui/app-shell`        | Read the currently-attached adapter (rarely needed by app code).                                                            |
| `useFavorites()`                          | `@object-ui/app-shell`        | `{ favorites, addFavorite, removeFavorite, toggleFavorite, isFavorite, clearFavorites, setPinned, isPinned, pinnedNavIds }` |
| `useNavPins()`                            | `@object-ui/app-shell`        | Thin shim over `useFavorites` for sidebar pinning — `{ pinnedIds, togglePin, isPinned, applyPins, clearPins }`.             |
| `useRecentItems()`                        | `@object-ui/app-shell`        | `{ recentItems, addRecentItem, clearRecentItems }`                                                                          |
| `useFlowPaletteRecents()`                 | `@object-ui/app-shell`        | `{ recents, recordRecent }` — flow-designer add-node MRU; falls back to localStorage outside a provider.                    |
| `createObjectStackUserStateAdapter(opts)` | `@object-ui/data-objectstack` | Official adapter against the `user_app_state` object.                                                                       |

## Limits [#limits]

* **20** favorites and **20** nav-pins per user (independent buckets), **8** recent items, **5** flow-palette recents. Enforced by the providers; older entries roll off within their own bucket without evicting the other.
* One JSON blob per (user, kind). Not designed for high-frequency / large payloads — this is UI state, not data.
* No automatic cross-tab sync today (see the roadmap).

## Unified Favorites + Nav Pins [#unified-favorites--nav-pins]

The left-sidebar "Pin" feature and the object-page top-right "Favorite" are stored in the **same** `favorites` collection. A `FavoriteItem` now carries three optional fields used by the navigation pin flow:

```ts
interface FavoriteItem {
  id: string;            // 'nav:<navId>' for nav pins, '<objectName>:<recordId>' for records, etc.
  type?: 'object' | 'record' | 'view' | 'page' | 'nav';
  pinned?: boolean;      // true => render in the sidebar Pinned section
  navId?: string;        // back-reference to the original NavigationItem.id
  // …plus existing fields: label, href, icon, addedAt, …
}
```

* **One source of truth, one server roundtrip.** Both flows write through the same `UserDataAdapter<FavoriteItem>` (`kind: 'favorites'`).
* **Cross-device sync.** Pinning a sidebar item on the desktop shows up in the same place on mobile, behind the same backend that already syncs Favorites.
* **Bucketed caps.** Content favorites and nav pins each have an independent cap of 20 — migrating sidebar pins never evicts starred records.
* **Legacy migration (one-shot).** The old `objectui-nav-pins` localStorage key (a plain `string[]`) is read once on first mount, converted to `type:'nav'` favorites with `pinned: true`, then removed. If an adapter is attached, the migrated set is also pushed to the backend on the next debounce window.

UIs that surface "favorites" (HomePage Starred, the sidebar Favorites section) filter out `type === 'nav'` so nav-pin records don't pollute the user-visible list. The sidebar Pinned section is rendered from the live navigation tree decorated by `useNavPins.applyPins`.


# AppShell





The AppShell component provides the main application layout structure with an integrated sidebar, header, and content area. It's the foundation for building enterprise applications with ObjectUI.

## Basic Usage [#basic-usage]

```plaintext
import { AppShell } from '@object-ui/layout';
import { SidebarNav } from '@object-ui/layout';

<AppShell
  sidebar={
    <SidebarNav
      items={[
        { label: 'Dashboard', href: '/', icon: 'home' },
        { label: 'Users', href: '/users', icon: 'users' },
        { label: 'Settings', href: '/settings', icon: 'settings' }
      ]}
    />
  }
  navbar={
    <div className="flex items-center gap-4">
      <span className="font-semibold">My App</span>
    </div>
  }
>
  {/* Your page content */}
  <div>Main content area</div>
</AppShell>
```

## Component Props [#component-props]

```plaintext
interface AppShellProps {
  sidebar?: React.ReactNode;     // Sidebar content (usually SidebarNav)
  navbar?: React.ReactNode;      // Top navbar content (logo, search, user menu)
  children: React.ReactNode;     // Main content area
  className?: string;            // Additional CSS classes for content area
  defaultOpen?: boolean;         // Sidebar default state (default: true)
}
```

## Features [#features]

### Responsive Sidebar [#responsive-sidebar]

The AppShell includes a responsive sidebar that:

* Collapses on mobile devices
* Can be toggled via hamburger menu
* Persists state across page navigations
* Supports smooth animations

### Header Bar [#header-bar]

The header bar provides:

* Sidebar toggle button
* Custom navbar content area
* Fixed height (64px / 4rem)
* Border bottom separator
* Background matching app theme

### Content Area [#content-area]

The main content area features:

* Responsive padding (4 on mobile, 6 on desktop)
* Automatic scrolling
* Flexible height (fills viewport)
* Custom className support

## Layout Structure [#layout-structure]

```
┌─────────────────────────────────────┐
│     Header (Sidebar Toggle + Nav)  │
├──────────┬──────────────────────────┤
│          │                          │
│ Sidebar  │   Main Content Area      │
│          │                          │
│          │                          │
│          │                          │
└──────────┴──────────────────────────┘
```

## Sidebar Configuration [#sidebar-configuration]

### Default Open State [#default-open-state]

Control whether sidebar is open by default:

```plaintext
<AppShell defaultOpen={false}>
  {/* Sidebar starts collapsed */}
</AppShell>
```

### Collapsible Sidebar [#collapsible-sidebar]

The sidebar can be toggled via:

* Hamburger menu button (always visible)
* Keyboard shortcuts (when implemented)
* Programmatic control

## Navbar Content [#navbar-content]

The navbar area is flexible and can contain:

### Logo and Title [#logo-and-title]

```plaintext
navbar={
  <div className="flex items-center gap-2">
    <img src="/logo.svg" alt="Logo" className="h-8 w-8" />
    <span className="font-semibold text-lg">My Application</span>
  </div>
}
```

### Search Bar [#search-bar]

```plaintext
navbar={
  <div className="flex-1 max-w-md">
    <Input placeholder="Search..." />
  </div>
}
```

### User Menu [#user-menu]

```plaintext
navbar={
  <div className="flex items-center gap-4 ml-auto">
    <NotificationsButton />
    <UserDropdown />
  </div>
}
```

## Complete Example [#complete-example]

```plaintext
import { AppShell, SidebarNav } from '@object-ui/layout';
import { Avatar, Button, Input } from '@object-ui/components';

function App() {
  return (
    <AppShell
      defaultOpen={true}
      sidebar={
        <SidebarNav
          header={{
            logo: '/logo.svg',
            title: 'ObjectUI'
          }}
          items={[
            {
              label: 'Dashboard',
              href: '/',
              icon: 'layout-dashboard',
              badge: '12'
            },
            {
              label: 'Projects',
              href: '/projects',
              icon: 'folder',
              children: [
                { label: 'Active', href: '/projects/active' },
                { label: 'Archived', href: '/projects/archived' }
              ]
            },
            {
              label: 'Team',
              href: '/team',
              icon: 'users'
            },
            {
              label: 'Settings',
              href: '/settings',
              icon: 'settings'
            }
          ]}
          footer={
            <div className="p-4 border-t">
              <Button variant="outline" className="w-full">
                Upgrade Plan
              </Button>
            </div>
          }
        />
      }
      navbar={
        <div className="flex items-center justify-between w-full">
          {/* Search */}
          <div className="flex-1 max-w-md">
            <Input 
              placeholder="Search..." 
              className="w-full"
            />
          </div>
          
          {/* Right side items */}
          <div className="flex items-center gap-4">
            <Button variant="ghost" size="icon">
              <Bell className="h-5 w-5" />
            </Button>
            <Avatar>
              <AvatarFallback>JD</AvatarFallback>
            </Avatar>
          </div>
        </div>
      }
      className="bg-gray-50"
    >
      {/* Main content */}
      <div className="max-w-7xl">
        <h1 className="text-2xl font-bold mb-4">Dashboard</h1>
        {/* Page content */}
      </div>
    </AppShell>
  );
}
```

## With Page Component [#with-page-component]

Combine AppShell with the Page component for complete layouts:

```plaintext
<AppShell sidebar={<SidebarNav items={navItems} />}>
  <Page
    title="Dashboard"
    description="Welcome to your dashboard"
    body={[
      { type: 'text', content: 'Dashboard content' }
    ]}
  />
</AppShell>
```

## Styling [#styling]

The AppShell uses Tailwind CSS and Shadcn UI components:

* `SidebarProvider`: Manages sidebar state
* `SidebarTrigger`: Hamburger menu button
* `SidebarInset`: Content area wrapper

## Accessibility [#accessibility]

The AppShell includes:

* Proper ARIA labels for sidebar toggle
* Keyboard navigation support
* Focus management
* Screen reader announcements

## Related [#related]

* [SidebarNav](/docs/layout/sidebar-nav) - Sidebar navigation component
* [PageHeader](/docs/layout/page-header) - Page header component
* [Page](/docs/components/layout/page) - Page layout component


# PageHeader





The PageHeader component provides a consistent header for pages with title, description, and action buttons.

## Basic Usage [#basic-usage]

```plaintext
import { PageHeader } from '@object-ui/layout';

<PageHeader
  title="Dashboard"
  description="Welcome to your dashboard"
/>
```

## With Actions [#with-actions]

<SchemaExample id="layout-page-header/pageheader-with-actions" />

## Component Props [#component-props]

```plaintext
interface PageHeaderProps {
  title: string;                 // Page title (required)
  description?: string;          // Page description
  action?: React.ReactNode;      // Action buttons or elements
  children?: React.ReactNode;    // Additional content (actions)
  className?: string;            // Additional CSS classes
}
```

## Examples [#examples]

### Simple Header [#simple-header]

```plaintext
<PageHeader title="Settings" />
```

### With Description [#with-description]

```plaintext
<PageHeader
  title="Analytics"
  description="Track your key metrics and performance indicators"
/>
```

### With Action Buttons [#with-action-buttons]

```plaintext
<PageHeader
  title="Projects"
  description="Manage your projects and tasks"
  action={
    <div className="flex gap-2">
      <Button variant="outline">
        <Download className="mr-2 h-4 w-4" />
        Export
      </Button>
      <Button>
        <Plus className="mr-2 h-4 w-4" />
        New Project
      </Button>
    </div>
  }
/>
```

### With Children [#with-children]

```plaintext
<PageHeader
  title="Team"
  description="Manage your team members"
>
  <Button>Invite Member</Button>
  <Button variant="outline">Settings</Button>
</PageHeader>
```

## Layout [#layout]

The PageHeader uses a flex layout:

```
┌─────────────────────────────────────┐
│ Title                     [Actions] │
│ Description                         │
└─────────────────────────────────────┘
```

* **Left Side**: Title and description stacked vertically
* **Right Side**: Action buttons or custom content
* **Responsive**: Actions move below title on mobile (if needed)

## Styling [#styling]

### Title [#title]

* Font size: `text-2xl` on mobile, `text-3xl` on desktop
* Font weight: `font-bold`
* Tracking: `tracking-tight`

### Description [#description]

* Font size: `text-sm`
* Color: `text-muted-foreground` (gray)

### Container [#container]

* Padding bottom: `pb-4` on mobile, `pb-8` on desktop
* Gap: `gap-4` between elements

## Usage with Page Component [#usage-with-page-component]

The Page component includes built-in PageHeader support:

```plaintext
<Page
  title="Dashboard"
  description="Welcome to your dashboard"
  action={<Button>Add Widget</Button>}
  body={[
    // Page content
  ]}
/>
```

## Complete Example [#complete-example]

```plaintext
import { PageHeader } from '@object-ui/layout';
import { Button } from '@object-ui/components';
import { Plus, Download, Settings } from 'lucide-react';

function UsersPage() {
  return (
    <div>
      <PageHeader
        title="Team Members"
        description="Manage your team members and their roles"
        action={
          <div className="flex items-center gap-2">
            <Button variant="outline" size="sm">
              <Download className="mr-2 h-4 w-4" />
              Export CSV
            </Button>
            <Button variant="outline" size="sm">
              <Settings className="mr-2 h-4 w-4" />
              Settings
            </Button>
            <Button size="sm">
              <Plus className="mr-2 h-4 w-4" />
              Invite Member
            </Button>
          </div>
        }
      />
      
      {/* Page content */}
      <div className="space-y-4">
        {/* Table, cards, etc. */}
      </div>
    </div>
  );
}
```

## Accessibility [#accessibility]

The PageHeader includes:

* Semantic HTML (`<h1>` for title)
* Proper heading hierarchy
* Color contrast for text
* Responsive layout

## Responsive Behavior [#responsive-behavior]

* **Mobile**: Actions stack below title if needed
* **Desktop**: Actions align to right side
* **Spacing**: Adjusts padding for different screen sizes

## Related [#related]

* [Page](/docs/components/layout/page) - Complete page layout
* [AppShell](/docs/layout/app-shell) - Application shell
* [SidebarNav](/docs/layout/sidebar-nav) - Sidebar navigation


# SidebarNav





The SidebarNav component provides a responsive sidebar navigation menu with support for icons, active states, badges, nested collapsible items, grouped navigation, and built-in search filtering.

## Basic Usage [#basic-usage]

```plaintext
import { SidebarNav } from '@object-ui/layout';
import { Home, Users, Settings } from 'lucide-react';

<SidebarNav
  title="My Application"
  items={[
    {
      title: 'Dashboard',
      href: '/',
      icon: Home
    },
    {
      title: 'Users',
      href: '/users',
      icon: Users
    },
    {
      title: 'Settings',
      href: '/settings',
      icon: Settings
    }
  ]}
/>
```

## Component Props [#component-props]

```plaintext
interface SidebarNavProps {
  items: NavItem[] | NavGroup[];  // Navigation items or grouped items
  title?: string;                 // Sidebar title (default: "Application")
  className?: string;             // Additional CSS classes
  collapsible?: "offcanvas" | "icon" | "none";  // Sidebar collapse mode
  searchEnabled?: boolean;        // Show search input to filter items
  searchPlaceholder?: string;     // Placeholder for search input
}

interface NavItem {
  title: string;                  // Item label
  href: string;                   // Navigation URL
  icon?: React.ComponentType;     // Lucide icon component
  badge?: string | number;        // Badge text or count
  badgeVariant?: 'default' | 'destructive' | 'outline';  // Badge style
  children?: NavItem[];           // Nested collapsible sub-items
}

interface NavGroup {
  label: string;                  // Group section label
  items: NavItem[];               // Items in the group
}
```

## Features [#features]

### Active State [#active-state]

The SidebarNav automatically highlights the active route based on the current URL:

```plaintext
// Current URL: /users
// The "Users" menu item will be highlighted
```

### Icons [#icons]

Add Lucide icons to navigation items:

```plaintext
import { 
  LayoutDashboard, 
  Users, 
  FolderKanban, 
  Settings 
} from 'lucide-react';

<SidebarNav
  items={[
    { title: 'Dashboard', href: '/', icon: LayoutDashboard },
    { title: 'Team', href: '/team', icon: Users },
    { title: 'Projects', href: '/projects', icon: FolderKanban },
    { title: 'Settings', href: '/settings', icon: Settings }
  ]}
/>
```

### Badges [#badges]

Add badge counters or labels to navigation items with variant styling:

```plaintext
<SidebarNav
  items={[
    { title: 'Inbox', href: '/inbox', icon: Mail, badge: 12, badgeVariant: 'destructive' },
    { title: 'Projects', href: '/projects', icon: FolderOpen, badge: '3 new', badgeVariant: 'outline' },
    { title: 'Contacts', href: '/contacts', icon: Users, badge: 342 },
  ]}
/>
```

### Nested Items [#nested-items]

Create collapsible sub-navigation with the `children` property:

```plaintext
<SidebarNav
  items={[
    { title: 'Dashboard', href: '/dashboard', icon: Home },
    {
      title: 'Projects',
      href: '/projects',
      icon: FolderOpen,
      badge: 5,
      children: [
        { title: 'Active', href: '/projects/active' },
        { title: 'Archived', href: '/projects/archived' },
        { title: 'Templates', href: '/projects/templates', badge: 2 },
      ],
    },
    { title: 'Settings', href: '/settings', icon: Settings },
  ]}
/>
```

### Grouped Navigation [#grouped-navigation]

Organize items into labeled sections using `NavGroup`:

```plaintext
<SidebarNav
  items={[
    {
      label: 'Main',
      items: [
        { title: 'Dashboard', href: '/dashboard', icon: Home },
        { title: 'Inbox', href: '/inbox', icon: Mail, badge: 5, badgeVariant: 'destructive' },
      ],
    },
    {
      label: 'Content',
      items: [
        { title: 'Documents', href: '/documents', icon: FileText },
        { title: 'Projects', href: '/projects', icon: FolderOpen },
      ],
    },
    {
      label: 'Admin',
      items: [
        { title: 'Users', href: '/admin/users', icon: Users },
        { title: 'Settings', href: '/settings', icon: Settings },
      ],
    },
  ]}
/>
```

### Search Filtering [#search-filtering]

Enable built-in search to filter navigation items and their children:

```plaintext
<SidebarNav
  items={navItems}
  searchEnabled={true}
  searchPlaceholder="Filter navigation..."
/>
```

### Custom Title [#custom-title]

Set a custom title for the sidebar:

```plaintext
<SidebarNav
  title="ObjectUI Dashboard"
  items={navItems}
/>
```

## Complete Example [#complete-example]

```plaintext
import { SidebarNav } from '@object-ui/layout';
import { 
  Home,
  Users,
  FolderOpen,
  BarChart,
  Settings,
  HelpCircle,
  Mail
} from 'lucide-react';

const navigationItems = [
  {
    label: 'Workspace',
    items: [
      { title: 'Dashboard', href: '/', icon: Home },
      { title: 'Inbox', href: '/inbox', icon: Mail, badge: 8, badgeVariant: 'destructive' },
      {
        title: 'Projects',
        href: '/projects',
        icon: FolderOpen,
        badge: 3,
        children: [
          { title: 'Design System', href: '/projects/design' },
          { title: 'API v2', href: '/projects/api', badge: 'WIP', badgeVariant: 'outline' },
          { title: 'Mobile App', href: '/projects/mobile' },
        ],
      },
    ],
  },
  {
    label: 'System',
    items: [
      { title: 'Settings', href: '/settings', icon: Settings },
      { title: 'Help', href: '/help', icon: HelpCircle },
    ],
  },
];

function App() {
  return (
    <SidebarNav
      title="My CRM"
      items={navigationItems}
      searchEnabled={true}
      searchPlaceholder="Search navigation..."
    />
  );
}
```

## Usage with AppShell [#usage-with-appshell]

The SidebarNav is designed to work with AppShell:

```plaintext
import { AppShell, SidebarNav } from '@object-ui/layout';

<AppShell
  sidebar={
    <SidebarNav
      title="My App"
      items={[
        { title: 'Home', href: '/', icon: Home },
        { title: 'About', href: '/about', icon: Info }
      ]}
    />
  }
>
  {/* Your content */}
</AppShell>
```

## Styling [#styling]

The SidebarNav uses Shadcn UI Sidebar components:

* **SidebarGroupLabel**: Section title
* **SidebarMenuItem**: Individual menu items
* **SidebarMenuButton**: Clickable button with active state
* **SidebarMenuSub**: Nested sub-items container
* **Badge**: Badge counters with variant styling

### Active Item [#active-item]

Active items receive:

* Background color highlighting
* Bold text
* Visual indicator

### Hover State [#hover-state]

Menu items on hover:

* Subtle background change
* Smooth transition
* Cursor pointer

## Responsive Behavior [#responsive-behavior]

The SidebarNav works with the AppShell's responsive behavior:

* **Desktop**: Full sidebar visible
* **Mobile**: Collapsible sidebar with hamburger menu
* **Tablet**: Medium-width sidebar

## Navigation [#navigation]

The SidebarNav uses React Router's `NavLink` for:

* Client-side navigation
* Active state detection
* Browser history management
* Back button support

## Accessibility [#accessibility]

The SidebarNav includes:

* Semantic `<nav>` element
* Proper ARIA labels
* Keyboard navigation
* Focus management
* Screen reader support
* Collapsible sections with `aria-expanded`

## Icon Guidelines [#icon-guidelines]

Use Lucide React icons:

```bash
npm install lucide-react
```

Common icons:

* `Home` - Dashboard/home
* `Users` - Team/users
* `Settings` - Settings/config
* `FolderOpen` - Projects/files
* `BarChart` - Analytics/reports
* `Mail` - Messages/email
* `Calendar` - Events/schedule
* `FileText` - Documents

## Related [#related]

* [AppShell](/docs/layout/app-shell) - Application shell layout
* [PageHeader](/docs/layout/page-header) - Page header component
* [Sidebar](/docs/components/basic/sidebar) - Base sidebar component


# RFC 0001 — Excel-style Clipboard Paste



# RFC 0001 — Excel-style Clipboard Paste [#rfc-0001--excel-style-clipboard-paste]

## 0. TL;DR [#0-tldr]

Enterprise users routinely build data in Excel/Google Sheets and want to land
that data into ObjectUI grids without re-typing. Today we have a primitive
cell-level clipboard hook (`useCellClipboard`) and a heavy file-based
`ImportWizard&#x60;, but no smooth path for the most common case: &#x2A;*"select N rows
in a spreadsheet → Ctrl+V into an ObjectUI grid"**.

This RFC defines a **horizontal clipboard-paste capability** that serves three
hosts uniformly:

1. `ObjectGrid` — list views, batch entry into the master table
2. `EditableGridField` — child sub-tables inside `ObjectForm` (Aggregate)
3. `ImportWizard` — reuse the same type-coercion pipeline

The first deliverable is intentionally minimal: a **paste-preview dialog**
running in **staged mode** with four coercer types (text/number/boolean/date),
integrated into `ObjectGrid` behind a feature flag.

## 1. Motivation [#1-motivation]

### 1.1 Real-world scenarios [#11-real-world-scenarios]

| #  | Scenario                                                                          | Host                                        | Today                                                              | Desired                                                 |
| -- | --------------------------------------------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------- |
| S1 | Sales ops pastes 80 new leads from a partner spreadsheet                          | `ObjectGrid` (master)                       | Re-type or use `ImportWizard` (3-step modal, overkill for 80 rows) | Ctrl+V → preview → confirm → staged → Save              |
| S2 | Finance enters an expense report with 20 line items copied from an Excel template | `EditableGridField` (child of `ObjectForm`) | Type each row                                                      | Ctrl+V → preview → rows appended to form state          |
| S3 | Project manager fixes 15 misspelt customer names by pasting a corrected column    | `ObjectGrid` selection                      | `useCellClipboard` works only if selection size matches            | Ctrl+V across selection auto-extends to clipboard range |
| S4 | Admin seeds dictionary data (countries, categories) during app setup              | `ObjectGrid` (master)                       | `ImportWizard` (file required)                                     | Paste from Sheets directly                              |

### 1.2 Why this is high-leverage [#12-why-this-is-high-leverage]

* **One implementation, three hosts** — the parsing/coercion pipeline is pure
  logic; only the commit strategy differs per host.
* **Demo-friendly** — "paste 50 rows in 5 seconds" is an immediate win in
  sales conversations.
* **Aligns with `@objectstack/spec`** — no new field types; we reuse the
  existing `columns` definitions on `GridFieldMetadata` and field metadata on
  list views.

## 2. Goals & Non-Goals [#2-goals--non-goals]

### 2.1 Goals (in scope for v1) [#21-goals-in-scope-for-v1]

* G1 — Parse TSV/CSV clipboard payloads from Excel / Google Sheets / Numbers
  (with quote/escape/newline edge cases).
* G2 — Coerce raw strings into 4 typed values: `text`, `number`, `boolean`,
  `date` (incl. Excel serial dates).
* G3 — Show a **paste-preview dialog** with column mapping, type errors, and
  before/after row counts.
* G4 — Apply paste in **staged mode**: new rows are appended to grid/form
  state; persistence is the host's responsibility.
* G5 — Provide a single React hook `usePasteToGrid` that both `ObjectGrid` and
  the future `EditableGridField` can consume unchanged.
* G6 — Feature-flag gate the integration so any app can opt-in/out per grid.
* G7 — i18n for all user-facing strings (en/zh, others follow `@object-ui/i18n`).
* G8 — Vitest coverage on parser & coercer (≥ 90% on those modules).

### 2.2 Non-Goals (explicitly deferred) [#22-non-goals-explicitly-deferred]

* N1 — **Immediate-commit mode** (paste → write to backend in one shot).
  Deferred because it requires `dataSource.createMany`, partial-success
  handling, undo windows, and audit hooks.
* N2 — **Lookup / user / select / multiselect coercers**. They require async
  resolution and are large enough to warrant their own RFC.
* N3 — **Excel binary `.xlsx` paste** (clipboard only carries TSV; binary
  paste is rare and requires `xlsx`/SheetJS, a \~700KB dep).
* N4 — **Formula support**, merged cells, fill-handle (drag-to-fill).
* N5 — **Bidirectional Excel sync** (export-edit-import round trips). That is
  `ImportWizard`'s territory.
* N6 — **Server-side validation feedback into the dialog**. Staged rows are
  validated client-side only; backend errors surface after Save via the host's
  existing error path.

## 3. Prior Art [#3-prior-art]

Quick survey of how leading platforms approach the same problem; the design
below borrows the best parts.

| Platform                       | Pattern                                                               | What we adopt                                                    | What we drop                                            |
| ------------------------------ | --------------------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------- |
| **AG Grid**                    | `processCellFromClipboard` hook, range selection, fill handle         | Coercion-callback architecture, separation of parse vs transform | Fill handle (deferred), range selection (uses existing) |
| **Handsontable / Univer**      | Full spreadsheet emulation, `paste-plugin` with overwrite/shift modes | "Auto-extend rows when paste exceeds selection"                  | Formulas, merged cells, A1 references                   |
| **Salesforce Lightning**       | Mass Update + Data Loader; no in-grid paste                           | Conservative: large batches go through a wizard                  | "No paste at all" (we provide it for small batches)     |
| **ServiceNow List Editor**     | Inline edit + Ctrl+C/V, no auto-extend                                | Familiar Ctrl+C/V bindings                                       | Strict "no row extension" stance                        |
| **Microsoft Dataverse**        | Excel-style paste, overwrites only; export-edit-import for bulk       | Treat large bulk as a separate flow                              | "Cannot extend rows" limitation                         |
| **Feishu / Lark Bitable**      | Auto-extends rows, type-tolerant, toast feedback                      | UX patterns (toast with row counts, type tolerance)              | Spreadsheet-style cell references                       |
| **Dingtalk Yida / Jiandaoyun** | Sub-form "paste rows" with client-side staging                        | Staged mode as default                                           | —                                                       |
| **Retool / Appsmith**          | Basic paste; developer-driven bulkInsert                              | —                                                                | Not a model we want to follow (too low fidelity)        |

**Industry consensus we encode**:

1. Parse and coerce are **separate phases**.
2. Sub-forms (child tables) universally stage rows in client state before
   commit; this maps to our `EditableGridField` plan perfectly.
3. Master-table bulk entry **should not** happen silently — preview or wizard
   is the safer default.
4. Partial success matters: surface row-level errors, never lose user data.

## 4. Architecture [#4-architecture]

### 4.1 Layering [#41-layering]

```
┌──────────────────────────────────────────────────────────────────┐
│ @object-ui/core/clipboard         (Pure logic, zero React)        │
│   ├── parseClipboard(raw)                                         │
│   ├── coerceCell(raw, columnDef)                                  │
│   └── types: ParsedClipboard, CoerceResult, ColumnCoercer         │
└──────────────────────────────────────────────────────────────────┘
                           ▲
                           │ (depends on)
┌──────────────────────────────────────────────────────────────────┐
│ @object-ui/fields/clipboard       (React layer)                  │
│   ├── usePasteToGrid(opts)                                        │
│   ├── <PastePreviewDialog />                                      │
│   └── types: PasteCommand, PastePreview                           │
└──────────────────────────────────────────────────────────────────┘
                           ▲
        ┌──────────────────┼──────────────────┐
        │                  │                  │
┌───────┴────────┐ ┌──────┴───────┐ ┌────────┴─────────┐
│  ObjectGrid    │ │ EditableGrid │ │  ImportWizard    │
│  (plugin-grid) │ │   Field      │ │  (plugin-grid)   │
│                │ │  (fields)    │ │ — reuses coercer │
└────────────────┘ └──────────────┘ └──────────────────┘
```

Key rules:

* `@object-ui/core/clipboard` has **no React, no Shadcn, no i18n runtime
  dependency**. It emits i18n keys, not strings.
* `@object-ui/fields/clipboard` is the only place that owns the dialog and
  the keyboard glue.
* Hosts (`ObjectGrid`, `EditableGridField`) **do not** know about parsing or
  coercion — they only consume `PasteCommand[]` from the hook.

### 4.2 Why this layering [#42-why-this-layering]

| Concern                         | Owner                           | Rationale                                             |
| ------------------------------- | ------------------------------- | ----------------------------------------------------- |
| String → cell value             | `core/clipboard`                | Pure functions, exhaustive unit tests, no JSX         |
| Dialog UX & keyboard            | `fields/clipboard`              | Shadcn-native, i18n-aware, reusable across hosts      |
| State mutation (rows, commands) | Host                            | Each host has its own state shape and commit strategy |
| Persistence                     | DataSource layer (out of scope) | Hosts decide when/how to flush staged rows            |

## 5. API Contract [#5-api-contract]

### 5.1 Parser (`@object-ui/core/clipboard`) [#51-parser-object-uicoreclipboard]

```ts
export interface ParsedClipboard {
  /** 2D string matrix, rows × cells, never null */
  rows: string[][];
  /** Detected separator */
  format: 'tsv' | 'csv' | 'single';
  /** Best-effort heuristic for telemetry / future tuning */
  sourceHint?: 'excel' | 'google-sheets' | 'numbers' | 'unknown';
  /** Trailing empty rows stripped */
  trimmedTrailingEmpty: number;
}

export function parseClipboard(raw: string): ParsedClipboard;
```

Parser handles:

* `\r\n`, `\r`, `\n` line endings (Excel on Windows commonly emits `\r\n`).
* Standard CSV quoting: `"a,b"`, escaped `""` inside quoted fields, embedded
  newlines inside quotes.
* Excel TSV (tab-separated, no quoting) — the most common path.
* BOM stripping (`\uFEFF` at start).
* Single value (no separators) → `format: 'single'`, `rows: [[value]]`.

### 5.2 Coercer (`@object-ui/core/clipboard`) [#52-coercer-object-uicoreclipboard]

```ts
export type CoercerType =
  | 'text' | 'number' | 'integer' | 'currency' | 'percent'
  | 'boolean' | 'date' | 'datetime' | 'time';
  // v1 ships: text, number, boolean, date
  // v2 will add: integer, currency, percent, datetime, time
  // future RFC: lookup, user, select, multiselect

export interface ColumnCoercer {
  /** Target field name on the row */
  field: string;
  /** Logical type for coercion */
  type: CoercerType;
  /** Whether empty string means null (true) or empty string (false) */
  nullable?: boolean;
  /** Locale for date/number parsing; defaults to current i18n locale */
  locale?: string;
  /** Custom parser overrides built-in for this column */
  parse?: (raw: string) => any;
}

export interface CoerceResult<T = any> {
  ok: boolean;
  value: T | null;
  /** Original string from clipboard */
  rawInput: string;
  /** i18n key when !ok, e.g. 'clipboard.error.invalidNumber' */
  errorKey?: string;
  /** Interpolation values for the i18n template */
  errorParams?: Record<string, unknown>;
  /** Optional hint shown as warning (e.g. "Parsed as 2025-05-18") */
  hintKey?: string;
}

export function coerceCell(raw: string, col: ColumnCoercer): CoerceResult;
```

Coercion details per type (v1):

* **text** — pass through; trims if column flagged.
* **number** — strips `,` thousands separators, currency prefix/suffix
  (`¥ $ € £ ¥`), trailing `%` (divides by 100), accepts `1.5e3`. Locale-aware
  decimal separator (`,` in de/fr).
* **boolean** — case-insensitive: `true/false`, `yes/no`, `y/n`, `1/0`,
  localized yes/no tokens, checkmarks, and `on/off`.
* **date** — tries in order: ISO 8601 → locale short date → Excel serial
  number (1900-system; documented limitation: 1904-system not auto-detected
  in v1). Returns native `Date`.

### 5.3 React Hook (`@object-ui/fields/clipboard`) [#53-react-hook-object-uifieldsclipboard]

```ts
export interface UsePasteToGridOptions {
  /** Columns currently visible / pasteable, in visual order */
  columns: ColumnCoercer[];
  /** Existing rows (for selection-aware paste modes) */
  rows: any[];
  /** Currently selected range, or null when nothing selected */
  selection?: CellRange | null;
  /** Cap rows after paste (e.g. max_rows from GridFieldMetadata) */
  maxRows?: number;
  /** Whether append-beyond-selection is allowed */
  allowAppend?: boolean;
  /** Required when allowAppend=false to produce overwrite-only commands */
  /** Whether to show the preview dialog (recommended: true in v1) */
  preview?: boolean;
  /** Called when user confirms; host applies commands to its state */
  onApply: (commands: PasteCommand[], meta: PasteMeta) => void;
}

export type PasteCommand =
  | { op: 'update'; rowIndex: number; field: string; value: unknown }
  | { op: 'append'; data: Record<string, unknown> };

export interface PasteMeta {
  /** Number of new rows appended */
  appended: number;
  /** Number of existing rows updated */
  updated: number;
  /** Rows that failed coercion and were dropped */
  rejected: number;
  source: 'clipboard';
}

export interface UsePasteToGridResult {
  /** Attach to the grid container as onPaste */
  onPaste: (e: React.ClipboardEvent | ClipboardEvent) => void;
  /** Programmatic trigger (e.g. from a context-menu "Paste" item) */
  triggerPaste: () => Promise<void>;
  /** Currently open preview dialog node (render in the host tree) */
  previewDialog: React.ReactNode;
}

export function usePasteToGrid(opts: UsePasteToGridOptions): UsePasteToGridResult;
```

### 5.4 Preview dialog component [#54-preview-dialog-component]

```tsx
<PastePreviewDialog
  open
  parsed={parsed}                  // ParsedClipboard
  columns={columns}                // ColumnCoercer[]
  initialMapping={autoGuessed}     // Record<csvColIndex, fieldName | null>
  onConfirm={(commands, meta) => ...}
  onCancel={() => ...}
/>
```

Dialog layout (Shadcn `Dialog` + `Table`):

1. **Header**: "Paste N rows into <ObjectLabel>"
2. **Column mapping row** — each clipboard column gets a `Select` widget
   listing target fields (auto-matched by header if first row looks like a
   header; otherwise positional).
3. **Preview table** — first 20 rows, error cells highlighted red with
   tooltip showing the i18n message.
4. **Status bar** — "47 rows ready · 3 rows have errors · 2 columns skipped"
5. **Footer**: `Cancel` · `Append N Rows` (primary, disabled if 0 valid rows).

## 6. Behaviour Specification [#6-behaviour-specification]

### 6.1 Paste-mode decision table [#61-paste-mode-decision-table]

| Trigger context                           | Clipboard size           | Behaviour                                                                                                       |
| ----------------------------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------- |
| Selection of M×N cells, paste fits inside | ≤ selection              | **Overwrite** within selection (no dialog by default for cell-level paste in `ObjectGrid`; see 6.4 quick-paste) |
| Selection exists, paste exceeds           | > selection rows or cols | **Open preview dialog** with "Append" framing                                                                   |
| No selection, grid is focused             | any                      | **Open preview dialog** with "Append at end" framing                                                            |
| Single-cell paste (1×1)                   | 1×1                      | Inline, no dialog                                                                                               |
| `preview: true` in hook opts              | any non-trivial          | Always show dialog                                                                                              |

### 6.2 Column mapping rules [#62-column-mapping-rules]

1. If clipboard row 0 has cells that **exactly match** existing column labels
   or field names (case-insensitive, ignore spaces/underscores), treat row 0
   as a header and skip it during apply.
2. Otherwise, map by **visual order** of grid columns (first clipboard column
   → first grid column, etc.).
3. User can override any mapping in the dialog.
4. Columns the current user lacks write permission for are pre-mapped to
   "Skip" and disabled in the select (with a lock icon).

### 6.3 Validation pyramid [#63-validation-pyramid]

* **Cell** — coercer returns `ok: false` → cell highlighted red, row keeps
  the raw string for user reference.
* **Row** — row is valid iff all mapped cells are `ok`. Invalid rows are
  dropped from the apply set but **kept in the preview** so the user can
  cancel and fix in the source spreadsheet.
* **Table** — `max_rows` cap enforced: if `currentRows + valid > max_rows`,
  surface "Only first K rows will be appended" in the status bar.

### 6.4 Quick-paste optimisation (deferred to v1.1) [#64-quick-paste-optimisation-deferred-to-v11]

When all of the following hold, the dialog **may** be skipped:

* Selection range matches clipboard dimensions exactly.
* All coercions succeed.
* No new rows would be appended.

This matches Excel's silent overwrite. v1 ships with `preview: true` always;
quick-paste is opt-in via `usePasteToGrid({ preview: 'auto' })`.

### 6.5 Feature flag [#65-feature-flag]

Hosts expose paste behind a flag so apps can opt-in per grid:

```tsx
<ObjectGrid
  features={{ clipboardPaste: 'preview' }}  // 'off' | 'preview' | 'auto'
  ...
/>
```

Default in v1: `'off'`. Documentation calls out how to enable it. After one
stable release cycle the default becomes `'preview'`.

## 7. Host Integration [#7-host-integration]

### 7.1 ObjectGrid (master, staged) [#71-objectgrid-master-staged]

```tsx
const { onPaste, previewDialog } = usePasteToGrid({
  columns: coercersFromObjectSchema(schema),
  rows: stagedRows ?? data,
  selection,
  allowAppend: schema.allowAdd !== false,
  preview: true,
  onApply: (commands, meta) => {
    setStagedRows(applyCommands(stagedRows ?? data, commands));
    toast(t('grid.paste.staged', { count: meta.appended }));
  },
});

return (
  <div onPaste={onPaste}>
    {pendingRowCount > 0 && (
      <StagedRowsToolbar
        count={pendingRowCount}
        onSave={saveAllStaged}
        onDiscard={discardStaged}
      />
    )}
    <ObjectGridImpl ... />
    {previewDialog}
  </div>
);
```

**Save All flow** (host-owned, out of RFC scope):

* `dataSource.create` invoked sequentially or batched, depending on adapter.
* Per-row success → swap staged row for server-returned record (real ID).
* Per-row failure → row stays in staged state, error attached.
* No partial-rollback semantics in v1; rows that succeed stay saved.

### 7.2 EditableGridField (child, staged) [#72-editablegridfield-child-staged]

```tsx
const { onPaste, previewDialog } = usePasteToGrid({
  columns: coercersFromGridFieldColumns(field.columns),
  rows: value ?? [],
  selection,
  allowAppend: field.allow_add !== false,
  maxRows: field.max_rows,
  preview: true,
  onApply: (commands) => {
    onChange(applyCommands(value ?? [], commands));
  },
});
```

No persistence concern: rows live in form state until the parent `ObjectForm`
submits.

### 7.3 ImportWizard (refactor for reuse) [#73-importwizard-refactor-for-reuse]

`ImportWizard` already does CSV upload → mapping → preview → import. Today
it has its own string-to-typed-value logic. After this RFC:

* Replace its inline coercion with `coerceCell` from `core/clipboard`.
* No user-facing change; reduces duplication and centralises type tolerance.

This refactor is **not** in the v1 deliverable — it is a follow-up once the
coercer API is stable.

## 8. Product Decisions Requiring Sign-Off [#8-product-decisions-requiring-sign-off]

Four decisions block implementation. Defaults proposed; sign-off needed before
plan.md is written.

| #  | Decision                                  | Default proposed     | Alternative                      | Reasoning                                                                                                                                                                            |
| -- | ----------------------------------------- | -------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| D1 | **Commit mode in v1**                     | `staged` only        | Also ship `immediate`            | Staged is strictly simpler, covers child tables natively, and the master use case loses only one click ("Save All"). Immediate requires `createMany`, partial-success, undo windows. |
| D2 | **Default feature flag**                  | `'off'`              | `'preview'`                      | Conservative roll-out; flip to `'preview'` after one minor version with no critical bugs.                                                                                            |
| D3 | **Preview always or auto-skip when safe** | Always preview in v1 | Auto-skip when selection matches | Always-preview removes a class of "I didn't mean to" bugs. Auto-skip becomes v1.1 opt-in.                                                                                            |
| D4 | **Excel 1904 date system**                | Not auto-detected    | Auto-detect via heuristic        | Heuristic is unreliable; document the limitation and let users override via custom `parse`.                                                                                          |

If any default is rejected, the affected sections must be updated before the
RFC is marked Accepted.

## 9. Testing Strategy [#9-testing-strategy]

| Layer                    | Tool                 | Coverage target                                                                                                             |
| ------------------------ | -------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `parseClipboard`         | Vitest               | 100% branch — covers TSV, CSV, mixed newlines, BOM, quoted with `""`, quoted with embedded newlines, single-cell, all-empty |
| `coerceCell`             | Vitest               | 100% per supported type — locale-sensitive numbers, currency, percent, ISO date, Excel serial, boolean dictionary           |
| `usePasteToGrid`         | RTL + Vitest         | Selection-aware mode decision, header detection, mapping override, error rollup                                             |
| `PastePreviewDialog`     | RTL + Vitest         | Empty preview, all-valid, mixed valid/invalid, all-invalid, skipped columns, max\_rows clamp                                |
| `ObjectGrid` integration | RTL + Playwright e2e | Paste flow end-to-end, staged toolbar, feature flag off path                                                                |
| Cross-browser clipboard  | Playwright           | Chromium + WebKit (Safari has known clipboard quirks)                                                                       |

**Clipboard permission caveat** — Playwright tests must grant
`clipboard-read` / `clipboard-write` per context; documented in test setup.

## 10. Documentation Deliverables [#10-documentation-deliverables]

Per Rule #2 (Documentation Driven Development):

1. **This RFC** (`content/docs/rfcs/0001-clipboard-paste.md`) — frozen on
   acceptance.
2. **User guide** (`content/docs/guide/clipboard-paste.md`) — written
   alongside implementation; covers enabling the feature, supported types,
   limitations, and migration notes from `useCellClipboard`.
3. **Package READMEs** updated:
   * `@object-ui/core` — new `clipboard` submodule
   * `@object-ui/fields` — new `usePasteToGrid` hook
   * `@object-ui/plugin-grid` — new `features.clipboardPaste` prop on
     `ObjectGrid`

## 11. Rollout Plan [#11-rollout-plan]

### Phase A — Pure logic (1 week, isolated PR) [#phase-a--pure-logic-1-week-isolated-pr]

* `parseClipboard` + exhaustive Vitest suite
* `coerceCell` for text/number/boolean/date + Vitest
* i18n keys registered under `clipboard.*` namespace in en + zh

**Exit criteria**: green CI, no consumers yet.

### Phase B — React layer (1 week, isolated PR) [#phase-b--react-layer-1-week-isolated-pr]

* `usePasteToGrid` hook
* `PastePreviewDialog` component

**Exit criteria**: dialog usable in isolation (e.g. RTL harness) with mock data.

### Phase C — ObjectGrid integration (1 week, behind flag) [#phase-c--objectgrid-integration-1-week-behind-flag]

* Add `features.clipboardPaste` prop to `ObjectGrid`
* Staged-rows toolbar component
* Integration test with 100-row Excel paste fixture
* User guide written

**Exit criteria**: feature works end-to-end with flag `'preview'`; flag
default stays `'off'`.

### Phase D — Dogfooding (2-4 weeks, no code) [#phase-d--dogfooding-2-4-weeks-no-code]

* Internal apps opt-in via flag
* Collect feedback on type tolerance gaps, UX friction
* Triage into v1.1 backlog

### Phase E — Follow-ups (separate RFCs) [#phase-e--follow-ups-separate-rfcs]

* `EditableGridField` integration (depends on the child-table RFC)
* `ImportWizard` coercer refactor
* `immediate` commit mode (requires `createMany` + partial-success design)
* Async coercers (lookup / user / select)
* Fill handle, Paste Special menu, drag-file-as-paste

## 12. Risks & Mitigations [#12-risks--mitigations]

| Risk                                                        | Likelihood | Impact | Mitigation                                                                          |
| ----------------------------------------------------------- | ---------- | ------ | ----------------------------------------------------------------------------------- |
| Locale-specific date parsing surprises (US vs EU vs ISO)    | Medium     | Medium | Always show parsed value in preview; let user reject before commit                  |
| Excel writes `\r\n` inside quoted cells — parser regression | Medium     | High   | Quoted-newline test cases in v1 unit suite                                          |
| Pasting 10K rows hangs the UI                               | Low        | High   | Preview caps at 20 rows; commit applies in `requestIdleCallback` batches when > 500 |
| Clipboard API requires HTTPS / user gesture                 | High       | Low    | We attach to user-initiated `paste` events; no programmatic read                    |
| Permission-sensitive columns leak via paste                 | Low        | High   | Mapping step pre-filters non-writable columns; documented in 6.2                    |
| Coercer API churns and breaks `ImportWizard` refactor       | Low        | Medium | Freeze API in this RFC; semver-major any breaking change                            |

## 13. Open Questions [#13-open-questions]

1. Should the dialog support **inline error correction** (click red cell →
   fix → re-validate)? Tempting, but doubles dialog complexity. Proposed:
   defer to v1.1.
2. Should we emit a **structured telemetry event** on paste (row count, type
   error rate, source hint)? Useful for tuning coercers. Proposed: yes, via
   existing analytics provider if present, no-op otherwise.
3. Do we need a &#x2A;*"Don't show preview again"** checkbox? Aligns with Excel
   muscle memory but bypasses safety. Proposed: no in v1; revisit with usage
   data.

## 14. Acceptance Checklist [#14-acceptance-checklist]

Before this RFC is marked **Accepted** and `plan.md` is generated:

* [ ] All four product decisions in §8 signed off
* [ ] Open questions in §13 resolved or explicitly deferred
* [ ] At least one reviewer from each of: protocol/spec, UX, plugin-grid
* [ ] Linked RFC for `EditableGridField` exists (can be Draft) so the
  integration point in §7.2 is not vapourware

***

**Appendix A — i18n key inventory**

```
clipboard.dialog.title          "Paste {{count}} rows"
clipboard.dialog.confirmAppend  "Append {{count}} Rows"
clipboard.dialog.cancel         "Cancel"
clipboard.dialog.statusMixed    "{{valid}} rows ready · {{errors}} with errors"
clipboard.dialog.columnSkipped  "Skipped"
clipboard.dialog.columnLocked   "No write permission"
clipboard.dialog.maxRowsClamp   "Only first {{count}} rows will be appended (max {{max}})"
clipboard.dialog.headerDetected "First row treated as header"

clipboard.error.invalidNumber   "Not a valid number"
clipboard.error.invalidDate     "Not a recognised date"
clipboard.error.invalidBoolean  "Cannot interpret as yes/no"

clipboard.toast.staged          "{{count}} rows added (unsaved)"
clipboard.toast.cancelled       "Paste cancelled"
```

**Appendix B — File layout**

```
packages/core/src/clipboard/
  index.ts
  parse.ts
  coerce.ts
  types.ts
  __tests__/
    parse.test.ts
    coerce.test.ts

packages/fields/src/clipboard/
  index.ts
  usePasteToGrid.ts
  PastePreviewDialog.tsx
  applyCommands.ts
  __tests__/
    usePasteToGrid.test.tsx
    PastePreviewDialog.test.tsx

packages/plugin-grid/src/
  ObjectGrid.tsx           (add features.clipboardPaste branch)
  StagedRowsToolbar.tsx    (new)
```


# ObjectUI CLI



# ObjectUI CLI [#objectui-cli]

`@object-ui/cli` is a standalone command-line tool for scaffolding, developing,
building, linting, testing, and validating ObjectUI applications driven by
JSON or YAML schemas.

It is **not** an oclif plugin — it ships its own `objectui` binary just like
`vite`, `next`, or `astro`.

## Installation [#installation]

```bash
npm install -g @object-ui/cli
# or run on demand
npx @object-ui/cli --help
```

The installed binary is named `objectui`.

## Quick start [#quick-start]

```bash
objectui init my-dashboard --template dashboard
cd my-dashboard
objectui dev app.json
```

Your app runs at `http://localhost:3000`.

## Commands [#commands]

The CLI exposes 15 commands. Run `objectui <command> --help` for the full
flag list.

### `objectui init [name]` [#objectui-init-name]

Scaffold a new ObjectUI project (creates `app.json`, `package.json`,
`vite.config.ts`, `tsconfig.json`, `index.html`, and `src/`).

```bash
objectui init my-app
objectui init my-app --template form
objectui init . --template dashboard
```

| Flag                    | Default     | Description                                     |
| ----------------------- | ----------- | ----------------------------------------------- |
| `-t, --template <name>` | `dashboard` | Template to use (`simple`, `form`, `dashboard`) |

### `objectui dev [schema]` [#objectui-dev-schema]

Start the development server with hot reload. Opens the browser automatically.

```bash
objectui dev app.json
objectui dev pages/                    # file-system routing
objectui dev --port 8080 --no-open
```

| Argument / Flag         | Default     | Description                                         |
| ----------------------- | ----------- | --------------------------------------------------- |
| `[schema]` (positional) | `app.json`  | Path to JSON/YAML schema file or `pages/` directory |
| `-p, --port <port>`     | `3000`      | Port to bind                                        |
| `-h, --host <host>`     | `localhost` | Host to bind                                        |
| `--no-open`             | —           | Do not open the browser                             |

### `objectui serve [schema]` [#objectui-serve-schema]

Legacy alias of `dev`, kept for older scripts. Same positional argument and
`-p`/`-h` flags as `dev` (no `--no-open`).

### `objectui build [schema]` [#objectui-build-schema]

Build the application for production with Vite.

```bash
objectui build app.json
objectui build --out-dir build --clean
```

| Argument / Flag         | Default    | Description                         |
| ----------------------- | ---------- | ----------------------------------- |
| `[schema]` (positional) | `app.json` | Path to JSON/YAML schema file       |
| `-o, --out-dir <dir>`   | `dist`     | Output directory                    |
| `--clean`               | `false`    | Clean output directory before build |

### `objectui start` [#objectui-start]

Serve a previously-built production bundle.

```bash
objectui start
objectui start --port 8080 --dir build
```

| Flag                | Default   | Description        |
| ------------------- | --------- | ------------------ |
| `-p, --port <port>` | `3000`    | Port to bind       |
| `-h, --host <host>` | `0.0.0.0` | Host to bind       |
| `-d, --dir <dir>`   | `dist`    | Directory to serve |

### `objectui lint` [#objectui-lint]

Lint the generated application code with ESLint.

```bash
objectui lint --fix
```

| Flag    | Description              |
| ------- | ------------------------ |
| `--fix` | Automatically fix issues |

### `objectui test` [#objectui-test]

Run the application's tests with Vitest.

```bash
objectui test --watch
objectui test --coverage
objectui test --ui
```

| Flag             | Description                |
| ---------------- | -------------------------- |
| `-w, --watch`    | Watch mode                 |
| `-c, --coverage` | Generate a coverage report |
| `--ui`           | Vitest UI                  |

### `objectui generate <type> <name>` (alias `g`) [#objectui-generate-type-name-alias-g]

Generate new resources.

```bash
objectui generate object User
objectui g page Dashboard
objectui generate plugin my-widget
```

| Flag              | Default    | Description                                                                             |
| ----------------- | ---------- | --------------------------------------------------------------------------------------- |
| `--from <source>` | —          | Generate schema from external source (`openapi.yaml`, `prisma.schema`) — *experimental* |
| `--output <dir>`  | `schemas/` | Output directory for generated schemas                                                  |

### `objectui validate [schema]` [#objectui-validate-schema]

Validate a schema file against the ObjectUI specification. Exits with code `0`
on success and non-zero on failure — use it in CI pipelines.

```bash
objectui validate app.json
objectui validate ./schemas/dashboard.yaml
```

### `objectui check` [#objectui-check]

Validate every schema file detected in the project. No flags.

### `objectui doctor` [#objectui-doctor]

Diagnose common environment issues (Node version, deps, config sanity).

### `objectui add <component>` [#objectui-add-component]

Add a new component renderer scaffold to your project.

```bash
objectui add Input
```

### `objectui studio` [#objectui-studio]

Launch the visual designer (`@object-ui/plugin-designer`) against the local
project.

### `objectui create plugin <name>` [#objectui-create-plugin-name]

Scaffold a new ObjectUI plugin via `@object-ui/create-plugin`.

```bash
objectui create plugin my-awesome-widget
```

### `objectui analyze` [#objectui-analyze]

Analyze the built application.

| Flag                   | Description                |
| ---------------------- | -------------------------- |
| `--bundle-size`        | Inspect bundle size        |
| `--render-performance` | Inspect render performance |

## Schema file format [#schema-file-format]

`dev`, `serve`, `build`, and `validate` accept either JSON or YAML.

### JSON [#json]

```json
{
  "type": "div",
  "className": "min-h-screen flex items-center justify-center",
  "body": {
    "type": "card",
    "title": "Hello World",
    "body": { "type": "text", "content": "Welcome to Object UI!" }
  }
}
```

### YAML [#yaml]

```yaml
type: div
className: min-h-screen flex items-center justify-center
body:
  type: card
  title: Hello World
  body:
    type: text
    content: Welcome to Object UI!
```

### File-system routing [#file-system-routing]

If the project contains a `pages/` directory, `dev` and `build` automatically
switch to file-system routing — every `.json`/`.yaml` file under `pages/` becomes
a route based on its path.

```
my-app/
├── pages/
│   ├── index.json          → /
│   ├── about.json          → /about
│   └── users/
│       └── [id].json       → /users/:id
```

## Programmatic API [#programmatic-api]

```ts
import { serve, init } from '@object-ui/cli';

await serve('app.json', { port: '3000', host: 'localhost' });
await init('my-app', { template: 'dashboard' });
```

Only the long-running `serve` and project-creating `init` are exported as
functions today; other commands are bin-only.

## Troubleshooting [#troubleshooting]

### Port already in use [#port-already-in-use]

```bash
objectui dev --port 3001
```

### Schema not found [#schema-not-found]

```bash
objectui dev ./path/to/schema.json
# or, scaffold a fresh one
objectui init .
```

### Run diagnostics [#run-diagnostics]

```bash
objectui doctor
```

## Package information [#package-information]

|                   |                            |
| ----------------- | -------------------------- |
| **Name**          | `@object-ui/cli`           |
| **Bin**           | `objectui`                 |
| **License**       | MIT                        |
| **Node**          | ≥ 18                       |
| **Compatibility** | `@objectstack/spec` ^3.3.0 |

## Dependencies [#dependencies]

The CLI is built on:

* **Vite** + `@vitejs/plugin-react` — bundling and dev server
* **Express** + `express-rate-limit` — preview / production server
* **Commander** — argument parsing
* **chalk** — terminal colors
* **js-yaml** — YAML parsing
* **glob** — file-system routing scan

## Next steps [#next-steps]

* **[Create Plugin](/docs/utilities/create-plugin)** — author your own plugins
* **[Schema Overview](/docs/guide/schema-overview)** — learn the schema format
* **[Plugins](/docs/plugins)** — explore available plugins
* **[Examples](https://github.com/objectstack-ai/objectui/tree/main/examples)** — see example projects

## Need help? [#need-help]

* [GitHub Issues](https://github.com/objectstack-ai/objectui/issues)
* [Documentation](https://www.objectui.org)


# Create Plugin



# Create Plugin [#create-plugin]

The `@object-ui/create-plugin` package is an interactive CLI tool that scaffolds new ObjectUI plugins with best practices and TypeScript support. It generates a complete plugin structure ready for development.

## Installation [#installation]

```bash
npm install -g @object-ui/create-plugin
```

Or use with npx (recommended):

```bash
npx @object-ui/create-plugin my-plugin
```

## Features [#features]

* 🎯 **Interactive Prompts** - Step-by-step plugin creation
* 📦 **Complete Scaffold** - All files needed to start
* 🔷 **TypeScript First** - Full TypeScript support
* 🎨 **Best Practices** - Follow ObjectUI conventions
* 🚀 **Ready to Develop** - Start coding immediately
* 📝 **Documentation Template** - Includes README and docs

## Quick Start [#quick-start]

### Create a New Plugin [#create-a-new-plugin]

```bash
npx @object-ui/create-plugin my-awesome-plugin
```

This will:

1. Ask you a few questions about your plugin
2. Generate the plugin structure
3. Install dependencies
4. Initialize a git repository

### Interactive Prompts [#interactive-prompts]

When you run `create-plugin`, you'll be asked:

```
? Plugin name: my-awesome-plugin
? Description: An awesome plugin for ObjectUI
? Author: Your Name
? Component name: AwesomeComponent
? Component type: awesome-component
? License: MIT
```

## Generated Structure [#generated-structure]

The tool creates a complete plugin structure:

```
my-awesome-plugin/
├── src/
│   ├── index.tsx              # Main entry point
│   ├── AwesomeComponent.tsx   # Component implementation
│   └── types.ts               # TypeScript types
├── package.json               # Package configuration
├── tsconfig.json             # TypeScript config
├── vite.config.ts            # Vite build config
├── README.md                 # Documentation
└── .gitignore                # Git ignore rules
```

## Generated Files [#generated-files]

### `src/index.tsx` [#srcindextsx]

The main entry point that registers your component:

```typescript
import { ComponentRegistry } from '@object-ui/core'
import { AwesomeComponent } from './AwesomeComponent'

// Auto-register the component
ComponentRegistry.register('awesome-component', AwesomeComponent)

// Export for direct use
export { AwesomeComponent }
export * from './types'
```

### `src/AwesomeComponent.tsx` [#srcawesomecomponenttsx]

The component implementation with lazy loading:

```typescript
import React, { Suspense } from 'react'
import { Skeleton } from '@object-ui/components'
import type { AwesomeComponentProps } from './types'

// Lazy load heavy implementation
const AwesomeImpl = React.lazy(() => import('./AwesomeImpl'))

export const AwesomeComponent: React.FC<AwesomeComponentProps> = (props) => {
  return (
    <Suspense fallback={<Skeleton className="w-full h-[400px]" />}>
      <AwesomeImpl {...props} />
    </Suspense>
  )
}
```

### `src/types.ts` [#srctypests]

TypeScript type definitions:

```typescript
import type { BaseComponentSchema } from '@object-ui/types'

export interface AwesomeComponentSchema extends BaseComponentSchema {
  type: 'awesome-component'
  // Your component-specific props
  message?: string
  color?: string
}

export interface AwesomeComponentProps {
  schema: AwesomeComponentSchema
}
```

### `package.json` [#packagejson]

Pre-configured with all necessary settings:

```json
{
  "name": "@object-ui/plugin-awesome",
  "version": "0.1.0",
  "description": "An awesome plugin for ObjectUI",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "files": ["dist"],
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "test": "vitest"
  },
  "peerDependencies": {
    "@object-ui/core": "^0.3.0",
    "@object-ui/components": "^0.3.0",
    "react": "^18.0.0"
  }
}
```

## Development Workflow [#development-workflow]

After creating your plugin:

### 1. Install Dependencies [#1-install-dependencies]

```bash
cd my-awesome-plugin
npm install
```

### 2. Start Development [#2-start-development]

```bash
npm run dev
```

This starts Vite in dev mode with HMR.

### 3. Implement Your Component [#3-implement-your-component]

Edit `src/AwesomeImpl.tsx`:

```typescript
import React from 'react'
import type { AwesomeComponentProps } from './types'

const AwesomeImpl: React.FC<AwesomeComponentProps> = ({ schema }) => {
  const { message = 'Hello!', color = 'blue' } = schema

  return (
    <div className={`p-4 text-${color}-600`}>
      <h2 className="text-2xl font-bold">{message}</h2>
    </div>
  )
}

export default AwesomeImpl
```

### 4. Add Tests [#4-add-tests]

Create `src/AwesomeComponent.test.tsx`:

```typescript
import { describe, it, expect } from 'vitest'
import { render, screen } from '@testing-library/react'
import { AwesomeComponent } from './AwesomeComponent'

describe('AwesomeComponent', () => {
  it('renders message', () => {
    const schema = {
      type: 'awesome-component' as const,
      message: 'Test message',
    }
    
    render(<AwesomeComponent schema={schema} />)
    expect(screen.getByText('Test message')).toBeInTheDocument()
  })
})
```

### 5. Build for Production [#5-build-for-production]

```bash
npm run build
```

This creates optimized bundles in the `dist/` folder.

### 6. Test in Your App [#6-test-in-your-app]

Link your plugin for local testing:

```bash
# In plugin directory
npm link

# In your app directory
npm link @object-ui/plugin-awesome
```

### 7. Publish to NPM [#7-publish-to-npm]

```bash
npm publish
```

## Configuration Options [#configuration-options]

### Custom Templates [#custom-templates]

You can customize the scaffolding by creating a `.create-plugin.config.js`:

```javascript
// .create-plugin.config.js
module.exports = {
  template: 'custom',
  defaults: {
    author: 'Your Name',
    license: 'MIT',
  },
  prompts: {
    // Custom prompts
  },
}
```

### Plugin Naming Conventions [#plugin-naming-conventions]

Follow these naming conventions:

* **Package name:** `@object-ui/plugin-<name>` or `@yourorg/objectui-plugin-<name>`
* **Component type:** `kebab-case` (e.g., `awesome-component`)
* **Component name:** `PascalCase` (e.g., `AwesomeComponent`)

## Best Practices [#best-practices]

### 1. Lazy Loading [#1-lazy-loading]

Always use lazy loading for heavy dependencies:

```typescript
const HeavyImpl = React.lazy(() => import('./HeavyImpl'))
```

### 2. Type Safety [#2-type-safety]

Export all TypeScript types:

```typescript
export type { AwesomeComponentSchema, AwesomeComponentProps }
```

### 3. Loading States [#3-loading-states]

Provide meaningful loading states:

```typescript
<Suspense fallback={<Skeleton className="w-full h-[200px]" />}>
  <AwesomeImpl {...props} />
</Suspense>
```

### 4. Documentation [#4-documentation]

Include comprehensive documentation:

* README with usage examples
* JSDoc comments for all exports

### 5. Testing [#5-testing]

Write tests for all functionality:

* Unit tests for components
* Integration tests for schemas
* E2E tests for user flows

## Example Plugins [#example-plugins]

See these official plugins for reference:

* **[@object-ui/plugin-charts](https://github.com/objectstack-ai/objectui/tree/main/packages/plugin-charts)** - Data visualization
* **[@object-ui/plugin-kanban](https://github.com/objectstack-ai/objectui/tree/main/packages/plugin-kanban)** - Kanban boards
* **[@object-ui/plugin-editor](https://github.com/objectstack-ai/objectui/tree/main/packages/plugin-editor)** - Code editor

## Package Information [#package-information]

**Package Name:** `@object-ui/create-plugin`\
&#x2A;*Version:** 0.3.1\
&#x2A;*Binary:** `create-plugin`\
&#x2A;*License:** MIT

## Dependencies [#dependencies]

The tool uses:

* **Inquirer** - Interactive prompts
* **Chalk** - Terminal colors
* **Ora** - Loading spinners
* **fs-extra** - File system utilities

## Next Steps [#next-steps]

* **[Plugin Concepts](/docs/guide/plugins)** - Learn how plugins work
* **[CLI](/docs/utilities/cli)** - Test your plugin with the CLI
* **[Component Registry](/docs/guide/component-registry)** - Register components
* **[Plugin Development Guide](/docs/guide/plugins)** - Learn plugin best practices

## Troubleshooting [#troubleshooting]

### Permission Denied [#permission-denied]

```bash
# On Linux/Mac, use sudo
sudo npm install -g @object-ui/create-plugin
```

### Template Not Found [#template-not-found]

Make sure you have the latest version:

```bash
npm update -g @object-ui/create-plugin
```

### Dependencies Not Installing [#dependencies-not-installing]

Try clearing npm cache:

```bash
npm cache clean --force
npx @object-ui/create-plugin my-plugin
```

## Need Help? [#need-help]

* [GitHub Issues](https://github.com/objectstack-ai/objectui/issues)
* [Plugin Development Guide](/docs/guide/plugins)
* [Examples](https://github.com/objectstack-ai/objectui/tree/main/packages)


# ObjectStack Data Adapter



# ObjectStack Data Adapter [#objectstack-data-adapter]

The `@object-ui/data-objectstack` package provides a data adapter that connects ObjectUI to ObjectStack backends. It enables seamless integration with ObjectStack's data layer, supporting CRUD operations, queries, and real-time updates.

## Installation [#installation]

```bash
npm install @object-ui/data-objectstack @objectstack/client
```

**Note:** The `@objectstack/client` package is a peer dependency and must be installed separately.

## Overview [#overview]

The ObjectStack adapter bridges ObjectUI's schema-driven UI with ObjectStack's data backend, providing:

* 🔌 **Automatic Integration** - Connect to ObjectStack APIs
* 🔄 **CRUD Operations** - Create, read, update, delete
* 🔍 **Query Builder** - Build complex queries
* 📊 **Data Binding** - Automatic data synchronization
* 🚀 **Real-time Updates** - Live data updates (if supported by backend)

## Features [#features]

* **ObjectStack Client Integration** - Uses `@objectstack/client` for API communication
* **Data Provider** - React context provider for data access
* **Query Support** - Full ObjectQL query support
* **Automatic Field Mapping** - Maps ObjectStack schemas to UI components
* **Type Safety** - Full TypeScript support
* **Error Handling** - Comprehensive error handling and retry logic

## Quick Start [#quick-start]

### 1. Setup Provider [#1-setup-provider]

Wrap your app with the `ObjectStackProvider`:

```typescript
import { ObjectStackProvider } from '@object-ui/data-objectstack'
import { SchemaRenderer } from '@object-ui/react'

function App() {
  return (
    <ObjectStackProvider
      apiUrl="https://api.example.com"
      apiKey="your-api-key"
    >
      <SchemaRenderer schema={schema} />
    </ObjectStackProvider>
  )
}
```

### 2. Use in Schemas [#2-use-in-schemas]

Reference ObjectStack data sources in your schemas:

```json
{
  "type": "data-table",
  "dataSource": {
    "type": "objectstack",
    "object": "users",
    "query": {
      "filters": [
        {
          "field": "status",
          "operator": "eq",
          "value": "active"
        }
      ],
      "sort": [
        {
          "field": "createdAt",
          "direction": "desc"
        }
      ],
      "limit": 50
    }
  },
  "columns": [
    {
      "key": "name",
      "title": "Name"
    },
    {
      "key": "email",
      "title": "Email"
    },
    {
      "key": "status",
      "title": "Status"
    }
  ]
}
```

## API Reference [#api-reference]

### `ObjectStackProvider` [#objectstackprovider]

React context provider for ObjectStack integration.

**Props:**

```typescript
interface ObjectStackProviderProps {
  /** API endpoint URL */
  apiUrl: string
  
  /** API authentication key */
  apiKey: string
  
  /** Optional organization ID */
  organizationId?: string
  
  /** Optional custom configuration */
  config?: ObjectStackConfig
  
  /** Children components */
  children: React.ReactNode
}
```

**Example:**

```typescript
<ObjectStackProvider
  apiUrl="https://api.objectstack.dev"
  apiKey={process.env.REACT_APP_OBJECTSTACK_KEY}
  organizationId="org_123"
>
  <App />
</ObjectStackProvider>
```

### `useObjectStack` [#useobjectstack]

Hook to access the ObjectStack client:

```typescript
import { useObjectStack } from '@object-ui/data-objectstack'

function MyComponent() {
  const client = useObjectStack()
  
  const fetchUsers = async () => {
    const users = await client.query('users', {
      filters: [{ field: 'status', operator: 'eq', value: 'active' }]
    })
    return users
  }
  
  // ...
}
```

### Data Source Schema [#data-source-schema]

Configure ObjectStack data sources in your schemas:

```typescript
interface ObjectStackDataSource {
  /** Data source type */
  type: 'objectstack'
  
  /** Object/table name */
  object: string
  
  /** Optional query */
  query?: {
    /** Filter conditions */
    filters?: Array<{
      field: string
      operator: 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin' | 'like'
      value: any
    }>
    
    /** Sort order */
    sort?: Array<{
      field: string
      direction: 'asc' | 'desc'
    }>
    
    /** Pagination */
    limit?: number
    offset?: number
    
    /** Field selection */
    select?: string[]
  }
}
```

## Usage Examples [#usage-examples]

### Basic Data Table [#basic-data-table]

```json
{
  "type": "data-table",
  "dataSource": {
    "type": "objectstack",
    "object": "products",
    "query": {
      "limit": 20,
      "sort": [{ "field": "name", "direction": "asc" }]
    }
  },
  "columns": [
    { "key": "name", "title": "Product Name" },
    { "key": "price", "title": "Price" },
    { "key": "stock", "title": "Stock" }
  ]
}
```

### Filtered Data [#filtered-data]

```json
{
  "type": "grid",
  "dataSource": {
    "type": "objectstack",
    "object": "orders",
    "query": {
      "filters": [
        { "field": "status", "operator": "eq", "value": "pending" },
        { "field": "total", "operator": "gt", "value": 100 }
      ],
      "sort": [{ "field": "createdAt", "direction": "desc" }],
      "limit": 50
    }
  }
}
```

### Form with ObjectStack Backend [#form-with-objectstack-backend]

```json
{
  "type": "form",
  "dataSource": {
    "type": "objectstack",
    "object": "users",
    "action": "create"
  },
  "fields": [
    {
      "name": "name",
      "type": "text",
      "label": "Full Name",
      "required": true
    },
    {
      "name": "email",
      "type": "email",
      "label": "Email Address",
      "required": true
    },
    {
      "name": "role",
      "type": "select",
      "label": "Role",
      "options": [
        { "value": "admin", "label": "Administrator" },
        { "value": "user", "label": "User" }
      ]
    }
  ],
  "onSubmit": {
    "type": "objectstack.create",
    "object": "users",
    "redirect": "/users"
  }
}
```

### Real-time Updates [#real-time-updates]

```json
{
  "type": "kanban",
  "dataSource": {
    "type": "objectstack",
    "object": "tasks",
    "realtime": true,
    "query": {
      "filters": [
        { "field": "project", "operator": "eq", "value": "${projectId}" }
      ]
    }
  },
  "columns": [
    {
      "id": "todo",
      "title": "To Do",
      "statusField": "status",
      "statusValue": "todo"
    },
    {
      "id": "in-progress",
      "title": "In Progress",
      "statusField": "status",
      "statusValue": "in-progress"
    },
    {
      "id": "done",
      "title": "Done",
      "statusField": "status",
      "statusValue": "done"
    }
  ]
}
```

## Configuration [#configuration]

### Environment Variables [#environment-variables]

```bash
# .env
REACT_APP_OBJECTSTACK_API_URL=https://api.objectstack.dev
REACT_APP_OBJECTSTACK_API_KEY=your_api_key_here
REACT_APP_OBJECTSTACK_ORG_ID=org_123
```

### Custom Configuration [#custom-configuration]

```typescript
import { ObjectStackProvider } from '@object-ui/data-objectstack'

const config = {
  timeout: 30000,
  retries: 3,
  caching: true,
  debug: process.env.NODE_ENV === 'development',
}

<ObjectStackProvider
  apiUrl={process.env.REACT_APP_OBJECTSTACK_API_URL}
  apiKey={process.env.REACT_APP_OBJECTSTACK_API_KEY}
  config={config}
>
  <App />
</ObjectStackProvider>
```

## Advanced Usage [#advanced-usage]

### Custom Queries [#custom-queries]

Use the client directly for complex queries:

```typescript
import { useObjectStack } from '@object-ui/data-objectstack'

function Dashboard() {
  const client = useObjectStack()
  
  const fetchDashboardData = async () => {
    // Multiple queries in parallel
    const [users, orders, revenue] = await Promise.all([
      client.query('users', { 
        filters: [{ field: 'createdAt', operator: 'gte', value: startDate }]
      }),
      client.query('orders', {
        filters: [{ field: 'status', operator: 'eq', value: 'completed' }]
      }),
      client.aggregate('orders', {
        field: 'total',
        operation: 'sum',
        groupBy: 'month'
      })
    ])
    
    return { users, orders, revenue }
  }
  
  // ...
}
```

### Mutations [#mutations]

Create, update, and delete records:

```typescript
import { useObjectStack } from '@object-ui/data-objectstack'

function UserForm() {
  const client = useObjectStack()
  
  const createUser = async (data) => {
    const user = await client.create('users', data)
    return user
  }
  
  const updateUser = async (id, data) => {
    const user = await client.update('users', id, data)
    return user
  }
  
  const deleteUser = async (id) => {
    await client.delete('users', id)
  }
  
  // ...
}
```

### Error Handling [#error-handling]

```typescript
import { useObjectStack } from '@object-ui/data-objectstack'

function DataComponent() {
  const client = useObjectStack()
  const [error, setError] = useState(null)
  
  const fetchData = async () => {
    try {
      const data = await client.query('users')
      return data
    } catch (err) {
      if (err.code === 'UNAUTHORIZED') {
        // Handle auth error
        setError('Please log in')
      } else if (err.code === 'NOT_FOUND') {
        // Handle not found
        setError('Data not found')
      } else {
        // Handle other errors
        setError('An error occurred')
      }
    }
  }
  
  // ...
}
```

## Package Information [#package-information]

**Package Name:** `@object-ui/data-objectstack`\
&#x2A;*Version:** 0.3.1\
&#x2A;*License:** MIT

## Dependencies [#dependencies]

* **@objectstack/client** (peer dependency) - ObjectStack API client
* **@object-ui/types** - TypeScript types
* **react** (peer dependency) - React library

## Integration with Plugins [#integration-with-plugins]

Many plugins support ObjectStack data sources:

* **plugin-grid** - Data grids with ObjectStack queries
* **plugin-form** - Forms with ObjectStack CRUD
* **plugin-kanban** - Kanban boards with ObjectStack data
* **plugin-calendar** - Calendars with ObjectStack events
* **plugin-gantt** - Gantt charts with ObjectStack tasks
* **plugin-map** - Maps with ObjectStack locations

## Next Steps [#next-steps]

* **[ObjectStack Documentation](https://objectstack.dev/docs)** - Learn about ObjectStack
* **[Data Sources Guide](/docs/guide/data-source)** - Learn about data sources
* **[Plugins](/docs/plugins)** - Explore plugins with data support
* **[Schema Overview](/docs/guide/schema-overview)** - Learn the schema format

## Troubleshooting [#troubleshooting]

### Authentication Errors [#authentication-errors]

Check your API key and URL:

```typescript
console.log('API URL:', process.env.REACT_APP_OBJECTSTACK_API_URL)
console.log('API Key:', process.env.REACT_APP_OBJECTSTACK_API_KEY?.substring(0, 10) + '...')
```

### CORS Issues [#cors-issues]

Configure CORS on your ObjectStack backend to allow your domain.

### Data Not Loading [#data-not-loading]

Check browser console and network tab for errors. Verify:

* API endpoint is correct
* API key is valid
* Object name exists in your ObjectStack instance
* Query syntax is correct

## Need Help? [#need-help]

* [ObjectStack Documentation](https://objectstack.dev/docs)
* [GitHub Issues](https://github.com/objectstack-ai/objectui/issues)
* [ObjectUI Documentation](https://www.objectui.org)


# Utilities & Tools



# Utilities & Tools [#utilities--tools]

ObjectUI provides a comprehensive suite of command-line tools and utilities to streamline your development workflow. These tools help you scaffold projects, create plugins, integrate with data sources, and develop with enhanced tooling support.

## Quick Navigation [#quick-navigation]

Browse available utilities:

### Development Tools [#development-tools]

* **[CLI](/docs/utilities/cli)** - Project scaffolding and development server
* **[Create Plugin](/docs/utilities/create-plugin)** - Plugin template generator
* **[Runner](/docs/utilities/runner)** - Universal application runtime

### Data Integration [#data-integration]

* **[ObjectStack Adapter](/docs/utilities/data-objectstack)** - Connect to ObjectStack backend

### Editor Extensions [#editor-extensions]

* **[VS Code Extension](/docs/utilities/vscode-extension)** - Schema editor and IntelliSense

## Official Utilities [#official-utilities]

### CLI [#cli]

**[@object-ui/cli](/docs/utilities/cli)** - Command-line interface for scaffolding and running ObjectUI applications.

* Project scaffolding from JSON schemas
* Built-in development server (Express + Vite)
* JSON/YAML schema support
* Hot module reloading

```bash
npm install -g @object-ui/cli
objectui --help
```

[Read full documentation →](/docs/utilities/cli)

***

### Create Plugin [#create-plugin]

**[@object-ui/create-plugin](/docs/utilities/create-plugin)** - Interactive CLI tool for creating ObjectUI plugins.

* Plugin template generation
* Interactive configuration prompts
* Best practices scaffolding
* TypeScript support

```bash
npm install -g @object-ui/create-plugin
create-plugin my-awesome-plugin
```

[Read full documentation →](/docs/utilities/create-plugin)

***

### Runner [#runner]

**[@object-ui/runner](/docs/utilities/runner)** - Universal runtime for running ObjectUI applications.

* Standalone demo application
* Plugin testing environment
* Development playground
* Example implementations

```bash
cd packages/runner
pnpm dev
```

[Read full documentation →](/docs/utilities/runner)

***

### ObjectStack Adapter [#objectstack-adapter]

**[@object-ui/data-objectstack](/docs/utilities/data-objectstack)** - Data adapter for connecting to ObjectStack backends.

* ObjectStack client integration
* Automatic data binding
* CRUD operations support
* Query builder integration

```bash
npm install @object-ui/data-objectstack @objectstack/client
```

[Read full documentation →](/docs/utilities/data-objectstack)

***

### VS Code Extension [#vs-code-extension]

**[object-ui](/docs/utilities/vscode-extension)** - Visual Studio Code extension for ObjectUI schema development.

* Schema preview
* JSON validation
* IntelliSense and auto-completion
* Syntax highlighting
* Export to React components
* Schema formatting

```bash
# Install from VS Code Marketplace
code --install-extension objectui.object-ui
```

[Read full documentation →](/docs/utilities/vscode-extension)

***

## How Utilities Work [#how-utilities-work]

### CLI Workflow [#cli-workflow]

The ObjectUI CLI provides a streamlined workflow for building applications:

```bash
# 1. Create a new project
objectui init my-app

# 2. Start the development server
cd my-app
objectui dev

# 3. Build for production
objectui build
```

### Plugin Development Workflow [#plugin-development-workflow]

Creating plugins is simplified with the create-plugin utility:

```bash
# 1. Generate plugin scaffold
create-plugin my-plugin

# 2. Implement your component
cd my-plugin/src
# Edit index.tsx

# 3. Test your plugin
pnpm dev

# 4. Publish to npm
pnpm publish
```

### Data Integration [#data-integration-1]

Connect to ObjectStack backends with the data adapter:

```typescript
import { ObjectStackProvider } from '@object-ui/data-objectstack'

function App() {
  return (
    <ObjectStackProvider
      apiUrl="https://api.example.com"
      apiKey="your-api-key"
    >
      <SchemaRenderer schema={schema} />
    </ObjectStackProvider>
  )
}
```

## Features [#features]

All ObjectUI utilities share these characteristics:

* ✅ **Easy to Use** - Simple CLI interfaces
* ✅ **Best Practices** - Follow framework conventions
* ✅ **Type-Safe** - Full TypeScript support
* ✅ **Well Documented** - Comprehensive guides
* ✅ **Actively Maintained** - Regular updates

## Next Steps [#next-steps]

* **[CLI Documentation](/docs/utilities/cli)** - Learn how to use the ObjectUI CLI
* **[Create Plugin Guide](/docs/utilities/create-plugin)** - Build your first plugin
* **[VS Code Extension](/docs/utilities/vscode-extension)** - Set up your development environment
* **[Plugin Concepts](/docs/guide/plugins)** - Learn how plugins work in detail

## Need Help? [#need-help]

Can't find what you're looking for? Check out:

* [Guide](/docs/guide) - Core concepts and guides
* [Plugins](/docs/plugins) - Explore available plugins
* [GitHub](https://github.com/objectstack-ai/objectui) - Report issues or contribute


# Runner



# ObjectUI Runner [#objectui-runner]

The `@object-ui/runner` package is a universal runtime application for ObjectUI. It serves as a standalone demo environment, plugin testing playground, and reference implementation for building ObjectUI applications.

## Overview [#overview]

The Runner is a complete ObjectUI application that demonstrates best practices and provides a development environment for testing plugins and features.

## Features [#features]

* 🎮 **Standalone Application** - Complete ObjectUI app
* 🧪 **Plugin Testing** - Test plugins in isolation
* 🎨 **Example Implementations** - Reference code
* 🚀 **Development Playground** - Experiment with schemas
* 📦 **Pre-configured** - All official plugins included

## Running the Runner [#running-the-runner]

### From Source [#from-source]

```bash
# Clone the repository
git clone https://github.com/objectstack-ai/objectui.git
cd objectui

# Install dependencies
pnpm install

# Run the runner
cd packages/runner
pnpm dev
```

The runner will start at `http://localhost:5173`.

### Using PNPM Workspace [#using-pnpm-workspace]

From the repository root:

```bash
# Run runner from root
pnpm --filter @object-ui/runner dev
```

## What's Included [#whats-included]

### Pre-installed Plugins [#pre-installed-plugins]

The Runner includes these plugins by default:

* **@object-ui/plugin-kanban** - Kanban board with drag-and-drop
* **@object-ui/plugin-charts** - Data visualization charts

### Example Schemas [#example-schemas]

The Runner includes example schemas demonstrating:

* Dashboard layouts
* Data tables and grids
* Form validation
* Kanban boards
* Chart visualizations
* Calendar views
* Timeline displays

### Development Tools [#development-tools]

* **Hot Module Reloading** - Instant updates
* **Error Overlay** - Debug errors easily
* **React DevTools** - Inspect component tree
* **Network Inspector** - Monitor API calls

## Directory Structure [#directory-structure]

```
packages/runner/
├── src/
│   ├── App.tsx              # Main application
│   ├── main.tsx             # Entry point
│   ├── schemas/             # Example schemas
│   │   ├── dashboard.json
│   │   ├── kanban.json
│   │   └── charts.json
│   └── components/          # Custom components
├── public/                  # Static assets
├── package.json
└── vite.config.ts
```

## Configuration [#configuration]

### `vite.config.ts` [#viteconfigts]

The Runner uses Vite for development and building:

```typescript
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  server: {
    port: 5173,
    open: true,
  },
})
```

### Adding Custom Plugins [#adding-custom-plugins]

To test your own plugin:

1. **Link your plugin:**

```bash
# In your plugin directory
npm link

# In runner directory
npm link @object-ui/plugin-yourplugin
```

2. **Import in `src/main.tsx`:**

```typescript
import '@object-ui/plugin-yourplugin'
```

3. **Use in schemas:**

```json
{
  "type": "your-component",
  "props": {
    // Your component props
  }
}
```

## Use Cases [#use-cases]

### 1. Plugin Development [#1-plugin-development]

Test new plugins in a full application context:

```typescript
// src/main.tsx
import '@object-ui/plugin-myplugin'

// src/schemas/test.json
{
  "type": "my-component",
  "message": "Testing my plugin"
}
```

### 2. Schema Prototyping [#2-schema-prototyping]

Experiment with complex schemas:

```bash
# Edit schemas in src/schemas/
# Changes are reflected immediately
```

### 3. Integration Testing [#3-integration-testing]

Test how multiple plugins work together:

```json
{
  "type": "div",
  "children": [
    { "type": "kanban", "..." },
    { "type": "bar-chart", "..." },
    { "type": "data-table", "..." }
  ]
}
```

### 4. Demo & Presentation [#4-demo--presentation]

Use as a live demo environment:

```bash
# Start runner for presentation
pnpm dev --host

# Access from any device on network
# http://your-ip:5173
```

## Example Schemas [#example-schemas-1]

### Dashboard Example [#dashboard-example]

```json
{
  "type": "div",
  "className": "p-8 space-y-6",
  "children": [
    {
      "type": "heading",
      "level": 1,
      "children": "Sales Dashboard"
    },
    {
      "type": "div",
      "className": "grid grid-cols-3 gap-4",
      "children": [
        {
          "type": "card",
          "title": "Revenue",
          "value": "$125,000",
          "change": "+12.5%"
        },
        {
          "type": "card",
          "title": "Orders",
          "value": "1,234",
          "change": "+8.2%"
        },
        {
          "type": "card",
          "title": "Customers",
          "value": "567",
          "change": "+5.1%"
        }
      ]
    },
    {
      "type": "bar-chart",
      "data": [
        { "month": "Jan", "sales": 4000 },
        { "month": "Feb", "sales": 3000 },
        { "month": "Mar", "sales": 6000 }
      ],
      "dataKey": "sales",
      "xAxisKey": "month",
      "height": 300
    }
  ]
}
```

### Kanban Example [#kanban-example]

```json
{
  "type": "kanban",
  "columns": [
    {
      "id": "todo",
      "title": "To Do",
      "cards": [
        {
          "id": "1",
          "title": "Design homepage",
          "description": "Create wireframes"
        }
      ]
    },
    {
      "id": "in-progress",
      "title": "In Progress",
      "cards": []
    },
    {
      "id": "done",
      "title": "Done",
      "cards": []
    }
  ]
}
```

## Development Scripts [#development-scripts]

### `pnpm dev` [#pnpm-dev]

Start development server with HMR:

```bash
pnpm dev
```

### `pnpm build` [#pnpm-build]

Build for production:

```bash
pnpm build
```

### `pnpm preview` [#pnpm-preview]

Preview production build:

```bash
pnpm preview
```

### `pnpm test` [#pnpm-test]

Run tests:

```bash
pnpm test
```

## Environment Variables [#environment-variables]

Configure the runner with environment variables:

```bash
# .env
VITE_API_URL=http://localhost:3000
VITE_APP_TITLE="ObjectUI Runner"
```

Use in code:

```typescript
const apiUrl = import.meta.env.VITE_API_URL
```

## Package Information [#package-information]

**Package Name:** `@object-ui/runner`\
&#x2A;*Version:** 0.3.1\
&#x2A;*Type:** Application (not published to npm)\
&#x2A;*License:** MIT

## Dependencies [#dependencies]

Key dependencies:

* **@object-ui/react** - Core renderer
* **@object-ui/components** - UI components
* **@object-ui/plugin-kanban** - Kanban plugin
* **@object-ui/plugin-charts** - Charts plugin
* **React** - UI library
* **Vite** - Build tool

## Extending the Runner [#extending-the-runner]

### Add Custom Routes [#add-custom-routes]

Edit `src/App.tsx`:

```typescript
import { BrowserRouter, Routes, Route } from 'react-router-dom'

function App() {
  return (
    <BrowserRouter>
      <Routes>
        <Route path="/" element={<Home />} />
        <Route path="/dashboard" element={<Dashboard />} />
        <Route path="/custom" element={<CustomPage />} />
      </Routes>
    </BrowserRouter>
  )
}
```

### Add Custom Components [#add-custom-components]

Create in `src/components/`:

```typescript
// src/components/MyComponent.tsx
export const MyComponent = () => {
  return <div>My Custom Component</div>
}
```

Register with the ComponentRegistry:

```typescript
import { ComponentRegistry } from '@object-ui/core'
import { MyComponent } from './components/MyComponent'

ComponentRegistry.register('my-component', MyComponent)
```

### Add Custom Schemas [#add-custom-schemas]

Add to `src/schemas/`:

```json
// src/schemas/my-page.json
{
  "type": "div",
  "className": "p-8",
  "children": [
    {
      "type": "my-component"
    }
  ]
}
```

## Best Practices [#best-practices]

### 1. Modular Schemas [#1-modular-schemas]

Keep schemas in separate files:

```
src/schemas/
├── dashboard.json
├── kanban.json
├── charts.json
└── index.ts
```

### 2. Environment Configuration [#2-environment-configuration]

Use environment variables for configuration:

```typescript
const config = {
  apiUrl: import.meta.env.VITE_API_URL,
  features: {
    analytics: import.meta.env.VITE_ENABLE_ANALYTICS === 'true',
  },
}
```

### 3. Error Boundaries [#3-error-boundaries]

Wrap components in error boundaries:

```typescript
import { ErrorBoundary } from '@object-ui/components'

<ErrorBoundary>
  <SchemaRenderer schema={schema} />
</ErrorBoundary>
```

## Next Steps [#next-steps]

* **[CLI](/docs/utilities/cli)** - Use CLI for rapid development
* **[Plugins](/docs/plugins)** - Explore available plugins
* **[Schema Overview](/docs/guide/schema-overview)** - Learn schema format
* **[Examples](https://github.com/objectstack-ai/objectui/tree/main/examples)** - See more examples

## Troubleshooting [#troubleshooting]

### Port Already in Use [#port-already-in-use]

Change port in `vite.config.ts`:

```typescript
export default defineConfig({
  server: {
    port: 3000, // Use different port
  },
})
```

### Plugin Not Loading [#plugin-not-loading]

Check if plugin is imported in `main.tsx`:

```typescript
import '@object-ui/plugin-yourplugin'
```

### Build Errors [#build-errors]

Clear cache and rebuild:

```bash
rm -rf node_modules dist .vite
pnpm install
pnpm build
```

## Need Help? [#need-help]

* [GitHub Issues](https://github.com/objectstack-ai/objectui/issues)
* [Documentation](https://www.objectui.org)
* [Examples](https://github.com/objectstack-ai/objectui/tree/main/examples)


# VS Code Extension



# ObjectUI VS Code Extension [#objectui-vs-code-extension]

The ObjectUI VS Code extension provides a comprehensive development environment for creating and editing ObjectUI schemas. It includes schema preview, validation, IntelliSense, syntax highlighting, and powerful productivity features.

## Installation [#installation]

### From VS Code Marketplace [#from-vs-code-marketplace]

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
3. Search for "ObjectUI"
4. Click Install

### From Command Line [#from-command-line]

```bash
code --install-extension objectui.object-ui
```

### Manual Installation [#manual-installation]

Download the `.vsix` file from the releases page and install:

```bash
code --install-extension objectui-0.3.1.vsix
```

## Features [#features]

* 🔍 **Schema Preview** - Live preview of your UI schemas
* ✅ **JSON Validation** - Real-time schema validation
* 💡 **IntelliSense** - Auto-completion for schema properties
* 🎨 **Syntax Highlighting** - Enhanced JSON highlighting for ObjectUI
* 📝 **Snippets** - Quick schema templates
* 🔧 **Commands** - Useful schema manipulation commands
* 🚀 **Export to React** - Convert schemas to React components
* 📋 **Format Schema** - Auto-format your schema files

## Commands [#commands]

Access commands via Command Palette (Ctrl+Shift+P / Cmd+Shift+P):

### `ObjectUI: Preview Schema` [#objectui-preview-schema]

Opens a live preview of your schema in a side panel.

**Usage:**

1. Open a `.json` or `.objectui.json` file
2. Press `Ctrl+Shift+P` (Windows/Linux) or `Cmd+Shift+P` (Mac)
3. Type "ObjectUI: Preview Schema"
4. Preview opens in side panel

**Keyboard Shortcut:** `Ctrl+Alt+P` (Windows/Linux) or `Cmd+Alt+P` (Mac)

### `ObjectUI: Validate Schema` [#objectui-validate-schema]

Validates the current schema against ObjectUI schema definitions.

**Usage:**

1. Open a schema file
2. Run command
3. View validation errors in Problems panel

**Keyboard Shortcut:** `Ctrl+Alt+V` (Windows/Linux) or `Cmd+Alt+V` (Mac)

### `ObjectUI: Export to React` [#objectui-export-to-react]

Converts the schema to a React component.

**Usage:**

1. Open a schema file
2. Run command
3. React component code is copied to clipboard

**Output Example:**

```typescript
import { SchemaRenderer } from '@object-ui/react'

const schema = {
  "type": "div",
  "className": "p-4",
  "children": [
    { "type": "heading", "level": 1, "children": "Hello World" }
  ]
}

export default function MyComponent() {
  return <SchemaRenderer schema={schema} />
}
```

### `ObjectUI: Format Schema` [#objectui-format-schema]

Formats the schema JSON with consistent indentation and ordering.

**Usage:**

1. Open a schema file
2. Run command
3. Schema is auto-formatted

**Keyboard Shortcut:** `Ctrl+Alt+F` (Windows/Linux) or `Cmd+Alt+F` (Mac)

### `ObjectUI: Create New Schema` [#objectui-create-new-schema]

Creates a new schema file from a template.

**Usage:**

1. Run command
2. Select template (Dashboard, Form, Grid, etc.)
3. New file is created with template content

## Language Support [#language-support]

### File Associations [#file-associations]

The extension recognizes these file patterns:

* `*.objectui.json` - ObjectUI schema files
* `schema.json` - Schema files in specific directories
* Any `.json` file with `"type": "app"` or component types

### Syntax Highlighting [#syntax-highlighting]

Enhanced JSON highlighting for ObjectUI-specific properties:

* **Component Types** - Highlighted in blue
* **Actions** - Highlighted in green
* **Data Sources** - Highlighted in purple
* **Expressions** - Highlighted in orange

## IntelliSense [#intellisense]

### Auto-completion [#auto-completion]

Type-ahead suggestions for:

* Component types (`div`, `button`, `form`, `data-table`, etc.)
* Schema properties (`className`, `dataSource`, `children`, etc.)
* Action types (`navigate`, `submit`, `ajax`, etc.)
* Data source types (`api`, `objectstack`, `value`, etc.)

**Example:**

Type `"type": "` and get suggestions:

* `button`
* `card`
* `data-table`
* `form`
* `grid`
* And 100+ more...

### Hover Information [#hover-information]

Hover over properties to see:

* Property description
* Expected type
* Example values
* Link to documentation

### Validation [#validation]

Real-time validation with error messages:

```json
{
  "type": "button",
  "invalidProp": true  // ❌ Error: Unknown property
}
```

## Snippets [#snippets]

Type these prefixes and press Tab to insert templates:

### `objectui-button` [#objectui-button]

```json
{
  "type": "button",
  "variant": "default",
  "children": "Click me"
}
```

### `objectui-form` [#objectui-form]

```json
{
  "type": "form",
  "fields": [
    {
      "name": "fieldName",
      "type": "text",
      "label": "Label",
      "required": true
    }
  ],
  "onSubmit": {
    "type": "ajax",
    "url": "/api/endpoint",
    "method": "POST"
  }
}
```

### `objectui-grid` [#objectui-grid]

```json
{
  "type": "data-table",
  "dataSource": {
    "type": "api",
    "url": "/api/data"
  },
  "columns": [
    {
      "key": "id",
      "title": "ID"
    }
  ]
}
```

### `objectui-app` [#objectui-app]

```json
{
  "type": "app",
  "title": "My App",
  "pages": [
    {
      "path": "/",
      "title": "Home",
      "component": {
        "type": "div",
        "children": []
      }
    }
  ]
}
```

### `objectui-chart` [#objectui-chart]

```json
{
  "type": "bar-chart",
  "data": [
    { "name": "A", "value": 100 }
  ],
  "dataKey": "value",
  "xAxisKey": "name",
  "height": 300
}
```

## Configuration [#configuration]

Configure the extension via Settings (Ctrl+, / Cmd+,):

### `objectui.preview.port` [#objectuipreviewport]

Port for preview server (default: `3000`)

```json
{
  "objectui.preview.port": 3000
}
```

### `objectui.preview.autoRefresh` [#objectuipreviewautorefresh]

Auto-refresh preview on save (default: `true`)

```json
{
  "objectui.preview.autoRefresh": true
}
```

### `objectui.validation.enabled` [#objectuivalidationenabled]

Enable real-time validation (default: `true`)

```json
{
  "objectui.validation.enabled": true
}
```

### `objectui.validation.severity` [#objectuivalidationseverity]

Validation severity level (default: `error`)

Options: `error`, `warning`, `info`

```json
{
  "objectui.validation.severity": "warning"
}
```

### `objectui.completion.enabled` [#objectuicompletionenabled]

Enable auto-completion (default: `true`)

```json
{
  "objectui.completion.enabled": true
}
```

### `objectui.snippets.enabled` [#objectuisnippetsenabled]

Enable code snippets (default: `true`)

```json
{
  "objectui.snippets.enabled": true
}
```

## Workspace Settings [#workspace-settings]

Create `.vscode/settings.json` in your project:

```json
{
  "objectui.preview.port": 3000,
  "objectui.preview.autoRefresh": true,
  "objectui.validation.enabled": true,
  "objectui.completion.enabled": true,
  "files.associations": {
    "*.schema.json": "objectui-json",
    "ui.json": "objectui-json"
  }
}
```

## Keyboard Shortcuts [#keyboard-shortcuts]

Default keyboard shortcuts:

| Command         | Windows/Linux | Mac         |
| --------------- | ------------- | ----------- |
| Preview Schema  | `Ctrl+Alt+P`  | `Cmd+Alt+P` |
| Validate Schema | `Ctrl+Alt+V`  | `Cmd+Alt+V` |
| Format Schema   | `Ctrl+Alt+F`  | `Cmd+Alt+F` |
| Export to React | `Ctrl+Alt+E`  | `Cmd+Alt+E` |

### Custom Shortcuts [#custom-shortcuts]

Customize via Keyboard Shortcuts editor (Ctrl+K Ctrl+S):

```json
{
  "key": "ctrl+shift+p",
  "command": "objectui.preview",
  "when": "editorLangId == json"
}
```

## Context Menus [#context-menus]

Right-click on a schema file to access:

### Editor Context Menu [#editor-context-menu]

* **Preview Schema** - Open live preview
* **Validate Schema** - Run validation
* **Export to React** - Convert to React component
* **Format Schema** - Auto-format

### Explorer Context Menu [#explorer-context-menu]

* **Preview Schema** - Preview selected file
* **Create Schema** - Create new schema in folder

## Preview Features [#preview-features]

The preview panel includes:

* **Live Rendering** - See changes immediately
* **Interactive UI** - Test interactions
* **Device Toggle** - Mobile/tablet/desktop views
* **Dark Mode Toggle** - Test light/dark themes
* **Refresh Button** - Manual refresh
* **Console** - View errors and logs

## Development Workflow [#development-workflow]

### Typical Workflow [#typical-workflow]

1. **Create Schema** - Use snippet or command
2. **Edit Schema** - IntelliSense helps with completion
3. **Preview** - Open live preview (Ctrl+Alt+P)
4. **Validate** - Check for errors (Ctrl+Alt+V)
5. **Test** - Interact with preview
6. **Export** - Convert to React (Ctrl+Alt+E)

### Tips [#tips]

* **Split Editor** - Keep schema and preview side-by-side
* **Auto Save** - Enable auto-save for instant preview updates
* **Multi-root Workspace** - Work on multiple schema projects
* **Git Integration** - Track schema changes

## Package Information [#package-information]

**Extension ID:** `objectui.object-ui`\
&#x2A;*Version:** 0.3.1\
&#x2A;*License:** MIT

## Extension Dependencies [#extension-dependencies]

The extension bundles:

* **JSON Language Server** - For validation and IntelliSense
* **Schema Definitions** - ObjectUI type definitions
* **Preview Server** - Built-in Vite server

## Troubleshooting [#troubleshooting]

### Preview Not Working [#preview-not-working]

1. Check preview port is available:
   ```bash
   # Change port in settings
   "objectui.preview.port": 5174
   ```

2. Check firewall settings

3. Reload window (Ctrl+R)

### Validation Not Working [#validation-not-working]

1. Check file is recognized as ObjectUI schema
2. Verify `objectui.validation.enabled` is `true`
3. Reload window

### IntelliSense Not Showing [#intellisense-not-showing]

1. Verify `objectui.completion.enabled` is `true`
2. Check file language mode is JSON
3. Reload window

### Extension Not Loading [#extension-not-loading]

1. Check extension is enabled
2. Check for extension errors in Output panel
3. Reinstall extension

## Updates [#updates]

The extension auto-updates via VS Code's extension manager.

### Manual Update [#manual-update]

```bash
code --install-extension objectui.object-ui --force
```

### Check Version [#check-version]

1. Go to Extensions
2. Find ObjectUI extension
3. Check version number

## Contributing [#contributing]

The extension is open source. Contribute on GitHub:

* **Repository:** [objectstack-ai/objectui](https://github.com/objectstack-ai/objectui)
* **Issues:** [Report bugs or request features](https://github.com/objectstack-ai/objectui/issues)
* **Pull Requests:** [Contribute code](https://github.com/objectstack-ai/objectui/pulls)

## Next Steps [#next-steps]

* **[Schema Overview](/docs/guide/schema-overview)** - Learn the schema format
* **[CLI](/docs/utilities/cli)** - Use CLI for development
* **[Plugins](/docs/plugins)** - Explore available plugins
* **[Examples](https://github.com/objectstack-ai/objectui/tree/main/examples)** - See example schemas

## Need Help? [#need-help]

* [GitHub Issues](https://github.com/objectstack-ai/objectui/issues)
* [Documentation](https://www.objectui.org)
* [VS Code Extension Documentation](https://code.visualstudio.com/docs/editor/extension-marketplace)


# Plugin Gallery



# Plugin Gallery [#plugin-gallery]

ObjectUI plugins are lazy-loaded component packages that extend the framework with additional functionality. They load on-demand, keeping your main application bundle small while providing rich features.

## Quick Navigation [#quick-navigation]

Browse available plugins:

### Data Visualization & Dashboards [#data-visualization--dashboards]

* **[Charts Plugin](/docs/plugins/plugin-charts)** - Bar, Line, Area, and Pie charts
* **[Dashboard Plugin](/docs/plugins/plugin-dashboard)** - Dashboard layouts with metric cards and widgets
* **[Timeline Plugin](/docs/plugins/plugin-timeline)** - Vertical, horizontal, and Gantt-style timelines
* **[Gantt Plugin](/docs/plugins/plugin-gantt)** - Project task visualization with dependencies (ObjectQL)
* **[Calendar View Plugin](/docs/plugins/plugin-calendar-view)** - Full calendar with month/week/day views
* **[Calendar Plugin](/docs/plugins/plugin-calendar)** - Calendar for ObjectQL data sources
* **[Map Plugin](/docs/plugins/plugin-map)** - Location visualization with markers (ObjectQL)

### Data Management [#data-management]

* **[Grid Plugin](/docs/plugins/plugin-grid)** - Advanced data grid with sorting, filtering, and pagination
* **[Form Plugin](/docs/plugins/plugin-form)** - Advanced form builder with validation
* **[View Plugin](/docs/plugins/plugin-view)** - ObjectQL-integrated views (grid, form, detail)

### Content & Editing [#content--editing]

* **[Editor Plugin](/docs/plugins/plugin-editor)** - Code editor powered by Monaco Editor
* **[Markdown Plugin](/docs/plugins/plugin-markdown)** - Markdown renderer with GFM support
* **[Chatbot Plugin](/docs/plugins/plugin-chatbot)** - Chat interface component

### Workflows & Tasks [#workflows--tasks]

* **[Kanban Plugin](/docs/plugins/plugin-kanban)** - Kanban board with drag-and-drop

## Official Plugins [#official-plugins]

### Charts Plugin [#charts-plugin]

**[@object-ui/plugin-charts](/docs/plugins/plugin-charts)** - Data visualization components powered by Recharts.

* Bar, line, area, and pie charts
* Responsive design
* Customizable colors and themes
* Lazy-loaded (\~540 KB)

```bash
npm install @object-ui/plugin-charts
```

[Read full documentation →](/docs/plugins/plugin-charts)

***

### Editor Plugin [#editor-plugin]

**[@object-ui/plugin-editor](/docs/plugins/plugin-editor)** - Code editor component powered by Monaco Editor (VS Code's editor).

* Syntax highlighting for 100+ languages
* IntelliSense and code completion
* Multiple themes (VS Dark, Light, etc.)
* Lazy-loaded (\~20 KB)

```bash
npm install @object-ui/plugin-editor
```

[Read full documentation →](/docs/plugins/plugin-editor)

***

### Kanban Plugin [#kanban-plugin]

**[@object-ui/plugin-kanban](/docs/plugins/plugin-kanban)** - Kanban board component with drag-and-drop powered by @dnd-kit.

* Drag and drop cards between columns
* Column limits (WIP limits)
* Card badges for status/priority
* Lazy-loaded (\~100-150 KB)

```bash
npm install @object-ui/plugin-kanban
```

[Read full documentation →](/docs/plugins/plugin-kanban)

***

### Markdown Plugin [#markdown-plugin]

**[@object-ui/plugin-markdown](/docs/plugins/plugin-markdown)** - Markdown renderer with GitHub Flavored Markdown support.

* GitHub Flavored Markdown
* XSS protection
* Code syntax highlighting
* Lazy-loaded (\~100-200 KB)

```bash
npm install @object-ui/plugin-markdown
```

[Read full documentation →](/docs/plugins/plugin-markdown)

***

### Timeline Plugin [#timeline-plugin]

**[@object-ui/plugin-timeline](/docs/plugins/plugin-timeline)** - Timeline component with multiple layout variants.

* Vertical, horizontal, and Gantt-style layouts
* Customizable markers with icons
* Date formatting options
* Time scales (day/week/month)

```bash
npm install @object-ui/plugin-timeline
```

[Read full documentation →](/docs/plugins/plugin-timeline)

***

### Chatbot Plugin [#chatbot-plugin]

**[@object-ui/plugin-chatbot](/docs/plugins/plugin-chatbot)** - Chat interface component with message history.

* User and assistant message roles
* System messages
* Timestamps and avatars
* Auto-scroll and typing indicators

```bash
npm install @object-ui/plugin-chatbot
```

[Read full documentation →](/docs/plugins/plugin-chatbot)

***

### Calendar View Plugin [#calendar-view-plugin]

**[@object-ui/plugin-calendar-view](/docs/plugins/plugin-calendar-view)** - Full-featured calendar with month, week, and day views.

* Month, week, and day calendar views
* Event display with colors
* Navigation controls
* All-day and timed events

```bash
npm install @object-ui/plugin-calendar-view
```

[Read full documentation →](/docs/plugins/plugin-calendar-view)

***

### Calendar Plugin (ObjectQL) [#calendar-plugin-objectql]

**[@object-ui/plugin-calendar](/docs/plugins/plugin-calendar)** - Calendar visualization for ObjectQL data sources.

* ObjectQL integration
* Automatic field mapping
* Database-driven events
* Works with object/api/value providers

```bash
npm install @object-ui/plugin-calendar
```

[Read full documentation →](/docs/plugins/plugin-calendar)

***

### Gantt Plugin (ObjectQL) [#gantt-plugin-objectql]

**[@object-ui/plugin-gantt](/docs/plugins/plugin-gantt)** - Gantt chart for ObjectQL data sources.

* Project task visualization
* Progress tracking (0-100%)
* Task dependencies
* ObjectQL integration

```bash
npm install @object-ui/plugin-gantt
```

[Read full documentation →](/docs/plugins/plugin-gantt)

***

### Map Plugin (ObjectQL) [#map-plugin-objectql]

**[@object-ui/plugin-map](/docs/plugins/plugin-map)** - Map visualization for ObjectQL data sources.

* Location-based markers
* Latitude/longitude support
* Marker customization
* ObjectQL integration

```bash
npm install @object-ui/plugin-map
```

[Read full documentation →](/docs/plugins/plugin-map)

***

### Dashboard Plugin [#dashboard-plugin]

**[@object-ui/plugin-dashboard](/docs/plugins/plugin-dashboard)** - Dashboard layouts with metric cards and widgets.

* Dashboard grid layouts
* Metric/KPI cards with trends
* Widget system
* Responsive design

```bash
npm install @object-ui/plugin-dashboard
```

[Read full documentation →](/docs/plugins/plugin-dashboard)

***

### Grid Plugin [#grid-plugin]

**[@object-ui/plugin-grid](/docs/plugins/plugin-grid)** - Advanced data grid with sorting, filtering, and pagination.

* Column sorting and filtering
* Pagination controls
* Row selection
* Custom cell renderers

```bash
npm install @object-ui/plugin-grid
```

[Read full documentation →](/docs/plugins/plugin-grid)

***

### Form Plugin [#form-plugin]

**[@object-ui/plugin-form](/docs/plugins/plugin-form)** - Advanced form builder with validation.

* Multi-step forms
* Field validation
* Custom field types
* Form state management

```bash
npm install @object-ui/plugin-form
```

[Read full documentation →](/docs/plugins/plugin-form)

***

### View Plugin [#view-plugin]

**[@object-ui/plugin-view](/docs/plugins/plugin-view)** - ObjectQL-integrated views for automatic CRUD operations.

* Auto-generated forms and grids
* CRUD operations
* ObjectQL integration
* Field mapping

```bash
npm install @object-ui/plugin-view
```

[Read full documentation →](/docs/plugins/plugin-view)

***

## How Plugins Work [#how-plugins-work]

### Lazy Loading Architecture [#lazy-loading-architecture]

Plugins use React's `lazy()` and `Suspense` to load heavy dependencies on-demand:

```typescript
// The plugin structure
import React, { Suspense } from 'react'
import { Skeleton } from '@object-ui/components'

// Lazy load the heavy implementation
const LazyEditor = React.lazy(() => import('./MonacoImpl'))

export const CodeEditorRenderer = (props) => (
  <Suspense fallback={<Skeleton className="w-full h-[400px]" />}>
    <LazyEditor {...props} />
  </Suspense>
)
```

**Benefits:**

* **Smaller initial bundle**: Main app loads faster
* **Progressive loading**: Components load when needed
* **Better UX**: Loading skeletons while chunks download
* **Automatic code splitting**: Vite handles chunking

### Bundle Impact [#bundle-impact]

| Plugin               | Initial Load | Lazy Load    | Description            |
| -------------------- | ------------ | ------------ | ---------------------- |
| plugin-editor        | \~0.2 KB     | \~20 KB      | Monaco editor          |
| plugin-charts        | \~0.2 KB     | \~540 KB     | Recharts visualization |
| plugin-kanban        | \~0.2 KB     | \~100-150 KB | Drag-and-drop board    |
| plugin-markdown      | \~0.2 KB     | \~100-200 KB | Markdown rendering     |
| plugin-timeline      | \~0.2 KB     | \~10 KB      | Timeline layouts       |
| plugin-chatbot       | \~0.2 KB     | \~30 KB      | Chat interface         |
| plugin-calendar-view | \~0.2 KB     | \~40 KB      | Full calendar          |
| plugin-calendar      | \~0.2 KB     | \~50 KB      | ObjectQL calendar      |
| plugin-gantt         | \~0.2 KB     | \~60 KB      | ObjectQL Gantt         |
| plugin-map           | \~0.2 KB     | \~20 KB      | ObjectQL map           |

Without lazy loading, all this code would be in your main bundle!

### Auto-Registration [#auto-registration]

Plugins automatically register their components when imported:

```typescript
// In the plugin's index.tsx
import { ComponentRegistry } from '@object-ui/core'

ComponentRegistry.register('code-editor', CodeEditorRenderer)
```

You just need to import the plugin once:

```typescript
// In your App.tsx or main.tsx
import '@object-ui/plugin-editor'
import '@object-ui/plugin-charts'
import '@object-ui/plugin-kanban'
import '@object-ui/plugin-markdown'
```

Now all plugin components are available in your schemas!

## Usage Pattern [#usage-pattern]

All ObjectUI plugins follow the same usage pattern:

```json
{
  "type": "plugin-component-name",
  "className": "tailwind-classes",
  "props": {
    // Plugin-specific properties
  }
}
```

### Example: Code Editor [#example-code-editor]

```json
{
  "type": "code-editor",
  "language": "typescript",
  "value": "const greeting = 'Hello World';",
  "className": "h-96",
  "theme": "vs-dark"
}
```

### Example: Bar Chart [#example-bar-chart]

```json
{
  "type": "bar-chart",
  "data": [
    { "name": "Jan", "value": 400 },
    { "name": "Feb", "value": 300 },
    { "name": "Mar", "value": 600 }
  ],
  "dataKey": "value",
  "xAxisKey": "name",
  "height": 300,
  "color": "#8884d8"
}
```

## Features [#features]

All ObjectUI plugins share these characteristics:

* ✅ **Lazy Loaded** - Load on-demand, not upfront
* ✅ **Auto-Register** - Import once, use everywhere
* ✅ **Type-Safe** - Full TypeScript support
* ✅ **Schema-Driven** - Define with JSON, not code
* ✅ **Tailwind CSS** - Use utility classes directly
* ✅ **Loading States** - Built-in skeletons while loading
* ✅ **Small Footprint** - Minimal initial bundle impact

## Next Steps [#next-steps]

* **[Plugin Guide](/docs/guide/plugins)** - Learn how plugins work in detail
* **[Quick Start Guide](/docs/guide/quick-start)** - Build your first ObjectUI app
* **[Component Gallery](/docs/components)** - Explore core components
* **[Schema Rendering](/docs/guide/schema-rendering)** - Learn how the engine works

## Need Help? [#need-help]

Can't find what you're looking for? Check out:

* [Architecture](/docs/guide/architecture) - Core concepts and package boundaries
* [API Reference](/docs/api) - Schema documentation and protocol specs
* [GitHub](https://github.com/objectstack-ai/objectui) - Report issues or contribute


# Plugin AI



# @object-ui/plugin-ai [#object-uiplugin-ai]

AI-driven UI plugin for Object UI — schema generation, conversational assistants and Vercel AI SDK integration

## Installation [#installation]

```bash
pnpm add @object-ui/plugin-ai
```

## Status [#status]

This plugin is part of the v3.3.0 release. For full API reference and usage
examples, see the package README:

* 📦 [`@object-ui/plugin-ai` on npm](https://www.npmjs.com/package/@object-ui/plugin-ai)
* 📝 [Package README](https://github.com/objectstack-ai/objectui/tree/main/packages/plugin-ai)
* 🐛 [Report an issue](https://github.com/objectstack-ai/objectui/issues)

> **Note:** A rich interactive documentation page for this plugin is coming soon.
> In the meantime, refer to the package README for schema, props and examples.


# Plugin Calendar View



<Callout type="info" title="Merged into Plugin Calendar">
  The `@object-ui/plugin-calendar-view` package has been merged into `@object-ui/plugin-calendar`.

  Please use `@object-ui/plugin-calendar` instead, which now includes both the `CalendarView` component and the `ObjectCalendar` component.

  See the [Plugin Calendar](/docs/plugins/plugin-calendar) documentation for details.
</Callout>

## Migration Guide [#migration-guide]

### Before (plugin-calendar-view) [#before-plugin-calendar-view]

```bash
npm install @object-ui/plugin-calendar-view
```

```tsx
import '@object-ui/plugin-calendar-view'

// Or direct import
import { CalendarView } from '@object-ui/plugin-calendar-view'
```

### After (plugin-calendar) [#after-plugin-calendar]

```bash
npm install @object-ui/plugin-calendar
```

```tsx
import '@object-ui/plugin-calendar'

// Or direct import
import { CalendarView } from '@object-ui/plugin-calendar'
```

## What Changed? [#what-changed]

* The `CalendarView` component is now exported from `@object-ui/plugin-calendar`
* The `calendar-view` schema type is still registered and works the same way
* All functionality remains the same - just the package name changed

For full documentation, see [Plugin Calendar](/docs/plugins/plugin-calendar).


# Plugin Calendar





Calendar view components for ObjectUI - includes both ObjectQL-integrated and standalone calendar components.

## Installation [#installation]

```bash
npm install @object-ui/plugin-calendar
```

<PluginLoader plugins="['calendar']">
  ## Overview [#overview]

  The `@object-ui/plugin-calendar` plugin provides two calendar components:

  1. **ObjectCalendar** (`object-calendar`): For ObjectQL data sources - displays database records as calendar events
  2. **CalendarView** (`calendar-view`): Standalone calendar component for displaying pre-loaded event data

  Both components support month, week, and day views with full event management capabilities.

  ## Drag-and-Drop Rescheduling [#drag-and-drop-rescheduling]

  ### Month view [#month-view]

  * **Move an event** — grab any cell of the event pill and drop it on another day. The grabbed-day → drop-day distance is the day delta applied to both `startDateField` and `endDateField`, so dragging a multi-day span from any of its days behaves intuitively.
  * **Resize an event** — grab the small right-edge handle on the last day of a multi-day pill and drop it on a different day to extend or shrink the end date. The start date is preserved; drops earlier than the start are ignored.

  ### Week / Day view (time grid) [#week--day-view-time-grid]

  Week and day views render a classic Google Calendar-style vertical time
  grid. All gestures use pointer events and snap to `slotMinutes` (default
  30\):

  * **Move an event** — drag the event body vertically to change its start
    time (and end, by the same delta). In week view, drag horizontally to
    also change the day.
  * **Resize start** — drag the top edge of an event to adjust only the
    start time. Refuses to cross the existing end.
  * **Resize end** — drag the bottom edge to adjust only the end time.
    Refuses to cross the existing start.
  * **Drag-to-create** — click-drag on an empty area of the time grid to
    open the quick-create dialog with start/end pre-filled to the dragged
    time range.

  Pass `slotMinutes={15}` to change the snap granularity, or
  `onTimeRangeSelect={(start, end) => …}` to override the drag-to-create
  default.

  When `ObjectCalendar` is bound to an object (i.e. it has `objectName` and a `dataSource`), the new dates are persisted automatically via `dataSource.update()` — local state is updated optimistically and rolled back on failure. To intercept (e.g. for a confirm dialog) pass an `onEventDrop` prop; supplying your own handler disables the default persistence.

  ```jsx
  <ObjectCalendar
    schema={{ type: 'object-calendar', objectName: 'campaign' }}
    // optional — omit to get default backend persistence
    onEventDrop={(record, newStart, newEnd) => {
      if (confirm(`Move ${record.name}?`)) save({ id: record.id, start_date: newStart, end_date: newEnd });
    }}
  />
  ```

  ## Click-to-Create [#click-to-create]

  Clicking the empty area of any day cell (month view) or click-dragging
  in the week/day time grid opens a quick-create dialog pre-filled with
  the selected date/range. Type a title and press <kbd>Enter</kbd> (or
  click **Create**) to persist a new record via
  `dataSource.create(objectName, payload)`. The new record is inserted
  optimistically into the calendar so it appears immediately.

  The payload includes the configured `titleField`, `startDateField`,
  optional `endDateField` (set to the clicked day), plus auto-defaults
  for any other required fields not provided by the user (first picklist
  option for `select`/`status`, `false` for booleans, `0` for numerics,
  or the field's declared `defaultValue`). This ensures the create
  succeeds against `NOT NULL` columns without forcing the user through
  the full form.

  To override (e.g. open your own multi-field create form), pass
  `onDateClick`:

  ```jsx
  <ObjectCalendar
    schema={{ type: 'object-calendar', objectName: 'campaign' }}
    onDateClick={(day) => navigate(`/campaign/new?start=${day.toISOString()}`)}
  />
  ```

  ## CalendarView Component [#calendarview-component]

  Full-featured standalone calendar with month, week, and day views for displaying events and scheduling.

  ### Interactive Examples [#interactive-examples]

  #### Month View [#month-view-1]

  <SchemaExample id="plugin-calendar/month-view-calendar" />

  #### Week View [#week-view]

  <SchemaExample id="plugin-calendar/week-view-calendar" />

  ### CalendarView Usage [#calendarview-usage]

  ```tsx
  import '@object-ui/plugin-calendar'

  const schema = {
    type: 'calendar-view',
    view: 'month',
    data: [
      {
        id: 1,
        title: 'Team Meeting',
        start: '2024-01-15T10:00:00',
        end: '2024-01-15T11:00:00',
        color: '#3b82f6'
      }
    ]
  }
  ```

  ### CalendarView Schema API [#calendarview-schema-api]

  ```plaintext
  {
    type: 'calendar-view',
    view?: 'month' | 'week' | 'day',
    data?: Array<CalendarEventData>,
    titleField?: string,
    startDateField?: string,
    endDateField?: string,
    allDayField?: string,
    colorField?: string,
    colorMapping?: Record<string, string>,
    currentDate?: string,
    allowCreate?: boolean,
    onEventClick?: (event: any) => void,
    onDateClick?: (date: Date) => void,
    onViewChange?: (view: string) => void,
    onNavigate?: (date: Date) => void,
    className?: string
  }
  ```

  ## ObjectCalendar Component [#objectcalendar-component]

  Calendar component designed for use with ObjectQL data sources.

  ## ObjectCalendar Component [#objectcalendar-component-1]

  Calendar component designed for use with ObjectQL data sources.

  ### Features [#features]

  * **ObjectQL Integration**: Works seamlessly with object/api/value data providers
  * **Automatic Field Mapping**: Maps database fields to calendar events
  * **Multiple View Modes**: Month, week, and day calendar views
  * **Date Filtering**: Automatically filters records by date range
  * **Event Interaction**: Click handling for events and dates
  * **Color Coding**: Support for event color customization

  ### ObjectCalendar Usage [#objectcalendar-usage]

  #### Basic Usage with ObjectQL [#basic-usage-with-objectql]

  ```tsx
  import '@object-ui/plugin-calendar'

  const schema = {
    type: 'object-calendar',
    objectName: 'events',  // Your ObjectQL object
    calendar: {
      startDateField: 'startDate',
      endDateField: 'endDate',
      titleField: 'title',
      colorField: 'category'
    }
  }
  ```

  ### With Static Data [#with-static-data]

  ```tsx
  const schema = {
    type: 'object-calendar',
    staticData: [
      {
        id: 1,
        title: 'Team Meeting',
        startDate: '2024-01-15T10:00:00',
        endDate: '2024-01-15T11:00:00',
        category: 'meeting'
      },
      {
        id: 2,
        title: 'Project Deadline',
        startDate: '2024-01-20',
        category: 'deadline'
      }
    ],
    calendar: {
      startDateField: 'startDate',
      endDateField: 'endDate',
      titleField: 'title',
      colorField: 'category'
    }
  }
  ```

  ## Schema API [#schema-api]

  ```plaintext
  {
    type: 'object-calendar',
    objectName?: string,              // ObjectQL object name
    staticData?: Array<any>,          // Static data array
    data?: ViewData,                  // Advanced data configuration
    calendar?: CalendarConfig,        // Calendar-specific configuration
    onEventClick?: (record: any) => void,
    onDateClick?: (date: Date) => void,
    className?: string
  }
  ```

  ### CalendarConfig [#calendarconfig]

  ```plaintext
  {
    startDateField: string,     // Field containing event start date
    endDateField?: string,      // Field containing event end date
    titleField: string,         // Field to use as event title
    colorField?: string,        // Field for color coding
    descriptionField?: string   // Field for event description
  }
  ```

  ## Configuration [#configuration]

  ### Field Mapping [#field-mapping]

  Map your database fields to calendar properties:

  ```tsx
  {
    type: 'object-calendar',
    objectName: 'tasks',
    calendar: {
      titleField: 'taskName',      // Database field for title
      startDateField: 'dueDate',   // Database field for start
      endDateField: 'completedAt', // Database field for end
      colorField: 'priority'       // Database field for color
    }
  }
  ```

  ### Data Providers [#data-providers]

  #### Object Provider (Database) [#object-provider-database]

  ```tsx
  {
    type: 'object-calendar',
    objectName: 'appointments',
    calendar: {
      startDateField: 'scheduledAt',
      titleField: 'subject'
    }
  }
  ```

  #### Value Provider (Static) [#value-provider-static]

  ```tsx
  {
    type: 'object-calendar',
    staticData: [
      { id: 1, title: 'Event 1', date: '2024-01-15' },
      { id: 2, title: 'Event 2', date: '2024-01-20' }
    ],
    calendar: {
      startDateField: 'date',
      titleField: 'title'
    }
  }
  ```

  #### API Provider [#api-provider]

  ```tsx
  {
    type: 'object-calendar',
    data: {
      provider: 'api',
      endpoint: '/api/events',
      method: 'GET'
    },
    calendar: {
      startDateField: 'startTime',
      endDateField: 'endTime',
      titleField: 'eventName'
    }
  }
  ```

  ## Comparison: CalendarView vs ObjectCalendar [#comparison-calendarview-vs-objectcalendar]

  | Feature           | CalendarView          | ObjectCalendar            |
  | ----------------- | --------------------- | ------------------------- |
  | **Schema Type**   | `calendar-view`       | `object-calendar`         |
  | **Data Source**   | Static arrays         | ObjectQL (database)       |
  | **Use Case**      | Pre-loaded event data | Dynamic data from backend |
  | **Field Mapping** | Standard field names  | Configurable field names  |
  | **Data Loading**  | Manual via props      | Automatic via ObjectQL    |
  | **Best For**      | Static schedules      | Database-driven apps      |

  **When to use CalendarView**:

  * You have static or pre-loaded event data
  * You're not using ObjectQL
  * You need a simple, standalone calendar

  **When to use ObjectCalendar**:

  * You're using ObjectQL for data management
  * Events come from a database or API
  * You need automatic data fetching and filtering

  ## Event Handling [#event-handling]

  ### Event Click [#event-click]

  ```tsx
  {
    type: 'object-calendar',
    objectName: 'events',
    calendar: {
      startDateField: 'start',
      titleField: 'title'
    },
    onEventClick: (record) => {
      console.log('Event clicked:', record);
      // Open event details
      // Navigate to event page
    }
  }
  ```

  ### Date Click [#date-click]

  ```tsx
  {
    type: 'object-calendar',
    objectName: 'events',
    calendar: {
      startDateField: 'start',
      titleField: 'title'
    },
    onDateClick: (date) => {
      console.log('Date clicked:', date);
      // Create new event on this date
    }
  }
  ```

  ## Examples [#examples]

  ### Appointment Scheduler [#appointment-scheduler]

  ```tsx
  const appointmentCalendar = {
    type: 'object-calendar',
    objectName: 'appointments',
    calendar: {
      startDateField: 'appointmentDate',
      endDateField: 'appointmentEnd',
      titleField: 'patientName',
      descriptionField: 'notes',
      colorField: 'appointmentType'
    },
    onEventClick: (appointment) => {
      // Show appointment details
    }
  }
  ```

  ### Event Management [#event-management]

  ```tsx
  const eventCalendar = {
    type: 'object-calendar',
    objectName: 'events',
    calendar: {
      startDateField: 'eventStart',
      endDateField: 'eventEnd',
      titleField: 'eventTitle',
      colorField: 'eventCategory'
    },
    onEventClick: (event) => {
      // Navigate to event details
    },
    onDateClick: (date) => {
      // Create new event
    }
  }
  ```

  ### Task Deadlines [#task-deadlines]

  ```tsx
  const taskCalendar = {
    type: 'object-calendar',
    objectName: 'tasks',
    calendar: {
      startDateField: 'dueDate',
      titleField: 'taskTitle',
      colorField: 'priority'
    },
    onEventClick: (task) => {
      // Open task details
    }
  }
  ```

  ## Direct Component Usage [#direct-component-usage]

  You can also import and use the components directly in React:

  ```tsx
  import { CalendarView, ObjectCalendar } from '@object-ui/plugin-calendar';

  // CalendarView - Standalone calendar
  function MyCalendar() {
    const events = [
      {
        id: 1,
        title: 'Meeting',
        start: new Date('2024-01-15T10:00:00'),
        end: new Date('2024-01-15T11:00:00'),
        color: '#3b82f6'
      }
    ];

    return (
      <CalendarView
        events={events}
        view="month"
        onEventClick={(event) => console.log(event)}
      />
    );
  }

  // ObjectCalendar - ObjectQL-integrated
  function MyObjectCalendar({ dataSource }) {
    const schema = {
      objectName: 'events',
      calendar: {
        startDateField: 'startDate',
        titleField: 'title'
      }
    };

    return (
      <ObjectCalendar
        schema={schema}
        dataSource={dataSource}
        onEventClick={(record) => console.log(record)}
      />
    );
  }
  ```

  ## TypeScript Support [#typescript-support]

  ```plaintext
  import type { 
    CalendarViewSchema, 
    CalendarEvent,
    ObjectGridSchema,
    CalendarConfig 
  } from '@object-ui/types'

  // CalendarView types
  const events: CalendarEvent[] = [
    {
      id: 1,
      title: 'Meeting',
      start: new Date('2024-01-15T10:00:00'),
      end: new Date('2024-01-15T11:00:00'),
      color: '#3b82f6'
    }
  ]

  const calendarViewSchema: CalendarViewSchema = {
    type: 'calendar-view',
    view: 'month',
    data: events
  }

  // ObjectCalendar types
  const calendarConfig: CalendarConfig = {
    startDateField: 'startDate',
    endDateField: 'endDate',
    titleField: 'title',
    colorField: 'category'
  }

  const objectCalendarSchema: ObjectGridSchema = {
    type: 'object-calendar',
    objectName: 'events',
    calendar: calendarConfig
  }
  ```

  ## Migration from @object-ui/plugin-calendar-view [#migration-from-object-uiplugin-calendar-view]

  The `@object-ui/plugin-calendar-view` package has been merged into this package. If you were using it:

  ### Before [#before]

  ```bash
  npm install @object-ui/plugin-calendar-view
  ```

  ```tsx
  import '@object-ui/plugin-calendar-view'
  import { CalendarView } from '@object-ui/plugin-calendar-view'
  ```

  ### After [#after]

  ```bash
  npm install @object-ui/plugin-calendar
  ```

  ```tsx
  import '@object-ui/plugin-calendar'
  import { CalendarView } from '@object-ui/plugin-calendar'
  ```

  All functionality remains the same - just update your imports and package dependencies.

  ## Related Documentation [#related-documentation]

  * [Plugin System Overview](/docs/guide/plugins)
  * [Package README](https://github.com/objectstack-ai/objectui/tree/main/packages/plugin-calendar)
</PluginLoader>


# Plugin Charts





Data visualization components powered by Recharts.

## Installation [#installation]

```bash
npm install @object-ui/plugin-charts
```

<PluginLoader plugins="['charts']">
  ## Interactive Examples [#interactive-examples]

  <SchemaExample id="plugin-charts/simple-bar-chart" />

  <SchemaExample id="plugin-charts/advanced-line-chart" />

  <SchemaExample id="plugin-charts/area-chart" />

  ## Usage [#usage]

  The plugin provides two chart APIs:

  1. **Simple Bar Chart** (`bar-chart`) - Simplified API for basic bar charts
  2. **Advanced Charts** (`chart`) - Full-featured API supporting multiple chart types (bar, line, area) and multiple data series

  ### Basic Usage [#basic-usage]

  ```tsx
  // Import once in your app entry point
  import '@object-ui/plugin-charts'

  // Use in schemas
  const schema = {
    type: 'bar-chart',
    data: [
      { name: 'Jan', value: 400 },
      { name: 'Feb', value: 300 },
      { name: 'Mar', value: 600 }
    ],
    dataKey: 'value',
    xAxisKey: 'name',
    height: 400
  }
  ```

  ## Features [#features]

  * **Bar, line, and area charts**
  * **Responsive design**
  * **Customizable colors and styles**
  * **Lazy-loaded** (\~540 KB loads only when rendered)

  ## Schema API [#schema-api]

  ```plaintext
  {
    type: 'bar-chart',
    data?: Array<Record<string, any>>,  // Chart data
    dataKey?: string,                    // Y-axis data key
    xAxisKey?: string,                   // X-axis label key
    height?: number,                     // Chart height
    color?: string,                      // Bar color
    className?: string                   // Tailwind classes
  }
  ```

  ### Properties [#properties]

  | Property    | Type             | Default     | Description                           |
  | ----------- | ---------------- | ----------- | ------------------------------------- |
  | `data`      | Array of objects | `[]`        | Array of data objects to visualize    |
  | `dataKey`   | string           | `'value'`   | Key in data objects for Y-axis values |
  | `xAxisKey`  | string           | `'name'`    | Key in data objects for X-axis labels |
  | `height`    | number           | `400`       | Chart height in pixels                |
  | `color`     | string           | `'#8884d8'` | Primary color for bars/lines          |
  | `className` | string           | `''`        | Additional Tailwind CSS classes       |

  ## Chart Types [#chart-types]

  The plugin provides two different chart components:

  ### Simple Bar Chart (bar-chart) [#simple-bar-chart-bar-chart]

  For basic single-series bar charts, use the simplified `bar-chart` type:

  ```tsx
  const schema = {
    type: 'bar-chart',
    data: [
      { month: 'Jan', sales: 400 },
      { month: 'Feb', sales: 300 },
      { month: 'Mar', sales: 600 }
    ],
    dataKey: 'sales',
    xAxisKey: 'month',
    color: '#3b82f6',
    height: 300
  }
  ```

  ### Advanced Charts (chart) [#advanced-charts-chart]

  For multi-series charts or line/area charts, use the advanced `chart` type with the `chartType` property:

  ##### Bar Chart [#bar-chart]

  ```tsx
  const schema = {
    type: 'chart',
    chartType: 'bar',
    data: [
      { month: 'Jan', sales: 400, target: 350 },
      { month: 'Feb', sales: 300, target: 400 },
      { month: 'Mar', sales: 600, target: 550 }
    ],
    xAxisKey: 'month',
    series: [
      { dataKey: 'sales' },
      { dataKey: 'target' }
    ],
    config: {
      sales: { label: 'Sales', color: '#3b82f6' },
      target: { label: 'Target', color: '#10b981' }
    }
  }
  ```

  ##### Line Chart [#line-chart]

  ```tsx
  const schema = {
    type: 'chart',
    chartType: 'line',
    data: [
      { date: '2024-01', users: 120 },
      { date: '2024-02', users: 180 },
      { date: '2024-03', users: 250 }
    ],
    xAxisKey: 'date',
    series: [
      { dataKey: 'users' }
    ],
    config: {
      users: { label: 'Users', color: '#8884d8' }
    }
  }
  ```

  ###### Area Chart [#area-chart]

  ```tsx
  const schema = {
    type: 'chart',
    chartType: 'area',
    data: [
      { time: '9:00', value: 20 },
      { time: '10:00', value: 35 },
      { time: '11:00', value: 45 }
    ],
    xAxisKey: 'time',
    series: [
      { dataKey: 'value' }
    ],
    config: {
      value: { label: 'Value', color: '#10b981' }
    }
  }
  ```

  ## Examples [#examples]

  ### Revenue Dashboard [#revenue-dashboard]

  ```tsx
  const revenueChart = {
    type: 'bar-chart',
    data: [
      { quarter: 'Q1 2024', revenue: 45000, target: 50000 },
      { quarter: 'Q2 2024', revenue: 52000, target: 50000 },
      { quarter: 'Q3 2024', revenue: 61000, target: 55000 },
      { quarter: 'Q4 2024', revenue: 58000, target: 60000 }
    ],
    dataKey: 'revenue',
    xAxisKey: 'quarter',
    height: 400,
    color: '#059669',
    className: 'rounded-lg shadow-md'
  }
  ```

  ### User Growth Chart [#user-growth-chart]

  ```tsx
  const growthChart = {
    type: 'chart',
    chartType: 'line',
    data: [
      { month: 'Jan', users: 1200, active: 980 },
      { month: 'Feb', users: 1450, active: 1150 },
      { month: 'Mar', users: 1680, active: 1380 },
      { month: 'Apr', users: 1920, active: 1620 }
    ],
    xAxisKey: 'month',
    series: [
      { dataKey: 'users' },
      { dataKey: 'active' }
    ],
    config: {
      users: { label: 'Total Users', color: '#8884d8' },
      active: { label: 'Active Users', color: '#82ca9d' }
    }
  }
  ```

  ## Bundle Size [#bundle-size]

  The plugin uses lazy loading to optimize bundle size:

  * **Initial load**: \~0.2 KB (entry point)
  * **Lazy chunk**: \~541 KB minified (\~136 KB gzipped)
  * **Loads only when rendered**

  Without lazy loading, this would add 541 KB to your main bundle. With lazy loading, it's loaded only when charts are displayed.

  ## Customization [#customization]

  ### Custom Colors [#custom-colors]

  ```tsx
  const schema = {
    type: 'bar-chart',
    data: salesData,
    color: '#f59e0b', // Amber color
    className: 'bg-white p-4 rounded-lg'
  }
  ```

  ### Responsive Height [#responsive-height]

  ```tsx
  const schema = {
    type: 'chart',
    chartType: 'line',
    data: metricsData,
    xAxisKey: 'date',
    series: [{ dataKey: 'value' }],
    config: {
      value: { label: 'Metrics', color: '#8884d8' }
    },
    className: 'h-64 sm:h-96 lg:h-[500px]'
  }
  ```

  ## TypeScript Support [#typescript-support]

  ```plaintext
  import type { BarChartSchema } from '@object-ui/plugin-charts'

  const chartSchema: BarChartSchema = {
    type: 'bar-chart',
    data: [
      { name: 'Product A', value: 400 },
      { name: 'Product B', value: 300 }
    ],
    dataKey: 'value',
    xAxisKey: 'name',
    height: 400
  }
  ```

  ## Related Documentation [#related-documentation]

  * [Plugin System Overview](/docs/guide/plugins)
  * [Lazy-Loaded Plugins Architecture](../concepts/lazy-loading)
  * [Package README](https://github.com/objectstack-ai/objectui/tree/main/packages/plugin-charts)
</PluginLoader>


# Plugin Chatbot





Chat interface component with message history, typing indicators, and customizable avatars.

> **v5.4+** — the chat surface is now composed from vendored
> [Vercel AI Elements](https://elements.ai-sdk.dev) (MIT). The public
> `chatbot` schema and `ChatbotEnhanced` / `FloatingChatbot` props are
> unchanged. A new optional `suggestions: string[]` field renders chip
> prompts in the empty state.

For advanced compositions, the underlying elements are re-exported:

```tsx
import { AIElements } from '@object-ui/plugin-chatbot';
// AIElements.Conversation, AIElements.Message, AIElements.PromptInput, ...
```

## Installation [#installation]

```bash
npm install @object-ui/plugin-chatbot
```

<PluginLoader plugins="['chatbot']">
  ## Interactive Examples [#interactive-examples]

  ### Basic Chatbot [#basic-chatbot]

  <SchemaExample id="plugin-chatbot/basic-chatbot" />

  ### Chatbot with Timestamps [#chatbot-with-timestamps]

  <SchemaExample id="plugin-chatbot/chatbot-with-timestamps" />

  ### Customer Support Chat [#customer-support-chat]

  <SchemaExample id="plugin-chatbot/customer-support-chat" />

  ## Usage [#usage]

  ### Basic Usage [#basic-usage]

  ```tsx
  // Import once in your app entry point
  import '@object-ui/plugin-chatbot'

  // Use in schemas
  const schema = {
    type: 'chatbot',
    messages: [
      {
        id: '1',
        role: 'assistant',
        content: 'Hello! How can I help you?'
      }
    ],
    placeholder: 'Type your message...',
    autoResponse: true
  }
  ```

  ## Features [#features]

  * **Message History**: Display chat messages with user and assistant roles
  * **System Messages**: Show system notifications in the chat
  * **Timestamps**: Optional timestamp display for each message
  * **Custom Avatars**: Configurable avatar images and fallback text
  * **Auto-scroll**: Automatically scroll to newest messages
  * **Typing Indicator**: Built-in typing indicator component
  * **Auto-response**: Demo mode with automatic responses
  * **Responsive Floating Panel**: Console assistants keep the panel inside safe
    browser gutters and hide the FAB while the chat is open
  * **Conversation States**: Empty streaming messages render as an assistant
    responding indicator, the submit control becomes Stop while streaming, and
    backend errors collapse into a retryable notice with optional details
  * **Lightweight**: Pure React components with minimal dependencies

  ## Schema API [#schema-api]

  ```plaintext
  {
    type: 'chatbot',
    messages?: ChatMessage[],
    placeholder?: string,
    showTimestamp?: boolean,
    disabled?: boolean,
    userAvatarUrl?: string,
    userAvatarFallback?: string,
    assistantAvatarUrl?: string,
    assistantAvatarFallback?: string,
    maxHeight?: string,
    autoResponse?: boolean,
    autoResponseText?: string,
    autoResponseDelay?: number,
    onSend?: (content: string, messages: ChatMessage[]) => void,
    className?: string,
    // AI / service-ai integration fields
    api?: string,
    conversationId?: string,
    systemPrompt?: string,
    model?: string,
    streamingEnabled?: boolean,
    headers?: Record<string, string>,
    body?: Record<string, unknown>,
    maxToolRoundtrips?: number,
    onError?: (error: Error) => void,
  }
  ```

  ### ChatMessage [#chatmessage]

  ```plaintext
  {
    id: string,
    role: 'user' | 'assistant' | 'system' | 'tool',
    content: string,
    timestamp?: string | Date,
    metadata?: any,
    streaming?: boolean,
    toolInvocations?: ChatToolInvocation[],
  }
  ```

  ## Properties [#properties]

  | Property                  | Type                               | Default                  | Description                                                                              |
  | ------------------------- | ---------------------------------- | ------------------------ | ---------------------------------------------------------------------------------------- |
  | `messages`                | array                              | `[]`                     | Initial chat messages                                                                    |
  | `placeholder`             | string                             | `'Type your message...'` | Input field placeholder text                                                             |
  | `showTimestamp`           | boolean                            | `false`                  | Display timestamps for messages                                                          |
  | `disabled`                | boolean                            | `false`                  | Disable chat input                                                                       |
  | `userAvatarUrl`           | string                             | -                        | URL for user avatar image                                                                |
  | `userAvatarFallback`      | string                             | `'You'`                  | Fallback text for user avatar                                                            |
  | `assistantAvatarUrl`      | string                             | -                        | URL for assistant avatar image                                                           |
  | `assistantAvatarFallback` | string                             | `'AI'`                   | Fallback text for assistant avatar                                                       |
  | `maxHeight`               | string                             | `'500px'`                | Maximum chat container height                                                            |
  | `autoResponse`            | boolean                            | `false`                  | Enable auto-response (demo mode, ignored when `api` is set)                              |
  | `autoResponseText`        | string                             | -                        | Text for auto-response                                                                   |
  | `autoResponseDelay`       | number                             | `1000`                   | Delay before auto-response (ms)                                                          |
  | `onSend`                  | function                           | -                        | Callback when message is sent                                                            |
  | `className`               | string                             | `''`                     | Additional Tailwind CSS classes                                                          |
  | `api`                     | string                             | -                        | Backend SSE endpoint (e.g., `/api/v1/ai/chat`). Enables AI streaming mode                |
  | `conversationId`          | string                             | -                        | Multi-turn conversation identifier                                                       |
  | `systemPrompt`            | string                             | -                        | System prompt to configure assistant behavior                                            |
  | `model`                   | string                             | -                        | AI model identifier (e.g., `gpt-4o`)                                                     |
  | `streamingEnabled`        | boolean                            | `true`                   | Enable SSE streaming for AI responses                                                    |
  | `headers`                 | object                             | -                        | Additional headers for API requests                                                      |
  | `body`                    | object                             | -                        | Additional body params for API requests                                                  |
  | `maxToolRoundtrips`       | number                             | `5`                      | Max tool-calling round-trips per message                                                 |
  | `surface`                 | `'card' \| 'plain'`                | `'card'`                 | Controls whether the chat renders as a bordered panel or a frameless full-page workspace |
  | `processVisibility`       | `'hidden' \| 'summary' \| 'debug'` | `'summary'`              | Controls how much agent reasoning and tool detail is shown                               |
  | `onError`                 | function                           | -                        | Error callback for streaming/API errors                                                  |

  ## Operating Modes [#operating-modes]

  The chatbot supports two modes, automatically selected based on the `api` field:

  ### Local/Demo Mode (default) [#localdemo-mode-default]

  When `api` is not set, the chatbot operates in local mode with optional auto-response:

  ```tsx
  const schema = {
    type: 'chatbot',
    messages: [...],
    autoResponse: true,
    autoResponseText: 'Thanks!',
    autoResponseDelay: 1000,
  };
  ```

  ### AI Streaming Mode (service-ai) [#ai-streaming-mode-service-ai]

  When `api` is set, the chatbot uses `@ai-sdk/react` for real SSE streaming:

  ```tsx
  const schema = {
    type: 'chatbot',
    api: '/api/v1/ai/chat',
    model: 'gpt-4o',
    systemPrompt: 'You are a helpful assistant.',
    streamingEnabled: true,
    messages: [],
  };
  ```

  ## Message Roles [#message-roles]

  ### User Messages [#user-messages]

  Messages from the user appear on the right side with primary styling:

  ```tsx
  {
    id: '1',
    role: 'user',
    content: 'Hello!',
    timestamp: '10:30 AM'
  }
  ```

  ### Assistant Messages [#assistant-messages]

  Messages from the assistant appear on the left side:

  ```tsx
  {
    id: '2',
    role: 'assistant',
    content: 'Hi! How can I help?',
    timestamp: '10:30 AM'
  }
  ```

  ### System Messages [#system-messages]

  System messages appear centered with muted styling:

  ```tsx
  {
    id: '3',
    role: 'system',
    content: 'Chat session started'
  }
  ```

  ### Tool Messages (AI Mode) [#tool-messages-ai-mode]

  Tool messages represent results from tool invocations during AI streaming. They are generated automatically by the vercel/ai SDK when the backend performs tool calls (e.g., fetching weather, querying a database). The SDK may emit `role: 'tool'` messages as well as populate the assistant message's `toolInvocations` array.

  By default, `ChatbotEnhanced` renders tool invocations as a compact agent activity summary. Repeated calls are grouped, raw tool names are hidden, and reasoning text is not shown. Use `processVisibility="debug"` for developer/admin views that need the full reasoning panel, raw tool names, parameters, and results. Use `processVisibility="hidden"` to suppress non-interactive activity entirely; approval and draft-review actions remain visible.

  Use `surface="plain"` for full-page chat workspaces where the surrounding app
  already provides navigation chrome. The default `surface="card"` remains a
  better fit for embedded dashboards, side panels, and floating chat windows.

  Console chat surfaces also keep a sanitized browser-side display cache for the
  current conversation. When a conversation can be reopened but the server returns
  no message rows, the UI restores user/assistant text and grouped tool names plus
  states. Reasoning, tool parameters, and raw tool results are not stored in this
  cache.

  ```tsx
  {
    id: '4',
    role: 'assistant',
    content: 'The weather in SF is 68°F.',
    toolInvocations: [
      {
        toolCallId: 'tc-1',
        toolName: 'getWeather',
        args: { city: 'San Francisco' },
        result: { temp: 68, condition: 'Sunny' },
        state: 'result',
      }
    ]
  }
  ```

  ## Examples [#examples]

  ### Simple AI Chat [#simple-ai-chat]

  ```tsx
  const aiChat = {
    type: 'chatbot',
    messages: [
      {
        id: 'welcome',
        role: 'assistant',
        content: 'Hello! I\'m your AI assistant. Ask me anything!'
      }
    ],
    placeholder: 'Ask me a question...',
    assistantAvatarFallback: 'AI',
    userAvatarFallback: 'You',
    autoResponse: true,
    autoResponseText: 'That\'s a great question! Let me think about that...',
    maxHeight: '600px'
  }
  ```

  ### Support Ticket Chat [#support-ticket-chat]

  ```tsx
  const supportChat = {
    type: 'chatbot',
    messages: [
      {
        id: 'sys-1',
        role: 'system',
        content: 'Ticket #12345 - Account Access Issue'
      },
      {
        id: '1',
        role: 'assistant',
        content: 'Hi! I\'m here to help with your account access issue.',
        avatarFallback: 'SP',
        timestamp: '2:15 PM'
      }
    ],
    placeholder: 'Describe your issue...',
    showTimestamp: true,
    userAvatarFallback: 'JD',
    assistantAvatarFallback: 'SP',
    className: 'w-full max-w-3xl mx-auto'
  }
  ```

  ### Sales Bot [#sales-bot]

  ```tsx
  const salesBot = {
    type: 'chatbot',
    messages: [
      {
        id: '1',
        role: 'assistant',
        content: 'Welcome! I\'m here to help you find the perfect product. What are you looking for today?',
        avatarFallback: 'SB'
      }
    ],
    placeholder: 'Tell us what you need...',
    assistantAvatarFallback: 'SB',
    userAvatarFallback: 'You',
    autoResponse: true,
    autoResponseText: 'Great choice! Let me show you some options...',
    autoResponseDelay: 1200,
    maxHeight: '500px',
    className: 'border-2 border-primary rounded-xl'
  }
  ```

  ### Multi-agent Chat [#multi-agent-chat]

  ```tsx
  const multiAgentChat = {
    type: 'chatbot',
    messages: [
      {
        id: '1',
        role: 'assistant',
        content: 'Hello! Sarah from Sales here.',
        avatarFallback: 'SA'
      },
      {
        id: '2',
        role: 'user',
        content: 'I need help with pricing',
        avatarFallback: 'CU'
      },
      {
        id: '3',
        role: 'system',
        content: 'Transferring to Finance team...'
      },
      {
        id: '4',
        role: 'assistant',
        content: 'Hi! Mike from Finance. I can help with that.',
        avatarFallback: 'MI'
      }
    ],
    showTimestamp: true,
    userAvatarFallback: 'CU'
  }
  ```

  ## Custom Avatars [#custom-avatars]

  ### Avatar Images [#avatar-images]

  ```tsx
  const schema = {
    type: 'chatbot',
    userAvatarUrl: 'https://example.com/user-avatar.jpg',
    assistantAvatarUrl: 'https://example.com/bot-avatar.jpg',
    messages: [...]
  }
  ```

  ### Avatar Fallbacks [#avatar-fallbacks]

  When images aren't available, fallback text is displayed:

  ```tsx
  const schema = {
    type: 'chatbot',
    userAvatarFallback: 'JD',  // User initials
    assistantAvatarFallback: 'AI',  // Bot identifier
    messages: [...]
  }
  ```

  ### Per-message Avatars [#per-message-avatars]

  Override avatars for individual messages:

  ```tsx
  {
    id: '1',
    role: 'assistant',
    content: 'Message content',
    avatar: 'https://example.com/special-avatar.jpg',
    avatarFallback: 'SP'
  }
  ```

  ## Event Handling [#event-handling]

  ### onSend Callback [#onsend-callback]

  Handle message sending in your application:

  ```tsx
  const schema = {
    type: 'chatbot',
    messages: [...],
    onSend: (content, allMessages) => {
      console.log('User sent:', content);
      console.log('All messages:', allMessages);
      
      // Send to your backend
      fetch('/api/chat', {
        method: 'POST',
        body: JSON.stringify({ message: content })
      });
    }
  }
  ```

  ## Customization [#customization]

  ### Container Styling [#container-styling]

  ```tsx
  const schema = {
    type: 'chatbot',
    className: 'w-full max-w-2xl mx-auto border-2 rounded-xl shadow-lg',
    maxHeight: '600px',
    messages: [...]
  }
  ```

  ### Responsive Heights [#responsive-heights]

  ```tsx
  const schema = {
    type: 'chatbot',
    maxHeight: '400px', // or use Tailwind: 'h-96'
    className: 'sm:max-h-[500px] lg:max-h-[600px]',
    messages: [...]
  }
  ```

  ## TypeScript Support [#typescript-support]

  ```plaintext
  import type { ChatbotSchema, ChatMessage, ChatToolInvocation } from '@object-ui/types'
  import { useObjectChat } from '@object-ui/plugin-chatbot'

  // Basic messages
  const messages: ChatMessage[] = [
    {
      id: '1',
      role: 'assistant',
      content: 'Hello!'
    }
  ]

  // Local/demo mode
  const demoSchema: ChatbotSchema = {
    type: 'chatbot',
    messages,
    placeholder: 'Type here...',
    showTimestamp: true
  }

  // AI streaming mode (service-ai)
  const aiSchema: ChatbotSchema = {
    type: 'chatbot',
    messages: [],
    api: '/api/v1/ai/chat',
    model: 'gpt-4o',
    systemPrompt: 'You are a helpful assistant.',
    streamingEnabled: true,
    conversationId: 'conv-123',
  }
  ```

  ## Related Documentation [#related-documentation]

  * [Plugin System Overview](/docs/guide/plugins)
  * [Package README](https://github.com/objectstack-ai/objectui/tree/main/packages/plugin-chatbot)
</PluginLoader>


# Plugin Dashboard





Dashboard layouts and metric widgets for creating beautiful dashboards with KPIs, charts, and statistics.

## Installation [#installation]

```bash
npm install @object-ui/plugin-dashboard
```

<PluginLoader plugins="['dashboard']">
  ## Interactive Examples [#interactive-examples]

  <SchemaExample id="plugin-dashboard/basic-dashboard" />

  <SchemaExample id="plugin-dashboard/e-commerce-dashboard" />

  <SchemaExample id="plugin-dashboard/support-dashboard" />

  ## Features [#features]

  * **Dashboard Layouts** - Responsive grid-based layouts
  * **Metric Cards** - Display KPIs with trends and icons
  * **Widget System** - Modular widget architecture
  * **Customizable** - Full Tailwind CSS styling support

  ## Schema API [#schema-api]

  ### Dashboard [#dashboard]

  ```plaintext
  {
    type: 'dashboard',
    widgets: Widget[],
    columns?: number,               // Grid columns (default: 3)
    gap?: number,                   // Gap between widgets
    className?: string
  }
  ```

  ### Metric Card [#metric-card]

  ```plaintext
  {
    type: 'metric-card',
    title: string,
    value: string | number,
    icon?: string,                  // Lucide icon name
    trend?: 'up' | 'down' | 'neutral',
    trendValue?: string,
    description?: string,
    className?: string
  }
  ```

  ## Usage [#usage]

  ### Auto-registration (Side-effect Import) [#auto-registration-side-effect-import]

  ```plaintext
  import '@object-ui/plugin-dashboard';
  ```

  ### Manual Registration [#manual-registration]

  ```plaintext
  import { dashboardComponents } from '@object-ui/plugin-dashboard';
  import { ComponentRegistry } from '@object-ui/core';

  Object.entries(dashboardComponents).forEach(([type, component]) => {
    ComponentRegistry.register(type, component);
  });
  ```

  ## Examples [#examples]

  ### Dashboard with Multiple Metrics [#dashboard-with-multiple-metrics]

  ```json
  {
    "type": "dashboard",
    "columns": 4,
    "gap": 6,
    "widgets": [
      {
        "type": "metric-card",
        "title": "Total Sales",
        "value": "$123,456",
        "icon": "shopping-cart",
        "trend": "up",
        "trendValue": "+15%"
      },
      {
        "type": "metric-card",
        "title": "New Customers",
        "value": "856",
        "icon": "user-plus",
        "trend": "up",
        "trendValue": "+22%"
      },
      {
        "type": "metric-card",
        "title": "Bounce Rate",
        "value": "2.4%",
        "icon": "trending-down",
        "trend": "down",
        "trendValue": "-5%"
      },
      {
        "type": "metric-card",
        "title": "Avg. Order Value",
        "value": "$144.20",
        "icon": "dollar-sign",
        "trend": "up",
        "trendValue": "+8%"
      }
    ]
  }
  ```

  ### Dashboard with Charts [#dashboard-with-charts]

  ```json
  {
    "type": "dashboard",
    "widgets": [
      {
        "type": "metric-card",
        "title": "Total Revenue",
        "value": "$123,456"
      },
      {
        "type": "card",
        "title": "Sales Trend",
        "body": {
          "type": "line-chart",
          "data": [],
          "height": 300
        }
      }
    ]
  }
  ```

  ## Dashboard-level filters [#dashboard-level-filters]

  A dashboard can declare top-level filters — a date range plus any number of
  select / text filters — whose values drive every bound widget at once. Filter
  values live as dashboard-level variables; each widget declares which of **its
  own** fields a filter binds to via `filterBindings`, and the dashboard merges
  the active values into each bound widget's inline query (`AND`-combined with
  the widget's own `filter`).

  ```json
  {
    "type": "dashboard",
    "dateRange": { "field": "created_at", "defaultRange": "last_30_days", "allowCustomRange": true },
    "globalFilters": [
      { "name": "region", "field": "region", "label": "Region", "type": "select", "options": ["EMEA", "APAC", "AMER"] }
    ],
    "widgets": [
      { "id": "w1", "type": "bar", "object": "invoices", "aggregate": "count" },
      {
        "id": "w2", "type": "line", "object": "accounts", "aggregate": "count",
        "filterBindings": { "dateRange": "signed_at", "region": "sales_region" }
      },
      {
        "id": "w3", "type": "metric", "object": "invoices", "aggregate": "count",
        "filterBindings": { "region": false }
      }
    ]
  }
  ```

  Binding rules, in precedence order:

  1. `filterBindings[name]` as a string — apply the filter to that field.
  2. `filterBindings[name]: false` — opt this widget out.
  3. Legacy `targetWidgets` on the filter — when set, only listed widget ids get
     the default binding (an explicit `filterBindings` entry still wins).
  4. Otherwise the filter applies to its own `field` (the built-in date range
     defaults to `dateRange.field ?? 'created_at'`).

  Date presets stay symbolic (date-macro tokens such as `{30_days_ago}`) until
  query time. Dataset-bound widgets receive the merged filter through the
  dataset query's `runtimeFilter`. Static-data widgets (inline `data` arrays)
  have no query to scope and are not filtered. Filter values are also readable
  in widget expressions as `page.<name>`.

  For a step-by-step tutorial — filter types, `optionsFrom` dynamic options,
  `page.*` expression usage, and known limitations with workarounds — see the
  [Dashboard-Level Filters guide](/docs/guide/dashboard-filters). The schema
  catalog ships runnable variants under `plugin-dashboard/filtered-dashboard*`
  (dynamic options, filter types, dataset widgets, `targetWidgets`, date
  presets).

  ## TypeScript Support [#typescript-support]

  ```plaintext
  import type { DashboardSchema, MetricCardSchema } from '@object-ui/plugin-dashboard';

  const dashboard: DashboardSchema = {
    type: 'dashboard',
    columns: 3,
    widgets: [...]
  };
  ```

  ## Type-aware list/table widget cells [#type-aware-listtable-widget-cells]

  `type: 'table'` widgets bound to an `objectName` infer the renderer for
  each cell from the object's field type — Badges for `select`, expanded
  display name for `lookup`/`user`/`owner`, formatted currency/percent/date
  for numeric fields, and so on. Lookup columns are auto-expanded server-side
  via `$expand`, so you don't see raw FK ids. See
  [`@object-ui/plugin-dashboard` README](https://github.com/objectstack-ai/objectui/blob/main/packages/plugin-dashboard/README.md#type-aware-listtable-widget-cells)
  for the full mapping table and an example.

  ## License [#license]

  MIT
</PluginLoader>


# Plugin Designer



# @object-ui/plugin-designer [#object-uiplugin-designer]

Visual designer plugin for Object UI with page, data model, process, and report designers plus collaborative editing.

## Installation [#installation]

```bash
pnpm add @object-ui/plugin-designer
```

## Status [#status]

This plugin is part of the v3.3.0 release. For full API reference and usage
examples, see the package README:

* 📦 [`@object-ui/plugin-designer` on npm](https://www.npmjs.com/package/@object-ui/plugin-designer)
* 📝 [Package README](https://github.com/objectstack-ai/objectui/tree/main/packages/plugin-designer)
* 🐛 [Report an issue](https://github.com/objectstack-ai/objectui/issues)

> **Note:** A rich interactive documentation page for this plugin is coming soon.
> In the meantime, refer to the package README for schema, props and examples.


# Plugin Detail — Feed & Chatter





Record-level discussion, activity timeline, and collaboration components for enterprise CRUD interfaces.

## Installation [#installation]

```bash
npm install @object-ui/plugin-detail
```

<PluginLoader plugins="['detail']">
  ## Overview [#overview]

  The Feed & Chatter system provides Airtable-style record-level collaboration. It includes components for threaded discussions, field change history, @mentions, emoji reactions, and notification subscriptions — all driven by `FeedItem[]` data.

  ### Key Components [#key-components]

  | Component                | Purpose                                                         |
  | ------------------------ | --------------------------------------------------------------- |
  | `RecordChatterPanel`     | Main wrapper panel (bottom/right/left positioning, collapsible) |
  | `RecordActivityTimeline` | Core activity feed renderer (filter, pagination, actor display) |
  | `CommentInput`           | Comment submission with Ctrl+Enter shortcut                     |
  | `FieldChangeItem`        | Field change history display (old → new values)                 |
  | `MentionAutocomplete`    | @mention suggestion dropdown                                    |
  | `ReactionPicker`         | Emoji reaction selector                                         |
  | `ThreadedReplies`        | Collapsible reply threading                                     |
  | `SubscriptionToggle`     | Bell notification toggle                                        |

  ## Usage [#usage]

  ### Basic RecordChatterPanel [#basic-recordchatterpanel]

  ```tsx
  import { RecordChatterPanel } from '@object-ui/plugin-detail';
  import type { FeedItem, RecordSubscription } from '@object-ui/types';

  const items: FeedItem[] = [
    {
      id: '1',
      type: 'comment',
      actor: 'Alice',
      body: 'Updated the deal stage to Negotiation.',
      createdAt: '2026-02-25T10:00:00Z',
      reactions: [{ emoji: '👍', count: 2, reacted: true }],
    },
    {
      id: '2',
      type: 'field_change',
      actor: 'System',
      createdAt: '2026-02-24T15:30:00Z',
      fieldChanges: [
        { field: 'stage', oldValue: 'Qualification', newValue: 'Negotiation' },
      ],
    },
  ];

  <RecordChatterPanel
    config={{
      position: 'bottom',
      collapsible: true,
      defaultCollapsed: false,
      feed: {
        enableReactions: true,
        enableThreading: true,
        showCommentInput: true,
      },
    }}
    items={items}
    onAddComment={(text) => console.log('Comment:', text)}
    onAddReply={(parentId, text) => console.log('Reply:', parentId, text)}
    onToggleReaction={(itemId, emoji) => console.log('Reaction:', itemId, emoji)}
  />
  ```

  ### RecordActivityTimeline [#recordactivitytimeline]

  ```tsx
  import { RecordActivityTimeline } from '@object-ui/plugin-detail';

  <RecordActivityTimeline
    items={items}
    config={{
      types: ['comment', 'field_change'],
      filterMode: 'all',
      showFilterToggle: true,
      showCommentInput: true,
      enableReactions: true,
      enableThreading: true,
      enableMentions: true,
      showSubscriptionToggle: true,
    }}
    filterMode="all"
    onFilterChange={(mode) => console.log('Filter:', mode)}
    hasMore={false}
    loading={false}
  />
  ```

  ### Console Integration [#console-integration]

  In the Console app, `RecordChatterPanel` is integrated with record detail views. Comments are fetched from the `sys_comment` object using a thread ID pattern of `{objectName}:{recordId}`:

  ```tsx
  // Thread ID format
  const threadId = `${objectName}:${recordId}`;

  // Fetch comments
  const comments = await dataSource.find('sys_comment', {
    $filter: { threadId },
    $orderby: 'createdAt asc',
  });

  // Map to FeedItem[]
  const feedItems: FeedItem[] = comments.map(c => ({
    id: c._id,
    type: 'comment',
    actor: c.author,
    body: c.body,
    createdAt: c.createdAt,
    reactions: c.reactions ?? [],
  }));
  ```

  **Full-page detail view** renders the panel non-collapsible at the bottom:

  ```tsx
  <RecordChatterPanel
    config={{ position: 'bottom', collapsible: false }}
    items={feedItems}
    onAddComment={handleAddComment}
  />
  ```

  **Drawer overlay** renders the panel collapsible and default-collapsed:

  ```tsx
  <RecordChatterPanel
    config={{ position: 'bottom', collapsible: true, defaultCollapsed: true }}
    items={feedItems}
    onAddComment={handleAddComment}
  />
  ```

  ## Features [#features]

  * **Threaded Discussions**: Nested comment replies with collapsible threading
  * **Activity Timeline**: Unified view of comments, field changes, tasks, and system events
  * **Filter Modes**: Filter by `all`, `comments_only`, `changes_only`, or `tasks_only`
  * **@Mentions**: Autocomplete dropdown for mentioning users
  * **Emoji Reactions**: Toggle emoji reactions on any feed item
  * **Subscription Toggle**: Bell icon to subscribe/unsubscribe from record notifications
  * **Field Change History**: Visual old → new value display for field changes
  * **Pagination**: Load more items with `hasMore` / `onLoadMore` pattern
  * **Positioning**: Panel can be placed at `bottom`, `right`, or `left` of the record view
  * **Collapsible**: Optional collapse/expand with configurable default state

  ## Schema API [#schema-api]

  ### RecordChatterPanel Config [#recordchatterpanel-config]

  ```plaintext
  {
    position?: 'bottom' | 'right' | 'left',    // Panel placement
    width?: string,                              // CSS width (e.g., '400px')
    collapsible?: boolean,                       // Enable collapse toggle
    defaultCollapsed?: boolean,                  // Start collapsed
    feed?: RecordActivityComponentProps,         // Activity feed config
    aria?: RecordComponentAriaProps              // Accessibility props
  }
  ```

  ### RecordActivityTimeline Config [#recordactivitytimeline-config]

  ```plaintext
  {
    types?: string[],                // Feed item types to show
    filterMode?: string,             // Default filter mode
    showFilterToggle?: boolean,      // Show filter mode buttons
    limit?: number,                  // Items per page
    showCompleted?: boolean,         // Show completed tasks
    unifiedTimeline?: boolean,       // Unified timeline view
    showCommentInput?: boolean,      // Show comment input
    enableMentions?: boolean,        // Enable @mentions
    enableReactions?: boolean,       // Enable emoji reactions
    enableThreading?: boolean,       // Enable threaded replies
    showSubscriptionToggle?: boolean // Show subscription toggle
  }
  ```

  ### FeedItem [#feeditem]

  ```plaintext
  {
    id: string | number,
    type: 'comment' | 'field_change' | 'task' | 'event' | 'system' | 'email' | 'call',
    actor: string,                   // Author display name
    actorAvatarUrl?: string,         // Author avatar URL
    body?: string,                   // Comment/event body text
    createdAt: string,               // ISO 8601 timestamp
    updatedAt?: string,              // Last edit timestamp
    source?: string,                 // Origin source
    parentId?: string | number,      // Parent item for threading
    replyCount?: number,             // Number of replies
    fieldChanges?: FieldChangeEntry[], // For field_change type
    mentions?: Mention[],            // @mention references
    reactions?: Reaction[],          // Emoji reactions
    pinned?: boolean,                // Pinned comment
    edited?: boolean                 // Edited flag
  }
  ```

  ### RecordSubscription [#recordsubscription]

  ```plaintext
  {
    recordId: string | number,
    subscribed: boolean,
    channels?: Array<'in_app' | 'email' | 'push'>
  }
  ```

  ## Properties [#properties]

  ### RecordChatterPanel [#recordchatterpanel]

  | Property               | Type                             | Default  | Description                                       |
  | ---------------------- | -------------------------------- | -------- | ------------------------------------------------- |
  | `config`               | `RecordChatterComponentProps`    | `{}`     | Panel configuration (position, collapsible, feed) |
  | `items`                | `FeedItem[]`                     | required | Feed items to display                             |
  | `hasMore`              | `boolean`                        | `false`  | Whether more items can be loaded                  |
  | `onLoadMore`           | `() => void`                     | —        | Callback to load next page                        |
  | `loading`              | `boolean`                        | `false`  | Loading state indicator                           |
  | `onAddComment`         | `(text: string) => void`         | —        | New comment callback                              |
  | `onAddReply`           | `(parentId, text) => void`       | —        | Reply to comment callback                         |
  | `onToggleReaction`     | `(itemId, emoji) => void`        | —        | Toggle emoji reaction callback                    |
  | `subscription`         | `RecordSubscription`             | —        | Current subscription state                        |
  | `onToggleSubscription` | `(subscribed: boolean) => void`  | —        | Toggle subscription callback                      |
  | `filterMode`           | `FeedFilterMode`                 | `'all'`  | Active filter mode                                |
  | `onFilterChange`       | `(mode: FeedFilterMode) => void` | —        | Filter mode change callback                       |
  | `className`            | `string`                         | `''`     | Additional CSS classes                            |

  ### RecordActivityTimeline [#recordactivitytimeline-1]

  | Property               | Type                            | Default  | Description                      |
  | ---------------------- | ------------------------------- | -------- | -------------------------------- |
  | `items`                | `FeedItem[]`                    | required | Feed items to display            |
  | `config`               | `RecordActivityComponentProps`  | `{}`     | Timeline configuration           |
  | `filterMode`           | `FeedFilterMode`                | `'all'`  | Active filter mode               |
  | `onFilterChange`       | `(mode) => void`                | —        | Filter mode change callback      |
  | `hasMore`              | `boolean`                       | `false`  | Whether more items can be loaded |
  | `onLoadMore`           | `() => void`                    | —        | Callback to load next page       |
  | `loading`              | `boolean`                       | `false`  | Loading state indicator          |
  | `onAddComment`         | `(text: string) => void`        | —        | New comment callback             |
  | `onAddReply`           | `(parentId, text) => void`      | —        | Reply to comment callback        |
  | `onToggleReaction`     | `(itemId, emoji) => void`       | —        | Toggle emoji reaction callback   |
  | `subscription`         | `RecordSubscription`            | —        | Current subscription state       |
  | `onToggleSubscription` | `(subscribed: boolean) => void` | —        | Toggle subscription callback     |
  | `className`            | `string`                        | `''`     | Additional CSS classes           |

  ### CommentInput [#commentinput]

  | Property      | Type                     | Default              | Description             |
  | ------------- | ------------------------ | -------------------- | ----------------------- |
  | `onSubmit`    | `(text: string) => void` | required             | Comment submit callback |
  | `placeholder` | `string`                 | `'Add a comment...'` | Input placeholder text  |
  | `disabled`    | `boolean`                | `false`              | Disable input           |
  | `className`   | `string`                 | `''`                 | Additional CSS classes  |

  ### ReactionPicker [#reactionpicker]

  | Property           | Type                      | Default     | Description              |
  | ------------------ | ------------------------- | ----------- | ------------------------ |
  | `reactions`        | `Reaction[]`              | required    | Current reactions        |
  | `onToggleReaction` | `(emoji: string) => void` | —           | Toggle reaction callback |
  | `emojiOptions`     | `string[]`                | default set | Available emoji options  |
  | `className`        | `string`                  | `''`        | Additional CSS classes   |

  ### ThreadedReplies [#threadedreplies]

  | Property         | Type                       | Default  | Description            |
  | ---------------- | -------------------------- | -------- | ---------------------- |
  | `parentItem`     | `FeedItem`                 | required | Parent comment item    |
  | `replies`        | `FeedItem[]`               | required | Reply items            |
  | `onAddReply`     | `(parentId, text) => void` | —        | Add reply callback     |
  | `showReplyInput` | `boolean`                  | `false`  | Show reply input       |
  | `className`      | `string`                   | `''`     | Additional CSS classes |

  ### SubscriptionToggle [#subscriptiontoggle]

  | Property       | Type                            | Default  | Description                |
  | -------------- | ------------------------------- | -------- | -------------------------- |
  | `subscription` | `RecordSubscription`            | required | Current subscription state |
  | `onToggle`     | `(subscribed: boolean) => void` | —        | Toggle callback            |
  | `className`    | `string`                        | `''`     | Additional CSS classes     |

  ## Filter Modes [#filter-modes]

  ```tsx
  type FeedFilterMode = 'all' | 'comments_only' | 'changes_only' | 'tasks_only';

  // Example: Filter to comments only
  <RecordChatterPanel
    items={items}
    filterMode="comments_only"
    onFilterChange={(mode) => setFilterMode(mode)}
  />
  ```

  ## TypeScript Support [#typescript-support]

  ```tsx
  import type {
    FeedItem,
    FeedItemType,
    FieldChangeEntry,
    Mention,
    Reaction,
    RecordSubscription,
  } from '@object-ui/types';

  import type {
    RecordChatterPanelProps,
    RecordActivityTimelineProps,
    CommentInputProps,
    FieldChangeItemProps,
    ReactionPickerProps,
    ThreadedRepliesProps,
    SubscriptionToggleProps,
    FeedFilterMode,
  } from '@object-ui/plugin-detail';
  ```

  ## Related Documentation [#related-documentation]

  * [Plugin System Overview](/docs/guide/plugins)
  * [Detail View Plugin](/docs/plugins/plugin-view)
  * [Package README](https://github.com/objectstack-ai/objectui/tree/main/packages/plugin-detail)
</PluginLoader>


# Plugin Editor





Code editor component powered by Monaco Editor (VS Code's editor).

## Installation [#installation]

```bash
npm install @object-ui/plugin-editor
```

<PluginLoader plugins="['editor']">
  ## Interactive Examples [#interactive-examples]

  <SchemaExample id="plugin-editor/javascript-editor" />

  <SchemaExample id="plugin-editor/python-editor" />

  <SchemaExample id="plugin-editor/read-only-json-viewer" />

  ## Usage [#usage]

  ### Basic Usage [#basic-usage]

  ```tsx
  // Import once in your app entry point
  import '@object-ui/plugin-editor'

  // Use in schemas
  const schema = {
    type: 'code-editor',
    value: 'console.log("Hello, World!");',
    language: 'javascript',
    theme: 'vs-dark',
    height: '400px'
  }
  ```

  ## Features [#features]

  * **Syntax highlighting** for 100+ languages
  * **IntelliSense and code completion**
  * **Find and replace**
  * **Multiple themes**
  * **Lazy-loaded** (\~20 KB initial, Monaco loads on-demand)

  ## Schema API [#schema-api]

  ```plaintext
  {
    type: 'code-editor',
    value?: string,              // Code content
    language?: string,           // Programming language
    theme?: 'vs-dark' | 'light', // Editor theme
    height?: string,             // Height (e.g., '400px')
    readOnly?: boolean,          // Read-only mode
    className?: string           // Tailwind classes
  }
  ```

  ### Properties [#properties]

  | Property    | Type                     | Default        | Description                                  |
  | ----------- | ------------------------ | -------------- | -------------------------------------------- |
  | `value`     | string                   | `''`           | The code content to display                  |
  | `language`  | string                   | `'javascript'` | Programming language for syntax highlighting |
  | `theme`     | `'vs-dark'` \| `'light'` | `'vs-dark'`    | Editor theme                                 |
  | `height`    | string                   | `'400px'`      | Height of the editor                         |
  | `readOnly`  | boolean                  | `false`        | Whether the editor is read-only              |
  | `className` | string                   | `''`           | Additional Tailwind CSS classes              |

  ## Supported Languages [#supported-languages]

  The Monaco Editor supports 100+ programming languages including:

  * JavaScript / TypeScript
  * Python
  * Java / C# / C++
  * HTML / CSS / SCSS
  * JSON / YAML / XML
  * Markdown
  * SQL
  * Shell / Bash
  * And many more...

  ## Examples [#examples]

  ### JavaScript Editor [#javascript-editor]

  ```tsx
  const schema = {
    type: 'code-editor',
    value: 'function hello() {\n  console.log("Hello!");\n}',
    language: 'javascript',
    theme: 'vs-dark',
    height: '300px'
  }
  ```

  ### Read-only Code Display [#read-only-code-display]

  ```tsx
  const schema = {
    type: 'code-editor',
    value: 'const API_KEY = "secret";\n// Do not modify',
    language: 'typescript',
    readOnly: true,
    theme: 'light'
  }
  ```

  ### Python Editor [#python-editor]

  ```tsx
  const schema = {
    type: 'code-editor',
    value: 'def hello():\n    print("Hello, World!")',
    language: 'python',
    height: '400px'
  }
  ```

  ## Bundle Size [#bundle-size]

  The plugin uses lazy loading to optimize bundle size:

  * **Initial load**: \~0.2 KB (entry point)
  * **Lazy chunk**: \~20 KB (loaded when editor is rendered)
  * **Monaco Editor**: Loaded on-demand from CDN

  This keeps your main application bundle small while providing full IDE-like editing capabilities.

  ## TypeScript Support [#typescript-support]

  ```plaintext
  import type { CodeEditorSchema } from '@object-ui/plugin-editor'

  const editorSchema: CodeEditorSchema = {
    type: 'code-editor',
    value: 'console.log("TypeScript!");',
    language: 'typescript',
    theme: 'vs-dark'
  }
  ```

  ## Related Documentation [#related-documentation]

  * [Plugin System Overview](/docs/guide/plugins)
  * [Lazy-Loaded Plugins Architecture](../concepts/lazy-loading)
  * [Package README](https://github.com/objectstack-ai/objectui/tree/main/packages/plugin-editor)
</PluginLoader>


# Plugin Form





Advanced form components with validation, multi-step forms, and comprehensive field support.

## Installation [#installation]

```bash
npm install @object-ui/plugin-form
```

<PluginLoader plugins="['form']">
  ## Interactive Examples [#interactive-examples]

  <SchemaExample id="plugin-form/basic-form" />

  <SchemaExample id="plugin-form/contact-form" />

  ## Features [#features]

  * **Form Builder** - Create complex forms from schemas
  * **Validation** - Built-in validation with custom rules
  * **Multi-Step Forms** - Wizard-style multi-step forms
  * **Field Types** - All standard HTML5 input types
  * **Form State** - Automatic state management
  * **Error Handling** - Field-level and form-level errors

  ## Schema API [#schema-api]

  ### Form [#form]

  ```plaintext
  {
    type: 'form',
    fields: FormField[],
    submitLabel?: string,
    cancelLabel?: string,
    onSubmit?: (data) => void,
    onCancel?: () => void,
    className?: string
  }
  ```

  ### Form Field [#form-field]

  ```plaintext
  interface FormField {
    name: string;
    type: string;                   // 'input', 'select', 'checkbox', etc.
    label: string;
    placeholder?: string;
    required?: boolean;
    validation?: ValidationRule[];
    defaultValue?: any;
    disabled?: boolean;
    className?: string;
  }
  ```

  ## Usage [#usage]

  ### Auto-registration (Side-effect Import) [#auto-registration-side-effect-import]

  ```plaintext
  import '@object-ui/plugin-form';
  ```

  ### Manual Registration [#manual-registration]

  ```plaintext
  import { formComponents } from '@object-ui/plugin-form';
  import { ComponentRegistry } from '@object-ui/core';

  Object.entries(formComponents).forEach(([type, component]) => {
    ComponentRegistry.register(type, component);
  });
  ```

  ## Examples [#examples]

  ### Form with Validation [#form-with-validation]

  ```json
  {
    "type": "form",
    "fields": [
      {
        "name": "username",
        "type": "input",
        "label": "Username",
        "required": true,
        "validation": [
          { "type": "minLength", "value": 3, "message": "Min 3 characters" },
          { "type": "maxLength", "value": 20, "message": "Max 20 characters" }
        ]
      },
      {
        "name": "password",
        "type": "input",
        "inputType": "password",
        "label": "Password",
        "required": true,
        "validation": [
          { "type": "minLength", "value": 8, "message": "Min 8 characters" }
        ]
      }
    ],
    "submitLabel": "Sign Up"
  }
  ```

  ### Multi-Step Form [#multi-step-form]

  ```json
  {
    "type": "multi-step-form",
    "steps": [
      {
        "title": "Personal Info",
        "fields": [
          { "name": "firstName", "type": "input", "label": "First Name", "required": true },
          { "name": "lastName", "type": "input", "label": "Last Name", "required": true }
        ]
      },
      {
        "title": "Contact Info",
        "fields": [
          { "name": "email", "type": "input", "inputType": "email", "label": "Email", "required": true },
          { "name": "phone", "type": "input", "inputType": "tel", "label": "Phone" }
        ]
      }
    ]
  }
  ```

  ## Field Types [#field-types]

  The plugin supports these field types:

  * **input** - Text, email, password, number, tel, url, etc.
  * **textarea** - Multi-line text input
  * **select** - Dropdown select
  * **checkbox** - Single checkbox
  * **radio-group** - Radio button group
  * **date-picker** - Date selection
  * **file-upload** - File upload

  ## TypeScript Support [#typescript-support]

  ```plaintext
  import type { FormSchema, FormField } from '@object-ui/plugin-form';

  const loginForm: FormSchema = {
    type: 'form',
    fields: [...],
    submitLabel: 'Sign In'
  };
  ```

  ## License [#license]

  MIT
</PluginLoader>


# Plugin Gantt





Gantt chart component for ObjectQL data sources - visualizes project tasks, timelines, and dependencies.

## Installation [#installation]

```bash
npm install @object-ui/plugin-gantt
```

## Overview [#overview]

The `@object-ui/plugin-gantt` plugin provides Gantt chart visualization for ObjectQL data sources. It's designed to work with object-based data providers and automatically maps record fields to Gantt chart tasks.

**Note**: This plugin is designed for use with ObjectQL data sources. For a simpler timeline component, see [Timeline Plugin](/docs/plugins/plugin-timeline).

## Features [#features]

* **ObjectQL Integration**: Works seamlessly with object/api/value data providers
* **Automatic Field Mapping**: Maps database fields to Gantt tasks
* **Task Timeline**: Visual bars showing task duration
* **Progress Tracking**: Display task completion percentage (0-100%)
* **Dependencies**: Visualize task dependencies and relationships
* **Date Ranges**: Automatic date range calculation
* **Interactive**: Click handling for tasks
* **Drag-and-drop rescheduling**: Drag a bar to move it; drag either edge to
  resize start/end. Snaps to whole days and persists the change through
  `dataSource.update()` automatically (optimistic local update + revert on
  failure). See the [package README](https://github.com/objectstack-ai/objectui/blob/main/packages/plugin-gantt/README.md#drag-and-drop-rescheduling) for details on the
  lower-level `onTaskUpdate` hook when embedding `<GanttView>` directly.

<PluginLoader plugins="['gantt']">
  ## Interactive Examples [#interactive-examples]

  ### Basic Gantt Chart [#basic-gantt-chart]

  <SchemaExample id="plugin-gantt/project-timeline-with-dependencies" />

  ### Software Development Sprint [#software-development-sprint]

  <SchemaExample id="plugin-gantt/sprint-development-timeline" />

  ### Construction Project [#construction-project]

  <SchemaExample id="plugin-gantt/construction-project-phases" />
</PluginLoader>

## Usage [#usage]

### Basic Usage with ObjectQL [#basic-usage-with-objectql]

```tsx
import '@object-ui/plugin-gantt'

const schema = {
  type: 'object-gantt',
  objectName: 'tasks',  // Your ObjectQL object
  gantt: {
    startDateField: 'startDate',
    endDateField: 'endDate',
    titleField: 'taskName',
    progressField: 'completion',
    dependenciesField: 'dependencies'
  }
}
```

### With Static Data [#with-static-data]

```tsx
const schema = {
  type: 'object-gantt',
  staticData: [
    {
      id: 1,
      taskName: 'Design Phase',
      startDate: '2024-01-01',
      endDate: '2024-01-15',
      completion: 100
    },
    {
      id: 2,
      taskName: 'Development',
      startDate: '2024-01-16',
      endDate: '2024-02-28',
      completion: 60,
      dependencies: [1]
    },
    {
      id: 3,
      taskName: 'Testing',
      startDate: '2024-03-01',
      endDate: '2024-03-15',
      completion: 0,
      dependencies: [2]
    }
  ],
  gantt: {
    startDateField: 'startDate',
    endDateField: 'endDate',
    titleField: 'taskName',
    progressField: 'completion',
    dependenciesField: 'dependencies'
  }
}
```

## Schema API [#schema-api]

```plaintext
{
  type: 'object-gantt',
  objectName?: string,              // ObjectQL object name
  staticData?: Array<any>,          // Static data array
  data?: ViewData,                  // Advanced data configuration
  gantt?: GanttConfig,              // Gantt-specific configuration
  onTaskClick?: (record: any) => void,
  className?: string
}
```

### GanttConfig [#ganttconfig]

```plaintext
{
  startDateField: string,      // Field containing task start date
  endDateField: string,        // Field containing task end date
  titleField: string,          // Field to use as task title
  progressField?: string,      // Field for progress (0-100)
  dependenciesField?: string   // Field for task dependencies (array of IDs)
}
```

## Configuration [#configuration]

### Field Mapping [#field-mapping]

Map your database fields to Gantt properties:

```tsx
{
  type: 'object-gantt',
  objectName: 'project_tasks',
  gantt: {
    titleField: 'name',           // Database field for task name
    startDateField: 'starts_at',  // Database field for start date
    endDateField: 'ends_at',      // Database field for end date
    progressField: 'percent_done', // Database field for progress
    dependenciesField: 'depends_on' // Database field for dependencies
  }
}
```

### Progress Field [#progress-field]

The progress field should contain a number between 0-100 representing the completion percentage:

```tsx
{
  id: 1,
  taskName: 'Development',
  startDate: '2024-01-01',
  endDate: '2024-02-01',
  completion: 75  // 75% complete
}
```

### Dependencies Field [#dependencies-field]

The dependencies field should contain an array of task IDs that this task depends on:

```tsx
[
  {
    id: 1,
    taskName: 'Design',
    startDate: '2024-01-01',
    endDate: '2024-01-15',
    dependencies: []  // No dependencies
  },
  {
    id: 2,
    taskName: 'Development',
    startDate: '2024-01-16',
    endDate: '2024-02-28',
    dependencies: [1]  // Depends on task 1 (Design)
  },
  {
    id: 3,
    taskName: 'Testing',
    startDate: '2024-03-01',
    endDate: '2024-03-15',
    dependencies: [2]  // Depends on task 2 (Development)
  }
]
```

## Data Providers [#data-providers]

### Object Provider (Database) [#object-provider-database]

```tsx
{
  type: 'object-gantt',
  objectName: 'project_tasks',
  gantt: {
    startDateField: 'start_date',
    endDateField: 'due_date',
    titleField: 'title',
    progressField: 'progress'
  }
}
```

### Value Provider (Static) [#value-provider-static]

```tsx
{
  type: 'object-gantt',
  staticData: [
    { id: 1, title: 'Task 1', start: '2024-01-01', end: '2024-01-15' },
    { id: 2, title: 'Task 2', start: '2024-01-16', end: '2024-01-31' }
  ],
  gantt: {
    startDateField: 'start',
    endDateField: 'end',
    titleField: 'title'
  }
}
```

### API Provider [#api-provider]

```tsx
{
  type: 'object-gantt',
  data: {
    provider: 'api',
    endpoint: '/api/project/tasks',
    method: 'GET'
  },
  gantt: {
    startDateField: 'startDate',
    endDateField: 'endDate',
    titleField: 'taskName',
    progressField: 'percentComplete'
  }
}
```

## Event Handling [#event-handling]

### Task Click [#task-click]

```tsx
{
  type: 'object-gantt',
  objectName: 'tasks',
  gantt: {
    startDateField: 'start',
    endDateField: 'end',
    titleField: 'name'
  },
  onTaskClick: (task) => {
    console.log('Task clicked:', task);
    // Open task details
    // Edit task
    // Show task dependencies
  }
}
```

## Examples [#examples]

### Software Project [#software-project]

```tsx
const softwareProject = {
  type: 'object-gantt',
  objectName: 'sprint_tasks',
  gantt: {
    startDateField: 'startDate',
    endDateField: 'endDate',
    titleField: 'taskTitle',
    progressField: 'completionPercent',
    dependenciesField: 'blockedBy'
  },
  onTaskClick: (task) => {
    // Show task details modal
  }
}
```

### Construction Project [#construction-project-1]

```tsx
const constructionGantt = {
  type: 'object-gantt',
  objectName: 'construction_phases',
  gantt: {
    startDateField: 'phase_start',
    endDateField: 'phase_end',
    titleField: 'phase_name',
    progressField: 'percent_complete'
  },
  onTaskClick: (phase) => {
    // Navigate to phase details
  }
}
```

### Marketing Campaign [#marketing-campaign]

```tsx
const campaignGantt = {
  type: 'object-gantt',
  staticData: [
    {
      id: 1,
      activity: 'Market Research',
      start: '2024-01-01',
      end: '2024-01-14',
      done: 100
    },
    {
      id: 2,
      activity: 'Content Creation',
      start: '2024-01-15',
      end: '2024-02-15',
      done: 80,
      requires: [1]
    },
    {
      id: 3,
      activity: 'Campaign Launch',
      start: '2024-02-16',
      end: '2024-02-29',
      done: 0,
      requires: [2]
    },
    {
      id: 4,
      activity: 'Performance Analysis',
      start: '2024-03-01',
      end: '2024-03-15',
      done: 0,
      requires: [3]
    }
  ],
  gantt: {
    titleField: 'activity',
    startDateField: 'start',
    endDateField: 'end',
    progressField: 'done',
    dependenciesField: 'requires'
  }
}
```

## Comparison with Timeline Plugin [#comparison-with-timeline-plugin]

| Feature           | object-gantt             | timeline (gantt variant) |
| ----------------- | ------------------------ | ------------------------ |
| **Data Source**   | ObjectQL (database)      | Static arrays            |
| **Dependencies**  | Yes                      | No                       |
| **Progress**      | Yes (0-100%)             | No                       |
| **Use Case**      | Project management       | Simple timelines         |
| **Field Mapping** | Configurable             | Fixed schema             |
| **Best For**      | Database-driven projects | Static presentations     |

**When to use object-gantt**:

* You're using ObjectQL for data management
* You need task dependencies and progress tracking
* Tasks come from a database or API
* You're building project management features

**When to use timeline (gantt variant)**:

* You have static timeline data
* You don't need dependencies or progress
* You're creating simple visual timelines
* You're not using ObjectQL

## Typical Use Cases [#typical-use-cases]

1. **Project Management**: Track project tasks, milestones, and dependencies
2. **Sprint Planning**: Visualize agile sprint tasks and their timeline
3. **Construction Planning**: Display construction phases and their relationships
4. **Event Planning**: Show event preparation tasks and schedules
5. **Product Roadmap**: Display product features and release timelines

## TypeScript Support [#typescript-support]

```plaintext
import type { ObjectGridSchema, GanttConfig } from '@object-ui/types'

const ganttConfig: GanttConfig = {
  startDateField: 'startDate',
  endDateField: 'endDate',
  titleField: 'taskName',
  progressField: 'completion',
  dependenciesField: 'dependencies'
}

const ganttSchema: ObjectGridSchema = {
  type: 'object-gantt',
  objectName: 'project_tasks',
  gantt: ganttConfig
}
```

## Related Documentation [#related-documentation]

* [Timeline Plugin](/docs/plugins/plugin-timeline) - Simpler timeline visualization
* [Plugin System Overview](/docs/guide/plugins)
* [Package README](https://github.com/objectstack-ai/objectui/tree/main/packages/plugin-gantt)


# Plugin Grid





Advanced data grid with sorting, filtering, pagination, and row selection capabilities.

## Installation [#installation]

```bash
npm install @object-ui/plugin-grid
```

<PluginLoader plugins="['grid']">
  ## Interactive Examples [#interactive-examples]

  <SchemaExample id="plugin-grid/product-inventory-grid" />

  <SchemaExample id="plugin-grid/team-members-grid" />

  ## Features [#features]

  * **Sorting** - Multi-column sorting support
  * **Filtering** - Column-level filtering
  * **Pagination** - Built-in pagination controls
  * **Row Selection** - Single and multi-row selection
  * **Custom Cells** - Custom cell renderers
  * **Responsive** - Mobile-friendly layouts

  ## Schema API [#schema-api]

  ### Grid [#grid]

  ```plaintext
  {
    type: 'grid',
    columns: GridColumn[],
    data?: any[],
    sortable?: boolean,
    filterable?: boolean,
    pagination?: boolean | PaginationConfig,
    selectable?: boolean,
    onRowClick?: (row) => void,
    className?: string
  }
  ```

  ### Column Definition [#column-definition]

  ```plaintext
  interface GridColumn {
    header: string;
    accessorKey: string;
    sortable?: boolean;
    filterable?: boolean;
    width?: number | string;
    align?: 'left' | 'center' | 'right';
    cell?: (value, row) => ReactNode;
  }
  ```

  ## Usage [#usage]

  ### Auto-registration (Side-effect Import) [#auto-registration-side-effect-import]

  ```plaintext
  import '@object-ui/plugin-grid';
  ```

  ### Manual Registration [#manual-registration]

  ```plaintext
  import { gridComponents } from '@object-ui/plugin-grid';
  import { ComponentRegistry } from '@object-ui/core';

  Object.entries(gridComponents).forEach(([type, component]) => {
    ComponentRegistry.register(type, component);
  });
  ```

  ## Examples [#examples]

  ### Grid with Custom Cells [#grid-with-custom-cells]

  ```json
  {
    "type": "grid",
    "columns": [
      { "header": "Name", "accessorKey": "name" },
      { 
        "header": "Status", 
        "accessorKey": "status",
        "cell": {
          "type": "badge",
          "label": "${value}",
          "variant": "${value === 'Active' ? 'success' : 'default'}"
        }
      },
      {
        "header": "Actions",
        "accessorKey": "id",
        "cell": {
          "type": "button-group",
          "buttons": [
            { "label": "Edit" },
            { "label": "Delete", "variant": "destructive" }
          ]
        }
      }
    ]
  }
  ```

  ### Selectable Grid [#selectable-grid]

  ```json
  {
    "type": "grid",
    "columns": [...],
    "data": [...],
    "selectable": true,
    "onSelectionChange": "handleSelection"
  }
  ```

  ### Grid with Pagination [#grid-with-pagination]

  ```json
  {
    "type": "grid",
    "columns": [...],
    "data": [...],
    "pagination": {
      "pageSize": 10,
      "showSizeChanger": true,
      "pageSizeOptions": [10, 20, 50, 100]
    }
  }
  ```

  ### ObjectQL Integration [#objectql-integration]

  ```json
  {
    "type": "object-grid",
    "object": "users",
    "columns": [
      { "header": "Name", "accessorKey": "name" },
      { "header": "Email", "accessorKey": "email" },
      { "header": "Created", "accessorKey": "created_at" }
    ],
    "pagination": true,
    "sortable": true,
    "filterable": true
  }
  ```

  ## Features [#features-1]

  ### Sorting [#sorting]

  Enable sorting on all or specific columns:

  ```json
  {
    "type": "grid",
    "sortable": true,
    "columns": [
      { "header": "Name", "accessorKey": "name", "sortable": true },
      { "header": "Email", "accessorKey": "email", "sortable": false }
    ]
  }
  ```

  ### Filtering [#filtering]

  Enable column-level filtering:

  ```json
  {
    "type": "grid",
    "filterable": true,
    "columns": [
      { "header": "Status", "accessorKey": "status", "filterable": true }
    ]
  }
  ```

  ### Row Actions [#row-actions]

  Add action buttons to each row:

  ```json
  {
    "type": "grid",
    "rowActions": [
      { "label": "View", "onClick": "viewRow" },
      { "label": "Edit", "onClick": "editRow" },
      { "label": "Delete", "onClick": "deleteRow" }
    ]
  }
  ```

  ### Inline Editing [#inline-editing]

  Enable inline cell editing for quick data updates:

  ```json
  {
    "type": "object-grid",
    "objectName": "users",
    "columns": [
      { "header": "ID", "accessorKey": "id", "editable": false },
      { "header": "Name", "accessorKey": "name" },
      { "header": "Email", "accessorKey": "email" },
      { "header": "Status", "accessorKey": "status" }
    ],
    "editable": true,
    "onCellChange": "handleCellChange"
  }
  ```

  **Features:**

  * Double-click or press Enter on a cell to start editing
  * Press Enter to save changes
  * Press Escape to cancel editing
  * Column-level control: Set `editable: false` on specific columns to prevent editing
  * Callback support: Use `onCellChange` to handle cell value updates

  **Example Handler:**

  ```javascript
  function handleCellChange(rowIndex, columnKey, newValue, row) {
    console.log(`Cell at row ${rowIndex}, column ${columnKey} changed to:`, newValue);
    console.log('Full row data:', row);
    // Update your data source here
  }
  ```

  ### Batch Editing & Multi-Row Save [#batch-editing--multi-row-save]

  Edit multiple cells across multiple rows and save them individually or all at once:

  ```json
  {
    "type": "object-grid",
    "objectName": "products",
    "columns": [
      { "header": "SKU", "accessorKey": "sku", "editable": false },
      { "header": "Name", "accessorKey": "name" },
      { "header": "Price", "accessorKey": "price" }
    ],
    "editable": true,
    "rowActions": true,
    "onRowSave": "handleRowSave",
    "onBatchSave": "handleBatchSave"
  }
  ```

  **Features:**

  * **Pending changes tracking**: Edit multiple cells across rows before saving
  * **Visual indicators**: Modified rows highlighted in amber, modified cells in bold
  * **Row-level save/cancel**: Individual row save and cancel buttons
  * **Batch operations**: Save All and Cancel All buttons for bulk actions
  * **Flexible callbacks**: `onRowSave` for single row, `onBatchSave` for multiple rows

  **Example Handlers:**

  ```javascript
  function handleRowSave(rowIndex, changes, row) {
    console.log('Saving row:', rowIndex, changes);
    // Save single row to backend
    await dataSource.update(row.id, changes);
  }

  function handleBatchSave(allChanges) {
    console.log('Batch saving:', allChanges.length, 'rows');
    // Save all changes at once
    await Promise.all(
      allChanges.map(({ row, changes }) => 
        dataSource.update(row.id, changes)
      )
    );
  }
  ```

  ## TypeScript Support [#typescript-support]

  ```plaintext
  import type { GridSchema, GridColumn } from '@object-ui/plugin-grid';

  const grid: GridSchema = {
    type: 'grid',
    columns: [...],
    data: [],
    sortable: true,
    pagination: true
  };
  ```

  ## License [#license]

  MIT
</PluginLoader>


# Plugin Kanban





Kanban board component with drag-and-drop powered by @dnd-kit.

## Installation [#installation]

```bash
npm install @object-ui/plugin-kanban
```

<PluginLoader plugins="['kanban']">
  ## Interactive Examples [#interactive-examples]

  <SchemaExample id="plugin-kanban/basic-kanban-board" />

  <SchemaExample id="plugin-kanban/advanced-kanban-with-badges-and-limits" />

  ## Usage [#usage]

  ### Basic Usage [#basic-usage]

  ```tsx
  // Import once in your app entry point
  import '@object-ui/plugin-kanban'

  // Use in schemas
  const schema = {
    type: 'kanban',
    columns: [
      {
        id: 'todo',
        title: 'To Do',
        cards: [
          { id: '1', title: 'Task 1', description: 'Do something' }
        ]
      },
      {
        id: 'done',
        title: 'Done',
        cards: []
      }
    ],
    onCardMove: (cardId, fromCol, toCol, index) => {
      console.log(`Card ${cardId} moved`)
    }
  }
  ```

  ## Features [#features]

  * **Drag and drop cards** between columns
  * **Column limits** (WIP limits)
  * **Card badges** for status/priority
  * **Keyboard navigation**
  * **Lazy-loaded** (\~100-150 KB loads only when rendered)

  ## Schema API [#schema-api]

  ```plaintext
  {
    type: 'kanban',
    columns?: KanbanColumn[],
    onCardMove?: (cardId, fromColumnId, toColumnId, newIndex) => void,
    className?: string
  }

  interface KanbanColumn {
    id: string
    title: string
    cards: KanbanCard[]
    limit?: number              // Max cards allowed
    className?: string
  }

  interface KanbanCard {
    id: string
    title: string
    description?: string
    badges?: Array<{
      label: string
      variant?: 'default' | 'secondary' | 'destructive' | 'outline'
    }>
  }
  ```

  ### Properties [#properties]

  | Property     | Type            | Description                     |
  | ------------ | --------------- | ------------------------------- |
  | `columns`    | KanbanColumn\[] | Array of column definitions     |
  | `onCardMove` | function        | Callback when a card is moved   |
  | `className`  | string          | Additional Tailwind CSS classes |

  ### Column Properties [#column-properties]

  | Property    | Type          | Description                     |
  | ----------- | ------------- | ------------------------------- |
  | `id`        | string        | Unique column identifier        |
  | `title`     | string        | Column title                    |
  | `cards`     | KanbanCard\[] | Cards in this column            |
  | `limit`     | number        | Max cards allowed (WIP limit)   |
  | `className` | string        | Additional Tailwind CSS classes |

  ### Card Properties [#card-properties]

  | Property      | Type     | Description            |
  | ------------- | -------- | ---------------------- |
  | `id`          | string   | Unique card identifier |
  | `title`       | string   | Card title             |
  | `description` | string   | Card description       |
  | `badges`      | Badge\[] | Status/priority badges |

  ### Card fields (object-driven boards) [#card-fields-object-driven-boards]

  When a board is bound to an object (an `object-kanban`, or a kanban view inside
  `ListView` / `ObjectView`) instead of being given static `columns`, the fields
  rendered on each card resolve in priority order:

  1. **View-level `cardFields`** — the fields the view configures (a kanban view's
     `columns`, forwarded as `cardFields`). An explicit choice always wins.
  2. **The object's `highlightFields`** — the object's ADR-0085 semantic role (its
     curated "most important fields"), the same list the Grid, List and Detail
     surfaces already default to. Used when the view configures no card fields, so
     a board over an object with no per-view config still surfaces meaningful
     fields. Entries that reference a field the object no longer declares are
     ignored.
  3. **A legacy semantic-field heuristic** — a best-effort guess (amount, owner,
     priority, …) used only when neither of the above is available.

  Defaulting to `highlightFields` keeps a card's contents consistent with the
  object's other views without every kanban view having to re-declare its fields.

  ## Examples [#examples]

  ### Project Task Board [#project-task-board]

  ```tsx
  const taskBoard = {
    type: 'kanban',
    columns: [
      {
        id: 'backlog',
        title: 'Backlog',
        cards: [
          {
            id: 'task-1',
            title: 'Design new homepage',
            description: 'Create mockups for the new landing page',
            badges: [
              { label: 'Design', variant: 'default' },
              { label: 'High Priority', variant: 'destructive' }
            ]
          }
        ]
      },
      {
        id: 'in-progress',
        title: 'In Progress',
        limit: 3,  // WIP limit
        cards: [
          {
            id: 'task-2',
            title: 'Implement authentication',
            description: 'Add OAuth2 login flow',
            badges: [
              { label: 'Backend', variant: 'secondary' }
            ]
          }
        ]
      },
      {
        id: 'review',
        title: 'Code Review',
        cards: []
      },
      {
        id: 'done',
        title: 'Done',
        cards: []
      }
    ],
    onCardMove: (cardId, fromCol, toCol, index) => {
      // Update backend/state
      console.log(`Moved ${cardId} from ${fromCol} to ${toCol}`)
    }
  }
  ```

  ### Support Ticket Board [#support-ticket-board]

  ```tsx
  const ticketBoard = {
    type: 'kanban',
    columns: [
      {
        id: 'new',
        title: 'New Tickets',
        cards: [
          {
            id: 'ticket-1',
            title: 'Login not working',
            description: 'User cannot log in with Google',
            badges: [
              { label: 'Bug', variant: 'destructive' },
              { label: 'P1', variant: 'destructive' }
            ]
          }
        ]
      },
      {
        id: 'assigned',
        title: 'Assigned',
        limit: 5,
        cards: []
      },
      {
        id: 'resolved',
        title: 'Resolved',
        cards: []
      }
    ],
    className: 'min-h-[600px]'
  }
  ```

  ### Sales Pipeline [#sales-pipeline]

  ```tsx
  const salesPipeline = {
    type: 'kanban',
    columns: [
      {
        id: 'leads',
        title: 'Leads',
        cards: [
          {
            id: 'lead-1',
            title: 'Acme Corp',
            description: '$50,000 - Enterprise plan',
            badges: [
              { label: 'Hot Lead', variant: 'destructive' }
            ]
          }
        ]
      },
      {
        id: 'qualified',
        title: 'Qualified',
        cards: []
      },
      {
        id: 'proposal',
        title: 'Proposal Sent',
        cards: []
      },
      {
        id: 'won',
        title: 'Won',
        cards: []
      }
    ]
  }
  ```

  ## Card Badges [#card-badges]

  Use badges to show card status, priority, or categories:

  ```tsx
  const card = {
    id: 'task-1',
    title: 'Important Task',
    badges: [
      { label: 'Frontend', variant: 'default' },
      { label: 'Urgent', variant: 'destructive' },
      { label: 'Reviewed', variant: 'secondary' },
      { label: 'Blocked', variant: 'outline' }
    ]
  }
  ```

  ### Badge Variants [#badge-variants]

  * `default` - Blue badge
  * `secondary` - Gray badge
  * `destructive` - Red badge
  * `outline` - Outlined badge

  ## Column Limits (WIP Limits) [#column-limits-wip-limits]

  Set maximum cards per column to enforce work-in-progress limits:

  ```tsx
  const column = {
    id: 'in-progress',
    title: 'In Progress',
    limit: 3,  // Max 3 cards
    cards: [...]
  }
  ```

  When the limit is reached, the column shows visual feedback.

  ## Event Handling [#event-handling]

  Handle card movements to update your backend or state:

  ```tsx
  const schema = {
    type: 'kanban',
    columns: [...],
    onCardMove: (cardId, fromColumnId, toColumnId, newIndex) => {
      // Update database
      await updateCardColumn(cardId, toColumnId, newIndex)
      
      // Update local state
      setCards(prev => moveCard(prev, cardId, toColumnId, newIndex))
    }
  }
  ```

  ## Bundle Size [#bundle-size]

  The plugin uses lazy loading to optimize bundle size:

  * **Initial load**: \~0.2 KB (entry point)
  * **Lazy chunk**: \~100-150 KB (loaded when kanban is rendered)
  * **Includes @dnd-kit** for drag-and-drop functionality

  ## Accessibility [#accessibility]

  The kanban board includes:

  * **Keyboard navigation** - Move cards with keyboard
  * **Screen reader support** - ARIA labels for all interactions
  * **Focus management** - Clear focus indicators

  ## TypeScript Support [#typescript-support]

  ```plaintext
  import type { KanbanSchema, KanbanCard, KanbanColumn } from '@object-ui/plugin-kanban'

  const column: KanbanColumn = {
    id: 'todo',
    title: 'To Do',
    cards: [],
    limit: 5
  }

  const kanbanSchema: KanbanSchema = {
    type: 'kanban',
    columns: [column]
  }
  ```

  ## Related Documentation [#related-documentation]

  * [Plugin System Overview](/docs/guide/plugins)
  * [Lazy-Loaded Plugins Architecture](../concepts/lazy-loading)
  * [Package README](https://github.com/objectstack-ai/objectui/tree/main/packages/plugin-kanban)
</PluginLoader>


# Plugin List



# @object-ui/plugin-list [#object-uiplugin-list]

ListView plugin for Object UI - unified view component with view type switching

## Installation [#installation]

```bash
pnpm add @object-ui/plugin-list
```

## Status [#status]

This plugin is part of the v3.3.0 release. For full API reference and usage
examples, see the package README:

* 📦 [`@object-ui/plugin-list` on npm](https://www.npmjs.com/package/@object-ui/plugin-list)
* 📝 [Package README](https://github.com/objectstack-ai/objectui/tree/main/packages/plugin-list)
* 🐛 [Report an issue](https://github.com/objectstack-ai/objectui/issues)

> **Note:** A rich interactive documentation page for this plugin is coming soon.
> In the meantime, refer to the package README for schema, props and examples.


# Plugin Map





Map visualization component for ObjectQL data sources - displays database records as map markers based on location data.

## Installation [#installation]

```bash
npm install @object-ui/plugin-map
```

## Overview [#overview]

The `@object-ui/plugin-map` plugin provides map visualization for ObjectQL data sources. It's designed to work with object-based data providers and automatically maps record fields to map markers/pins.

**Note**: This is a basic implementation suitable for simple use cases. For production applications with advanced mapping needs, consider integrating a dedicated mapping library like Mapbox, Leaflet, or Google Maps.

## Features [#features]

* **ObjectQL Integration**: Works seamlessly with object/api/value data providers
* **Automatic Field Mapping**: Maps database fields to map markers
* **Location Support**: Handle latitude/longitude or combined location fields
* **Marker Customization**: Configurable marker titles and descriptions
* **Marker Clustering**: Group nearby markers (when many points)
* **Popup/Tooltip**: Show details on marker click
* **Interactive**: Click handling for markers

<PluginLoader plugins="['map']">
  ## Interactive Examples [#interactive-examples]

  ### Store Locations [#store-locations]

  <SchemaExample id="plugin-map/store-locator-map" />

  ### Delivery Tracking [#delivery-tracking]

  <SchemaExample id="plugin-map/real-time-delivery-tracking" />

  ### Event Venues [#event-venues]

  <SchemaExample id="plugin-map/event-venue-finder" />
</PluginLoader>

## Usage [#usage]

### Basic Usage with ObjectQL [#basic-usage-with-objectql]

```tsx
import '@object-ui/plugin-map'

const schema = {
  type: 'object-map',
  objectName: 'locations',  // Your ObjectQL object
  map: {
    latitudeField: 'lat',
    longitudeField: 'lng',
    titleField: 'name',
    descriptionField: 'address'
  }
}
```

### With Static Data [#with-static-data]

```tsx
const schema = {
  type: 'object-map',
  staticData: [
    {
      id: 1,
      name: 'Office HQ',
      lat: 37.7749,
      lng: -122.4194,
      address: '123 Main St, San Francisco, CA'
    },
    {
      id: 2,
      name: 'Warehouse',
      lat: 37.8044,
      lng: -122.2711,
      address: '456 Oak Ave, Oakland, CA'
    }
  ],
  map: {
    latitudeField: 'lat',
    longitudeField: 'lng',
    titleField: 'name',
    descriptionField: 'address'
  }
}
```

## Schema API [#schema-api]

```plaintext
{
  type: 'object-map',
  objectName?: string,              // ObjectQL object name
  staticData?: Array<any>,          // Static data array
  data?: ViewData,                  // Advanced data configuration
  map?: MapConfig,                  // Map-specific configuration
  onMarkerClick?: (record: any) => void,
  className?: string
}
```

### MapConfig [#mapconfig]

```plaintext
{
  latitudeField?: string,      // Field containing latitude
  longitudeField?: string,     // Field containing longitude
  locationField?: string,      // Field with combined location (alternative)
  titleField?: string,         // Field to use as marker title
  descriptionField?: string,   // Field for marker description
  zoom?: number,               // Default zoom level (1-20)
  center?: [number, number]    // Center coordinates [lat, lng]
}
```

## Configuration [#configuration]

### Field Mapping - Separate Coordinates [#field-mapping---separate-coordinates]

When your data has separate latitude and longitude fields:

```tsx
{
  type: 'object-map',
  objectName: 'stores',
  map: {
    latitudeField: 'latitude',
    longitudeField: 'longitude',
    titleField: 'storeName',
    descriptionField: 'storeAddress'
  }
}
```

### Field Mapping - Combined Location [#field-mapping---combined-location]

When your data has a combined location field:

```tsx
{
  type: 'object-map',
  objectName: 'places',
  map: {
    locationField: 'coordinates',  // e.g., "37.7749,-122.4194" or {lat: 37.7749, lng: -122.4194}
    titleField: 'placeName',
    descriptionField: 'description'
  }
}
```

### Zoom and Center [#zoom-and-center]

Control the initial map view:

```tsx
{
  type: 'object-map',
  objectName: 'locations',
  map: {
    latitudeField: 'lat',
    longitudeField: 'lng',
    titleField: 'name',
    zoom: 12,                    // Zoom level (1-20)
    center: [37.7749, -122.4194] // [latitude, longitude]
  }
}
```

## Data Providers [#data-providers]

### Object Provider (Database) [#object-provider-database]

```tsx
{
  type: 'object-map',
  objectName: 'retail_stores',
  map: {
    latitudeField: 'store_lat',
    longitudeField: 'store_lng',
    titleField: 'store_name',
    descriptionField: 'store_address'
  }
}
```

### Value Provider (Static) [#value-provider-static]

```tsx
{
  type: 'object-map',
  staticData: [
    { id: 1, name: 'Location 1', lat: 37.7749, lng: -122.4194 },
    { id: 2, name: 'Location 2', lat: 37.8044, lng: -122.2711 }
  ],
  map: {
    latitudeField: 'lat',
    longitudeField: 'lng',
    titleField: 'name'
  }
}
```

### API Provider [#api-provider]

```tsx
{
  type: 'object-map',
  data: {
    provider: 'api',
    endpoint: '/api/locations',
    method: 'GET'
  },
  map: {
    latitudeField: 'latitude',
    longitudeField: 'longitude',
    titleField: 'locationName'
  }
}
```

## Event Handling [#event-handling]

### Marker Click [#marker-click]

```tsx
{
  type: 'object-map',
  objectName: 'locations',
  map: {
    latitudeField: 'lat',
    longitudeField: 'lng',
    titleField: 'name'
  },
  onMarkerClick: (location) => {
    console.log('Marker clicked:', location);
    // Show location details
    // Navigate to location page
    // Open directions
  }
}
```

## Examples [#examples]

### Store Locator [#store-locator]

```tsx
const storeLocator = {
  type: 'object-map',
  objectName: 'retail_locations',
  map: {
    latitudeField: 'latitude',
    longitudeField: 'longitude',
    titleField: 'storeName',
    descriptionField: 'fullAddress',
    zoom: 10,
    center: [37.7749, -122.4194]  // San Francisco
  },
  onMarkerClick: (store) => {
    // Show store details
    // Display hours, phone, etc.
  }
}
```

### Delivery Tracking [#delivery-tracking-1]

```tsx
const deliveryMap = {
  type: 'object-map',
  objectName: 'active_deliveries',
  map: {
    latitudeField: 'current_lat',
    longitudeField: 'current_lng',
    titleField: 'driver_name',
    descriptionField: 'delivery_address'
  },
  onMarkerClick: (delivery) => {
    // Show delivery details
    // Contact driver
  }
}
```

### Real Estate Listings [#real-estate-listings]

```tsx
const propertyMap = {
  type: 'object-map',
  objectName: 'properties',
  map: {
    latitudeField: 'property_lat',
    longitudeField: 'property_lng',
    titleField: 'property_address',
    descriptionField: 'property_details',
    zoom: 12
  },
  onMarkerClick: (property) => {
    // Show property details
    // Display photos, price, etc.
  }
}
```

### Event Venues [#event-venues-1]

```tsx
const venueMap = {
  type: 'object-map',
  staticData: [
    {
      id: 1,
      venueName: 'Conference Center',
      lat: 37.7833,
      lng: -122.4167,
      details: 'Capacity: 500 people'
    },
    {
      id: 2,
      venueName: 'Exhibition Hall',
      lat: 37.7891,
      lng: -122.3894,
      details: 'Capacity: 1000 people'
    },
    {
      id: 3,
      venueName: 'Outdoor Amphitheater',
      lat: 37.7694,
      lng: -122.4862,
      details: 'Capacity: 2000 people'
    }
  ],
  map: {
    latitudeField: 'lat',
    longitudeField: 'lng',
    titleField: 'venueName',
    descriptionField: 'details',
    zoom: 11
  },
  onMarkerClick: (venue) => {
    // Show venue details
    // Book venue
  }
}
```

### Field Service Map [#field-service-map]

```tsx
const serviceMap = {
  type: 'object-map',
  objectName: 'service_calls',
  map: {
    latitudeField: 'customer_latitude',
    longitudeField: 'customer_longitude',
    titleField: 'customer_name',
    descriptionField: 'service_type',
    zoom: 10
  },
  onMarkerClick: (serviceCall) => {
    // Show service call details
    // Assign technician
    // Get directions
  }
}
```

## Typical Use Cases [#typical-use-cases]

1. **Store Locator**: Display retail store locations
2. **Fleet Tracking**: Show vehicle or delivery locations
3. **Real Estate**: Display property listings on a map
4. **Event Venues**: Show event or venue locations
5. **Field Service**: Track service calls or technician locations
6. **Customer Locations**: Visualize customer distribution
7. **Asset Tracking**: Show location of equipment or assets

## Location Data Formats [#location-data-formats]

### Separate Fields [#separate-fields]

```tsx
{
  id: 1,
  name: 'Location',
  latitude: 37.7749,
  longitude: -122.4194
}
```

### Combined String [#combined-string]

```tsx
{
  id: 1,
  name: 'Location',
  coordinates: '37.7749,-122.4194'
}
```

### Object Format [#object-format]

```tsx
{
  id: 1,
  name: 'Location',
  location: {
    lat: 37.7749,
    lng: -122.4194
  }
}
```

## Map Controls [#map-controls]

The map typically includes:

* **Zoom controls**: Zoom in/out buttons
* **Pan**: Drag to move around the map
* **Marker click**: Click markers to show details
* **Auto-fit**: Automatically adjust view to show all markers

## Integration with Full-featured Map Libraries [#integration-with-full-featured-map-libraries]

For production applications, you may want to integrate with:

* **Mapbox**: Advanced styling, 3D maps, routing
* **Google Maps**: Street view, directions, extensive POI data
* **Leaflet**: Open-source, lightweight, customizable
* **OpenStreetMap**: Free, community-driven map data

This plugin provides a basic implementation. For advanced features like:

* Directions/routing
* Street view
* 3D buildings
* Traffic data
* Custom map styles
* Advanced geocoding

Consider using one of the full-featured mapping libraries above.

## TypeScript Support [#typescript-support]

```plaintext
import type { ObjectGridSchema, MapConfig } from '@object-ui/types'

const mapConfig: MapConfig = {
  latitudeField: 'lat',
  longitudeField: 'lng',
  titleField: 'name',
  descriptionField: 'description',
  zoom: 12,
  center: [37.7749, -122.4194]
}

const mapSchema: ObjectGridSchema = {
  type: 'object-map',
  objectName: 'locations',
  map: mapConfig
}
```

## Related Documentation [#related-documentation]

* [Plugin System Overview](/docs/guide/plugins)
* [Package README](https://github.com/objectstack-ai/objectui/tree/main/packages/plugin-map)


# Plugin Markdown





Markdown renderer with GitHub Flavored Markdown support.

## Installation [#installation]

```bash
npm install @object-ui/plugin-markdown
```

<PluginLoader plugins="['markdown']">
  ## Usage [#usage]

  ### Basic Usage [#basic-usage]

  ```tsx
  // Import once in your app entry point
  import '@object-ui/plugin-markdown'

  // Use in schemas
  const schema = {
    type: 'markdown',
    content: '# Hello World\n\nThis is **markdown** text with [links](https://example.com).'
  }
  ```

  ## Interactive Examples [#interactive-examples]

  <SchemaExample id="plugin-markdown/basic-markdown" />

  <SchemaExample id="plugin-markdown/advanced-features" />

  <SchemaExample id="plugin-markdown/markdown-tables" />

  ## Features [#features]

  * **GitHub Flavored Markdown** (tables, task lists, strikethrough)
  * **XSS protection** (sanitized output)
  * **Code syntax highlighting**
  * **Lazy-loaded** (\~100-200 KB loads only when rendered)

  ## Schema API [#schema-api]

  ```plaintext
  {
    type: 'markdown',
    content?: string,    // Markdown content
    className?: string   // Tailwind classes
  }
  ```

  ### Properties [#properties]

  | Property    | Type   | Default | Description                     |
  | ----------- | ------ | ------- | ------------------------------- |
  | `content`   | string | `''`    | Markdown content to render      |
  | `className` | string | `''`    | Additional Tailwind CSS classes |

  ## Supported Markdown Features [#supported-markdown-features]

  ### Headers [#headers]

  ```markdown
  # H1 Header
  ## H2 Header
  ### H3 Header
  #### H4 Header
  ##### H5 Header
  ###### H6 Header
  ```

  ### Text Formatting [#text-formatting]

  ```markdown
  **Bold text**
  *Italic text*
  ~~Strikethrough~~
  `Inline code`
  ```

  ### Links and Images [#links-and-images]

  ```markdown
  [Link text](https://example.com)
  ![Alt text](https://example.com/image.jpg)
  ```

  ### Lists [#lists]

  ```markdown
  - Unordered item 1
  - Unordered item 2
    - Nested item

  1. Ordered item 1
  2. Ordered item 2
     1. Nested ordered item
  ```

  ### Task Lists [#task-lists]

  ```markdown
  - [x] Completed task
  - [ ] Incomplete task
  - [ ] Another task
  ```

  ### Tables [#tables]

  ```markdown
  | Column 1 | Column 2 | Column 3 |
  |----------|----------|----------|
  | Cell 1   | Cell 2   | Cell 3   |
  | Cell 4   | Cell 5   | Cell 6   |
  ```

  ### Code Blocks [#code-blocks]

  ````markdown
  ```javascript
  function hello() {
    console.log("Hello, World!");
  }
  ```
  ````

  ### Blockquotes [#blockquotes]

  ```markdown
  > This is a blockquote
  > It can span multiple lines
  ```

  ### Horizontal Rules [#horizontal-rules]

  ```markdown
  ---
  ***
  ___
  ```

  ## Examples [#examples]

  ### Documentation Page [#documentation-page]

  ```tsx
  const docSchema = {
    type: 'markdown',
    content: `
  # Getting Started

  Welcome to our documentation!

  ## Installation

  Install the package using npm:

  \`\`\`bash
  npm install our-package
  \`\`\`

  ## Quick Start

  1. Import the package
  2. Configure your settings
  3. Start building!

  For more information, see the [API Reference](/docs/api/schema-reference).
    `,
    className: 'prose prose-lg max-w-none'
  }
  ```

  ### README Viewer [#readme-viewer]

  ```tsx
  const readmeSchema = {
    type: 'markdown',
    content: `
  # Project Name

  [![Build Status](https://img.shields.io/badge/build-passing-brightgreen.svg)]()

  A brief description of the project.

  ## Features

  - ✅ Feature 1
  - ✅ Feature 2
  - ✅ Feature 3

  ## Installation

  \`\`\`bash
  npm install project-name
  \`\`\`

  ## Usage

  \`\`\`javascript
  import { Component } from 'project-name'

  const app = new Component()
  app.run()
  \`\`\`

  ## Contributing

  Contributions are welcome! Please read our [contributing guidelines](https://github.com/objectstack-ai/objectui/blob/main/CONTRIBUTING.md).

  ## License

  MIT
    `,
    className: 'prose dark:prose-invert'
  }
  ```

  ### Release Notes [#release-notes]

  ```tsx
  const releaseNotes = {
    type: 'markdown',
    content: `
  # Release Notes - v2.5.0

  ## 🎉 New Features

  - Added dark mode support
  - Improved performance by 40%
  - New dashboard components

  ## 🐛 Bug Fixes

  - Fixed login redirect issue (#123)
  - Resolved memory leak in table component (#456)

  ## 🔄 Changes

  - Updated dependencies
  - Improved documentation
  - Refactored authentication flow

  ## ⚠️ Breaking Changes

  - Removed deprecated \`oldAPI\` method
  - Changed config file format from JSON to YAML

  ## 📦 Dependencies

  | Package | Old Version | New Version |
  |---------|------------|-------------|
  | react   | 18.2.0     | 18.3.0      |
  | vite    | 4.5.0      | 5.0.0       |
    `
  }
  ```

  ### API Documentation [#api-documentation]

  ```tsx
  const apiDocs = {
    type: 'markdown',
    content: `
  # API Reference

  ## Methods

  ### \`getData(id: string): Promise<Data>\`

  Fetches data by ID.

  **Parameters:**
  - \`id\` (string) - The unique identifier

  **Returns:**
  - Promise resolving to Data object

  **Example:**
  \`\`\`typescript
  const data = await getData('user-123')
  console.log(data.name)
  \`\`\`

  ### \`updateData(id: string, updates: Partial<Data>): Promise<void>\`

  Updates existing data.

  **Parameters:**
  - \`id\` (string) - The unique identifier
  - \`updates\` (Partial<Data>) - Fields to update

  **Example:**
  \`\`\`typescript
  await updateData('user-123', { name: 'John Doe' })
  \`\`\`
    `
  }
  ```

  ## Styling with Tailwind [#styling-with-tailwind]

  Use Tailwind Typography plugin for better markdown styling:

  ```tsx
  const schema = {
    type: 'markdown',
    content: '# My Document\n\nContent here...',
    className: 'prose prose-lg prose-slate dark:prose-invert max-w-none'
  }
  ```

  Common prose classes:

  * `prose` - Base typography styles
  * `prose-sm` / `prose-lg` / `prose-xl` - Size variants
  * `prose-slate` / `prose-gray` - Color schemes
  * `dark:prose-invert` - Dark mode support
  * `max-w-none` - Remove max-width constraint

  ## Security (XSS Protection) [#security-xss-protection]

  All markdown content is automatically sanitized using `rehype-sanitize` to prevent XSS attacks:

  ```tsx
  // Safe - HTML tags are sanitized
  const schema = {
    type: 'markdown',
    content: '**Safe** markdown with <script>alert("XSS")</script>'
  }
  // The script tag will be removed in the output
  ```

  ## Bundle Size [#bundle-size]

  The plugin uses lazy loading to optimize bundle size:

  * **Initial load**: \~0.2 KB (entry point)
  * **Lazy chunk**: \~100-200 KB (loaded when markdown is rendered)
  * **Includes react-markdown and plugins**

  ## TypeScript Support [#typescript-support]

  ```plaintext
  import type { MarkdownSchema } from '@object-ui/plugin-markdown'

  const markdownSchema: MarkdownSchema = {
    type: 'markdown',
    content: '# Hello TypeScript!'
  }
  ```

  ## Related Documentation [#related-documentation]

  * [Plugin System Overview](/docs/guide/plugins)
  * [Lazy-Loaded Plugins Architecture](../concepts/lazy-loading)
  * [Package README](https://github.com/objectstack-ai/objectui/tree/main/packages/plugin-markdown)
</PluginLoader>


# Plugin Report



# @object-ui/plugin-report [#object-uiplugin-report]

Spec-driven report engine for Object UI. Renders the four report variants
defined by `@objectstack/spec` (`tabular` / `summary` / `matrix` / `joined`)
on top of any `objectName`, with server-side aggregation, multi-level
grouping, date bucketing, cell drill-down and printable export.

## Installation [#installation]

```bash
pnpm add @object-ui/plugin-report
```

## At a glance [#at-a-glance]

| Variant   | What it shows                                     | Renderer               |
| --------- | ------------------------------------------------- | ---------------------- |
| `tabular` | Flat rows, one per record                         | `SpecReportGrid`       |
| `summary` | Grouped rows + aggregates (single axis)           | `SpecReportGrid`       |
| `matrix`  | Pivot table — rows × columns + cell aggregates    | `MatrixRenderer`       |
| `joined`  | Vertically stacked sub-reports (independent data) | `JoinedReportRenderer` |

All four are dispatched by a single `<ReportRenderer schema={...}>` based
on `schema.type`. The same schema can also be embedded via the JSON
component registry as `{ "type": "spec-report", "report": { ... } }` —
the dispatcher unwraps either shape automatically.

## Quick start [#quick-start]

```ts
import type { ReportInput } from '@objectstack/spec/ui';

export const OpportunitiesByStage: ReportInput = {
  name: 'opp_by_stage',
  label: 'Opportunities by Stage',
  objectName: 'opportunity',
  type: 'summary',
  columns: [
    { field: 'stage',  label: 'Stage' },
    { field: 'amount', label: 'Amount', aggregate: 'sum' },
    { field: 'id',     label: 'Deals',  aggregate: 'count' },
  ],
  groupingsDown: [{ field: 'stage', sortOrder: 'asc' }],
};
```

```tsx
import { ReportRenderer } from '@object-ui/plugin-report';
<ReportRenderer schema={OpportunitiesByStage} dataSource={ds} />
```

## Matrix reports (row × column pivot) [#matrix-reports-row--column-pivot]

A `matrix` report adds `groupingsAcross` to create columns. Combined with
`dateGranularity`, you get classic period pivots without writing any SQL:

```ts
export const PipelineByQuarter: ReportInput = {
  name: 'pipeline_coverage_by_quarter',
  objectName: 'opportunity',
  type: 'matrix',
  columns: [{ field: 'amount', label: 'Pipeline', aggregate: 'sum' }],
  groupingsDown:   [{ field: 'forecast_category', sortOrder: 'asc' }],
  groupingsAcross: [{ field: 'close_date', dateGranularity: 'quarter', sortOrder: 'asc' }],
};
```

Supported `dateGranularity` values: `day` / `week` / `month` / `quarter` /
`year`. The plugin routes these to the server-side aggregator via
`POST /api/v1/data/:object/query` (spec `{ groupBy, aggregations }`
shape). When the server can't natively bucket a granularity, the engine
falls back to in-memory `applyInMemoryAggregation()` — fully transparent
to the report author.

`MatrixRenderer` renders row totals, column totals and grand total
automatically and makes every cell click-drillable.

## Joined reports (M3) [#joined-reports-m3]

A `joined` report stacks N independent sub-reports vertically — perfect
for early-warning dashboards where each panel asks a different question
about different data:

```ts
export const CustomerChurnSignals: ReportInput = {
  name: 'customer_churn_signals',
  label: 'Customer Churn Signals',
  objectName: 'account',          // container default
  type: 'joined',
  columns: [],                    // intentionally empty at container level
  blocks: [
    {
      name: 'at_risk_accounts',
      label: 'At-Risk Accounts',
      type: 'summary',
      objectName: 'account',
      columns: [{ field: 'id', label: 'Accounts', aggregate: 'count' }],
      groupingsDown: [{ field: 'industry', sortOrder: 'asc' }],
      filter: { is_active: true, last_activity_date: { $lt: '2026-04-19' } },
    },
    {
      name: 'recently_lost',
      label: 'Recently Lost Opportunities',
      type: 'summary',
      objectName: 'opportunity',  // different object than container — OK
      columns: [
        { field: 'amount', label: 'Lost Revenue', aggregate: 'sum' },
        { field: 'id',     label: 'Deals',        aggregate: 'count' },
      ],
      groupingsDown: [{ field: 'owner', sortOrder: 'asc' }],
      filter: { stage: 'closed_lost', close_date: { $gte: '2026-04-19' } },
    },
  ],
};
```

Block inheritance rules:

* `objectName` falls back to the container's if a block omits it.
* `filter` is ANDed with the container's filter (block keys win on
  collision).
* Each block runs its own `useReportData()` call — failures are
  isolated to that block.
* `block.type` may be `tabular` / `summary` / `matrix` but **not**
  `joined` (no recursive composition).

## Drill-down [#drill-down]

Every aggregated row / cell is drill-aware. When the user clicks a cell,
the renderer dispatches a `drill` action (built by `buildDrillAction`)
through the host's `ActionRunner`. The default handler opens the
underlying records:

```tsx
import { registerDrillHandler } from '@object-ui/plugin-report';
registerDrillHandler(actionRunner, { navigate: router.push });
```

Two drill targets are supported:

1. **List view** (default): navigates to `/console/apps/<app>/<object>?filter=...`
2. **Report drawer** (M3): if the calling widget (e.g., a Dashboard
   pivot) declares `drillDown.report`, the click opens a side drawer
   that renders that report with the cell's group key merged into its
   filter — composing **dashboard → report → record** in three clicks.

## Server-side aggregation (M3) [#server-side-aggregation-m3]

`useReportData()` translates a `Report` into a spec `QueryAST`
(`{ groupBy, aggregations, where, limit }`) and posts it to
`POST /api/v1/data/:object/query`. The framework routes the request
through `engine.aggregate()`, which **pushes structured `groupBy`
entries** (`{ field, dateGranularity }`) down to the driver as native
SQL date functions:

| Dialect    | `day` / `month` / `quarter` / `year`   | `week` (ISO-8601)               |
| ---------- | -------------------------------------- | ------------------------------- |
| PostgreSQL | `to_char(... AT TIME ZONE 'UTC', ...)` | ✅ `IYYY-"W"IW`                  |
| MySQL      | `date_format(convert_tz(...), ...)`    | ✅ `%x-W%v`                      |
| SQLite     | `strftime(...)`                        | ⚠️ in-memory fallback (no `%V`) |

The driver advertises per-granularity support via
`supports.queryDateGranularity`. When a granularity isn't supported by
the current dialect (notably `week` on SQLite), the engine transparently
falls back to fetching raw rows and bucketing in-memory with
`bucketDateValue()` — the resulting group key strings are
**byte-for-byte identical** so drill filters compose without drift.

If the endpoint is unavailable or returns an error, the hook
**transparently degrades** to `dataSource.find()` + client-side
aggregation. No application code changes required.

## Filter-time date helpers (current limitation) [#filter-time-date-helpers-current-limitation]

> ⚠️ &#x2A;*Heads-up:** the server does **not** currently evaluate
> ``cel`...` `` expressions embedded inside filter values (e.g.
> ``{ close_date: { $gte: cel`daysAgo(30)` } }``). The unevaluated
> template object reaches the SQL driver and triggers
> `SQLite3 can only bind numbers, strings, bigints, buffers, and null`.

**Workaround pattern** (used by the bundled CRM `customer_churn_signals`
demo): compute concrete ISO date strings at module load time and treat
the report as a snapshot of "now".

```ts
// Module-load helper. Re-evaluates each time the app boots.
const daysAgo = (n: number): string => {
  const d = new Date();
  d.setUTCDate(d.getUTCDate() - n);
  return d.toISOString().slice(0, 10); // 'YYYY-MM-DD'
};

filter: {
  is_active: true,
  last_activity_date: { $lt: daysAgo(60) },
}
```

For long-lived processes that need a sliding window, recompute the
report on each page render (the hook re-runs on filter change) or wrap
the date helper in a `useMemo` keyed on a 1-hour bucket.

Native CEL filter-time evaluation is tracked for a future major version
alongside server-side schedule execution.

## Type-aware cell rendering [#type-aware-cell-rendering]

Report cells use the shared `getCellRenderer` registry from
`@object-ui/fields`, the same renderer used by `ObjectGrid` and list
views. Each column gets the right component for its type —
`select` becomes a coloured `Badge`, `lookup` becomes a deep link,
`boolean` becomes ✓/✗, `email`/`url`/`phone` become `mailto:`/external/
`tel:` links, `image` becomes a thumbnail, and so on.

When a report binds an `objectName`, columns auto-hydrate `type`,
`options`, `referenceTo`, and `label` from the underlying object so
authors don't need to duplicate field metadata. Per-column overrides
always win.

```ts
{
  name: 'contacts_by_account',
  objectName: 'contact',
  columns: [
    { field: 'email' },       // mailto: link
    { field: 'phone' },       // tel: link
    { field: 'is_primary' },  // ✓/✗
    { field: 'status' },      // Badge with option color
    { field: 'account' },     // Linked account record
  ],
}
```

## Schema-driven embedding [#schema-driven-embedding]

Components auto-register with `ComponentRegistry` on import. To embed a
report inside any JSON schema tree:

```json
{
  "type": "spec-report",
  "report": {
    "name": "opp_by_stage",
    "objectName": "opportunity",
    "type": "summary",
    "columns": [{ "field": "amount", "aggregate": "sum" }],
    "groupingsDown": [{ "field": "stage" }]
  }
}
```

The dispatcher unwraps `{type:'spec-report', report:{...}}` and routes
the inner `type` (`summary`/`matrix`/`joined`) to the correct renderer.
Passing the report as the top-level schema also works:

```json
{ "type": "summary", "name": "...", "objectName": "...", "columns": [...] }
```

## Further reading [#further-reading]

* 📦 [`@object-ui/plugin-report` on npm](https://www.npmjs.com/package/@object-ui/plugin-report)
* 📝 [Package README](https://github.com/objectstack-ai/objectui/tree/main/packages/plugin-report)
* 🐛 [Report an issue](https://github.com/objectstack-ai/objectui/issues)


# Plugin Timeline





Timeline component with vertical, horizontal, and Gantt-style layouts for displaying events and project timelines.

## Installation [#installation]

```bash
npm install @object-ui/plugin-timeline
```

<PluginLoader plugins="['timeline']">
  ## Interactive Examples [#interactive-examples]

  ### Vertical Timeline [#vertical-timeline]

  <SchemaExample id="plugin-timeline/vertical-timeline" />

  ### Horizontal Timeline [#horizontal-timeline]

  <SchemaExample id="plugin-timeline/horizontal-timeline" />

  ### Gantt-Style Timeline [#gantt-style-timeline]

  <SchemaExample id="plugin-timeline/gantt-style-timeline" />

  ## Usage [#usage]

  ### Basic Usage [#basic-usage]

  ```tsx
  // Import once in your app entry point
  import '@object-ui/plugin-timeline'

  // Use in schemas - Vertical Timeline
  const schema = {
    type: 'timeline',
    variant: 'vertical',
    items: [
      {
        time: '2024-01-15',
        title: 'Project Started',
        description: 'Kickoff meeting',
        variant: 'success'
      }
    ]
  }
  ```

  ## Features [#features]

  * **Three Layout Variants**: Vertical, horizontal, and Gantt-style layouts
  * **Customizable Markers**: Color-coded markers with icon support
  * **Date Formatting**: Multiple date format options
  * **Gantt Charts**: Project timeline visualization with task bars
  * **Time Scales**: Day, week, or month scales for Gantt view
  * **Lightweight**: Pure CSS and React components

  ## Schema API [#schema-api]

  ### Timeline Schema [#timeline-schema]

  ```plaintext
  {
    type: 'timeline',
    variant?: 'vertical' | 'horizontal' | 'gantt',
    items?: TimelineItem[],
    dateFormat?: 'short' | 'long' | 'iso',
    // Gantt-specific
    timeScale?: 'day' | 'week' | 'month',
    rowLabel?: string,
    minDate?: string,
    maxDate?: string,
    className?: string
  }
  ```

  ### Timeline Item (Vertical/Horizontal) [#timeline-item-verticalhorizontal]

  ```plaintext
  {
    time: string,              // ISO date string
    title: string,
    description?: string,
    variant?: 'default' | 'success' | 'warning' | 'danger' | 'info',
    icon?: string,            // Emoji or text
    content?: SchemaNode,     // Custom React content
    className?: string
  }
  ```

  ### Gantt Item [#gantt-item]

  ```plaintext
  {
    label: string,            // Row label
    items: Array<{
      title: string,
      startDate: string,      // ISO date string
      endDate: string,        // ISO date string
      variant?: 'default' | 'success' | 'warning' | 'danger' | 'info'
    }>
  }
  ```

  ## Properties [#properties]

  | Property     | Type   | Default      | Description                                     |
  | ------------ | ------ | ------------ | ----------------------------------------------- |
  | `variant`    | string | `'vertical'` | Timeline layout: vertical, horizontal, or gantt |
  | `items`      | array  | `[]`         | Array of timeline items                         |
  | `dateFormat` | string | `'short'`    | Date formatting: short, long, or iso            |
  | `timeScale`  | string | `'month'`    | Gantt time scale: day, week, or month           |
  | `rowLabel`   | string | `'Items'`    | Label for Gantt rows                            |
  | `minDate`    | string | auto         | Override min date for Gantt (YYYY-MM-DD)        |
  | `maxDate`    | string | auto         | Override max date for Gantt (YYYY-MM-DD)        |
  | `className`  | string | `''`         | Additional Tailwind CSS classes                 |

  ## Variants [#variants]

  ### Marker Variants [#marker-variants]

  Available marker/bar colors:

  * `default` - Gray
  * `success` - Green
  * `info` - Blue
  * `warning` - Yellow
  * `danger` - Red

  ```tsx
  const item = {
    time: '2024-01-15',
    title: 'Important Milestone',
    variant: 'success'  // Green marker
  }
  ```

  ## Examples [#examples]

  ### Product Roadmap [#product-roadmap]

  ```tsx
  const roadmap = {
    type: 'timeline',
    variant: 'horizontal',
    dateFormat: 'long',
    items: [
      {
        time: '2024-01-01',
        title: 'Alpha Release',
        description: 'Internal testing phase',
        variant: 'info',
        icon: '🔬'
      },
      {
        time: '2024-03-01',
        title: 'Beta Launch',
        description: 'Limited public beta',
        variant: 'warning',
        icon: '🚀'
      },
      {
        time: '2024-06-01',
        title: 'Public Launch',
        description: 'General availability',
        variant: 'success',
        icon: '🎉'
      }
    ]
  }
  ```

  ### Project Schedule (Gantt) [#project-schedule-gantt]

  ```tsx
  const schedule = {
    type: 'timeline',
    variant: 'gantt',
    timeScale: 'week',
    rowLabel: 'Teams',
    items: [
      {
        label: 'Design Team',
        items: [
          {
            title: 'Wireframes',
            startDate: '2024-01-01',
            endDate: '2024-01-14',
            variant: 'info'
          },
          {
            title: 'Mockups',
            startDate: '2024-01-15',
            endDate: '2024-02-01',
            variant: 'success'
          }
        ]
      },
      {
        label: 'Engineering',
        items: [
          {
            title: 'Development',
            startDate: '2024-02-01',
            endDate: '2024-03-31',
            variant: 'warning'
          }
        ]
      }
    ]
  }
  ```

  ### Company History [#company-history]

  ```tsx
  const history = {
    type: 'timeline',
    variant: 'vertical',
    dateFormat: 'long',
    items: [
      {
        time: '2020-01-01',
        title: 'Company Founded',
        description: 'Started in a garage with 2 founders',
        variant: 'success',
        icon: '🏢'
      },
      {
        time: '2021-06-01',
        title: 'Series A Funding',
        description: 'Raised $5M from VCs',
        variant: 'info',
        icon: '💰'
      },
      {
        time: '2022-12-01',
        title: '10,000 Customers',
        description: 'Reached major milestone',
        variant: 'success',
        icon: '🎯'
      },
      {
        time: '2024-01-01',
        title: 'Series B Funding',
        description: 'Raised $20M to expand globally',
        variant: 'warning',
        icon: '🌍'
      }
    ]
  }
  ```

  ## Date Formatting [#date-formatting]

  The timeline component supports three date formats:

  ```tsx
  // Short format: "1/15/2024"
  { dateFormat: 'short' }

  // Long format: "January 15, 2024"
  { dateFormat: 'long' }

  // ISO format: "2024-01-15"
  { dateFormat: 'iso' }
  ```

  ## Time Scales (Gantt) [#time-scales-gantt]

  For Gantt-style timelines, choose the appropriate time scale:

  ```tsx
  // Day scale - for short projects
  { timeScale: 'day' }

  // Week scale - for medium projects
  { timeScale: 'week' }

  // Month scale - for long projects
  { timeScale: 'month' }
  ```

  ## Customization [#customization]

  ### Custom Icons [#custom-icons]

  ```tsx
  const item = {
    time: '2024-01-15',
    title: 'Milestone',
    icon: '🎯',  // Any emoji or short text
    variant: 'success'
  }
  ```

  ### Custom Colors [#custom-colors]

  Use Tailwind CSS classes for additional styling:

  ```tsx
  const schema = {
    type: 'timeline',
    variant: 'vertical',
    className: 'max-w-4xl mx-auto',
    items: [...]
  }
  ```

  ## TypeScript Support [#typescript-support]

  ```plaintext
  import type { TimelineSchema } from '@object-ui/types'

  const timelineSchema: TimelineSchema = {
    type: 'timeline',
    variant: 'vertical',
    items: [
      {
        time: '2024-01-15',
        title: 'Event',
        description: 'Description',
        variant: 'success'
      }
    ]
  }
  ```

  ## Related Documentation [#related-documentation]

  * [Plugin System Overview](/docs/guide/plugins)
  * [Package README](https://github.com/objectstack-ai/objectui/tree/main/packages/plugin-timeline)
</PluginLoader>


# Plugin View





Unified view component for ObjectQL objects with automatic form and grid generation.

## Installation [#installation]

```bash
npm install @object-ui/plugin-view
```

<PluginLoader plugins="['view']">
  ## Interactive Examples [#interactive-examples]

  ### User Directory View [#user-directory-view]

  <SchemaExample id="plugin-view/grid-view-mode" />

  ### Record Detail View [#record-detail-view]

  <SchemaExample id="plugin-view/detail-view-mode" />

  ### Form Create View [#form-create-view]

  <SchemaExample id="plugin-view/form-view-mode" />

  ## Features [#features]

  * **Automatic Views** - Generate views from ObjectQL schemas
  * **Form Generation** - Auto-generate forms from object definitions
  * **Grid Generation** - Auto-generate data grids
  * **CRUD Operations** - Built-in create, read, update, delete
  * **Field Mapping** - Automatic field type detection
  * **ObjectQL Integration** - Native ObjectStack support

  ## Schema API [#schema-api]

  ### ObjectView [#objectview]

  ```plaintext
  {
    type: 'object-view',
    object: string,                 // ObjectQL object name
    viewMode?: 'grid' | 'form' | 'detail',
    fields?: string[],              // Fields to display
    dataSource?: DataSource,
    onCreate?: (data) => void,
    onUpdate?: (id, data) => void,
    onDelete?: (id) => void,
    className?: string
  }
  ```

  ## Usage [#usage]

  ### Auto-registration (Side-effect Import) [#auto-registration-side-effect-import]

  ```plaintext
  import '@object-ui/plugin-view';
  ```

  ### Manual Registration [#manual-registration]

  ```plaintext
  import { viewComponents } from '@object-ui/plugin-view';
  import { ComponentRegistry } from '@object-ui/core';

  Object.entries(viewComponents).forEach(([type, component]) => {
    ComponentRegistry.register(type, component);
  });
  ```

  ## Examples [#examples]

  ### Grid View [#grid-view]

  Display objects in a data grid:

  ```json
  {
    "type": "object-view",
    "object": "users",
    "viewMode": "grid",
    "fields": ["name", "email", "role", "created_at"]
  }
  ```

  ### Form View [#form-view]

  Create or edit objects with a form:

  ```json
  {
    "type": "object-view",
    "object": "users",
    "viewMode": "form",
    "mode": "create",
    "fields": ["name", "email", "role"]
  }
  ```

  ### Detail View [#detail-view]

  Display a single object's details:

  ```json
  {
    "type": "object-view",
    "object": "users",
    "viewMode": "detail",
    "recordId": "123",
    "fields": ["name", "email", "role", "bio", "created_at"]
  }
  ```

  ## CRUD Operations [#crud-operations]

  ### Create [#create]

  ```json
  {
    "type": "object-view",
    "object": "products",
    "viewMode": "form",
    "mode": "create"
  }
  ```

  ### Read/List [#readlist]

  ```json
  {
    "type": "object-view",
    "object": "products",
    "viewMode": "grid",
    "pagination": true,
    "searchable": true,
    "filters": {
      "category": "electronics"
    }
  }
  ```

  ### Update [#update]

  ```json
  {
    "type": "object-view",
    "object": "products",
    "viewMode": "form",
    "mode": "edit",
    "recordId": "123"
  }
  ```

  ### Delete [#delete]

  ```json
  {
    "type": "object-view",
    "object": "products",
    "viewMode": "grid",
    "enableDelete": true
  }
  ```

  ## Field Configuration [#field-configuration]

  Customize field display and behavior:

  ```json
  {
    "type": "object-view",
    "object": "users",
    "viewMode": "form",
    "fieldConfig": {
      "name": {
        "label": "Full Name",
        "required": true,
        "placeholder": "Enter name"
      },
      "email": {
        "label": "Email Address",
        "type": "email",
        "required": true
      },
      "role": {
        "label": "User Role",
        "type": "select",
        "options": [
          { "label": "Admin", "value": "admin" },
          { "label": "User", "value": "user" }
        ]
      }
    }
  }
  ```

  ## Advanced Features [#advanced-features]

  ### Nested Objects [#nested-objects]

  ```json
  {
    "type": "object-view",
    "object": "orders",
    "viewMode": "detail",
    "fields": ["order_number", "customer.name", "items", "total"],
    "nestedFields": {
      "items": {
        "type": "object-grid",
        "object": "order_items",
        "fields": ["product.name", "quantity", "price"]
      }
    }
  }
  ```

  ### Tabs View [#tabs-view]

  ```json
  {
    "type": "object-view",
    "object": "users",
    "viewMode": "tabs",
    "tabs": [
      { "label": "Details", "fields": ["name", "email", "bio"] },
      { "label": "Settings", "fields": ["theme", "notifications", "timezone"] },
      { "label": "Activity", "type": "object-grid", "object": "user_activities" }
    ]
  }
  ```

  ## Integration with ObjectQL [#integration-with-objectql]

  ```plaintext
  import { createObjectStackAdapter } from '@object-ui/data-objectstack';

  const dataSource = createObjectStackAdapter({
    baseUrl: 'https://api.example.com',
    token: 'your-auth-token'
  });

  const schema = {
    type: 'object-view',
    object: 'contacts',
    viewMode: 'grid',
    dataSource,
    fields: ['first_name', 'last_name', 'email', 'company'],
    searchable: true,
    sortable: true
  };
  ```

  ## TypeScript Support [#typescript-support]

  ```plaintext
  import type { ObjectViewSchema } from '@object-ui/plugin-view';

  const userView: ObjectViewSchema = {
    type: 'object-view',
    object: 'users',
    viewMode: 'grid',
    fields: ['name', 'email', 'role']
  };
  ```

  ## License [#license]

  MIT
</PluginLoader>


# Button Group





The Button Group component groups multiple buttons together with consistent styling.

## Basic Usage [#basic-usage]

<SchemaExample id="components-basic-button-group/basic-button-group" />

## Variants [#variants]

<DemoGrid>
  <SchemaExample id="components-basic-button-group/outline-variant" />

  <SchemaExample id="components-basic-button-group/with-icons" />
</DemoGrid>

## Selection Mode [#selection-mode]

<DemoGrid>
  <SchemaExample id="components-basic-button-group/single-selection" />

  <SchemaExample id="components-basic-button-group/multiple-selection" />
</DemoGrid>

## Schema [#schema]

```plaintext
interface ButtonGroupButton {
  label?: string;
  value: string;
  icon?: string;
  disabled?: boolean;
}

interface ButtonGroupSchema {
  type: 'button-group';
  buttons: ButtonGroupButton[];   // Button definitions
  value?: string | string[];      // Selected value(s)
  selectionMode?: 'single' | 'multiple' | 'none';
  variant?: 'default' | 'outline' | 'ghost';
  size?: 'sm' | 'default' | 'lg';
  
  // Events
  onValueChange?: string | ActionConfig;
  
  // States
  disabled?: boolean;
  
  // Styling
  className?: string;
}
```

## Examples [#examples]

### Toolbar Actions [#toolbar-actions]

<SchemaExample id="components-basic-button-group/icon-toolbar" />


# Div (Deprecated)





<div className="rounded-lg border border-yellow-500/50 bg-yellow-50 p-4 dark:bg-yellow-950/50">
  <p className="font-semibold text-yellow-800 dark:text-yellow-200">
    ⚠️ Deprecated Component
  </p>

  <p className="mt-2 text-sm text-yellow-700 dark:text-yellow-300">
    The Div component is deprecated. Please use Shadcn components instead:
  </p>

  <ul className="mt-2 list-inside list-disc text-sm text-yellow-700 dark:text-yellow-300">
    <li>
      For containers: use 

      <code>card</code>

      , 

      <code>flex</code>

      , or semantic layout components
    </li>

    <li>
      For simple wrappers: use layout components like 

      <code>container</code>

      , 

      <code>stack</code>

      , or 

      <code>grid</code>
    </li>
  </ul>
</div>

The Div component is a generic container element. **It is now deprecated in favor of semantic Shadcn-based components** that provide better accessibility, consistency, and design system integration.

## Migration Guide [#migration-guide]

Instead of using `div`, use these Shadcn alternatives:

### For Card-like Containers → Use `card` [#for-card-like-containers--use-card]

<SchemaExample id="components-basic-div/use-card-instead" />

### For Flex Layouts → Use `flex` [#for-flex-layouts--use-flex]

<SchemaExample id="components-basic-div/flex-layout" />

### For Grid Layouts → Use `grid` [#for-grid-layouts--use-grid]

<SchemaExample id="components-basic-div/grid-layout" />

## Old Examples (Deprecated) [#old-examples-deprecated]

Below are the old `div` examples. Please migrate to the alternatives shown above.

## Schema [#schema]

```plaintext
// ⚠️ DEPRECATED - Use Card, Flex, Grid, or other layout components instead
interface DivSchema {
  type: 'div';
  
  // Content
  children?: SchemaNode | SchemaNode[];  // Child components
  body?: SchemaNode[];                    // Alternative content prop
  
  // Styling
  className?: string;                     // Tailwind CSS classes
  
  // Base properties
  id?: string;
  visible?: boolean | string;
  testId?: string;
}
```

## Legacy Examples (For Reference Only) [#legacy-examples-for-reference-only]

### Old Card Layout Example [#old-card-layout-example]

<SchemaExample id="components-basic-div/custom-card" />

### Nested Containers [#nested-containers]

<SchemaExample id="components-basic-div/nested-divs" />


# HTML





## Examples [#examples]

<SchemaExample id="components-basic-html/basic-html" />

## Schema [#schema]

```plaintext
interface HtmlSchema {
  type: 'html';
  html: string;
}
```


# Icon





## Examples [#examples]

<SchemaExample id="components-basic-icon/basic-icon" />

<SchemaExample id="components-basic-icon/icon-sizes" />

<SchemaExample id="components-basic-icon/colored-icons" />

## Schema [#schema]

```plaintext
interface IconSchema {
  type: 'icon';
  name: string;              // Lucide icon name (kebab-case)
  size?: number | 'sm' | 'md' | 'lg' | 'xl';
  color?: string;            // Tailwind color class
  className?: string;
}
```


# Image





## Examples [#examples]

<SchemaExample id="components-basic-image/basic-image" />

<SchemaExample id="components-basic-image/with-sizing" />

## Schema [#schema]

```plaintext
interface ImageSchema {
  type: 'image';
  src: string;
  alt?: string;
  width?: number | string;
  height?: number | string;
  fallback?: string;
  fit?: 'contain' | 'cover' | 'fill' | 'none' | 'scale-down';
}
```


# Navigation Menu





The Navigation Menu component provides an accessible menu for site navigation.

## Basic Usage [#basic-usage]

<SchemaExample id="components-basic-navigation-menu/site-navigation" />

## With Descriptions [#with-descriptions]

<SchemaExample id="components-basic-navigation-menu/documentation-nav" />

## Schema [#schema]

```plaintext
interface NavigationMenuItem {
  label: string;
  href?: string;
  description?: string;
  icon?: string;
  items?: NavigationMenuItem[];   // Submenu items
}

interface NavigationMenuSchema {
  type: 'navigation-menu';
  items: NavigationMenuItem[];    // Menu items
  className?: string;
}
```


# Pagination





The Pagination component allows users to navigate through pages of data.

## Basic Usage [#basic-usage]

<SchemaExample id="components-basic-pagination/basic-pagination" />

## With Page Size [#with-page-size]

<SchemaExample id="components-basic-pagination/with-item-count" />

## Schema [#schema]

```plaintext
interface PaginationSchema {
  type: 'pagination';
  currentPage: number;            // Current page (1-based)
  totalPages: number;             // Total number of pages
  pageSize?: number;              // Items per page
  totalItems?: number;            // Total number of items
  
  // Events
  onPageChange?: string | ActionConfig;
  
  // Styling
  className?: string;
}
```


# Separator





## Examples [#examples]

<SchemaExample id="components-basic-separator/horizontal" />

<SchemaExample id="components-basic-separator/vertical" />

## Schema [#schema]

```plaintext
interface SeparatorSchema {
  type: 'separator';
  orientation?: 'horizontal' | 'vertical';
  className?: string;
}
```


# Sidebar





The Sidebar component provides a collapsible navigation sidebar for applications.

## Basic Usage [#basic-usage]

<SchemaExample id="components-basic-sidebar/basic-sidebar" />

## With Groups [#with-groups]

<SchemaExample id="components-basic-sidebar/grouped-sidebar" />

## Collapsible [#collapsible]

<SchemaExample id="components-basic-sidebar/collapsible-sidebar" />

## Schema [#schema]

```plaintext
interface SidebarItem {
  label: string;
  icon?: string;
  href?: string;
  active?: boolean;
  badge?: string | number;
}

interface SidebarGroup {
  title?: string;
  items: SidebarItem[];
}

interface SidebarSchema {
  type: 'sidebar';
  items?: SidebarItem[];          // Flat list of items
  groups?: SidebarGroup[];        // Grouped items
  collapsible?: boolean;          // Allow collapse
  defaultCollapsed?: boolean;     // Initial state
  
  // Styling
  className?: string;
}
```

## Examples [#examples]

### With Badges [#with-badges]

<SchemaExample id="components-basic-sidebar/sidebar-with-badges" />


# Span (Deprecated)





<div className="rounded-lg border border-yellow-500/50 bg-yellow-50 p-4 dark:bg-yellow-950/50">
  <p className="font-semibold text-yellow-800 dark:text-yellow-200">
    ⚠️ Deprecated Component
  </p>

  <p className="mt-2 text-sm text-yellow-700 dark:text-yellow-300">
    The Span component is deprecated. Please use Shadcn components instead:
  </p>

  <ul className="mt-2 list-inside list-disc text-sm text-yellow-700 dark:text-yellow-300">
    <li>
      For badges/labels: use 

      <code>badge</code>

       component
    </li>

    <li>
      For inline text emphasis: use 

      <code>text</code>

       component with appropriate className
    </li>
  </ul>
</div>

The Span component is an inline container. **It is now deprecated in favor of semantic Shadcn-based components** that provide better accessibility and design system integration.

## Migration Guide [#migration-guide]

Instead of using `span`, use these Shadcn alternatives:

### For Badges → Use `badge` [#for-badges--use-badge]

<DemoGrid>
  <SchemaExample id="components-basic-span/default-badge" />

  <SchemaExample id="components-basic-span/secondary-badge" />
</DemoGrid>

### For Status Indicators → Use `badge` with variants [#for-status-indicators--use-badge-with-variants]

<SchemaExample id="components-basic-span/status-badges" />

### For Inline Text → Use `text` with className [#for-inline-text--use-text-with-classname]

<SchemaExample id="components-basic-span/text-component" />

## Old Examples (Deprecated) [#old-examples-deprecated]

Below are the old `span` examples. Please migrate to the alternatives shown above.

## Schema [#schema]

```plaintext
// ⚠️ DEPRECATED - Use Badge or Text components instead
interface SpanSchema {
  type: 'span';
  
  // Content
  value?: string;                        // Text content
  children?: SchemaNode | SchemaNode[];  // Child components
  body?: SchemaNode | SchemaNode[];      // Alternative content prop
  
  // Styling
  className?: string;                    // Tailwind CSS classes
  
  // Base properties
  id?: string;
  visible?: boolean | string;
  testId?: string;
}
```

## Legacy Examples (For Reference Only) [#legacy-examples-for-reference-only]


# Text





The Text component displays text content with predefined typography variants.

## Basic Usage [#basic-usage]

<SchemaExample id="components-basic-text/simple-text" />

## Variants [#variants]

<DemoGrid>
  <SchemaExample id="components-basic-text/heading-1" />

  <SchemaExample id="components-basic-text/heading-2" />

  <SchemaExample id="components-basic-text/heading-3" />

  <SchemaExample id="components-basic-text/paragraph" />

  <SchemaExample id="components-basic-text/lead" />

  <SchemaExample id="components-basic-text/large" />

  <SchemaExample id="components-basic-text/small" />

  <SchemaExample id="components-basic-text/muted" />
</DemoGrid>

## Schema [#schema]

```plaintext
interface TextSchema {
  type: 'text';
  content: string;           // Text content to display
  value?: string;            // Alias for content
  variant?: 'h1' | 'h2' | 'h3' | 'h4' | 'p' | 'lead' | 'large' | 'small' | 'muted';
  align?: 'left' | 'center' | 'right' | 'justify';
  color?: string;            // Tailwind color class
  className?: string;        // Additional CSS classes
}
```

## Examples [#examples]

### Colored Text [#colored-text]

<SchemaExample id="components-basic-text/text-with-colors" />

### Text Alignment [#text-alignment]

<SchemaExample id="components-basic-text/text-alignment" />


# Carousel





The Carousel component displays content in a slideshow format with navigation controls.

## Basic Usage [#basic-usage]

<SchemaExample id="components-complex-carousel/simple-carousel" />

## Without Arrows [#without-arrows]

<SchemaExample id="components-complex-carousel/no-arrows" />

## Schema [#schema]

```plaintext
interface CarouselSchema {
  type: 'carousel';
  
  // Configuration
  orientation?: 'horizontal' | 'vertical';  // Carousel direction (default: 'horizontal')
  showArrows?: boolean;                     // Show navigation arrows (default: true)
  
  // Items
  items: SchemaNode[][];                    // Array of slides (each slide is an array of components)
  
  // Options
  opts?: {
    loop?: boolean;                         // Enable infinite loop
    align?: 'start' | 'center' | 'end';    // Slide alignment
  };
  
  // Styling
  className?: string;                       // Container CSS classes
  itemClassName?: string;                   // Individual slide CSS classes
  
  // Base properties
  id?: string;
  visible?: boolean | string;
  testId?: string;
}
```

## Examples [#examples]

### Image Gallery [#image-gallery]

<SchemaExample id="components-complex-carousel/photo-gallery" />

### Product Showcase [#product-showcase]

<SchemaExample id="components-complex-carousel/products" />

### Testimonials [#testimonials]

<SchemaExample id="components-complex-carousel/customer-reviews" />


# Data Table





The Data Table component provides comprehensive table functionality inspired by Airtable, including multi-column sorting, search, pagination, row selection, and export capabilities.

## Basic Usage [#basic-usage]

<SchemaExample id="components-complex-data-table/simple-table" />

## With All Features [#with-all-features]

<SchemaExample id="components-complex-data-table/full-featured-table" />

## Schema [#schema]

```plaintext
interface TableColumn {
  header: string;                        // Column header text
  accessorKey: string;                   // Data property key
  width?: string;                        // Column width (e.g., '100px', '20%')
  sortable?: boolean;                    // Enable sorting for this column
}

interface DataTableSchema {
  type: 'data-table';
  
  // Structure
  columns: TableColumn[];                // Column definitions
  data: Record<string, any>[];          // Table data
  caption?: string;                      // Table caption
  
  // Features
  pagination?: boolean;                  // Enable pagination (default: true)
  pageSize?: number;                     // Items per page (default: 10)
  searchable?: boolean;                  // Enable search (default: true)
  selectable?: boolean;                  // Enable row selection (default: false)
  sortable?: boolean;                    // Enable sorting (default: true)
  exportable?: boolean;                  // Enable CSV export (default: false)
  rowActions?: boolean;                  // Show edit/delete buttons (default: false)
  
  // Advanced features
  resizableColumns?: boolean;            // Allow column resizing (default: true)
  reorderableColumns?: boolean;          // Allow column reordering (default: true)
  
  // Styling
  className?: string;                    // Tailwind CSS classes
  
  // Base properties
  id?: string;
  visible?: boolean | string;
  testId?: string;
}
```

## Examples [#examples]

### Product Inventory [#product-inventory]

<SchemaExample id="components-complex-data-table/inventory-management" />

### User Management [#user-management]

<SchemaExample id="components-complex-data-table/user-table" />

### Sales Report [#sales-report]

<SchemaExample id="components-complex-data-table/sales-data" />

## Features [#features]

The Data Table component provides:

* **Sorting**: Click column headers to sort (ascending/descending/none)
* **Search**: Real-time search across all columns
* **Pagination**: Navigate through large datasets
* **Selection**: Select multiple rows with checkboxes
* **Export**: Download table data as CSV
* **Row Actions**: Built-in edit and delete buttons
* **Resizable Columns**: Drag column borders to resize
* **Column Reordering**: Drag columns to reorder


# Filter Builder





The Filter Builder component provides a visual interface for creating complex filter queries with support for nested conditions and multiple operators.

## Basic Usage [#basic-usage]

<SchemaExample id="components-complex-filter-builder/empty-filter-builder" />

## With Initial Conditions [#with-initial-conditions]

<SchemaExample id="components-complex-filter-builder/with-conditions" />

## Schema [#schema]

```plaintext
interface FilterField {
  value: string;                         // Field identifier
  label: string;                         // Display label
  type?:
    | 'text' | 'number' | 'currency' | 'percent' | 'rating'
    | 'date' | 'datetime' | 'time'
    | 'boolean'
    | 'select' | 'status'
    | 'lookup' | 'master_detail' | 'user' | 'owner'; // Field type
  options?: Array<{ value: string; label: string }>;  // Static options (select-like)
  // Lookup-like fields without `options` render a remote-search picker that
  // queries the configured DataSource. The metadata below describes how to
  // resolve and display referenced records:
  referenceTo?: string;                  // Referenced object name (e.g. "user")
  displayField?: string;                 // Display field on referenced object (default "name")
  idField?: string;                      // Id field on referenced object (default "id")
}

interface FilterCondition {
  id: string;                            // Condition identifier
  field: string;                         // Field to filter on
  operator: string;                      // Comparison operator
  value: any;                            // Filter value
}

interface FilterGroup {
  id: string;                            // Group identifier
  logic: 'and' | 'or';                  // Logic operator (AND/OR)
  conditions: (FilterCondition | FilterGroup)[];  // Conditions or nested groups
}

interface FilterBuilderSchema {
  type: 'filter-builder';
  
  // Required
  name: string;                          // Field name for form submission
  fields: FilterField[];                 // Available fields for filtering
  
  // Configuration
  label?: string;                        // Component label
  value?: FilterGroup;                   // Initial/controlled filter value
  allowGroups?: boolean;                 // Allow nested groups (default: true)
  maxDepth?: number;                     // Maximum nesting depth (default: 3)
  
  // Events
  onChange?: (filter: FilterGroup) => void;  // Change handler
  
  // Styling
  className?: string;                    // Tailwind CSS classes
  wrapperClass?: string;                 // Wrapper container classes
  
  // Base properties
  id?: string;
  visible?: boolean | string;
  testId?: string;
}
```

## Examples [#examples]

### Product Filters [#product-filters]

<SchemaExample id="components-complex-filter-builder/product-search" />

### User Query Builder [#user-query-builder]

<SchemaExample id="components-complex-filter-builder/user-filters" />

### Advanced Query [#advanced-query]

<SchemaExample id="components-complex-filter-builder/search-interface" />

## Supported Operators [#supported-operators]

The Filter Builder supports various comparison operators based on field type:

* **Text fields**: equals, not equals, contains, starts with, ends with
* **Number fields**: equals, not equals, greater than, less than, between
* **Date fields**: equals, before, after, between
* **Boolean fields**: is true, is false

## Use Cases [#use-cases]

* **Search interfaces**: Build advanced search forms
* **Data filtering**: Filter large datasets in tables
* **Report generation**: Create custom report criteria
* **Query builders**: Visual SQL/NoSQL query construction
* **Access control**: Define permission rules


# Filter UI





The Filter UI component renders configurable filters with text, select, date, and boolean inputs.

## JSON Configuration [#json-configuration]

```plaintext
{
  type: 'filter-ui',
  layout: 'popover',
  showApply: true,
  showClear: true,
  filters: [
    { field: 'name', label: 'Name', type: 'text', placeholder: 'Search name' },
    { field: 'status', label: 'Status', type: 'select', options: [
      { label: 'Open', value: 'open' },
      { label: 'Closed', value: 'closed' }
    ] },
    { field: 'created_at', label: 'Created', type: 'date-range' }
  ]
}
```

## Basic Usage [#basic-usage]

<SchemaExample id="components-complex-filter-ui/filter-ui" />

## Schema [#schema]

```plaintext
interface FilterUISchema {
  type: 'filter-ui';
  filters: Array<{
    field: string;
    label?: string;
    type: 'text' | 'number' | 'select' | 'date' | 'date-range' | 'boolean';
    operator?: 'equals' | 'contains' | 'startsWith' | 'gt' | 'lt' | 'between' | 'in';
    options?: Array<{ label: string; value: any }>;
    placeholder?: string;
  }>;
  values?: Record<string, any>;
  onChange?: string;
  showClear?: boolean;
  showApply?: boolean;
  layout?: 'inline' | 'popover' | 'drawer';
}
```


# Resizable





The Resizable component creates adjustable panel layouts with draggable handles, perfect for split views and customizable interfaces.

## Basic Usage [#basic-usage]

<SchemaExample id="components-complex-resizable/horizontal-split" />

## Vertical Layout [#vertical-layout]

<SchemaExample id="components-complex-resizable/vertical-split" />

## Three Panels [#three-panels]

<SchemaExample id="components-complex-resizable/triple-split" />

## Schema [#schema]

```plaintext
interface ResizablePanel {
  defaultSize: number;                  // Initial size percentage
  minSize?: number;                     // Minimum size percentage
  maxSize?: number;                     // Maximum size percentage
  content: SchemaNode | SchemaNode[];   // Panel content
}

interface ResizableSchema {
  type: 'resizable';
  
  // Configuration
  direction?: 'horizontal' | 'vertical'; // Panel direction (default: 'horizontal')
  minHeight?: string;                    // Minimum container height
  withHandle?: boolean;                  // Show handle icons (default: true)
  
  // Panels
  panels: ResizablePanel[];              // Array of panel configurations
  
  // Styling
  className?: string;                    // Tailwind CSS classes
  
  // Base properties
  id?: string;
  visible?: boolean | string;
  testId?: string;
}
```

## Examples [#examples]

### Code Editor Layout [#code-editor-layout]

<SchemaExample id="components-complex-resizable/editor-interface" />

### Dashboard Layout [#dashboard-layout]

<SchemaExample id="components-complex-resizable/complex-layout" />

### Mail Client [#mail-client]

<SchemaExample id="components-complex-resizable/mail-layout" />


# Scroll Area





The Scroll Area component provides a scrollable container with styled scrollbars that match your design system.

## Basic Usage [#basic-usage]

<SchemaExample id="components-complex-scroll-area/vertical-scroll" />

## Horizontal Scroll [#horizontal-scroll]

<SchemaExample id="components-complex-scroll-area/horizontal-scroll" />

## Custom Heights [#custom-heights]

<DemoGrid>
  <SchemaExample id="components-complex-scroll-area/short-150px" />

  <SchemaExample id="components-complex-scroll-area/tall-300px" />
</DemoGrid>

## Schema [#schema]

```plaintext
interface ScrollAreaSchema {
  type: 'scroll-area';
  
  // Dimensions
  height?: string;                      // Container height (e.g., '200px', '50vh')
  width?: string;                       // Container width (default: '100%')
  
  // Configuration
  orientation?: 'vertical' | 'horizontal' | 'both';  // Scroll direction (default: 'vertical')
  
  // Content
  content?: SchemaNode | SchemaNode[];  // Scrollable content
  children?: SchemaNode | SchemaNode[]; // Alternative content prop
  
  // Styling
  className?: string;                   // Tailwind CSS classes
  
  // Base properties
  id?: string;
  visible?: boolean | string;
  testId?: string;
}
```

## Examples [#examples]

### Message List [#message-list]

<SchemaExample id="components-complex-scroll-area/chat-messages" />

### File List [#file-list]

<SchemaExample id="components-complex-scroll-area/document-browser" />

### Code Block [#code-block]

<SchemaExample id="components-complex-scroll-area/code-preview" />


# Sort UI





The Sort UI component exposes single or multi-field sorting controls.

## JSON Configuration [#json-configuration]

```plaintext
{
  type: 'sort-ui',
  variant: 'dropdown',
  multiple: true,
  fields: [
    { field: 'name', label: 'Name' },
    { field: 'created_at', label: 'Created At' }
  ],
  sort: [{ field: 'name', direction: 'asc' }]
}
```

## Basic Usage [#basic-usage]

<SchemaExample id="components-complex-sort-ui/sort-ui" />

## Schema [#schema]

```plaintext
interface SortUISchema {
  type: 'sort-ui';
  fields: Array<{
    field: string;
    label?: string;
  }>;
  sort?: Array<{
    field: string;
    direction: 'asc' | 'desc';
  }>;
  onChange?: string;
  multiple?: boolean;
  variant?: 'dropdown' | 'buttons';
}
```


# Table





## Examples [#examples]

<SchemaExample id="components-complex-table/basic-table" />

## Schema [#schema]

```plaintext
interface TableSchema {
  type: 'table';
  columns: Array<{ header: string; accessorKey: string }>;
  data: Record<string, any>[];
}
```


# View Switcher





The View Switcher component renders a selector and the active view schema in one place.

## JSON Configuration [#json-configuration]

```plaintext
{
  type: 'view-switcher',
  variant: 'tabs',
  position: 'top',
  defaultView: 'grid',
  views: [
    {
      type: 'grid',
      label: 'Grid',
      schema: { type: 'text', content: 'Grid content' }
    },
    {
      type: 'kanban',
      label: 'Kanban',
      schema: { type: 'text', content: 'Kanban content' }
    }
  ]
}
```

## Basic Usage [#basic-usage]

<SchemaExample id="components-complex-view-switcher/view-switcher" />

## Schema [#schema]

```plaintext
interface ViewSwitcherSchema {
  type: 'view-switcher';
  views: Array<{
    type: 'list' | 'detail' | 'grid' | 'kanban' | 'calendar' | 'timeline' | 'map';
    label?: string;
    icon?: string;
    schema?: SchemaNode;
  }>;
  defaultView?: string;
  activeView?: string;
  variant?: 'tabs' | 'buttons' | 'dropdown';
  position?: 'top' | 'bottom' | 'left' | 'right';
  onViewChange?: string;
  persistPreference?: boolean;
  storageKey?: string;
  allowCreateView?: boolean;                          // Show "+" button to create views
  viewActions?: Array<{                               // Per-view action icons
    type: 'share' | 'settings' | 'duplicate' | 'delete';
    icon?: string;
  }>;
}
```


# Alert





## Examples [#examples]

<SchemaExample id="components-data-display-alert/info-alert" />

<SchemaExample id="components-data-display-alert/destructive-alert" />

## Schema [#schema]

```plaintext
interface AlertSchema {
  type: 'alert';
  title?: string;
  description?: string;
  variant?: 'default' | 'destructive';
  icon?: string;
  className?: string;
}
```


# Avatar





## Examples [#examples]

<SchemaExample id="components-data-display-avatar/avatar-with-image" />

<SchemaExample id="components-data-display-avatar/avatar-with-fallback" />

## Schema [#schema]

```plaintext
interface AvatarSchema {
  type: 'avatar';
  src?: string;
  alt?: string;
  fallback?: string;
  size?: 'sm' | 'md' | 'lg';
  className?: string;
}
```


# Badge





## Examples [#examples]

<SchemaExample id="components-data-display-badge/badge-variants" />

## Schema [#schema]

```plaintext
interface BadgeSchema {
  type: 'badge';
  label: string;
  variant?: 'default' | 'secondary' | 'outline' | 'destructive';
  className?: string;
}
```


# Breadcrumb





The Breadcrumb component shows the current page's location within the site hierarchy.

## Basic Usage [#basic-usage]

<SchemaExample id="components-data-display-breadcrumb/basic-breadcrumb" />

## With Icons [#with-icons]

<SchemaExample id="components-data-display-breadcrumb/with-icons" />

## Schema [#schema]

```plaintext
interface BreadcrumbItem {
  label: string;
  href?: string;
  icon?: string;
}

interface BreadcrumbSchema {
  type: 'breadcrumb';
  items: BreadcrumbItem[];        // Breadcrumb items
  separator?: string;             // Custom separator
  className?: string;
}
```


# Kbd





The Kbd component displays keyboard shortcuts in a styled format.

## Basic Usage [#basic-usage]

<SchemaExample id="components-data-display-kbd/copy-shortcut" />

## Multiple Key Combinations [#multiple-key-combinations]

<DemoGrid>
  <SchemaExample id="components-data-display-kbd/command-palette" />

  <SchemaExample id="components-data-display-kbd/search" />

  <SchemaExample id="components-data-display-kbd/submit" />
</DemoGrid>

## Schema [#schema]

```plaintext
interface KbdSchema {
  type: 'kbd';
  keys: string[];                 // Keyboard keys
  className?: string;
}
```

## Examples [#examples]

### In Documentation [#in-documentation]

<SchemaExample id="components-data-display-kbd/inline-usage" />


# List





## Examples [#examples]

<SchemaExample id="components-data-display-list/basic-list" />

## Schema [#schema]

```plaintext
interface ListSchema {
  type: 'list';
  items: SchemaNode[];
  ordered?: boolean;
  className?: string;
}
```


# Statistic





The Statistic component displays numerical data and key metrics with optional labels, descriptions, and trend indicators.

## Basic Usage [#basic-usage]

<SchemaExample id="components-data-display-statistic/simple-statistic" />

## With Trend Indicators [#with-trend-indicators]

<DemoGrid>
  <SchemaExample id="components-data-display-statistic/positive-trend" />

  <SchemaExample id="components-data-display-statistic/negative-trend" />

  <SchemaExample id="components-data-display-statistic/neutral" />
</DemoGrid>

## With Descriptions [#with-descriptions]

<SchemaExample id="components-data-display-statistic/with-description" />

## Schema [#schema]

```plaintext
interface StatisticSchema {
  type: 'statistic';
  
  // Content
  label?: string;                       // Label/title of the statistic
  value: string | number;               // Main value to display
  description?: string;                 // Additional description text
  icon?: string;                        // Optional icon name
  
  // Trend indicator
  trend?: 'up' | 'down' | 'neutral';   // Trend direction
  
  // Styling
  className?: string;                   // Tailwind CSS classes
  
  // Base properties
  id?: string;
  visible?: boolean | string;
  testId?: string;
}
```

## Examples [#examples]

### Dashboard Metrics [#dashboard-metrics]

<SchemaExample id="components-data-display-statistic/metrics-grid" />

### Sales Dashboard [#sales-dashboard]

<SchemaExample id="components-data-display-statistic/sales-dashboard" />

### Simple Stats Row [#simple-stats-row]

<SchemaExample id="components-data-display-statistic/social-stats" />


# Tree View





The Tree View component displays hierarchical data in an expandable tree structure, perfect for file explorers, organizational charts, and nested navigation.

## Basic Usage [#basic-usage]

<SchemaExample id="components-data-display-tree-view/file-tree" />

## Nested Structure [#nested-structure]

<SchemaExample id="components-data-display-tree-view/deep-nesting" />

## Schema [#schema]

```plaintext
interface TreeNode {
  id: string;                           // Unique node identifier
  label: string;                        // Node label text
  icon?: string;                        // Icon name ('folder' or 'file')
  children?: TreeNode[];                // Child nodes
  data?: any;                           // Additional node data
}

interface TreeViewSchema {
  type: 'tree-view';
  
  // Data
  data?: TreeNode[];                    // Tree data (alias for nodes)
  nodes?: TreeNode[];                   // Tree nodes
  title?: string;                       // Tree title
  
  // Selection
  defaultExpandedIds?: string[];        // Default expanded node IDs
  defaultSelectedIds?: string[];        // Default selected node IDs
  expandedIds?: string[];               // Controlled expanded node IDs
  selectedIds?: string[];               // Controlled selected node IDs
  multiSelect?: boolean;                // Enable multi-selection (default: false)
  
  // Appearance
  showLines?: boolean;                  // Show connecting lines (default: true)
  
  // Events
  onSelectChange?: (selectedIds: string[]) => void;  // Selection change handler
  onExpandChange?: (expandedIds: string[]) => void;  // Expand change handler
  onNodeClick?: (node: TreeNode) => void;            // Node click handler
  
  // Styling
  className?: string;                   // Tailwind CSS classes
  
  // Base properties
  id?: string;
  visible?: boolean | string;
  testId?: string;
}
```

## Examples [#examples]

### Organization Chart [#organization-chart]

<SchemaExample id="components-data-display-tree-view/org-chart" />

### Navigation Menu [#navigation-menu]

<SchemaExample id="components-data-display-tree-view/sidebar-navigation" />


# Accordion





## Examples [#examples]

<SchemaExample id="components-disclosure-accordion/basic-accordion" />

## Schema [#schema]

```plaintext
interface AccordionSchema {
  type: 'accordion';
  items: Array<{
    title: string;
    content: string | SchemaNode;
  }>;
  defaultOpen?: number[];
  multiple?: boolean;
}
```


# Collapsible





## Examples [#examples]

<SchemaExample id="components-disclosure-collapsible/basic-collapsible" />

## Schema [#schema]

```plaintext
interface CollapsibleSchema {
  type: 'collapsible';
  trigger: SchemaNode;
  children: SchemaNode[];
  defaultOpen?: boolean;
}
```


# Toggle Group





The Toggle Group component allows users to toggle between multiple options.

## Basic Usage [#basic-usage]

<SchemaExample id="components-disclosure-toggle-group/single-selection" />

## Multiple Selection [#multiple-selection]

<SchemaExample id="components-disclosure-toggle-group/multiple-selection" />

## With Labels [#with-labels]

<SchemaExample id="components-disclosure-toggle-group/with-labels" />

## Schema [#schema]

```plaintext
interface ToggleGroupItem {
  value: string;
  icon?: string;
  label?: string;
}

interface ToggleGroupSchema {
  type: 'toggle-group';
  type: 'single' | 'multiple';    // Selection mode
  items: ToggleGroupItem[];       // Toggle items
  value?: string | string[];      // Selected value(s)
  variant?: 'default' | 'outline';
  size?: 'sm' | 'default' | 'lg';
  
  // Events
  onValueChange?: string | ActionConfig;
  
  // States
  disabled?: boolean;
  
  // Styling
  className?: string;
}
```


# Empty





The Empty component displays a placeholder when there's no content to show.

## Basic Usage [#basic-usage]

<SchemaExample id="components-feedback-empty/basic-empty-state" />

## With Icon [#with-icon]

<SchemaExample id="components-feedback-empty/with-icon" />

## With Action [#with-action]

<SchemaExample id="components-feedback-empty/with-action-button" />

## Schema [#schema]

```plaintext
interface EmptySchema {
  type: 'empty';
  icon?: string;                  // Lucide icon name
  title?: string;                 // Main message
  description?: string;           // Supporting text
  action?: ComponentSchema;       // Call to action button
  className?: string;
}
```

## Examples [#examples]

### Search Results [#search-results]

<SchemaExample id="components-feedback-empty/empty-search-results" />

### Empty List [#empty-list]

<SchemaExample id="components-feedback-empty/empty-team-list" />


# Loading





## Examples [#examples]

<SchemaExample id="components-feedback-loading/basic-loading" />

<SchemaExample id="components-feedback-loading/with-text" />

## Schema [#schema]

```plaintext
interface LoadingSchema {
  type: 'loading';
  size?: 'sm' | 'md' | 'lg';
  className?: string;
}
```


# Progress





## Examples [#examples]

<SchemaExample id="components-feedback-progress/progress-bar" />

<SchemaExample id="components-feedback-progress/different-values" />

## Schema [#schema]

```plaintext
interface ProgressSchema {
  type: 'progress';
  value: number;           // 0-100
  className?: string;
}
```


# Skeleton





## Examples [#examples]

<SchemaExample id="components-feedback-skeleton/text-skeleton" />

## Schema [#schema]

```plaintext
interface SkeletonSchema {
  type: 'skeleton';
  width?: string | number;
  height?: string | number;
  className?: string;
}
```


# Sonner





The Sonner component provides beautiful toast notifications with a rich API.

## Basic Usage [#basic-usage]

<SchemaExample id="components-feedback-sonner/basic-sonner-toast" />

## Toast Types [#toast-types]

<DemoGrid>
  <SchemaExample id="components-feedback-sonner/success" />

  <SchemaExample id="components-feedback-sonner/error" />

  <SchemaExample id="components-feedback-sonner/warning" />

  <SchemaExample id="components-feedback-sonner/info" />
</DemoGrid>

## With Action [#with-action]

<SchemaExample id="components-feedback-sonner/toast-with-action" />

## Schema [#schema]

```plaintext
interface SonnerSchema {
  action: 'sonner';
  message: string;                // Toast message
  description?: string;           // Additional description
  type?: 'default' | 'success' | 'error' | 'warning' | 'info';
  duration?: number;              // Auto-close duration (ms)
  
  // Action
  action?: {
    label: string;
    onClick: string | ActionConfig;
  };
}
```

## Examples [#examples]

### Promise Toast [#promise-toast]

<SchemaExample id="components-feedback-sonner/promise-based-toast" />


# Spinner





The Spinner component displays a loading indicator.

## Basic Usage [#basic-usage]

<SchemaExample id="components-feedback-spinner/default-spinner" />

## Sizes [#sizes]

<DemoGrid>
  <SchemaExample id="components-feedback-spinner/small" />

  <SchemaExample id="components-feedback-spinner/medium" />

  <SchemaExample id="components-feedback-spinner/large" />
</DemoGrid>

## Schema [#schema]

```plaintext
interface SpinnerSchema {
  type: 'spinner';
  size?: 'sm' | 'md' | 'lg';
  className?: string;
}
```

## Examples [#examples]

### In Button [#in-button]

<SchemaExample id="components-feedback-spinner/loading-button" />

### Centered [#centered]

<SchemaExample id="components-feedback-spinner/centered-spinner" />


# Toast





The Toast component displays brief notifications to users that appear temporarily and then disappear.

## Basic Usage [#basic-usage]

<SchemaExample id="components-feedback-toast/basic-toast" />

## Variants [#variants]

<DemoGrid>
  <SchemaExample id="components-feedback-toast/default" />

  <SchemaExample id="components-feedback-toast/destructive" />
</DemoGrid>

## With Action [#with-action]

<SchemaExample id="components-feedback-toast/toast-with-action" />

## Schema [#schema]

```plaintext
interface ToastSchema {
  type: 'toast';
  title?: string;                // Toast title
  description?: string;           // Toast message
  variant?: 'default' | 'destructive';
  
  // Action
  actionLabel?: string;           // Action button label
  onAction?: string | ActionConfig;
  
  // Timing
  duration?: number;              // Auto-dismiss time in ms
}
```

## Examples [#examples]

### Success Message [#success-message]

<SchemaExample id="components-feedback-toast/success-toast" />

### Error Message [#error-message]

<SchemaExample id="components-feedback-toast/error-toast" />

### With Undo Action [#with-undo-action]

<SchemaExample id="components-feedback-toast/toast-with-undo" />


# Toaster





The Toaster component provides a container for toast notifications. It should be placed once at the root level of your application to enable toast functionality.

## Basic Usage [#basic-usage]

The Toaster component is typically added to your app's layout and doesn't require configuration:

<SchemaExample id="components-feedback-toaster/default-toaster" />

## Providers [#providers]

ObjectUI supports two toast providers:

<DemoGrid>
  <SchemaExample id="components-feedback-toaster/default-provider" />

  <SchemaExample id="components-feedback-toaster/sonner-provider" />
</DemoGrid>

## Schema [#schema]

```plaintext
interface ToasterSchema {
  type: 'toaster';
  
  // Configuration
  provider?: 'default' | 'sonner';      // Toast provider (default: 'default')
  position?: 'top-left' | 'top-center' | 'top-right' | 
             'bottom-left' | 'bottom-center' | 'bottom-right';  // Toast position
  limit?: number;                        // Maximum number of toasts (default: 5)
  
  // Styling
  className?: string;                    // Tailwind CSS classes
  
  // Base properties
  id?: string;
  visible?: boolean | string;
  testId?: string;
}
```

## Examples [#examples]

### In App Layout [#in-app-layout]

```plaintext
{
  type: 'div',
  className: 'min-h-screen',
  children: [
    // Your app content
    { type: 'page', title: 'Dashboard', body: [...] },
    
    // Toaster at root level
    { type: 'toaster', provider: 'sonner' }
  ]
}
```

### Usage with Toast Actions [#usage-with-toast-actions]

The Toaster component works in conjunction with Toast components to display notifications. Once the Toaster is mounted, you can trigger toasts programmatically or via Toast components:

<SchemaExample id="components-feedback-toaster/with-toast-trigger" />

### Configuration [#configuration]

<SchemaExample id="components-feedback-toaster/custom-position-limit" />

## Notes [#notes]

* Place the Toaster component once in your app's root layout
* The `default` provider uses the standard Shadcn/UI toast system
* The `sonner` provider uses Sonner for more advanced toast features
* Toast notifications are triggered separately using toast functions or Toast components
* The Toaster manages the positioning and lifecycle of all toasts


# Button





The Button component triggers actions when clicked. It supports multiple variants, sizes, and states.

## Basic Usage [#basic-usage]

<SchemaExample id="components-form-button/simple-button" />

## Variants [#variants]

<DemoGrid>
  <SchemaExample id="components-form-button/default" />

  <SchemaExample id="components-form-button/destructive" />

  <SchemaExample id="components-form-button/outline" />

  <SchemaExample id="components-form-button/secondary" />

  <SchemaExample id="components-form-button/ghost" />

  <SchemaExample id="components-form-button/link" />
</DemoGrid>

## Sizes [#sizes]

<DemoGrid>
  <SchemaExample id="components-form-button/button-sizes" />

  <SchemaExample id="components-form-button/icon-button" />
</DemoGrid>

## With Icons [#with-icons]

<DemoGrid>
  <SchemaExample id="components-form-button/button-with-icon" />

  <SchemaExample id="components-form-button/icon-on-right" />
</DemoGrid>

## States [#states]

<DemoGrid>
  <SchemaExample id="components-form-button/disabled-state" />

  <SchemaExample id="components-form-button/loading-state" />
</DemoGrid>

## Schema [#schema]

```plaintext
interface ButtonSchema {
  type: 'button';
  label: string;                    // Button text
  variant?: 'default' | 'destructive' | 'outline' | 'secondary' | 'ghost' | 'link';
  size?: 'sm' | 'default' | 'lg' | 'icon';
  
  // Icons
  icon?: string;                    // Lucide icon name
  iconPosition?: 'left' | 'right'; // Icon placement
  
  // States
  disabled?: boolean;
  loading?: boolean;
  
  // Actions
  onClick?: string | ActionConfig;  // Action on click
  href?: string;                    // Link URL (renders as link)
  
  // Styling
  className?: string;
  fullWidth?: boolean;
}
```

## Examples [#examples]

### Action Buttons [#action-buttons]

<SchemaExample id="components-form-button/common-action-buttons" />

### Full Width [#full-width]

<SchemaExample id="components-form-button/full-width-button" />


# Calendar





The Calendar component allows users to select dates in various modes including single date, multiple dates, or date ranges.

## Basic Usage [#basic-usage]

<SchemaExample id="components-form-calendar/simple-calendar" />

## Selection Modes [#selection-modes]

<DemoGrid>
  <SchemaExample id="components-form-calendar/single-date" />

  <SchemaExample id="components-form-calendar/date-range" />
</DemoGrid>

## Multiple Selection [#multiple-selection]

<SchemaExample id="components-form-calendar/multiple-dates" />

## Schema [#schema]

```plaintext
interface CalendarSchema {
  type: 'calendar';
  
  // Selection
  mode?: 'single' | 'multiple' | 'range';  // Selection mode (default: 'single')
  defaultValue?: Date | Date[];             // Default selected date(s)
  value?: Date | Date[];                    // Controlled selected date(s)
  
  // Constraints
  minDate?: Date | string;                  // Minimum selectable date
  maxDate?: Date | string;                  // Maximum selectable date
  disabled?: boolean;                       // Whether calendar is disabled
  
  // Events
  onChange?: (date: Date | Date[] | undefined) => void;  // Date change handler
  
  // Styling
  className?: string;                       // Tailwind CSS classes
  
  // Base properties
  id?: string;
  visible?: boolean | string;
  testId?: string;
}
```

## Examples [#examples]

### In a Form [#in-a-form]

<SchemaExample id="components-form-calendar/form-integration" />

### With Custom Styling [#with-custom-styling]

<SchemaExample id="components-form-calendar/custom-style" />


# Checkbox





## Examples [#examples]

<SchemaExample id="components-form-checkbox/basic-checkbox" />

<SchemaExample id="components-form-checkbox/multiple-checkboxes" />

## Schema [#schema]

```plaintext
interface CheckboxSchema {
  type: 'checkbox';
  name?: string;
  label?: string;
  defaultChecked?: boolean;
  required?: boolean;
  disabled?: boolean;
}
```


# Combobox





The Combobox component combines a text input with a dropdown list, allowing users to search and select from options.

## Basic Usage [#basic-usage]

<SchemaExample id="components-form-combobox/basic-combobox" />

## With Search [#with-search]

<SchemaExample id="components-form-combobox/searchable-combobox" />

## States [#states]

<DemoGrid>
  <SchemaExample id="components-form-combobox/disabled" />

  <SchemaExample id="components-form-combobox/with-value" />
</DemoGrid>

## Schema [#schema]

```plaintext
interface ComboboxOption {
  value: string;
  label: string;
}

interface ComboboxSchema {
  type: 'combobox';
  options: ComboboxOption[];     // Available options
  value?: string;                 // Selected value
  
  // Text
  placeholder?: string;           // Button placeholder
  searchPlaceholder?: string;     // Search input placeholder
  emptyText?: string;             // Text when no results
  
  // Events
  onValueChange?: string | ActionConfig;
  
  // States
  disabled?: boolean;
  
  // Styling
  className?: string;
}
```

## Examples [#examples]

### Dynamic Options [#dynamic-options]

<SchemaExample id="components-form-combobox/country-selector" />


# Command





The Command component provides a fast, searchable command menu with keyboard navigation.

## Basic Usage [#basic-usage]

<SchemaExample id="components-form-command/command-menu" />

## Schema [#schema]

```plaintext
interface CommandItem {
  value: string;
  label: string;
  icon?: string;
  shortcut?: string[];
}

interface CommandGroup {
  heading?: string;
  items: CommandItem[];
}

interface CommandSchema {
  type: 'command';
  placeholder?: string;           // Search placeholder
  groups: CommandGroup[];         // Command groups
  emptyText?: string;             // Text when no results
  
  // Events
  onSelect?: string | ActionConfig;
  
  // Styling
  className?: string;
}
```

## Examples [#examples]

### With Shortcuts [#with-shortcuts]

<SchemaExample id="components-form-command/command-palette-with-shortcuts" />


# Date Picker





The Date Picker component allows users to select a date from a calendar interface.

## Basic Usage [#basic-usage]

<SchemaExample id="components-form-date-picker/basic-date-picker" />

## With Default Date [#with-default-date]

<SchemaExample id="components-form-date-picker/with-default-value" />

## States [#states]

<DemoGrid>
  <SchemaExample id="components-form-date-picker/disabled" />

  <SchemaExample id="components-form-date-picker/full-width" />
</DemoGrid>

## Schema [#schema]

```plaintext
interface DatePickerSchema {
  type: 'date-picker';
  value?: string | Date;          // Selected date (ISO string or Date)
  placeholder?: string;           // Placeholder text
  
  // Events
  onDateChange?: string | ActionConfig;
  
  // States
  disabled?: boolean;
  
  // Styling
  className?: string;
}
```

## Examples [#examples]

### In a Form [#in-a-form]

<SchemaExample id="components-form-date-picker/form-field" />

### Date Range [#date-range]

<SchemaExample id="components-form-date-picker/date-range-selector" />


# File Upload





The File Upload component provides a futuristic interface for uploading files with visual feedback, progress indication, and multiple file support.

## Basic Usage [#basic-usage]

<SchemaExample id="components-form-file-upload/simple-upload" />

## Single vs Multiple [#single-vs-multiple]

<DemoGrid>
  <SchemaExample id="components-form-file-upload/single-file" />

  <SchemaExample id="components-form-file-upload/multiple-files" />
</DemoGrid>

## File Type Restrictions [#file-type-restrictions]

<SchemaExample id="components-form-file-upload/images-only" />

## Schema [#schema]

```text
interface FileUploadSchema {
  type: 'file-upload';
  
  // Required
  id: string;                           // Field identifier
  
  // Configuration
  name?: string;                        // Field name for form submission
  label?: string;                       // Label text
  buttonText?: string;                  // Upload button text
  
  // File constraints
  accept?: string;                      // Accepted file types (e.g., 'image/*', '.pdf,.doc')
  multiple?: boolean;                   // Allow multiple files (default: false)
  maxSize?: number;                     // Maximum file size in bytes
  maxFiles?: number;                    // Maximum number of files (for multiple)
  
  // States
  disabled?: boolean;                   // Whether field is disabled
  
  // Help text
  description?: string;                 // Help text or description
  error?: string;                       // Error message
  
  // Styling
  className?: string;                   // Tailwind CSS classes
  wrapperClass?: string;                // Wrapper container classes
  
  // Base properties
  visible?: boolean | string;
  testId?: string;
}
```

## Examples [#examples]

### Document Upload [#document-upload]

<SchemaExample id="components-form-file-upload/document-upload" />

### Profile Picture [#profile-picture]

<SchemaExample id="components-form-file-upload/avatar-upload" />

### Full Example [#full-example]

<SchemaExample id="components-form-file-upload/form-example" />


# Form





The Form component provides a complete form solution with validation and submission handling.

## Basic Usage [#basic-usage]

<SchemaExample id="components-form-form/login-form" />

## With Validation [#with-validation]

<SchemaExample id="components-form-form/registration-form" />

## Schema [#schema]

```plaintext
interface FormField {
  name: string;
  label?: string;
  type: 'input' | 'textarea' | 'select' | 'checkbox' | 'radio-group' | 'date-picker';
  placeholder?: string;
  required?: boolean;
  disabled?: boolean;
  
  // Validation
  minLength?: number;
  maxLength?: number;
  min?: number;
  max?: number;
  pattern?: string;
  
  // Options (for select, radio-group)
  options?: Array<{ value: string; label: string }>;
  
  // Default value
  defaultValue?: any;
}

interface FormSchema {
  type: 'form';
  fields: FormField[];            // Form fields
  submitButton?: {
    label: string;
    variant?: string;
  };
  
  // Events
  onSubmit?: string | ActionConfig;
  
  // Layout
  columns?: number;               // Grid layout
  
  // Styling
  className?: string;
}
```

## Examples [#examples]

### Multi-column Form [#multi-column-form]

<SchemaExample id="components-form-form/contact-form" />


# Input OTP





The Input OTP component provides a secure way to enter one-time passwords or verification codes.

## Basic Usage [#basic-usage]

<SchemaExample id="components-form-input-otp/6-digit-otp" />

## With Separator [#with-separator]

<SchemaExample id="components-form-input-otp/with-visual-separator" />

## Different Lengths [#different-lengths]

<DemoGrid>
  <SchemaExample id="components-form-input-otp/4-digit" />

  <SchemaExample id="components-form-input-otp/8-digit" />
</DemoGrid>

## Schema [#schema]

```plaintext
interface InputOTPSchema {
  type: 'input-otp';
  length: number;                 // Number of digits
  value?: string;                 // Current value
  separator?: boolean;            // Show visual separator
  
  // Events
  onChange?: string | ActionConfig;
  onComplete?: string | ActionConfig;
  
  // States
  disabled?: boolean;
  
  // Styling
  className?: string;
}
```

## Examples [#examples]

### In a Form [#in-a-form]

<SchemaExample id="components-form-input-otp/verification-form" />


# Input





## Examples [#examples]

<SchemaExample id="components-form-input/basic-input" />

<SchemaExample id="components-form-input/with-label" />

<SchemaExample id="components-form-input/input-types" />

## Schema [#schema]

```plaintext
interface InputSchema {
  type: 'input';
  name?: string;
  label?: string;
  inputType?: 'text' | 'password' | 'email' | 'number' | 'tel' | 'url';
  placeholder?: string;
  defaultValue?: string | number;
  required?: boolean;
  disabled?: boolean;
  readonly?: boolean;
}
```


# Label





The Label component renders accessible labels for form fields.

## Basic Usage [#basic-usage]

<SchemaExample id="components-form-label/form-label" />

## Required Field [#required-field]

<SchemaExample id="components-form-label/required-label" />

## Schema [#schema]

```plaintext
interface LabelSchema {
  type: 'label';
  text: string;                   // Label text
  htmlFor?: string;               // Associated input ID
  required?: boolean;             // Show required indicator
  className?: string;
}
```


# Radio Group





The Radio Group component allows users to select one option from a set of mutually exclusive options.

## Basic Usage [#basic-usage]

<SchemaExample id="components-form-radio-group/basic-radio-group" />

## With Default Value [#with-default-value]

<SchemaExample id="components-form-radio-group/with-default-selection" />

## Layout Options [#layout-options]

<DemoGrid>
  <SchemaExample id="components-form-radio-group/vertical-layout" />

  <SchemaExample id="components-form-radio-group/horizontal-layout" />
</DemoGrid>

## States [#states]

<DemoGrid>
  <SchemaExample id="components-form-radio-group/disabled" />

  <SchemaExample id="components-form-radio-group/individual-disabled" />
</DemoGrid>

## Schema [#schema]

```plaintext
interface RadioOption {
  value: string;
  label: string;
  disabled?: boolean;
}

interface RadioGroupSchema {
  type: 'radio-group';
  options: RadioOption[];         // Available options
  value?: string;                 // Selected value
  
  // Layout
  direction?: 'vertical' | 'horizontal';
  
  // Events
  onValueChange?: string | ActionConfig;
  
  // States
  disabled?: boolean;
  
  // Styling
  className?: string;
}
```

## Examples [#examples]

### In a Form [#in-a-form]

<SchemaExample id="components-form-radio-group/form-field" />

### With Descriptions [#with-descriptions]

<SchemaExample id="components-form-radio-group/with-descriptions" />


# Select





## Examples [#examples]

<SchemaExample id="components-form-select/basic-select" />

<SchemaExample id="components-form-select/with-placeholder" />

## Schema [#schema]

```plaintext
interface SelectSchema {
  type: 'select';
  name?: string;
  label?: string;
  options: { label: string; value: string | number }[];
  placeholder?: string;
  required?: boolean;
  disabled?: boolean;
}
```


# Slider





## Examples [#examples]

<SchemaExample id="components-form-slider/basic-slider" />

## Schema [#schema]

```plaintext
interface SliderSchema {
  type: 'slider';
  name?: string;
  label?: string;
  min?: number;
  max?: number;
  step?: number;
  defaultValue?: number;
}
```


# Switch





## Examples [#examples]

<SchemaExample id="components-form-switch/basic-switch" />

<SchemaExample id="components-form-switch/multiple-switches" />

## Schema [#schema]

```plaintext
interface SwitchSchema {
  type: 'switch';
  name?: string;
  label?: string;
  defaultChecked?: boolean;
  disabled?: boolean;
}
```


# Textarea





## Examples [#examples]

<SchemaExample id="components-form-textarea/basic-textarea" />

<SchemaExample id="components-form-textarea/with-label" />

## Schema [#schema]

```plaintext
interface TextareaSchema {
  type: 'textarea';
  name?: string;
  label?: string;
  placeholder?: string;
  rows?: number;
  required?: boolean;
  disabled?: boolean;
}
```


# Toggle





The Toggle component is a button that can be toggled between on and off states, useful for settings and preferences.

## Basic Usage [#basic-usage]

<SchemaExample id="components-form-toggle/simple-toggle" />

## Variants [#variants]

<DemoGrid>
  <SchemaExample id="components-form-toggle/default" />

  <SchemaExample id="components-form-toggle/outline" />
</DemoGrid>

## Sizes [#sizes]

<SchemaExample id="components-form-toggle/toggle-sizes" />

## States [#states]

<DemoGrid>
  <SchemaExample id="components-form-toggle/pressed-state" />

  <SchemaExample id="components-form-toggle/disabled-state" />
</DemoGrid>

## Schema [#schema]

(Schema documentation temporarily disabled)

## Examples [#examples]

### With Icons [#with-icons]

<SchemaExample id="components-form-toggle/settings-toggles" />

### In a Settings Panel [#in-a-settings-panel]

<SchemaExample id="components-form-toggle/settings-example" />

### Toolbar Toggles [#toolbar-toggles]

<SchemaExample id="components-form-toggle/text-formatting" />


# Aspect Ratio





The Aspect Ratio component maintains a consistent width to height ratio for content.

## Basic Usage [#basic-usage]

<SchemaExample id="components-layout-aspect-ratio/16-9-aspect-ratio" />

## Different Ratios [#different-ratios]

<DemoGrid>
  <SchemaExample id="components-layout-aspect-ratio/square" />

  <SchemaExample id="components-layout-aspect-ratio/4-3" />

  <SchemaExample id="components-layout-aspect-ratio/ultrawide" />
</DemoGrid>

## Schema [#schema]

```plaintext
interface AspectRatioSchema {
  type: 'aspect-ratio';
  ratio: number;                  // Width / Height ratio
  content: ComponentSchema;       // Content to display
  className?: string;
}
```

## Examples [#examples]

### Video Container [#video-container]

<SchemaExample id="components-layout-aspect-ratio/video-aspect-ratio" />


# Card





## Examples [#examples]

<SchemaExample id="components-layout-card/basic-card" />

<SchemaExample id="components-layout-card/with-footer" />

## Schema [#schema]

```plaintext
interface CardSchema {
  type: 'card';
  title?: string;
  description?: string;
  children?: SchemaNode[];
  header?: SchemaNode[];
  footer?: SchemaNode[];
  className?: string;
}
```


# Container





## Examples [#examples]

<SchemaExample id="components-layout-container/basic-container" />

## Schema [#schema]

```plaintext
interface ContainerSchema {
  type: 'container';
  children: SchemaNode[];
  className?: string;
}
```


# Flex





## Examples [#examples]

<SchemaExample id="components-layout-flex/horizontal-layout" />

## Schema [#schema]

```plaintext
interface FlexSchema {
  type: 'flex';
  direction?: 'row' | 'column';
  gap?: number;
  align?: 'start' | 'center' | 'end';
  justify?: 'start' | 'center' | 'end' | 'between';
  wrap?: boolean;
  children: SchemaNode[];
  className?: string;
}
```


# Grid





## Examples [#examples]

<SchemaExample id="components-layout-grid/2-column-grid" />

## Schema [#schema]

```plaintext
interface GridSchema {
  type: 'grid';
  columns?: number;
  gap?: number;
  children: SchemaNode[];
  className?: string;
}
```


# Page





The Page component provides a standardized full-page layout with built-in support for titles, descriptions, and organized content sections.

## Basic Usage [#basic-usage]

<SchemaExample id="components-layout-page/simple-page" />

## With Title and Description [#with-title-and-description]

<SchemaExample id="components-layout-page/page-with-header" />

## Schema [#schema]

```plaintext
interface PageSchema {
  type: 'page';
  
  // Header
  title?: string;                       // Page title
  icon?: string;                        // Page icon (Lucide icon name)
  description?: string;                 // Page description
  
  // Content
  body?: SchemaNode[];                  // Main content array
  children?: SchemaNode | SchemaNode[]; // Alternative content prop
  
  // Styling
  className?: string;                   // Tailwind CSS classes
  
  // Base properties
  id?: string;
  visible?: boolean | string;
  testId?: string;
}
```

## Examples [#examples]

### Dashboard Page [#dashboard-page]

<SchemaExample id="components-layout-page/full-dashboard" />

### Settings Page [#settings-page]

<SchemaExample id="components-layout-page/settings-layout" />

### Content Page [#content-page]

<SchemaExample id="components-layout-page/documentation-page" />


# Semantic





Semantic components provide HTML5 semantic elements that give meaning to the structure of web content, improving accessibility and SEO.

## Available Elements [#available-elements]

ObjectUI provides semantic wrappers for these HTML5 elements:

* `header` - Page or section header
* `nav` - Navigation section
* `main` - Main content area
* `aside` - Sidebar or complementary content
* `section` - Thematic grouping of content
* `article` - Self-contained content
* `footer` - Page or section footer

## Basic Usage [#basic-usage]

<SchemaExample id="components-layout-semantic/main-element" />

## Header [#header]

<SchemaExample id="components-layout-semantic/header" />

## Navigation [#navigation]

<SchemaExample id="components-layout-semantic/navigation" />

## Section and Article [#section-and-article]

<DemoGrid>
  <SchemaExample id="components-layout-semantic/section" />

  <SchemaExample id="components-layout-semantic/article" />
</DemoGrid>

## Aside and Footer [#aside-and-footer]

<DemoGrid>
  <SchemaExample id="components-layout-semantic/aside" />

  <SchemaExample id="components-layout-semantic/footer" />
</DemoGrid>

## Schema [#schema]

```plaintext
// All semantic elements share the same schema structure
interface SemanticSchema {
  type: 'header' | 'nav' | 'main' | 'aside' | 'section' | 'article' | 'footer';
  
  // Content
  children?: SchemaNode | SchemaNode[];  // Child components
  body?: SchemaNode[];                    // Alternative content prop
  
  // Styling
  className?: string;                     // Tailwind CSS classes
  
  // Base properties
  id?: string;
  visible?: boolean | string;
  testId?: string;
}
```

## Examples [#examples]

### Page Layout [#page-layout]

<SchemaExample id="components-layout-semantic/complete-layout" />

### Blog Post [#blog-post]

<SchemaExample id="components-layout-semantic/blog-article" />


# Stack





## Examples [#examples]

<SchemaExample id="components-layout-stack/basic-stack" />

## Schema [#schema]

```plaintext
interface StackSchema {
  type: 'stack';
  gap?: number;
  children: SchemaNode[];
  className?: string;
}
```


# Tabs





## Examples [#examples]

<SchemaExample id="components-layout-tabs/basic-tabs" />

## Schema [#schema]

```plaintext
interface TabsSchema {
  type: 'tabs';
  items: Array<{
    label: string;
    content: SchemaNode[];
  }>;
  defaultValue?: number;
}
```


# Header Bar





The Header Bar component provides a standard application header with sidebar trigger button and breadcrumb navigation.

## Basic Usage [#basic-usage]

<SchemaExample id="components-navigation-header-bar/simple-header" />

## With Multiple Breadcrumbs [#with-multiple-breadcrumbs]

<SchemaExample id="components-navigation-header-bar/deep-navigation" />

## Schema [#schema]

```plaintext
interface Breadcrumb {
  label: string;                         // Breadcrumb text
  href?: string;                         // Link URL (optional for last item)
}

interface HeaderBarSchema {
  type: 'header-bar';
  
  // Breadcrumbs
  crumbs?: Breadcrumb[];                 // Breadcrumb items
  
  // Styling
  className?: string;                    // Tailwind CSS classes
  
  // Base properties
  id?: string;
  visible?: boolean | string;
  testId?: string;
}
```

## Examples [#examples]

### Application Header [#application-header]

<SchemaExample id="components-navigation-header-bar/app-navigation" />

### Settings Navigation [#settings-navigation]

<SchemaExample id="components-navigation-header-bar/settings-path" />

### Admin Panel [#admin-panel]

<SchemaExample id="components-navigation-header-bar/admin-breadcrumbs" />

## Usage Notes [#usage-notes]

* The Header Bar component includes a sidebar trigger button that works with the Sidebar component
* The last breadcrumb item is typically rendered as plain text (current page)
* All other breadcrumb items should have an `href` to enable navigation
* The component has a fixed height of 64px (`h-16`)
* Includes a vertical separator between the sidebar trigger and breadcrumbs

## Integration [#integration]

This component is designed to work with the sidebar layout pattern:

```plaintext
{
  type: 'div',
  children: [
    { type: 'sidebar', /* sidebar config */ },
    {
      type: 'div',
      className: 'flex-1',
      children: [
        { 
          type: 'header-bar',
          crumbs: [
            { label: 'Home', href: '#' },
            { label: 'Current' }
          ]
        },
        {
          type: 'main',
          className: 'p-6',
          children: [
            // Main content
          ]
        }
      ]
    }
  ]
}
```


# Alert Dialog





The Alert Dialog component is used to interrupt the user with important content and require a confirmation before proceeding.

## Basic Usage [#basic-usage]

<SchemaExample id="components-overlay-alert-dialog/basic-alert-dialog" />

## Variants [#variants]

<DemoGrid>
  <SchemaExample id="components-overlay-alert-dialog/destructive-action" />

  <SchemaExample id="components-overlay-alert-dialog/confirmation-dialog" />
</DemoGrid>

## Schema [#schema]

```plaintext
interface AlertDialogSchema {
  type: 'alert-dialog';
  title: string;                // Dialog title
  description: string;           // Dialog description
  
  // Trigger
  trigger: ComponentSchema;      // Component that triggers the dialog
  
  // Actions
  actions?: ComponentSchema[];   // Action buttons
  
  // Styling
  className?: string;
}
```

## Examples [#examples]

### With Custom Actions [#with-custom-actions]

<SchemaExample id="components-overlay-alert-dialog/custom-actions" />


# Context Menu





The Context Menu component displays a menu when right-clicking on an element.

## Basic Usage [#basic-usage]

<SchemaExample id="components-overlay-context-menu/basic-context-menu" />

## Schema [#schema]

```plaintext
interface ContextMenuItem {
  label?: string;
  value?: string;
  icon?: string;
  type?: 'separator';
  disabled?: boolean;
}

interface ContextMenuSchema {
  type: 'context-menu';
  trigger: ComponentSchema;       // Trigger element
  items: ContextMenuItem[];       // Menu items
  onSelect?: string | ActionConfig;
  className?: string;
}
```


# Dialog





## Examples [#examples]

<SchemaExample id="components-overlay-dialog/dialog-trigger" />

## Schema [#schema]

```plaintext
interface DialogSchema {
  type: 'dialog';
  trigger: SchemaNode;
  title?: string;
  description?: string;
  children: SchemaNode[];
  footer?: SchemaNode[];
}
```


# Drawer





## Examples [#examples]

<SchemaExample id="components-overlay-drawer/basic-drawer" />

## Schema [#schema]

```plaintext
interface DrawerSchema {
  type: 'drawer';
  trigger: SchemaNode;
  title?: string;
  children: SchemaNode[];
  side?: 'left' | 'right' | 'top' | 'bottom';
}
```


# Dropdown Menu





The Dropdown Menu component displays a list of actions or options when triggered.

## Basic Usage [#basic-usage]

<SchemaExample id="components-overlay-dropdown-menu/basic-dropdown-menu" />

## With Icons [#with-icons]

<SchemaExample id="components-overlay-dropdown-menu/with-icons" />

## Schema [#schema]

```plaintext
interface DropdownMenuItem {
  label?: string;
  value?: string;
  icon?: string;
  variant?: 'default' | 'destructive';
  type?: 'separator';
  disabled?: boolean;
}

interface DropdownMenuSchema {
  type: 'dropdown-menu';
  trigger: ComponentSchema;       // Trigger component
  items: DropdownMenuItem[];      // Menu items
  
  // Events
  onSelect?: string | ActionConfig;
  
  // Styling
  className?: string;
}
```


# Hover Card





The Hover Card component displays rich content when hovering over an element.

## Basic Usage [#basic-usage]

<SchemaExample id="components-overlay-hover-card/basic-hover-card" />

## Schema [#schema]

```plaintext
interface HoverCardSchema {
  type: 'hover-card';
  trigger: ComponentSchema;       // Trigger element
  content: ComponentSchema;       // Card content
  side?: 'top' | 'right' | 'bottom' | 'left';
  align?: 'start' | 'center' | 'end';
  openDelay?: number;             // Delay before opening (ms)
  closeDelay?: number;            // Delay before closing (ms)
  className?: string;
}
```


# Menubar





The Menubar component provides a horizontal menu bar similar to desktop applications.

## Basic Usage [#basic-usage]

<SchemaExample id="components-overlay-menubar/application-menubar" />

## Schema [#schema]

```plaintext
interface MenubarItem {
  label?: string;
  value?: string;
  icon?: string;
  shortcut?: string[];
  type?: 'separator';
  disabled?: boolean;
}

interface MenubarMenu {
  label: string;
  items: MenubarItem[];
}

interface MenubarSchema {
  type: 'menubar';
  menus: MenubarMenu[];           // Menu definitions
  
  // Events
  onSelect?: string | ActionConfig;
  
  // Styling
  className?: string;
}
```


# Popover





## Examples [#examples]

<SchemaExample id="components-overlay-popover/basic-popover" />

## Schema [#schema]

```plaintext
interface PopoverSchema {
  type: 'popover';
  trigger: SchemaNode;
  children: SchemaNode[];
  side?: 'top' | 'right' | 'bottom' | 'left';
}
```


# Sheet





The Sheet component displays content in a panel that slides in from the edge of the screen.

## Basic Usage [#basic-usage]

<SchemaExample id="components-overlay-sheet/basic-sheet" />

## Sides [#sides]

<DemoGrid>
  <SchemaExample id="components-overlay-sheet/left-side" />

  <SchemaExample id="components-overlay-sheet/right-side" />
</DemoGrid>

## Schema [#schema]

```plaintext
interface SheetSchema {
  type: 'sheet';
  trigger: ComponentSchema;       // Trigger component
  title?: string;                 // Sheet title
  description?: string;           // Sheet description
  content: ComponentSchema;       // Sheet content
  side?: 'left' | 'right' | 'top' | 'bottom';
  className?: string;
}
```


# Tooltip





## Examples [#examples]

<SchemaExample id="components-overlay-tooltip/basic-tooltip" />

## Schema [#schema]

```plaintext
interface TooltipSchema {
  type: 'tooltip';
  content: string;
  children: SchemaNode;
  side?: 'top' | 'right' | 'bottom' | 'left';
}
```