@object-ui/core 3.0.3 → 3.1.0

package/src/data-scope/ViewDataProvider.ts

@@ -0,0 +1,282 @@
+/**
+ * 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 - View Data Provider
+ *
+ * Resolves @objectstack/spec ViewData discriminated union into
+ * a unified data access interface. Supports three data modes:
+ *
+ * 1. 'object' — Metadata-driven via ObjectStack API (object name → fields/records)
+ * 2. 'api' — Custom REST API endpoints (read/write URLs)
+ * 3. 'value' — Static data (pre-loaded items array)
+ *
+ * @module data-scope
+ * @packageDocumentation
+ */
+
+/** ViewData union — matches @objectstack/spec ViewDataSchema */
+export type ViewDataConfig =
+  | { provider: 'object'; object: string }
+  | {
+      provider: 'api';
+      read: { url: string; method?: string; headers?: Record<string, string> };
+      write?: { url: string; method?: string; headers?: Record<string, string> };
+    }
+  | { provider: 'value'; items: any[] };
+
+/** Element-level data source — matches @objectstack/spec ElementDataSourceSchema */
+export interface ElementDataSourceConfig {
+  object: string;
+  view?: string;
+  filter?: Record<string, any>;
+  sort?: Array<{ field: string; order: 'asc' | 'desc' }>;
+  limit?: number;
+}
+
+/** Fetcher interface — consumers provide the actual fetch implementation */
+export interface DataFetcher {
+  /** Fetch records for an object */
+  fetchRecords(
+    object: string,
+    options?: {
+      filter?: Record<string, any>;
+      sort?: Array<{ field: string; order: 'asc' | 'desc' }>;
+      limit?: number;
+      offset?: number;
+      fields?: string[];
+    },
+  ): Promise<{ records: any[]; total: number }>;
+
+  /** Fetch object metadata (fields, etc.) */
+  fetchMetadata?(object: string): Promise<{
+    name: string;
+    label?: string;
+    fields: Array<{
+      name: string;
+      label?: string;
+      type: string;
+      required?: boolean;
+    }>;
+  }>;
+
+  /** Fetch from a custom API URL */
+  fetchUrl?(
+    url: string,
+    options?: {
+      method?: string;
+      headers?: Record<string, string>;
+      body?: any;
+    },
+  ): Promise<any>;
+}
+
+/** Resolved data result */
+export interface ResolvedData {
+  /** Data records */
+  records: any[];
+  /** Total record count (for pagination) */
+  total: number;
+  /** Object metadata (if available) */
+  metadata?: {
+    name: string;
+    label?: string;
+    fields: Array<{
+      name: string;
+      label?: string;
+      type: string;
+      required?: boolean;
+    }>;
+  };
+  /** Provider type */
+  provider: 'object' | 'api' | 'value';
+  /** Loading state */
+  loading: boolean;
+  /** Error */
+  error?: string;
+}
+
+/** Extract records array from various common API response shapes */
+function extractRecords(data: any): any[] {
+  if (Array.isArray(data)) return data;
+  if (Array.isArray(data?.records)) return data.records;
+  if (Array.isArray(data?.data)) return data.data;
+  if (Array.isArray(data?.items)) return data.items;
+  return [];
+}
+
+/**
+ * Resolves ViewData configuration into actual data via a pluggable fetcher.
+ *
+ * @example
+ * ```ts
+ * const provider = new ViewDataProvider(myFetcher);
+ * const data = await provider.resolve({ provider: 'object', object: 'Account' });
+ * ```
+ */
+export class ViewDataProvider {
+  private fetcher: DataFetcher | null = null;
+
+  constructor(fetcher?: DataFetcher) {
+    this.fetcher = fetcher ?? null;
+  }
+
+  /** Set the data fetcher implementation */
+  setFetcher(fetcher: DataFetcher): void {
+    this.fetcher = fetcher;
+  }
+
+  /** Resolve ViewData config into actual data */
+  async resolve(
+    config: ViewDataConfig,
+    options?: {
+      filter?: Record<string, any>;
+      sort?: Array<{ field: string; order: 'asc' | 'desc' }>;
+      limit?: number;
+      offset?: number;
+      fields?: string[];
+    },
+  ): Promise<ResolvedData> {
+    switch (config.provider) {
+      case 'value':
+        return this.resolveValue(config);
+      case 'api':
+        return this.resolveApi(config);
+      case 'object':
+        return this.resolveObject(config, options);
+      default:
+        return {
+          records: [],
+          total: 0,
+          provider: 'value' as const,
+          loading: false,
+          error: `Unknown data provider: ${(config as any).provider}`,
+        };
+    }
+  }
+
+  /** Resolve static value data */
+  private resolveValue(config: {
+    provider: 'value';
+    items: any[];
+  }): ResolvedData {
+    const items = Array.isArray(config.items) ? config.items : [];
+    return {
+      records: items,
+      total: items.length,
+      provider: 'value',
+      loading: false,
+    };
+  }
+
+  /** Resolve API-based data */
+  private async resolveApi(config: {
+    provider: 'api';
+    read: { url: string; method?: string; headers?: Record<string, string> };
+  }): Promise<ResolvedData> {
+    if (!this.fetcher?.fetchUrl) {
+      return {
+        records: [],
+        total: 0,
+        provider: 'api',
+        loading: false,
+        error: 'No fetchUrl implementation available for API data provider',
+      };
+    }
+
+    try {
+      const data = await this.fetcher.fetchUrl(config.read.url, {
+        method: config.read.method,
+        headers: config.read.headers,
+      });
+
+      // Handle common response shapes
+      const records = extractRecords(data);
+      const total = data?.total ?? data?.count ?? records.length;
+
+      return {
+        records,
+        total,
+        provider: 'api',
+        loading: false,
+      };
+    } catch (error) {
+      return {
+        records: [],
+        total: 0,
+        provider: 'api',
+        loading: false,
+        error: (error as Error).message,
+      };
+    }
+  }
+
+  /** Resolve object-based data (metadata-driven) */
+  private async resolveObject(
+    config: { provider: 'object'; object: string },
+    options?: {
+      filter?: Record<string, any>;
+      sort?: Array<{ field: string; order: 'asc' | 'desc' }>;
+      limit?: number;
+      offset?: number;
+      fields?: string[];
+    },
+  ): Promise<ResolvedData> {
+    if (!this.fetcher) {
+      return {
+        records: [],
+        total: 0,
+        provider: 'object',
+        loading: false,
+        error: 'No data fetcher configured for object data provider',
+      };
+    }
+
+    try {
+      // Fetch metadata if available
+      let metadata: ResolvedData['metadata'];
+      if (this.fetcher.fetchMetadata) {
+        metadata = await this.fetcher.fetchMetadata(config.object);
+      }
+
+      // Fetch records
+      const result = await this.fetcher.fetchRecords(config.object, options);
+
+      return {
+        records: result.records,
+        total: result.total,
+        metadata,
+        provider: 'object',
+        loading: false,
+      };
+    } catch (error) {
+      return {
+        records: [],
+        total: 0,
+        provider: 'object',
+        loading: false,
+        error: (error as Error).message,
+      };
+    }
+  }
+
+  /** Resolve element-level data source */
+  async resolveElementDataSource(
+    config: ElementDataSourceConfig,
+  ): Promise<ResolvedData> {
+    return this.resolve(
+      { provider: 'object', object: config.object },
+      {
+        filter: config.filter,
+        sort: config.sort,
+        limit: config.limit,
+      },
+    );
+  }
+
+}

