@react-spa-scaffold/mcp 0.3.0

package/templates/src/components/ui/visually-hidden.tsx

@@ -0,0 +1,51 @@
+import type { ReactNode } from 'react';
+
+export interface VisuallyHiddenProps {
+  children: ReactNode;
+  as?: 'span' | 'div';
+}
+
+/**
+ * Visually hidden content for screen readers.
+ * Content is hidden visually but remains accessible to assistive technologies.
+ */
+export function VisuallyHidden({ children, as: Component = 'span' }: VisuallyHiddenProps) {
+  return (
+    <Component
+      style={{
+        position: 'absolute',
+        width: '1px',
+        height: '1px',
+        padding: 0,
+        margin: '-1px',
+        overflow: 'hidden',
+        clip: 'rect(0, 0, 0, 0)',
+        whiteSpace: 'nowrap',
+        border: 0,
+      }}
+    >
+      {children}
+    </Component>
+  );
+}
+
+/**
+ * Skip link for keyboard navigation.
+ * Becomes visible on focus.
+ */
+export function SkipLink({
+  href = '#main',
+  children = 'Skip to main content',
+}: {
+  href?: string;
+  children?: ReactNode;
+}) {
+  return (
+    <a
+      href={href}
+      className="bg-background text-foreground ring-ring fixed top-4 left-4 z-50 -translate-y-16 rounded-md px-4 py-2 font-medium transition-transform focus:translate-y-0 focus:ring-2"
+    >
+      {children}
+    </a>
+  );
+}

package/templates/src/contexts/mobileContext.tsx

@@ -0,0 +1,66 @@
+import { createContext, type ReactNode, useContext, useEffect, useMemo, useState } from 'react';
+
+import { BREAKPOINTS } from '@/hooks/useMediaQuery';
+
+interface MobileContextValue {
+  isMobile: boolean;
+  isTablet: boolean;
+  isDesktop: boolean;
+  /** Current viewport width in pixels */
+  width: number;
+}
+
+const MobileContext = createContext<MobileContextValue | null>(null);
+
+/**
+ * Optimized MobileProvider that uses a single resize listener
+ * instead of multiple matchMedia listeners.
+ */
+export function MobileProvider({ children }: { children: ReactNode }) {
+  const [width, setWidth] = useState(() => {
+    if (typeof window === 'undefined') return BREAKPOINTS.lg;
+    return window.innerWidth;
+  });
+
+  useEffect(() => {
+    let rafId: number;
+    let lastWidth = window.innerWidth;
+
+    const handleResize = () => {
+      // Debounce with requestAnimationFrame for performance
+      cancelAnimationFrame(rafId);
+      rafId = requestAnimationFrame(() => {
+        const newWidth = window.innerWidth;
+        // Only update if width actually changed to prevent unnecessary re-renders
+        if (newWidth !== lastWidth) {
+          lastWidth = newWidth;
+          setWidth(newWidth);
+        }
+      });
+    };
+
+    window.addEventListener('resize', handleResize, { passive: true });
+    return () => {
+      window.removeEventListener('resize', handleResize);
+      cancelAnimationFrame(rafId);
+    };
+  }, []);
+
+  const value = useMemo(() => {
+    const isMobile = width < BREAKPOINTS.md;
+    const isTablet = width >= BREAKPOINTS.md && width < BREAKPOINTS.lg;
+    const isDesktop = width >= BREAKPOINTS.lg;
+
+    return { isMobile, isTablet, isDesktop, width };
+  }, [width]);
+
+  return <MobileContext.Provider value={value}>{children}</MobileContext.Provider>;
+}
+
+export function useMobileContext(): MobileContextValue {
+  const context = useContext(MobileContext);
+  if (!context) {
+    throw new Error('useMobileContext must be used within MobileProvider');
+  }
+  return context;
+}

package/templates/src/contexts/queryContext.tsx

