@object-ui/react 0.5.0 → 3.0.0

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

@@ -0,0 +1,220 @@
+/**
+ * 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, afterEach } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import {
+  useSchemaPersistence,
+  createLocalStorageAdapter,
+} from '../useSchemaPersistence';
+import type { SchemaPersistenceAdapter } from '../useSchemaPersistence';
+
+// Mock localStorage
+const localStorageMock = (() => {
+  let store: Record<string, string> = {};
+  return {
+    getItem: (key: string) => store[key] ?? null,
+    setItem: (key: string, value: string) => { store[key] = value; },
+    removeItem: (key: string) => { delete store[key]; },
+    clear: () => { store = {}; },
+  };
+})();
+
+Object.defineProperty(window, 'localStorage', { value: localStorageMock });
+
+describe('useSchemaPersistence', () => {
+  beforeEach(() => {
+    localStorageMock.clear();
+  });
+
+  it('should initialize with default state', () => {
+    const { result } = renderHook(() => useSchemaPersistence());
+    expect(result.current.loading).toBe(false);
+    expect(result.current.error).toBeNull();
+    expect(result.current.isDirty).toBe(false);
+    expect(result.current.lastSavedAt).toBeNull();
+  });
+
+  it('should save and load a schema with default localStorage adapter', async () => {
+    const { result } = renderHook(() => useSchemaPersistence());
+    const testSchema = { type: 'page', title: 'My Page', regions: [] };
+
+    let savedId: string | null = null;
+    await act(async () => {
+      savedId = await result.current.save('test-page', testSchema);
+    });
+
+    expect(savedId).toBe('test-page');
+    expect(result.current.isDirty).toBe(false);
+    expect(result.current.lastSavedAt).not.toBeNull();
+
+    let loaded: Record<string, unknown> | null = null;
+    await act(async () => {
+      loaded = await result.current.load('test-page');
+    });
+
+    expect(loaded).toEqual(testSchema);
+  });
+
+  it('should list saved schemas', async () => {
+    const { result } = renderHook(() => useSchemaPersistence());
+
+    await act(async () => {
+      await result.current.save('schema-1', { type: 'page' });
+      await result.current.save('schema-2', { type: 'form' });
+    });
+
+    let items: Array<{ id: string }> = [];
+    await act(async () => {
+      items = await result.current.list();
+    });
+
+    expect(items).toHaveLength(2);
+    expect(items.map((i) => i.id)).toEqual(['schema-1', 'schema-2']);
+  });
+
+  it('should delete a schema', async () => {
+    const { result } = renderHook(() => useSchemaPersistence());
+
+    await act(async () => {
+      await result.current.save('to-delete', { type: 'grid' });
+    });
+
+    let success = false;
+    await act(async () => {
+      success = await result.current.remove('to-delete');
+    });
+
+    expect(success).toBe(true);
+
+    let loaded: Record<string, unknown> | null = null;
+    await act(async () => {
+      loaded = await result.current.load('to-delete');
+    });
+
+    expect(loaded).toBeNull();
+  });
+
+  it('should track dirty state', () => {
+    const { result } = renderHook(() => useSchemaPersistence());
+
+    expect(result.current.isDirty).toBe(false);
+
+    act(() => {
+      result.current.markDirty();
+    });
+
+    expect(result.current.isDirty).toBe(true);
+  });
+
+  it('should clear dirty state after save', async () => {
+    const { result } = renderHook(() => useSchemaPersistence());
+
+    act(() => {
+      result.current.markDirty();
+    });
+    expect(result.current.isDirty).toBe(true);
+
+    await act(async () => {
+      await result.current.save('test', { type: 'page' });
+    });
+    expect(result.current.isDirty).toBe(false);
+  });
+
+  it('should handle save errors gracefully', async () => {
+    const failingAdapter: SchemaPersistenceAdapter = {
+      save: () => Promise.reject(new Error('Network error')),
+      load: () => Promise.resolve(null),
+    };
+
+    const { result } = renderHook(() => useSchemaPersistence(failingAdapter));
+
+    await act(async () => {
+      await result.current.save('test', { type: 'page' });
+    });
+
+    expect(result.current.error).not.toBeNull();
+    expect(result.current.error?.message).toBe('Network error');
+  });
+
+  it('should clear errors', async () => {
+    const failingAdapter: SchemaPersistenceAdapter = {
+      save: () => Promise.reject(new Error('fail')),
+      load: () => Promise.resolve(null),
+    };
+
+    const { result } = renderHook(() => useSchemaPersistence(failingAdapter));
+
+    await act(async () => {
+      await result.current.save('test', { type: 'page' });
+    });
+    expect(result.current.error).not.toBeNull();
+
+    act(() => {
+      result.current.clearError();
+    });
+    expect(result.current.error).toBeNull();
+  });
+
+  it('should work with custom adapter', async () => {
+    const mockStore: Record<string, Record<string, unknown>> = {};
+    const customAdapter: SchemaPersistenceAdapter = {
+      save: async (id, schema) => { mockStore[id] = schema; return id; },
+      load: async (id) => mockStore[id] ?? null,
+      list: async () => Object.keys(mockStore).map((id) => ({ id })),
+      delete: async (id) => { delete mockStore[id]; },
+    };
+
+    const { result } = renderHook(() => useSchemaPersistence(customAdapter));
+
+    await act(async () => {
+      await result.current.save('custom-1', { type: 'dashboard' });
+    });
+
+    let loaded: Record<string, unknown> | null = null;
+    await act(async () => {
+      loaded = await result.current.load('custom-1');
+    });
+
+    expect(loaded).toEqual({ type: 'dashboard' });
+  });
+});
+
+describe('createLocalStorageAdapter', () => {
+  beforeEach(() => {
+    localStorageMock.clear();
+  });
+
+  it('should create an adapter with custom prefix', async () => {
+    const adapter = createLocalStorageAdapter('my-prefix');
+
+    await adapter.save('test', { hello: 'world' });
+    const result = await adapter.load('test');
+    expect(result).toEqual({ hello: 'world' });
+  });
+
+  it('should maintain an index of saved schemas', async () => {
+    const adapter = createLocalStorageAdapter('test-prefix');
+
+    await adapter.save('a', { type: 'a' });
+    await adapter.save('b', { type: 'b' });
+
+    const items = await adapter.list!();
+    expect(items).toHaveLength(2);
+  });
+
+  it('should not duplicate IDs in index', async () => {
+    const adapter = createLocalStorageAdapter('test-prefix');
+
+    await adapter.save('same-id', { v: 1 });
+    await adapter.save('same-id', { v: 2 });
+
+    const items = await adapter.list!();
+    expect(items).toHaveLength(1);
+  });
+});

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

@@ -0,0 +1,121 @@
+/**
+ * Tests for useViewSharing hook
+ */
+import { describe, it, expect } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import { useViewSharing } from '../useViewSharing';
+import type { SavedView } from '../useViewSharing';
+
+const createView = (overrides?: Partial<SavedView>): SavedView => ({
+  id: 'test-1',
+  name: 'Test View',
+  config: { filters: [] },
+  visibility: 'private',
+  updatedAt: new Date(),
+  ...overrides,
+});
+
+describe('useViewSharing', () => {
+  it('starts with empty views by default', () => {
+    const { result } = renderHook(() => useViewSharing());
+    expect(result.current.views).toEqual([]);
+    expect(result.current.activeView).toBeNull();
+  });
+
+  it('starts with provided initial views', () => {
+    const initial = [createView()];
+    const { result } = renderHook(() => useViewSharing(initial));
+    expect(result.current.views).toHaveLength(1);
+    expect(result.current.activeView?.id).toBe('test-1');
+  });
+
+  it('saves a new view', () => {
+    const { result } = renderHook(() => useViewSharing());
+
+    act(() => {
+      result.current.saveView({
+        name: 'My View',
+        config: { sort: 'name' },
+        visibility: 'private',
+      });
+    });
+
+    expect(result.current.views).toHaveLength(1);
+    expect(result.current.views[0].name).toBe('My View');
+  });
+
+  it('returns ID when saving a view', () => {
+    const { result } = renderHook(() => useViewSharing());
+
+    let id: string = '';
+    act(() => {
+      id = result.current.saveView({
+        name: 'My View',
+        config: {},
+        visibility: 'private',
+      });
+    });
+
+    expect(id).toBeTruthy();
+    expect(id).toContain('view-');
+  });
+
+  it('deletes a view', () => {
+    const initial = [createView()];
+    const { result } = renderHook(() => useViewSharing(initial));
+
+    act(() => {
+      result.current.deleteView('test-1');
+    });
+
+    expect(result.current.views).toHaveLength(0);
+  });
+
+  it('sets active view', () => {
+    const initial = [
+      createView({ id: 'v1', name: 'View 1' }),
+      createView({ id: 'v2', name: 'View 2' }),
+    ];
+    const { result } = renderHook(() => useViewSharing(initial));
+
+    act(() => {
+      result.current.setActiveView('v2');
+    });
+
+    expect(result.current.activeView?.id).toBe('v2');
+  });
+
+  it('duplicates a view', () => {
+    const initial = [createView()];
+    const { result } = renderHook(() => useViewSharing(initial));
+
+    act(() => {
+      result.current.duplicateView('test-1', 'Copy of Test');
+    });
+
+    expect(result.current.views).toHaveLength(2);
+    expect(result.current.views[1].name).toBe('Copy of Test');
+    expect(result.current.views[1].isDefault).toBe(false);
+  });
+
+  it('updates view visibility', () => {
+    const initial = [createView()];
+    const { result } = renderHook(() => useViewSharing(initial));
+
+    act(() => {
+      result.current.setVisibility('test-1', 'organization');
+    });
+
+    expect(result.current.views[0].visibility).toBe('organization');
+  });
+
+  it('selects default view as active', () => {
+    const initial = [
+      createView({ id: 'v1', name: 'View 1' }),
+      createView({ id: 'v2', name: 'View 2', isDefault: true }),
+    ];
+    const { result } = renderHook(() => useViewSharing(initial));
+
+    expect(result.current.activeView?.id).toBe('v2');
+  });
+});

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

