@react-spa-scaffold/mcp 2.1.1 → 2.3.0

package/templates/src/mocks/handlers/index.ts

@@ -1,7 +1,8 @@
+import { supabaseHandlers } from './supabase';
 import { todosHandlers } from './todos';
 
 /**
  * All MSW request handlers.
  * Add new feature handlers here as the application grows.
  */
-export const handlers = [...todosHandlers];
+export const handlers = [...todosHandlers, ...supabaseHandlers];

package/templates/src/mocks/handlers/supabase.ts

@@ -0,0 +1,64 @@
+/**
+ * MSW handlers for Supabase PostgREST API.
+ *
+ * Minimal handlers for testing. Extend as needed.
+ * @see https://postgrest.org/en/stable/references/api.html
+ */
+
+import { http, HttpResponse } from 'msw';
+
+import { MOCK_SUPABASE_URL, MOCK_USER } from '../constants';
+import { createProfile, mockProfiles } from '../fixtures/profiles';
+
+export const supabaseHandlers = [
+  // GET /rest/v1/profiles
+  http.get(`${MOCK_SUPABASE_URL}/rest/v1/profiles`, ({ request }) => {
+    const url = new URL(request.url);
+    const idFilter = url.searchParams.get('id');
+    const isSingle = request.headers.get('Accept')?.includes('vnd.pgrst.object');
+
+    let profiles = [...mockProfiles];
+
+    // Filter by ID if specified (eq.user_123 format)
+    if (idFilter?.startsWith('eq.')) {
+      const id = idFilter.replace('eq.', '');
+      profiles = profiles.filter((p) => p.id === id);
+    }
+
+    // Simulate RLS: only return current user's data
+    profiles = profiles.filter((p) => p.id === MOCK_USER.id);
+
+    if (isSingle) {
+      return profiles.length > 0
+        ? HttpResponse.json(profiles[0])
+        : HttpResponse.json({ message: 'No rows found', code: 'PGRST116' }, { status: 406 });
+    }
+
+    return HttpResponse.json(profiles);
+  }),
+
+  // POST /rest/v1/profiles
+  http.post(`${MOCK_SUPABASE_URL}/rest/v1/profiles`, async ({ request }) => {
+    const body = await request.json();
+    const profile = createProfile(body as Record<string, unknown>);
+
+    return request.headers.get('Prefer')?.includes('return=representation')
+      ? HttpResponse.json(profile, { status: 201 })
+      : new HttpResponse(null, { status: 201 });
+  }),
+
+  // PATCH /rest/v1/profiles
+  http.patch(`${MOCK_SUPABASE_URL}/rest/v1/profiles`, async ({ request }) => {
+    const body = await request.json();
+    const profile = { ...mockProfiles[0], ...(body as Record<string, unknown>), updated_at: new Date().toISOString() };
+
+    return request.headers.get('Prefer')?.includes('return=representation')
+      ? HttpResponse.json(profile)
+      : new HttpResponse(null, { status: 204 });
+  }),
+
+  // DELETE /rest/v1/profiles
+  http.delete(`${MOCK_SUPABASE_URL}/rest/v1/profiles`, () => {
+    return new HttpResponse(null, { status: 204 });
+  }),
+];

package/templates/src/mocks/handlers/todos.ts

@@ -4,7 +4,7 @@
  */
 import { delay, http, HttpResponse } from 'msw';
 
-import { API_CONFIG } from '@/lib/api';
+import { API_CONFIG } from '@/lib/config';
 import type { Todo } from '@/types/api';
 
 import { mockTodos } from '../fixtures/todos';

package/templates/src/mocks/index.ts

@@ -1,3 +1,9 @@
+// Shared test constants
+export * from './constants';
+
+// MSW handlers and server
 export { handlers } from './handlers';
 export { server } from './node';
+
+// Fixtures
 export * from './fixtures';

package/templates/src/pages/Profile.test.tsx

