devflow-kit 1.8.2 → 2.0.0

package/src/assets/skills/react/references/error-handling.md

@@ -0,0 +1,179 @@
+# React — Error Handling Patterns
+
+Error boundaries, async error states, and Suspense integration.
+Sources in `references/sources.md`.
+
+---
+
+## Error Boundaries [1]
+
+Error boundaries are class components that catch render errors in their subtree. They
+cannot catch async errors (use state for those). [1]
+
+```tsx
+interface ErrorBoundaryState { hasError: boolean; error: Error | null; }
+
+class ErrorBoundary extends Component<
+  { children: React.ReactNode; fallback?: React.ReactNode },
+  ErrorBoundaryState
+> {
+  state: ErrorBoundaryState = { hasError: false, error: null };
+
+  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error: Error, info: ErrorInfo) {
+    // Log to error reporting service (Sentry, Datadog, etc.)
+    console.error('Error caught by boundary:', error, info);
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return this.props.fallback ?? <DefaultErrorFallback error={this.state.error} />;
+    }
+    return this.props.children;
+  }
+}
+```
+
+### Resettable Error Boundary
+
+Allow users to recover without a full page reload:
+
+```tsx
+class ResettableErrorBoundary extends Component<
+  {
+    children: React.ReactNode;
+    fallback?: (error: Error, reset: () => void) => React.ReactNode;
+    onError?: (error: Error, info: ErrorInfo) => void;
+  },
+  ErrorBoundaryState
+> {
+  state: ErrorBoundaryState = { hasError: false, error: null };
+
+  static getDerivedStateFromError(error: Error) { return { hasError: true, error }; }
+  componentDidCatch(error: Error, info: ErrorInfo) { this.props.onError?.(error, info); }
+  reset = () => this.setState({ hasError: false, error: null });
+
+  render() {
+    if (this.state.hasError && this.state.error) {
+      return this.props.fallback
+        ? this.props.fallback(this.state.error, this.reset)
+        : <div><h2>Something went wrong</h2><button onClick={this.reset}>Try again</button></div>;
+    }
+    return this.props.children;
+  }
+}
+```
+
+---
+
+## Scoped Error Boundaries [1]
+
+Isolate failures to feature boundaries — prevent one component's error from crashing
+the whole app:
+
+```tsx
+function App() {
+  return (
+    <div>
+      <Header />
+      <main>
+        <ErrorBoundary fallback={<SidebarError />}>
+          <Sidebar />
+        </ErrorBoundary>
+        <ErrorBoundary fallback={<ContentError />}>
+          <MainContent />
+        </ErrorBoundary>
+      </main>
+      <Footer />
+    </div>
+  );
+}
+```
+
+---
+
+## Async Error Handling [3][13]
+
+Error boundaries do not catch errors in async code. Use state to track async errors:
+
+```tsx
+function useAsync<T>(asyncFn: () => Promise<T>, deps: unknown[] = []) {
+  const [state, setState] = useState<{
+    data: T | null; error: Error | null; isLoading: boolean;
+  }>({ data: null, error: null, isLoading: false });
+
+  const execute = useCallback(async () => {
+    setState({ data: null, error: null, isLoading: true });
+    try {
+      const result = await asyncFn();
+      setState({ data: result, error: null, isLoading: false });
+    } catch (error) {
+      setState({ data: null, error: error as Error, isLoading: false });
+    }
+  }, deps);
+
+  return { ...state, execute };
+}
+
+// Usage
+function DataComponent() {
+  const { data, error, isLoading, execute } = useAsync(() => fetchData(), []);
+  useEffect(() => { execute(); }, [execute]);
+  if (isLoading) return <Spinner />;
+  if (error) return <ErrorMessage error={error} onRetry={execute} />;
+  return <DataDisplay data={data} />;
+}
+```
+
+---
+
+## Suspense Integration [1][7]
+
+`Suspense` handles loading states declaratively. Pair with error boundaries for complete
+async UI handling:
+
+```tsx
+function Dashboard() {
+  return (
+    <ErrorBoundary fallback={<DashboardError />}>
+      <Suspense fallback={<DashboardSkeleton />}>
+        <DashboardContent />  {/* can suspend during data fetch */}
+      </Suspense>
+    </ErrorBoundary>
+  );
+}
+```
+
+Server Components extend Suspense: a Server Component can `async/await` data directly;
+React streams the result to the client, showing the Suspense fallback until ready. [6][7]
+
+---
+
+## Error Fallback Components [1]
+
+```tsx
+function ErrorFallback({ error, onRetry }: { error: Error; onRetry?: () => void }) {
+  return (
+    <div role="alert" className="error-fallback">
+      <h2>Something went wrong</h2>
+      <pre>{error.message}</pre>
+      {onRetry && <button onClick={onRetry}>Try again</button>}
+    </div>
+  );
+}
+```
+
+---
+
+## Common Violations
+
+| Violation | Problem | Fix | Source |
+|-----------|---------|-----|--------|
+| No error boundary around risky components | One crash kills the full app | Wrap each feature in `<ErrorBoundary>` | [1] |
+| `.catch(() => {})` swallows error | User sees broken UI with no feedback | Set error state and display message | [3] |
+| Only success state rendered | No loading spinner or error path | Handle `isLoading` + `error` explicitly | [13] |
+| Error state not cleared on retry | Old error persists after successful retry | Clear error at start of each async call | [3] |
+| Async errors inside error boundary | Error boundary only catches render errors | Use state-based error handling for async | [1][3] |

