@react-spa-scaffold/mcp 2.1.0 → 2.2.0

package/templates/src/components/shared/ErrorBoundary/ErrorBoundary.tsx

@@ -1,7 +1,10 @@
-import { Component, type ErrorInfo, type ReactNode } from 'react';
 import { Trans } from '@lingui/react/macro';
+import { AlertTriangle, RefreshCw } from 'lucide-react';
+import { Component, type ErrorInfo, type ReactNode } from 'react';
 
-import { SENTRY_CONFIG } from '@/lib/config';
+import { Button } from '@/components/ui/button';
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
+import { captureException } from '@/lib/sentry';
 
 interface Props {
   children: ReactNode;
@@ -15,6 +18,48 @@ interface State {
   error: Error | null;
 }
 
+interface ErrorFallbackUIProps {
+  error: Error | null;
+  onRetry: () => void;
+  onReload: () => void;
+}
+
+function ErrorFallbackUI({ error, onRetry, onReload }: ErrorFallbackUIProps) {
+  return (
+    <div className="flex min-h-screen items-center justify-center p-4">
+      <Card className="max-w-md">
+        <CardHeader>
+          <div className="flex items-center gap-2">
+            <AlertTriangle className="text-destructive size-5" />
+            <CardTitle>
+              <Trans>Something went wrong</Trans>
+            </CardTitle>
+          </div>
+          <CardDescription>
+            <Trans>An unexpected error occurred. You can try again or reload the page.</Trans>
+          </CardDescription>
+        </CardHeader>
+        <CardContent className="space-y-4">
+          {error && (
+            <div className="bg-muted rounded-md p-3">
+              <p className="text-muted-foreground font-mono text-xs break-all">{error.message}</p>
+            </div>
+          )}
+          <div className="flex gap-2">
+            <Button onClick={onRetry} variant="default">
+              <Trans>Try Again</Trans>
+            </Button>
+            <Button onClick={onReload} variant="outline">
+              <RefreshCw className="mr-2 size-4" />
+              <Trans>Reload Page</Trans>
+            </Button>
+          </div>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
+
 export class ErrorBoundary extends Component<Props, State> {
   constructor(props: Props) {
     super(props);
@@ -28,22 +73,11 @@ export class ErrorBoundary extends Component<Props, State> {
   componentDidCatch(error: Error, errorInfo: ErrorInfo) {
     console.error('ErrorBoundary caught an error:', error, errorInfo);
 
+    // Report error to Sentry with component stack
+    captureException(error, { componentStack: errorInfo.componentStack ?? undefined });
+
     // Call custom error handler if provided
     this.props.onError?.(error, errorInfo);
-
-    // Report to Sentry in production (if enabled and configured)
-    if (import.meta.env.PROD && SENTRY_CONFIG.enabled && SENTRY_CONFIG.dsn) {
-      // eslint-disable-next-line lingui/no-unlocalized-strings
-      import('@sentry/react')
-        .then((Sentry) => {
-          Sentry.captureException(error, {
-            extra: { componentStack: errorInfo.componentStack },
-          });
-        })
-        .catch(() => {
-          // Sentry failed to load, error already logged above
-        });
-    }
   }
 
   /**
@@ -54,49 +88,17 @@ export class ErrorBoundary extends Component<Props, State> {
     this.setState({ hasError: false, error: null });
   };
 
+  handleReload = () => {
+    window.location.reload();
+  };
+
   render() {
     if (this.state.hasError) {
       if (this.props.fallback) {
         return this.props.fallback;
       }
 
-      return (
-        <div className="flex min-h-screen items-center justify-center p-4">
-          <div className="text-center">
-            <h1 className="text-destructive text-2xl font-bold">
-              <Trans comment="Error boundary - main error heading">Something went wrong</Trans>
-            </h1>
-            <p className="text-muted-foreground mt-2">
-              <Trans comment="Error boundary - error explanation">
-                We're sorry, but something unexpected happened.
-              </Trans>
-            </p>
-            {import.meta.env.DEV && this.state.error && (
-              <details className="bg-muted mt-4 rounded-md p-4 text-left">
-                <summary className="cursor-pointer font-medium">
-                  <Trans comment="Error boundary - debug section heading">Error details</Trans>
-                </summary>
-                <pre className="mt-2 overflow-auto text-sm">{this.state.error.message}</pre>
-                <pre className="mt-1 overflow-auto text-xs opacity-75">{this.state.error.stack}</pre>
-              </details>
-            )}
-            <div className="mt-6 flex justify-center gap-3">
-              <button
-                onClick={this.reset}
-                className="bg-secondary text-secondary-foreground rounded px-4 py-2 transition-colors hover:opacity-90"
-              >
-                <Trans comment="Error boundary - try again button">Try Again</Trans>
-              </button>
-              <button
-                onClick={() => window.location.reload()}
-                className="bg-primary text-primary-foreground rounded px-4 py-2 transition-colors hover:opacity-90"
-              >
-                <Trans comment="Error boundary - refresh button">Refresh Page</Trans>
-              </button>
-            </div>
-          </div>
-        </div>
-      );
+      return <ErrorFallbackUI error={this.state.error} onRetry={this.reset} onReload={this.handleReload} />;
     }
 
     return this.props.children;

package/templates/src/components/shared/ProtectedRoute/ProtectedRoute.test.tsx

@@ -0,0 +1,43 @@
+import { screen } from '@testing-library/react';
+import { describe, it, expect, beforeEach } from 'vitest';
+
+import { render, setMockSignedIn, setMockLoaded, resetClerkMocks } from '@/test';
+
+import { ProtectedRoute } from './ProtectedRoute';
+
+describe('ProtectedRoute', () => {
+  beforeEach(() => {
+    resetClerkMocks();
+  });
+
+  it('renders children when signed in', () => {
+    render(
+      <ProtectedRoute>
+        <div>Protected Content</div>
+      </ProtectedRoute>,
+    );
+    expect(screen.getByText('Protected Content')).toBeInTheDocument();
+  });
+
+  it('shows loading when auth is not loaded', () => {
+    setMockLoaded(false);
+    const { container } = render(
+      <ProtectedRoute>
+        <div>Protected Content</div>
+      </ProtectedRoute>,
+    );
+    expect(screen.queryByText('Protected Content')).not.toBeInTheDocument();
+    expect(container.querySelector('.animate-spin')).toBeInTheDocument();
+  });
+
+  it('redirects when not signed in', () => {
+    setMockSignedIn(false);
+    render(
+      <ProtectedRoute>
+        <div>Protected Content</div>
+      </ProtectedRoute>,
+    );
+    expect(screen.queryByText('Protected Content')).not.toBeInTheDocument();
+    expect(screen.getByTestId('redirect-to-sign-in')).toBeInTheDocument();
+  });
+});

package/templates/src/components/shared/ProtectedRoute/ProtectedRoute.tsx

@@ -0,0 +1,35 @@
+import { RedirectToSignIn, useAuth } from '@clerk/react-router';
+import type { ReactNode } from 'react';
+
+import { PageLoading } from '@/components/ui/loading';
+
+interface ProtectedRouteProps {
+  children: ReactNode;
+}
+
+/**
+ * Wraps routes that require authentication.
+ * Shows loading state while auth loads, redirects to sign-in if not authenticated.
+ *
+ * @example
+ * ```tsx
+ * <Route path="/dashboard" element={
+ *   <ProtectedRoute>
+ *     <DashboardPage />
+ *   </ProtectedRoute>
+ * } />
+ * ```
+ */
+export function ProtectedRoute({ children }: ProtectedRouteProps) {
+  const { isLoaded, isSignedIn } = useAuth();
+
+  if (!isLoaded) {
+    return <PageLoading />;
+  }
+
+  if (!isSignedIn) {
+    return <RedirectToSignIn />;
+  }
+
+  return <>{children}</>;
+}

package/templates/src/components/shared/ProtectedRoute/index.ts

@@ -0,0 +1 @@
+export { ProtectedRoute } from './ProtectedRoute';

package/templates/src/components/shared/index.ts

@@ -1,5 +1,7 @@
-export { ThemeToggle } from './ThemeToggle';
+export { AccountButton } from './AccountButton';
 export { ErrorBoundary } from './ErrorBoundary';
-export { SEO } from './SEO';
 export { LanguageSwitcher } from './LanguageSwitcher';
+export { ProtectedRoute } from './ProtectedRoute';
 export { RegisterForm } from './RegisterForm';
+export { SEO } from './SEO';
+export { ThemeToggle } from './ThemeToggle';

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