@react-spa-scaffold/mcp 2.1.0 → 2.2.0

package/templates/src/hooks/useDocumentTitle.test.ts

@@ -0,0 +1,59 @@
+import { renderHook } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+vi.mock('@/lib/config', () => ({
+  APP_CONFIG: { name: 'TestApp' },
+}));
+
+import { useDocumentTitle } from './useDocumentTitle';
+
+describe('useDocumentTitle', () => {
+  const originalTitle = 'Original Title';
+
+  beforeEach(() => {
+    document.title = originalTitle;
+  });
+
+  afterEach(() => {
+    document.title = originalTitle;
+  });
+
+  it('sets document title with app name suffix', () => {
+    renderHook(() => useDocumentTitle('My Page'));
+    expect(document.title).toBe('My Page | TestApp');
+  });
+
+  it('sets just app name when title is undefined', () => {
+    renderHook(() => useDocumentTitle(undefined));
+    expect(document.title).toBe('TestApp');
+  });
+
+  it('sets just app name when title is empty string', () => {
+    renderHook(() => useDocumentTitle(''));
+    expect(document.title).toBe('TestApp');
+  });
+
+  it('restores previous title on unmount', () => {
+    const { unmount } = renderHook(() => useDocumentTitle('My Page'));
+    expect(document.title).toBe('My Page | TestApp');
+
+    unmount();
+    expect(document.title).toBe(originalTitle);
+  });
+
+  it('updates title when title prop changes', () => {
+    const { rerender } = renderHook(({ title }) => useDocumentTitle(title), {
+      initialProps: { title: 'Page 1' },
+    });
+
+    expect(document.title).toBe('Page 1 | TestApp');
+
+    rerender({ title: 'Page 2' });
+    expect(document.title).toBe('Page 2 | TestApp');
+  });
+
+  it('handles title with special characters', () => {
+    renderHook(() => useDocumentTitle('Page & "Title" | More'));
+    expect(document.title).toBe('Page & "Title" | More | TestApp');
+  });
+});

package/templates/src/hooks/useDocumentTitle.ts

@@ -0,0 +1,31 @@
+import { useEffect, useRef } from 'react';
+
+import { APP_CONFIG } from '@/lib/config';
+
+/**
+ * Sets the document title dynamically, with cleanup on unmount.
+ *
+ * @param title - The page title (will be formatted as "{title} | {APP_NAME}")
+ */
+export function useDocumentTitle(title?: string): void {
+  const previousTitleRef = useRef<string | undefined>(undefined);
+
+  useEffect(() => {
+    if (typeof document === 'undefined') return;
+
+    // Store previous title on first run
+    if (previousTitleRef.current === undefined) {
+      previousTitleRef.current = document.title;
+    }
+
+    // Format title as "{title} | {APP_NAME}" or just "{APP_NAME}" if empty
+    document.title = title ? `${title} | ${APP_CONFIG.name}` : APP_CONFIG.name;
+
+    return () => {
+      // Restore previous title on unmount
+      if (previousTitleRef.current !== undefined) {
+        document.title = previousTitleRef.current;
+      }
+    };
+  }, [title]);
+}

package/templates/src/hooks/useIOSViewportReset.test.ts

@@ -0,0 +1,58 @@
+import { renderHook } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { useIOSViewportReset } from './useIOSViewportReset';
+
+describe('useIOSViewportReset', () => {
+  it('returns a stable blur handler function', () => {
+    const { result, rerender } = renderHook(() => useIOSViewportReset());
+
+    const firstRef = result.current;
+    rerender();
+    const secondRef = result.current;
+
+    expect(typeof firstRef).toBe('function');
+    expect(firstRef).toBe(secondRef);
+  });
+
+  it('scrolls to top when blur handler is called', () => {
+    vi.useFakeTimers();
+    const scrollToSpy = vi.spyOn(window, 'scrollTo').mockImplementation(() => {});
+
+    const { result } = renderHook(() => useIOSViewportReset());
+
+    // Call the blur handler
+    result.current();
+
+    // Should not scroll immediately
+    expect(scrollToSpy).not.toHaveBeenCalled();
+
+    // Advance past the 50ms delay
+    vi.advanceTimersByTime(50);
+
+    expect(scrollToSpy).toHaveBeenCalledWith(0, 0);
+
+    scrollToSpy.mockRestore();
+    vi.useRealTimers();
+  });
+
+  it('is safe to call handler multiple times', () => {
+    vi.useFakeTimers();
+    const scrollToSpy = vi.spyOn(window, 'scrollTo').mockImplementation(() => {});
+
+    const { result } = renderHook(() => useIOSViewportReset());
+
+    // Call multiple times
+    result.current();
+    result.current();
+    result.current();
+
+    vi.advanceTimersByTime(50);
+
+    // Each call triggers a scroll
+    expect(scrollToSpy).toHaveBeenCalledTimes(3);
+
+    scrollToSpy.mockRestore();
+    vi.useRealTimers();
+  });
+});

