@react-spa-scaffold/mcp 2.1.1 → 2.3.0

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

@@ -0,0 +1,129 @@
+import { act, renderHook } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { TIMING } from '@/lib/constants';
+
+import { useCopyFeedback } from './useCopyFeedback';
+
+describe('useCopyFeedback', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('returns isCopied: false initially', () => {
+    const { result } = renderHook(() => useCopyFeedback());
+    expect(result.current.isCopied).toBe(false);
+  });
+
+  it('sets isCopied to true when triggerCopied is called', () => {
+    const { result } = renderHook(() => useCopyFeedback());
+
+    act(() => {
+      result.current.triggerCopied();
+    });
+
+    expect(result.current.isCopied).toBe(true);
+  });
+
+  it('resets isCopied to false after default duration', () => {
+    const { result } = renderHook(() => useCopyFeedback());
+
+    act(() => {
+      result.current.triggerCopied();
+    });
+    expect(result.current.isCopied).toBe(true);
+
+    // Just before duration ends
+    act(() => {
+      vi.advanceTimersByTime(TIMING.COPY_FEEDBACK_DURATION - 1);
+    });
+    expect(result.current.isCopied).toBe(true);
+
+    // At duration
+    act(() => {
+      vi.advanceTimersByTime(1);
+    });
+    expect(result.current.isCopied).toBe(false);
+  });
+
+  it('respects custom duration', () => {
+    const customDuration = 1000;
+    const { result } = renderHook(() => useCopyFeedback(customDuration));
+
+    act(() => {
+      result.current.triggerCopied();
+    });
+
+    act(() => {
+      vi.advanceTimersByTime(customDuration - 1);
+    });
+    expect(result.current.isCopied).toBe(true);
+
+    act(() => {
+      vi.advanceTimersByTime(1);
+    });
+    expect(result.current.isCopied).toBe(false);
+  });
+
+  it('resets timer if triggered again quickly', () => {
+    const duration = 1000;
+    const { result } = renderHook(() => useCopyFeedback(duration));
+
+    act(() => {
+      result.current.triggerCopied();
+    });
+
+    // Wait 500ms
+    act(() => {
+      vi.advanceTimersByTime(500);
+    });
+    expect(result.current.isCopied).toBe(true);
+
+    // Trigger again - resets timer
+    act(() => {
+      result.current.triggerCopied();
+    });
+
+    // Wait another 500ms (1000ms total from first trigger)
+    act(() => {
+      vi.advanceTimersByTime(500);
+    });
+    expect(result.current.isCopied).toBe(true);
+
+    // Wait remaining 500ms from second trigger
+    act(() => {
+      vi.advanceTimersByTime(500);
+    });
+    expect(result.current.isCopied).toBe(false);
+  });
+
+  it('cleans up timeout on unmount', () => {
+    const { result, unmount } = renderHook(() => useCopyFeedback(1000));
+
+    act(() => {
+      result.current.triggerCopied();
+    });
+
+    // Unmount before timeout completes - should not cause errors
+    unmount();
+
+    // This should not throw
+    act(() => {
+      vi.advanceTimersByTime(1000);
+    });
+  });
+
+  it('maintains stable triggerCopied reference', () => {
+    const { result, rerender } = renderHook(() => useCopyFeedback());
+
+    const firstRef = result.current.triggerCopied;
+    rerender();
+    const secondRef = result.current.triggerCopied;
+
+    expect(firstRef).toBe(secondRef);
+  });
+});

package/templates/src/hooks/useCopyFeedback.ts

@@ -0,0 +1,41 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import { TIMING } from '@/lib/constants';
+
+/**
+ * Manages temporary "Copied!" feedback state with automatic reset after a duration.
+ *
+ * @param duration - How long to show feedback (defaults to TIMING.COPY_FEEDBACK_DURATION)
+ */
+export function useCopyFeedback(duration: number = TIMING.COPY_FEEDBACK_DURATION): {
+  isCopied: boolean;
+  triggerCopied: () => void;
+} {
+  const [isCopied, setIsCopied] = useState(false);
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current);
+      }
+    };
+  }, []);
+
+  const triggerCopied = useCallback(() => {
+    // Clear any existing timeout
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+    }
+
+    setIsCopied(true);
+
+    // Reset after duration
+    timeoutRef.current = setTimeout(() => {
+      setIsCopied(false);
+    }, duration);
+  }, [duration]);
+
+  return { isCopied, triggerCopied };
+}

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

