@object-ui/react 0.5.0 → 3.0.0

package/src/__tests__/usePageTransition.test.ts

@@ -0,0 +1,214 @@
+/**
+ * ObjectUI — usePageTransition Tests
+ * 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 } from '@testing-library/react';
+import { usePageTransition } from '../hooks/usePageTransition';
+
+// ---------------------------------------------------------------------------
+// matchMedia mock helper
+// ---------------------------------------------------------------------------
+
+function mockMatchMedia(reducedMotion: boolean) {
+  const listeners: Array<(e: MediaQueryListEvent) => void> = [];
+  const mql = {
+    matches: reducedMotion,
+    media: '(prefers-reduced-motion: reduce)',
+    addEventListener: (_: string, cb: (e: MediaQueryListEvent) => void) => {
+      listeners.push(cb);
+    },
+    removeEventListener: (_: string, cb: (e: MediaQueryListEvent) => void) => {
+      const idx = listeners.indexOf(cb);
+      if (idx >= 0) listeners.splice(idx, 1);
+    },
+    addListener: vi.fn(),
+    removeListener: vi.fn(),
+    onchange: null,
+    dispatchEvent: vi.fn(),
+  } as unknown as MediaQueryList;
+
+  Object.defineProperty(window, 'matchMedia', {
+    writable: true,
+    configurable: true,
+    value: vi.fn().mockReturnValue(mql),
+  });
+
+  return { mql, listeners };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('usePageTransition', () => {
+  beforeEach(() => {
+    mockMatchMedia(false);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('should return inactive result for default (none) type', () => {
+    const { result } = renderHook(() => usePageTransition());
+
+    expect(result.current.isActive).toBe(false);
+    expect(result.current.type).toBe('none');
+    expect(result.current.enterClassName).toBe('');
+    expect(result.current.exitClassName).toBe('');
+    expect(result.current.enterStyle).toEqual({});
+    expect(result.current.exitStyle).toEqual({});
+  });
+
+  it('should generate fade transition classes', () => {
+    const { result } = renderHook(() =>
+      usePageTransition({ type: 'fade', duration: 200 }),
+    );
+
+    expect(result.current.isActive).toBe(true);
+    expect(result.current.enterClassName).toContain('animate-in');
+    expect(result.current.enterClassName).toContain('fade-in');
+    expect(result.current.exitClassName).toContain('animate-out');
+    expect(result.current.exitClassName).toContain('fade-out');
+    expect(result.current.enterStyle.animationDuration).toBe('200ms');
+    expect(result.current.duration).toBe(200);
+  });
+
+  it('should generate slide_up transition classes', () => {
+    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('should generate slide_down transition classes', () => {
+    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('should generate slide_left transition classes', () => {
+    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('should generate slide_right transition classes', () => {
+    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('should generate scale transition classes', () => {
+    const { result } = renderHook(() =>
+      usePageTransition({ type: 'scale' }),
+    );
+
+    expect(result.current.enterClassName).toContain('zoom-in');
+    expect(result.current.exitClassName).toContain('zoom-out');
+  });
+
+  it('should generate rotate transition classes', () => {
+    const { result } = renderHook(() =>
+      usePageTransition({ type: 'rotate' }),
+    );
+
+    expect(result.current.enterClassName).toContain('spin-in');
+    expect(result.current.exitClassName).toContain('spin-out');
+  });
+
+  it('should generate flip transition classes', () => {
+    const { result } = renderHook(() =>
+      usePageTransition({ type: 'flip' }),
+    );
+
+    expect(result.current.isActive).toBe(true);
+    expect(result.current.enterClassName).toContain('fade-in');
+    expect(result.current.exitClassName).toContain('fade-out');
+  });
+
+  it('should apply 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('should apply custom duration', () => {
+    const { result } = renderHook(() =>
+      usePageTransition({ type: 'fade', duration: 500 }),
+    );
+
+    expect(result.current.enterStyle.animationDuration).toBe('500ms');
+    expect(result.current.duration).toBe(500);
+  });
+
+  it('should use default duration of 300ms', () => {
+    const { result } = renderHook(() =>
+      usePageTransition({ type: 'fade' }),
+    );
+
+    expect(result.current.duration).toBe(300);
+    expect(result.current.enterStyle.animationDuration).toBe('300ms');
+  });
+
+  it('should disable transitions when reduced motion is preferred', () => {
+    mockMatchMedia(true);
+
+    const { result } = renderHook(() =>
+      usePageTransition({ type: 'fade', duration: 200 }),
+    );
+
+    expect(result.current.isActive).toBe(false);
+    expect(result.current.enterClassName).toBe('');
+    expect(result.current.exitClassName).toBe('');
+    expect(result.current.enterStyle).toEqual({});
+    expect(result.current.exitStyle).toEqual({});
+  });
+
+  it('should set animationFillMode to both', () => {
+    const { result } = renderHook(() =>
+      usePageTransition({ type: 'fade' }),
+    );
+
+    expect(result.current.enterStyle.animationFillMode).toBe('both');
+    expect(result.current.exitStyle.animationFillMode).toBe('both');
+  });
+
+  it('should support all easing values', () => {
+    const easings = [
+      { input: 'linear' as const, expected: 'linear' },
+      { input: 'ease' as const, expected: 'ease' },
+      { input: 'ease_in' as const, expected: 'ease-in' },
+      { input: 'ease_out' as const, expected: 'ease-out' },
+      { input: 'ease_in_out' as const, expected: 'ease-in-out' },
+    ];
+
+    for (const { input, expected } of easings) {
+      const { result } = renderHook(() =>
+        usePageTransition({ type: 'fade', easing: input }),
+      );
+      expect(result.current.enterStyle.animationTimingFunction).toBe(expected);
+    }
+  });
+});

package/src/__tests__/usePageVariables.test.tsx

@@ -0,0 +1,334 @@
+/**
+ * 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 { renderHook, act } from '@testing-library/react';
+import React from 'react';
+import {
+  PageVariablesProvider,
+  usePageVariables,
+  useHasPageVariables,
+} from '../hooks/usePageVariables';
+import type { PageVariable } from '@object-ui/types';
+
+// ---------------------------------------------------------------------------
+// Helper: wrap hook in PageVariablesProvider
+// ---------------------------------------------------------------------------
+
+function createWrapper(definitions?: PageVariable[]) {
+  return ({ children }: { children: React.ReactNode }) => (
+    <PageVariablesProvider definitions={definitions}>
+      {children}
+    </PageVariablesProvider>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// useHasPageVariables
+// ---------------------------------------------------------------------------
+
+describe('useHasPageVariables', () => {
+  it('should return false when outside provider', () => {
+    const { result } = renderHook(() => useHasPageVariables());
+    expect(result.current).toBe(false);
+  });
+
+  it('should return true when inside provider', () => {
+    const { result } = renderHook(() => useHasPageVariables(), {
+      wrapper: createWrapper([]),
+    });
+    expect(result.current).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// usePageVariables — outside provider (graceful fallback)
+// ---------------------------------------------------------------------------
+
+describe('usePageVariables — outside provider', () => {
+  it('should return empty variables', () => {
+    const { result } = renderHook(() => usePageVariables());
+    expect(result.current.variables).toEqual({});
+  });
+
+  it('should provide no-op setVariable', () => {
+    const { result } = renderHook(() => usePageVariables());
+    // Should not throw
+    act(() => {
+      result.current.setVariable('x', 1);
+    });
+    expect(result.current.variables).toEqual({});
+  });
+
+  it('should provide no-op setVariables', () => {
+    const { result } = renderHook(() => usePageVariables());
+    act(() => {
+      result.current.setVariables({ a: 1, b: 2 });
+    });
+    expect(result.current.variables).toEqual({});
+  });
+
+  it('should provide no-op resetVariables', () => {
+    const { result } = renderHook(() => usePageVariables());
+    act(() => {
+      result.current.resetVariables();
+    });
+    expect(result.current.variables).toEqual({});
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Initialization from definitions
+// ---------------------------------------------------------------------------
+
+describe('usePageVariables — initialization', () => {
+  it('should initialize string variable with default', () => {
+    const defs: PageVariable[] = [
+      { name: 'query', type: 'string', defaultValue: 'hello' },
+    ];
+    const { result } = renderHook(() => usePageVariables(), {
+      wrapper: createWrapper(defs),
+    });
+    expect(result.current.variables.query).toBe('hello');
+  });
+
+  it('should initialize number variable with default', () => {
+    const defs: PageVariable[] = [
+      { name: 'count', type: 'number', defaultValue: 42 },
+    ];
+    const { result } = renderHook(() => usePageVariables(), {
+      wrapper: createWrapper(defs),
+    });
+    expect(result.current.variables.count).toBe(42);
+  });
+
+  it('should initialize boolean variable with default', () => {
+    const defs: PageVariable[] = [
+      { name: 'isOpen', type: 'boolean', defaultValue: true },
+    ];
+    const { result } = renderHook(() => usePageVariables(), {
+      wrapper: createWrapper(defs),
+    });
+    expect(result.current.variables.isOpen).toBe(true);
+  });
+
+  it('should initialize object variable with default', () => {
+    const defs: PageVariable[] = [
+      { name: 'filter', type: 'object', defaultValue: { status: 'active' } },
+    ];
+    const { result } = renderHook(() => usePageVariables(), {
+      wrapper: createWrapper(defs),
+    });
+    expect(result.current.variables.filter).toEqual({ status: 'active' });
+  });
+
+  it('should initialize array variable with default', () => {
+    const defs: PageVariable[] = [
+      { name: 'tags', type: 'array', defaultValue: ['a', 'b'] },
+    ];
+    const { result } = renderHook(() => usePageVariables(), {
+      wrapper: createWrapper(defs),
+    });
+    expect(result.current.variables.tags).toEqual(['a', 'b']);
+  });
+
+  it('should use type-appropriate defaults when no defaultValue', () => {
+    const defs: PageVariable[] = [
+      { name: 'str', type: 'string' },
+      { name: 'num', type: 'number' },
+      { name: 'bool', type: 'boolean' },
+      { name: 'obj', type: 'object' },
+      { name: 'arr', type: 'array' },
+    ];
+    const { result } = renderHook(() => usePageVariables(), {
+      wrapper: createWrapper(defs),
+    });
+    expect(result.current.variables.str).toBe('');
+    expect(result.current.variables.num).toBe(0);
+    expect(result.current.variables.bool).toBe(false);
+    expect(result.current.variables.obj).toEqual({});
+    expect(result.current.variables.arr).toEqual([]);
+  });
+
+  it('should default to empty string when type is undefined', () => {
+    const defs: PageVariable[] = [{ name: 'unknown' }];
+    const { result } = renderHook(() => usePageVariables(), {
+      wrapper: createWrapper(defs),
+    });
+    expect(result.current.variables.unknown).toBe('');
+  });
+
+  it('should initialize multiple variables', () => {
+    const defs: PageVariable[] = [
+      { name: 'name', type: 'string', defaultValue: 'Alice' },
+      { name: 'age', type: 'number', defaultValue: 30 },
+      { name: 'active', type: 'boolean', defaultValue: true },
+    ];
+    const { result } = renderHook(() => usePageVariables(), {
+      wrapper: createWrapper(defs),
+    });
+    expect(result.current.variables).toEqual({
+      name: 'Alice',
+      age: 30,
+      active: true,
+    });
+  });
+
+  it('should return empty variables when definitions is empty array', () => {
+    const { result } = renderHook(() => usePageVariables(), {
+      wrapper: createWrapper([]),
+    });
+    expect(result.current.variables).toEqual({});
+  });
+
+  it('should return empty variables when definitions is undefined', () => {
+    const { result } = renderHook(() => usePageVariables(), {
+      wrapper: createWrapper(undefined),
+    });
+    expect(result.current.variables).toEqual({});
+  });
+});
+
+// ---------------------------------------------------------------------------
+// setVariable
+// ---------------------------------------------------------------------------
+
+describe('usePageVariables — setVariable', () => {
+  it('should update a single variable', () => {
+    const defs: PageVariable[] = [
+      { name: 'selected', type: 'string', defaultValue: '' },
+    ];
+    const { result } = renderHook(() => usePageVariables(), {
+      wrapper: createWrapper(defs),
+    });
+
+    act(() => {
+      result.current.setVariable('selected', 'item-1');
+    });
+    expect(result.current.variables.selected).toBe('item-1');
+  });
+
+  it('should not overwrite other variables', () => {
+    const defs: PageVariable[] = [
+      { name: 'a', type: 'string', defaultValue: 'alpha' },
+      { name: 'b', type: 'string', defaultValue: 'beta' },
+    ];
+    const { result } = renderHook(() => usePageVariables(), {
+      wrapper: createWrapper(defs),
+    });
+
+    act(() => {
+      result.current.setVariable('a', 'updated');
+    });
+    expect(result.current.variables.a).toBe('updated');
+    expect(result.current.variables.b).toBe('beta');
+  });
+
+  it('should allow setting a new key not in definitions', () => {
+    const defs: PageVariable[] = [
+      { name: 'known', type: 'string', defaultValue: 'x' },
+    ];
+    const { result } = renderHook(() => usePageVariables(), {
+      wrapper: createWrapper(defs),
+    });
+
+    act(() => {
+      result.current.setVariable('dynamic', 'value');
+    });
+    expect(result.current.variables.dynamic).toBe('value');
+    expect(result.current.variables.known).toBe('x');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// setVariables (batch)
+// ---------------------------------------------------------------------------
+
+describe('usePageVariables — setVariables', () => {
+  it('should update multiple variables at once', () => {
+    const defs: PageVariable[] = [
+      { name: 'x', type: 'number', defaultValue: 0 },
+      { name: 'y', type: 'number', defaultValue: 0 },
+      { name: 'z', type: 'number', defaultValue: 0 },
+    ];
+    const { result } = renderHook(() => usePageVariables(), {
+      wrapper: createWrapper(defs),
+    });
+
+    act(() => {
+      result.current.setVariables({ x: 10, y: 20 });
+    });
+    expect(result.current.variables).toEqual({ x: 10, y: 20, z: 0 });
+  });
+
+  it('should merge with existing variables', () => {
+    const defs: PageVariable[] = [
+      { name: 'name', type: 'string', defaultValue: 'Alice' },
+      { name: 'age', type: 'number', defaultValue: 25 },
+    ];
+    const { result } = renderHook(() => usePageVariables(), {
+      wrapper: createWrapper(defs),
+    });
+
+    act(() => {
+      result.current.setVariable('name', 'Bob');
+    });
+    act(() => {
+      result.current.setVariables({ age: 30 });
+    });
+    expect(result.current.variables).toEqual({ name: 'Bob', age: 30 });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// resetVariables
+// ---------------------------------------------------------------------------
+
+describe('usePageVariables — resetVariables', () => {
+  it('should reset all variables to defaults', () => {
+    const defs: PageVariable[] = [
+      { name: 'a', type: 'string', defaultValue: 'original' },
+      { name: 'b', type: 'number', defaultValue: 5 },
+    ];
+    const { result } = renderHook(() => usePageVariables(), {
+      wrapper: createWrapper(defs),
+    });
+
+    // Mutate
+    act(() => {
+      result.current.setVariables({ a: 'changed', b: 99 });
+    });
+    expect(result.current.variables).toEqual({ a: 'changed', b: 99 });
+
+    // Reset
+    act(() => {
+      result.current.resetVariables();
+    });
+    expect(result.current.variables).toEqual({ a: 'original', b: 5 });
+  });
+
+  it('should reset dynamically added variables', () => {
+    const defs: PageVariable[] = [
+      { name: 'x', type: 'number', defaultValue: 1 },
+    ];
+    const { result } = renderHook(() => usePageVariables(), {
+      wrapper: createWrapper(defs),
+    });
+
+    act(() => {
+      result.current.setVariable('extra', 'gone');
+    });
+    expect(result.current.variables.extra).toBe('gone');
+
+    act(() => {
+      result.current.resetVariables();
+    });
+    // 'extra' was not in definitions, so it's removed on reset
+    expect(result.current.variables).toEqual({ x: 1 });
+  });
+});

package/src/__tests__/usePerformance.test.ts

@@ -0,0 +1,137 @@
+/**
+ * ObjectUI — usePerformance Tests
+ * 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, afterEach } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import { usePerformance } from '../hooks/usePerformance';
+
+describe('usePerformance', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('should return default config values', () => {
+    const { result } = renderHook(() => usePerformance());
+
+    expect(result.current.config).toEqual({
+      lazyLoad: true,
+      cacheStrategy: 'stale-while-revalidate',
+      prefetch: false,
+      pageSize: 50,
+      debounceMs: 300,
+      virtualScroll: {
+        enabled: false,
+        itemHeight: 40,
+        overscan: 5,
+      },
+    });
+  });
+
+  it('should merge user config with defaults', () => {
+    const { result } = renderHook(() =>
+      usePerformance({
+        lazyLoad: false,
+        pageSize: 100,
+        virtualScroll: { enabled: true, itemHeight: 60 },
+      }),
+    );
+
+    expect(result.current.config.lazyLoad).toBe(false);
+    expect(result.current.config.pageSize).toBe(100);
+    expect(result.current.config.virtualScroll.enabled).toBe(true);
+    expect(result.current.config.virtualScroll.itemHeight).toBe(60);
+    // Default overscan preserved
+    expect(result.current.config.virtualScroll.overscan).toBe(5);
+  });
+
+  it('should accept all cache strategy values', () => {
+    for (const strategy of [
+      'none',
+      'cache-first',
+      'network-first',
+      'stale-while-revalidate',
+    ] as const) {
+      const { result } = renderHook(() =>
+        usePerformance({ cacheStrategy: strategy }),
+      );
+      expect(result.current.config.cacheStrategy).toBe(strategy);
+    }
+  });
+
+  it('should track render count via markRenderStart', () => {
+    const { result } = renderHook(() => usePerformance());
+
+    // Initial render count should be 0 (only increments when markRenderStart stop is called)
+    expect(result.current.metrics.renderCount).toBe(0);
+
+    // After calling markRenderStart and its stop function, count should increment
+    act(() => {
+      const stop = result.current.markRenderStart();
+      stop();
+    });
+    expect(result.current.metrics.renderCount).toBeGreaterThanOrEqual(1);
+  });
+
+  it('should provide markRenderStart that returns stop function', () => {
+    const { result } = renderHook(() => usePerformance());
+
+    let stop: () => void;
+    act(() => {
+      stop = result.current.markRenderStart();
+    });
+
+    // stop should be a function
+    expect(typeof stop!).toBe('function');
+
+    act(() => {
+      stop();
+    });
+
+    // After calling stop, lastRenderDuration should be a number
+    expect(result.current.metrics.lastRenderDuration).toBeTypeOf('number');
+    expect(result.current.metrics.lastRenderDuration!).toBeGreaterThanOrEqual(0);
+  });
+
+  it('should create a debounced function', async () => {
+    const { result } = renderHook(() => usePerformance({ debounceMs: 100 }));
+
+    const callback = vi.fn();
+    let debounced: typeof callback;
+
+    act(() => {
+      debounced = result.current.debounce(callback);
+    });
+
+    // Call the debounced function multiple times in quick succession
+    act(() => {
+      debounced!('arg1');
+    });
+
+    // Callback not called immediately
+    expect(callback).not.toHaveBeenCalled();
+
+    // Wait for debounce to fire
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 150));
+    });
+
+    // Called once with the last arguments
+    expect(callback).toHaveBeenCalledTimes(1);
+    expect(callback).toHaveBeenCalledWith('arg1');
+  });
+
+  it('should provide initial metrics with null values', () => {
+    const { result } = renderHook(() => usePerformance());
+
+    // FCP and LCP may be null in test environment
+    expect(result.current.metrics.lcp).toBeNull();
+    expect(result.current.metrics.fcp).toBeNull();
+    expect(result.current.metrics.tti).toBeNull();
+    expect(result.current.metrics.lastRenderDuration).toBeNull();
+  });
+});