@@ -0,0 +1,28 @@
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { type ReactNode, useState } from 'react';
+
+/**
+ * Create QueryClient with optimized defaults.
+ * Using a function ensures each provider instance gets its own client,
+ * which is important for SSR and testing.
+ */
+function createQueryClient() {
+  return new QueryClient({
+    defaultOptions: {
+      queries: {
+        staleTime: 1000 * 60 * 5, // 5 minutes
+        gcTime: 1000 * 60 * 30, // 30 minutes (formerly cacheTime)
+        retry: 1,
+        refetchOnWindowFocus: false,
+      },
+    },
+  });
+}
+
+export function QueryProvider({ children }: { children: ReactNode }) {
+  // Use useState to ensure queryClient is created once per component instance
+  // This is the recommended pattern from TanStack Query docs
+  const [queryClient] = useState(createQueryClient);
+
+  return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>;
+}

package/templates/src/hooks/index.ts

@@ -0,0 +1,7 @@
+export { useMediaQuery, BREAKPOINTS } from './useMediaQuery';
+export { useThemeEffect } from './useThemeEffect';
+export { useTouchSizes } from './useTouchSizes';
+export { useLanguage } from './useLanguage';
+export { useExampleQuery } from './useExampleQuery';
+export { useContactForm } from './useContactForm';
+export { useMobileContext } from '@/contexts/mobileContext';

package/templates/src/hooks/useContactForm.ts

@@ -0,0 +1,33 @@
+import { zodResolver } from '@hookform/resolvers/zod';
+import { useForm } from 'react-hook-form';
+
+import { type ContactFormData, contactFormSchema } from '@/lib/validations';
+
+/**
+ * Example React Hook Form + Zod hook for a contact form.
+ * Demonstrates the pattern for form validation.
+ */
+export function useContactForm() {
+  const form = useForm<ContactFormData>({
+    resolver: zodResolver(contactFormSchema),
+    defaultValues: {
+      name: '',
+      email: '',
+      message: '',
+    },
+  });
+
+  const onSubmit = async (data: ContactFormData) => {
+    // Replace with your actual form submission logic
+    // eslint-disable-next-line no-console
+    console.log('Form submitted:', data);
+    // await api.submitContactForm(data);
+  };
+
+  return {
+    form,
+    onSubmit: form.handleSubmit(onSubmit),
+    isSubmitting: form.formState.isSubmitting,
+    errors: form.formState.errors,
+  };
+}

package/templates/src/hooks/useExampleQuery.ts

@@ -0,0 +1,20 @@
+import { useQuery } from '@tanstack/react-query';
+
+import { api } from '@/lib/api';
+import type { Todo } from '@/types/api';
+
+async function fetchTodos(): Promise<Todo[]> {
+  return api.get<Todo[]>('/todos?_limit=5');
+}
+
+/**
+ * Example TanStack Query hook demonstrating the pattern.
+ * Uses the centralized API client and shared types.
+ */
+export function useExampleQuery() {
+  return useQuery({
+    queryKey: ['example', 'todos'],
+    queryFn: fetchTodos,
+    // Uses default staleTime from QueryProvider (5 minutes)
+  });
+}

package/templates/src/hooks/useLanguage.ts

@@ -0,0 +1,23 @@
+import { useLingui } from '@lingui/react/macro';
+import { useCallback } from 'react';
+
+import { dynamicActivate, SUPPORTED_LOCALES, type SupportedLocale } from '@/i18n';
+import { setStorageItem } from '@/lib/storage';
+import { STORAGE_KEYS } from '@/lib/storageKeys';
+
+export function useLanguage() {
+  const { i18n } = useLingui();
+
+  const currentLocale = i18n.locale as SupportedLocale;
+
+  const changeLanguage = useCallback(async (locale: SupportedLocale) => {
+    await dynamicActivate(locale);
+    setStorageItem(STORAGE_KEYS.locale, locale);
+  }, []);
+
+  return {
+    currentLocale,
+    changeLanguage,
+    supportedLocales: SUPPORTED_LOCALES,
+  };
+}

