@react-spa-scaffold/mcp 0.3.0

package/templates/docs/COMPONENT_GUIDELINES.md

@@ -0,0 +1,301 @@
+# React + TypeScript Component Guidelines
+
+A focused blueprint for writing React components. For related patterns, see:
+
+- [Coding Standards](./CODING_STANDARDS.md) - TypeScript, state management, hooks
+- [Testing](./TESTING.md) - Unit testing patterns
+- [Internationalization](./INTERNATIONALIZATION.md) - i18n with Lingui
+
+---
+
+## Component Anatomy
+
+Every component follows this structure:
+
+```tsx
+// 1. Imports (grouped: external → internal → types)
+import { useState } from 'react';
+
+import { Button } from '@/components/ui/button';
+import { cn } from '@/lib/utils';
+
+// 2. Types/Interfaces
+export interface MyComponentProps {
+  title: string;
+  count?: number;
+  onAction?: () => void;
+}
+
+// 3. Component Implementation
+export function MyComponent({ title, count = 0, onAction }: MyComponentProps) {
+  // a. Hooks (all hooks must be called unconditionally)
+  const [isOpen, setIsOpen] = useState(false);
+
+  // b. Derived state / computations
+  const displayCount = count > 99 ? '99+' : count;
+
+  // c. Event handlers
+  const handleClick = () => {
+    setIsOpen(true);
+    onAction?.();
+  };
+
+  // d. Early returns (only AFTER all hooks)
+  if (!title) return null;
+
+  // e. Render
+  return (
+    <div>
+      <h2>{title}</h2>
+      <span>{displayCount}</span>
+      <Button onClick={handleClick}>Action</Button>
+    </div>
+  );
+}
+```
+
+---
+
+## Props Patterns
+
+### Extending HTML Attributes
+
+For components wrapping native elements:
+
+```tsx
+import { forwardRef } from 'react';
+
+export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: 'primary' | 'secondary';
+  isLoading?: boolean;
+}
+
+export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
+  ({ variant = 'primary', isLoading, children, className, ...props }, ref) => {
+    return (
+      <button ref={ref} className={cn(buttonVariants({ variant }), className)} {...props}>
+        {isLoading ? <Spinner /> : children}
+      </button>
+    );
+  },
+);
+
+Button.displayName = 'Button';
+```
+
+### Generic Components
+
+```tsx
+interface ListProps<T> {
+  items: T[];
+  renderItem: (item: T) => ReactNode;
+  keyExtractor: (item: T) => string;
+}
+
+export function List<T>({ items, renderItem, keyExtractor }: ListProps<T>) {
+  return (
+    <ul>
+      {items.map((item) => (
+        <li key={keyExtractor(item)}>{renderItem(item)}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+---
+
+## Component Categories
+
+| Category           | Location                     | Naming                     | Export  | Barrel |
+| ------------------ | ---------------------------- | -------------------------- | ------- | ------ |
+| UI Primitives      | `components/ui/`             | `button.tsx` (lowercase)   | Named   | No\*   |
+| Feature Components | `components/shared/Feature/` | `Feature.tsx` (PascalCase) | Named   | Yes    |
+| Layout             | `components/layout/`         | `Header.tsx` (PascalCase)  | Named   | Yes    |
+| Pages              | `pages/`                     | `Home.tsx` (PascalCase)    | Default | No     |
+
+\*UI primitives use direct imports (`@/components/ui/button`) following shadcn/ui conventions.
+
+### Feature Component Structure
+
+```
+src/components/shared/
+├── ThemeToggle/
+│   ├── ThemeToggle.tsx
+│   └── index.ts           # export { ThemeToggle } from './ThemeToggle';
+├── LanguageSwitcher/
+│   └── ...
+└── index.ts               # Re-exports all shared components
+```
+
+---
+
+## File Organization
+
+### Default: Single File
+
+Keep types, helpers, and component together in one file. This is the pattern used throughout this codebase—even `dropdown-menu.tsx` at 228 lines remains a single file.
+
+```tsx
+// button.tsx - types and component together
+export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: 'primary' | 'secondary';
+}
+
+const buttonVariants = cva(/* ... */);
+
+export function Button({ variant, className, ...props }: ButtonProps) {
+  return <button className={cn(buttonVariants({ variant }), className)} {...props} />;
+}
+```
+
+### When to Split
+
+Split only when you have a **concrete reason**, not preemptively:
+
+| Situation                        | Action                            |
+| -------------------------------- | --------------------------------- |
+| Types reused by other components | Move to `@/types/`                |
+| Helper reused elsewhere          | Move to `@/lib/`                  |
+| File exceeds ~300 lines          | Consider splitting by concern     |
+| Multiple sub-components          | Create folder with separate files |
+
+### Splitting Example
+
+For a complex component like a data table:
+
+```
+src/components/shared/DataTable/
+├── DataTable.tsx          # Main component
+├── DataTableHeader.tsx    # Sub-component
+├── DataTableRow.tsx       # Sub-component
+├── columns.tsx            # Column configuration
+└── index.ts               # export { DataTable } from './DataTable';
+```
+
+**Avoid**: Separate `.types.ts` or `.helpers.ts` files for code used only by that component. Keep related code together.
+
+---
+
+## Styling with CVA
+
+Use [Class Variance Authority](https://cva.style/docs) for variant-based styling:
+
+```tsx
+import { cva, type VariantProps } from 'class-variance-authority';
+import { cn } from '@/lib/utils';
+
+const badgeVariants = cva(
+  // Base styles
+  'inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-semibold',
+  {
+    variants: {
+      variant: {
+        default: 'bg-primary text-primary-foreground',
+        secondary: 'bg-secondary text-secondary-foreground',
+        destructive: 'bg-destructive text-destructive-foreground',
+        outline: 'border border-input bg-transparent',
+      },
+      size: {
+        sm: 'px-2 py-0.5 text-xs',
+        md: 'px-2.5 py-0.5 text-sm',
+        lg: 'px-3 py-1 text-base',
+      },
+    },
+    defaultVariants: {
+      variant: 'default',
+      size: 'md',
+    },
+  },
+);
+
+export interface BadgeProps extends React.HTMLAttributes<HTMLSpanElement>, VariantProps<typeof badgeVariants> {}
+
+export function Badge({ variant, size, className, ...props }: BadgeProps) {
+  return <span className={cn(badgeVariants({ variant, size }), className)} {...props} />;
+}
+```
+
+### `cn()` Utility
+
+```tsx
+cn('px-4 py-2', 'px-6'); // → 'py-2 px-6' (later overrides)
+cn('text-red-500', className); // → allows prop override
+cn(isActive && 'bg-primary'); // → conditional classes
+```
+
+---
+
+## Loading & Error States
+
+Components fetching data should handle all states:
+
+```tsx
+export function UserProfile({ userId }: { userId: string }) {
+  const { data: user, isLoading, error } = useUserQuery(userId);
+
+  if (isLoading) {
+    return (
+      <div className="flex items-center gap-3">
+        <Skeleton className="h-10 w-10 rounded-full" />
+        <Skeleton className="h-4 w-24" />
+      </div>
+    );
+  }
+
+  if (error || !user) {
+    return (
+      <div className="text-destructive">
+        <Trans comment="Error when user profile fails to load">Failed to load profile</Trans>
+      </div>
+    );
+  }
+
+  return (
+    <div className="flex items-center gap-3">
+      <Avatar src={user.avatar} alt={user.name} />
+      <span>{user.name}</span>
+    </div>
+  );
+}
+```
+
+---
+
+## Accessibility
+
+### Required Practices
+
+```tsx
+// Icons need labels
+<button aria-label={t({ message: 'Close', comment: 'Close dialog button' })}>
+  <XIcon />
+</button>
+
+// Use semantic roles
+<header role="banner">...</header>
+<nav role="navigation">...</nav>
+<main role="main">...</main>
+
+// Loading states
+<Spinner role="status" aria-label="Loading" />
+
+// Interactive elements need focus styles (handled by Tailwind's focus-visible)
+<button className="focus-visible:ring-2 focus-visible:ring-ring">...</button>
+```
+
+---
+
+## Checklist
+
+Before submitting a component:
+
+- [ ] Props use `interface` with `Props` suffix
+- [ ] Named export (default only for pages)
+- [ ] Imports use `@/` path alias
+- [ ] User-facing text has translator comments
+- [ ] Handles loading/error states for async data
+- [ ] Uses `cn()` for className merging
+- [ ] Accessible (roles, aria-labels, keyboard nav)
+- [ ] Barrel export in `index.ts` (except UI primitives)
+- [ ] Test file in `tests/unit/`

package/templates/docs/E2E_TESTING.md

@@ -0,0 +1,116 @@
+# E2E Testing Guidelines
+
+## Overview
+
+- **Framework**: Playwright
+- **Test location**: `e2e/tests/`
+- **Utilities**: `e2e/fixtures/`
+
+## File Structure
+
+```
+e2e/
+├── fixtures/
+│   └── index.ts           # setupPage, clearAppState
+└── tests/
+    ├── home.spec.ts       # Page structure, accessibility
+    ├── theme.spec.ts      # Theme toggle, persistence
+    ├── language.spec.ts   # Language switcher
+    └── navigation.spec.ts # Routing, 404
+```
+
+## Imports
+
+```typescript
+import { expect, test } from '@playwright/test';
+
+// For tests that need state clearing
+import { setupPage } from '../fixtures';
+```
+
+## Core Patterns
+
+### Simple Page Tests
+
+```typescript
+test.describe('Home Page', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto('/');
+  });
+
+  test('displays welcome heading', async ({ page }) => {
+    await expect(page.getByRole('heading', { name: /welcome/i })).toBeVisible();
+  });
+});
+```
+
+### Tests Requiring Clean State
+
+```typescript
+import { setupPage } from '../fixtures';
+
+test.describe('Theme Toggle', () => {
+  test.beforeEach(async ({ page }) => {
+    await setupPage(page); // Clears localStorage, reloads
+  });
+
+  test('persists preference across reload', async ({ page }) => {
+    await page.getByRole('button', { name: /dark mode/i }).click();
+    await page.reload();
+    await expect(page.locator('html')).toHaveClass(/dark/);
+  });
+});
+```
+
+### Selecting Elements
+
+```typescript
+// ✅ Good - accessible selectors
+page.getByRole('button', { name: /submit/i });
+page.getByRole('heading', { name: /welcome/i });
+page.getByText('English');
+
+// ❌ Avoid
+page.locator('.btn-primary');
+page.locator('div > span.title');
+```
+
+### Waiting for State
+
+```typescript
+// ✅ Good - wait for visible state change
+await expect(page.getByText('Success')).toBeVisible();
+await expect(page.locator('html')).toHaveClass(/dark/);
+
+// ❌ Avoid - arbitrary timeouts
+await page.waitForTimeout(500);
+```
+
+## What to Test
+
+| Type        | Examples                          |
+| ----------- | --------------------------------- |
+| Navigation  | Routes work, 404 handling         |
+| User flows  | Toggle theme, change language     |
+| Persistence | Settings survive reload           |
+| Structure   | Header present, main content area |
+
+## What NOT to Test
+
+- CSS class names (implementation detail)
+- Internal component state
+- API response content (use unit tests)
+
+## Running Tests
+
+```bash
+npm run e2e        # Run all
+npm run e2e:ui     # Interactive UI
+```
+
+## Checklist
+
+- [ ] Uses accessible selectors
+- [ ] No arbitrary timeouts
+- [ ] Tests behavior, not implementation
+- [ ] Uses `setupPage` when testing persistence

package/templates/docs/INTERNATIONALIZATION.md

@@ -0,0 +1,67 @@
+# Internationalization (i18n)
+
+This project uses [Lingui](https://lingui.dev/) for internationalization. **ESLint will warn about untranslated strings.**
+
+## Quick Reference
+
+```tsx
+// Trans component - for JSX content
+<Trans comment="Error shown when upload exceeds 10MB">File too large</Trans>;
+
+// t() function - for strings (aria-labels, placeholders, etc.)
+const { t } = useLingui();
+<Button aria-label={t({ message: 'Close', comment: 'Close dialog button' })} />;
+
+// msg() - for messages defined outside components
+const labels = {
+  save: msg({ message: 'Save', comment: 'Form submit button' }),
+};
+```
+
+## Adding Translations
+
+1. Wrap text with `<Trans>` or `t()` and add a `comment`
+2. Run `pnpm i18n:extract` to update PO files
+3. Translate in `src/locales/{locale}.po`
+4. Build compiles translations automatically
+
+## Writing Comments
+
+Comments help translators understand context. They appear in PO files as `#.` lines.
+
+```tsx
+// Good - explains where and why
+<Trans comment="Error message when file upload exceeds 10MB limit">
+  File too large
+</Trans>
+
+// Good - explains the variable
+<Trans comment="Badge showing unread count, {count} is 1-99 or 99+">
+  {count} new
+</Trans>
+
+// Bad - obvious or vague
+<Trans comment="A message">Error</Trans>
+<Trans comment="Title">Welcome</Trans>
+```
+
+**Tip:** Use `context` prop when the same word needs different translations:
+
+```tsx
+<Trans context="calendar">Date</Trans>
+<Trans context="romantic">Date</Trans>
+```
+
+## ESLint Rules
+
+The `eslint-plugin-lingui` enforces translations:
+
+- `no-unlocalized-strings` - Warns about untranslated JSX text
+- `t-call-in-function` - Ensures `t()` is called inside functions
+- `no-trans-inside-trans` - Prevents nested Trans components
+
+Excluded from checks: tests, mocks, UI primitives, config files.
+
+## Adding a New Locale
+
+Edit `lingui.config.js` and add the locale code to the `locales` array.