@object-ui/react 2.0.0 → 3.0.0

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

@@ -0,0 +1,93 @@
+/**
+ * Tests for useColumnSummary hook
+ */
+import { describe, it, expect } from 'vitest';
+import { renderHook } from '@testing-library/react';
+import { useColumnSummary } from '../useColumnSummary';
+
+const sampleData = [
+  { name: 'Alice', amount: 100, category: 'A' },
+  { name: 'Bob', amount: 200, category: 'B' },
+  { name: 'Charlie', amount: 300, category: 'A' },
+  { name: 'Diana', amount: 400, category: 'C' },
+];
+
+describe('useColumnSummary', () => {
+  it('computes sum correctly', () => {
+    const { result } = renderHook(() =>
+      useColumnSummary(sampleData, { field: 'amount', function: 'sum' })
+    );
+    expect(result.current.value).toBe(1000);
+    expect(result.current.label).toBe('SUM');
+  });
+
+  it('computes avg correctly', () => {
+    const { result } = renderHook(() =>
+      useColumnSummary(sampleData, { field: 'amount', function: 'avg' })
+    );
+    expect(result.current.value).toBe(250);
+  });
+
+  it('computes count correctly', () => {
+    const { result } = renderHook(() =>
+      useColumnSummary(sampleData, { field: 'amount', function: 'count' })
+    );
+    expect(result.current.value).toBe(4);
+  });
+
+  it('computes min correctly', () => {
+    const { result } = renderHook(() =>
+      useColumnSummary(sampleData, { field: 'amount', function: 'min' })
+    );
+    expect(result.current.value).toBe(100);
+  });
+
+  it('computes max correctly', () => {
+    const { result } = renderHook(() =>
+      useColumnSummary(sampleData, { field: 'amount', function: 'max' })
+    );
+    expect(result.current.value).toBe(400);
+  });
+
+  it('computes distinct correctly', () => {
+    const { result } = renderHook(() =>
+      useColumnSummary(sampleData, { field: 'category', function: 'distinct' })
+    );
+    expect(result.current.value).toBe(3); // A, B, C
+  });
+
+  it('uses custom label', () => {
+    const { result } = renderHook(() =>
+      useColumnSummary(sampleData, { field: 'amount', function: 'sum', label: 'Total Revenue' })
+    );
+    expect(result.current.label).toBe('Total Revenue');
+  });
+
+  it('returns formatted string', () => {
+    const { result } = renderHook(() =>
+      useColumnSummary(sampleData, { field: 'amount', function: 'sum' }, 'en-US')
+    );
+    expect(result.current.formatted).toBe('1,000');
+  });
+
+  it('handles empty data for sum', () => {
+    const { result } = renderHook(() =>
+      useColumnSummary([], { field: 'amount', function: 'sum' })
+    );
+    expect(result.current.value).toBe(0);
+  });
+
+  it('handles empty data for avg', () => {
+    const { result } = renderHook(() =>
+      useColumnSummary([], { field: 'amount', function: 'avg' })
+    );
+    expect(result.current.value).toBe(0);
+  });
+
+  it('handles empty data for min', () => {
+    const { result } = renderHook(() =>
+      useColumnSummary([], { field: 'amount', function: 'min' })
+    );
+    expect(result.current.value).toBe(0);
+  });
+});

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

