Skip to content

README.md

Latest commit

 

History

History
312 lines (237 loc) · 7.57 KB

README.md

File metadata and controls

312 lines (237 loc) · 7.57 KB

@object-ui/types

Pure TypeScript type definitions for Object UI - The Protocol Layer.

Features

  • 🎯 Complete Type Coverage - Every component has full TypeScript definitions
  • 🏛️ Built on @objectstack/spec - Extends the universal UI component specification
  • 📦 Minimal Dependencies - Only depends on @objectstack/spec (pure types)
  • 🔌 Framework Agnostic - Use with React, Vue, or any framework
  • 🌍 Backend Agnostic - Works with REST, GraphQL, ObjectQL, or local data
  • 🎨 Tailwind Native - Designed for Tailwind CSS styling
  • 📚 Comprehensive JSDoc - Every type is fully documented

Installation

npm install @object-ui/types
# or
yarn add @object-ui/types
# or
pnpm add @object-ui/types

Important: This package depends on @objectstack/spec which provides the foundational protocol.

Architecture: The Inheritance Chain

Object UI follows a strict "Protocol First" approach with a clear inheritance hierarchy:

@objectstack/spec (v2.0.1)          ← The "Highest Law" - Universal protocol
    ↓
UIComponent                         ← Base interface for all UI components
    ↓
BaseSchema (@object-ui/types)       ← ObjectUI extensions (visibleOn, hiddenOn, etc.)
    ↓
Specific Schemas                    ← Component implementations (ChartSchema, etc.)
    ↓
@object-ui/core (Engine)            ← Schema validation and expression evaluation
    ↓
@object-ui/react (Framework)        ← React renderer
    ↓
@object-ui/components (UI)          ← Shadcn/Tailwind implementation

This separation allows:

  • ✅ Multiple UI implementations (Shadcn, Material, Ant Design)
  • ✅ Multiple framework bindings (React, Vue, Svelte)
  • ✅ Multiple backend adapters (REST, GraphQL, ObjectQL)
  • ✅ Static analysis and validation without runtime dependencies
  • ✅ Compliance with the ObjectStack ecosystem standards

Usage

Basic Example

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

const loginForm: FormSchema = {
  type: 'form',
  fields: [
    {
      name: 'email',
      type: 'input',
      inputType: 'email',
      label: 'Email',
      required: true,
    },
    {
      name: 'password',
      type: 'input',
      inputType: 'password',
      label: 'Password',
      required: true,
    }
  ],
  submitLabel: 'Sign In'
};

Advanced Example

import type { DataTableSchema, FlexSchema, CardSchema } from '@object-ui/types';

const dashboard: CardSchema = {
  type: 'card',
  title: 'User Management',
  content: {
    type: 'data-table',
    columns: [
      { header: 'Name', accessorKey: 'name' },
      { header: 'Email', accessorKey: 'email' },
      { header: 'Role', accessorKey: 'role' }
    ],
    data: [], // Connected to data source
    pagination: true,
    searchable: true,
    selectable: true
  }
};

Type Narrowing

import type { AnySchema, SchemaByType } from '@object-ui/types';

function renderComponent(schema: AnySchema) {
  if (schema.type === 'input') {
    // TypeScript automatically narrows to InputSchema
    console.log(schema.placeholder);
  }
}

// Or use the utility type
type ButtonSchema = SchemaByType<'button'>;

Type Categories

Base Types

Foundation types that all components build upon:

  • BaseSchema - The base interface for all components
  • SchemaNode - Union type for schema nodes (objects, strings, numbers, etc.)
  • ComponentMeta - Metadata for component registration
  • ComponentInput - Input field definitions for designers/editors

Layout Components

Structure and organization:

  • ContainerSchema - Max-width container
  • FlexSchema - Flexbox layout
  • GridSchema - CSS Grid layout
  • CardSchema - Card container
  • TabsSchema - Tabbed interface

Form Components

User input and interaction:

  • FormSchema - Complete form with validation
  • InputSchema - Text input field
  • SelectSchema - Dropdown select
  • CheckboxSchema - Checkbox input
  • RadioGroupSchema - Radio button group
  • DatePickerSchema - Date selection
  • And 10+ more form components

Data Display Components

Information presentation:

  • DataTableSchema - Enterprise data table with sorting, filtering, pagination
  • TableSchema - Simple table
  • ListSchema - List with items
  • ChartSchema - Charts and graphs
  • TreeViewSchema - Hierarchical tree
  • TimelineSchema - Timeline visualization

Feedback Components

Status and progress:

  • LoadingSchema - Loading spinner
  • ProgressSchema - Progress bar
  • SkeletonSchema - Loading placeholder
  • ToastSchema - Toast notifications

Overlay Components

Modals and popovers:

  • DialogSchema - Modal dialog
  • SheetSchema - Side panel/drawer
  • PopoverSchema - Popover
  • TooltipSchema - Tooltip
  • DropdownMenuSchema - Dropdown menu

Navigation Components

Menus and navigation:

  • HeaderBarSchema - Top navigation bar
  • SidebarSchema - Side navigation
  • BreadcrumbSchema - Breadcrumb navigation
  • PaginationSchema - Pagination controls

Complex Components

Advanced composite components:

  • KanbanSchema - Kanban board
  • CalendarViewSchema - Calendar with events
  • FilterBuilderSchema - Advanced filter builder
  • CarouselSchema - Image/content carousel
  • ChatbotSchema - Chat interface

Data Management

Backend integration:

  • DataSource - Universal data adapter interface
  • QueryParams - Query parameters (OData-style)
  • QueryResult - Paginated query results
  • DataBinding - Data binding configuration

Design Principles

1. Protocol Agnostic

Types don't assume any specific backend:

interface DataSource<T = any> {
  find(resource: string, params?: QueryParams): Promise<QueryResult<T>>;
  create(resource: string, data: Partial<T>): Promise<T>;
  // Works with REST, GraphQL, ObjectQL, or anything
}

2. Tailwind Native

All components support className for Tailwind styling:

const button: ButtonSchema = {
  type: 'button',
  label: 'Click Me',
  className: 'bg-blue-500 hover:bg-blue-600 text-white font-bold py-2 px-4 rounded'
};

3. Type Safe

Full TypeScript support with discriminated unions:

type AnySchema = 
  | InputSchema 
  | ButtonSchema 
  | FormSchema 
  | /* 50+ more */;

function render(schema: AnySchema) {
  switch (schema.type) {
    case 'input': /* schema is InputSchema */ break;
    case 'button': /* schema is ButtonSchema */ break;
  }
}

4. Composable

Components can nest indefinitely:

const page: FlexSchema = {
  type: 'flex',
  direction: 'col',
  children: [
    { type: 'header-bar', title: 'My App' },
    {
      type: 'flex',
      direction: 'row',
      children: [
        { type: 'sidebar', nav: [...] },
        { type: 'container', children: [...] }
      ]
    }
  ]
};

Comparison

vs Amis Types

  • ✅ Lighter - No runtime dependencies
  • ✅ Tailwind Native - Built for Tailwind CSS
  • ✅ Better TypeScript - Full type inference
  • ✅ Framework Agnostic - Not tied to React

vs Formily Types

  • ✅ Full Pages - Not just forms, entire UIs
  • ✅ Simpler - More straightforward API
  • ✅ Better Docs - Comprehensive JSDoc

Contributing

We follow these constraints for this package:

  1. ZERO runtime dependencies - Only TypeScript types
  2. No React imports - Framework agnostic
  3. Comprehensive JSDoc - Every property documented
  4. Protocol first - Types define the contract

License

MIT

Links