@windagency/valora 2.0.1

package/data/templates/PLAN_PATTERN_REACT_FEATURE.md

@@ -0,0 +1,303 @@
+# Planning Template: React Feature/Component
+
+## Pattern Type: React Feature
+
+**Use when**: Adding new React features, pages, or complex component hierarchies.
+
+---
+
+## Quick Fill Template
+
+### 1. Feature Overview
+
+| Field                | Value                                       |
+| -------------------- | ------------------------------------------- |
+| **Feature Name**     | [e.g., UserProfile, Dashboard, Settings]    |
+| **Type**             | [ ] Page [ ] Feature [ ] Component Library  |
+| **State Management** | [ ] Local [ ] Context [ ] Zustand [ ] Redux |
+| **Data Fetching**    | [ ] TanStack Query [ ] SWR [ ] Custom       |
+| **Forms**            | [ ] React Hook Form [ ] Formik [ ] Custom   |
+
+### 2. Component Hierarchy
+
+```
+[FeatureName]/
+├── index.ts                 # Public exports
+├── [FeatureName].tsx        # Main container
+├── components/
+│   ├── [Component1].tsx     # Molecule
+│   ├── [Component2].tsx     # Molecule
+│   └── [Component3].tsx     # Organism
+├── hooks/
+│   ├── use[Feature].ts      # Feature hook
+│   └── use[Feature]Query.ts # Data hook
+├── types/
+│   └── index.ts             # Type definitions
+├── utils/
+│   └── index.ts             # Utilities
+└── __tests__/
+    ├── [FeatureName].test.tsx
+    └── components/
+```
+
+### 3. Files to Create
+
+| File                                          | Type      | Purpose          |
+| --------------------------------------------- | --------- | ---------------- |
+| `src/features/[feature]/index.ts`             | Export    | Public API       |
+| `src/features/[feature]/[Feature].tsx`        | Container | Main component   |
+| `src/features/[feature]/components/*.tsx`     | UI        | Child components |
+| `src/features/[feature]/hooks/*.ts`           | Logic     | Custom hooks     |
+| `src/features/[feature]/types/index.ts`       | Types     | TypeScript types |
+| `src/features/[feature]/__tests__/*.test.tsx` | Tests     | Component tests  |
+
+### 4. Standard Implementation Steps
+
+#### Step 1: Define Types
+
+**Objective**: Create TypeScript interfaces
+
+**Files**:
+
+- `src/features/[feature]/types/index.ts`
+
+```typescript
+export interface [Feature]Props {
+  // Component props
+}
+
+export interface [Feature]State {
+  // State shape
+}
+
+export interface [Feature]Data {
+  // API response type
+}
+```
+
+**Validation**: Types compile without errors
+
+---
+
+#### Step 2: Create Data Hooks
+
+**Objective**: Implement data fetching with TanStack Query
+
+**Files**:
+
+- `src/features/[feature]/hooks/use[Feature]Query.ts`
+
+```typescript
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+
+export function use[Feature]Query(id: string) {
+  return useQuery({
+    queryKey: ['[feature]', id],
+    queryFn: () => fetch[Feature](id),
+  });
+}
+
+export function use[Feature]Mutation() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: update[Feature],
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['[feature]'] });
+    },
+  });
+}
+```
+
+**Validation**: Hooks fetch and cache data correctly
+
+---
+
+#### Step 3: Create UI Components
+
+**Objective**: Build component hierarchy (atoms → molecules → organisms)
+
+**Files**:
+
+- `src/features/[feature]/components/[Component].tsx`
+
+```typescript
+interface [Component]Props {
+  // Props
+}
+
+export function [Component]({ ...props }: [Component]Props) {
+  return (
+    <div className="...">
+      {/* Component JSX */}
+    </div>
+  );
+}
+```
+
+**Validation**: Components render correctly in Storybook
+
+---
+
+#### Step 4: Create Main Container
+
+**Objective**: Compose components with data and logic
+
+**Files**:
+
+- `src/features/[feature]/[Feature].tsx`
+
+```typescript
+import { use[Feature]Query } from './hooks/use[Feature]Query';
+import { [Component1], [Component2] } from './components';
+
+export function [Feature]({ id }: [Feature]Props) {
+  const { data, isLoading, error } = use[Feature]Query(id);
+
+  if (isLoading) return <[Feature]Skeleton />;
+  if (error) return <[Feature]Error error={error} />;
+
+  return (
+    <div className="[feature]-container">
+      <[Component1] data={data} />
+      <[Component2] data={data} />
+    </div>
+  );
+}
+```
+
+**Validation**: Container orchestrates data and components
+
+---
+
+#### Step 5: Add Form Handling (if applicable)
+
+**Objective**: Implement forms with React Hook Form
+
+**Files**:
+
+- `src/features/[feature]/components/[Feature]Form.tsx`
+
+```typescript
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+
+export function [Feature]Form({ onSubmit }: [Feature]FormProps) {
+  const form = useForm<[Feature]FormData>({
+    resolver: zodResolver([feature]FormSchema),
+    defaultValues: {},
+  });
+
+  return (
+    <form onSubmit={form.handleSubmit(onSubmit)}>
+      {/* Form fields */}
+    </form>
+  );
+}
+```
+
+**Validation**: Form validates and submits correctly
+
+---
+
+#### Step 6: Write Tests
+
+**Objective**: Add component and integration tests
+
+**Files**:
+
+- `src/features/[feature]/__tests__/[Feature].test.tsx`
+
+```typescript
+import { render, screen } from '@testing-library/react';
+import { [Feature] } from '../[Feature]';
+
+describe('[Feature]', () => {
+  it('renders loading state', () => {
+    render(<[Feature] id="123" />);
+    expect(screen.getByTestId('loading')).toBeInTheDocument();
+  });
+
+  it('renders data when loaded', async () => {
+    render(<[Feature] id="123" />);
+    expect(await screen.findByText('...')).toBeInTheDocument();
+  });
+
+  it('renders error state', async () => {
+    // Mock error
+    render(<[Feature] id="invalid" />);
+    expect(await screen.findByText(/error/i)).toBeInTheDocument();
+  });
+});
+```
+
+**Validation**: `pnpm test:quick` passes
+
+---
+
+#### Step 7: Add Accessibility Tests
+
+**Objective**: Ensure WCAG compliance
+
+**Files**:
+
+- `src/features/[feature]/__tests__/[Feature].a11y.test.tsx`
+
+```typescript
+import { axe } from 'vitest-axe';
+
+it('has no accessibility violations', async () => {
+  const { container } = render(<[Feature] id="123" />);
+  const results = await axe(container);
+  expect(results).toHaveNoViolations();
+});
+```
+
+**Validation**: No a11y violations
+
+---
+
+### 5. Standard Dependencies
+
+| Dependency      | Purpose       | Status        |
+| --------------- | ------------- | ------------- |
+| React 18+       | UI library    | [ ] Available |
+| TanStack Query  | Data fetching | [ ] Available |
+| React Hook Form | Forms         | [ ] Available |
+| Zod             | Validation    | [ ] Available |
+| Tailwind CSS    | Styling       | [ ] Available |
+
+### 6. Standard Risks
+
+| Risk                   | Mitigation                     |
+| ---------------------- | ------------------------------ |
+| Prop drilling          | Use composition or context     |
+| Re-render performance  | Use memo, useMemo, useCallback |
+| Missing loading states | Add Suspense boundaries        |
+| Missing error states   | Add Error boundaries           |
+| Accessibility issues   | Test with axe, screen reader   |
+
+### 7. Rollback
+
+```bash
+# Revert all changes
+git revert HEAD
+
+# Or remove feature folder
+rm -rf src/features/[feature]
+```
+
+---
+
+## Estimated Effort
+
+| Step           | Points | Confidence |
+| -------------- | ------ | ---------- |
+| Types          | 1      | High       |
+| Data Hooks     | 2      | High       |
+| UI Components  | 3      | Medium     |
+| Main Container | 2      | High       |
+| Form Handling  | 2      | Medium     |
+| Tests          | 2      | High       |
+| A11y Tests     | 1      | High       |
+| **Total**      | **13** | **Medium** |

