@object-ui/react 3.0.2 → 3.1.0

package/src/hooks/__tests__/usePageTransition.test.ts

@@ -0,0 +1,158 @@
+/**
+ * Tests for usePageTransition hook
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { renderHook } from '@testing-library/react';
+import { usePageTransition } from '../usePageTransition';
+
+describe('usePageTransition', () => {
+
+  it('returns inactive result when type is none (default)', () => {
+    const { result } = renderHook(() => usePageTransition());
+    expect(result.current.isActive).toBe(false);
+    expect(result.current.enterClassName).toBe('');
+    expect(result.current.exitClassName).toBe('');
+    expect(result.current.type).toBe('none');
+  });
+
+  it('returns active result for fade transition', () => {
+    const { result } = renderHook(() => usePageTransition({ type: 'fade' }));
+    expect(result.current.isActive).toBe(true);
+    expect(result.current.enterClassName).toContain('fade-in');
+    expect(result.current.exitClassName).toContain('fade-out');
+    expect(result.current.type).toBe('fade');
+  });
+
+  it('returns correct classes for slide_up transition', () => {
+    const { result } = renderHook(() => usePageTransition({ type: 'slide_up' }));
+    expect(result.current.isActive).toBe(true);
+    expect(result.current.enterClassName).toContain('slide-in-from-bottom');
+    expect(result.current.exitClassName).toContain('slide-out-to-top');
+  });
+
+  it('returns correct classes for slide_down transition', () => {
+    const { result } = renderHook(() => usePageTransition({ type: 'slide_down' }));
+    expect(result.current.enterClassName).toContain('slide-in-from-top');
+    expect(result.current.exitClassName).toContain('slide-out-to-bottom');
+  });
+
+  it('returns correct classes for slide_left transition', () => {
+    const { result } = renderHook(() => usePageTransition({ type: 'slide_left' }));
+    expect(result.current.enterClassName).toContain('slide-in-from-right');
+    expect(result.current.exitClassName).toContain('slide-out-to-left');
+  });
+
+  it('returns correct classes for slide_right transition', () => {
+    const { result } = renderHook(() => usePageTransition({ type: 'slide_right' }));
+    expect(result.current.enterClassName).toContain('slide-in-from-left');
+    expect(result.current.exitClassName).toContain('slide-out-to-right');
+  });
+
+  it('returns correct classes for scale transition', () => {
+    const { result } = renderHook(() => usePageTransition({ type: 'scale' }));
+    expect(result.current.enterClassName).toContain('zoom-in');
+    expect(result.current.exitClassName).toContain('zoom-out');
+  });
+
+  it('returns correct classes for rotate transition', () => {
+    const { result } = renderHook(() => usePageTransition({ type: 'rotate' }));
+    expect(result.current.enterClassName).toContain('spin-in');
+    expect(result.current.exitClassName).toContain('spin-out');
+  });
+
+  it('returns correct classes for flip transition', () => {
+    const { result } = renderHook(() => usePageTransition({ type: 'flip' }));
+    expect(result.current.enterClassName).toContain('zoom-in');
+    expect(result.current.exitClassName).toContain('zoom-out');
+  });
+
+  it('uses default duration of 300ms', () => {
+    const { result } = renderHook(() => usePageTransition({ type: 'fade' }));
+    expect(result.current.duration).toBe(300);
+    expect(result.current.enterStyle.animationDuration).toBe('300ms');
+  });
+
+  it('accepts custom duration', () => {
+    const { result } = renderHook(() => usePageTransition({ type: 'fade', duration: 500 }));
+    expect(result.current.duration).toBe(500);
+    expect(result.current.enterStyle.animationDuration).toBe('500ms');
+  });
+
+  it('uses ease_in_out easing by default', () => {
+    const { result } = renderHook(() => usePageTransition({ type: 'fade' }));
+    expect(result.current.enterStyle.animationTimingFunction).toBe('ease-in-out');
+  });
+
+  it('accepts custom easing', () => {
+    const { result } = renderHook(() => usePageTransition({ type: 'fade', easing: 'spring' }));
+    expect(result.current.enterStyle.animationTimingFunction).toBe('cubic-bezier(0.34, 1.56, 0.64, 1)');
+  });
+
+  it('sets animationFillMode to both', () => {
+    const { result } = renderHook(() => usePageTransition({ type: 'fade' }));
+    expect(result.current.enterStyle.animationFillMode).toBe('both');
+    expect(result.current.exitStyle.animationFillMode).toBe('both');
+  });
+
+  it('applies crossFade positioning', () => {
+    const { result } = renderHook(() => usePageTransition({ type: 'fade', crossFade: true }));
+    expect(result.current.enterStyle.position).toBe('absolute');
+    expect(result.current.enterStyle.inset).toBe('0');
+    expect(result.current.exitStyle.position).toBe('absolute');
+    expect(result.current.exitStyle.inset).toBe('0');
+  });
+
+  it('does not apply crossFade positioning when disabled', () => {
+    const { result } = renderHook(() => usePageTransition({ type: 'fade', crossFade: false }));
+    expect(result.current.enterStyle.position).toBeUndefined();
+    expect(result.current.exitStyle.position).toBeUndefined();
+  });
+
+  it('returns inactive when reduced motion is preferred', () => {
+    // Mock window.matchMedia to simulate reduced motion preference
+    const original = window.matchMedia;
+    window.matchMedia = vi.fn((query: string) => ({
+      matches: query === '(prefers-reduced-motion: reduce)',
+      media: query,
+      onchange: null,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    })) as unknown as typeof window.matchMedia;
+
+    const { result } = renderHook(() => usePageTransition({ type: 'fade' }));
+    expect(result.current.isActive).toBe(false);
+    expect(result.current.enterClassName).toBe('');
+    expect(result.current.exitClassName).toBe('');
+
+    window.matchMedia = original;
+  });
+
+  it('returns empty styles when inactive', () => {
+    const { result } = renderHook(() => usePageTransition({ type: 'none' }));
+    expect(result.current.enterStyle).toEqual({});
+    expect(result.current.exitStyle).toEqual({});
+  });
+
+  it('accepts linear easing', () => {
+    const { result } = renderHook(() => usePageTransition({ type: 'fade', easing: 'linear' }));
+    expect(result.current.enterStyle.animationTimingFunction).toBe('linear');
+  });
+
+  it('accepts ease easing', () => {
+    const { result } = renderHook(() => usePageTransition({ type: 'fade', easing: 'ease' }));
+    expect(result.current.enterStyle.animationTimingFunction).toBe('ease');
+  });
+
+  it('accepts ease_in easing', () => {
+    const { result } = renderHook(() => usePageTransition({ type: 'fade', easing: 'ease_in' }));
+    expect(result.current.enterStyle.animationTimingFunction).toBe('ease-in');
+  });
+
+  it('accepts ease_out easing', () => {
+    const { result } = renderHook(() => usePageTransition({ type: 'fade', easing: 'ease_out' }));
+    expect(result.current.enterStyle.animationTimingFunction).toBe('ease-out');
+  });
+});

package/src/hooks/__tests__/useReducedMotion.test.ts

@@ -0,0 +1,104 @@
+/**
+ * Tests for useReducedMotion hook
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import { useReducedMotion } from '../useReducedMotion';
+
+describe('useReducedMotion', () => {
+  let originalMatchMedia: typeof window.matchMedia;
+  let listeners: Map<string, ((event: MediaQueryListEvent) => void)[]>;
+
+  beforeEach(() => {
+    originalMatchMedia = window.matchMedia;
+    listeners = new Map();
+
+    window.matchMedia = vi.fn((query: string) => {
+      const mediaQueryList = {
+        matches: false,
+        media: query,
+        onchange: null,
+        addEventListener: vi.fn((event: string, handler: (event: MediaQueryListEvent) => void) => {
+          const key = `${query}:${event}`;
+          if (!listeners.has(key)) {
+            listeners.set(key, []);
+          }
+          listeners.get(key)!.push(handler);
+        }),
+        removeEventListener: vi.fn(),
+        addListener: vi.fn(),
+        removeListener: vi.fn(),
+        dispatchEvent: vi.fn(),
+      } as unknown as MediaQueryList;
+      return mediaQueryList;
+    });
+  });
+
+  afterEach(() => {
+    window.matchMedia = originalMatchMedia;
+    listeners.clear();
+  });
+
+  it('returns false when prefers-reduced-motion is not set', () => {
+    const { result } = renderHook(() => useReducedMotion());
+    expect(result.current).toBe(false);
+  });
+
+  it('returns true when prefers-reduced-motion is set', () => {
+    window.matchMedia = vi.fn((query: string) => ({
+      matches: true,
+      media: query,
+      onchange: null,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    })) as unknown as typeof window.matchMedia;
+
+    const { result } = renderHook(() => useReducedMotion());
+    expect(result.current).toBe(true);
+  });
+
+  it('registers a change event listener', () => {
+    renderHook(() => useReducedMotion());
+
+    const key = '(prefers-reduced-motion: reduce):change';
+    expect(listeners.has(key)).toBe(true);
+    expect(listeners.get(key)!.length).toBe(1);
+  });
+
+  it('updates when media query changes', () => {
+    const { result } = renderHook(() => useReducedMotion());
+
+    expect(result.current).toBe(false);
+
+    const key = '(prefers-reduced-motion: reduce):change';
+    const handler = listeners.get(key)![0];
+
+    act(() => {
+      handler({ matches: true } as MediaQueryListEvent);
+    });
+
+    expect(result.current).toBe(true);
+  });
+
+  it('cleans up event listener on unmount', () => {
+    const removeEventListener = vi.fn();
+    window.matchMedia = vi.fn((query: string) => ({
+      matches: false,
+      media: query,
+      onchange: null,
+      addEventListener: vi.fn(),
+      removeEventListener,
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    })) as unknown as typeof window.matchMedia;
+
+    const { unmount } = renderHook(() => useReducedMotion());
+    unmount();
+
+    expect(removeEventListener).toHaveBeenCalledWith('change', expect.any(Function));
+  });
+});

package/src/hooks/index.ts

@@ -30,3 +30,6 @@ export * from './usePageTransition';
 export * from './useViewTransition';
 export * from './useETagCache';
 export * from './useSchemaPersistence';
+export * from './useGlobalUndo';
+export * from './useDebugMode';
+export * from './useActionEngine';

package/src/hooks/useActionEngine.ts

@@ -0,0 +1,84 @@
+/**
+ * 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.
+ */
+
+/**
+ * useActionEngine — React hook wrapping ActionEngine for location-based action management.
+ *
+ * Provides declarative access to the ActionEngine's location filtering, bulk operations,
+ * keyboard shortcut handling, and execution pipeline from React components.
+ *
+ * @example
+ * ```tsx
+ * const { getActionsForLocation, executeAction } = useActionEngine({
+ *   actions: schema.actions,
+ *   context: { record, user },
+ * });
+ *
+ * const toolbarActions = getActionsForLocation('list_toolbar');
+ * ```
+ */
+
+import { useCallback, useMemo } from 'react';
+import {
+  ActionEngine,
+  type ActionLocation,
+  type ActionDef,
+  type ActionContext,
+  type ActionResult,
+} from '@object-ui/core';
+
+export interface UseActionEngineOptions {
+  /** Action definitions to register */
+  actions?: ActionDef[];
+  /** Action context (record, user, etc.) */
+  context?: ActionContext;
+}
+
+export interface UseActionEngineReturn {
+  /** Get actions available at a specific location, sorted by priority */
+  getActionsForLocation: (location: ActionLocation) => ActionDef[];
+  /** Get actions that support bulk operations */
+  getBulkActions: () => ActionDef[];
+  /** Execute an action by name */
+  executeAction: (name: string, contextOverride?: Partial<ActionContext>) => Promise<ActionResult>;
+  /** Handle a keyboard shortcut */
+  handleShortcut: (keys: string) => Promise<ActionResult | null>;
+  /** The underlying ActionEngine instance */
+  engine: ActionEngine;
+}
+
+export function useActionEngine(options: UseActionEngineOptions = {}): UseActionEngineReturn {
+  const { actions = [], context = {} } = options;
+
+  const engine = useMemo(() => {
+    const e = new ActionEngine(context);
+    e.registerActions(actions);
+    return e;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [JSON.stringify(actions), JSON.stringify(context)]);
+
+  const getActionsForLocation = useCallback(
+    (location: ActionLocation) => engine.getActionsForLocation(location),
+    [engine],
+  );
+
+  const getBulkActions = useCallback(() => engine.getBulkActions(), [engine]);
+
+  const executeAction = useCallback(
+    (name: string, contextOverride?: Partial<ActionContext>) =>
+      engine.executeAction(name, contextOverride),
+    [engine],
+  );
+
+  const handleShortcut = useCallback(
+    (keys: string) => engine.handleShortcut(keys),
+    [engine],
+  );
+
+  return { getActionsForLocation, getBulkActions, executeAction, handleShortcut, engine };
+}

package/src/hooks/useDebugMode.ts

@@ -0,0 +1,95 @@
+/**
+ * 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 { useState, useEffect, useCallback, useMemo } from 'react';
+import { parseDebugFlags, type DebugFlags } from '@object-ui/core';
+
+/**
+ * Result returned by {@link useDebugMode}.
+ */
+export interface UseDebugModeResult {
+  /** Whether debug mode is currently enabled */
+  enabled: boolean;
+  /** Fine-grained debug flags parsed from the URL */
+  flags: DebugFlags;
+  /** Toggle debug mode on/off */
+  toggle: () => void;
+  /** Explicitly set debug mode */
+  setEnabled: (value: boolean) => void;
+}
+
+/**
+ * Hook for managing debug mode.
+ *
+ * Automatically detects `?__debug` (and sub-flags like `?__debug_schema`)
+ * from the URL. Supports manual toggle and Ctrl+Shift+D keyboard shortcut.
+ *
+ * SSR-safe — returns disabled state when `window` is unavailable.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const debug = useDebugMode();
+ *   return (
+ *     <>
+ *       {debug.enabled && <DebugPanel flags={debug.flags} />}
+ *       <button onClick={debug.toggle}>Toggle Debug</button>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export function useDebugMode(): UseDebugModeResult {
+  const urlFlags = useMemo(() => {
+    try {
+      return typeof window !== 'undefined'
+        ? parseDebugFlags(window.location.search)
+        : { enabled: false } as DebugFlags;
+    } catch {
+      return { enabled: false } as DebugFlags;
+    }
+  }, []);
+
+  const [manualEnabled, setManualEnabled] = useState<boolean | null>(null);
+
+  // Effective enabled: manual override wins, then URL flags
+  const enabled = manualEnabled !== null ? manualEnabled : urlFlags.enabled;
+
+  // Flags reflect URL-parsed flags plus effective enabled state
+  const flags: DebugFlags = useMemo(
+    () => ({ ...urlFlags, enabled }),
+    [urlFlags, enabled],
+  );
+
+  const toggle = useCallback(() => {
+    setManualEnabled((prev) => {
+      if (prev === null) return !urlFlags.enabled;
+      return !prev;
+    });
+  }, [urlFlags.enabled]);
+
+  const setEnabled = useCallback((value: boolean) => {
+    setManualEnabled(value);
+  }, []);
+
+  // Ctrl+Shift+D keyboard shortcut
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+
+    const handler = (e: KeyboardEvent) => {
+      if (e.ctrlKey && e.shiftKey && e.key === 'D') {
+        e.preventDefault();
+        toggle();
+      }
+    };
+    document.addEventListener('keydown', handler);
+    return () => document.removeEventListener('keydown', handler);
+  }, [toggle]);
+
+  return { enabled, flags, toggle, setEnabled };
+}

package/src/hooks/useGlobalUndo.ts

@@ -0,0 +1,98 @@
+/**
+ * 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 { useCallback, useEffect, useMemo, useRef, useSyncExternalStore } from 'react';
+import { globalUndoManager, type UndoableOperation } from '@object-ui/core';
+
+export interface UseGlobalUndoOptions {
+  /** DataSource to execute undo/redo operations. */
+  dataSource?: {
+    create(objectName: string, data: Record<string, unknown>): Promise<unknown>;
+    update(objectName: string, recordId: string, data: Record<string, unknown>): Promise<unknown>;
+    delete(objectName: string, recordId: string): Promise<unknown>;
+  };
+  /** Callback after successful undo. */
+  onUndo?: (op: UndoableOperation) => void;
+  /** Callback after successful redo. */
+  onRedo?: (op: UndoableOperation) => void;
+}
+
+function getSnapshot() {
+  return {
+    canUndo: globalUndoManager.canUndo,
+    canRedo: globalUndoManager.canRedo,
+    undoDescription: globalUndoManager.peekUndo()?.description,
+    redoDescription: globalUndoManager.peekRedo()?.description,
+    history: globalUndoManager.getHistory(),
+  };
+}
+
+function getServerSnapshot() {
+  return { canUndo: false, canRedo: false, undoDescription: undefined, redoDescription: undefined, history: [] as UndoableOperation[] };
+}
+
+// Cache reference to avoid re-renders when nothing changed
+let cachedSnapshot = getSnapshot();
+function subscribe(callback: () => void) {
+  return globalUndoManager.subscribe(() => {
+    cachedSnapshot = getSnapshot();
+    callback();
+  });
+}
+function getCachedSnapshot() { return cachedSnapshot; }
+
+/**
+ * React hook that wraps the global UndoManager for use in console components.
+ *
+ * Provides reactive undo/redo state, executes data operations through the
+ * supplied dataSource, and registers Ctrl+Z / Ctrl+Shift+Z keyboard shortcuts.
+ */
+export function useGlobalUndo(options: UseGlobalUndoOptions = {}) {
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+
+  const state = useSyncExternalStore(subscribe, getCachedSnapshot, getServerSnapshot);
+
+  const executeOp = useCallback(async (op: UndoableOperation, data: Record<string, unknown>, mode: 'undo' | 'redo') => {
+    const ds = optionsRef.current.dataSource;
+    if (!ds) return;
+    const action = mode === 'undo'
+      ? ({ create: 'delete', update: 'update', delete: 'create' } as const)[op.type]
+      : op.type;
+    if (action === 'delete') await ds.delete(op.objectName, op.recordId);
+    else if (action === 'update') await ds.update(op.objectName, op.recordId, data);
+    else await ds.create(op.objectName, data);
+  }, []);
+
+  const undo = useCallback(async () => {
+    const op = globalUndoManager.popUndo();
+    if (!op) return;
+    await executeOp(op, op.undoData, 'undo');
+    optionsRef.current.onUndo?.(op);
+  }, [executeOp]);
+
+  const redo = useCallback(async () => {
+    const op = globalUndoManager.popRedo();
+    if (!op) return;
+    await executeOp(op, op.redoData, 'redo');
+    optionsRef.current.onRedo?.(op);
+  }, [executeOp]);
+
+  // Keyboard shortcuts: Ctrl+Z (undo), Ctrl+Shift+Z (redo)
+  useEffect(() => {
+    const handler = (e: KeyboardEvent) => {
+      if (!(e.ctrlKey || e.metaKey) || e.key.toLowerCase() !== 'z') return;
+      e.preventDefault();
+      if (e.shiftKey) { void redo(); } else { void undo(); }
+    };
+    window.addEventListener('keydown', handler);
+    return () => window.removeEventListener('keydown', handler);
+  }, [undo, redo]);
+
+  return useMemo(() => ({ ...state, undo, redo }), [state, undo, redo]);
+}