@@ -0,0 +1,61 @@
+/**
+ * Tests for useViewTransition hook
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import { useViewTransition } from '../useViewTransition';
+
+describe('useViewTransition', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('returns isSupported as false when document.startViewTransition is not available', () => {
+    const { result } = renderHook(() => useViewTransition());
+
+    // happy-dom does not implement startViewTransition
+    expect(result.current.isSupported).toBe(false);
+  });
+
+  it('returns isTransitioning as false initially', () => {
+    const { result } = renderHook(() => useViewTransition());
+
+    expect(result.current.isTransitioning).toBe(false);
+  });
+
+  it('startTransition calls callback without transition API (fallback behavior)', async () => {
+    const { result } = renderHook(() => useViewTransition());
+
+    const callback = vi.fn();
+
+    await act(async () => {
+      await result.current.startTransition(callback);
+    });
+
+    expect(callback).toHaveBeenCalledTimes(1);
+  });
+
+  it('respects enabled: false by calling callback directly', async () => {
+    const { result } = renderHook(() =>
+      useViewTransition({ enabled: false }),
+    );
+
+    const callback = vi.fn();
+
+    await act(async () => {
+      await result.current.startTransition(callback);
+    });
+
+    expect(callback).toHaveBeenCalledTimes(1);
+  });
+
+  it('transitionClass is empty initially', () => {
+    const { result } = renderHook(() => useViewTransition());
+
+    expect(result.current.transitionClass).toBe('');
+  });
+});

package/src/hooks/index.ts

@@ -8,4 +8,25 @@
 
 export * from './useExpression';
 export * from './useActionRunner';
-
+export * from './useNavigationOverlay';
+export * from './usePageVariables';
+export * from './useViewData';
+export * from './useDynamicApp';
+export * from './useDiscovery';
+export * from './useFocusTrap';
+export * from './useFocusManagement';
+export * from './useKeyboardShortcuts';
+export * from './useCrudShortcuts';
+export * from './useReducedMotion';
+export * from './useAnimation';
+export * from './useColumnSummary';
+export * from './useDensityMode';
+export * from './useViewSharing';
+export * from './useClientNotifications';
+export * from './useOffline';
+export * from './usePerformance';
+export * from './usePerformanceBudget';
+export * from './usePageTransition';
+export * from './useViewTransition';
+export * from './useETagCache';
+export * from './useSchemaPersistence';

package/src/hooks/useActionRunner.ts

@@ -7,36 +7,74 @@
  */
 
 import { useState, useCallback, useMemo } from 'react';