package/src/data-scope/__tests__/ViewDataProvider.test.ts

@@ -0,0 +1,270 @@
+/**
+ * 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.
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import {
+  ViewDataProvider,
+  type DataFetcher,
+  type ViewDataConfig,
+} from '../ViewDataProvider';
+
+describe('ViewDataProvider', () => {
+  let provider: ViewDataProvider;
+
+  beforeEach(() => {
+    provider = new ViewDataProvider();
+  });
+
+  // ===== Value Provider =====
+  describe('value provider', () => {
+    it('resolves static items', async () => {
+      const config: ViewDataConfig = {
+        provider: 'value',
+        items: [
+          { id: 1, name: 'Alice' },
+          { id: 2, name: 'Bob' },
+        ],
+      };
+
+      const result = await provider.resolve(config);
+
+      expect(result.provider).toBe('value');
+      expect(result.records).toHaveLength(2);
+      expect(result.total).toBe(2);
+      expect(result.loading).toBe(false);
+      expect(result.error).toBeUndefined();
+    });
+
+    it('handles empty items', async () => {
+      const result = await provider.resolve({
+        provider: 'value',
+        items: [],
+      });
+      expect(result.records).toHaveLength(0);
+      expect(result.total).toBe(0);
+    });
+
+    it('handles non-array items gracefully', async () => {
+      const result = await provider.resolve({
+        provider: 'value',
+        items: null as any,
+      });
+      expect(result.records).toHaveLength(0);
+    });
+  });
+
+  // ===== API Provider =====
+  describe('api provider', () => {
+    it('returns error when no fetchUrl implementation', async () => {
+      const config: ViewDataConfig = {
+        provider: 'api',
+        read: { url: 'https://api.example.com/records' },
+      };
+
+      const result = await provider.resolve(config);
+      expect(result.error).toContain('No fetchUrl implementation');
+    });
+
+    it('fetches data from API URL', async () => {
+      const fetcher: DataFetcher = {
+        fetchRecords: vi.fn(),
+        fetchUrl: vi.fn().mockResolvedValue({
+          records: [{ id: 1 }],
+          total: 1,
+        }),
+      };
+      provider.setFetcher(fetcher);
+
+      const result = await provider.resolve({
+        provider: 'api',
+        read: { url: 'https://api.example.com/data', method: 'GET' },
+      });
+
+      expect(result.records).toHaveLength(1);
+      expect(result.total).toBe(1);
+      expect(fetcher.fetchUrl).toHaveBeenCalledWith(
+        'https://api.example.com/data',
+        {
+          method: 'GET',
+          headers: undefined,
+        },
+      );
+    });
+
+    it('handles array response shape', async () => {
+      const fetcher: DataFetcher = {
+        fetchRecords: vi.fn(),
+        fetchUrl: vi.fn().mockResolvedValue([{ id: 1 }, { id: 2 }]),
+      };
+      provider.setFetcher(fetcher);
+
+      const result = await provider.resolve({
+        provider: 'api',
+        read: { url: 'https://api.example.com/data' },
+      });
+
+      expect(result.records).toHaveLength(2);
+      expect(result.total).toBe(2);
+    });
+
+    it('handles { data: [] } response shape', async () => {
+      const fetcher: DataFetcher = {
+        fetchRecords: vi.fn(),
+        fetchUrl: vi.fn().mockResolvedValue({ data: [{ id: 1 }] }),
+      };
+      provider.setFetcher(fetcher);
+
+      const result = await provider.resolve({
+        provider: 'api',
+        read: { url: 'https://api.example.com/data' },
+      });
+
+      expect(result.records).toHaveLength(1);
+    });
+
+    it('handles API errors gracefully', async () => {
+      const fetcher: DataFetcher = {
+        fetchRecords: vi.fn(),
+        fetchUrl: vi.fn().mockRejectedValue(new Error('Network error')),
+      };
+      provider.setFetcher(fetcher);
+
+      const result = await provider.resolve({
+        provider: 'api',
+        read: { url: 'https://api.example.com/data' },
+      });
+
+      expect(result.error).toBe('Network error');
+      expect(result.records).toHaveLength(0);
+    });
+  });
+
+  // ===== Object Provider =====
+  describe('object provider', () => {
+    it('returns error when no fetcher configured', async () => {
+      const result = await provider.resolve({
+        provider: 'object',
+        object: 'Account',
+      });
+      expect(result.error).toContain('No data fetcher configured');
+    });
+
+    it('fetches records for object', async () => {
+      const fetcher: DataFetcher = {
+        fetchRecords: vi.fn().mockResolvedValue({
+          records: [{ id: '1', name: 'Acme Corp' }],
+          total: 1,
+        }),
+      };
+      provider.setFetcher(fetcher);
+
+      const result = await provider.resolve({
+        provider: 'object',
+        object: 'Account',
+      });
+
+      expect(result.records).toHaveLength(1);
+      expect(result.total).toBe(1);
+      expect(fetcher.fetchRecords).toHaveBeenCalledWith('Account', undefined);
+    });
+
+    it('passes filter/sort/limit options', async () => {
+      const fetcher: DataFetcher = {
+        fetchRecords: vi.fn().mockResolvedValue({ records: [], total: 0 }),
+      };
+      provider.setFetcher(fetcher);
+
+      const options = {
+        filter: { status: 'active' },
+        sort: [{ field: 'name', order: 'asc' as const }],
+        limit: 10,
+      };
+
+      await provider.resolve(
+        { provider: 'object', object: 'Account' },
+        options,
+      );
+
+      expect(fetcher.fetchRecords).toHaveBeenCalledWith('Account', options);
+    });
+
+    it('fetches metadata when available', async () => {
+      const fetcher: DataFetcher = {
+        fetchRecords: vi.fn().mockResolvedValue({ records: [], total: 0 }),
+        fetchMetadata: vi.fn().mockResolvedValue({
+          name: 'Account',
+          label: 'Accounts',
+          fields: [{ name: 'name', type: 'string', label: 'Name' }],
+        }),
+      };
+      provider.setFetcher(fetcher);
+
+      const result = await provider.resolve({
+        provider: 'object',
+        object: 'Account',
+      });
+
+      expect(result.metadata).toBeDefined();
+      expect(result.metadata?.name).toBe('Account');
+      expect(result.metadata?.fields).toHaveLength(1);
+    });
+
+    it('handles fetch errors gracefully', async () => {
+      const fetcher: DataFetcher = {
+        fetchRecords: vi
+          .fn()
+          .mockRejectedValue(new Error('Connection failed')),
+      };
+      provider.setFetcher(fetcher);
+
+      const result = await provider.resolve({
+        provider: 'object',
+        object: 'Account',
+      });
+
+      expect(result.error).toBe('Connection failed');
+      expect(result.records).toHaveLength(0);
+    });
+  });
+
+  // ===== Element Data Source =====
+  describe('resolveElementDataSource', () => {
+    it('resolves element-level data source', async () => {
+      const fetcher: DataFetcher = {
+        fetchRecords: vi
+          .fn()
+          .mockResolvedValue({ records: [{ id: '1' }], total: 1 }),
+      };
+      provider.setFetcher(fetcher);
+
+      const result = await provider.resolveElementDataSource({
+        object: 'Contact',
+        filter: { accountId: '123' },
+        sort: [{ field: 'name', order: 'asc' }],
+        limit: 5,
+      });
+
+      expect(result.records).toHaveLength(1);
+      expect(fetcher.fetchRecords).toHaveBeenCalledWith('Contact', {
+        filter: { accountId: '123' },
+        sort: [{ field: 'name', order: 'asc' }],
+        limit: 5,
+      });
+    });
+  });
+
+  // ===== Unknown Provider =====
+  describe('unknown provider', () => {
+    it('returns error for unknown provider type', async () => {
+      const result = await provider.resolve({
+        provider: 'unknown' as any,
+      } as ViewDataConfig);
+      expect(result.error).toContain('Unknown data provider');
+    });
+  });
+});

package/src/data-scope/index.ts

@@ -14,3 +14,11 @@ export {
   type RowLevelFilter,
   type DataScopeConfig,
 } from './DataScopeManager.js';
+
+export {
+  ViewDataProvider,
+  type ViewDataConfig,
+  type ElementDataSourceConfig,
+  type DataFetcher,
+  type ResolvedData,
+} from './ViewDataProvider.js';

package/src/evaluator/ExpressionEvaluator.ts

@@ -291,3 +291,25 @@ export function evaluateCondition(
   const evaluator = new ExpressionEvaluator(context, globalCache, globalFormulas);
   return evaluator.evaluateCondition(condition);
 }
+
+/**
+ * Convenience function to evaluate a plain condition string against a data record.
+ * Supports both template expressions (e.g., '${data.amount > 1000}') and
+ * plain expressions (e.g., "status == 'overdue'").
+ * Record fields are available both directly (status) and namespaced (data.status).
+ */
+export function evaluatePlainCondition(
+  condition: string,
+  record: Record<string, any>
+): boolean {
+  const evaluator = new ExpressionEvaluator({ ...record, data: record }, globalCache, globalFormulas);
+  try {
+    const isTemplate = /\$\{/.test(condition);
+    const result = isTemplate
+      ? evaluator.evaluate(condition, { throwOnError: true })
+      : evaluator.evaluateExpression(condition);
+    return result === true;
+  } catch {
+    return false;
+  }
+}

package/src/evaluator/__tests__/ExpressionEvaluator.test.ts

@@ -7,7 +7,7 @@
  */
 
 import { describe, it, expect } from 'vitest';
-import { ExpressionEvaluator, evaluateExpression, evaluateCondition } from '../ExpressionEvaluator';
+import { ExpressionEvaluator, evaluateExpression, evaluateCondition, evaluatePlainCondition } from '../ExpressionEvaluator';
 import { ExpressionContext } from '../ExpressionContext';
 
 describe('ExpressionContext', () => {
@@ -99,3 +99,33 @@ describe('ExpressionEvaluator', () => {
     });
   });
 });
