@object-ui/core 3.3.0 → 3.3.1

package/src/utils/__tests__/normalize-quick-filter.test.ts

@@ -1,123 +0,0 @@
-/**
- * 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 } from 'vitest';
-import { normalizeQuickFilter, normalizeQuickFilters } from '../normalize-quick-filter';
-
-describe('normalizeQuickFilter', () => {
-  it('should pass through ObjectUI format unchanged', () => {
-    const input = { id: 'active', label: 'Active', filters: [['status', '=', 'active']] };
-    const result = normalizeQuickFilter(input);
-    expect(result).toBe(input); // same reference
-    expect(result.id).toBe('active');
-    expect(result.label).toBe('Active');
-    expect(result.filters).toEqual([['status', '=', 'active']]);
-  });
-
-  it('should convert spec format { field, operator, value } to ObjectUI format', () => {
-    const result = normalizeQuickFilter({
-      field: 'status',
-      operator: 'eq',
-      value: 'active',
-      label: 'Active',
-    });
-    expect(result.id).toBe('status-eq-active');
-    expect(result.label).toBe('Active');
-    expect(result.filters).toEqual([['status', '=', 'active']]);
-  });
-
-  it('should auto-generate label when omitted', () => {
-    const result = normalizeQuickFilter({
-      field: 'status',
-      operator: 'eq',
-      value: 'active',
-    });
-    expect(result.label).toBe('status eq active');
-  });
-
-  it('should handle null value', () => {
-    const result = normalizeQuickFilter({
-      field: 'archived',
-      operator: 'eq',
-      value: null,
-      label: 'Not Archived',
-    });
-    expect(result.id).toBe('archived-eq-');
-    expect(result.filters).toEqual([['archived', '=', null]]);
-  });
-
-  it('should map "equals" operator to "="', () => {
-    const result = normalizeQuickFilter({
-      field: 'status',
-      operator: 'equals',
-      value: 'active',
-    });
-    expect(result.filters).toEqual([['status', '=', 'active']]);
-  });
-
-  it('should map "gt" operator to ">"', () => {
-    const result = normalizeQuickFilter({
-      field: 'amount',
-      operator: 'gt',
-      value: 100,
-    });
-    expect(result.filters).toEqual([['amount', '>', 100]]);
-  });
-
-  it('should map "lte" operator to "<="', () => {
-    const result = normalizeQuickFilter({
-      field: 'age',
-      operator: 'lte',
-      value: 18,
-    });
-    expect(result.filters).toEqual([['age', '<=', 18]]);
-  });
-
-  it('should pass through unknown operators', () => {
-    const result = normalizeQuickFilter({
-      field: 'status',
-      operator: 'custom_op',
-      value: 'x',
-    });
-    expect(result.filters).toEqual([['status', 'custom_op', 'x']]);
-  });
-
-  it('should preserve icon and defaultActive', () => {
-    const result = normalizeQuickFilter({
-      field: 'status',
-      operator: 'eq',
-      value: 'active',
-      label: 'Active',
-      icon: 'check',
-      defaultActive: true,
-    });
-    expect(result.icon).toBe('check');
-    expect(result.defaultActive).toBe(true);
-  });
-});
-
-describe('normalizeQuickFilters', () => {
-  it('should return undefined for undefined input', () => {
-    expect(normalizeQuickFilters(undefined)).toBeUndefined();
-  });
-
-  it('should return undefined for empty array', () => {
-    expect(normalizeQuickFilters([])).toBeUndefined();
-  });
-
-  it('should normalize mixed format arrays', () => {
-    const result = normalizeQuickFilters([
-      { id: 'vip', label: 'VIP', filters: [['vip', '=', true]] },
-      { field: 'status', operator: 'eq', value: 'active', label: 'Active' },
-    ]);
-    expect(result).toHaveLength(2);
-    expect(result![0].id).toBe('vip');
-    expect(result![1].id).toBe('status-eq-active');
-    expect(result![1].filters).toEqual([['status', '=', 'active']]);
-  });
-});

package/src/utils/debug-collector.ts

@@ -1,100 +0,0 @@
-/**
- * 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.
- */
-
-/**
- * DebugCollector — lightweight, tree-shakeable event collector
- * for perf / expression / action debug data.
- *
- * Usage in production is a no-op when the singleton is never imported.
- * Consumers call `DebugCollector.getInstance()` and subscribe via
- * `.subscribe()`.
- */
-
-export interface PerfEntry {
-  type: string;
-  id?: string;
-  durationMs: number;
-  timestamp: number;
-}
-
-export interface ExprEntry {
-  expression: string;
-  result: unknown;
-  context?: Record<string, unknown>;
-  timestamp: number;
-}
-
-export interface EventEntry {
-  action: string;
-  payload?: unknown;
-  timestamp: number;
-}
-
-export type DebugEntry =
-  | { kind: 'perf'; data: PerfEntry }
-  | { kind: 'expr'; data: ExprEntry }
-  | { kind: 'event'; data: EventEntry };
-
-type DebugSubscriber = (entry: DebugEntry) => void;
-
-const MAX_ENTRIES = 200;
-
-export class DebugCollector {
-  private static instance: DebugCollector | null = null;
-
-  private entries: DebugEntry[] = [];
-  private subscribers = new Set<DebugSubscriber>();
-
-  static getInstance(): DebugCollector {
-    if (!DebugCollector.instance) {
-      DebugCollector.instance = new DebugCollector();
-    }
-    return DebugCollector.instance;
-  }
-
-  /** Reset singleton — only used for testing */
-  static resetInstance(): void {
-    DebugCollector.instance = null;
-  }
-
-  addPerf(entry: PerfEntry): void {
-    this.push({ kind: 'perf', data: entry });
-  }
-
-  addExpr(entry: ExprEntry): void {
-    this.push({ kind: 'expr', data: entry });
-  }
-
-  addEvent(entry: EventEntry): void {
-    this.push({ kind: 'event', data: entry });
-  }
-
-  getEntries(kind?: DebugEntry['kind']): DebugEntry[] {
-    if (!kind) return this.entries.slice();
-    return this.entries.filter((e) => e.kind === kind);
-  }
-
-  clear(): void {
-    this.entries = [];
-  }
-
-  subscribe(fn: DebugSubscriber): () => void {
-    this.subscribers.add(fn);
-    return () => this.subscribers.delete(fn);
-  }
-
-  private push(entry: DebugEntry): void {
-    this.entries.push(entry);
-    if (this.entries.length > MAX_ENTRIES) {
-      this.entries = this.entries.slice(-MAX_ENTRIES);
-    }
-    for (const fn of this.subscribers) {
-      try { fn(entry); } catch { /* subscriber errors must not break debug flow */ }
-    }
-  }
-}

