@react-spa-scaffold/mcp 2.1.1 → 2.2.0

package/templates/src/contexts/clerkContext.tsx

@@ -0,0 +1,45 @@
+import { ClerkProvider } from '@clerk/react-router';
+import { shadcn } from '@clerk/themes';
+import type { Appearance } from '@clerk/types';
+import type { ReactNode } from 'react';
+
+interface ClerkThemeProviderProps {
+  children: ReactNode;
+  publishableKey: string;
+}
+
+/**
+ * Clerk appearance configuration.
+ * Uses shadcn theme which auto-adapts to light/dark mode.
+ * Requires @clerk/themes/shadcn.css to be imported in index.css.
+ */
+const appearance: Appearance = {
+  baseTheme: shadcn,
+  variables: {
+    // Typography
+    fontFamily: '"Inter Variable", sans-serif',
+    // Match app's border radius (--radius: 0.45rem in index.css)
+    borderRadius: '0.45rem',
+  },
+  elements: {
+    // Make modal fullscreen on mobile devices
+    modalBackdrop: 'backdrop-blur-sm',
+    modalContent: 'sm:max-w-md max-sm:min-h-svh max-sm:min-w-full max-sm:rounded-none',
+    card: 'max-sm:rounded-none max-sm:shadow-none',
+    // Ensure consistent border radius on form elements
+    formFieldInput: 'rounded-md',
+    formButtonPrimary: 'rounded-md',
+    socialButtonsBlockButton: 'rounded-md',
+  },
+};
+
+/**
+ * ClerkProvider wrapper with consistent theming.
+ */
+export function ClerkThemeProvider({ children, publishableKey }: ClerkThemeProviderProps) {
+  return (
+    <ClerkProvider publishableKey={publishableKey} afterSignOutUrl="/" appearance={appearance}>
+      {children}
+    </ClerkProvider>
+  );
+}

package/templates/src/hooks/index.ts

@@ -1,7 +1,28 @@
+// Media query and responsive hooks
 export { useMediaQuery, BREAKPOINTS } from './useMediaQuery';
-export { useThemeEffect } from './useThemeEffect';
+export { useMobileContext } from '@/contexts/mobileContext';
 export { useTouchSizes } from './useTouchSizes';
+export { useIOSViewportReset } from './useIOSViewportReset';
+
+// Theme and UI hooks
+export { useThemeEffect } from './useThemeEffect';
+export { useDocumentTitle } from './useDocumentTitle';
+
+// State and storage hooks
+export { useLocalStorage } from './useLocalStorage';
+export { useSyncedState } from './useSyncedState';
+export { useSyncedFormData } from './useSyncedFormData';
+
+// Utility hooks
+export { useCopyFeedback } from './useCopyFeedback';
+export { useDebouncedCallback } from './useDebouncedCallback';
+export { useKeyboardShortcut } from './useKeyboardShortcuts';
+
+// i18n hooks
 export { useLanguage } from './useLanguage';
+
+// API hooks
 export { useExampleQuery } from './useExampleQuery';
+
+// Form hooks
 export { useRegisterForm } from './useRegisterForm';
-export { useMobileContext } from '@/contexts/mobileContext';

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