@@ -0,0 +1,263 @@
+import { screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+import { render, resetClerkMocks, createProfile } from '@/test';
+
+import { ProfilePage } from './Profile';
+
+// Mock the hooks
+const mockMutate = vi.fn();
+const mockRefetch = vi.fn();
+
+// Default mock profile
+const defaultProfile = createProfile({
+  full_name: 'Test User',
+  email: 'test@example.com',
+  avatar_url: 'https://example.com/avatar.jpg',
+});
+
+// Hook mock state
+let mockProfileState: {
+  profile: ReturnType<typeof createProfile> | null;
+  isLoading: boolean;
+  error: Error | null;
+  exists: boolean;
+  isFetching: boolean;
+  refetch: typeof mockRefetch;
+} = {
+  profile: defaultProfile,
+  isLoading: false,
+  error: null,
+  exists: true,
+  isFetching: false,
+  refetch: mockRefetch,
+};
+
+let mockUpdateState = {
+  mutate: mockMutate,
+  isPending: false,
+  error: null as Error | null,
+};
+
+vi.mock('@/hooks', async () => {
+  const actual = await vi.importActual('@/hooks');
+  return {
+    ...actual,
+    useProfile: vi.fn(() => mockProfileState),
+    useUpdateProfile: vi.fn(() => mockUpdateState),
+  };
+});
+
+describe('ProfilePage', () => {
+  beforeEach(() => {
+    resetClerkMocks();
+    mockMutate.mockClear();
+    mockRefetch.mockClear();
+
+    // Reset mock state to defaults
+    mockProfileState = {
+      profile: defaultProfile,
+      isLoading: false,
+      error: null,
+      exists: true,
+      isFetching: false,
+      refetch: mockRefetch,
+    };
+
+    mockUpdateState = {
+      mutate: mockMutate,
+      isPending: false,
+      error: null,
+    };
+  });
+
+  it('renders profile page with title and description', () => {
+    render(<ProfilePage />);
+    // Verify both card title and description are present
+    expect(screen.getByText('Your Profile')).toBeInTheDocument();
+    expect(screen.getByText(/manage your profile information/i)).toBeInTheDocument();
+  });
+
+  it('shows loading skeleton when profile is loading', () => {
+    mockProfileState.isLoading = true;
+    mockProfileState.profile = null;
+
+    const { container } = render(<ProfilePage />);
+
+    // Should show skeleton elements
+    const skeletons = container.querySelectorAll('[class*="animate-pulse"]');
+    expect(skeletons.length).toBeGreaterThan(0);
+  });
+
+  it('displays profile data when loaded', () => {
+    render(<ProfilePage />);
+
+    // Name appears in header and name field - use getAllByText
+    expect(screen.getAllByText('Test User').length).toBeGreaterThan(0);
+    expect(screen.getByText('test@example.com')).toBeInTheDocument();
+    expect(screen.getByAltText(/profile avatar/i)).toHaveAttribute('src', 'https://example.com/avatar.jpg');
+  });
+
+  it('shows avatar fallback when no avatar_url', () => {
+    mockProfileState.profile = createProfile({
+      full_name: 'John Doe',
+      avatar_url: null,
+    });
+
+    render(<ProfilePage />);
+
+    // Should show first letter of name as fallback
+    expect(screen.getByText('J')).toBeInTheDocument();
+  });
+
+  it('shows email initial when no name or avatar', () => {
+    mockProfileState.profile = createProfile({
+      full_name: null,
+      email: 'user@example.com',
+      avatar_url: null,
+    });
+
+    render(<ProfilePage />);
+
+    // Should show first letter of email as fallback
+    expect(screen.getByText('U')).toBeInTheDocument();
+  });
+
+  it('shows error state and retry button on fetch failure', async () => {
+    const user = userEvent.setup();
+    mockProfileState.error = new Error('Network error');
+    mockProfileState.profile = null;
+
+    render(<ProfilePage />);
+
+    expect(screen.getByText(/failed to load profile/i)).toBeInTheDocument();
+    expect(screen.getByText(/network error/i)).toBeInTheDocument();
+
+    const retryButton = screen.getByRole('button', { name: /try again/i });
+    await user.click(retryButton);
+
+    expect(mockRefetch).toHaveBeenCalled();
+  });
+
+  it('allows editing name field', async () => {
+    const user = userEvent.setup();
+    render(<ProfilePage />);
+
+    // Click edit button
+    const editButton = screen.getByRole('button', { name: /edit/i });
+    await user.click(editButton);
+
+    // Should show input field
+    const input = screen.getByRole('textbox', { name: /full name/i });
+    expect(input).toBeInTheDocument();
+    expect(input).toHaveValue('Test User');
+  });
+
+  it('saves updated name via useUpdateProfile', async () => {
+    const user = userEvent.setup();
+
+    // Mock successful mutation
+    mockMutate.mockImplementation((_data, options) => {
+      options?.onSuccess?.();
+    });
+
+    render(<ProfilePage />);
+
+    // Click edit
+    await user.click(screen.getByRole('button', { name: /edit/i }));
+
+    // Change name
+    const input = screen.getByRole('textbox', { name: /full name/i });
+    await user.clear(input);
+    await user.type(input, 'New Name');
+
+    // Click save
+    await user.click(screen.getByRole('button', { name: /save/i }));
+
+    await waitFor(() => {
+      expect(mockMutate).toHaveBeenCalledWith({ full_name: 'New Name' }, expect.any(Object));
+    });
+  });
+
+  it('submits form on Enter key', async () => {
+    const user = userEvent.setup();
+
+    // Mock successful mutation
+    mockMutate.mockImplementation((_data, options) => {
+      options?.onSuccess?.();
+    });
+
+    render(<ProfilePage />);
+
+    // Enter edit mode
+    await user.click(screen.getByRole('button', { name: /edit/i }));
+
+    // Change name and press Enter
+    const input = screen.getByRole('textbox', { name: /full name/i });
+    await user.clear(input);
+    await user.type(input, 'Entered Name{Enter}');
+
+    await waitFor(() => {
+      expect(mockMutate).toHaveBeenCalledWith({ full_name: 'Entered Name' }, expect.any(Object));
+    });
+  });
+
+  it('shows saving state on button while updating', async () => {
+    const user = userEvent.setup();
+    mockUpdateState.isPending = true;
+
+    render(<ProfilePage />);
+
+    // Enter edit mode
+    await user.click(screen.getByRole('button', { name: /edit/i }));
+
+    // Should show saving state
+    expect(screen.getByRole('button', { name: /saving/i })).toBeDisabled();
+  });
+
+  it('cancel button reverts changes', async () => {
+    const user = userEvent.setup();
+    render(<ProfilePage />);
+
+    // Click edit
+    await user.click(screen.getByRole('button', { name: /edit/i }));
+
+    // Change name
+    const input = screen.getByRole('textbox', { name: /full name/i });
+    await user.clear(input);
+    await user.type(input, 'Changed Name');
+
+    // Click cancel
+    await user.click(screen.getByRole('button', { name: /cancel/i }));
+
+    // Should exit edit mode and show original name (appears multiple times)
+    expect(screen.queryByRole('textbox')).not.toBeInTheDocument();
+    expect(screen.getAllByText('Test User').length).toBeGreaterThan(0);
+  });
+
+  it('shows error message when update fails', async () => {
+    const user = userEvent.setup();
+    mockUpdateState.error = new Error('Update failed');
+
+    render(<ProfilePage />);
+
+    // Enter edit mode
+    await user.click(screen.getByRole('button', { name: /edit/i }));
+
+    // Should show error message
+    expect(screen.getByText(/failed to update/i)).toBeInTheDocument();
+    expect(screen.getByText(/update failed/i)).toBeInTheDocument();
+  });
+
+  it('shows "Not set" when name is empty', () => {
+    mockProfileState.profile = createProfile({
+      full_name: null,
+      email: 'test@example.com',
+    });
+
+    render(<ProfilePage />);
+
+    expect(screen.getByText(/not set/i)).toBeInTheDocument();
+  });
+});

package/templates/src/pages/Profile.tsx

@@ -0,0 +1,171 @@
+import { Trans, useLingui } from '@lingui/react/macro';
+import { useState } from 'react';
+
+import { SEO } from '@/components/shared';
+import { Button } from '@/components/ui/button';
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+import { Skeleton } from '@/components/ui/skeleton';
+import { useProfile, useSyncedState, useUpdateProfile } from '@/hooks';
+
+/**
+ * Profile page demonstrating Supabase database integration.
+ * Shows current user's profile with ability to edit the name.
+ */
+export function ProfilePage() {
+  const { t } = useLingui();
+  const { profile, isLoading, error, refetch } = useProfile();
+  const updateProfile = useUpdateProfile();
+
+  const [isEditing, setIsEditing] = useState(false);
+  // Sync name with profile, blocking sync while editing
+  const [name, setName] = useSyncedState(profile?.full_name ?? '', isEditing);
+
+  // Extract error messages for i18n (avoids object property access in Trans)
+  const fetchErrorMessage = error?.message;
+  const updateErrorMessage = updateProfile.error?.message;
+
+  const handleEdit = () => {
+    setIsEditing(true);
+  };
+
+  const handleCancel = () => {
+    setName(profile?.full_name ?? '');
+    setIsEditing(false);
+  };
+
+  const handleSave = () => {
+    updateProfile.mutate(
+      { full_name: name },
+      {
+        onSuccess: () => {
+          setIsEditing(false);
+        },
+      },
+    );
+  };
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    handleSave();
+  };
+
+  return (
+    <div className="container mx-auto max-w-lg px-4 py-8">
+      <SEO
+        title={t({ message: 'Profile', comment: 'Profile page title for SEO' })}
+        description={t({
+          message: 'Manage your profile information',
+          comment: 'Profile page meta description for SEO',
+        })}
+      />
+
+      <Card>
+        <CardHeader>
+          <CardTitle>
+            <Trans comment="Profile page card title">Your Profile</Trans>
+          </CardTitle>
+          <CardDescription>
+            <Trans comment="Profile page card description">Manage your profile information stored in Supabase</Trans>
+          </CardDescription>
+        </CardHeader>
+        <CardContent>
+          {isLoading && (
+            <div className="space-y-4">
+              <div className="flex items-center gap-4">
+                <Skeleton className="size-16 rounded-full" />
+                <div className="space-y-2">
+                  <Skeleton className="h-4 w-32" />
+                  <Skeleton className="h-4 w-48" />
+                </div>
+              </div>
+              <Skeleton className="h-10 w-full" />
+            </div>
+          )}
+
+          {error && (
+            <div className="space-y-4">
+              <p className="text-destructive text-sm" role="alert">
+                <Trans comment="Error message when profile fails to load">
+                  Failed to load profile: {fetchErrorMessage}
+                </Trans>
+              </p>
+              <Button variant="outline" onClick={() => refetch()}>
+                <Trans comment="Retry button label">Try Again</Trans>
+              </Button>
+            </div>
+          )}
+
+          {profile && (
+            <div className="space-y-6">
+              {/* Avatar and Email */}
+              <div className="flex items-center gap-4">
+                {profile.avatar_url ? (
+                  <img
+                    src={profile.avatar_url}
+                    alt={t({ message: 'Profile avatar', comment: 'Alt text for profile avatar image' })}
+                    className="size-16 rounded-full object-cover"
+                  />
+                ) : (
+                  <div className="bg-muted flex size-16 items-center justify-center rounded-full">
+                    <span className="text-muted-foreground text-xl">
+                      {profile.full_name?.[0]?.toUpperCase() ?? profile.email[0].toUpperCase()}
+                    </span>
+                  </div>
+                )}
+                <div>
+                  <p className="font-medium">{profile.full_name ?? profile.email}</p>
+                  <p className="text-muted-foreground text-sm">{profile.email}</p>
+                </div>
+              </div>
+
+              {/* Name Editor */}
+              <div className="space-y-2">
+                <Label htmlFor="full-name">
+                  <Trans comment="Full name field label">Full Name</Trans>
+                </Label>
+                {isEditing ? (
+                  <form onSubmit={handleSubmit} className="space-y-2">
+                    <Input
+                      id="full-name"
+                      value={name}
+                      onChange={(e) => setName(e.target.value)}
+                      placeholder={t({ message: 'Enter your name', comment: 'Name input placeholder' })}
+                    />
+                    <div className="flex gap-2">
+                      <Button type="submit" disabled={updateProfile.isPending}>
+                        {updateProfile.isPending ? (
+                          <Trans comment="Save button loading state">Saving...</Trans>
+                        ) : (
+                          <Trans comment="Save button label">Save</Trans>
+                        )}
+                      </Button>
+                      <Button type="button" variant="outline" onClick={handleCancel} disabled={updateProfile.isPending}>
+                        <Trans comment="Cancel button label">Cancel</Trans>
+                      </Button>
+                    </div>
+                    {updateProfile.error && (
+                      <p className="text-destructive text-sm" role="alert">
+                        <Trans comment="Error message when update fails">Failed to update: {updateErrorMessage}</Trans>
+                      </p>
+                    )}
+                  </form>
+                ) : (
+                  <div className="flex items-center gap-2">
+                    <p className="text-muted-foreground">
+                      {profile.full_name || <Trans comment="Placeholder when no name is set">Not set</Trans>}
+                    </p>
+                    <Button variant="ghost" size="sm" onClick={handleEdit}>
+                      <Trans comment="Edit button label">Edit</Trans>
+                    </Button>
+                  </div>
+                )}
+              </div>
+            </div>
+          )}
+        </CardContent>
+      </Card>
+    </div>
+  );
+}