package/src/utils/debug.ts

@@ -1,148 +0,0 @@
-/**
- * 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 type DebugCategory = 'schema' | 'registry' | 'expression' | 'action' | 'plugin' | 'render' | 'dashboard';
-
-/**
- * Fine-grained debug flags parsed from URL parameters.
- *
- * @example
- * ```
- * ?__debug              → { enabled: true }
- * ?__debug_schema       → { enabled: true, schema: true }
- * ?__debug_perf&__debug_data → { enabled: true, perf: true, data: true }
- * ```
- */
-export interface DebugFlags {
-  /** Master switch — true when any debug parameter is present */
-  enabled: boolean;
-  schema?: boolean;
-  perf?: boolean;
-  data?: boolean;
-  expr?: boolean;
-  events?: boolean;
-  registry?: boolean;
-}
-
-const DEBUG_PARAM_PREFIX = '__debug';
-
-/**
- * Parse debug flags from a URL search string (e.g. `?__debug&__debug_schema`).
- * SSR-safe — returns `{ enabled: false }` when `window` is unavailable.
- *
- * @param search — Optional search string. Defaults to `window.location.search` when available.
- */
-export function parseDebugFlags(search?: string): DebugFlags {
-  let qs: string | undefined = search;
-  if (qs === undefined) {
-    try {
-      qs = typeof window !== 'undefined' ? window.location.search : '';
-    } catch {
-      qs = '';
-    }
-  }
-
-  const params = new URLSearchParams(qs);
-  const hasMain = params.has(DEBUG_PARAM_PREFIX);
-  const schema = params.has(`${DEBUG_PARAM_PREFIX}_schema`);
-  const perf = params.has(`${DEBUG_PARAM_PREFIX}_perf`);
-  const data = params.has(`${DEBUG_PARAM_PREFIX}_data`);
-  const expr = params.has(`${DEBUG_PARAM_PREFIX}_expr`);
-  const events = params.has(`${DEBUG_PARAM_PREFIX}_events`);
-  const registry = params.has(`${DEBUG_PARAM_PREFIX}_registry`);
-
-  const anySub = schema || perf || data || expr || events || registry;
-  const enabled = hasMain || anySub;
-
-  return {
-    enabled,
-    ...(schema && { schema }),
-    ...(perf && { perf }),
-    ...(data && { data }),
-    ...(expr && { expr }),
-    ...(events && { events }),
-    ...(registry && { registry }),
-  };
-}
-
-/**
- * Check whether debug mode is enabled.
- *
- * Resolution order (first truthy wins):
- * 1. URL parameter `?__debug` (browser only)
- * 2. `globalThis.OBJECTUI_DEBUG`
- * 3. `process.env.OBJECTUI_DEBUG`
- */
-export function isDebugEnabled(): boolean {
-  try {
-    // 1. URL parameter (browser only, SSR-safe)
-    if (typeof window !== 'undefined') {
-      try {
-        const flags = parseDebugFlags(window.location.search);
-        if (flags.enabled) return true;
-      } catch { /* ignore */ }
-    }
-
-    // 2. globalThis flag
-    const g = typeof globalThis !== 'undefined' && (globalThis as any).OBJECTUI_DEBUG;
-    if (g === true || g === 'true') return true;
-
-    // 3. process.env
-    const proc = (globalThis as any).process;
-    if (proc?.env?.OBJECTUI_DEBUG === 'true') return true;
-
-    return false;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Log a debug message when OBJECTUI_DEBUG is enabled.
- * No-op in production or when debug mode is off.
- *
- * @example
- * ```ts
- * // Enable debug mode
- * globalThis.OBJECTUI_DEBUG = true;
- *
- * debugLog('schema', 'Resolving component', { type: 'Button' });
- * // [ObjectUI Debug][schema] Resolving component { type: 'Button' }
- * ```
- */
-export function debugLog(category: DebugCategory, message: string, data?: unknown): void {
-  if (!isDebugEnabled()) return;
-  if (data !== undefined) {
-    console.log(`[ObjectUI Debug][${category}] ${message}`, data);
-  } else {
-    console.log(`[ObjectUI Debug][${category}] ${message}`);
-  }
-}
-
-const timers = new Map<string, number>();
-
-/**
- * Start a debug timer. Pair with {@link debugTimeEnd}.
- */
-export function debugTime(label: string): void {
-  if (!isDebugEnabled()) return;
-  timers.set(label, performance.now());
-}
-
-/**
- * End a debug timer and log the elapsed time.
- */
-export function debugTimeEnd(label: string): void {
-  if (!isDebugEnabled()) return;
-  const start = timers.get(label);
-  if (start !== undefined) {
-    const elapsed = (performance.now() - start).toFixed(2);
-    console.log(`[ObjectUI Debug][perf] ${label}: ${elapsed}ms`);
-    timers.delete(label);
-  }
-}

package/src/utils/expand-fields.ts

@@ -1,76 +0,0 @@
-/**
- * ObjectUI — expand-fields utility
- * 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.
- */
-
-/**
- * Build an array of field names that should be included in `$expand`
- * when fetching data. This scans the given object schema fields
- * (and optional column configuration) for `lookup` and `master_detail`
- * field types, so the backend (e.g. objectql) returns expanded objects
- * instead of raw foreign-key IDs.
- *
- * @param schemaFields - Object map of field metadata from `getObjectSchema()`,
- *   e.g. `{ account: { type: 'lookup', reference_to: 'accounts' }, ... }`.
- * @param columns - Optional explicit column list. When provided, only
- *   lookup/master_detail fields that appear in `columns` are expanded.
- *   Accepts `string[]` or `ListColumn[]` (objects with a `field` property).
- * @returns Array of field names to pass as `$expand`.
- *
- * @example
- * ```ts
- * const fields = {
- *   name: { type: 'text' },
- *   account: { type: 'lookup', reference_to: 'accounts' },
- *   parent: { type: 'master_detail', reference_to: 'contacts' },
- * };
- * buildExpandFields(fields);
- * // → ['account', 'parent']
- *
- * buildExpandFields(fields, ['name', 'account']);
- * // → ['account']
- * ```
- */
-export function buildExpandFields(
-  schemaFields?: Record<string, any> | null,
-  columns?: (string | { field?: string; name?: string; fieldName?: string })[],
-): string[] {
-  if (!schemaFields || typeof schemaFields !== 'object') {
-    return [];
-  }
-
-  // Collect all lookup / master_detail field names from the schema
-  const lookupFieldNames: string[] = [];
-  for (const [fieldName, fieldDef] of Object.entries(schemaFields)) {
-    if (
-      fieldDef &&
-      typeof fieldDef === 'object' &&
-      (fieldDef.type === 'lookup' || fieldDef.type === 'master_detail')
-    ) {
-      lookupFieldNames.push(fieldName);
-    }
-  }
-
-  if (lookupFieldNames.length === 0) {
-    return [];
-  }
-
-  // When columns are provided, restrict expansion to visible columns only
-  if (columns && Array.isArray(columns) && columns.length > 0) {
-    const columnFieldNames = new Set<string>();
-    for (const col of columns) {
-      if (typeof col === 'string') {
-        columnFieldNames.add(col);
-      } else if (col && typeof col === 'object') {
-        const name = col.field ?? col.name ?? col.fieldName;
-        if (name) columnFieldNames.add(name);
-      }
-    }
-    return lookupFieldNames.filter((f) => columnFieldNames.has(f));
-  }
-
-  return lookupFieldNames;
-}

package/src/utils/extract-records.ts

@@ -1,33 +0,0 @@
-/**
- * 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.
- */
-
-/**
- * Extract an array of records from various API response formats.
- * Supports: raw array, { records: [] }, { data: [] }, { value: [] }.
- *
- * This utility normalises the different shapes returned by ObjectStack,
- * OData, and MSW mock endpoints so that every data-fetching component
- * can rely on a single extraction path.
- */
-export function extractRecords(results: unknown): any[] {
-  if (Array.isArray(results)) {
-    return results;
-  }
-  if (results && typeof results === 'object') {
-    if (Array.isArray((results as any).records)) {
-      return (results as any).records;
-    }
-    if (Array.isArray((results as any).data)) {
-      return (results as any).data;
-    }
-    if (Array.isArray((results as any).value)) {
-      return (results as any).value;
-    }
-  }
-  return [];
-}

package/src/utils/filter-converter.ts

@@ -1,133 +0,0 @@
-/**
- * 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.
- */
-
-/**
- * Filter Converter Utilities
- * 
- * Shared utilities for converting MongoDB-like filter operators
- * to ObjectStack FilterNode AST format.
- */
-
-/**
- * FilterNode AST type definition
- * Represents a filter condition or a logical combination of conditions
- * 
- * @example
- * // Simple condition
- * ['status', '=', 'active']
- * 
- * // Logical combination
- * ['and', ['age', '>=', 18], ['status', '=', 'active']]
- */
-export type FilterNode = 
-  | [string, string, any]  // [field, operator, value]
-  | [string, ...FilterNode[]];  // [logic, ...conditions]
-
-/**
- * Map MongoDB-like operators to ObjectStack filter operators.
- * 
- * @param operator - MongoDB-style operator (e.g., '$gte', '$in')
- * @returns ObjectStack operator or null if not recognized
- */
-export function convertOperatorToAST(operator: string): string | null {
-  const operatorMap: Record<string, string> = {
-    '$eq': '=',
-    '$ne': '!=',
-    '$gt': '>',
-    '$gte': '>=',
-    '$lt': '<',
-    '$lte': '<=',
-    '$in': 'in',
-    '$nin': 'notin',
-    '$notin': 'notin',
-    '$contains': 'contains',
-    '$startswith': 'startswith',
-    '$between': 'between',
-  };
-  
-  return operatorMap[operator] || null;
-}
-
-/**
- * Convert object-based filters to ObjectStack FilterNode AST format.
- * Converts MongoDB-like operators to ObjectStack filter expressions.
- * 
- * @param filter - Object-based filter with optional operators
- * @returns FilterNode AST array
- * 
- * @example
- * // Simple filter - converted to AST
- * convertFiltersToAST({ status: 'active' })
- * // => ['status', '=', 'active']
- * 
- * @example
- * // Complex filter with operators
- * convertFiltersToAST({ age: { $gte: 18 } })
- * // => ['age', '>=', 18]
- * 
- * @example
- * // Multiple conditions
- * convertFiltersToAST({ age: { $gte: 18, $lte: 65 }, status: 'active' })
- * // => ['and', ['age', '>=', 18], ['age', '<=', 65], ['status', '=', 'active']]
- * 
- * @throws {Error} If an unknown operator is encountered
- */
-export function convertFiltersToAST(filter: Record<string, any>): FilterNode | Record<string, any> {
-  const conditions: FilterNode[] = [];
-  
-  for (const [field, value] of Object.entries(filter)) {
-    if (value === null || value === undefined) continue;
-    
-    // Check if value is a complex operator object
-    if (typeof value === 'object' && !Array.isArray(value)) {
-      // Handle operator-based filters
-      for (const [operator, operatorValue] of Object.entries(value)) {
-        // Special handling for $regex - warn users about limited support
-        if (operator === '$regex') {
-          console.warn(
-            `[ObjectUI] Warning: $regex operator is not fully supported. ` +
-            `Converting to 'contains' which only supports substring matching, not regex patterns. ` +
-            `Field: '${field}', Value: ${JSON.stringify(operatorValue)}. ` +
-            `Consider using $contains or $startswith instead.`
-          );
-          conditions.push([field, 'contains', operatorValue]);
-          continue;
-        }
-        
-        const astOperator = convertOperatorToAST(operator);
-        
-        if (astOperator) {
-          conditions.push([field, astOperator, operatorValue]);
-        } else {
-          // Unknown operator - throw error to avoid silent failure
-          throw new Error(
-            `[ObjectUI] Unknown filter operator '${operator}' for field '${field}'. ` +
-            `Supported operators: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $contains, $startswith, $between. ` +
-            `If you need exact object matching, use the value directly without an operator.`
-          );
-        }
-      }
-    } else {
-      // Simple equality filter
-      conditions.push([field, '=', value]);
-    }
-  }
-  
-  // If no conditions, return original filter
-  if (conditions.length === 0) {
-    return filter;
-  }
-  
-  // If only one condition, return it directly
-  if (conditions.length === 1) {
-    return conditions[0];
-  }
-  
-  // Multiple conditions: combine with 'and'
-  return ['and', ...conditions];
-}

package/src/utils/merge-views-into-objects.ts

@@ -1,36 +0,0 @@
-/**
- * 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.
- */
-
-/**
- * Adapter: merge stack-level views into object definitions.
- *
- * Views are defined at the stack level (views[].listViews) but the runtime
- * expects listViews on each object definition. This bridges the gap until
- * the runtime/provider layer handles it natively.
- *
- * @param objects - Object definitions from composed stack
- * @param views   - View definitions containing listViews keyed by object name
- * @returns Objects with listViews merged in from matching views
- */
-export function mergeViewsIntoObjects(objects: any[], views: any[]): any[] {
-  const viewsByObject: Record<string, Record<string, any>> = {};
-  for (const view of views) {
-    if (!view.listViews) continue;
-    for (const [viewName, listView] of Object.entries(view.listViews as Record<string, any>)) {
-      const objectName = listView?.data?.object;
-      if (!objectName) continue;
-      if (!viewsByObject[objectName]) viewsByObject[objectName] = {};
-      viewsByObject[objectName][viewName] = listView;
-    }
-  }
-  return objects.map((obj: any) => {
-    const v = viewsByObject[obj.name];
-    if (!v) return obj;
-    return { ...obj, listViews: { ...(obj.listViews || {}), ...v } };
-  });
-}