metacoding 1.0.0 → 1.1.0

package/templates/react/react.docs.instructions.md

@@ -0,0 +1,427 @@
+---
+description: 'React-specific documentation standards and guidelines'
+language: 'react'
+category: 'documentation'
+---
+
+# React Documentation Standards
+
+## Component Documentation Guidelines
+
+### JSDoc for React Components
+
+````typescript
+/**
+ * A reusable button component with multiple variants and sizes.
+ *
+ * @example
+ * ```tsx
+ * <Button variant="primary" size="large" onClick={handleClick}>
+ *   Click me
+ * </Button>
+ * ```
+ *
+ * @param props - The component props
+ * @param props.variant - The visual style variant
+ * @param props.size - The size of the button
+ * @param props.disabled - Whether the button is disabled
+ * @param props.children - The button content
+ * @param props.onClick - Click event handler
+ */
+export function Button({
+  variant = 'primary',
+  size = 'medium',
+  disabled = false,
+  children,
+  onClick,
+}: ButtonProps) {
+  // Component implementation
+}
+````
+
+### PropTypes and TypeScript Interfaces
+
+```typescript
+/**
+ * Props for the Button component.
+ */
+export interface ButtonProps {
+  /** The visual style variant of the button */
+  variant?: 'primary' | 'secondary' | 'danger';
+  /** The size of the button */
+  size?: 'small' | 'medium' | 'large';
+  /** Whether the button is disabled */
+  disabled?: boolean;
+  /** The content to display inside the button */
+  children: React.ReactNode;
+  /** Click event handler */
+  onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void;
+}
+```
+
+## Component API Documentation
+
+### Required Documentation Elements
+
+1. **Purpose and Use Cases:** Clear description of what the component does
+2. **Props Interface:** Complete TypeScript interface with descriptions
+3. **Usage Examples:** Common usage patterns with code examples
+4. **Accessibility Notes:** ARIA requirements and keyboard interactions
+5. **Styling Information:** CSS classes, design tokens, theming support
+6. **Dependencies:** Required peer dependencies or context providers
+
+### Component README Template
+
+````markdown
+# ComponentName
+
+Brief description of the component's purpose and primary use case.
+
+## Usage
+
+```tsx
+import { ComponentName } from './ComponentName';
+
+function Example() {
+  return (
+    <ComponentName prop1="value" prop2={variable} onAction={handleAction}>
+      Content
+    </ComponentName>
+  );
+}
+```
+````
+
+## Props
+
+| Prop  | Type    | Default   | Description          |
+| ----- | ------- | --------- | -------------------- |
+| prop1 | string  | 'default' | Description of prop1 |
+| prop2 | boolean | false     | Description of prop2 |
+
+## Examples
+
+### Basic Usage
+
+[Code example]
+
+### Advanced Usage
+
+[Code example with complex props]
+
+## Accessibility
+
+- Keyboard navigation support
+- Screen reader compatibility
+- ARIA attributes used
+
+## Styling
+
+- CSS classes available
+- Design tokens used
+- Theming support
+
+## Related Components
+
+- List of related components
+- When to use alternatives
+
+````
+
+## Hook Documentation
+
+### Custom Hook Documentation
+
+```typescript
+/**
+ * A hook for managing form state with validation.
+ *
+ * @example
+ * ```tsx
+ * function ContactForm() {
+ *   const { values, errors, handleChange, handleSubmit } = useForm({
+ *     initialValues: { email: '', message: '' },
+ *     validation: {
+ *       email: (value) => value.includes('@') ? null : 'Invalid email'
+ *     }
+ *   });
+ *
+ *   return (
+ *     <form onSubmit={handleSubmit}>
+ *       <input
+ *         value={values.email}
+ *         onChange={handleChange('email')}
+ *         aria-invalid={!!errors.email}
+ *       />
+ *       {errors.email && <span>{errors.email}</span>}
+ *     </form>
+ *   );
+ * }
+ * ```
+ *
+ * @param config - Hook configuration options
+ * @returns Form state and handlers
+ */
+export function useForm<T extends Record<string, any>>(
+  config: FormConfig<T>
+): FormReturn<T> {
+  // Hook implementation
+}
+````
+
+## Storybook Documentation
+
+### Story Documentation Standards
+
+```typescript
+import type { Meta, StoryObj } from '@storybook/react';
+import { Button } from './Button';
+
+const meta: Meta<typeof Button> = {
+  title: 'Components/Button',
+  component: Button,
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'A versatile button component with multiple variants and sizes.',
+      },
+    },
+  },
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ['primary', 'secondary', 'danger'],
+      description: 'The visual style variant of the button',
+    },
+    size: {
+      control: 'select',
+      options: ['small', 'medium', 'large'],
+      description: 'The size of the button',
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/**
+ * The default button style used for primary actions.
+ */
+export const Primary: Story = {
+  args: {
+    variant: 'primary',
+    children: 'Button',
+  },
+};
+
+/**
+ * Secondary buttons for less prominent actions.
+ */
+export const Secondary: Story = {
+  args: {
+    variant: 'secondary',
+    children: 'Button',
+  },
+};
+```
+
+## Architecture Documentation
+
+### Component Architecture Docs
+
+Document component relationships and data flow:
+
+```markdown
+# Component Architecture
+
+## Component Hierarchy
+```
+
+App
+├── Header
+│ ├── Navigation
+│ └── UserMenu
+├── Main
+│ ├── Sidebar
+│ └── ContentArea
+│ ├── FeatureComponent
+│ └── DataDisplay
+└── Footer
+
+```
+
+## Data Flow
+
+1. **State Management:** Describe state management approach (Context, Redux, Zustand)
+2. **Props Flow:** How data flows down through component tree
+3. **Event Handling:** How events bubble up and are handled
+4. **Side Effects:** API calls, external integrations
+
+## Performance Considerations
+
+- Component memoization strategies
+- Bundle splitting points
+- Lazy loading implementation
+- Re-render optimization
+```
+
+## Design System Documentation
+
+### Component Design Specs
+
+```markdown
+# Design System - Button Component
+
+## Design Tokens
+
+### Colors
+
+- Primary: `--color-primary-500`
+- Secondary: `--color-neutral-200`
+- Danger: `--color-error-500`
+
+### Typography
+
+- Font: `--font-family-base`
+- Size: `--font-size-md`
+- Weight: `--font-weight-medium`
+
+### Spacing
+
+- Padding: `--space-3` `--space-4`
+- Margin: `--space-2`
+
+## Variants
+
+### Primary Button
+
+- Background: Primary color
+- Text: White
+- Border: None
+- Shadow: `--shadow-sm`
+
+### Secondary Button
+
+- Background: Transparent
+- Text: Primary color
+- Border: 1px solid primary
+- Shadow: None
+
+## States
+
+- **Default:** Base styling
+- **Hover:** Darker background, `--shadow-md`
+- **Active:** Pressed state with inset shadow
+- **Disabled:** 50% opacity, no interactions
+- **Focus:** Visible focus ring for accessibility
+```
+
+## API Integration Documentation
+
+### Component API Integration
+
+````typescript
+/**
+ * A component that fetches and displays user data.
+ *
+ * @example
+ * ```tsx
+ * <UserProfile userId="123" />
+ * ```
+ *
+ * ## API Dependencies
+ *
+ * - **GET /api/users/:id** - Fetches user profile data
+ * - **PUT /api/users/:id** - Updates user profile
+ *
+ * ## Error Handling
+ *
+ * - Network errors: Shows retry button
+ * - 404 errors: Shows "User not found" message
+ * - 403 errors: Shows permission denied message
+ *
+ * ## Loading States
+ *
+ * - Initial load: Skeleton placeholder
+ * - Update: Spinner overlay
+ * - Background refresh: Subtle loading indicator
+ */
+export function UserProfile({ userId }: UserProfileProps) {
+  // Component implementation
+}
+````
+
+## Testing Documentation Integration
+
+### Component Test Documentation
+
+```typescript
+/**
+ * Tests for the Button component.
+ *
+ * @testcases
+ * - Renders with correct text content
+ * - Applies variant classes correctly
+ * - Handles click events properly
+ * - Shows disabled state appropriately
+ * - Meets accessibility requirements
+ * - Supports keyboard navigation
+ */
+describe('Button Component', () => {
+  // Test implementations
+});
+```
+
+## Migration and Deprecation Docs
+
+### Breaking Changes Documentation
+
+````markdown
+# Migration Guide: Button v2.0
+
+## Breaking Changes
+
+### Removed Props
+
+- `type` prop removed - use `variant` instead
+- `large` prop removed - use `size="large"` instead
+
+### API Changes
+
+- `onClick` now receives event object as first parameter
+- `disabled` prop now affects aria-disabled attribute
+
+## Migration Steps
+
+1. Replace `type="primary"` with `variant="primary"`
+2. Replace `large={true}` with `size="large"`
+3. Update click handlers to accept event parameter
+
+### Before
+
+```tsx
+<Button type="primary" large onClick={handleClick}>
+  Click me
+</Button>
+```
+````
+
+### After
+
+```tsx
+<Button variant="primary" size="large" onClick={(e) => handleClick(e)}>
+  Click me
+</Button>
+```
+
+```
+
+## Documentation Maintenance
+
+- **Component Updates:** Update docs when component API changes
+- **Example Accuracy:** Ensure all code examples are tested and working
+- **Version Alignment:** Keep documentation in sync with component versions
+- **Accessibility Updates:** Update accessibility docs when ARIA patterns change
+- **Performance Notes:** Document performance implications of component usage
+```

package/templates/react/react.testing.instructions.md

@@ -0,0 +1,193 @@
+---
+description: 'React-specific testing guidelines and standards'
+language: 'react'
+category: 'testing'
+---
+
+# React Testing Standards
+
+## Test Case Naming Conventions
+
+### Test Case ID Format: `[AREA]-[TYPE]-[NUMBER]`
+
+**React/Frontend Area Prefixes:**
+
+- `COMP` - React component tests
+- `HOOK` - Custom hooks tests
+- `PAGE` - Page/Route component tests
+- `FORM` - Form validation and submission tests
+- `UI` - UI interaction and behavior tests
+- `STORE` - State management tests (Redux/Zustand/Context)
+- `API` - Frontend API client tests
+- `A11Y` - Accessibility compliance tests
+- `PERF` - Performance and optimization tests
+- `UTIL` - Frontend utility function tests
+
+**Type Suffixes:**
+
+- `UNIT` - Unit tests (isolated component testing)
+- `INT` - Integration tests (component interaction testing)
+- `E2E` - End-to-end tests (full user workflow testing)
+
+**Examples:**
+
+- `COMP-UNIT-001` - First unit test for React Component
+- `HOOK-UNIT-001` - First unit test for Custom Hook
+- `PAGE-E2E-001` - First end-to-end test for Page Component
+- `FORM-INT-001` - First integration test for Form Component
+
+## Testing Framework Stack
+
+- **Primary Framework:** Jest with React Testing Library
+- **Component Testing:** @testing-library/react for component behavior testing
+- **User Interaction:** @testing-library/user-event for realistic user interactions
+- **Mocking:** Jest built-in mocking for modules and dependencies
+- **Snapshot Testing:** Use sparingly, prefer behavioral tests
+
+## Component Testing Guidelines
+
+### Test Structure
+
+- **Arrange-Act-Assert:** Clear test structure with setup, action, and verification
+- **Test Behavior, Not Implementation:** Focus on what the component does, not how
+- **User-Centric Tests:** Test from the user's perspective using accessible queries
+- **Isolation:** Each test should be independent and not rely on other tests
+
+### Testing Patterns
+
+```typescript
+// Good: Testing behavior
+test('displays error message when form submission fails', async () => {
+  render(<ContactForm onSubmit={jest.fn().mockRejectedValue(new Error())} />);
+
+  await user.click(screen.getByRole('button', { name: /submit/i }));
+
+  expect(screen.getByText(/error occurred/i)).toBeInTheDocument();
+});
+
+// Bad: Testing implementation details
+test('calls setState when button is clicked', () => {
+  const component = shallow(<MyComponent />);
+  component.find('button').simulate('click');
+  expect(component.state('clicked')).toBe(true);
+});
+```
+
+## Query Priorities
+
+1. **Accessible Queries (Preferred):**
+
+   - `getByRole()` - Primary choice for interactive elements
+   - `getByLabelText()` - Form inputs with labels
+   - `getByPlaceholderText()` - Form inputs with placeholders
+   - `getByText()` - Non-interactive text content
+
+2. **Semantic Queries:**
+
+   - `getByAltText()` - Images with alt text
+   - `getByTitle()` - Elements with title attributes
+
+3. **Test ID Queries (Last Resort):**
+   - `getByTestId()` - Only when semantic queries aren't sufficient
+
+## React-Specific Testing Scenarios
+
+### Component Lifecycle and State
+
+- **State Changes:** Test state transitions triggered by user interactions
+- **Effect Testing:** Verify useEffect behavior with proper cleanup
+- **Context Testing:** Test components that consume React Context
+- **Custom Hooks:** Test custom hooks in isolation using renderHook
+
+### Async Operations
+
+- **API Calls:** Mock API responses and test loading/success/error states
+- **User Interactions:** Use waitFor() for async state updates
+- **Suspense:** Test Suspense boundaries and fallback components
+- **Error Boundaries:** Test error boundary behavior with error states
+
+### Form Testing
+
+- **Form Validation:** Test client-side validation messages
+- **Form Submission:** Test successful and failed form submissions
+- **Field Interactions:** Test input changes, selections, and clearing
+- **Accessibility:** Ensure form labels and error associations work correctly
+
+## Mock Strategies
+
+### Component Mocking
+
+```typescript
+// Mock child components that aren't relevant to the test
+jest.mock('./ComplexChild', () => {
+  return function MockedComplexChild({ title }: { title: string }) {
+    return <div data-testid="mocked-complex-child">{title}</div>;
+  };
+});
+```
+
+### API Mocking
+
+```typescript
+// Use MSW (Mock Service Worker) for API mocking
+import { rest } from 'msw';
+import { setupServer } from 'msw/node';
+
+const server = setupServer(
+  rest.get('/api/users', (req, res, ctx) => {
+    return res(ctx.json([{ id: 1, name: 'John Doe' }]));
+  })
+);
+```
+
+## Performance Testing
+
+- **Render Performance:** Use React DevTools Profiler for performance testing
+- **Memory Leaks:** Test component cleanup and event listener removal
+- **Large Lists:** Test virtualization and pagination performance
+- **Bundle Size:** Monitor component bundle impact with bundler analysis
+
+## Testing File Organization
+
+```
+/test
+  /components
+    /common           # Reusable component tests
+    /pages            # Page component tests
+    /forms            # Form component tests
+  /hooks              # Custom hook tests
+  /utils              # Utility function tests
+  /fixtures
+    /api-responses    # Mock API response data
+    /component-props  # Common component prop fixtures
+```
+
+## React Testing Anti-Patterns
+
+- **Avoid Shallow Rendering:** Use full rendering with React Testing Library
+- **Don't Test Implementation Details:** Focus on user-observable behavior
+- **Avoid Snapshot Testing Everything:** Use snapshots sparingly for stable UI
+- **Don't Mock React Itself:** Mock external dependencies, not React features
+- **Avoid Testing Library Internals:** Don't test useState, useEffect directly
+
+## Accessibility Testing
+
+- **Screen Reader Testing:** Ensure components work with assistive technology
+- **Keyboard Navigation:** Test keyboard-only navigation patterns
+- **ARIA Attributes:** Verify proper ARIA labels and roles
+- **Color Contrast:** Test component readability across different themes
+- **Focus Management:** Test focus trapping and restoration in modals/dialogs
+
+## Test Data Management
+
+- **Factory Functions:** Create reusable test data generators
+- **Realistic Data:** Use realistic data that matches production scenarios
+- **Edge Cases:** Test with empty states, long text, special characters
+- **Internationalization:** Test with different locales and text lengths
+
+## CI/CD Integration
+
+- **Visual Regression:** Use tools like Chromatic for visual testing
+- **Cross-Browser Testing:** Test across different browsers and devices
+- **Performance Budgets:** Set performance thresholds for components
+- **Bundle Analysis:** Monitor bundle size impact of new components