package/templates/src/hooks/useIOSViewportReset.ts

@@ -0,0 +1,18 @@
+import { useCallback } from 'react';
+
+/**
+ * Returns a blur handler that fixes iOS Safari's viewport scroll bug
+ * when the keyboard is dismissed.
+ *
+ * Uses a 50ms delay to allow the viewport to settle before resetting.
+ */
+export function useIOSViewportReset(): () => void {
+  const handleBlur = useCallback(() => {
+    // Use setTimeout to allow viewport to settle after keyboard dismissal
+    setTimeout(() => {
+      window.scrollTo(0, 0);
+    }, 50);
+  }, []);
+
+  return handleBlur;
+}

package/templates/src/hooks/useKeyboardShortcut.test.ts

@@ -0,0 +1,86 @@
+import { renderHook } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { useKeyboardShortcut } from './useKeyboardShortcuts';
+
+// Mock react-hotkeys-hook
+vi.mock('react-hotkeys-hook', () => ({
+  useHotkeys: vi.fn(),
+}));
+
+import { useHotkeys } from 'react-hotkeys-hook';
+
+const mockedUseHotkeys = vi.mocked(useHotkeys);
+
+describe('useKeyboardShortcut', () => {
+  beforeEach(() => {
+    mockedUseHotkeys.mockClear();
+  });
+
+  it('calls useHotkeys with the correct shortcut and handler', () => {
+    const handler = vi.fn();
+
+    renderHook(() => useKeyboardShortcut('mod+s', handler));
+
+    expect(mockedUseHotkeys).toHaveBeenCalledWith(
+      'mod+s',
+      handler,
+      expect.objectContaining({
+        enableOnFormTags: false,
+        preventDefault: true,
+      }),
+      [handler],
+    );
+  });
+
+  it('respects custom options', () => {
+    const handler = vi.fn();
+
+    renderHook(() =>
+      useKeyboardShortcut('mod+enter', handler, {
+        enableOnFormTags: true,
+        preventDefault: false,
+      }),
+    );
+
+    expect(mockedUseHotkeys).toHaveBeenCalledWith(
+      'mod+enter',
+      handler,
+      expect.objectContaining({
+        enableOnFormTags: true,
+        preventDefault: false,
+      }),
+      [handler],
+    );
+  });
+
+  it('uses default options when not provided', () => {
+    const handler = vi.fn();
+
+    renderHook(() => useKeyboardShortcut('escape', handler));
+
+    expect(mockedUseHotkeys).toHaveBeenCalledWith(
+      'escape',
+      handler,
+      expect.objectContaining({
+        enableOnFormTags: false,
+        preventDefault: true,
+      }),
+      [handler],
+    );
+  });
+
+  it('can be used for multiple shortcuts by calling hook multiple times', () => {
+    const saveHandler = vi.fn();
+    const undoHandler = vi.fn();
+
+    renderHook(() => {
+      useKeyboardShortcut('mod+s', saveHandler);
+      useKeyboardShortcut('mod+z', undoHandler);
+    });
+
+    expect(mockedUseHotkeys).toHaveBeenCalledTimes(2);
+    expect(mockedUseHotkeys).toHaveBeenCalledWith('mod+s', saveHandler, expect.any(Object), [saveHandler]);
+    expect(mockedUseHotkeys).toHaveBeenCalledWith('mod+z', undoHandler, expect.any(Object), [undoHandler]);
+  });
+});

