@object-ui/core 3.0.2 → 3.1.0

package/src/utils/__tests__/extract-records.test.ts

@@ -0,0 +1,50 @@
+/**
+ * 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 { extractRecords } from '../extract-records';
+
+describe('extractRecords', () => {
+  const sampleData = [{ id: 1, name: 'A' }, { id: 2, name: 'B' }];
+
+  it('should return the array directly when results is an array', () => {
+    expect(extractRecords(sampleData)).toEqual(sampleData);
+  });
+
+  it('should extract from results.records', () => {
+    expect(extractRecords({ records: sampleData })).toEqual(sampleData);
+  });
+
+  it('should extract from results.data', () => {
+    expect(extractRecords({ data: sampleData })).toEqual(sampleData);
+  });
+
+  it('should extract from results.value', () => {
+    expect(extractRecords({ value: sampleData })).toEqual(sampleData);
+  });
+
+  it('should return empty array for null/undefined', () => {
+    expect(extractRecords(null)).toEqual([]);
+    expect(extractRecords(undefined)).toEqual([]);
+  });
+
+  it('should return empty array for non-array/non-object', () => {
+    expect(extractRecords('string')).toEqual([]);
+    expect(extractRecords(42)).toEqual([]);
+  });
+
+  it('should return empty array for object without recognized keys', () => {
+    expect(extractRecords({ total: 100 })).toEqual([]);
+  });
+
+  it('should prefer records over data and value', () => {
+    const records = [{ id: 1 }];
+    const data = [{ id: 2 }];
+    expect(extractRecords({ records, data })).toEqual(records);
+  });
+});

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

@@ -0,0 +1,123 @@
+/**
+ * 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

@@ -0,0 +1,100 @@
+/**
+ * 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

@@ -6,15 +6,96 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-type DebugCategory = 'schema' | 'registry' | 'expression' | 'action' | 'plugin' | 'render';
+export type DebugCategory = 'schema' | 'registry' | 'expression' | 'action' | 'plugin' | 'render' | 'dashboard';
 
-function isDebugEnabled(): boolean {
+/**
+ * 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;
-    return (
-      (g === true || g === 'true') ||
-      (typeof process !== 'undefined' && process.env?.OBJECTUI_DEBUG === 'true')
-    );
+    if (g === true || g === 'true') return true;
+
+    // 3. process.env
+    if (typeof process !== 'undefined' && process.env?.OBJECTUI_DEBUG === 'true') return true;
+
+    return false;
   } catch {
     return false;
   }

package/src/utils/expand-fields.ts

@@ -0,0 +1,76 @@
+/**
+ * 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

@@ -0,0 +1,33 @@
+/**
+ * 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/normalize-quick-filter.ts

@@ -0,0 +1,78 @@
+/**
+ * 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.
+ */
+
+/**
+ * QuickFilter Normalization Utility
+ *
+ * Adapter layer that converts between two QuickFilter formats:
+ * - Spec format:     { field, operator, value }
+ * - ObjectUI format: { id, label, filters[], icon?, defaultActive? }
+ *
+ * Both formats are accepted; spec-format items are auto-converted to ObjectUI format.
+ */
+
+import type { QuickFilterItem, ObjectUIQuickFilterItem } from '@object-ui/types';
+
+/** Normalized ObjectUI QuickFilter shape (output of normalizeQuickFilter) */
+export type NormalizedQuickFilter = ObjectUIQuickFilterItem;
+
+/**
+ * Map a human-readable / spec operator to the ObjectStack AST operator.
+ */
+function mapSpecOperator(op: string): string {
+  switch (op) {
+    case 'equals': case 'eq': return '=';
+    case 'notEquals': case 'ne': case 'neq': return '!=';
+    case 'contains': return 'contains';
+    case 'notContains': return 'notcontains';
+    case 'greaterThan': case 'gt': return '>';
+    case 'greaterOrEqual': case 'gte': return '>=';
+    case 'lessThan': case 'lt': return '<';
+    case 'lessOrEqual': case 'lte': return '<=';
+    case 'in': return 'in';
+    case 'notIn': return 'not in';
+    case 'before': return '<';
+    case 'after': return '>';
+    default: return op;
+  }
+}
+
+/**
+ * Normalize a single QuickFilter item.
+ * - If it's already in ObjectUI format (has id + label + filters), return as-is.
+ * - If it's in Spec format (has field + operator), convert to ObjectUI format.
+ */
+export function normalizeQuickFilter(item: QuickFilterItem): NormalizedQuickFilter {
+  // Already in ObjectUI format
+  if ('id' in item && 'filters' in item && item.label && Array.isArray(item.filters)) {
+    return item as NormalizedQuickFilter;
+  }
+  // Spec format: { field, operator, value }
+  if ('field' in item && 'operator' in item) {
+    const op = mapSpecOperator(item.operator);
+    return {
+      id: `${item.field}-${item.operator}-${String(item.value ?? '')}`,
+      label: item.label || `${item.field} ${item.operator} ${String(item.value ?? '')}`,
+      filters: [[item.field, op, item.value]],
+      icon: item.icon,
+      defaultActive: item.defaultActive,
+    };
+  }
+  // Unknown format — return as-is
+  return item as NormalizedQuickFilter;
+}
+
+/**
+ * Normalize an array of QuickFilter items (mixed formats accepted).
+ */
+export function normalizeQuickFilters(
+  items: QuickFilterItem[] | undefined,
+): NormalizedQuickFilter[] | undefined {
+  if (!items || items.length === 0) return undefined;
+  return items.map(normalizeQuickFilter);
+}