-import { ActionRunner, type ActionContext, type ActionResult } from '@object-ui/core';
+import {
+  ActionRunner,
+  type ActionContext,
+  type ActionDef,
+  type ActionResult,
+  type ConfirmationHandler,
+  type ToastHandler,
+  type ModalHandler,
+  type NavigationHandler,
+} from '@object-ui/core';
+
+export interface UseActionRunnerOptions {
+  context?: ActionContext;
+  /** Custom confirmation handler — wire to Shadcn AlertDialog or similar */
+  onConfirm?: ConfirmationHandler;
+  /** Custom toast handler — wire to Sonner or similar */
+  onToast?: ToastHandler;
+  /** Custom modal handler — render modals in response to modal actions */
+  onModal?: ModalHandler;
+  /** Custom navigation handler — SPA-aware routing */
+  onNavigate?: NavigationHandler;
+}
 
 /**
- * Hook for executing actions with loading state
+ * Hook for executing actions with loading state, typed with ActionDef.
  * 
  * @example
  * ```tsx
- * const { execute, loading, error, result } = useActionRunner({ data: formData });
+ * const { execute, loading, error, result } = useActionRunner({
+ *   context: { data: formData },
+ *   onToast: (msg, opts) => toast[opts?.type || 'info'](msg),
+ * });
  * 
  * const handleClick = () => {
  *   execute({
- *     type: 'action',
+ *     type: 'api',
  *     api: '/api/save',
- *     successMessage: 'Saved successfully!'
+ *     successMessage: 'Saved successfully!',
  *   });
  * };
  * ```
  */
