metacoding 1.5.1 → 2.0.1

package/templates/react/react.coding.instructions.md

@@ -1,694 +0,0 @@
----
-description: 'React/Frontend-specific coding standards and best practices'
-applyTo: '**/*.{tsx,jsx,ts,js}'
----
-
-# React/Frontend Coding Standards and Best Practices
-
-## Language and Framework Preferences
-
-- **Primary Language:** TypeScript with React 18+ for all React projects
-- **Build Tool:** Vite for development and build tooling
-- **Code Style:** Prettier with ESLint for consistent formatting and linting
-- **State Management:** Context API for simple state, Zustand/Redux Toolkit for complex state
-- **Target Compatibility:** Modern browsers (ES2020+), Node.js 18+
-
-## Code Quality Guidelines
-
-- **Component Design:** Small, focused components with single responsibilities
-- **Functions:** Prefer functional components with hooks over class components
-- **Performance:** Use React.memo, useMemo, and useCallback judiciously
-- **Error Handling:** Implement error boundaries and proper error handling
-- **Accessibility:** Follow WCAG guidelines and use semantic HTML
-- **Type Safety:** Strict TypeScript configuration with comprehensive type coverage
-
-## Naming Conventions
-
-- **Files:** PascalCase for components (e.g., `UserProfile.tsx`), camelCase for utilities (e.g., `apiHelpers.ts`)
-- **Components:** PascalCase (e.g., `UserCard`, `NavigationMenu`)
-- **Functions/Hooks:** camelCase (e.g., `useUserData`, `handleSubmit`)
-- **Variables:** camelCase (e.g., `userData`, `isLoading`)
-- **Constants:** SCREAMING_SNAKE_CASE (e.g., `API_ENDPOINTS`, `DEFAULT_TIMEOUT`)
-- **Interfaces/Types:** PascalCase with descriptive names (e.g., `UserData`, `ApiResponse`)
-- **CSS Classes:** kebab-case (e.g., `user-card`, `navigation-menu`)
-
-## Code Organization
-
-- **Feature-Based Structure:** Organize by features rather than file types
-- **Component Co-location:** Keep related files (component, styles, tests) together
-- **Barrel Exports:** Use index.ts files for clean imports
-- **Separation of Concerns:** Separate business logic from presentation logic
-
-### Recommended Project Structure
-
-```
-src/
-  components/          # Reusable UI components
-    ui/               # Basic UI primitives (Button, Input, Modal)
-    layout/           # Layout components (Header, Sidebar, Footer)
-  features/           # Feature-specific components and logic
-    auth/            # Authentication feature
-    dashboard/       # Dashboard feature
-  hooks/             # Custom React hooks
-  services/          # API calls and external services
-  utils/             # Utility functions
-  types/             # TypeScript type definitions
-  stores/            # State management (Context, Zustand, etc.)
-  assets/            # Static assets (images, icons, fonts)
-```
-
-## React-Specific Best Practices
-
-### Component Design Patterns
-
-```tsx
-// Good: Functional component with TypeScript
-interface UserCardProps {
-  user: User;
-  onEdit?: (user: User) => void;
-  className?: string;
-}
-
-export const UserCard: React.FC<UserCardProps> = ({
-  user,
-  onEdit,
-  className,
-}) => {
-  const handleEditClick = useCallback(() => {
-    onEdit?.(user);
-  }, [user, onEdit]);
-
-  return (
-    <div className={`user-card ${className || ''}`}>
-      <h3>{user.name}</h3>
-      <p>{user.email}</p>
-      {onEdit && <button onClick={handleEditClick}>Edit</button>}
-    </div>
-  );
-};
-```
-
-### Custom Hooks
-
-```tsx
-// Good: Custom hook for data fetching
-interface UseUserDataResult {
-  user: User | null;
-  loading: boolean;
-  error: string | null;
-  refetch: () => void;
-}
-
-export const useUserData = (userId: string): UseUserDataResult => {
-  const [user, setUser] = useState<User | null>(null);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<string | null>(null);
-
-  const fetchUser = useCallback(async () => {
-    try {
-      setLoading(true);
-      setError(null);
-      const userData = await userService.getUser(userId);
-      setUser(userData);
-    } catch (err) {
-      setError(err instanceof Error ? err.message : 'Unknown error');
-    } finally {
-      setLoading(false);
-    }
-  }, [userId]);
-
-  useEffect(() => {
-    fetchUser();
-  }, [fetchUser]);
-
-  return { user, loading, error, refetch: fetchUser };
-};
-```
-
-### State Management Patterns
-
-```tsx
-// Good: Context for global state
-interface AppContextType {
-  user: User | null;
-  theme: 'light' | 'dark';
-  setUser: (user: User | null) => void;
-  setTheme: (theme: 'light' | 'dark') => void;
-}
-
-const AppContext = createContext<AppContextType | undefined>(undefined);
-
-export const useAppContext = (): AppContextType => {
-  const context = useContext(AppContext);
-  if (!context) {
-    throw new Error('useAppContext must be used within AppProvider');
-  }
-  return context;
-};
-
-export const AppProvider: React.FC<{ children: React.ReactNode }> = ({
-  children,
-}) => {
-  const [user, setUser] = useState<User | null>(null);
-  const [theme, setTheme] = useState<'light' | 'dark'>('light');
-
-  const value = useMemo(
-    () => ({
-      user,
-      theme,
-      setUser,
-      setTheme,
-    }),
-    [user, theme]
-  );
-
-  return <AppContext.Provider value={value}>{children}</AppContext.Provider>;
-};
-```
-
-## Performance Optimization
-
-### Component Optimization
-
-```tsx
-// Good: Memoized component to prevent unnecessary re-renders
-interface UserListProps {
-  users: User[];
-  onUserSelect: (user: User) => void;
-}
-
-export const UserList = React.memo<UserListProps>(({ users, onUserSelect }) => {
-  return (
-    <div className="user-list">
-      {users.map((user) => (
-        <UserCard key={user.id} user={user} onEdit={onUserSelect} />
-      ))}
-    </div>
-  );
-});
-
-UserList.displayName = 'UserList';
-```
-
-### Optimized Callbacks and Values
-
-```tsx
-// Good: Memoized callbacks and computed values
-export const Dashboard: React.FC = () => {
-  const [filter, setFilter] = useState('');
-  const [users, setUsers] = useState<User[]>([]);
-
-  // Memoize expensive computations
-  const filteredUsers = useMemo(() => {
-    return users.filter((user) =>
-      user.name.toLowerCase().includes(filter.toLowerCase())
-    );
-  }, [users, filter]);
-
-  // Memoize callbacks to prevent child re-renders
-  const handleUserSelect = useCallback((user: User) => {
-    console.log('Selected user:', user);
-  }, []);
-
-  const handleFilterChange = useCallback(
-    (event: React.ChangeEvent<HTMLInputElement>) => {
-      setFilter(event.target.value);
-    },
-    []
-  );
-
-  return (
-    <div>
-      <input
-        value={filter}
-        onChange={handleFilterChange}
-        placeholder="Filter users..."
-      />
-      <UserList users={filteredUsers} onUserSelect={handleUserSelect} />
-    </div>
-  );
-};
-```
-
-## Error Handling and Validation
-
-### Error Boundaries
-
-```tsx
-interface ErrorBoundaryState {
-  hasError: boolean;
-  error?: Error;
-}
-
-class ErrorBoundary extends React.Component<
-  React.PropsWithChildren<{}>,
-  ErrorBoundaryState
-> {
-  constructor(props: React.PropsWithChildren<{}>) {
-    super(props);
-    this.state = { hasError: false };
-  }
-
-  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
-    return { hasError: true, error };
-  }
-
-  componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
-    console.error('Error caught by boundary:', error, errorInfo);
-  }
-
-  render() {
-    if (this.state.hasError) {
-      return (
-        <div className="error-boundary">
-          <h2>Something went wrong</h2>
-          <p>{this.state.error?.message}</p>
-        </div>
-      );
-    }
-
-    return this.props.children;
-  }
-}
-```
-
-### Form Validation
-
-```tsx
-// Good: Form with validation using react-hook-form
-import { useForm } from 'react-hook-form';
-import { zodResolver } from '@hookform/resolvers/zod';
-import { z } from 'zod';
-
-const userSchema = z.object({
-  name: z.string().min(2, 'Name must be at least 2 characters'),
-  email: z.string().email('Invalid email address'),
-  age: z.number().min(18, 'Must be at least 18 years old'),
-});
-
-type UserFormData = z.infer<typeof userSchema>;
-
-export const UserForm: React.FC = () => {
-  const {
-    register,
-    handleSubmit,
-    formState: { errors, isSubmitting },
-  } = useForm<UserFormData>({
-    resolver: zodResolver(userSchema),
-  });
-
-  const onSubmit = async (data: UserFormData) => {
-    try {
-      await userService.createUser(data);
-    } catch (error) {
-      console.error('Failed to create user:', error);
-    }
-  };
-
-  return (
-    <form onSubmit={handleSubmit(onSubmit)}>
-      <div>
-        <input {...register('name')} placeholder="Name" />
-        {errors.name && <p className="error">{errors.name.message}</p>}
-      </div>
-
-      <div>
-        <input {...register('email')} placeholder="Email" />
-        {errors.email && <p className="error">{errors.email.message}</p>}
-      </div>
-
-      <div>
-        <input
-          {...register('age', { valueAsNumber: true })}
-          type="number"
-          placeholder="Age"
-        />
-        {errors.age && <p className="error">{errors.age.message}</p>}
-      </div>
-
-      <button type="submit" disabled={isSubmitting}>
-        {isSubmitting ? 'Creating...' : 'Create User'}
-      </button>
-    </form>
-  );
-};
-```
-
-## Testing Standards
-
-### Component Testing
-
-```tsx
-// Good: Component testing with React Testing Library
-import { render, screen, fireEvent } from '@testing-library/react';
-import { UserCard } from './UserCard';
-
-const mockUser: User = {
-  id: '1',
-  name: 'John Doe',
-  email: 'john@example.com',
-};
-
-describe('UserCard', () => {
-  it('renders user information correctly', () => {
-    render(<UserCard user={mockUser} />);
-
-    expect(screen.getByText('John Doe')).toBeInTheDocument();
-    expect(screen.getByText('john@example.com')).toBeInTheDocument();
-  });
-
-  it('calls onEdit when edit button is clicked', () => {
-    const mockOnEdit = jest.fn();
-    render(<UserCard user={mockUser} onEdit={mockOnEdit} />);
-
-    const editButton = screen.getByText('Edit');
-    fireEvent.click(editButton);
-
-    expect(mockOnEdit).toHaveBeenCalledWith(mockUser);
-  });
-
-  it('does not render edit button when onEdit is not provided', () => {
-    render(<UserCard user={mockUser} />);
-
-    expect(screen.queryByText('Edit')).not.toBeInTheDocument();
-  });
-});
-```
-
-### Hook Testing
-
-```tsx
-// Good: Custom hook testing
-import { renderHook, waitFor } from '@testing-library/react';
-import { useUserData } from './useUserData';
-
-// Mock the service
-jest.mock('../services/userService');
-
-describe('useUserData', () => {
-  beforeEach(() => {
-    jest.clearAllMocks();
-  });
-
-  it('fetches user data successfully', async () => {
-    const mockUser = { id: '1', name: 'John Doe' };
-    (userService.getUser as jest.Mock).mockResolvedValue(mockUser);
-
-    const { result } = renderHook(() => useUserData('1'));
-
-    expect(result.current.loading).toBe(true);
-    expect(result.current.user).toBe(null);
-
-    await waitFor(() => {
-      expect(result.current.loading).toBe(false);
-    });
-
-    expect(result.current.user).toEqual(mockUser);
-    expect(result.current.error).toBe(null);
-  });
-
-  it('handles error states correctly', async () => {
-    const errorMessage = 'User not found';
-    (userService.getUser as jest.Mock).mockRejectedValue(
-      new Error(errorMessage)
-    );
-
-    const { result } = renderHook(() => useUserData('1'));
-
-    await waitFor(() => {
-      expect(result.current.loading).toBe(false);
-    });
-
-    expect(result.current.user).toBe(null);
-    expect(result.current.error).toBe(errorMessage);
-  });
-});
-```
-
-## Accessibility Standards
-
-### Semantic HTML and ARIA
-
-```tsx
-// Good: Accessible form component
-export const AccessibleForm: React.FC = () => {
-  const [fieldError, setFieldError] = useState<string>('');
-
-  return (
-    <form role="form" aria-label="User registration form">
-      <fieldset>
-        <legend>Personal Information</legend>
-
-        <div className="form-group">
-          <label htmlFor="username">Username:</label>
-          <input
-            id="username"
-            type="text"
-            aria-required="true"
-            aria-describedby={fieldError ? 'username-error' : undefined}
-            aria-invalid={fieldError ? 'true' : 'false'}
-          />
-          {fieldError && (
-            <div
-              id="username-error"
-              role="alert"
-              aria-live="polite"
-              className="error-message"
-            >
-              {fieldError}
-            </div>
-          )}
-        </div>
-      </fieldset>
-
-      <button type="submit" aria-describedby="submit-help">
-        Register
-      </button>
-      <div id="submit-help" className="help-text">
-        Click to create your account
-      </div>
-    </form>
-  );
-};
-```
-
-### Keyboard Navigation
-
-```tsx
-// Good: Keyboard accessible dropdown
-export const Dropdown: React.FC<DropdownProps> = ({ options, onSelect }) => {
-  const [isOpen, setIsOpen] = useState(false);
-  const [activeIndex, setActiveIndex] = useState(-1);
-
-  const handleKeyDown = (event: React.KeyboardEvent) => {
-    switch (event.key) {
-      case 'Enter':
-      case ' ':
-        event.preventDefault();
-        if (activeIndex >= 0) {
-          onSelect(options[activeIndex]);
-        }
-        setIsOpen(!isOpen);
-        break;
-      case 'ArrowDown':
-        event.preventDefault();
-        setActiveIndex((prev) => (prev < options.length - 1 ? prev + 1 : 0));
-        break;
-      case 'ArrowUp':
-        event.preventDefault();
-        setActiveIndex((prev) => (prev > 0 ? prev - 1 : options.length - 1));
-        break;
-      case 'Escape':
-        setIsOpen(false);
-        setActiveIndex(-1);
-        break;
-    }
-  };
-
-  return (
-    <div className="dropdown" onKeyDown={handleKeyDown}>
-      <button
-        aria-haspopup="listbox"
-        aria-expanded={isOpen}
-        onClick={() => setIsOpen(!isOpen)}
-      >
-        Select option
-      </button>
-      {isOpen && (
-        <ul role="listbox" className="dropdown-menu">
-          {options.map((option, index) => (
-            <li
-              key={option.id}
-              role="option"
-              aria-selected={index === activeIndex}
-              className={index === activeIndex ? 'active' : ''}
-              onClick={() => onSelect(option)}
-            >
-              {option.label}
-            </li>
-          ))}
-        </ul>
-      )}
-    </div>
-  );
-};
-```
-
-## Styling and CSS Standards
-
-### CSS-in-JS with Styled Components
-
-```tsx
-import styled from 'styled-components';
-
-// Good: Styled component with theme support
-const Button = styled.button<{ variant?: 'primary' | 'secondary' }>`
-  padding: ${({ theme }) => theme.spacing.md};
-  border: none;
-  border-radius: ${({ theme }) => theme.borderRadius.sm};
-  font-weight: 500;
-  cursor: pointer;
-  transition: all 0.2s ease;
-
-  ${({ variant = 'primary', theme }) => {
-    switch (variant) {
-      case 'primary':
-        return `
-          background-color: ${theme.colors.primary};
-          color: ${theme.colors.white};
-          
-          &:hover {
-            background-color: ${theme.colors.primaryDark};
-          }
-        `;
-      case 'secondary':
-        return `
-          background-color: ${theme.colors.secondary};
-          color: ${theme.colors.text};
-          
-          &:hover {
-            background-color: ${theme.colors.secondaryDark};
-          }
-        `;
-    }
-  }}
-
-  &:disabled {
-    opacity: 0.6;
-    cursor: not-allowed;
-  }
-`;
-```
-
-### CSS Modules
-
-```tsx
-// UserCard.module.css
-.userCard {
-  border: 1px solid #e0e0e0;
-  border-radius: 8px;
-  padding: 16px;
-  margin-bottom: 16px;
-}
-
-.userCard:hover {
-  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
-}
-
-.userInfo {
-  margin-bottom: 12px;
-}
-
-.userName {
-  font-size: 1.2em;
-  font-weight: bold;
-  margin-bottom: 4px;
-}
-
-// UserCard.tsx
-import styles from './UserCard.module.css';
-
-export const UserCard: React.FC<UserCardProps> = ({ user }) => {
-  return (
-    <div className={styles.userCard}>
-      <div className={styles.userInfo}>
-        <h3 className={styles.userName}>{user.name}</h3>
-        <p>{user.email}</p>
-      </div>
-    </div>
-  );
-};
-```
-
-## Common Anti-Patterns to Avoid
-
-- **Inline Styles for Complex Styling:** Use CSS-in-JS or CSS modules instead
-- **Prop Drilling:** Use Context or state management for deeply nested props
-- **Mutating Props:** Always treat props as read-only
-- **Missing Keys in Lists:** Always provide unique keys for list items
-- **Not Cleaning Up Effects:** Remove event listeners and cancel async operations
-- **Using Index as Key:** Use stable, unique identifiers for keys
-- **Overusing useEffect:** Consider if the effect is really necessary
-- **Not Memoizing Expensive Calculations:** Use useMemo for expensive computations
-- **Creating Objects/Functions in Render:** This causes unnecessary re-renders
-- **Ignoring Accessibility:** Always consider screen readers and keyboard navigation
-
-## Security Considerations
-
-### XSS Prevention
-
-```tsx
-// Good: Safe rendering of user content
-import DOMPurify from 'dompurify';
-
-interface SafeHtmlProps {
-  content: string;
-}
-
-export const SafeHtml: React.FC<SafeHtmlProps> = ({ content }) => {
-  const sanitizedContent = useMemo(() => {
-    return DOMPurify.sanitize(content);
-  }, [content]);
-
-  return <div dangerouslySetInnerHTML={{ __html: sanitizedContent }} />;
-};
-
-// Good: Escape user input in URL parameters
-const SearchResults: React.FC = () => {
-  const query = useSearchParams().get('q') || '';
-  const encodedQuery = encodeURIComponent(query);
-
-  return (
-    <div>
-      <h2>Results for: {query}</h2>
-      <a href={`/search/advanced?query=${encodedQuery}`}>Advanced search</a>
-    </div>
-  );
-};
-```
-
-### Environment Variables
-
-```tsx
-// Good: Environment configuration
-interface Config {
-  apiUrl: string;
-  environment: 'development' | 'staging' | 'production';
-  enableAnalytics: boolean;
-}
-
-const config: Config = {
-  apiUrl: import.meta.env.VITE_API_URL || 'http://localhost:3000',
-  environment:
-    (import.meta.env.VITE_ENVIRONMENT as Config['environment']) ||
-    'development',
-  enableAnalytics: import.meta.env.VITE_ENABLE_ANALYTICS === 'true',
-};
-
-// Validate required environment variables
-if (!config.apiUrl) {
-  throw new Error('VITE_API_URL environment variable is required');
-}
-
-export default config;
-```