@object-ui/core 0.3.0 → 0.3.1

package/src/actions/ActionRunner.ts

@@ -0,0 +1,195 @@
+/**
+ * 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.
+ */
+
+/**
+ * @object-ui/core - Action Runner
+ * 
+ * Executes actions defined in ActionSchema and EventHandler.
+ */
+
+import { ExpressionEvaluator } from '../evaluator/ExpressionEvaluator';
+
+export interface ActionResult {
+  success: boolean;
+  data?: any;
+  error?: string;
+  reload?: boolean;
+  close?: boolean;
+  redirect?: string;
+}
+
+export interface ActionContext {
+  data?: Record<string, any>;
+  record?: any;
+  user?: any;
+  [key: string]: any;
+}
+
+export type ActionHandler = (
+  action: any,
+  context: ActionContext
+) => Promise<ActionResult> | ActionResult;
+
+export class ActionRunner {
+  private handlers = new Map<string, ActionHandler>();
+  private evaluator: ExpressionEvaluator;
+  private context: ActionContext;
+
+  constructor(context: ActionContext = {}) {
+    this.context = context;
+    this.evaluator = new ExpressionEvaluator(context);
+  }
+
+  registerHandler(actionName: string, handler: ActionHandler): void {
+    this.handlers.set(actionName, handler);
+  }
+
+  async execute(action: any): Promise<ActionResult> {
+    try {
+      if (action.condition) {
+        const shouldExecute = this.evaluator.evaluateCondition(action.condition);
+        if (!shouldExecute) {
+          return { success: false, error: 'Action condition not met' };
+        }
+      }
+
+      if (action.disabled) {
+        const isDisabled = typeof action.disabled === 'string'
+          ? this.evaluator.evaluateCondition(action.disabled)
+          : action.disabled;
+        
+        if (isDisabled) {
+          return { success: false, error: 'Action is disabled' };
+        }
+      }
+
+      if (action.type === 'action' || action.actionType) {
+        return await this.executeActionSchema(action);
+      } else if (action.type === 'navigation' || action.navigate) {
+        return await this.executeNavigation(action);
+      } else if (action.type === 'api' || action.api) {
+        return await this.executeAPI(action);
+      } else if (action.onClick) {
+        await action.onClick();
+        return { success: true };
+      }
+
+      return { success: false, error: 'Unknown action type' };
+    } catch (error) {
+      return { success: false, error: (error as Error).message };
+    }
+  }
+
+  private async executeActionSchema(action: any): Promise<ActionResult> {
+    const result: ActionResult = { success: true };
+
+    if (action.confirmText) {
+      const confirmed = await this.showConfirmation(action.confirmText);
+      if (!confirmed) {
+        return { success: false, error: 'Action cancelled by user' };
+      }
+    }
+
+    if (action.api) {
+      const apiResult = await this.executeAPI(action);
+      if (!apiResult.success) return apiResult;
+      result.data = apiResult.data;
+    }
+
+    if (action.onClick) {
+      await action.onClick();
+    }
+
+    result.reload = action.reload !== false;
+    result.close = action.close !== false;
+
+    if (action.redirect) {
+      result.redirect = this.evaluator.evaluate(action.redirect) as string;
+    }
+
+    return result;
+  }
+
+  /**
+   * Execute navigation action
+   */
+  private async executeNavigation(action: any): Promise<ActionResult> {
+    const nav = action.navigate || action;
+    const to = this.evaluator.evaluate(nav.to) as string;
+
+    // Validate URL to prevent javascript: or data: schemes
+    const isValidUrl = typeof to === 'string' && (
+      to.startsWith('http://') || 
+      to.startsWith('https://') || 
+      to.startsWith('/') || 
+      to.startsWith('./')
+    );
+
+    if (!isValidUrl) {
+      return {
+        success: false,
+        error: 'Invalid URL scheme. Only http://, https://, and relative URLs are allowed.'
+      };
+    }
+
+    if (nav.external) {
+      window.open(to, '_blank', 'noopener,noreferrer');
+    } else {
+      return { success: true, redirect: to };
+    }
+
+    return { success: true };
+  }
+
+  private async executeAPI(action: any): Promise<ActionResult> {
+    const apiConfig = action.api;
+    
+    if (typeof apiConfig === 'string') {
+      try {
+        const response = await fetch(apiConfig, {
+          method: action.method || 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(this.context.data || {})
+        });
+
+        if (!response.ok) {
+          throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+        }
+
+        const data = await response.json();
+        return { success: true, data };
+      } catch (error) {
+        return { success: false, error: (error as Error).message };
+      }
+    }
+
+    return { success: false, error: 'Complex API configuration not yet implemented' };
+  }
+
+  private async showConfirmation(message: string): Promise<boolean> {
+    const evaluatedMessage = this.evaluator.evaluate(message) as string;
+    return window.confirm(evaluatedMessage);
+  }
+
+  updateContext(newContext: Partial<ActionContext>): void {
+    this.context = { ...this.context, ...newContext };
+    this.evaluator.updateContext(newContext);
+  }
+
+  getContext(): ActionContext {
+    return this.context;
+  }
+}
+
+export async function executeAction(
+  action: any,
+  context: ActionContext = {}
+): Promise<ActionResult> {
+  const runner = new ActionRunner(context);
+  return await runner.execute(action);
+}

