@object-ui/core 3.3.0 → 3.3.1

package/src/actions/UndoManager.ts

@@ -1,215 +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.
- */
-
-/**
- * @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

@@ -1,206 +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, 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);
-    });
-  });
-});

package/src/actions/__tests__/ActionRunner.params.test.ts

@@ -1,134 +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, vi, beforeEach } from 'vitest';
-import { ActionRunner, type ActionContext } from '../ActionRunner';
-
-describe('ActionRunner — ParamCollectionHandler', () => {
-  let runner: ActionRunner;
-  let context: ActionContext;
-
-  beforeEach(() => {
-    context = {
-      data: { id: 1, name: 'Test' },
-      record: { id: 1, status: 'active' },
-      user: { id: 'u1', role: 'admin' },
-    };
-    runner = new ActionRunner(context);
-  });
-
-  // ==========================================================================
-  // Param collection before execution
-  // ==========================================================================
-
-  describe('param collection', () => {
-    it('should call paramCollectionHandler when actionParams are defined', async () => {
-      const paramHandler = vi.fn().mockResolvedValue({ owner_email: 'alice@example.com' });
-      runner.setParamCollectionHandler(paramHandler);
-
-      const onClick = vi.fn();
-      await runner.execute({
-        onClick,
-        actionParams: [
-          { name: 'owner_email', label: 'Owner Email', type: 'text', required: true },
-        ],
-      });
-
-      expect(paramHandler).toHaveBeenCalledOnce();
-      expect(paramHandler).toHaveBeenCalledWith([
-        { name: 'owner_email', label: 'Owner Email', type: 'text', required: true },
-      ]);
-      expect(onClick).toHaveBeenCalledOnce();
-    });
-
-    it('should cancel action when paramCollectionHandler returns null', async () => {
-      const paramHandler = vi.fn().mockResolvedValue(null);
-      runner.setParamCollectionHandler(paramHandler);
-
-      const onClick = vi.fn();
-      const result = await runner.execute({
-        onClick,
-        actionParams: [
-          { name: 'owner_email', label: 'Owner Email', type: 'text', required: true },
-        ],
-      });
-
-      expect(paramHandler).toHaveBeenCalledOnce();
-      expect(result.success).toBe(false);
-      expect(result.error).toBe('Action cancelled by user (params)');
-      expect(onClick).not.toHaveBeenCalled();
-    });
-
-    it('should merge collected params into action.params', async () => {
-      const paramHandler = vi.fn().mockResolvedValue({
-        owner_email: 'alice@example.com',
-        notify: true,
-      });
-      runner.setParamCollectionHandler(paramHandler);
-
-      const handler = vi.fn().mockResolvedValue({ success: true });
-      runner.registerHandler('custom_action', handler);
-
-      await runner.execute({
-        type: 'custom_action',
-        params: { existing: 'value' },
-        actionParams: [
-          { name: 'owner_email', label: 'Owner Email', type: 'text' },
-          { name: 'notify', label: 'Notify', type: 'boolean' },
-        ],
-      });
-
-      expect(handler).toHaveBeenCalledOnce();
-      const calledAction = handler.mock.calls[0][0];
-      expect(calledAction.params).toEqual({
-        existing: 'value',
-        owner_email: 'alice@example.com',
-        notify: true,
-      });
-    });
-
-    it('should skip param collection when no paramCollectionHandler is set', async () => {
-      const onClick = vi.fn();
-      const result = await runner.execute({
-        onClick,
-        actionParams: [
-          { name: 'test', label: 'Test', type: 'text' },
-        ],
-      });
-
-      // Should proceed normally without param collection
-      expect(result.success).toBe(true);
-      expect(onClick).toHaveBeenCalledOnce();
-    });
-
-    it('should skip param collection when actionParams is empty', async () => {
-      const paramHandler = vi.fn();
-      runner.setParamCollectionHandler(paramHandler);
-
-      const onClick = vi.fn();
-      await runner.execute({
-        onClick,
-        actionParams: [],
-      });
-
-      expect(paramHandler).not.toHaveBeenCalled();
-      expect(onClick).toHaveBeenCalledOnce();
-    });
-
-    it('should skip param collection when actionParams is not provided', async () => {
-      const paramHandler = vi.fn();
-      runner.setParamCollectionHandler(paramHandler);
-
-      const onClick = vi.fn();
-      await runner.execute({ onClick });
-
-      expect(paramHandler).not.toHaveBeenCalled();
-      expect(onClick).toHaveBeenCalledOnce();
-    });
-  });
-});