@react-spa-scaffold/mcp 2.1.1 → 2.2.0

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];
+}

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

@@ -0,0 +1,119 @@
+import { act, renderHook } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+
+import { useSyncedState } from './useSyncedState';
+
+describe('useSyncedState', () => {
+  it('returns external value initially', () => {
+    const { result } = renderHook(() => useSyncedState('initial', false));
+    expect(result.current[0]).toBe('initial');
+  });
+
+  it('updates local value via setter', () => {
+    const { result } = renderHook(() => useSyncedState('initial', false));
+
+    act(() => {
+      result.current[1]('local-change');
+    });
+
+    expect(result.current[0]).toBe('local-change');
+  });
+
+  it('syncs with external value when not active', () => {
+    const { result, rerender } = renderHook(({ externalValue, isActive }) => useSyncedState(externalValue, isActive), {
+      initialProps: { externalValue: 'v1', isActive: false },
+    });
+
+    expect(result.current[0]).toBe('v1');
+
+    // External value changes while not active - should sync
+    rerender({ externalValue: 'v2', isActive: false });
+    expect(result.current[0]).toBe('v2');
+  });
+
+  it('does not sync with external value while active', () => {
+    const { result, rerender } = renderHook(({ externalValue, isActive }) => useSyncedState(externalValue, isActive), {
+      initialProps: { externalValue: 'v1', isActive: true },
+    });
+
+    // Initial sync when becoming active
+    expect(result.current[0]).toBe('v1');
+
+    // User makes local edit while active
+    act(() => {
+      result.current[1]('local-edit');
+    });
+    expect(result.current[0]).toBe('local-edit');
+
+    // External value changes while still active - should NOT sync (preserve user edit)
+    rerender({ externalValue: 'v2', isActive: true });
+    expect(result.current[0]).toBe('local-edit');
+  });
+
+  it('syncs when switching from active to inactive', () => {
+    const { result, rerender } = renderHook(({ externalValue, isActive }) => useSyncedState(externalValue, isActive), {
+      initialProps: { externalValue: 'v1', isActive: true },
+    });
+
+    // Make local edit while active
+    act(() => {
+      result.current[1]('local-edit');
+    });
+    expect(result.current[0]).toBe('local-edit');
+
+    // External value changed while we were editing
+    rerender({ externalValue: 'v2', isActive: true });
+    expect(result.current[0]).toBe('local-edit');
+
+    // Switch to inactive - should sync with new external value
+    rerender({ externalValue: 'v2', isActive: false });
+    expect(result.current[0]).toBe('v2');
+  });
+
+  it('syncs when switching from inactive to active (e.g., opening drawer)', () => {
+    const { result, rerender } = renderHook(({ externalValue, isActive }) => useSyncedState(externalValue, isActive), {
+      initialProps: { externalValue: '', isActive: false },
+    });
+
+    expect(result.current[0]).toBe('');
+
+    // Simulate opening a drawer with new content - external value and isActive change together
+    rerender({ externalValue: 'section content', isActive: true });
+
+    // Should sync with the new external value when becoming active
+    expect(result.current[0]).toBe('section content');
+  });
+
+  it('preserves local edits while active after initial sync', () => {
+    const { result, rerender } = renderHook(({ externalValue, isActive }) => useSyncedState(externalValue, isActive), {
+      initialProps: { externalValue: '', isActive: false },
+    });
+
+    // Open drawer with content
+    rerender({ externalValue: 'initial content', isActive: true });
+    expect(result.current[0]).toBe('initial content');
+
+    // User edits locally
+    act(() => {
+      result.current[1]('user edited content');
+    });
+    expect(result.current[0]).toBe('user edited content');
+
+    // External value changes (e.g., from another source) - should NOT overwrite user edit
+    rerender({ externalValue: 'different content', isActive: true });
+    expect(result.current[0]).toBe('user edited content');
+  });
+
+  it('works with complex objects', () => {
+    const initial = { name: 'test', value: 1 };
+    const { result, rerender } = renderHook(({ externalValue, isActive }) => useSyncedState(externalValue, isActive), {
+      initialProps: { externalValue: initial, isActive: false },
+    });
+
+    expect(result.current[0]).toEqual(initial);
+
+    const updated = { name: 'updated', value: 2 };
+    rerender({ externalValue: updated, isActive: false });
+    expect(result.current[0]).toEqual(updated);
+  });
+});

package/templates/src/hooks/useSyncedState.ts

@@ -0,0 +1,30 @@
+import { useEffect, useRef, useState, type Dispatch, type SetStateAction } from 'react';
+
+/**
+ * Syncs local state with an external value, but only when not actively editing.
+ * Prevents external updates from overwriting user input mid-edit.
+ *
+ * @param externalValue - The external/server value to sync from
+ * @param isActive - Whether the user is currently editing (blocks sync)
+ */
+export function useSyncedState<T>(externalValue: T, isActive: boolean): [T, Dispatch<SetStateAction<T>>] {
+  const [localValue, setLocalValue] = useState<T>(externalValue);
+  const prevIsActiveRef = useRef(isActive);
+
+  // Sync external value to local state when:
+  // 1. Not active (external updates flow through)
+  // 2. Activity state changed (sync on open/close transitions)
+  // This is an intentional pattern for synchronizing external props to local state
+  useEffect(() => {
+    const activityChanged = prevIsActiveRef.current !== isActive;
+
+    if (!isActive || activityChanged) {
+      // eslint-disable-next-line react-hooks/set-state-in-effect -- Intentional sync pattern
+      setLocalValue(externalValue);
+    }
+
+    prevIsActiveRef.current = isActive;
+  }, [externalValue, isActive]);
+
+  return [localValue, setLocalValue];
+}

package/templates/src/index.css

@@ -1,6 +1,7 @@
 @import 'tailwindcss';
 @import 'tw-animate-css';
 @import 'shadcn/tailwind.css';
+@import '@clerk/themes/shadcn.css';
 @import '@fontsource-variable/inter';
 
 @custom-variant dark (&:is(.dark *));

package/templates/src/lib/constants.ts

@@ -0,0 +1,10 @@
+/**
+ * Centralized timing constants for consistent UX across the application.
+ * Use these instead of magic numbers to ensure consistency.
+ */
+export const TIMING = {
+  /** Debounce delay for user input in milliseconds */
+  DEBOUNCE_DELAY: 300,
+  /** Duration to show "Copied!" feedback in milliseconds */
+  COPY_FEEDBACK_DURATION: 2000,
+} as const;