package/src/actions/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 * from './ActionRunner';

package/src/adapters/README.md

@@ -0,0 +1,180 @@
+# 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 (MongoDB-like operators)
+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');
+```
+
+### Filter Conversion
+
+The adapter automatically converts MongoDB-like filter operators to **ObjectStack FilterNode AST format**. This ensures compatibility with the latest ObjectStack Protocol (v0.1.2+).
+
+#### Supported Filter Operators
+
+| MongoDB Operator | ObjectStack Operator | Example |
+|------------------|---------------------|---------|
+| `$eq` or simple value | `=` | `{ status: 'active' }` → `['status', '=', 'active']` |
+| `$ne` | `!=` | `{ status: { $ne: 'archived' } }` → `['status', '!=', 'archived']` |
+| `$gt` | `>` | `{ age: { $gt: 18 } }` → `['age', '>', 18]` |
+| `$gte` | `>=` | `{ age: { $gte: 18 } }` → `['age', '>=', 18]` |
+| `$lt` | `<` | `{ age: { $lt: 65 } }` → `['age', '<', 65]` |
+| `$lte` | `<=` | `{ age: { $lte: 65 } }` → `['age', '<=', 65]` |
+| `$in` | `in` | `{ status: { $in: ['active', 'pending'] } }` → `['status', 'in', ['active', 'pending']]` |
+| `$nin` / `$notin` | `notin` | `{ status: { $nin: ['archived'] } }` → `['status', 'notin', ['archived']]` |
+| `$contains` / `$regex` | `contains` | `{ name: { $contains: 'John' } }` → `['name', 'contains', 'John']` |
+| `$startswith` | `startswith` | `{ email: { $startswith: 'admin' } }` → `['email', 'startswith', 'admin']` |
+| `$between` | `between` | `{ age: { $between: [18, 65] } }` → `['age', 'between', [18, 65]]` |
+
+#### Complex Filter Examples
+
+**Multiple conditions** are combined with `'and'`:
+
+```typescript
+// Input
+$filter: {
+  age: { $gte: 18, $lte: 65 },
+  status: 'active'
+}
+
+// Converted to AST
+['and', 
+  ['age', '>=', 18],
+  ['age', '<=', 65],
+  ['status', '=', 'active']
+]
+```
+
+### Query Parameter Mapping
+
+The adapter automatically converts ObjectUI query parameters (OData-style) to ObjectStack protocol:
+
+| ObjectUI ($) | ObjectStack | Description |
+|--------------|-------------|-------------|
+| `$select` | `select` | Field selection |
+| `$filter` | `filters` (AST) | Filter conditions (converted to FilterNode AST) |
+| `$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

