@mind-fold/open-flow 0.1.17 → 0.2.2

package/dist/templates/markdown/structure/frontend/hook-guidelines.md.txt

@@ -0,0 +1,287 @@
+# Hook Guidelines
+
+> Query hooks, mutation hooks, and custom hooks patterns
+
+---
+
+## Query Hooks
+
+Use React Query for data fetching.
+
+### Basic Query Hook
+
+```typescript
+import { useQuery } from '@tanstack/react-query';
+import { api } from '@/lib/api-client';
+import type { User } from '@/types';
+
+export function useUser(userId: string) {
+  return useQuery({
+    queryKey: ['user', userId],
+    queryFn: () => api.users.get(userId),
+    enabled: !!userId,  // Don't fetch if no userId
+  });
+}
+
+// Usage
+function UserProfile({ userId }: { userId: string }) {
+  const { data: user, isLoading, error } = useUser(userId);
+  
+  if (isLoading) return <Spinner />;
+  if (error) return <Error message={error.message} />;
+  if (!user) return <NotFound />;
+  
+  return <div>{user.name}</div>;
+}
+```
+
+### List Query with Pagination
+
+```typescript
+export function useUsers(page: number, pageSize: number = 20) {
+  return useQuery({
+    queryKey: ['users', { page, pageSize }],
+    queryFn: () => api.users.list({ page, pageSize }),
+    placeholderData: keepPreviousData,  // Keep old data while fetching new
+  });
+}
+```
+
+### Query Key Rules
+
+```typescript
+// ✅ GOOD: Include all dependencies in query key
+queryKey: ['user', userId]
+queryKey: ['users', { page, pageSize, filter }]
+queryKey: ['posts', userId, 'comments']
+
+// ❌ BAD: Missing dependencies
+queryKey: ['user']  // Same key for different users!
+queryKey: ['users']  // Same key for different pages!
+```
+
+---
+
+## Mutation Hooks
+
+For create, update, delete operations.
+
+### Basic Mutation
+
+```typescript
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+
+export function useUpdateUser() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (data: { id: string; name: string }) => 
+      api.users.update(data.id, { name: data.name }),
+    
+    onSuccess: (updatedUser) => {
+      // Invalidate and refetch
+      queryClient.invalidateQueries({ queryKey: ['users'] });
+      queryClient.invalidateQueries({ queryKey: ['user', updatedUser.id] });
+    },
+  });
+}
+
+// Usage
+function EditUserForm({ user }: { user: User }) {
+  const updateUser = useUpdateUser();
+  
+  const handleSubmit = (data: FormData) => {
+    updateUser.mutate(
+      { id: user.id, name: data.name },
+      {
+        onSuccess: () => toast.success('User updated'),
+        onError: (error) => toast.error(error.message),
+      }
+    );
+  };
+  
+  return (
+    <form onSubmit={handleSubmit}>
+      {/* ... */}
+      <button disabled={updateUser.isPending}>
+        {updateUser.isPending ? 'Saving...' : 'Save'}
+      </button>
+    </form>
+  );
+}
+```
+
+### Optimistic Updates
+
+```typescript
+export function useToggleFavorite() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (postId: string) => api.posts.toggleFavorite(postId),
+    
+    // Optimistically update before server responds
+    onMutate: async (postId) => {
+      await queryClient.cancelQueries({ queryKey: ['posts'] });
+      
+      const previousPosts = queryClient.getQueryData(['posts']);
+      
+      queryClient.setQueryData(['posts'], (old: Post[]) =>
+        old.map(post =>
+          post.id === postId
+            ? { ...post, isFavorite: !post.isFavorite }
+            : post
+        )
+      );
+      
+      return { previousPosts };
+    },
+    
+    // Rollback on error
+    onError: (err, postId, context) => {
+      queryClient.setQueryData(['posts'], context?.previousPosts);
+    },
+    
+    // Always refetch after error or success
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: ['posts'] });
+    },
+  });
+}
+```
+
+---
+
+## Custom Hooks
+
+### State + Logic Encapsulation
+
+```typescript
+export function useToggle(initialValue = false) {
+  const [value, setValue] = useState(initialValue);
+  
+  const toggle = useCallback(() => setValue(v => !v), []);
+  const setTrue = useCallback(() => setValue(true), []);
+  const setFalse = useCallback(() => setValue(false), []);
+  
+  return { value, toggle, setTrue, setFalse };
+}
+
+// Usage
+function Dialog() {
+  const { value: isOpen, setTrue: open, setFalse: close } = useToggle();
+  
+  return (
+    <>
+      <button onClick={open}>Open</button>
+      {isOpen && <Modal onClose={close} />}
+    </>
+  );
+}
+```
+
+### Debounced Value
+
+```typescript
+export function useDebounce<T>(value: T, delay: number): T {
+  const [debouncedValue, setDebouncedValue] = useState(value);
+
+  useEffect(() => {
+    const timer = setTimeout(() => setDebouncedValue(value), delay);
+    return () => clearTimeout(timer);
+  }, [value, delay]);
+
+  return debouncedValue;
+}
+
+// Usage
+function SearchInput() {
+  const [query, setQuery] = useState('');
+  const debouncedQuery = useDebounce(query, 300);
+  
+  const { data } = useSearch(debouncedQuery);
+  
+  return <input value={query} onChange={e => setQuery(e.target.value)} />;
+}
+```
+
+### Local Storage
+
+```typescript
+export function useLocalStorage<T>(key: string, initialValue: T) {
+  const [storedValue, setStoredValue] = useState<T>(() => {
+    if (typeof window === 'undefined') return initialValue;
+    
+    try {
+      const item = window.localStorage.getItem(key);
+      return item ? JSON.parse(item) : initialValue;
+    } catch {
+      return initialValue;
+    }
+  });
+
+  const setValue = useCallback((value: T | ((val: T) => T)) => {
+    setStoredValue(prev => {
+      const valueToStore = value instanceof Function ? value(prev) : value;
+      window.localStorage.setItem(key, JSON.stringify(valueToStore));
+      return valueToStore;
+    });
+  }, [key]);
+
+  return [storedValue, setValue] as const;
+}
+```
+
+---
+
+## Best Practices
+
+### DO
+
+```typescript
+// Include all dependencies in query keys
+queryKey: ['user', userId, { includeDetails }]
+
+// Handle loading and error states
+if (isLoading) return <Spinner />;
+if (error) return <ErrorDisplay error={error} />;
+
+// Use enabled option for conditional fetching
+enabled: !!userId && isAuthenticated
+
+// Memoize callbacks in custom hooks
+const toggle = useCallback(() => setValue(v => !v), []);
+```
+
+### DON'T
+
+```typescript
+// Don't fetch in useEffect
+useEffect(() => {
+  fetch('/api/user').then(...)  // ❌ Use useQuery instead
+}, []);
+
+// Don't ignore error states
+const { data } = useUser(id);
+return <div>{data.name}</div>;  // ❌ data might be undefined
+
+// Don't mutate query data directly
+data.name = 'New Name';  // ❌ Use mutation
+```
+
+---
+
+## Hook Naming
+
+| Pattern | Name | Example |
+|---------|------|---------|
+| Query single | `use{Entity}` | `useUser` |
+| Query list | `use{Entity}s` | `useUsers` |
+| Mutation create | `useCreate{Entity}` | `useCreateUser` |
+| Mutation update | `useUpdate{Entity}` | `useUpdateUser` |
+| Mutation delete | `useDelete{Entity}` | `useDeleteUser` |
+| Custom utility | `use{Action}` | `useDebounce`, `useToggle` |
+
+---
+
+**Language**: All documentation must be written in **English**.