+
+describe('evaluatePlainCondition', () => {
+  it('should evaluate a plain condition with direct field references', () => {
+    expect(evaluatePlainCondition("status == 'overdue'", { status: 'overdue' })).toBe(true);
+    expect(evaluatePlainCondition("status == 'overdue'", { status: 'active' })).toBe(false);
+  });
+
+  it('should evaluate numeric comparisons', () => {
+    expect(evaluatePlainCondition('amount > 1000', { amount: 2500 })).toBe(true);
+    expect(evaluatePlainCondition('amount > 1000', { amount: 500 })).toBe(false);
+  });
+
+  it('should evaluate compound conditions', () => {
+    expect(evaluatePlainCondition("amount > 1000 && status === 'urgent'", { amount: 2000, status: 'urgent' })).toBe(true);
+    expect(evaluatePlainCondition("amount > 1000 && status === 'urgent'", { amount: 2000, status: 'normal' })).toBe(false);
+  });
+
+  it('should support data.field references in template expressions', () => {
+    expect(evaluatePlainCondition('${data.amount > 1000}', { amount: 2000 })).toBe(true);
+    expect(evaluatePlainCondition('${data.amount > 1000}', { amount: 500 })).toBe(false);
+  });
+
+  it('should return false for invalid expressions', () => {
+    expect(evaluatePlainCondition('!!!invalidSyntax', { status: 'ok' })).toBe(false);
+  });
+
+  it('should return false for non-boolean results', () => {
+    expect(evaluatePlainCondition('status', { status: 'active' })).toBe(false);
+  });
+});

package/src/index.ts

@@ -14,6 +14,9 @@ export * from './registry/WidgetRegistry.js';
 export * from './validation/index.js';
 export * from './builder/schema-builder.js';
 export * from './utils/filter-converter.js';
+export * from './utils/normalize-quick-filter.js';
+export * from './utils/extract-records.js';
+export * from './utils/expand-fields.js';
 export * from './evaluator/index.js';
 export * from './actions/index.js';
 export * from './query/index.js';
@@ -22,3 +25,5 @@ export * from './theme/index.js';
 export * from './data-scope/index.js';
 export * from './errors/index.js';
 export * from './utils/debug.js';
+export * from './utils/debug-collector.js';
+export * from './protocols/index.js';