@@ -0,0 +1,164 @@
+import { act, renderHook } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { TIMING } from '@/lib/constants';
+
+import { useDebouncedCallback } from './useDebouncedCallback';
+
+describe('useDebouncedCallback', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('debounces callback execution', () => {
+    const callback = vi.fn();
+    const { result } = renderHook(() => useDebouncedCallback(callback));
+
+    act(() => {
+      result.current('arg1');
+      result.current('arg2');
+      result.current('arg3');
+    });
+
+    // Not called yet
+    expect(callback).not.toHaveBeenCalled();
+
+    // Advance time past debounce delay
+    act(() => {
+      vi.advanceTimersByTime(TIMING.DEBOUNCE_DELAY);
+    });
+
+    // Called once with last arguments
+    expect(callback).toHaveBeenCalledTimes(1);
+    expect(callback).toHaveBeenCalledWith('arg3');
+  });
+
+  it('uses default delay from TIMING.DEBOUNCE_DELAY', () => {
+    const callback = vi.fn();
+    const { result } = renderHook(() => useDebouncedCallback(callback));
+
+    act(() => {
+      result.current();
+    });
+
+    // Just before default delay
+    act(() => {
+      vi.advanceTimersByTime(TIMING.DEBOUNCE_DELAY - 1);
+    });
+    expect(callback).not.toHaveBeenCalled();
+
+    // At default delay
+    act(() => {
+      vi.advanceTimersByTime(1);
+    });
+    expect(callback).toHaveBeenCalledTimes(1);
+  });
+
+  it('respects custom delay', () => {
+    const callback = vi.fn();
+    const customDelay = 500;
+    const { result } = renderHook(() => useDebouncedCallback(callback, customDelay));
+
+    act(() => {
+      result.current();
+    });
+
+    act(() => {
+      vi.advanceTimersByTime(customDelay - 1);
+    });
+    expect(callback).not.toHaveBeenCalled();
+
+    act(() => {
+      vi.advanceTimersByTime(1);
+    });
+    expect(callback).toHaveBeenCalledTimes(1);
+  });
+
+  it('resets timer on each call', () => {
+    const callback = vi.fn();
+    const delay = 100;
+    const { result } = renderHook(() => useDebouncedCallback(callback, delay));
+
+    act(() => {
+      result.current();
+    });
+
+    // Advance halfway
+    act(() => {
+      vi.advanceTimersByTime(50);
+    });
+
+    // Call again - resets timer
+    act(() => {
+      result.current();
+    });
+
+    // Advance another 50ms (100ms total from first call)
+    act(() => {
+      vi.advanceTimersByTime(50);
+    });
+    expect(callback).not.toHaveBeenCalled();
+
+    // Advance remaining 50ms
+    act(() => {
+      vi.advanceTimersByTime(50);
+    });
+    expect(callback).toHaveBeenCalledTimes(1);
+  });
+
+  it('maintains stable callback reference', () => {
+    const callback = vi.fn();
+    const { result, rerender } = renderHook(() => useDebouncedCallback(callback, 100));
+
+    const firstRef = result.current;
+    rerender();
+    const secondRef = result.current;
+
+    expect(firstRef).toBe(secondRef);
+  });
+
+  it('uses latest callback version', () => {
+    let counter = 0;
+    const { result, rerender } = renderHook(({ cb }) => useDebouncedCallback(cb, 100), {
+      initialProps: { cb: () => counter++ },
+    });
+
+    act(() => {
+      result.current();
+    });
+
+    // Update callback before debounce fires
+    const newCallback = vi.fn(() => (counter = 100));
+    rerender({ cb: newCallback });
+
+    act(() => {
+      vi.advanceTimersByTime(100);
+    });
+
+    // Should have used the new callback
+    expect(counter).toBe(100);
+    expect(newCallback).toHaveBeenCalled();
+  });
+
+  it('cleans up timeout on unmount', () => {
+    const callback = vi.fn();
+    const { result, unmount } = renderHook(() => useDebouncedCallback(callback, 100));
+
+    act(() => {
+      result.current();
+    });
+
+    unmount();
+
+    act(() => {
+      vi.advanceTimersByTime(100);
+    });
+
+    // Callback should not be called after unmount
+    expect(callback).not.toHaveBeenCalled();
+  });
+});

package/templates/src/hooks/useDebouncedCallback.ts

@@ -0,0 +1,47 @@
+import { useCallback, useEffect, useRef } from 'react';
+
+import { TIMING } from '@/lib/constants';
+
+/**
+ * Returns a debounced version of a callback that only fires after a delay
+ * since the last call.
+ *
+ * @param callback - Function to debounce
+ * @param delay - Delay in ms (defaults to TIMING.DEBOUNCE_DELAY)
+ */
+export function useDebouncedCallback<T extends (...args: never[]) => void>(
+  callback: T,
+  delay: number = TIMING.DEBOUNCE_DELAY,
+): T {
+  const callbackRef = useRef(callback);
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+
+  // Keep callback ref up to date without restarting debounce
+  useEffect(() => {
+    callbackRef.current = callback;
+  }, [callback]);
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current);
+      }
+    };
+  }, []);
+
+  // Stable reference via useCallback (delay is the only dependency)
+  const debouncedCallback = useCallback(
+    (...args: Parameters<T>) => {
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current);
+      }
+      timeoutRef.current = setTimeout(() => {
+        callbackRef.current(...args);
+      }, delay);
+    },
+    [delay],
+  ) as T;
+
+  return debouncedCallback;
+}

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