package/templates/src/hooks/useMediaQuery.ts

@@ -0,0 +1,53 @@
+import { useEffect, useRef, useState } from 'react';
+
+export const BREAKPOINTS = {
+  sm: 640,
+  md: 768,
+  lg: 1024,
+  xl: 1280,
+} as const;
+
+/**
+ * Hook to track a media query match status.
+ * Optimized to reuse matchMedia objects when the query doesn't change.
+ */
+export function useMediaQuery(query: string): boolean {
+  const [matches, setMatches] = useState(() => {
+    if (typeof window !== 'undefined') {
+      return window.matchMedia(query).matches;
+    }
+    return false;
+  });
+
+  // Use ref to store the MediaQueryList to avoid recreating on every render
+  const mediaQueryRef = useRef<MediaQueryList | null>(null);
+
+  useEffect(() => {
+    // Create or update the MediaQueryList only when query changes
+    mediaQueryRef.current = window.matchMedia(query);
+
+    const handler = (e: MediaQueryListEvent) => setMatches(e.matches);
+
+    // Sync initial state
+    setMatches(mediaQueryRef.current.matches);
+
+    mediaQueryRef.current.addEventListener('change', handler);
+
+    return () => {
+      mediaQueryRef.current?.removeEventListener('change', handler);
+    };
+  }, [query]);
+
+  return matches;
+}
+
+/**
+ * Convenience hooks for common breakpoints
+ */
+export function useIsMobile(): boolean {
+  return !useMediaQuery(`(min-width: ${BREAKPOINTS.md}px)`);
+}
+
+export function useIsDesktop(): boolean {
+  return useMediaQuery(`(min-width: ${BREAKPOINTS.lg}px)`);
+}

package/templates/src/hooks/useThemeEffect.ts

@@ -0,0 +1,31 @@
+import { useEffect } from 'react';
+
+import { usePreferencesStore } from '@/stores';
+
+/**
+ * Hook that syncs the theme preference to the DOM.
+ * Handles 'system' theme by listening to prefers-color-scheme changes.
+ */
+export function useThemeEffect() {
+  const theme = usePreferencesStore((state) => state.theme);
+  const getResolvedTheme = usePreferencesStore((state) => state.getResolvedTheme);
+
+  useEffect(() => {
+    // Apply the resolved theme to the DOM
+    const applyTheme = () => {
+      const resolved = getResolvedTheme();
+      document.documentElement.classList.toggle('dark', resolved === 'dark');
+    };
+
+    applyTheme();
+
+    // If theme is 'system', listen for system preference changes
+    if (theme === 'system') {
+      const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
+      const handleChange = () => applyTheme();
+
+      mediaQuery.addEventListener('change', handleChange);
+      return () => mediaQuery.removeEventListener('change', handleChange);
+    }
+  }, [theme, getResolvedTheme]);
+}

package/templates/src/hooks/useTouchSizes.ts

@@ -0,0 +1,16 @@
+import { useMobileContext } from '@/contexts/mobileContext';
+
+export function useTouchSizes() {
+  const { isMobile } = useMobileContext();
+
+  return {
+    button: isMobile ? 'touch' : 'default',
+    buttonSm: isMobile ? 'touch' : 'sm',
+    iconButton: isMobile ? 'icon-touch' : 'icon-sm',
+    iconButtonLg: isMobile ? 'icon-touch' : 'icon',
+    input: isMobile ? 'touch' : 'default',
+    select: isMobile ? 'touch' : 'default',
+    toggle: isMobile ? 'touch' : 'sm',
+    textarea: isMobile ? 'touch' : 'default',
+  } as const;
+}

package/templates/src/i18n/config.ts