package/data/templates/PLAN_PATTERN_REST_API.md

@@ -0,0 +1,322 @@
+# Planning Template: REST API Endpoint
+
+## Pattern Type: REST API
+
+**Use when**: Adding new API endpoints, extending existing APIs, or creating new resources.
+
+---
+
+## Quick Fill Template
+
+### 1. Endpoint Overview
+
+| Field             | Value                                         |
+| ----------------- | --------------------------------------------- |
+| **Resource**      | [e.g., users, orders, products]               |
+| **Base Path**     | `/api/v1/[resource]`                          |
+| **Methods**       | [ ] GET [ ] POST [ ] PUT [ ] PATCH [ ] DELETE |
+| **Auth Required** | [ ] Yes [ ] No                                |
+| **Rate Limited**  | [ ] Yes [ ] No                                |
+
+### 2. Endpoints to Implement
+
+| Method | Path                     | Handler            | Description          |
+| ------ | ------------------------ | ------------------ | -------------------- |
+| GET    | `/api/v1/[resource]`     | `list[Resource]`   | List with pagination |
+| GET    | `/api/v1/[resource]/:id` | `get[Resource]`    | Get by ID            |
+| POST   | `/api/v1/[resource]`     | `create[Resource]` | Create new           |
+| PUT    | `/api/v1/[resource]/:id` | `update[Resource]` | Full update          |
+| PATCH  | `/api/v1/[resource]/:id` | `patch[Resource]`  | Partial update       |
+| DELETE | `/api/v1/[resource]/:id` | `delete[Resource]` | Soft/hard delete     |
+
+### 3. Files to Create/Modify
+
+| File                                        | Action | Purpose           |
+| ------------------------------------------- | ------ | ----------------- |
+| `src/routes/[resource].routes.ts`           | Create | Route definitions |
+| `src/controllers/[resource].controller.ts`  | Create | Request handlers  |
+| `src/services/[resource].service.ts`        | Create | Business logic    |
+| `src/repositories/[resource].repository.ts` | Create | Data access       |
+| `src/schemas/[resource].schema.ts`          | Create | Zod validation    |
+| `src/types/[resource].types.ts`             | Create | TypeScript types  |
+| `tests/[resource].test.ts`                  | Create | Unit tests        |
+| `tests/[resource].integration.test.ts`      | Create | Integration tests |
+
+### 4. Standard Implementation Steps
+
+#### Step 1: Define Types and Schemas
+
+**Objective**: Create TypeScript types and Zod validation schemas
+
+**Files**:
+
+- `src/types/[resource].types.ts`
+- `src/schemas/[resource].schema.ts`
+
+```typescript
+// types/[resource].types.ts
+export interface [Resource] {
+  id: string;
+  // Add fields
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface Create[Resource]Dto {
+  // Add fields
+}
+
+export interface Update[Resource]Dto {
+  // Add fields (all optional)
+}
+```
+
+```typescript
+// schemas/[resource].schema.ts
+import { z } from 'zod';
+
+export const create[Resource]Schema = z.object({
+  // Add validation rules
+});
+
+export const update[Resource]Schema = create[Resource]Schema.partial();
+
+export const [resource]ParamsSchema = z.object({
+  id: z.string().uuid(),
+});
+
+export const [resource]QuerySchema = z.object({
+  page: z.coerce.number().min(1).default(1),
+  limit: z.coerce.number().min(1).max(100).default(20),
+});
+```
+
+**Validation**: Types compile, schemas validate test data
+
+---
+
+#### Step 2: Create Repository
+
+**Objective**: Implement data access layer
+
+**Files**:
+
+- `src/repositories/[resource].repository.ts`
+
+```typescript
+export class [Resource]Repository {
+  constructor(private db: Database) {}
+
+  async findAll(options: PaginationOptions): Promise<[Resource][]> {
+    // Implementation
+  }
+
+  async findById(id: string): Promise<[Resource] | null> {
+    // Implementation
+  }
+
+  async create(data: Create[Resource]Dto): Promise<[Resource]> {
+    // Implementation
+  }
+
+  async update(id: string, data: Update[Resource]Dto): Promise<[Resource]> {
+    // Implementation
+  }
+
+  async delete(id: string): Promise<void> {
+    // Implementation
+  }
+}
+```
+
+**Validation**: Repository methods work with test database
+
+---
+
+#### Step 3: Create Service
+
+**Objective**: Implement business logic
+
+**Files**:
+
+- `src/services/[resource].service.ts`
+
+```typescript
+export class [Resource]Service {
+  constructor(private repository: [Resource]Repository) {}
+
+  async list(options: PaginationOptions): Promise<Paginated<[Resource]>> {
+    // Add business logic
+    return this.repository.findAll(options);
+  }
+
+  async get(id: string): Promise<[Resource]> {
+    const result = await this.repository.findById(id);
+    if (!result) throw new NotFoundError('[Resource] not found');
+    return result;
+  }
+
+  async create(data: Create[Resource]Dto): Promise<[Resource]> {
+    // Validate business rules
+    return this.repository.create(data);
+  }
+
+  async update(id: string, data: Update[Resource]Dto): Promise<[Resource]> {
+    await this.get(id); // Ensure exists
+    return this.repository.update(id, data);
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.get(id); // Ensure exists
+    return this.repository.delete(id);
+  }
+}
+```
+
+**Validation**: Service methods handle business rules correctly
+
+---
+
+#### Step 4: Create Controller
+
+**Objective**: Implement request handlers
+
+**Files**:
+
+- `src/controllers/[resource].controller.ts`
+
+```typescript
+export class [Resource]Controller {
+  constructor(private service: [Resource]Service) {}
+
+  list = async (req: Request, res: Response) => {
+    const query = [resource]QuerySchema.parse(req.query);
+    const result = await this.service.list(query);
+    res.json({ data: result.items, pagination: result.pagination });
+  };
+
+  get = async (req: Request, res: Response) => {
+    const { id } = [resource]ParamsSchema.parse(req.params);
+    const result = await this.service.get(id);
+    res.json({ data: result });
+  };
+
+  create = async (req: Request, res: Response) => {
+    const data = create[Resource]Schema.parse(req.body);
+    const result = await this.service.create(data);
+    res.status(201).json({ data: result });
+  };
+
+  update = async (req: Request, res: Response) => {
+    const { id } = [resource]ParamsSchema.parse(req.params);
+    const data = update[Resource]Schema.parse(req.body);
+    const result = await this.service.update(id, data);
+    res.json({ data: result });
+  };
+
+  delete = async (req: Request, res: Response) => {
+    const { id } = [resource]ParamsSchema.parse(req.params);
+    await this.service.delete(id);
+    res.status(204).send();
+  };
+}
+```
+
+**Validation**: Controller handles requests and responses correctly
+
+---
+
+#### Step 5: Create Routes
+
+**Objective**: Define route configuration
+
+**Files**:
+
+- `src/routes/[resource].routes.ts`
+
+```typescript
+import { Router } from 'express';
+
+export function create[Resource]Routes(controller: [Resource]Controller): Router {
+  const router = Router();
+
+  router.get('/', controller.list);
+  router.get('/:id', controller.get);
+  router.post('/', controller.create);
+  router.put('/:id', controller.update);
+  router.delete('/:id', controller.delete);
+
+  return router;
+}
+```
+
+**Validation**: Routes registered and accessible
+
+---
+
+#### Step 6: Write Tests
+
+**Objective**: Add unit and integration tests
+
+**Files**:
+
+- `tests/[resource].test.ts`
+- `tests/[resource].integration.test.ts`
+
+**Test scenarios**:
+
+- [ ] List returns paginated results
+- [ ] Get returns single resource
+- [ ] Get returns 404 for missing
+- [ ] Create validates input
+- [ ] Create returns 201 with resource
+- [ ] Update validates input
+- [ ] Update returns 404 for missing
+- [ ] Delete returns 204
+- [ ] Delete returns 404 for missing
+
+**Validation**: `pnpm test:quick` passes
+
+---
+
+### 5. Standard Dependencies
+
+| Dependency      | Purpose        | Status        |
+| --------------- | -------------- | ------------- |
+| Express/Fastify | HTTP framework | [ ] Available |
+| Zod             | Validation     | [ ] Available |
+| Database client | Data access    | [ ] Available |
+
+### 6. Standard Risks
+
+| Risk               | Mitigation                    |
+| ------------------ | ----------------------------- |
+| N+1 queries        | Use eager loading / joins     |
+| Missing validation | Zod schemas at boundary       |
+| Auth bypass        | Middleware on all routes      |
+| Rate limiting      | Apply rate limiter middleware |
+
+### 7. Rollback
+
+```bash
+# Revert all changes
+git revert HEAD
+
+# Or remove specific files
+rm -rf src/**/[resource]*
+rm -rf tests/**/[resource]*
+```
+
+---
+
+## Estimated Effort
+
+| Step            | Points | Confidence |
+| --------------- | ------ | ---------- |
+| Types & Schemas | 1      | High       |
+| Repository      | 2      | High       |
+| Service         | 2      | High       |
+| Controller      | 1      | High       |
+| Routes          | 1      | High       |
+| Tests           | 3      | Medium     |
+| **Total**       | **10** | **High**   |