package/templates/src/hooks/useKeyboardShortcuts.ts

@@ -0,0 +1,44 @@
+import { useHotkeys, type Options } from 'react-hotkeys-hook';
+
+interface ShortcutOptions {
+  /** Enable shortcuts in form tags (input, textarea, select). Default: false */
+  enableOnFormTags?: boolean;
+  /** Prevent default browser behavior. Default: true */
+  preventDefault?: boolean;
+}
+
+const DEFAULT_OPTIONS: Required<ShortcutOptions> = {
+  enableOnFormTags: false,
+  preventDefault: true,
+};
+
+/**
+ * Registers a single keyboard shortcut with platform-aware modifiers.
+ * Uses react-hotkeys-hook under the hood.
+ *
+ * For multiple shortcuts, call this hook once for each shortcut.
+ *
+ * @param shortcut - The keyboard shortcut (e.g., 'mod+s', 'mod+enter')
+ * @param handler - Function to call when shortcut is triggered
+ * @param options - Configuration options for shortcut behavior
+ *
+ * @example
+ * ```tsx
+ * // Single shortcut
+ * useKeyboardShortcut('mod+s', () => handleSave());
+ *
+ * // Multiple shortcuts (call the hook multiple times)
+ * useKeyboardShortcut('mod+s', () => handleSave());
+ * useKeyboardShortcut('mod+z', () => handleUndo());
+ * ```
+ */
+export function useKeyboardShortcut(shortcut: string, handler: () => void, options: ShortcutOptions = {}): void {
+  const mergedOptions = { ...DEFAULT_OPTIONS, ...options };
+
+  const hotkeyOptions: Options = {
+    enableOnFormTags: mergedOptions.enableOnFormTags,
+    preventDefault: mergedOptions.preventDefault,
+  };
+
+  useHotkeys(shortcut, handler, hotkeyOptions, [handler]);
+}

package/templates/src/hooks/useLocalStorage.test.ts

@@ -0,0 +1,111 @@
+import { act, renderHook } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { useLocalStorage } from './useLocalStorage';
+
+describe('useLocalStorage', () => {
+  const key = 'test-key';
+  const initialValue = 'initial';
+
+  beforeEach(() => {
+    localStorage.clear();
+    vi.clearAllMocks();
+  });
+
+  it('returns initial value when localStorage is empty', () => {
+    const { result } = renderHook(() => useLocalStorage(key, initialValue));
+    expect(result.current[0]).toBe(initialValue);
+  });
+
+  it('returns stored value from localStorage', () => {
+    localStorage.setItem(key, JSON.stringify('stored'));
+    const { result } = renderHook(() => useLocalStorage(key, initialValue));
+    expect(result.current[0]).toBe('stored');
+  });
+
+  it('updates value with direct setter', () => {
+    const { result } = renderHook(() => useLocalStorage(key, initialValue));
+
+    act(() => {
+      result.current[1]('new-value');
+    });
+
+    expect(result.current[0]).toBe('new-value');
+    expect(JSON.parse(localStorage.getItem(key)!)).toBe('new-value');
+  });
+
+  it('updates value with updater function', () => {
+    const { result } = renderHook(() => useLocalStorage(key, 0));
+
+    act(() => {
+      result.current[1]((prev) => prev + 1);
+    });
+
+    expect(result.current[0]).toBe(1);
+  });
+
+  it('handles complex objects', () => {
+    const initial = { name: 'test', count: 0 };
+    const { result } = renderHook(() => useLocalStorage(key, initial));
+
+    act(() => {
+      result.current[1]({ name: 'updated', count: 1 });
+    });
+
+    expect(result.current[0]).toEqual({ name: 'updated', count: 1 });
+  });
+
+  it('re-reads from localStorage when key changes', () => {
+    localStorage.setItem('key-a', JSON.stringify('value-a'));
+    localStorage.setItem('key-b', JSON.stringify('value-b'));
+
+    const { result, rerender } = renderHook(({ k }) => useLocalStorage(k, 'default'), {
+      initialProps: { k: 'key-a' },
+    });
+
+    expect(result.current[0]).toBe('value-a');
+
+    rerender({ k: 'key-b' });
+    expect(result.current[0]).toBe('value-b');
+  });
+
+  it('handles JSON parse errors gracefully', () => {
+    localStorage.setItem(key, 'not-valid-json');
+    const consoleWarn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    const { result } = renderHook(() => useLocalStorage(key, initialValue));
+
+    expect(result.current[0]).toBe(initialValue);
+    consoleWarn.mockRestore();
+  });
+
+  it('syncs across tabs via storage event', () => {
+    const { result } = renderHook(() => useLocalStorage(key, initialValue));
+
+    act(() => {
+      window.dispatchEvent(
+        new StorageEvent('storage', {
+          key,
+          newValue: JSON.stringify('from-other-tab'),
+        }),
+      );
+    });
+
+    expect(result.current[0]).toBe('from-other-tab');
+  });
+
+  it('ignores storage events for different keys', () => {
+    const { result } = renderHook(() => useLocalStorage(key, initialValue));
+
+    act(() => {
+      window.dispatchEvent(
+        new StorageEvent('storage', {
+          key: 'other-key',
+          newValue: JSON.stringify('other-value'),
+        }),
+      );
+    });
+
+    expect(result.current[0]).toBe(initialValue);
+  });
+});