package/templates/src/pages/index.ts

@@ -1,2 +1,3 @@
 export { HomePage } from './Home';
 export { NotFoundPage } from './NotFound';
+export { ProfilePage } from './Profile';

package/templates/src/stores/preferencesStore.ts

@@ -1,6 +1,8 @@
 import { create } from 'zustand';
 import { devtools, persist } from 'zustand/middleware';
 
+import { createSelectors } from '@/lib/createSelectors';
+import { env } from '@/lib/env';
 import { STORAGE_KEYS } from '@/lib/storageKeys';
 
 export type Theme = 'light' | 'dark' | 'system';
@@ -31,18 +33,25 @@ function getSystemTheme(): 'light' | 'dark' {
   return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
 }
 
-export const usePreferencesStore = create<PreferencesState>()(
+/** Current schema version for preferences store persistence */
+const PREFERENCES_STORE_VERSION = 1;
+
+const usePreferencesStoreBase = create<PreferencesState>()(
   devtools(
     persist(
       (set, get) => ({
         ...initialState,
-        setTheme: (theme) => set({ theme }),
+        setTheme: (theme) => set({ theme }, undefined, 'preferences/setTheme'),
         toggleTheme: () =>
-          set((state) => {
-            const resolved = state.theme === 'system' ? getSystemTheme() : state.theme;
-            return { theme: resolved === 'light' ? 'dark' : 'light' };
-          }),
-        reset: () => set(initialState),
+          set(
+            (state) => {
+              const resolved = state.theme === 'system' ? getSystemTheme() : state.theme;
+              return { theme: resolved === 'light' ? 'dark' : 'light' };
+            },
+            undefined,
+            'preferences/toggleTheme',
+          ),
+        reset: () => set(initialState, undefined, 'preferences/reset'),
         getResolvedTheme: () => {
           const { theme } = get();
           return theme === 'system' ? getSystemTheme() : theme;
@@ -50,13 +59,30 @@ export const usePreferencesStore = create<PreferencesState>()(
       }),
       {
         name: STORAGE_KEYS.preferences,
-        partialize: (state) => ({ theme: state.theme }),
+        version: PREFERENCES_STORE_VERSION,
+        partialize: (state): Preferences => ({ theme: state.theme }),
+        migrate: (persisted, version) => {
+          const state = persisted as Preferences;
+          if (version === 0) {
+            // v0 → v1: No changes needed, establishes baseline for future migrations
+            return state;
+          }
+          return state;
+        },
+        onRehydrateStorage: () => (_state, error) => {
+          if (error) {
+            console.error('Failed to hydrate preferences store:', error);
+          }
+        },
       },
     ),
-    { name: 'preferences' },
+    { name: 'preferences', enabled: env.DEV },
   ),
 );
 
+/** Preferences store with auto-generated selectors */
+export const usePreferencesStore = createSelectors(usePreferencesStoreBase);
+
 /**
  * Initialize multi-tab sync for preferences.
  * Call this once at app startup.