@@ -0,0 +1,11 @@
+export const SUPPORTED_LOCALES = ['en', 'es', 'de'] as const;
+
+export type SupportedLocale = (typeof SUPPORTED_LOCALES)[number];
+
+export const DEFAULT_LOCALE: SupportedLocale = 'en';
+
+export const LOCALE_LABELS: Record<SupportedLocale, { native: string; english: string }> = {
+  en: { native: 'English', english: 'English' },
+  es: { native: 'Español', english: 'Spanish' },
+  de: { native: 'Deutsch', english: 'German' },
+};

package/templates/src/i18n/detectLanguage.ts

@@ -0,0 +1,57 @@
+import { STORAGE_KEYS } from '@/lib/storageKeys';
+
+import { DEFAULT_LOCALE, SUPPORTED_LOCALES, type SupportedLocale } from './config';
+
+function isSupported(locale: string): locale is SupportedLocale {
+  return SUPPORTED_LOCALES.includes(locale.toLowerCase() as SupportedLocale);
+}
+
+function findBestMatch(langTag: string): SupportedLocale | null {
+  const normalized = langTag.toLowerCase();
+
+  if (isSupported(normalized)) return normalized;
+
+  const exactMatch = SUPPORTED_LOCALES.find((locale) => locale.toLowerCase() === normalized);
+  if (exactMatch) return exactMatch;
+
+  const baseLanguage = normalized.split('-')[0];
+  if (isSupported(baseLanguage)) return baseLanguage as SupportedLocale;
+
+  const regionalFallback = SUPPORTED_LOCALES.find((locale) => locale.toLowerCase().startsWith(baseLanguage));
+  if (regionalFallback) return regionalFallback;
+
+  return null;
+}
+
+export function detectLanguage(): SupportedLocale {
+  // 1. Check localStorage for user preference
+  if (typeof localStorage !== 'undefined') {
+    const stored = localStorage.getItem(STORAGE_KEYS.locale);
+    if (stored) {
+      let parsedLocale: string;
+      try {
+        parsedLocale = JSON.parse(stored) as string;
+      } catch {
+        parsedLocale = stored;
+      }
+      const match = findBestMatch(parsedLocale);
+      if (match) return match;
+    }
+  }
+
+  // 2. Check browser language preferences
+  if (typeof navigator !== 'undefined' && navigator.languages) {
+    for (const lang of navigator.languages) {
+      const match = findBestMatch(lang);
+      if (match) return match;
+    }
+  }
+
+  // 3. Check primary browser language
+  if (typeof navigator !== 'undefined' && navigator.language) {
+    const match = findBestMatch(navigator.language);
+    if (match) return match;
+  }
+
+  return DEFAULT_LOCALE;
+}

package/templates/src/i18n/index.ts

@@ -0,0 +1,20 @@
+import { i18n } from '@lingui/core';
+
+import { type SupportedLocale } from './config';
+import { detectLanguage } from './detectLanguage';
+import { dynamicActivate } from './loadCatalog';
+
+// Re-export everything from a single source
+export { i18n };
+export { detectLanguage };
+export { dynamicActivate };
+export { SUPPORTED_LOCALES, DEFAULT_LOCALE, LOCALE_LABELS, type SupportedLocale } from './config';
+
+export async function initI18n(locale?: SupportedLocale): Promise<void> {
+  const targetLocale = locale || detectLanguage();
+  await dynamicActivate(targetLocale);
+}
+
+export function getLocale(): string {
+  return i18n.locale || 'en';
+}

package/templates/src/i18n/loadCatalog.ts