@@ -0,0 +1,81 @@
+/**
+ * Tests for useDensityMode hook
+ */
+import { describe, it, expect } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import { useDensityMode } from '../useDensityMode';
+
+describe('useDensityMode', () => {
+  it('defaults to comfortable mode', () => {
+    const { result } = renderHook(() => useDensityMode());
+    expect(result.current.mode).toBe('comfortable');
+  });
+
+  it('accepts initial mode', () => {
+    const { result } = renderHook(() => useDensityMode('compact'));
+    expect(result.current.mode).toBe('compact');
+  });
+
+  it('provides correct row height for compact', () => {
+    const { result } = renderHook(() => useDensityMode('compact'));
+    expect(result.current.rowHeight).toBe(32);
+  });
+
+  it('provides correct row height for comfortable', () => {
+    const { result } = renderHook(() => useDensityMode('comfortable'));
+    expect(result.current.rowHeight).toBe(40);
+  });
+
+  it('provides correct row height for spacious', () => {
+    const { result } = renderHook(() => useDensityMode('spacious'));
+    expect(result.current.rowHeight).toBe(52);
+  });
+
+  it('provides padding classes', () => {
+    const { result } = renderHook(() => useDensityMode('compact'));
+    expect(result.current.paddingClass).toContain('py-1');
+    expect(result.current.paddingClass).toContain('px-2');
+  });
+
+  it('provides font size classes', () => {
+    const { result } = renderHook(() => useDensityMode('compact'));
+    expect(result.current.fontSizeClass).toBe('text-xs');
+  });
+
+  it('cycles through modes', () => {
+    const { result } = renderHook(() => useDensityMode('compact'));
+
+    act(() => {
+      result.current.cycle();
+    });
+    expect(result.current.mode).toBe('comfortable');
+
+    act(() => {
+      result.current.cycle();
+    });
+    expect(result.current.mode).toBe('spacious');
+
+    act(() => {
+      result.current.cycle();
+    });
+    expect(result.current.mode).toBe('compact');
+  });
+
+  it('allows setting mode directly', () => {
+    const { result } = renderHook(() => useDensityMode());
+
+    act(() => {
+      result.current.setMode('spacious');
+    });
+    expect(result.current.mode).toBe('spacious');
+  });
+
+  it('accepts custom row heights', () => {
+    const { result } = renderHook(() =>
+      useDensityMode('compact', {
+        rowHeights: { compact: 24, comfortable: 36, spacious: 48 },
+      })
+    );
+    expect(result.current.rowHeight).toBe(24);
+  });
+});

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