package/dist/templates/markdown/structure/frontend/index.md.txt

@@ -0,0 +1,91 @@
+# Frontend Development Guidelines
+
+> Best practices for frontend development with React
+
+---
+
+## Overview
+
+This collection of guidelines covers essential patterns and best practices for building robust frontend applications.
+
+---
+
+## Guidelines Index
+
+### Core Patterns
+
+| Guide | Description |
+|-------|-------------|
+| [Directory Structure](./directory-structure.md) | Module organization and file layout |
+| [Type Safety](./type-safety.md) | TypeScript patterns, type inference |
+| [Quality Guidelines](./quality-guidelines.md) | Forbidden patterns, code standards |
+
+### React Patterns
+
+| Guide | Description |
+|-------|-------------|
+| [Hook Guidelines](./hook-guidelines.md) | Query hooks, mutation hooks, custom hooks |
+| [Component Guidelines](./component-guidelines.md) | Component patterns, semantic HTML, accessibility |
+| [State Management](./state-management.md) | Local state, global state, server state |
+
+---
+
+## Quick Reference
+
+### Directory Structure
+
+```
+src/
+├── components/              # Shared components
+│   ├── ui/                  # Base UI components
+│   └── common/              # Common composite components
+│
+├── modules/                 # Feature modules
+│   └── {feature}/
+│       ├── components/      # Feature-specific components
+│       ├── hooks/           # Feature-specific hooks
+│       └── types.ts         # Feature types
+│
+├── hooks/                   # Shared hooks
+├── lib/                     # Utilities
+└── types/                   # Shared types
+```
+
+### Key Rules
+
+| Rule | Description |
+|------|-------------|
+| Import types from API | Don't redefine backend types |
+| Use semantic HTML | `<button>` not `<div role="button">` |
+| No `any` type | Use `unknown` + type guards |
+| No `!` assertions | Use null checks |
+
+---
+
+## Getting Started
+
+1. **New to this codebase?** Start with [Directory Structure](./directory-structure.md)
+2. **Writing hooks?** Read [Hook Guidelines](./hook-guidelines.md)
+3. **Building components?** Read [Component Guidelines](./component-guidelines.md)
+4. **Before commit?** Check [Quality Guidelines](./quality-guidelines.md)
+
+---
+
+## Common Tasks
+
+### Create a New Feature Module
+
+```bash
+mkdir -p src/modules/{feature}/{components,hooks}
+touch src/modules/{feature}/types.ts
+```
+
+See: [Directory Structure](./directory-structure.md)
+
+### Add a Data Fetching Hook
+
+See: [Hook Guidelines](./hook-guidelines.md) - Query Hooks section
+
+---
+
+**Language**: All documentation must be written in **English**.