package/templates/src/hooks/useLocalStorage.ts

@@ -0,0 +1,77 @@
+import { useCallback, useEffect, useState } from 'react';
+
+/**
+ * useState-like hook with localStorage persistence.
+ * Syncs state across tabs via storage events.
+ *
+ * @param key - localStorage key
+ * @param initialValue - Default value when key doesn't exist
+ */
+export function useLocalStorage<T>(key: string, initialValue: T): [T, (value: T | ((prev: T) => T)) => void] {
+  // Lazy initialization reads from localStorage on first render
+  const [storedValue, setStoredValue] = useState<T>(() => {
+    if (typeof window === 'undefined') {
+      return initialValue;
+    }
+    try {
+      const item = localStorage.getItem(key);
+      return item ? (JSON.parse(item) as T) : initialValue;
+    } catch {
+      console.warn(`Failed to parse localStorage key "${key}"`);
+      return initialValue;
+    }
+  });
+
+  // Track the previous key to detect changes
+  const [prevKey, setPrevKey] = useState(key);
+
+  // Re-read from localStorage when key changes
+  if (key !== prevKey) {
+    setPrevKey(key);
+    try {
+      const item = localStorage.getItem(key);
+      const newValue = item ? (JSON.parse(item) as T) : initialValue;
+      setStoredValue(newValue);
+    } catch {
+      setStoredValue(initialValue);
+    }
+  }
+
+  // Sync to localStorage whenever value changes
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+    try {
+      localStorage.setItem(key, JSON.stringify(storedValue));
+    } catch (error) {
+      console.warn(`Failed to write localStorage key "${key}":`, error);
+    }
+  }, [key, storedValue]);
+
+  // Setter that supports both direct values and updater functions
+  const setValue = useCallback((value: T | ((prev: T) => T)) => {
+    setStoredValue((prev) => {
+      const nextValue = value instanceof Function ? value(prev) : value;
+      return nextValue;
+    });
+  }, []);
+
+  // Sync across tabs via storage events
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+
+    const handleStorage = (e: StorageEvent) => {
+      if (e.key === key && e.newValue !== null) {
+        try {
+          setStoredValue(JSON.parse(e.newValue) as T);
+        } catch {
+          // Ignore parse errors from other tabs
+        }
+      }
+    };
+
+    window.addEventListener('storage', handleStorage);
+    return () => window.removeEventListener('storage', handleStorage);
+  }, [key]);
+
+  return [storedValue, setValue];
+}

package/templates/src/hooks/useSyncedFormData.test.ts