package/src/hooks/useNavigationOverlay.ts

@@ -64,6 +64,8 @@ export interface NavigationOverlayState {
   width: string | number | undefined;
   /** Whether navigation is an overlay mode (drawer/modal/split/popover) */
   isOverlay: boolean;
+  /** The target view/form name from NavigationConfig */
+  view: string | undefined;
 }
 
 /**
@@ -102,6 +104,7 @@ export function useNavigationOverlay(
 
   const mode: NavigationMode = navigation?.mode ?? 'page';
   const width = navigation?.width;
+  const view = navigation?.view;
   const isOverlay = mode === 'drawer' || mode === 'modal' || mode === 'split' || mode === 'popover';
 
   const close = useCallback(() => {
@@ -126,7 +129,7 @@ export function useNavigationOverlay(
       if (!navigation) {
         const recordId = record._id || record.id;
         if (onNavigate && recordId != null) {
-          onNavigate(recordId as string | number, 'view');
+          onNavigate(recordId as string | number, view ?? 'view');
         }
         return;
       }
@@ -136,10 +139,15 @@ export function useNavigationOverlay(
         return;
       }
 
-      // new_window / openNewTab — open in new browser tab
+      // new_window / openNewTab — delegate to onNavigate when available, else open directly
       if (mode === 'new_window' || navigation.openNewTab) {
         const recordId = record._id || record.id;
-        const url = objectName ? `/${objectName}/${recordId}` : `/${recordId}`;
+        if (onNavigate && recordId != null) {
+          onNavigate(recordId as string | number, 'new_window');
+          return;
+        }
+        const viewPath = view ? `/${view}` : '';
+        const url = objectName ? `/${objectName}/${recordId}${viewPath}` : `/${recordId}${viewPath}`;
         window.open(url, '_blank');
         return;
       }
@@ -148,7 +156,7 @@ export function useNavigationOverlay(
       if (mode === 'page') {
         const recordId = record._id || record.id;
         if (onNavigate && recordId != null) {
-          onNavigate(recordId as string | number, 'view');
+          onNavigate(recordId as string | number, view ?? 'view');
         }
         return;
       }
@@ -173,8 +181,9 @@ export function useNavigationOverlay(
       setIsOpen,
       handleClick,
       width,
+      view,
       isOverlay,
     }),
-    [isOpen, selectedRecord, mode, close, open, handleClick, width, isOverlay]
+    [isOpen, selectedRecord, mode, close, open, handleClick, width, view, isOverlay]
   );
 }

package/src/index.ts

@@ -11,11 +11,17 @@ export * from './hooks'; // will be empty for now
 export * from './context'; // will be empty for now
 export * from './components/form';
 export * from './LazyPluginLoader';
+export * from './spec-bridge';
+
+// i18n utilities
+export { resolveI18nLabel } from './utils/i18n';
 
 // Built-in i18n support
 export {
   I18nProvider,
   useObjectTranslation,
+  useObjectLabel,
+  useSafeFieldLabel,
   useI18nContext,
   createI18n,
   getDirection,