@react-spa-scaffold/mcp 2.1.1 → 2.3.0

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/api.test.ts

@@ -1,18 +1,21 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { api, ApiClientError } from '@/lib/api';
+import {
+  mockFetchError,
+  mockFetchNetworkError,
+  mockFetchNoContent,
+  mockFetchSuccess,
+  mockFetchUnknownError,
+} from '@/test';
 
 describe('api client', () => {
-  const mockFetch = vi.fn();
-  const originalFetch = global.fetch;
-
   beforeEach(() => {
-    global.fetch = mockFetch;
-    vi.clearAllMocks();
+    vi.spyOn(global, 'fetch');
   });
 
   afterEach(() => {
-    global.fetch = originalFetch;
+    vi.restoreAllMocks();
   });
 
   describe('HTTP methods', () => {
@@ -23,15 +26,11 @@ describe('api client', () => {
       { method: 'patch', httpMethod: 'PATCH' },
       { method: 'delete', httpMethod: 'DELETE' },
     ] as const)('$method makes $httpMethod request', async ({ method, httpMethod }) => {
-      mockFetch.mockResolvedValueOnce({
-        ok: true,
-        status: 200,
-        json: () => Promise.resolve({ id: 1 }),
-      });
+      mockFetchSuccess({ id: 1 });
 
       await api[method]('/test');
 
-      expect(mockFetch).toHaveBeenCalledWith(
+      expect(global.fetch).toHaveBeenCalledWith(
         expect.stringContaining('/test'),
         expect.objectContaining({ method: httpMethod }),
       );
@@ -39,30 +38,22 @@ describe('api client', () => {
 
     it('sends request body for POST/PUT/PATCH', async () => {
       const body = { name: 'Test' };
-      mockFetch.mockResolvedValueOnce({
-        ok: true,
-        status: 200,
-        json: () => Promise.resolve({ id: 1 }),
-      });
+      mockFetchSuccess({ id: 1 });
 
       await api.post('/test', body);
 
-      expect(mockFetch).toHaveBeenCalledWith(
+      expect(global.fetch).toHaveBeenCalledWith(
         expect.anything(),
         expect.objectContaining({ body: JSON.stringify(body) }),
       );
     });
 
     it('handles full URL without prepending base URL', async () => {
-      mockFetch.mockResolvedValueOnce({
-        ok: true,
-        status: 200,
-        json: () => Promise.resolve({}),
-      });
+      mockFetchSuccess({});
 
       await api.get('https://external.api/data');
 
-      expect(mockFetch).toHaveBeenCalledWith('https://external.api/data', expect.anything());
+      expect(global.fetch).toHaveBeenCalledWith('https://external.api/data', expect.anything());
     });
   });
 
@@ -71,12 +62,7 @@ describe('api client', () => {
       { status: 404, message: 'Resource not found', hasJson: true },
       { status: 500, message: 'Internal Server Error', hasJson: false },
     ])('handles $status error response', async ({ status, message, hasJson }) => {
-      mockFetch.mockResolvedValueOnce({
-        ok: false,
-        status,
-        statusText: message,
-        json: hasJson ? () => Promise.resolve({ message }) : () => Promise.reject(new Error('No JSON')),
-      });
+      mockFetchError(status, message, hasJson);
 
       const error = (await api.get('/error').catch((e) => e)) as ApiClientError;
 
@@ -87,7 +73,7 @@ describe('api client', () => {
 
     it('handles timeout with TIMEOUT code', async () => {
       vi.useFakeTimers();
-      mockFetch.mockImplementationOnce(
+      vi.mocked(global.fetch).mockImplementationOnce(
         () =>
           new Promise((_, reject) => {
             const error = new Error('Aborted');
@@ -106,20 +92,26 @@ describe('api client', () => {
       vi.useRealTimers();
     });
 
-    it.each([
-      { rejection: new Error('Network failure'), code: 'NETWORK_ERROR' },
-      { rejection: 'string error', code: 'UNKNOWN' },
-    ])('handles $code errors', async ({ rejection, code }) => {
-      mockFetch.mockRejectedValueOnce(rejection);
+    it('handles NETWORK_ERROR', async () => {
+      mockFetchNetworkError();
+
+      const error = (await api.get('/error').catch((e) => e)) as ApiClientError;
+
+      expect(error).toBeInstanceOf(ApiClientError);
+      expect(error.code).toBe('NETWORK_ERROR');
+    });
+
+    it('handles UNKNOWN errors', async () => {
+      mockFetchUnknownError('string error');
 
       const error = (await api.get('/error').catch((e) => e)) as ApiClientError;
 
       expect(error).toBeInstanceOf(ApiClientError);
-      expect(error.code).toBe(code);
+      expect(error.code).toBe('UNKNOWN');
     });
 
     it('returns undefined for 204 No Content', async () => {
-      mockFetch.mockResolvedValueOnce({ ok: true, status: 204 });
+      mockFetchNoContent();
 
       const result = await api.delete('/test/1');
 

package/templates/src/lib/api.ts

@@ -5,13 +5,7 @@
 
 import type { ApiError } from '@/types/api';
 
-/**
- * API configuration.
- */
-export const API_CONFIG = {
-  baseUrl: import.meta.env.VITE_API_URL || 'https://jsonplaceholder.typicode.com',
-  timeout: 30000,
-} as const;
+import { API_CONFIG } from './config';
 
 /**
  * Custom API error class

package/templates/src/lib/config.ts

@@ -1,15 +1,65 @@
 /**
  * Application configuration.
  * Centralized config for feature flags, etc.
+ *
+ * All environment variables flow through the validated `env` object from env.ts.
  */
 
+import { env } from './env';
+
+// =============================================================================
+// App Configuration
+// =============================================================================
+
 export const APP_CONFIG = {
-  name: import.meta.env.VITE_APP_NAME || 'My App',
-  url: import.meta.env.VITE_APP_URL || 'http://localhost:5173',
+  name: env.VITE_APP_NAME,
+  url: env.VITE_APP_URL,
+} as const;
+
+// =============================================================================
+// API Configuration
+// =============================================================================
+
+export const API_CONFIG = {
+  baseUrl: env.VITE_API_URL,
+  timeout: 30000,
 } as const;
 
+// =============================================================================
+// Sentry Configuration
+// =============================================================================
+
 export const SENTRY_CONFIG = {
-  enabled: import.meta.env.VITE_SENTRY_ENABLED !== 'false',
-  dsn: import.meta.env.VITE_SENTRY_DSN,
+  enabled: env.VITE_SENTRY_ENABLED,
+  dsn: env.VITE_SENTRY_DSN,
+  environment: env.MODE,
   tracesSampleRate: 0.1,
 } as const;
+
+// =============================================================================
+// Clerk Configuration
+// =============================================================================
+
+export const CLERK_CONFIG = {
+  publishableKey: env.VITE_CLERK_PUBLISHABLE_KEY,
+} as const;
+
+// =============================================================================
+// Supabase Configuration
+// =============================================================================
+
+export const SUPABASE_CONFIG = {
+  url: env.VITE_SUPABASE_DATABASE_URL,
+  anonKey: env.VITE_SUPABASE_ANON_KEY,
+  /** Whether both URL and anon key are configured */
+  isConfigured: Boolean(env.VITE_SUPABASE_DATABASE_URL && env.VITE_SUPABASE_ANON_KEY),
+} as const;
+
+// =============================================================================
+// Performance Configuration
+// =============================================================================
+
+export const PERFORMANCE_CONFIG = {
+  /** Enable performance tracking in dev or when VITE_PERF_TEST is set */
+  enabled: env.DEV || env.VITE_PERF_TEST,
+} as const;

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;