Integrate ObjectStack Protocol (spec@0.1.2, client@0.1.1) into platform core

MIGRATION_GUIDE_OBJECTSTACK.md

@@ -0,0 +1,162 @@
+# Migration Guide: ObjectStack Integration
+
+This guide helps you migrate to the new ObjectStack-integrated version of ObjectUI.
+
+## What Changed
+
+### 1. New Dependencies
+
+The following packages now have ObjectStack dependencies:
+
+- `@object-ui/types` → depends on `@objectstack/spec@^0.1.2`
+- `@object-ui/core` → depends on `@objectstack/client@^0.1.1` and `@objectstack/spec@^0.1.2`
+- `@object-ui/data-objectql` → depends on `@objectstack/client@^0.1.1`
+
+### 2. New Data Source Adapter
+
+A new `ObjectStackAdapter` is now available for seamless integration with ObjectStack Protocol servers.
+
+## For Users
+
+### Using the ObjectStack Adapter
+
+If you want to connect to an ObjectStack backend:
+
+```typescript
+import { createObjectStackAdapter } from '@object-ui/core';
+
+const dataSource = createObjectStackAdapter({
+  baseUrl: 'https://your-objectstack-server.com',
+  token: 'your-auth-token', // optional
+});
+
+// Use it in your components
+const schema = {
+  type: 'data-table',
+  dataSource,
+  resource: 'users',
+  columns: [
+    { header: 'Name', accessorKey: 'name' },
+    { header: 'Email', accessorKey: 'email' },
+  ]
+};
+```
+
+### Migrating from Other Data Sources
+
+The `ObjectStackAdapter` implements the standard `DataSource` interface, so it's a drop-in replacement:
+
+```typescript
+// Before
+const dataSource = createRESTDataSource({ baseUrl: '...' });
+
+// After
+const dataSource = createObjectStackAdapter({ baseUrl: '...' });
+
+// Everything else stays the same!
+```
+
+## For Package Maintainers
+
+### Installation
+
+After pulling the latest changes, run:
+
+```bash
+pnpm install
+```
+
+This will install the new `@objectstack/spec` and `@objectstack/client` dependencies.
+
+### Building
+
+The build process remains the same:
+
+```bash
+pnpm build
+```
+
+### Testing
+
+All existing tests should pass:
+
+```bash
+pnpm test
+```
+
+## Breaking Changes
+
+**None!** This is a backward-compatible addition.
+
+- Existing code continues to work unchanged
+- The ObjectStack adapter is an optional feature
+- No changes to public APIs or type definitions
+- All tests pass without modification
+
+## New Features
+
+### 1. ObjectStack Adapter
+
+- Full CRUD operations (find, findOne, create, update, delete)
+- Bulk operations (createMany, updateMany, deleteMany)
+- Auto-discovery of server capabilities
+- Query parameter translation (OData-style → ObjectStack)
+
+### 2. Type Safety
+
+- Full TypeScript support with the `@objectstack/spec` protocol
+- Type inference for query results
+- Proper error handling with typed errors
+
+### 3. Documentation
+
+- New adapter README with usage examples
+- Comprehensive JSDoc comments
+- Integration examples
+
+## For Contributors
+
+### Where to Find Code
+
+- **Adapter Implementation**: `packages/core/src/adapters/objectstack-adapter.ts`
+- **Adapter Documentation**: `packages/core/src/adapters/README.md`
+- **Type Definitions**: `@objectstack/spec` (external package)
+- **Client SDK**: `@objectstack/client` (external package)
+
+### Architecture
+
+The integration follows this hierarchy:
+
+```
+@objectstack/spec (protocol specification)
+    ↓
+@object-ui/types (ObjectUI type extensions)
+    ↓
+@object-ui/core (engine + adapters)
+    ↓
+@object-ui/react (React bindings)
+    ↓
+@object-ui/components (Shadcn/Tailwind UI)
+```
+
+## Support
+
+If you encounter any issues:
+
+1. Check the [adapter README](packages/core/src/adapters/README.md)
+2. Review the [ObjectStack spec](https://github.com/objectstack-ai/spec)
+3. Open an issue on GitHub
+
+## Version Compatibility
+
+| Package | Version | ObjectStack Spec | ObjectStack Client |
+|---------|---------|------------------|-------------------|
+| @object-ui/types | 0.3.0+ | ^0.1.2 | - |
+| @object-ui/core | 0.3.0+ | ^0.1.2 | ^0.1.1 |
+| @object-ui/data-objectql | 0.3.0+ | - | ^0.1.1 |
+
+## Next Steps
+
+- Explore the [ObjectStack Protocol](https://github.com/objectstack-ai/spec)
+- Try the adapter in your application
+- Provide feedback on the integration

apps/site/package.json

@@ -7,7 +7,7 @@
     "dev": "next dev",
     "build": "next build",
     "start": "next start",
-    "lint": "next lint"
+    "lint": "eslint ."
   },
   "dependencies": {
     "fumadocs-core": "^16.4.7",

package.json

@@ -21,7 +21,7 @@
     "showcase": "node packages/cli/dist/cli.js showcase",
     "start": "pnpm dev",
     "build": "pnpm --filter './packages/*' -r build && pnpm --filter './examples/*' -r build",
-    "pretest": "pnpm --filter @objectstack/spec build && pnpm --filter @object-ui/types build && pnpm --filter @object-ui/core build && pnpm --filter @object-ui/react build && pnpm --filter @object-ui/components build && pnpm --filter @object-ui/plugin-kanban build && pnpm --filter @object-ui/plugin-charts build",
+    "pretest": "pnpm --filter @object-ui/types build && pnpm --filter @object-ui/core build && pnpm --filter @object-ui/react build && pnpm --filter @object-ui/components build && pnpm --filter @object-ui/plugin-kanban build && pnpm --filter @object-ui/plugin-charts build",
     "test": "vitest run",
     "site:dev": "pnpm --filter @objectui/site dev",
     "site:build": "pnpm --filter @objectui/site build",

packages/core/package.json

@@ -22,6 +22,8 @@
   },
   "dependencies": {
     "@object-ui/types": "workspace:*",
+    "@objectstack/client": "^0.1.1",
+    "@objectstack/spec": "^0.1.2",
     "lodash": "^4.17.21",
     "zod": "^3.22.4"
   },

packages/core/src/adapters/README.md

@@ -0,0 +1,141 @@
+# Data Source Adapters
+
+This directory contains data source adapters that bridge various backend protocols with the ObjectUI DataSource interface.
+
+## ObjectStack Adapter
+
+The `ObjectStackAdapter` provides seamless integration with ObjectStack Protocol servers.
+
+### Features
+
+- ✅ Full CRUD operations (find, findOne, create, update, delete)
+- ✅ Bulk operations (createMany, updateMany, deleteMany)
+- ✅ Auto-discovery of server capabilities
+- ✅ Query parameter translation (OData-style → ObjectStack)
+- ✅ Proper error handling
+- ✅ TypeScript types
+
+### Usage
+
+```typescript
+import { createObjectStackAdapter } from '@object-ui/core';
+
+// Create the adapter
+const dataSource = createObjectStackAdapter({
+  baseUrl: 'https://api.example.com',
+  token: 'your-auth-token', // Optional
+});
+
+// Use it with ObjectUI components
+const schema = {
+  type: 'data-table',
+  dataSource,
+  resource: 'users',
+  columns: [
+    { header: 'Name', accessorKey: 'name' },
+    { header: 'Email', accessorKey: 'email' },
+  ]
+};
+```
+
+### Advanced Usage
+
+```typescript
+import { ObjectStackAdapter } from '@object-ui/core';
+
+const adapter = new ObjectStackAdapter({
+  baseUrl: 'https://api.example.com',
+  token: process.env.API_TOKEN,
+  fetch: customFetch // Optional: use custom fetch (e.g., Next.js fetch)
+});
+
+// Manually connect (optional, auto-connects on first request)
+await adapter.connect();
+
+// Query with filters
+const result = await adapter.find('tasks', {
+  $filter: { 
+    status: 'active',
+    priority: { $gte: 2 }
+  },
+  $orderby: { createdAt: 'desc' },
+  $top: 20,
+  $skip: 0
+});
+
+// Access the underlying client for advanced operations
+const client = adapter.getClient();
+const metadata = await client.meta.getObject('task');
+```
+
+### Query Parameter Mapping
+
+The adapter automatically converts ObjectUI query parameters (OData-style) to ObjectStack protocol:
+
+| ObjectUI ($) | ObjectStack | Description |
+|--------------|-------------|-------------|
+| `$select` | `select` | Field selection |
+| `$filter` | `filters` | Filter conditions |
+| `$orderby` | `sort` | Sort order |
+| `$skip` | `skip` | Pagination offset |
+| `$top` | `top` | Limit records |
+
+### Example with Sorting
+
+```typescript
+// OData-style
+await dataSource.find('users', {
+  $orderby: { 
+    createdAt: 'desc',
+    name: 'asc'
+  }
+});
+
+// Converted to ObjectStack: ['-createdAt', 'name']
+```
+
+## Creating Custom Adapters
+
+To create a custom adapter, implement the `DataSource<T>` interface:
+
+```typescript
+import type { DataSource, QueryParams, QueryResult } from '@object-ui/types';
+
+export class MyCustomAdapter<T = any> implements DataSource<T> {
+  async find(resource: string, params?: QueryParams): Promise<QueryResult<T>> {
+    // Your implementation
+  }
+
+  async findOne(resource: string, id: string | number): Promise<T | null> {
+    // Your implementation
+  }
+
+  async create(resource: string, data: Partial<T>): Promise<T> {
+    // Your implementation
+  }
+
+  async update(resource: string, id: string | number, data: Partial<T>): Promise<T> {
+    // Your implementation
+  }
+
+  async delete(resource: string, id: string | number): Promise<boolean> {
+    // Your implementation
+  }
+
+  // Optional: bulk operations
+  async bulk?(resource: string, operation: string, data: Partial<T>[]): Promise<T[]> {
+    // Your implementation
+  }
+}
+```
+
+## Available Adapters
+
+- **ObjectStackAdapter** - For ObjectStack Protocol servers
+- More adapters coming soon (REST, GraphQL, Supabase, Firebase, etc.)
+
+## Related Packages
+
+- `@objectstack/client` - ObjectStack Client SDK
+- `@objectstack/spec` - ObjectStack Protocol Specification
+- `@object-ui/types` - ObjectUI Type Definitions

packages/core/src/adapters/index.ts

@@ -0,0 +1,9 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+export { ObjectStackAdapter, createObjectStackAdapter } from './objectstack-adapter';