package/dist/templates/markdown/structure/frontend/quality-guidelines.md.txt

@@ -0,0 +1,274 @@
+# Quality Guidelines
+
+> Code standards and forbidden patterns for frontend
+
+---
+
+## Before Every Commit
+
+Run these checks before committing:
+
+```bash
+# Must pass with 0 errors
+pnpm lint
+
+# Must pass with no type errors
+pnpm type-check
+
+# Run tests
+pnpm test
+```
+
+---
+
+## Forbidden Patterns
+
+### Any Type
+
+```typescript
+// ❌ FORBIDDEN
+function process(data: any) { ... }
+const result: any = await fetch(...);
+
+// ✅ REQUIRED
+function process(data: unknown) {
+  if (isValidData(data)) {
+    // Now data is typed
+  }
+}
+```
+
+### Non-Null Assertions
+
+```typescript
+// ❌ FORBIDDEN
+const name = user!.name;
+const element = document.querySelector('.item')!;
+
+// ✅ REQUIRED
+if (!user) return null;
+const name = user.name;
+
+const element = document.querySelector('.item');
+if (!element) return;
+```
+
+### Type Assertions Without Validation
+
+```typescript
+// ❌ FORBIDDEN
+const data = response as UserData;
+const config = JSON.parse(str) as Config;
+
+// ✅ REQUIRED
+const data = userDataSchema.parse(response);
+if (!isUserData(response)) throw new Error('Invalid data');
+```
+
+### Div Instead of Semantic HTML
+
+```typescript
+// ❌ FORBIDDEN
+<div role="button" onClick={handleClick}>Click</div>
+<div onClick={handleNavigate}>Go to page</div>
+
+// ✅ REQUIRED
+<button onClick={handleClick}>Click</button>
+<Link href="/page">Go to page</Link>
+```
+
+### Native img in Next.js
+
+```typescript
+// ❌ FORBIDDEN
+<img src="/photo.jpg" alt="Photo" />
+
+// ✅ REQUIRED
+import Image from 'next/image';
+<Image src="/photo.jpg" alt="Photo" width={200} height={200} />
+```
+
+### useEffect for Data Fetching
+
+```typescript
+// ❌ FORBIDDEN
+useEffect(() => {
+  fetch('/api/users')
+    .then(res => res.json())
+    .then(setUsers);
+}, []);
+
+// ✅ REQUIRED
+const { data: users } = useQuery({
+  queryKey: ['users'],
+  queryFn: () => api.users.list(),
+});
+```
+
+---
+
+## Required Patterns
+
+### Handle Loading States
+
+```typescript
+// ✅ REQUIRED: Handle all states
+function UserList() {
+  const { data, isLoading, error } = useUsers();
+  
+  if (isLoading) return <Skeleton />;
+  if (error) return <Error message={error.message} />;
+  if (!data?.length) return <Empty />;
+  
+  return <List items={data} />;
+}
+```
+
+### Accessible Forms
+
+```typescript
+// ✅ REQUIRED: Labels for all inputs
+<label htmlFor="email">Email</label>
+<input id="email" type="email" aria-describedby="email-error" />
+{error && <span id="email-error" role="alert">{error}</span>}
+```
+
+### Error Boundaries
+
+```typescript
+// ✅ REQUIRED: Wrap feature modules
+<ErrorBoundary fallback={<ErrorFallback />}>
+  <FeatureModule />
+</ErrorBoundary>
+```
+
+---
+
+## Code Style
+
+### Naming Conventions
+
+| Type | Convention | Example |
+|------|------------|---------|
+| Components | PascalCase | `UserCard`, `SubmitButton` |
+| Hooks | camelCase with `use` | `useUser`, `useToggle` |
+| Files | kebab-case | `user-card.tsx`, `use-user.ts` |
+| Types | PascalCase | `UserData`, `FormState` |
+| Constants | SCREAMING_SNAKE | `MAX_FILE_SIZE` |
+
+### Component File Structure
+
+```typescript
+// 1. Imports
+import { useState } from 'react';
+import { Button } from '@/components/ui';
+
+// 2. Types
+interface Props {
+  user: User;
+}
+
+// 3. Component
+export function UserCard({ user }: Props) {
+  // Hooks first
+  const [isOpen, setIsOpen] = useState(false);
+  
+  // Derived state
+  const displayName = user.nickname ?? user.name;
+  
+  // Event handlers
+  const handleClick = () => setIsOpen(true);
+  
+  // Render
+  return (
+    <article>
+      <h3>{displayName}</h3>
+      <Button onClick={handleClick}>View</Button>
+    </article>
+  );
+}
+```
+
+---
+
+## Performance
+
+### Memoization
+
+```typescript
+// ✅ Memoize expensive calculations
+const sortedItems = useMemo(
+  () => items.sort((a, b) => a.name.localeCompare(b.name)),
+  [items]
+);
+
+// ✅ Memoize callbacks passed to children
+const handleClick = useCallback(() => {
+  doSomething(id);
+}, [id]);
+
+// ❌ Don't memoize everything - only when needed
+const name = useMemo(() => user.name, [user.name]);  // Unnecessary
+```
+
+### Avoid Unnecessary Rerenders
+
+```typescript
+// ❌ BAD: Creates new object every render
+<Component style={{ color: 'red' }} />
+
+// ✅ GOOD: Stable reference
+const style = { color: 'red' };  // Outside component
+<Component style={style} />
+
+// ✅ GOOD: Or use className
+<Component className="text-red" />
+```
+
+---
+
+## Accessibility Checklist
+
+- [ ] All images have alt text
+- [ ] All inputs have labels
+- [ ] Interactive elements are focusable
+- [ ] Color is not the only indicator
+- [ ] Proper heading hierarchy
+- [ ] Keyboard navigation works
+
+---
+
+## Testing Requirements
+
+### What to Test
+
+- User interactions (click, type, submit)
+- Error states
+- Loading states
+- Edge cases (empty data, long text)
+
+### What NOT to Test
+
+- Implementation details
+- CSS styling
+- Third-party library internals
+
+---
+
+## Checklist
+
+Before submitting for review:
+
+- [ ] No TypeScript errors (`pnpm type-check`)
+- [ ] No lint errors (`pnpm lint`)
+- [ ] No `any` types
+- [ ] No `!` assertions
+- [ ] Semantic HTML used
+- [ ] Loading/error states handled
+- [ ] Images use Next.js Image
+- [ ] Tests pass
+- [ ] Accessibility basics covered
+
+---
+
+**Language**: All documentation must be written in **English**.