@object-ui/core 3.0.2 → 3.1.0

package/src/actions/ActionEngine.ts

@@ -0,0 +1,268 @@
+/**
+ * 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 Engine
+ * 
+ * Declarative action dispatch engine. Manages action registration,
+ * event-to-action mapping, location-based filtering, keyboard shortcuts,
+ * and bulk operation support.
+ * 
+ * Replaces callback-based patterns with a schema-driven pipeline:
+ *   ActionSchema[] → ActionEngine → ActionRunner → ActionResult
+ */
+
+import { ActionRunner, type ActionDef, type ActionContext, type ActionResult } from './ActionRunner';
+
+/** Action location types (from @objectstack/spec) */
+export type ActionLocation =
+  | 'list_toolbar'
+  | 'list_item'
+  | 'record_header'
+  | 'record_more'
+  | 'record_related'
+  | 'global_nav';
+
+/** Registered action with metadata */
+export interface RegisteredAction {
+  action: ActionDef;
+  locations: ActionLocation[];
+  /** Keyboard shortcut (e.g., 'ctrl+s', 'meta+k') */
+  shortcut?: string;
+  /** Whether this action supports bulk operations */
+  bulkEnabled?: boolean;
+  /** Priority for ordering (lower = first) */
+  priority?: number;
+}
+
+/** Event-to-action mapping */
+export interface ActionMapping {
+  /** Event name (e.g., 'row:click', 'toolbar:save', 'keyboard:ctrl+s') */
+  event: string;
+  /** Action name to execute */
+  actionName: string;
+  /** Optional condition expression */
+  condition?: string;
+}
+
+/** Keyboard shortcut handler */
+export interface ShortcutBinding {
+  /** Key combination (e.g., 'ctrl+s', 'meta+k', 'shift+n') */
+  keys: string;
+  /** Action name to trigger */
+  actionName: string;
+}
+
+/** Normalize a shortcut string for comparison (lowercase, trimmed, sorted parts) */
+function normalizeShortcut(keys: string): string {
+  return keys.toLowerCase().split('+').map(k => k.trim()).sort().join('+');
+}
+
+export class ActionEngine {
+  private actions = new Map<string, RegisteredAction>();
+  private mappings: ActionMapping[] = [];
+  private shortcuts: ShortcutBinding[] = [];
+  private normalizedShortcutMap = new Map<string, string>();
+  private runner: ActionRunner;
+
+  constructor(context: ActionContext = {}) {
+    this.runner = new ActionRunner(context);
+  }
+
+  /** Get the underlying ActionRunner for handler configuration */
+  getRunner(): ActionRunner {
+    return this.runner;
+  }
+
+  /** Register a single action */
+  registerAction(action: ActionDef, options?: {
+    locations?: ActionLocation[];
+    shortcut?: string;
+    bulkEnabled?: boolean;
+    priority?: number;
+  }): void {
+    const name = action.name || action.type || '';
+    if (!name) throw new Error('Action must have a name or type');
+    
+    this.actions.set(name, {
+      action,
+      locations: options?.locations || [],
+      shortcut: options?.shortcut,
+      bulkEnabled: options?.bulkEnabled ?? false,
+      priority: options?.priority ?? 100,
+    });
+
+    // Auto-register keyboard shortcut
+    if (options?.shortcut) {
+      this.shortcuts.push({ keys: options.shortcut, actionName: name });
+      this.normalizedShortcutMap.set(normalizeShortcut(options.shortcut), name);
+    }
+  }
+
+  /** Register multiple actions from an ActionSchema array */
+  registerActions(actions: ActionDef[]): void {
+    for (const action of actions) {
+      this.registerAction(action, {
+        locations: (action as any).locations,
+        shortcut: (action as any).shortcut,
+        bulkEnabled: (action as any).bulkEnabled,
+      });
+    }
+  }
+
+  /** Unregister an action by name */
+  unregisterAction(name: string): void {
+    const registered = this.actions.get(name);
+    if (registered?.shortcut) {
+      this.normalizedShortcutMap.delete(normalizeShortcut(registered.shortcut));
+    }
+    this.actions.delete(name);
+    this.shortcuts = this.shortcuts.filter(s => s.actionName !== name);
+    this.mappings = this.mappings.filter(m => m.actionName !== name);
+  }
+
+  /** Add an event-to-action mapping */
+  addMapping(mapping: ActionMapping): void {
+    this.mappings.push(mapping);
+  }
+
+  /** Get actions available at a specific location, sorted by priority */
+  getActionsForLocation(location: ActionLocation): ActionDef[] {
+    return Array.from(this.actions.values())
+      .filter(ra => ra.locations.includes(location))
+      .sort((a, b) => (a.priority ?? 100) - (b.priority ?? 100))
+      .map(ra => ra.action);
+  }
+
+  /** Get actions that support bulk operations */
+  getBulkActions(): ActionDef[] {
+    return Array.from(this.actions.values())
+      .filter(ra => ra.bulkEnabled)
+      .sort((a, b) => (a.priority ?? 100) - (b.priority ?? 100))
+      .map(ra => ra.action);
+  }
+
+  /** Get all registered keyboard shortcuts */
+  getShortcuts(): ShortcutBinding[] {
+    return [...this.shortcuts];
+  }
+
+  /** Get a registered action by name */
+  getAction(name: string): ActionDef | undefined {
+    return this.actions.get(name)?.action;
+  }
+
+  /** Execute an action by name */
+  async executeAction(name: string, contextOverride?: Partial<ActionContext>): Promise<ActionResult> {
+    const registered = this.actions.get(name);
+    if (!registered) {
+      return { success: false, error: `Action not found: ${name}` };
+    }
+
+    if (contextOverride) {
+      this.runner.updateContext(contextOverride);
+    }
+
+    return this.runner.execute(registered.action);
+  }
+
+  /** Dispatch an event — finds mapped actions and executes them */
+  async dispatch(event: string, contextOverride?: Partial<ActionContext>): Promise<ActionResult[]> {
+    const matchingMappings = this.mappings.filter(m => m.event === event);
+    
+    if (matchingMappings.length === 0) {
+      return [];
+    }
+
+    const results: ActionResult[] = [];
+    for (const mapping of matchingMappings) {
+      // Check condition if present
+      if (mapping.condition) {
+        const evaluator = this.runner.getEvaluator();
+        const shouldRun = evaluator.evaluateCondition(mapping.condition);
+        if (!shouldRun) continue;
+      }
+
+      const result = await this.executeAction(mapping.actionName, contextOverride);
+      results.push(result);
+    }
+
+    return results;
+  }
+
+  /** Handle a keyboard shortcut event — returns true if handled */
+  async handleShortcut(keys: string, contextOverride?: Partial<ActionContext>): Promise<ActionResult | null> {
+    const actionName = this.normalizedShortcutMap.get(normalizeShortcut(keys));
+    if (!actionName) return null;
+    
+    return this.executeAction(actionName, contextOverride);
+  }
+
+  /** Execute a bulk operation on multiple records */
+  async executeBulk(
+    actionName: string,
+    records: Record<string, any>[],
+    options?: { parallel?: boolean; continueOnError?: boolean }
+  ): Promise<{ total: number; succeeded: number; failed: number; results: ActionResult[] }> {
+    const registered = this.actions.get(actionName);
+    if (!registered) {
+      return { total: 0, succeeded: 0, failed: 0, results: [{ success: false, error: `Action not found: ${actionName}` }] };
+    }
+    if (!registered.bulkEnabled) {
+      return { total: 0, succeeded: 0, failed: 0, results: [{ success: false, error: `Action ${actionName} does not support bulk operations` }] };
+    }
+
+    const results: ActionResult[] = [];
+    let succeeded = 0;
+    let failed = 0;
+
+    if (options?.parallel) {
+      const promises = records.map(record => {
+        this.runner.updateContext({ record, selectedRecords: records });
+        return this.runner.execute(registered.action);
+      });
+      const settled = await Promise.allSettled(promises);
+      for (const r of settled) {
+        if (r.status === 'fulfilled') {
+          results.push(r.value);
+          if (r.value.success) succeeded++;
+          else failed++;
+        } else {
+          results.push({ success: false, error: r.reason?.message || 'Unknown error' });
+          failed++;
+        }
+      }
+    } else {
+      for (const record of records) {
+        this.runner.updateContext({ record, selectedRecords: records });
+        const result = await this.runner.execute(registered.action);
+        results.push(result);
+        if (result.success) succeeded++;
+        else {
+          failed++;
+          if (!options?.continueOnError) break;
+        }
+      }
+    }
+
+    return { total: records.length, succeeded, failed, results };
+  }
+
+  /** Update the action context */
+  updateContext(context: Partial<ActionContext>): void {
+    this.runner.updateContext(context);
+  }
+
+  /** Clear all registered actions and mappings */
+  clear(): void {
+    this.actions.clear();
+    this.mappings = [];
+    this.shortcuts = [];
+    this.normalizedShortcutMap.clear();
+  }
+}