-export function useActionRunner(context: ActionContext = {}) {
+export function useActionRunner(
+  optionsOrContext: UseActionRunnerOptions | ActionContext = {},
+) {
+  // Backwards compat: if no 'context' key, treat entire object as context
+  const options: UseActionRunnerOptions = 'context' in optionsOrContext
+    ? optionsOrContext as UseActionRunnerOptions
+    : { context: optionsOrContext as ActionContext };
+
+  const { context = {}, onConfirm, onToast, onModal, onNavigate } = options;
+
   const [loading, setLoading] = useState(false);
   const [error, setError] = useState<string | null>(null);
   const [result, setResult] = useState<ActionResult | null>(null);
 
-  const runner = useMemo(
-    () => new ActionRunner(context),
-    [JSON.stringify(context)]
-  );
+  const runner = useMemo(() => {
+    const r = new ActionRunner(context);
+    if (onConfirm) r.setConfirmHandler(onConfirm);
+    if (onToast) r.setToastHandler(onToast);
+    if (onModal) r.setModalHandler(onModal);
+    if (onNavigate) r.setNavigationHandler(onNavigate);
+    return r;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [JSON.stringify(context)]);
 
   const execute = useCallback(
-    async (action: any): Promise<ActionResult> => {
+    async (action: ActionDef): Promise<ActionResult> => {
       setLoading(true);
       setError(null);
       setResult(null);

package/src/hooks/useAnimation.ts

@@ -0,0 +1,117 @@
+/**
+ * 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 { useMemo } from 'react';
+
+/** Animation trigger type */
+export type AnimationTriggerType = 'enter' | 'exit' | 'hover' | 'focus' | 'click';
+
+/** Easing presets aligned with EasingFunctionSchema */
+export type EasingPreset =
+  | 'linear'
+  | 'ease'
+  | 'ease-in'
+  | 'ease-out'
+  | 'ease-in-out'
+  | 'spring';
+
+/** Transition preset aligned with TransitionPresetSchema */
+export type TransitionPresetType =
+  | 'fade'
+  | 'slide-up'
+  | 'slide-down'
+  | 'slide-left'
+  | 'slide-right'
+  | 'scale'
+  | 'scale-fade'
+  | 'none';
+
+export interface AnimationConfig {
+  /** The animation/transition preset */
+  preset?: TransitionPresetType;
+  /** Duration in milliseconds */
+  duration?: number;
+  /** Delay in milliseconds */
+  delay?: number;
+  /** Easing function */
+  easing?: EasingPreset;
+  /** Whether animation is enabled */
+  enabled?: boolean;
+}
+
+/** Resolved CSS classes and styles for animation */
+export interface AnimationResult {
+  /** Tailwind CSS classes for the animation */
+  className: string;
+  /** Inline style for custom durations/delays (only when needed) */
+  style: React.CSSProperties;
+}
+
+const EASING_MAP: Record<EasingPreset, string> = {
+  linear: 'linear',
+  ease: 'ease',
+  'ease-in': 'ease-in',
+  'ease-out': 'ease-out',
+  'ease-in-out': 'ease-in-out',
+  spring: 'cubic-bezier(0.34, 1.56, 0.64, 1)',
+};
+
+const PRESET_CLASSES: Record<TransitionPresetType, string> = {
+  fade: 'animate-in fade-in',
+  'slide-up': 'animate-in slide-in-from-bottom-2',
+  'slide-down': 'animate-in slide-in-from-top-2',
+  'slide-left': 'animate-in slide-in-from-right-2',
+  'slide-right': 'animate-in slide-in-from-left-2',
+  scale: 'animate-in zoom-in-95',
+  'scale-fade': 'animate-in fade-in zoom-in-95',
+  none: '',
+};
+
+/**
+ * Hook for applying spec-driven animations to components.
+ * Implements ComponentAnimationSchema and TransitionPresetSchema
+ * from @objectstack/spec v2.0.7.
+ *
+ * @example
+ * ```tsx
+ * function Card() {
+ *   const animation = useAnimation({ preset: 'fade', duration: 200, easing: 'ease-out' });
+ *   return <div className={animation.className} style={animation.style}>...</div>;
+ * }
+ * ```
+ */
+export function useAnimation(config: AnimationConfig = {}): AnimationResult {
+  const {
+    preset = 'none',
+    duration,
+    delay,
+    easing = 'ease-out',
+    enabled = true,
+  } = config;
+
+  return useMemo(() => {
+    if (!enabled || preset === 'none') {
+      return { className: '', style: {} };
+    }
+
+    const className = PRESET_CLASSES[preset] || '';
+    const style: React.CSSProperties = {};
+
+    if (duration !== undefined) {
+      style.animationDuration = `${duration}ms`;
+    }
+    if (delay !== undefined) {
+      style.animationDelay = `${delay}ms`;
+    }
+    if (easing) {
+      style.animationTimingFunction = EASING_MAP[easing] || easing;
+    }
+
+    return { className, style };
+  }, [preset, duration, delay, easing, enabled]);
+}