package/src/adapters/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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';

package/src/adapters/index.js

@@ -0,0 +1,10 @@
+/**
+ * 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';
+// Adapters have been moved to separate packages (e.g. @object-ui/data-objectstack)

package/src/adapters/index.ts

@@ -0,0 +1,10 @@
+/**
+ * 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';
+// Adapters have been moved to separate packages (e.g. @object-ui/data-objectstack)

package/src/builder/schema-builder.d.ts

@@ -1,3 +1,10 @@
+/**
+ * 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.
+ */
 /**
  * @object-ui/core - Schema Builder
  *

package/src/builder/schema-builder.js

@@ -1,11 +1,9 @@
 /**
- * @object-ui/core - Schema Builder
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
  *
- * Fluent API for building schemas programmatically.
- * Provides type-safe builder functions for common schema patterns.
- *
- * @module builder
- * @packageDocumentation
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
  */
 /**
  * Base builder class

package/src/builder/schema-builder.ts

@@ -1,3 +1,11 @@
+/**
+ * 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.
+ */
+
 /**
  * @object-ui/core - Schema Builder
  * 

package/src/evaluator/ExpressionContext.ts

@@ -0,0 +1,118 @@
+/**
+ * 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.
+ */
+
+/**
+ * @object-ui/core - Expression Context
+ * 
+ * Manages variable scope and data context for expression evaluation.
+ * 
+ * @module evaluator
+ * @packageDocumentation
+ */
+
+/**
+ * Expression context for variable resolution
+ */
+export class ExpressionContext {
+  private scopes: Map<string, any>[] = [];
+
+  constructor(initialData: Record<string, any> = {}) {
+    this.scopes.push(new Map(Object.entries(initialData)));
+  }
+
+  /**
+   * Push a new scope onto the context stack
+   */
+  pushScope(data: Record<string, any>): void {
+    this.scopes.push(new Map(Object.entries(data)));
+  }
+
+  /**
+   * Pop the current scope from the context stack
+   */
+  popScope(): void {
+    if (this.scopes.length > 1) {
+      this.scopes.pop();
+    }
+  }
+
+  /**
+   * Get a variable value from the context
+   * Searches from innermost to outermost scope
+   */
+  get(path: string): any {
+    // Split path by dots for nested access
+    const parts = path.split('.');
+    const varName = parts[0];
+
+    // Search scopes from innermost to outermost
+    for (let i = this.scopes.length - 1; i >= 0; i--) {
+      if (this.scopes[i].has(varName)) {
+        let value = this.scopes[i].get(varName);
+        
+        // Navigate nested path
+        for (let j = 1; j < parts.length; j++) {
+          if (value && typeof value === 'object') {
+            value = value[parts[j]];
+          } else {
+            return undefined;
+          }
+        }
+        
+        return value;
+      }
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Set a variable value in the current scope
+   */
+  set(name: string, value: any): void {
+    if (this.scopes.length > 0) {
+      this.scopes[this.scopes.length - 1].set(name, value);
+    }
+  }
+
+  /**
+   * Check if a variable exists in any scope
+   */
+  has(name: string): boolean {
+    const varName = name.split('.')[0];
+    for (let i = this.scopes.length - 1; i >= 0; i--) {
+      if (this.scopes[i].has(varName)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Get all variables from all scopes as a flat object
+   */
+  toObject(): Record<string, any> {
+    const result: Record<string, any> = {};
+    // Merge from outermost to innermost (later scopes override earlier ones)
+    for (const scope of this.scopes) {
+      for (const [key, value] of scope.entries()) {
+        result[key] = value;
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Create a child context with additional data
+   */
+  createChild(data: Record<string, any> = {}): ExpressionContext {
+    const child = new ExpressionContext();
+    child.scopes = [...this.scopes, new Map(Object.entries(data))];
+    return child;
+  }
+}