@@ -0,0 +1,153 @@
+/**
+ * Tests for useETagCache hook
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import { useETagCache } from '../useETagCache';
+
+describe('useETagCache', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    // Clear the module-scoped memory cache between tests
+    const { result } = renderHook(() => useETagCache());
+    act(() => {
+      result.current.clearCache();
+    });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('returns initial state with cacheSize: 0', () => {
+    const { result } = renderHook(() => useETagCache());
+
+    expect(result.current.cacheSize).toBe(0);
+    expect(result.current.serviceWorkerActive).toBe(false);
+    expect(result.current.fetchWithETag).toBeTypeOf('function');
+    expect(result.current.invalidate).toBeTypeOf('function');
+    expect(result.current.clearCache).toBeTypeOf('function');
+  });
+
+  it('fetchWithETag makes a network request and caches the response', async () => {
+    const mockData = { id: 1, name: 'Test' };
+    const mockHeaders = new Headers({ etag: '"abc123"' });
+    vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+      new Response(JSON.stringify(mockData), {
+        status: 200,
+        headers: mockHeaders,
+      }),
+    );
+
+    const { result } = renderHook(() => useETagCache());
+
+    let response: { data: unknown; fromCache: boolean; etag?: string } | undefined;
+    await act(async () => {
+      response = await result.current.fetchWithETag('/api/test');
+    });
+
+    expect(response!.data).toEqual(mockData);
+    expect(response!.fromCache).toBe(false);
+    expect(response!.etag).toBe('"abc123"');
+    expect(result.current.cacheSize).toBe(1);
+  });
+
+  it('fetchWithETag sends If-None-Match header on subsequent requests', async () => {
+    const mockData = { id: 1 };
+    const fetchSpy = vi.spyOn(globalThis, 'fetch');
+
+    // First request — returns data with ETag
+    fetchSpy.mockResolvedValueOnce(
+      new Response(JSON.stringify(mockData), {
+        status: 200,
+        headers: new Headers({ etag: '"etag-1"' }),
+      }),
+    );
+
+    const { result } = renderHook(() => useETagCache());
+
+    await act(async () => {
+      await result.current.fetchWithETag('/api/data');
+    });
+
+    // Second request — server returns 304
+    fetchSpy.mockResolvedValueOnce(
+      new Response(null, { status: 304 }),
+    );
+
+    let response: { data: unknown; fromCache: boolean; etag?: string } | undefined;
+    await act(async () => {
+      response = await result.current.fetchWithETag('/api/data');
+    });
+
+    // Verify If-None-Match was sent
+    const secondCallArgs = fetchSpy.mock.calls[1];
+    const headers = secondCallArgs[1]?.headers as Headers;
+    expect(headers.get('If-None-Match')).toBe('"etag-1"');
+    expect(response!.fromCache).toBe(true);
+    expect(response!.data).toEqual(mockData);
+  });
+
+  it('invalidate removes a specific cache entry', async () => {
+    const mockData = { id: 1 };
+    vi.spyOn(globalThis, 'fetch').mockResolvedValueOnce(
+      new Response(JSON.stringify(mockData), {
+        status: 200,
+        headers: new Headers({ etag: '"etag-x"' }),
+      }),
+    );
+
+    const { result } = renderHook(() => useETagCache());
+
+    await act(async () => {
+      await result.current.fetchWithETag('/api/item');
+    });
+    expect(result.current.cacheSize).toBe(1);
+
+    act(() => {
+      result.current.invalidate('/api/item');
+    });
+
+    expect(result.current.cacheSize).toBe(0);
+  });
+
+  it('clearCache removes all entries', async () => {
+    const fetchSpy = vi.spyOn(globalThis, 'fetch');
+
+    fetchSpy.mockResolvedValueOnce(
+      new Response(JSON.stringify({ a: 1 }), {
+        status: 200,
+        headers: new Headers({ etag: '"e1"' }),
+      }),
+    );
+    fetchSpy.mockResolvedValueOnce(
+      new Response(JSON.stringify({ b: 2 }), {
+        status: 200,
+        headers: new Headers({ etag: '"e2"' }),
+      }),
+    );
+
+    const { result } = renderHook(() => useETagCache());
+
+    await act(async () => {
+      await result.current.fetchWithETag('/api/a');
+    });
+    await act(async () => {
+      await result.current.fetchWithETag('/api/b');
+    });
+
+    expect(result.current.cacheSize).toBe(2);
+
+    act(() => {
+      result.current.clearCache();
+    });
+
+    expect(result.current.cacheSize).toBe(0);
+  });
+
+  it('serviceWorkerActive is false initially', () => {
+    const { result } = renderHook(() => useETagCache());
+
+    expect(result.current.serviceWorkerActive).toBe(false);
+  });
+});

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

@@ -0,0 +1,47 @@
+/**
+ * Tests for useFocusTrap hook
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import { useFocusTrap } from '../useFocusTrap';
+
+describe('useFocusTrap', () => {
+  it('returns a ref object', () => {
+    const { result } = renderHook(() => useFocusTrap());
+    expect(result.current).toBeDefined();
+    expect(result.current).toHaveProperty('current');
+  });
+
+  it('returns a ref with null initial value', () => {
+    const { result } = renderHook(() => useFocusTrap());
+    expect(result.current.current).toBeNull();
+  });
+
+  it('accepts disabled option', () => {
+    const { result } = renderHook(() =>
+      useFocusTrap({ enabled: false })
+    );
+    expect(result.current).toBeDefined();
+  });
+
+  it('accepts all options without error', () => {
+    const onEscape = vi.fn();
+    const { result } = renderHook(() =>
+      useFocusTrap({
+        enabled: true,
+        autoFocus: true,
+        restoreFocus: true,
+        escapeDeactivates: true,
+        onEscape,
+        initialFocus: '.first-input',
+      })
+    );
+    expect(result.current).toBeDefined();
+  });
+
+  it('defaults to enabled when no options provided', () => {
+    const { result } = renderHook(() => useFocusTrap());
+    // Should not throw
+    expect(result.current.current).toBeNull();
+  });
+});

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

@@ -0,0 +1,144 @@
+/**
+ * Tests for useKeyboardShortcuts hook
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { renderHook } from '@testing-library/react';
+import { useKeyboardShortcuts, getShortcutDescriptions } from '../useKeyboardShortcuts';
+import type { KeyboardShortcutDefinition } from '../useKeyboardShortcuts';
+
+describe('useKeyboardShortcuts', () => {
+  it('registers shortcuts without error', () => {
+    const handler = vi.fn();
+    const shortcuts: KeyboardShortcutDefinition[] = [
+      { key: 'k', ctrlOrMeta: true, handler, description: 'Search' },
+    ];
+
+    expect(() => {
+      renderHook(() => useKeyboardShortcuts(shortcuts));
+    }).not.toThrow();
+  });
+
+  it('handles empty shortcuts array', () => {
+    expect(() => {
+      renderHook(() => useKeyboardShortcuts([]));
+    }).not.toThrow();
+  });
+
+  it('respects enabled option', () => {
+    const handler = vi.fn();
+    const shortcuts: KeyboardShortcutDefinition[] = [
+      { key: 'k', handler },
+    ];
+
+    expect(() => {
+      renderHook(() => useKeyboardShortcuts(shortcuts, { enabled: false }));
+    }).not.toThrow();
+  });
+
+  it('fires handler on matching keyboard event', () => {
+    const handler = vi.fn();
+    const shortcuts: KeyboardShortcutDefinition[] = [
+      { key: 'Escape', handler },
+    ];
+
+    renderHook(() => useKeyboardShortcuts(shortcuts));
+
+    // Simulate keydown
+    const event = new KeyboardEvent('keydown', {
+      key: 'Escape',
+      bubbles: true,
+    });
+    document.dispatchEvent(event);
+
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not fire handler for non-matching key', () => {
+    const handler = vi.fn();
+    const shortcuts: KeyboardShortcutDefinition[] = [
+      { key: 'k', ctrlOrMeta: true, handler },
+    ];
+
+    renderHook(() => useKeyboardShortcuts(shortcuts));
+
+    const event = new KeyboardEvent('keydown', {
+      key: 'k',
+      bubbles: true,
+      // No ctrl or meta
+    });
+    document.dispatchEvent(event);
+
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it('fires handler when modifier keys match', () => {
+    const handler = vi.fn();
+    const shortcuts: KeyboardShortcutDefinition[] = [
+      { key: 'k', ctrlOrMeta: true, handler },
+    ];
+
+    renderHook(() => useKeyboardShortcuts(shortcuts));
+
+    const event = new KeyboardEvent('keydown', {
+      key: 'k',
+      ctrlKey: true,
+      bubbles: true,
+    });
+    document.dispatchEvent(event);
+
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+
+  it('skips disabled shortcuts', () => {
+    const handler = vi.fn();
+    const shortcuts: KeyboardShortcutDefinition[] = [
+      { key: 'k', handler, enabled: false },
+    ];
+
+    renderHook(() => useKeyboardShortcuts(shortcuts));
+
+    const event = new KeyboardEvent('keydown', {
+      key: 'k',
+      bubbles: true,
+    });
+    document.dispatchEvent(event);
+
+    expect(handler).not.toHaveBeenCalled();
+  });
+});
+
+describe('getShortcutDescriptions', () => {
+  it('returns formatted descriptions', () => {
+    const shortcuts: KeyboardShortcutDefinition[] = [
+      { key: 'k', ctrlOrMeta: true, handler: vi.fn(), description: 'Search' },
+      { key: 'n', ctrlOrMeta: true, shift: true, handler: vi.fn(), description: 'New' },
+      { key: 'Escape', handler: vi.fn(), description: 'Close' },
+    ];
+
+    const descriptions = getShortcutDescriptions(shortcuts);
+
+    expect(descriptions).toHaveLength(3);
+    expect(descriptions[0]).toEqual({ keys: '⌘/Ctrl + K', description: 'Search' });
+    expect(descriptions[1]).toEqual({ keys: '⌘/Ctrl + Shift + N', description: 'New' });
+    expect(descriptions[2]).toEqual({ keys: 'Escape', description: 'Close' });
+  });
+
+  it('excludes shortcuts without descriptions', () => {
+    const shortcuts: KeyboardShortcutDefinition[] = [
+      { key: 'k', handler: vi.fn() },
+      { key: 'n', handler: vi.fn(), description: 'New' },
+    ];
+
+    const descriptions = getShortcutDescriptions(shortcuts);
+    expect(descriptions).toHaveLength(1);
+  });
+
+  it('excludes disabled shortcuts', () => {
+    const shortcuts: KeyboardShortcutDefinition[] = [
+      { key: 'k', handler: vi.fn(), description: 'Search', enabled: false },
+    ];
+
+    const descriptions = getShortcutDescriptions(shortcuts);
+    expect(descriptions).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,157 @@
+/**
+ * Tests for usePerformanceBudget hook
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import { usePerformanceBudget } from '../usePerformanceBudget';
+
+describe('usePerformanceBudget', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it('returns default budget config when no config provided', () => {
+    const { result } = renderHook(() => usePerformanceBudget());
+
+    // Default snapshot values
+    expect(result.current.snapshot).toEqual({
+      lcp: null,
+      fcp: null,
+      memoryMB: null,
+    });
+    expect(result.current.clearViolations).toBeTypeOf('function');
+    expect(result.current.checkMetric).toBeTypeOf('function');
+    expect(result.current.trackRender).toBeTypeOf('function');
+  });
+
+  it('isWithinBudget is true initially (no violations)', () => {
+    const { result } = renderHook(() => usePerformanceBudget());
+
+    expect(result.current.isWithinBudget).toBe(true);
+    expect(result.current.violations).toEqual([]);
+  });
+
+  it('trackRender records a violation when render exceeds maxRenderTime', () => {
+    const { result } = renderHook(() =>
+      usePerformanceBudget({ maxRenderTime: 16, warnOnViolation: false }),
+    );
+
+    act(() => {
+      result.current.trackRender(50);
+    });
+
+    expect(result.current.violations).toHaveLength(1);
+    expect(result.current.violations[0].metric).toBe('renderTime');
+    expect(result.current.violations[0].actual).toBe(50);
+    expect(result.current.violations[0].budget).toBe(16);
+    expect(result.current.isWithinBudget).toBe(false);
+  });
+
+  it('trackRender does NOT record when render is within budget', () => {
+    const { result } = renderHook(() =>
+      usePerformanceBudget({ maxRenderTime: 16, warnOnViolation: false }),
+    );
+
+    let withinBudget: boolean = false;
+    act(() => {
+      withinBudget = result.current.trackRender(10);
+    });
+
+    expect(withinBudget).toBe(true);
+    expect(result.current.violations).toHaveLength(0);
+    expect(result.current.isWithinBudget).toBe(true);
+  });
+
+  it('checkMetric returns false for metrics exceeding budget', () => {
+    const { result } = renderHook(() =>
+      usePerformanceBudget({ maxLCP: 600, warnOnViolation: false }),
+    );
+
+    let withinBudget: boolean = true;
+    act(() => {
+      withinBudget = result.current.checkMetric('lcp', 800);
+    });
+
+    expect(withinBudget).toBe(false);
+    expect(result.current.violations).toHaveLength(1);
+    expect(result.current.violations[0].metric).toBe('lcp');
+  });
+
+  it('checkMetric returns true for metrics within budget', () => {
+    const { result } = renderHook(() =>
+      usePerformanceBudget({ maxLCP: 600, warnOnViolation: false }),
+    );
+
+    let withinBudget: boolean = false;
+    act(() => {
+      withinBudget = result.current.checkMetric('lcp', 400);
+    });
+
+    expect(withinBudget).toBe(true);
+    expect(result.current.violations).toHaveLength(0);
+  });
+
+  it('clearViolations removes all violations', () => {
+    const { result } = renderHook(() =>
+      usePerformanceBudget({ maxRenderTime: 16, warnOnViolation: false }),
+    );
+
+    act(() => {
+      result.current.trackRender(50);
+    });
+    expect(result.current.violations).toHaveLength(1);
+
+    act(() => {
+      result.current.clearViolations();
+    });
+
+    expect(result.current.violations).toHaveLength(0);
+    expect(result.current.isWithinBudget).toBe(true);
+  });
+
+  it('deduplication: same metric type only recorded once', () => {
+    const { result } = renderHook(() =>
+      usePerformanceBudget({ maxRenderTime: 16, warnOnViolation: false }),
+    );
+
+    act(() => {
+      result.current.trackRender(50);
+    });
+    act(() => {
+      result.current.trackRender(100);
+    });
+
+    // Only one violation for 'renderTime' due to deduplication
+    expect(result.current.violations).toHaveLength(1);
+    expect(result.current.violations[0].metric).toBe('renderTime');
+  });
+
+  it('onViolation callback is called on budget violation', () => {
+    const onViolation = vi.fn();
+    const { result } = renderHook(() =>
+      usePerformanceBudget({
+        maxRenderTime: 16,
+        warnOnViolation: false,
+        onViolation,
+      }),
+    );
+
+    act(() => {
+      result.current.trackRender(50);
+    });
+
+    expect(onViolation).toHaveBeenCalledTimes(1);
+    expect(onViolation).toHaveBeenCalledWith(
+      expect.objectContaining({
+        metric: 'renderTime',
+        budget: 16,
+        actual: 50,
+      }),
+    );
+  });
+});