@@ -0,0 +1,30 @@
+import { i18n } from '@lingui/core';
+
+import { DEFAULT_LOCALE, type SupportedLocale } from './config';
+
+export async function dynamicActivate(locale: SupportedLocale): Promise<void> {
+  if (i18n.locale === locale && i18n.messages[locale]) return;
+  if (i18n.messages[locale]) {
+    i18n.activate(locale);
+    return;
+  }
+
+  try {
+    const { messages } = await import(`../locales/${locale}.po`);
+    i18n.loadAndActivate({ locale, messages });
+  } catch (error) {
+    console.error(`Failed to load locale: ${locale}`, error);
+    if (locale !== DEFAULT_LOCALE) {
+      if (i18n.messages[DEFAULT_LOCALE]) {
+        i18n.activate(DEFAULT_LOCALE);
+      } else {
+        try {
+          const { messages } = await import(`../locales/${DEFAULT_LOCALE}.po`);
+          i18n.loadAndActivate({ locale: DEFAULT_LOCALE, messages });
+        } catch {
+          console.error('Failed to load default locale');
+        }
+      }
+    }
+  }
+}

package/templates/src/index.css

@@ -0,0 +1,98 @@
+@import 'tailwindcss';
+@import 'tw-animate-css';
+@import 'shadcn/tailwind.css';
+@import '@fontsource-variable/inter';
+
+@custom-variant dark (&:is(.dark *));
+
+:root {
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.141 0.005 285.823);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.141 0.005 285.823);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.141 0.005 285.823);
+  --primary: oklch(0.488 0.243 264.376);
+  --primary-foreground: oklch(0.97 0.014 254.604);
+  --secondary: oklch(0.967 0.001 286.375);
+  --secondary-foreground: oklch(0.21 0.006 285.885);
+  --muted: oklch(0.967 0.001 286.375);
+  --muted-foreground: oklch(0.552 0.016 285.938);
+  --accent: oklch(0.967 0.001 286.375);
+  --accent-foreground: oklch(0.21 0.006 285.885);
+  --destructive: oklch(0.577 0.245 27.325);
+  --border: oklch(0.92 0.004 286.32);
+  --input: oklch(0.92 0.004 286.32);
+  --ring: oklch(0.705 0.015 286.067);
+  --radius: 0.45rem;
+}
+
+.dark {
+  --background: oklch(0.141 0.005 285.823);
+  --foreground: oklch(0.985 0 0);
+  --card: oklch(0.21 0.006 285.885);
+  --card-foreground: oklch(0.985 0 0);
+  --popover: oklch(0.21 0.006 285.885);
+  --popover-foreground: oklch(0.985 0 0);
+  --primary: oklch(0.42 0.18 266);
+  --primary-foreground: oklch(0.97 0.014 254.604);
+  --secondary: oklch(0.274 0.006 286.033);
+  --secondary-foreground: oklch(0.985 0 0);
+  --muted: oklch(0.274 0.006 286.033);
+  --muted-foreground: oklch(0.705 0.015 286.067);
+  --accent: oklch(0.274 0.006 286.033);
+  --accent-foreground: oklch(0.985 0 0);
+  --destructive: oklch(0.704 0.191 22.216);
+  --border: oklch(1 0 0 / 10%);
+  --input: oklch(1 0 0 / 15%);
+  --ring: oklch(0.552 0.016 285.938);
+}
+
+@theme inline {
+  --font-sans: 'Inter Variable', sans-serif;
+  --color-ring: var(--ring);
+  --color-input: var(--input);
+  --color-border: var(--border);
+  --color-destructive: var(--destructive);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-accent: var(--accent);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-muted: var(--muted);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-secondary: var(--secondary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-primary: var(--primary);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-popover: var(--popover);
+  --color-card-foreground: var(--card-foreground);
+  --color-card: var(--card);
+  --color-foreground: var(--foreground);
+  --color-background: var(--background);
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+}
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+
+  html {
+    @apply h-full font-sans;
+  }
+
+  body {
+    @apply bg-background text-foreground h-full font-sans;
+  }
+
+  /* Prevent iOS Safari zoom on input focus - must be 16px+ */
+  @media screen and (max-width: 640px) {
+    input,
+    textarea,
+    select {
+      font-size: 16px !important;
+    }
+  }
+}