package/src/actions/UndoManager.ts

@@ -0,0 +1,215 @@
+/**
+ * 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 - Undo Manager
+ *
+ * Global undo/redo system for CRUD operations. Class-based singleton
+ * pattern for use from ActionRunner, React hooks, and standalone contexts.
+ * Maintains bounded history stacks with subscriber notifications.
+ */
+
+/** Represents a single undoable CRUD operation. */
+export interface UndoableOperation {
+  id: string;
+  type: 'create' | 'update' | 'delete';
+  objectName: string;
+  recordId: string;
+  timestamp: number;
+  description: string;
+  /** Data needed to undo: for create=recordId, for update=previousData, for delete=fullRecord */
+  undoData: Record<string, unknown>;
+  /** Data needed to redo: for create=newData, for update=newData, for delete=recordId */
+  redoData: Record<string, unknown>;
+}
+
+export interface UndoManagerOptions {
+  /** Maximum number of operations to retain in history. @default 50 */
+  maxHistory?: number;
+}
+
+/** Type guard validating the required shape of a persisted UndoableOperation. */
+function isValidOperation(op: unknown): op is UndoableOperation {
+  if (typeof op !== 'object' || op === null) return false;
+  const o = op as Record<string, unknown>;
+  return (
+    typeof o.id === 'string' &&
+    typeof o.type === 'string' &&
+    typeof o.objectName === 'string' &&
+    typeof o.recordId === 'string' &&
+    typeof o.timestamp === 'number'
+  );
+}
+
+/**
+ * Manages undo/redo stacks for CRUD operations.
+ *
+ * Designed as a framework-agnostic class so it can be used from
+ * ActionRunner, React hooks, or any other consumer.
+ */
+export class UndoManager {
+  private undoStack: UndoableOperation[] = [];
+  private redoStack: UndoableOperation[] = [];
+  private readonly maxHistory: number;
+  private listeners: Set<() => void> = new Set();
+
+  constructor(options?: UndoManagerOptions) {
+    this.maxHistory = options?.maxHistory ?? 50;
+  }
+
+  /** Record an undoable operation. Clears the redo stack. */
+  push(operation: UndoableOperation): void {
+    this.undoStack.push(operation);
+    if (this.undoStack.length > this.maxHistory) {
+      this.undoStack.shift();
+    }
+    this.redoStack = [];
+    this.notify();
+  }
+
+  /** Peek at the next undoable operation without removing it. */
+  peekUndo(): UndoableOperation | undefined {
+    return this.undoStack[this.undoStack.length - 1];
+  }
+
+  /** Peek at the next redoable operation without removing it. */
+  peekRedo(): UndoableOperation | undefined {
+    return this.redoStack[this.redoStack.length - 1];
+  }
+
+  /** Pop the last operation from the undo stack and move it to redo. */
+  popUndo(): UndoableOperation | undefined {
+    const op = this.undoStack.pop();
+    if (op) {
+      this.redoStack.push(op);
+      this.notify();
+    }
+    return op;
+  }
+
+  /** Pop the last operation from the redo stack and move it to undo. */
+  popRedo(): UndoableOperation | undefined {
+    const op = this.redoStack.pop();
+    if (op) {
+      this.undoStack.push(op);
+      this.notify();
+    }
+    return op;
+  }
+
+  /** Clear all undo and redo history. */
+  clear(): void {
+    this.undoStack = [];
+    this.redoStack = [];
+    this.notify();
+  }
+
+  get canUndo(): boolean { return this.undoStack.length > 0; }
+  get canRedo(): boolean { return this.redoStack.length > 0; }
+  get undoCount(): number { return this.undoStack.length; }
+  get redoCount(): number { return this.redoStack.length; }
+
+  /** Subscribe to state changes. Returns an unsubscribe function. */
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  /** Get a shallow copy of the undo history (for developer tools). */
+  getHistory(): UndoableOperation[] { return [...this.undoStack]; }
+
+  /** Get a shallow copy of the redo history (for developer tools). */
+  getRedoHistory(): UndoableOperation[] { return [...this.redoStack]; }
+
+  // ---------------------------------------------------------------------------
+  // Batch operations
+  // ---------------------------------------------------------------------------
+
+  /** Push multiple operations as one atomic unit. Clears the redo stack. */
+  pushBatch(operations: UndoableOperation[]): void {
+    if (operations.length === 0) return;
+    this.undoStack.push(...operations);
+    // Trim from the front if we exceed maxHistory
+    if (this.undoStack.length > this.maxHistory) {
+      this.undoStack.splice(0, this.undoStack.length - this.maxHistory);
+    }
+    this.redoStack = [];
+    this.notify();
+  }
+
+  /** Pop `count` operations from the undo stack and move them to redo (LIFO order). */
+  popUndoBatch(count: number): UndoableOperation[] {
+    const actual = Math.min(count, this.undoStack.length);
+    if (actual === 0) return [];
+    const ops = this.undoStack.splice(this.undoStack.length - actual, actual);
+    // Preserve LIFO order on the redo stack (last undone goes on top)
+    this.redoStack.push(...ops);
+    this.notify();
+    return ops;
+  }
+
+  /** Pop `count` operations from the redo stack and move them to undo (LIFO order). */
+  popRedoBatch(count: number): UndoableOperation[] {
+    const actual = Math.min(count, this.redoStack.length);
+    if (actual === 0) return [];
+    const ops = this.redoStack.splice(this.redoStack.length - actual, actual);
+    this.undoStack.push(...ops);
+    this.notify();
+    return ops;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Persistence (localStorage)
+  // ---------------------------------------------------------------------------
+
+  private static readonly STORAGE_KEY = 'objectui:undo-history';
+
+  /** Persist the current undo/redo stacks to localStorage. */
+  saveToStorage(): void {
+    try {
+      const payload = JSON.stringify({
+        undoStack: this.undoStack,
+        redoStack: this.redoStack,
+      });
+      localStorage.setItem(UndoManager.STORAGE_KEY, payload);
+    } catch {
+      // localStorage may be unavailable (SSR, quota exceeded, etc.)
+    }
+  }
+
+  /** Restore undo/redo stacks from localStorage (no-op when unavailable). */
+  loadFromStorage(): void {
+    try {
+      if (typeof localStorage === 'undefined') return;
+      const raw = localStorage.getItem(UndoManager.STORAGE_KEY);
+      if (!raw) return;
+      const parsed = JSON.parse(raw) as {
+        undoStack?: UndoableOperation[];
+        redoStack?: UndoableOperation[];
+      };
+      if (Array.isArray(parsed.undoStack)) {
+        this.undoStack = parsed.undoStack.filter(isValidOperation);
+      }
+      if (Array.isArray(parsed.redoStack)) {
+        this.redoStack = parsed.redoStack.filter(isValidOperation);
+      }
+      // Enforce maxHistory in case persisted state used a different limit
+      if (this.undoStack.length > this.maxHistory) {
+        this.undoStack.splice(0, this.undoStack.length - this.maxHistory);
+      }
+      this.notify();
+    } catch {
+      // Silently ignore parse errors or missing storage
+    }
+  }
+
+  private notify(): void { this.listeners.forEach((fn) => fn()); }
+}
+
+/** Global singleton instance. */
+export const globalUndoManager = new UndoManager();

package/src/actions/__tests__/ActionEngine.test.ts

@@ -0,0 +1,206 @@
+/**
+ * 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 } from 'vitest';
+import { ActionEngine } from '../ActionEngine';
+import type { ActionDef } from '../ActionRunner';
+
+describe('ActionEngine', () => {
+  let engine: ActionEngine;
+
+  beforeEach(() => {
+    engine = new ActionEngine({ data: { status: 'active' } });
+  });
+
+  describe('registerAction', () => {
+    it('registers an action by name', () => {
+      engine.registerAction({ name: 'save', type: 'api', endpoint: '/save' });
+      expect(engine.getAction('save')).toBeDefined();
+      expect(engine.getAction('save')?.type).toBe('api');
+    });
+
+    it('throws if action has no name or type', () => {
+      expect(() => engine.registerAction({} as ActionDef)).toThrow('Action must have a name or type');
+    });
+
+    it('registers with locations', () => {
+      engine.registerAction(
+        { name: 'delete', type: 'api' },
+        { locations: ['record_header', 'list_item'] }
+      );
+      expect(engine.getActionsForLocation('record_header')).toHaveLength(1);
+      expect(engine.getActionsForLocation('list_toolbar')).toHaveLength(0);
+    });
+
+    it('auto-registers keyboard shortcuts', () => {
+      engine.registerAction(
+        { name: 'save', type: 'api' },
+        { shortcut: 'ctrl+s' }
+      );
+      expect(engine.getShortcuts()).toHaveLength(1);
+      expect(engine.getShortcuts()[0].keys).toBe('ctrl+s');
+    });
+  });
+
+  describe('registerActions', () => {
+    it('registers multiple actions from array', () => {
+      engine.registerActions([
+        { name: 'save', type: 'api', endpoint: '/save' },
+        { name: 'delete', type: 'api', endpoint: '/delete' },
+      ]);
+      expect(engine.getAction('save')).toBeDefined();
+      expect(engine.getAction('delete')).toBeDefined();
+    });
+  });
+
+  describe('unregisterAction', () => {
+    it('removes action and its shortcuts/mappings', () => {
+      engine.registerAction({ name: 'save', type: 'api' }, { shortcut: 'ctrl+s' });
+      engine.addMapping({ event: 'toolbar:save', actionName: 'save' });
+      
+      engine.unregisterAction('save');
+      
+      expect(engine.getAction('save')).toBeUndefined();
+      expect(engine.getShortcuts()).toHaveLength(0);
+    });
+  });
+
+  describe('getActionsForLocation', () => {
+    it('returns actions sorted by priority', () => {
+      engine.registerAction({ name: 'delete', type: 'api' }, { locations: ['list_toolbar'], priority: 200 });
+      engine.registerAction({ name: 'create', type: 'modal' }, { locations: ['list_toolbar'], priority: 10 });
+      engine.registerAction({ name: 'export', type: 'api' }, { locations: ['list_toolbar'], priority: 100 });
+
+      const actions = engine.getActionsForLocation('list_toolbar');
+      expect(actions).toHaveLength(3);
+      expect(actions[0].name).toBe('create');
+      expect(actions[1].name).toBe('export');
+      expect(actions[2].name).toBe('delete');
+    });
+  });
+
+  describe('getBulkActions', () => {
+    it('returns only bulk-enabled actions', () => {
+      engine.registerAction({ name: 'delete', type: 'api' }, { bulkEnabled: true });
+      engine.registerAction({ name: 'edit', type: 'modal' }, { bulkEnabled: false });
+      
+      expect(engine.getBulkActions()).toHaveLength(1);
+      expect(engine.getBulkActions()[0].name).toBe('delete');
+    });
+  });
+
+  describe('dispatch', () => {
+    it('executes mapped actions for an event', async () => {
+      engine.registerAction({ name: 'log', type: 'script', execute: '"logged"' });
+      engine.addMapping({ event: 'row:click', actionName: 'log' });
+
+      const results = await engine.dispatch('row:click');
+      expect(results).toHaveLength(1);
+      expect(results[0].success).toBe(true);
+    });
+
+    it('returns empty array for unmapped events', async () => {
+      const results = await engine.dispatch('unknown:event');
+      expect(results).toEqual([]);
+    });
+
+    it('skips actions when mapping condition is false', async () => {
+      engine = new ActionEngine({ data: { status: 'locked' } });
+      engine.registerAction({ name: 'edit', type: 'script', execute: '"edited"' });
+      engine.addMapping({ 
+        event: 'row:click', 
+        actionName: 'edit',
+        condition: '${data.status === "active"}'
+      });
+
+      const results = await engine.dispatch('row:click');
+      expect(results).toHaveLength(0);
+    });
+  });
+
+  describe('handleShortcut', () => {
+    it('executes action for matching shortcut', async () => {
+      engine.registerAction(
+        { name: 'save', type: 'script', execute: '"saved"' },
+        { shortcut: 'ctrl+s' }
+      );
+
+      const result = await engine.handleShortcut('ctrl+s');
+      expect(result).not.toBeNull();
+      expect(result?.success).toBe(true);
+    });
+
+    it('normalizes shortcut key order', async () => {
+      engine.registerAction(
+        { name: 'save', type: 'script', execute: '"saved"' },
+        { shortcut: 'ctrl+shift+s' }
+      );
+
+      // Different order should still match
+      const result = await engine.handleShortcut('shift+ctrl+s');
+      expect(result).not.toBeNull();
+      expect(result?.success).toBe(true);
+    });
+
+    it('returns null for unregistered shortcut', async () => {
+      const result = await engine.handleShortcut('ctrl+z');
+      expect(result).toBeNull();
+    });
+  });
+
+  describe('executeBulk', () => {
+    it('executes action on multiple records sequentially', async () => {
+      engine.registerAction(
+        { name: 'approve', type: 'script', execute: '"approved"' },
+        { bulkEnabled: true }
+      );
+
+      const result = await engine.executeBulk('approve', [
+        { id: '1', name: 'Record 1' },
+        { id: '2', name: 'Record 2' },
+      ]);
+
+      expect(result.total).toBe(2);
+      expect(result.succeeded).toBe(2);
+      expect(result.failed).toBe(0);
+    });
+
+    it('fails if action is not bulk-enabled', async () => {
+      engine.registerAction({ name: 'edit', type: 'modal' }, { bulkEnabled: false });
+
+      const result = await engine.executeBulk('edit', [{ id: '1' }]);
+      expect(result.results[0].success).toBe(false);
+      expect(result.results[0].error).toContain('does not support bulk');
+    });
+
+    it('fails if action is not found', async () => {
+      const result = await engine.executeBulk('nonexistent', [{ id: '1' }]);
+      expect(result.results[0].success).toBe(false);
+    });
+  });
+
+  describe('executeAction', () => {
+    it('returns error for unknown action', async () => {
+      const result = await engine.executeAction('nonexistent');
+      expect(result.success).toBe(false);
+      expect(result.error).toContain('Action not found');
+    });
+  });
+
+  describe('clear', () => {
+    it('removes all actions, mappings, and shortcuts', () => {
+      engine.registerAction({ name: 'save', type: 'api' }, { shortcut: 'ctrl+s' });
+      engine.addMapping({ event: 'test', actionName: 'save' });
+      
+      engine.clear();
+      
+      expect(engine.getAction('save')).toBeUndefined();
+      expect(engine.getShortcuts()).toHaveLength(0);
+    });
+  });
+});