@object-ui/plugin-view

Object View plugin for Object UI - Unified component for displaying and managing ObjectQL data with automatic form and grid generation.

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
• Validation - Schema-based validation
• ObjectQL Integration - Native ObjectStack support
• View Controls - View switcher, filter UI, and sort UI components

Installation

pnpm add @object-ui/plugin-view

Usage

Automatic Registration (Side-Effect Import)

// In your app entry point (e.g., App.tsx or main.tsx)
import '@object-ui/plugin-view';

// Now you can use view types in your schemas
const schema = {
  type: 'object-view',
  object: 'users',
  viewMode: 'grid'
};

Manual Registration

import { viewComponents } from '@object-ui/plugin-view';
import { ComponentRegistry } from '@object-ui/core';

// Register view components
Object.entries(viewComponents).forEach(([type, component]) => {
  ComponentRegistry.register(type, component);
});

Schema API

ObjectView

Unified view component for ObjectQL objects:

{
  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
}

ViewSwitcher

Toggle between multiple view configurations:

{
  type: 'view-switcher',
  views: [
    { type: 'grid', label: 'Grid', schema: { type: 'text', content: 'Grid content' } },
    { type: 'kanban', label: 'Kanban', schema: { type: 'text', content: 'Kanban content' } }
  ],
  defaultView: 'grid',
  variant: 'tabs',
  position: 'top',
  persistPreference: true,
  storageKey: 'my-view-switcher'
}

FilterUI

Render a filter toolbar with multiple field types:

{
  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' }
  ]
}

SortUI

Configure sorting with dropdowns or buttons:

{
  type: 'sort-ui',
  variant: 'dropdown',
  multiple: true,
  fields: [
    { field: 'name', label: 'Name' },
    { field: 'created_at', label: 'Created At' }
  ],
  sort: [{ field: 'name', direction: 'asc' }]
}

Examples

Grid View

Display objects in a data grid:

const schema = {
  type: 'object-view',
  object: 'users',
  viewMode: 'grid',
  fields: ['name', 'email', 'role', 'created_at'],
  dataSource: myDataSource
};

Form View

Create or edit objects with a form:

const schema = {
  type: 'object-view',
  object: 'users',
  viewMode: 'form',
  mode: 'create',
  fields: ['name', 'email', 'role'],
  onSubmit: (data) => {
    console.log('Form submitted:', data);
  }
};

Detail View

Display a single object's details:

const schema = {
  type: 'object-view',
  object: 'users',
  viewMode: 'detail',
  recordId: '123',
  fields: ['name', 'email', 'role', 'bio', 'created_at']
};

CRUD Operations

Create

const schema = {
  type: 'object-view',
  object: 'products',
  viewMode: 'form',
  mode: 'create',
  onCreate: async (data) => {
    const newProduct = await dataSource.create('products', data);
    console.log('Created:', newProduct);
  }
};

Read/List

const schema = {
  type: 'object-view',
  object: 'products',
  viewMode: 'grid',
  pagination: true,
  searchable: true,
  filters: {
    category: 'electronics'
  }
};

Update

const schema = {
  type: 'object-view',
  object: 'products',
  viewMode: 'form',
  mode: 'edit',
  recordId: '123',
  onUpdate: async (id, data) => {
    await dataSource.update('products', id, data);
    console.log('Updated product:', id);
  }
};

Delete

const schema = {
  type: 'object-view',
  object: 'products',
  viewMode: 'grid',
  enableDelete: true,
  onDelete: async (id) => {
    await dataSource.delete('products', id);
    console.log('Deleted product:', id);
  }
};

Integration with ObjectQL

The plugin works seamlessly with ObjectStack:

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,
  pagination: {
    pageSize: 25
  }
};

Field Configuration

Customize field display and behavior:

const schema = {
  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,
      validation: [
        { type: 'email', message: 'Invalid email format' }
      ]
    },
    role: {
      label: 'User Role',
      type: 'select',
      options: [
        { label: 'Admin', value: 'admin' },
        { label: 'User', value: 'user' },
        { label: 'Guest', value: 'guest' }
      ]
    }
  }
};

Advanced Features

Nested Objects

const schema = {
  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

const schema = {
  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' }
  ]
};

TypeScript Support

import type { ObjectViewSchema } from '@object-ui/plugin-view';

const userView: ObjectViewSchema = {
  type: 'object-view',
  object: 'users',
  viewMode: 'grid',
  fields: ['name', 'email', 'role']
};

Compatibility

• React: 18.x or 19.x
• Node.js: ≥ 18
• TypeScript: ≥ 5.0 (strict mode)
• @objectstack/spec: ^3.3.0
• @objectstack/client: ^3.3.0
• Tailwind CSS: ≥ 3.4 (for packages with UI)

Links

• 📚 Documentation
• 📦 npm package
• 📝 Changelog
• 🐛 Report an issue
• 🤝 Contributing Guide
• 🗺️ Roadmap

License

MIT — see LICENSE.

Multi-view UX

In addition to the renderer, the package ships two components that wrap an object's set of saved views (Airtable / Notion-style):

• <ViewTabBar> — a horizontal strip of view tabs. Per-tab chevron menu exposes rename, pin, duplicate, set default, delete, and "Manage all views…". An overflow … N more dropdown surfaces the remaining views and links to the management dialog. (In-place tab drag is intentionally disabled — reordering happens in <ManageViewsDialog> to avoid the ambiguity of "does dragging the visible tab change the global order or just the visible subset?".)
• <ManageViewsDialog> — a Shadcn Dialog containing a vertical sortable list of every view (visible + overflow + metadata-defined). Supports drag-reorder, search, inline rename, pin / set-default toggles, and a per-row ⋯ action menu (rename, duplicate, edit configuration, set default, pin/unpin, delete). Open it from the chevron menu's "Manage all views…" item or from the header of the overflow … N more dropdown.

Both components share the same callback surface (onRenameView, onDeleteView, onReorderViews, …) so a host like @object-ui/app-shell's ObjectView wires the same set of handlers into both. View ordering is persisted to localStorage under viewOrder:{objectName} and, for backend-saved views, also written back as sortOrder.