@@ -0,0 +1,75 @@
+import { renderHook } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+
+import { useSyncedFormData } from './useSyncedFormData';
+
+describe('useSyncedFormData', () => {
+  it('returns source data initially', () => {
+    const { result } = renderHook(() => useSyncedFormData({ name: 'test' }, 'trigger-1'));
+    expect(result.current[0]).toEqual({ name: 'test' });
+  });
+
+  it('provides a setter function', () => {
+    const { result } = renderHook(() => useSyncedFormData({ name: 'initial' }, 'trigger-1'));
+    expect(typeof result.current[1]).toBe('function');
+  });
+
+  it('syncs when trigger value changes', () => {
+    const { result, rerender } = renderHook(
+      ({ sourceData, syncTrigger }) => useSyncedFormData(sourceData, syncTrigger),
+      { initialProps: { sourceData: { name: 'v1' }, syncTrigger: 'trigger-1' } },
+    );
+
+    expect(result.current[0]).toEqual({ name: 'v1' });
+
+    // Trigger changes - should sync to new source data
+    rerender({ sourceData: { name: 'v2' }, syncTrigger: 'trigger-2' });
+    expect(result.current[0]).toEqual({ name: 'v2' });
+  });
+
+  it('syncs when source data changes with same trigger', () => {
+    const { result, rerender } = renderHook(
+      ({ sourceData, syncTrigger }) => useSyncedFormData(sourceData, syncTrigger),
+      { initialProps: { sourceData: { name: 'v1' }, syncTrigger: 'trigger-1' } },
+    );
+
+    // Source data changes (trigger also changes per useEffect deps)
+    rerender({ sourceData: { name: 'v2' }, syncTrigger: 'trigger-1' });
+    // Per the implementation, it syncs when either trigger or sourceData changes
+    expect(result.current[0]).toEqual({ name: 'v2' });
+  });
+
+  it('handles dialog open/close pattern (boolean trigger)', () => {
+    const { result, rerender } = renderHook(
+      ({ sourceData, syncTrigger }) => useSyncedFormData(sourceData, syncTrigger),
+      { initialProps: { sourceData: { name: 'original' }, syncTrigger: false } },
+    );
+
+    // Dialog opens
+    rerender({ sourceData: { name: 'original' }, syncTrigger: true });
+    expect(result.current[0]).toEqual({ name: 'original' });
+
+    // Dialog closes
+    rerender({ sourceData: { name: 'original' }, syncTrigger: false });
+    expect(result.current[0]).toEqual({ name: 'original' });
+
+    // Dialog reopens with new data
+    rerender({ sourceData: { name: 'new-data' }, syncTrigger: true });
+    expect(result.current[0]).toEqual({ name: 'new-data' });
+  });
+
+  it('handles ID-based trigger pattern', () => {
+    const { result, rerender } = renderHook(
+      ({ sourceData, syncTrigger }) => useSyncedFormData(sourceData, syncTrigger),
+      { initialProps: { sourceData: { name: 'item-1' }, syncTrigger: 'id-1' } },
+    );
+
+    // Switch to item 2
+    rerender({ sourceData: { name: 'item-2' }, syncTrigger: 'id-2' });
+    expect(result.current[0]).toEqual({ name: 'item-2' });
+
+    // Switch back to item 1
+    rerender({ sourceData: { name: 'item-1' }, syncTrigger: 'id-1' });
+    expect(result.current[0]).toEqual({ name: 'item-1' });
+  });
+});

package/templates/src/hooks/useSyncedFormData.ts

@@ -0,0 +1,21 @@
+import { useEffect, useState, type Dispatch, type SetStateAction } from 'react';
+
+/**
+ * Syncs form data when a trigger condition changes (e.g., dialog opens, ID changes).
+ * Similar to useSyncedState but trigger-based rather than active-state-based.
+ *
+ * @param sourceData - The source data to sync from
+ * @param syncTrigger - Value that triggers a re-sync when changed (e.g., item ID, dialog open state)
+ */
+export function useSyncedFormData<T>(sourceData: T, syncTrigger: unknown): [T, Dispatch<SetStateAction<T>>] {
+  const [formData, setFormData] = useState<T>(sourceData);
+
+  // Sync form data when trigger changes
+  // This is an intentional pattern for synchronizing external props to local state
+  useEffect(() => {
+    // eslint-disable-next-line react-hooks/set-state-in-effect -- Intentional sync pattern
+    setFormData(sourceData);
+  }, [syncTrigger, sourceData]);
+
+  return [formData, setFormData];
+}