Add @object-ui/types package - TypeScript protocol definitions

packages/types/.gitignore

@@ -0,0 +1,2 @@
+dist/
+node_modules/

packages/types/README.md

@@ -0,0 +1,304 @@
+# @object-ui/types
+
+Pure TypeScript type definitions for Object UI - **The Protocol Layer**.
+
+## Features
+
+- 🎯 **Complete Type Coverage** - Every component has full TypeScript definitions
+- 📦 **Zero Dependencies** - Pure types with no runtime dependencies
+- 🔌 **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
+
+```bash
+npm install @object-ui/types
+# or
+yarn add @object-ui/types
+# or
+pnpm add @object-ui/types
+```
+
+**Important:** This package has **ZERO runtime dependencies**. It's pure TypeScript types.
+
+## Philosophy
+
+Object UI follows a **"Protocol First"** approach:
+
+```
+@object-ui/types (Protocol)
+     ↓
+@object-ui/core (Engine)
+     ↓
+@object-ui/react (Framework)
+     ↓
+@object-ui/components (UI 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
+
+## Usage
+
+### Basic Example
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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:
+
+```typescript
+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:
+
+```typescript
+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:
+
+```typescript
+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:
+
+```typescript
+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
+
+- [Documentation](https://objectui.org/docs/types)
+- [GitHub](https://github.com/objectstack-ai/objectui)
+- [NPM](https://www.npmjs.com/package/@object-ui/types)

packages/types/examples/dashboard.ts

@@ -0,0 +1,88 @@
+/**
+ * Example: Dashboard Layout
+ * 
+ * This example demonstrates a complete dashboard layout with
+ * sidebar, header, and data table.
+ */
+
+import type { FlexSchema, SidebarSchema, HeaderBarSchema, CardSchema, DataTableSchema } from '../src/index';
+
+export const dashboardSchema: FlexSchema = {
+  type: 'flex',
+  direction: 'col',
+  className: 'h-screen',
+
+  children: [
+    // Header
+    {
+      type: 'header-bar',
+      title: 'Object UI Dashboard',
+      logo: '/logo.svg',
+      sticky: true,
+      right: [
+        {
+          type: 'button',
+          label: 'Profile',
+          variant: 'ghost',
+          icon: 'User'
+        }
+      ]
+    } as HeaderBarSchema,
+
+    // Main content with sidebar
+    {
+      type: 'flex',
+      direction: 'row',
+      className: 'flex-1',
+      children: [
+        // Sidebar
+        {
+          type: 'sidebar',
+          collapsible: true,
+          nav: [
+            { label: 'Dashboard', href: '/', icon: 'Home', active: true },
+            { label: 'Users', href: '/users', icon: 'Users' },
+            { label: 'Settings', href: '/settings', icon: 'Settings' }
+          ]
+        } as SidebarSchema,
+
+        // Main content area
+        {
+          type: 'container',
+          className: 'flex-1 p-6',
+          children: [
+            {
+              type: 'card',
+              title: 'User Management',
+              description: 'Manage your users and permissions',
+              content: {
+                type: 'data-table',
+                columns: [
+                  { header: 'ID', accessorKey: 'id', width: '80px' },
+                  { header: 'Name', accessorKey: 'name' },
+                  { header: 'Email', accessorKey: 'email' },
+                  { header: 'Role', accessorKey: 'role' },
+                  { header: 'Status', accessorKey: 'status' }
+                ],
+                data: [
+                  { id: 1, name: 'John Doe', email: 'john@example.com', role: 'Admin', status: 'Active' },
+                  { id: 2, name: 'Jane Smith', email: 'jane@example.com', role: 'User', status: 'Active' },
+                  { id: 3, name: 'Bob Johnson', email: 'bob@example.com', role: 'User', status: 'Inactive' }
+                ],
+                pagination: true,
+                pageSize: 10,
+                searchable: true,
+                selectable: true,
+                sortable: true,
+                exportable: true,
+                rowActions: true,
+                onRowEdit: (row) => console.log('Edit:', row),
+                onRowDelete: (row) => console.log('Delete:', row)
+              } as DataTableSchema
+            } as CardSchema
+          ]
+        }
+      ]
+    }
+  ]
+};