package/src/assets/skills/react/references/forms.md

@@ -0,0 +1,214 @@
+# React — Form Patterns
+
+Extended form handling patterns with citations. Reference from main SKILL.md.
+Sources in `references/sources.md`.
+
+---
+
+## Controlled vs Uncontrolled [1]
+
+**Controlled**: React state is the single source of truth. Every keystroke updates state.
+Gives full control for validation and conditional logic.
+
+**Uncontrolled**: DOM manages value; use `ref` to read on submit. Simpler for basic forms
+and native browser behavior (file inputs must be uncontrolled). [1]
+
+```tsx
+// VIOLATION: Switching from uncontrolled to controlled mid-lifecycle
+function SearchInput() {
+  const [value, setValue] = useState<string>();  // undefined initially
+  return <input value={value} onChange={(e) => setValue(e.target.value)} />;
+  // BAD: undefined -> string switch causes React warning
+}
+
+// CORRECT: Controlled — initialize with empty string
+function SearchInput() {
+  const [value, setValue] = useState('');  // always a string
+  return <input value={value} onChange={(e) => setValue(e.target.value)} />;
+}
+
+// CORRECT: Uncontrolled with FormData for simple submit-only forms
+function UncontrolledForm({ onSubmit }: { onSubmit: (data: FormData) => void }) {
+  const formRef = useRef<HTMLFormElement>(null);
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    if (formRef.current) onSubmit(new FormData(formRef.current));
+  };
+  return (
+    <form ref={formRef} onSubmit={handleSubmit}>
+      <input name="email" type="email" required />
+      <input name="password" type="password" required />
+      <button type="submit">Submit</button>
+    </form>
+  );
+}
+```
+
+---
+
+## Controlled Form with Validation [1][21][22]
+
+Accessible forms require labels, error announcements, and `aria-invalid`. [21][22]
+
+```tsx
+function LoginForm({ onSubmit }: { onSubmit: (data: FormData) => void }) {
+  const [formData, setFormData] = useState({ email: '', password: '' });
+  const [errors, setErrors] = useState<Partial<typeof formData>>({});
+
+  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const { name, value } = e.target;
+    setFormData((prev) => ({ ...prev, [name]: value }));
+    setErrors((prev) => ({ ...prev, [name]: '' }));  // clear on change
+  };
+
+  const validate = (): boolean => {
+    const newErrors: Partial<typeof formData> = {};
+    if (!formData.email) newErrors.email = 'Email required';
+    if (!formData.password) newErrors.password = 'Password required';
+    setErrors(newErrors);
+    return Object.keys(newErrors).length === 0;
+  };
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    if (validate()) onSubmit(formData);
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <label htmlFor="email">Email</label>
+      <input
+        id="email" name="email" type="email"
+        value={formData.email} onChange={handleChange}
+        aria-invalid={!!errors.email} aria-describedby="email-error"
+      />
+      {errors.email && <span id="email-error" role="alert">{errors.email}</span>}
+
+      <label htmlFor="password">Password</label>
+      <input
+        id="password" name="password" type="password"
+        value={formData.password} onChange={handleChange}
+        aria-invalid={!!errors.password} aria-describedby="password-error"
+      />
+      {errors.password && <span id="password-error" role="alert">{errors.password}</span>}
+
+      <button type="submit">Login</button>
+    </form>
+  );
+}
+```
+
+---
+
+## Reusable Form Hook [14][1]
+
+Extract form logic into a custom hook to avoid repetition across form components. [14]
+
+```tsx
+interface UseFormOptions<T> {
+  initialValues: T;
+  validate: (values: T) => Partial<Record<keyof T, string>>;
+  onSubmit: (values: T) => void | Promise<void>;
+}
+
+function useForm<T extends Record<string, unknown>>({
+  initialValues, validate, onSubmit,
+}: UseFormOptions<T>) {
+  const [values, setValues] = useState(initialValues);
+  const [errors, setErrors] = useState<Partial<Record<keyof T, string>>>({});
+  const [touched, setTouched] = useState<Partial<Record<keyof T, boolean>>>({});
+  const [isSubmitting, setIsSubmitting] = useState(false);
+
+  const handleChange = (name: keyof T) => (e: React.ChangeEvent<HTMLInputElement>) => {
+    setValues((prev) => ({ ...prev, [name]: e.target.value }));
+    if (errors[name]) setErrors((prev) => ({ ...prev, [name]: undefined }));
+  };
+
+  const handleBlur = (name: keyof T) => () => {
+    setTouched((prev) => ({ ...prev, [name]: true }));
+    const fieldErrors = validate(values);
+    if (fieldErrors[name]) setErrors((prev) => ({ ...prev, [name]: fieldErrors[name] }));
+  };
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    const validationErrors = validate(values);
+    setErrors(validationErrors);
+    setTouched(Object.keys(values).reduce((acc, key) => ({ ...acc, [key]: true }), {}));
+    if (Object.keys(validationErrors).length === 0) {
+      setIsSubmitting(true);
+      try { await onSubmit(values); } finally { setIsSubmitting(false); }
+    }
+  };
+
+  const reset = () => { setValues(initialValues); setErrors({}); setTouched({}); };
+  return { values, errors, touched, isSubmitting, handleChange, handleBlur, handleSubmit, reset };
+}
+```
+
+---
+
+## Multi-Step Form [1]
+
+```tsx
+function MultiStepForm() {
+  const [step, setStep] = useState(0);
+  const [data, setData] = useState<FormData>({ name: '', email: '', address: '' });
+  const updateData = (updates: Partial<FormData>) =>
+    setData((prev) => ({ ...prev, ...updates }));
+  const next = () => setStep((s) => Math.min(s + 1, steps.length - 1));
+  const prev = () => setStep((s) => Math.max(s - 1, 0));
+
+  const steps = [
+    <PersonalInfo {...{ next, prev, data, updateData }} />,
+    <AddressInfo {...{ next, prev, data, updateData }} />,
+    <Confirmation {...{ next, prev, data, updateData }} />,
+  ];
+
+  return (
+    <div>
+      <StepIndicator current={step} total={steps.length} />
+      {steps[step]}
+    </div>
+  );
+}
+```
+
+---
+
+## Server Actions (React 19+) [1][7][10]
+
+Server Actions allow form submission to invoke server-side functions directly,
+eliminating the need for API route boilerplate. [7][10]
+
+```tsx
+// Server Component with Server Action
+async function createTodo(formData: FormData) {
+  'use server';
+  const title = formData.get('title') as string;
+  await db.todos.create({ title });
+  revalidatePath('/todos');
+}
+
+export default function NewTodoForm() {
+  return (
+    <form action={createTodo}>
+      <input name="title" type="text" required />
+      <button type="submit">Add Todo</button>
+    </form>
+  );
+}
+```
+
+---
+
+## Common Form Violations
+
+| Violation | Problem | Fix | Source |
+|-----------|---------|-----|--------|
+| `useState<string>()` for input value | undefined→string switch causes warning | Always initialize with `''` | [1] |
+| No labels on inputs | Screen readers can't identify fields | Use `<label htmlFor>` + `id` pair | [21][22] |
+| Error displayed without `role="alert"` | Screen readers miss error announcements | Add `role="alert"` to error elements | [21] |
+| No `aria-invalid` on errored input | Assistive tech can't identify invalid state | Set `aria-invalid={!!error}` | [22] |
+| Not resetting form after successful submit | Stale values confuse users | Call `reset()` or clear state | [1] |
+| Validation only on submit | Late feedback hurts UX | Validate on blur for touched fields | [1] |

package/src/assets/skills/react/references/hooks.md

@@ -0,0 +1,193 @@
+# React — Hook Patterns
+
+Extended hook patterns with citations. Reference from main SKILL.md.
+Sources in `references/sources.md`.
+
+---
+
+## Rules of Hooks [16][24]
+
+All hooks must be called at the **top level** of a function component or custom hook —
+never inside loops, conditionals, or nested functions. React relies on call order
+to associate hook state with the right component. [16]
+
+```tsx
+// VIOLATION: Conditional hook — breaks hook order
+function UserProfile({ user }: { user: User | null }) {
+  if (!user) return <LoginPrompt />;  // BAD: hook called after conditional return
+  const [isEditing, setIsEditing] = useState(false);
+  return <ProfileEditor user={user} isEditing={isEditing} />;
+}
+
+// CORRECT: Hook before conditional
+function UserProfile({ user }: { user: User | null }) {
+  const [isEditing, setIsEditing] = useState(false);
+  if (!user) return <LoginPrompt />;
+  return <ProfileEditor user={user} isEditing={isEditing} />;
+}
+```
+
+---
+
+## Custom Hooks — Extract Reusable Logic [1][16]
+
+Custom hooks encapsulate stateful logic without touching component tree structure.
+"A custom hook is just a function that uses other hooks." [1]
+
+```tsx
+// CORRECT: Reusable localStorage hook
+function useLocalStorage<T>(key: string, initialValue: T) {
+  const [value, setValue] = useState<T>(() => {
+    const stored = localStorage.getItem(key);
+    return stored ? JSON.parse(stored) : initialValue;
+  });
+  useEffect(() => localStorage.setItem(key, JSON.stringify(value)), [key, value]);
+  return [value, setValue] as const;
+}
+
+// CORRECT: Data fetching hook with loading/error states
+interface UseQueryResult<T> {
+  data: T | undefined;
+  isLoading: boolean;
+  error: Error | undefined;
+  refetch: () => void;
+}
+
+function useQuery<T>(url: string): UseQueryResult<T> {
+  const [data, setData] = useState<T>();
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error>();
+
+  const fetchData = useCallback(async () => {
+    setIsLoading(true);
+    setError(undefined);
+    try {
+      const response = await fetch(url);
+      if (!response.ok) throw new Error('Failed to fetch');
+      setData(await response.json());
+    } catch (e) {
+      setError(e as Error);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [url]);
+
+  useEffect(() => { fetchData(); }, [fetchData]);
+  return { data, isLoading, error, refetch: fetchData };
+}
+```
+
+---
+
+## useEffect — Synchronization, Not Lifecycle [3][13]
+
+Effects synchronize your component with an external system. They are not lifecycle
+methods. "Every time your component renders, React will clean up the effect from
+the last render and run the new effect." [3]
+
+```tsx
+// CORRECT: Effect with cleanup — always return cleanup function [3]
+function WindowSize() {
+  const [size, setSize] = useState({ width: 0, height: 0 });
+  useEffect(() => {
+    const handleResize = () =>
+      setSize({ width: window.innerWidth, height: window.innerHeight });
+    window.addEventListener('resize', handleResize);
+    return () => window.removeEventListener('resize', handleResize); // cleanup
+  }, []);
+  return <span>{size.width} x {size.height}</span>;
+}
+
+// CORRECT: Extract primitive deps to avoid object churn [3]
+function UserOrders({ user }: { user: User }) {
+  const userId = user.id;          // primitive
+  const isActive = user.status === 'active';  // primitive
+  useEffect(() => {
+    if (isActive) fetchOrders(userId);
+  }, [userId, isActive]);  // stable — no new refs
+}
+```
+
+### Effect Anti-Patterns to Avoid [13]
+
+| Anti-Pattern | Correct Approach | Source |
+|-------------|-----------------|--------|
+| Derived state computed in effect | Compute during render with `useMemo` | [13] |
+| Event handler logic in effect | Move to event handler directly | [13] |
+| Missing dependency in `[]` | Include all dependencies; use `useCallback` to stabilize | [3] |
+| Object/array literal in deps | Extract primitives or memoize the reference | [3] |
+| No cleanup for subscriptions | Always return cleanup from `useEffect` | [3] |
+
+---
+
+## useReducer — Complex State Machines [14]
+
+When state transitions involve multiple sub-values or the next state depends on the
+previous, `useReducer` is more predictable than `useState`. [14]
+
+```tsx
+type FormAction =
+  | { type: 'SET_VALUE'; field: string; value: string }
+  | { type: 'SUBMIT_START' }
+  | { type: 'SUBMIT_END' }
+  | { type: 'RESET' };
+
+function formReducer(state: FormState, action: FormAction): FormState {
+  switch (action.type) {
+    case 'SET_VALUE':
+      return { ...state, values: { ...state.values, [action.field]: action.value } };
+    case 'SUBMIT_START': return { ...state, isSubmitting: true };
+    case 'SUBMIT_END':   return { ...state, isSubmitting: false };
+    case 'RESET':        return initialFormState;
+    default:             return state;
+  }
+}
+```
+
+---
+
+## Utility Hooks [11][16]
+
+```tsx
+// Debounce rapid value changes
+function useDebouncedValue<T>(value: T, delayMs: number): T {
+  const [debounced, setDebounced] = useState(value);
+  useEffect(() => {
+    const timer = setTimeout(() => setDebounced(value), delayMs);
+    return () => clearTimeout(timer);
+  }, [value, delayMs]);
+  return debounced;
+}
+
+// Track previous value for comparisons
+function usePrevious<T>(value: T): T | undefined {
+  const ref = useRef<T | undefined>(undefined);
+  useEffect(() => { ref.current = value; }, [value]);
+  return ref.current;
+}
+
+// Detect clicks outside an element
+function useClickOutside<T extends HTMLElement>(callback: () => void): React.RefObject<T> {
+  const ref = useRef<T>(null);
+  useEffect(() => {
+    const handleClick = (event: MouseEvent) => {
+      if (ref.current && !ref.current.contains(event.target as Node)) callback();
+    };
+    document.addEventListener('mousedown', handleClick);
+    return () => document.removeEventListener('mousedown', handleClick);
+  }, [callback]);
+  return ref;
+}
+
+// Responsive logic
+function useMediaQuery(query: string): boolean {
+  const [matches, setMatches] = useState(() => window.matchMedia(query).matches);
+  useEffect(() => {
+    const mq = window.matchMedia(query);
+    const handler = (e: MediaQueryListEvent) => setMatches(e.matches);
+    mq.addEventListener('change', handler);
+    return () => mq.removeEventListener('change', handler);
+  }, [query]);
+  return matches;
+}
+```