omgkit 2.2.0 → 2.3.1

package/plugin/skills/frontend/frontend-design/SKILL.md

@@ -1,1325 +1,132 @@
 ---
-name: frontend-design
-description: Frontend design patterns with compound components, render props, custom hooks, state machines, and scalable architecture
-category: frontend
-triggers:
-  - frontend design
-  - component patterns
-  - design patterns
-  - compound components
-  - render props
-  - custom hooks
-  - state management
-  - component architecture
+name: designing-frontend-patterns
+description: Claude designs scalable React component architectures using compound components, custom hooks, and state machines. Use when building reusable UI systems or complex component APIs.
 ---
 
-# Frontend Design Patterns
+# Designing Frontend Patterns
 
-Enterprise-grade **frontend design patterns** following industry best practices. This skill covers compound components, render props, custom hooks, state machines, higher-order components, and scalable architecture patterns used by top engineering teams.
-
-## Purpose
-
-Build maintainable and scalable frontend applications:
-
-- Design reusable component APIs with compound patterns
-- Implement flexible data fetching with render props
-- Create powerful custom hooks for shared logic
-- Manage complex state with state machines
-- Build accessible form systems
-- Implement optimistic UI updates
-- Design scalable component architecture
-
-## Features
-
-### 1. Compound Components Pattern
+## Quick Start
 
 ```tsx
-// components/Select/SelectContext.tsx
-import { createContext, useContext, useState, useCallback, ReactNode } from 'react';
-
-interface SelectContextValue {
-  isOpen: boolean;
-  selectedValue: string | null;
-  selectedLabel: string | null;
-  highlightedIndex: number;
-  open: () => void;
-  close: () => void;
-  toggle: () => void;
-  selectOption: (value: string, label: string) => void;
-  setHighlightedIndex: (index: number) => void;
-}
-
+// Compound component pattern with context
 const SelectContext = createContext<SelectContextValue | null>(null);
 
-function useSelectContext() {
-  const context = useContext(SelectContext);
-  if (!context) {
-    throw new Error('Select components must be used within a Select provider');
-  }
-  return context;
-}
-
-// components/Select/Select.tsx
-interface SelectProps {
-  children: ReactNode;
-  defaultValue?: string;
-  value?: string;
-  onValueChange?: (value: string) => void;
-  disabled?: boolean;
-}
-
-export function Select({
-  children,
-  defaultValue,
-  value: controlledValue,
-  onValueChange,
-  disabled = false,
-}: SelectProps) {
+export function Select({ children, value, onValueChange }: SelectProps) {
   const [isOpen, setIsOpen] = useState(false);
-  const [internalValue, setInternalValue] = useState(defaultValue ?? null);
-  const [selectedLabel, setSelectedLabel] = useState<string | null>(null);
-  const [highlightedIndex, setHighlightedIndex] = useState(-1);
-
-  const isControlled = controlledValue !== undefined;
-  const selectedValue = isControlled ? controlledValue : internalValue;
-
-  const open = useCallback(() => {
-    if (!disabled) setIsOpen(true);
-  }, [disabled]);
-
-  const close = useCallback(() => {
-    setIsOpen(false);
-    setHighlightedIndex(-1);
-  }, []);
-
-  const toggle = useCallback(() => {
-    if (!disabled) setIsOpen((prev) => !prev);
-  }, [disabled]);
-
-  const selectOption = useCallback(
-    (value: string, label: string) => {
-      if (!isControlled) {
-        setInternalValue(value);
-      }
-      setSelectedLabel(label);
-      onValueChange?.(value);
-      close();
-    },
-    [isControlled, onValueChange, close]
-  );
-
   return (
-    <SelectContext.Provider
-      value={{
-        isOpen,
-        selectedValue,
-        selectedLabel,
-        highlightedIndex,
-        open,
-        close,
-        toggle,
-        selectOption,
-        setHighlightedIndex,
-      }}
-    >
-      <div className="relative inline-block" data-disabled={disabled}>
-        {children}
-      </div>
+    <SelectContext.Provider value={{ isOpen, setIsOpen, value, onValueChange }}>
+      <div className="relative">{children}</div>
     </SelectContext.Provider>
   );
 }
 
-// components/Select/SelectTrigger.tsx
-interface SelectTriggerProps {
-  children?: ReactNode;
-  placeholder?: string;
-  className?: string;
-}
-
-export function SelectTrigger({
-  children,
-  placeholder = 'Select an option',
-  className = '',
-}: SelectTriggerProps) {
-  const { isOpen, selectedLabel, toggle } = useSelectContext();
-
-  return (
-    <button
-      type="button"
-      role="combobox"
-      aria-expanded={isOpen}
-      aria-haspopup="listbox"
-      className={`flex items-center justify-between gap-2 px-3 py-2 border rounded-md
-        bg-white hover:bg-gray-50 focus:outline-none focus:ring-2 focus:ring-blue-500
-        ${className}`}
-      onClick={toggle}
-    >
-      <span className={selectedLabel ? 'text-gray-900' : 'text-gray-500'}>
-        {selectedLabel || children || placeholder}
-      </span>
-      <ChevronIcon isOpen={isOpen} />
-    </button>
-  );
-}
-
-// components/Select/SelectContent.tsx
-interface SelectContentProps {
-  children: ReactNode;
-  className?: string;
-}
-
-export function SelectContent({ children, className = '' }: SelectContentProps) {
-  const { isOpen, close } = useSelectContext();
-  const contentRef = useRef<HTMLDivElement>(null);
-
-  // Close on outside click
-  useEffect(() => {
-    const handleClickOutside = (event: MouseEvent) => {
-      if (contentRef.current && !contentRef.current.contains(event.target as Node)) {
-        close();
-      }
-    };
-
-    if (isOpen) {
-      document.addEventListener('mousedown', handleClickOutside);
-      return () => document.removeEventListener('mousedown', handleClickOutside);
-    }
-  }, [isOpen, close]);
-
-  // Close on escape
-  useEffect(() => {
-    const handleEscape = (event: KeyboardEvent) => {
-      if (event.key === 'Escape') close();
-    };
-
-    if (isOpen) {
-      document.addEventListener('keydown', handleEscape);
-      return () => document.removeEventListener('keydown', handleEscape);
-    }
-  }, [isOpen, close]);
-
-  if (!isOpen) return null;
-
-  return (
-    <div
-      ref={contentRef}
-      role="listbox"
-      className={`absolute z-50 mt-1 w-full bg-white border rounded-md shadow-lg
-        max-h-60 overflow-auto ${className}`}
-    >
-      {children}
-    </div>
-  );
-}
-
-// components/Select/SelectItem.tsx
-interface SelectItemProps {
-  value: string;
-  children: ReactNode;
-  disabled?: boolean;
-}
-
-export function SelectItem({ value, children, disabled = false }: SelectItemProps) {
-  const { selectedValue, selectOption } = useSelectContext();
-  const isSelected = selectedValue === value;
-
-  const handleSelect = () => {
-    if (!disabled) {
-      selectOption(value, typeof children === 'string' ? children : value);
-    }
-  };
-
-  return (
-    <div
-      role="option"
-      aria-selected={isSelected}
-      aria-disabled={disabled}
-      className={`px-3 py-2 cursor-pointer
-        ${isSelected ? 'bg-blue-100 text-blue-900' : 'text-gray-900'}
-        ${disabled ? 'opacity-50 cursor-not-allowed' : 'hover:bg-gray-100'}
-      `}
-      onClick={handleSelect}
-    >
-      {children}
-    </div>
-  );
-}
-
-// Usage example
-function SelectExample() {
-  const [country, setCountry] = useState('');
-
-  return (
-    <Select value={country} onValueChange={setCountry}>
-      <SelectTrigger placeholder="Select a country" />
-      <SelectContent>
-        <SelectItem value="us">United States</SelectItem>
-        <SelectItem value="uk">United Kingdom</SelectItem>
-        <SelectItem value="ca">Canada</SelectItem>
-        <SelectItem value="au" disabled>Australia (Coming Soon)</SelectItem>
-      </SelectContent>
-    </Select>
-  );
-}
+Select.Trigger = SelectTrigger;
+Select.Content = SelectContent;
+Select.Item = SelectItem;
 ```
 
-### 2. Render Props Pattern
-
-```tsx
-// components/DataFetcher.tsx
-import { useState, useEffect, useCallback, ReactNode } from 'react';
-
-interface FetchState<T> {
-  data: T | null;
-  loading: boolean;
-  error: Error | null;
-  refetch: () => Promise<void>;
-}
-
-interface DataFetcherProps<T> {
-  url: string;
-  options?: RequestInit;
-  children: (state: FetchState<T>) => ReactNode;
-  onSuccess?: (data: T) => void;
-  onError?: (error: Error) => void;
-  initialData?: T;
-  enabled?: boolean;
-}
-
-export function DataFetcher<T>({
-  url,
-  options,
-  children,
-  onSuccess,
-  onError,
-  initialData = null as T,
-  enabled = true,
-}: DataFetcherProps<T>) {
-  const [data, setData] = useState<T | null>(initialData);
-  const [loading, setLoading] = useState(false);
-  const [error, setError] = useState<Error | null>(null);
-
-  const fetchData = useCallback(async () => {
-    if (!enabled) return;
-
-    setLoading(true);
-    setError(null);
-
-    try {
-      const response = await fetch(url, {
-        ...options,
-        headers: {
-          'Content-Type': 'application/json',
-          ...options?.headers,
-        },
-      });
-
-      if (!response.ok) {
-        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
-      }
-
-      const result = await response.json();
-      setData(result);
-      onSuccess?.(result);
-    } catch (err) {
-      const error = err instanceof Error ? err : new Error(String(err));
-      setError(error);
-      onError?.(error);
-    } finally {
-      setLoading(false);
-    }
-  }, [url, options, enabled, onSuccess, onError]);
-
-  useEffect(() => {
-    fetchData();
-  }, [fetchData]);
-
-  return <>{children({ data, loading, error, refetch: fetchData })}</>;
-}
-
-// Mouse position render props
-interface MousePosition {
-  x: number;
-  y: number;
-}
-
-interface MouseTrackerProps {
-  children: (position: MousePosition) => ReactNode;
-}
-
-export function MouseTracker({ children }: MouseTrackerProps) {
-  const [position, setPosition] = useState<MousePosition>({ x: 0, y: 0 });
-
-  useEffect(() => {
-    const handleMouseMove = (event: MouseEvent) => {
-      setPosition({ x: event.clientX, y: event.clientY });
-    };
-
-    window.addEventListener('mousemove', handleMouseMove);
-    return () => window.removeEventListener('mousemove', handleMouseMove);
-  }, []);
-
-  return <>{children(position)}</>;
-}
-
-// Intersection observer render props
-interface IntersectionProps {
-  children: (entry: IntersectionObserverEntry | null, ref: React.RefObject<Element>) => ReactNode;
-  options?: IntersectionObserverInit;
-}
-
-export function IntersectionObserverRender({ children, options }: IntersectionProps) {
-  const [entry, setEntry] = useState<IntersectionObserverEntry | null>(null);
-  const ref = useRef<Element>(null);
-
-  useEffect(() => {
-    const element = ref.current;
-    if (!element) return;
-
-    const observer = new IntersectionObserver(([entry]) => {
-      setEntry(entry);
-    }, options);
-
-    observer.observe(element);
-    return () => observer.disconnect();
-  }, [options]);
-
-  return <>{children(entry, ref)}</>;
-}
+## Features
 
-// Usage examples
-function RenderPropsExamples() {
-  return (
-    <>
-      {/* Data fetcher */}
-      <DataFetcher<User[]> url="/api/users">
-        {({ data, loading, error, refetch }) => {
-          if (loading) return <Spinner />;
-          if (error) return <ErrorMessage error={error} onRetry={refetch} />;
-          return <UserList users={data || []} />;
-        }}
-      </DataFetcher>
+| Feature | Description | Guide |
+|---------|-------------|-------|
+| Compound Components | Shared state via context for flexible component APIs | `ref/compound-components.md` |
+| Custom Hooks | Encapsulate reusable logic (useDebounce, useLocalStorage) | `ref/custom-hooks.md` |
+| Render Props | Maximum flexibility for data fetching and rendering | `ref/render-props.md` |
+| State Machines | Predictable state transitions for complex flows | `ref/state-machines.md` |
+| HOCs | Cross-cutting concerns (auth, error boundaries) | `ref/higher-order-components.md` |
+| Optimistic UI | Instant feedback with rollback on failure | `ref/optimistic-updates.md` |
 
-      {/* Mouse tracker */}
-      <MouseTracker>
-        {({ x, y }) => (
-          <div className="fixed pointer-events-none" style={{ left: x, top: y }}>
-            Custom cursor at ({x}, {y})
-          </div>
-        )}
-      </MouseTracker>
+## Common Patterns
 
-      {/* Lazy loading with intersection observer */}
-      <IntersectionObserverRender options={{ threshold: 0.1 }}>
-        {(entry, ref) => (
-          <div ref={ref as React.RefObject<HTMLDivElement>}>
-            {entry?.isIntersecting ? <HeavyComponent /> : <Placeholder />}
-          </div>
-        )}
-      </IntersectionObserverRender>
-    </>
-  );
-}
-```
-
-### 3. Custom Hooks Pattern
+### Custom Hook with Cleanup
 
 ```tsx
-// hooks/useLocalStorage.ts
-import { useState, useEffect, useCallback } from 'react';
-
-export function useLocalStorage<T>(
-  key: string,
-  initialValue: T
-): [T, (value: T | ((prev: T) => T)) => void, () => void] {
-  // Get initial value from localStorage or use provided initial
-  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 (error) {
-      console.warn(`Error reading localStorage key "${key}":`, error);
-      return initialValue;
-    }
-  });
-
-  // Persist to localStorage when value changes
-  useEffect(() => {
-    if (typeof window === 'undefined') return;
-
-    try {
-      window.localStorage.setItem(key, JSON.stringify(storedValue));
-    } catch (error) {
-      console.warn(`Error setting localStorage key "${key}":`, error);
-    }
-  }, [key, storedValue]);
-
-  // Listen for changes in other tabs/windows
-  useEffect(() => {
-    const handleStorageChange = (event: StorageEvent) => {
-      if (event.key === key && event.newValue) {
-        try {
-          setStoredValue(JSON.parse(event.newValue));
-        } catch {
-          // Ignore parse errors
-        }
-      }
-    };
-
-    window.addEventListener('storage', handleStorageChange);
-    return () => window.removeEventListener('storage', handleStorageChange);
-  }, [key]);
-
-  const remove = useCallback(() => {
-    if (typeof window !== 'undefined') {
-      window.localStorage.removeItem(key);
-      setStoredValue(initialValue);
-    }
-  }, [key, initialValue]);
-
-  return [storedValue, setStoredValue, remove];
-}
-
-// hooks/useDebounce.ts
 export function useDebounce<T>(value: T, delay: number): T {
   const [debouncedValue, setDebouncedValue] = useState(value);
 
   useEffect(() => {
-    const timer = setTimeout(() => {
-      setDebouncedValue(value);
-    }, delay);
-
+    const timer = setTimeout(() => setDebouncedValue(value), delay);
     return () => clearTimeout(timer);
   }, [value, delay]);
 
   return debouncedValue;
 }
 
-// hooks/useDebouncedCallback.ts
-export function useDebouncedCallback<T extends (...args: any[]) => any>(
-  callback: T,
-  delay: number
-): (...args: Parameters<T>) => void {
-  const timeoutRef = useRef<NodeJS.Timeout | null>(null);
-  const callbackRef = useRef(callback);
-
-  // Keep callback ref updated
-  useEffect(() => {
-    callbackRef.current = callback;
-  }, [callback]);
-
-  // Cleanup on unmount
-  useEffect(() => {
-    return () => {
-      if (timeoutRef.current) clearTimeout(timeoutRef.current);
-    };
-  }, []);
-
-  return useCallback(
-    (...args: Parameters<T>) => {
-      if (timeoutRef.current) clearTimeout(timeoutRef.current);
-
-      timeoutRef.current = setTimeout(() => {
-        callbackRef.current(...args);
-      }, delay);
-    },
-    [delay]
-  );
-}
-
-// hooks/useAsync.ts
-interface AsyncState<T> {
-  data: T | null;
-  loading: boolean;
-  error: Error | null;
-}
-
-interface UseAsyncReturn<T> extends AsyncState<T> {
-  execute: () => Promise<T | null>;
-  reset: () => void;
-}
-
-export function useAsync<T>(
-  asyncFunction: () => Promise<T>,
-  immediate = true
-): UseAsyncReturn<T> {
-  const [state, setState] = useState<AsyncState<T>>({
-    data: null,
-    loading: immediate,
-    error: null,
-  });
-
-  const execute = useCallback(async () => {
-    setState((prev) => ({ ...prev, loading: true, error: null }));
-
+export function useLocalStorage<T>(key: string, initialValue: T) {
+  const [stored, setStored] = useState<T>(() => {
     try {
-      const data = await asyncFunction();
-      setState({ data, loading: false, error: null });
-      return data;
-    } catch (error) {
-      setState({
-        data: null,
-        loading: false,
-        error: error instanceof Error ? error : new Error(String(error)),
-      });
-      return null;
-    }
-  }, [asyncFunction]);
-
-  const reset = useCallback(() => {
-    setState({ data: null, loading: false, error: null });
-  }, []);
-
-  useEffect(() => {
-    if (immediate) {
-      execute();
-    }
-  }, [execute, immediate]);
-
-  return { ...state, execute, reset };
-}
-
-// hooks/useMediaQuery.ts
-export function useMediaQuery(query: string): boolean {
-  const [matches, setMatches] = useState(() => {
-    if (typeof window === 'undefined') return false;
-    return window.matchMedia(query).matches;
+      const item = window.localStorage.getItem(key);
+      return item ? JSON.parse(item) : initialValue;
+    } catch { return initialValue; }
   });
 
   useEffect(() => {
-    const mediaQuery = window.matchMedia(query);
-    const handler = (event: MediaQueryListEvent) => setMatches(event.matches);
-
-    // Set initial value
-    setMatches(mediaQuery.matches);
-
-    // Modern browsers
-    mediaQuery.addEventListener('change', handler);
-    return () => mediaQuery.removeEventListener('change', handler);
-  }, [query]);
-
-  return matches;
-}
-
-// hooks/useClickOutside.ts
-export 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]);
+    window.localStorage.setItem(key, JSON.stringify(stored));
+  }, [key, stored]);
 
-  return ref;
-}
-
-// hooks/usePrevious.ts
-export function usePrevious<T>(value: T): T | undefined {
-  const ref = useRef<T>();
-
-  useEffect(() => {
-    ref.current = value;
-  }, [value]);
-
-  return ref.current;
-}
-
-// Usage examples
-function HooksExamples() {
-  const [theme, setTheme] = useLocalStorage('theme', 'light');
-  const [search, setSearch] = useState('');
-  const debouncedSearch = useDebounce(search, 300);
-  const isMobile = useMediaQuery('(max-width: 768px)');
-  const { data, loading, error } = useAsync(() => fetchUsers());
-
-  const dropdownRef = useClickOutside<HTMLDivElement>(() => {
-    setIsOpen(false);
-  });
-
-  return (
-    <div>
-      <ThemeToggle theme={theme} onChange={setTheme} />
-      <SearchInput value={search} onChange={setSearch} />
-      <SearchResults query={debouncedSearch} />
-      {isMobile ? <MobileNav /> : <DesktopNav />}
-    </div>
-  );
+  return [stored, setStored] as const;
 }
 ```
 
-### 4. State Machine Pattern
+### State Machine Pattern
 
 ```tsx
-// lib/createStateMachine.ts
-type StateConfig<TContext, TState extends string, TEvent extends { type: string }> = {
-  initial: TState;
-  context: TContext;
-  states: {
-    [K in TState]: {
-      on?: {
-        [E in TEvent['type']]?: TState | {
-          target: TState;
-          actions?: (context: TContext, event: Extract<TEvent, { type: E }>) => TContext;
-          guard?: (context: TContext, event: Extract<TEvent, { type: E }>) => boolean;
-        };
-      };
-      entry?: (context: TContext) => TContext | void;
-      exit?: (context: TContext) => TContext | void;
-    };
-  };
-};
-
-// hooks/useStateMachine.ts
-export function useStateMachine<
-  TContext,
-  TState extends string,
-  TEvent extends { type: string }
->(config: StateConfig<TContext, TState, TEvent>) {
-  const [state, setState] = useState<TState>(config.initial);
-  const [context, setContext] = useState<TContext>(config.context);
-
-  const send = useCallback(
-    (event: TEvent) => {
-      const currentStateConfig = config.states[state];
-      const transition = currentStateConfig.on?.[event.type as TEvent['type']];
-
-      if (!transition) return;
-
-      let nextState: TState;
-      let newContext = context;
-
-      if (typeof transition === 'string') {
-        nextState = transition;
-      } else {
-        // Check guard condition
-        if (transition.guard && !transition.guard(context, event as any)) {
-          return;
-        }
-        nextState = transition.target;
-        if (transition.actions) {
-          newContext = transition.actions(context, event as any);
-        }
-      }
-
-      // Run exit action
-      const exitAction = currentStateConfig.exit;
-      if (exitAction) {
-        const result = exitAction(newContext);
-        if (result) newContext = result;
-      }
-
-      // Run entry action
-      const nextStateConfig = config.states[nextState];
-      const entryAction = nextStateConfig.entry;
-      if (entryAction) {
-        const result = entryAction(newContext);
-        if (result) newContext = result;
-      }
-
-      setState(nextState);
-      setContext(newContext);
-    },
-    [state, context, config]
-  );
-
-  const matches = useCallback((s: TState) => state === s, [state]);
-
-  return { state, context, send, matches };
-}
-
-// Example: Form submission state machine
 type FormState = 'idle' | 'validating' | 'submitting' | 'success' | 'error';
-
 type FormEvent =
   | { type: 'SUBMIT'; data: FormData }
-  | { type: 'VALIDATE_SUCCESS' }
-  | { type: 'VALIDATE_ERROR'; errors: Record<string, string> }
-  | { type: 'SUBMIT_SUCCESS'; response: any }
-  | { type: 'SUBMIT_ERROR'; error: string }
-  | { type: 'RESET' };
+  | { type: 'SUCCESS'; response: any }
+  | { type: 'ERROR'; error: string };
 
-interface FormContext {
-  data: FormData | null;
-  errors: Record<string, string>;
-  response: any;
-  submitError: string | null;
-}
+function useFormMachine() {
+  const [state, setState] = useState<FormState>('idle');
+  const [context, setContext] = useState({ data: null, error: null });
 
-const formMachine: StateConfig<FormContext, FormState, FormEvent> = {
-  initial: 'idle',
-  context: {
-    data: null,
-    errors: {},
-    response: null,
-    submitError: null,
-  },
-  states: {
-    idle: {
-      on: {
-        SUBMIT: {
-          target: 'validating',
-          actions: (ctx, event) => ({ ...ctx, data: event.data, errors: {} }),
-        },
-      },
-    },
-    validating: {
-      on: {
-        VALIDATE_SUCCESS: 'submitting',
-        VALIDATE_ERROR: {
-          target: 'idle',
-          actions: (ctx, event) => ({ ...ctx, errors: event.errors }),
-        },
-      },
-    },
-    submitting: {
-      on: {
-        SUBMIT_SUCCESS: {
-          target: 'success',
-          actions: (ctx, event) => ({ ...ctx, response: event.response }),
-        },
-        SUBMIT_ERROR: {
-          target: 'error',
-          actions: (ctx, event) => ({ ...ctx, submitError: event.error }),
-        },
-      },
-    },
-    success: {
-      on: {
-        RESET: {
-          target: 'idle',
-          actions: () => ({
-            data: null,
-            errors: {},
-            response: null,
-            submitError: null,
-          }),
-        },
-      },
-    },
-    error: {
-      on: {
-        SUBMIT: {
-          target: 'validating',
-          actions: (ctx, event) => ({
-            ...ctx,
-            data: event.data,
-            submitError: null,
-          }),
-        },
-        RESET: {
-          target: 'idle',
-          actions: () => ({
-            data: null,
-            errors: {},
-            response: null,
-            submitError: null,
-          }),
-        },
-      },
-    },
-  },
-};
-
-function FormWithStateMachine() {
-  const { state, context, send, matches } = useStateMachine(formMachine);
-
-  const handleSubmit = async (formData: FormData) => {
-    send({ type: 'SUBMIT', data: formData });
-
-    // Validate
-    const errors = validate(formData);
-    if (Object.keys(errors).length > 0) {
-      send({ type: 'VALIDATE_ERROR', errors });
-      return;
+  const send = useCallback((event: FormEvent) => {
+    switch (state) {
+      case 'idle':
+        if (event.type === 'SUBMIT') { setState('validating'); }
+        break;
+      case 'submitting':
+        if (event.type === 'SUCCESS') { setState('success'); }
+        if (event.type === 'ERROR') { setState('error'); setContext(c => ({ ...c, error: event.error })); }
+        break;
     }
-    send({ type: 'VALIDATE_SUCCESS' });
+  }, [state]);
 
-    // Submit
-    try {
-      const response = await submitForm(formData);
-      send({ type: 'SUBMIT_SUCCESS', response });
-    } catch (error) {
-      send({ type: 'SUBMIT_ERROR', error: error.message });
-    }
-  };
-
-  return (
-    <form onSubmit={(e) => { e.preventDefault(); handleSubmit(new FormData(e.target)); }}>
-      {matches('success') && <SuccessMessage response={context.response} />}
-      {matches('error') && <ErrorMessage error={context.submitError} />}
-      {Object.entries(context.errors).map(([field, error]) => (
-        <FieldError key={field} field={field} error={error} />
-      ))}
-      <button type="submit" disabled={matches('submitting') || matches('validating')}>
-        {matches('submitting') ? 'Submitting...' : 'Submit'}
-      </button>
-    </form>
-  );
+  return { state, context, send };
 }
 ```
 
-### 5. Higher-Order Components (HOC)
+### Optimistic Update Hook
 
 ```tsx
-// hocs/withAuth.tsx
-import { useRouter } from 'next/router';
-import { ComponentType, useEffect } from 'react';
-import { useAuth } from '@/hooks/useAuth';
-
-interface WithAuthOptions {
-  redirectTo?: string;
-  requiredRole?: string;
-}
-
-export function withAuth<P extends object>(
-  WrappedComponent: ComponentType<P>,
-  options: WithAuthOptions = {}
-) {
-  const { redirectTo = '/login', requiredRole } = options;
-
-  function AuthenticatedComponent(props: P) {
-    const router = useRouter();
-    const { user, loading, isAuthenticated } = useAuth();
-
-    useEffect(() => {
-      if (!loading && !isAuthenticated) {
-        router.push(`${redirectTo}?returnUrl=${encodeURIComponent(router.asPath)}`);
-      }
-
-      if (!loading && requiredRole && user?.role !== requiredRole) {
-        router.push('/unauthorized');
-      }
-    }, [loading, isAuthenticated, user, router]);
-
-    if (loading) {
-      return <LoadingSpinner />;
-    }
-
-    if (!isAuthenticated) {
-      return null;
-    }
-
-    if (requiredRole && user?.role !== requiredRole) {
-      return null;
-    }
-
-    return <WrappedComponent {...props} />;
-  }
-
-  AuthenticatedComponent.displayName = `withAuth(${
-    WrappedComponent.displayName || WrappedComponent.name || 'Component'
-  })`;
-
-  return AuthenticatedComponent;
-}
-
-// hocs/withErrorBoundary.tsx
-interface WithErrorBoundaryOptions {
-  fallback?: ReactNode;
-  onError?: (error: Error, errorInfo: React.ErrorInfo) => void;
-}
-
-export function withErrorBoundary<P extends object>(
-  WrappedComponent: ComponentType<P>,
-  options: WithErrorBoundaryOptions = {}
-) {
-  const { fallback, onError } = options;
-
-  class ErrorBoundaryHOC extends React.Component<
-    P,
-    { hasError: boolean; error: Error | null }
-  > {
-    static displayName = `withErrorBoundary(${
-      WrappedComponent.displayName || WrappedComponent.name || 'Component'
-    })`;
-
-    constructor(props: P) {
-      super(props);
-      this.state = { hasError: false, error: null };
-    }
-
-    static getDerivedStateFromError(error: Error) {
-      return { hasError: true, error };
-    }
-
-    componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
-      onError?.(error, errorInfo);
-    }
-
-    render() {
-      if (this.state.hasError) {
-        return fallback || <DefaultErrorFallback error={this.state.error} />;
-      }
+export function useOptimistic<T>(initialData: T, reducer: (state: T, action: any) => T) {
+  const [state, setState] = useState({ data: initialData, pending: false, error: null });
+  const previousRef = useRef(initialData);
 
-      return <WrappedComponent {...this.props} />;
-    }
-  }
-
-  return ErrorBoundaryHOC;
-}
-
-// hocs/withLoading.tsx
-interface WithLoadingProps {
-  isLoading?: boolean;
-}
+  const optimisticUpdate = useCallback(async (action: any, asyncOp: () => Promise<T>) => {
+    previousRef.current = state.data;
+    setState({ data: reducer(state.data, action), pending: true, error: null });
 
-export function withLoading<P extends object>(
-  WrappedComponent: ComponentType<P>,
-  LoadingComponent: ComponentType = DefaultSpinner
-) {
-  function LoadingWrapper(props: P & WithLoadingProps) {
-    const { isLoading, ...rest } = props;
-
-    if (isLoading) {
-      return <LoadingComponent />;
+    try {
+      const result = await asyncOp();
+      setState({ data: result, pending: false, error: null });
+    } catch (error) {
+      setState({ data: previousRef.current, pending: false, error: error as Error });
     }
-
-    return <WrappedComponent {...(rest as P)} />;
-  }
-
-  LoadingWrapper.displayName = `withLoading(${
-    WrappedComponent.displayName || WrappedComponent.name || 'Component'
-  })`;
-
-  return LoadingWrapper;
-}
-
-// Usage
-const ProtectedDashboard = withAuth(Dashboard, { requiredRole: 'admin' });
-const SafeUserProfile = withErrorBoundary(UserProfile, {
-  fallback: <div>Something went wrong</div>,
-});
-const LoadableDataGrid = withLoading(DataGrid);
-```
-
-### 6. Optimistic UI Updates
-
-```tsx
-// hooks/useOptimistic.ts
-interface OptimisticState<T> {
-  data: T;
-  pending: boolean;
-  error: Error | null;
-}
-
-export function useOptimistic<T, TAction>(
-  initialData: T,
-  reducer: (state: T, action: TAction) => T
-) {
-  const [state, setState] = useState<OptimisticState<T>>({
-    data: initialData,
-    pending: false,
-    error: null,
-  });
-
-  const previousDataRef = useRef<T>(initialData);
-
-  const optimisticUpdate = useCallback(
-    async (action: TAction, asyncOperation: () => Promise<T>) => {
-      // Store previous state for rollback
-      previousDataRef.current = state.data;
-
-      // Apply optimistic update
-      const optimisticData = reducer(state.data, action);
-      setState({ data: optimisticData, pending: true, error: null });
-
-      try {
-        // Perform actual async operation
-        const result = await asyncOperation();
-        setState({ data: result, pending: false, error: null });
-        return result;
-      } catch (error) {
-        // Rollback on error
-        setState({
-          data: previousDataRef.current,
-          pending: false,
-          error: error instanceof Error ? error : new Error(String(error)),
-        });
-        throw error;
-      }
-    },
-    [state.data, reducer]
-  );
+  }, [state.data, reducer]);
 
   return { ...state, optimisticUpdate };
 }
-
-// Example: Todo list with optimistic updates
-interface Todo {
-  id: string;
-  text: string;
-  completed: boolean;
-}
-
-function TodoList() {
-  const { data: todos, pending, error, optimisticUpdate } = useOptimistic<
-    Todo[],
-    { type: 'ADD' | 'TOGGLE' | 'DELETE'; payload: any }
-  >(initialTodos, (state, action) => {
-    switch (action.type) {
-      case 'ADD':
-        return [...state, action.payload];
-      case 'TOGGLE':
-        return state.map((todo) =>
-          todo.id === action.payload
-            ? { ...todo, completed: !todo.completed }
-            : todo
-        );
-      case 'DELETE':
-        return state.filter((todo) => todo.id !== action.payload);
-      default:
-        return state;
-    }
-  });
-
-  const addTodo = async (text: string) => {
-    const tempId = `temp-${Date.now()}`;
-    const newTodo = { id: tempId, text, completed: false };
-
-    await optimisticUpdate(
-      { type: 'ADD', payload: newTodo },
-      async () => {
-        const response = await api.createTodo({ text });
-        return todos.map((t) => (t.id === tempId ? response : t));
-      }
-    );
-  };
-
-  const toggleTodo = async (id: string) => {
-    await optimisticUpdate(
-      { type: 'TOGGLE', payload: id },
-      async () => {
-        await api.toggleTodo(id);
-        return todos.map((t) =>
-          t.id === id ? { ...t, completed: !t.completed } : t
-        );
-      }
-    );
-  };
-
-  return (
-    <div className={pending ? 'opacity-70' : ''}>
-      {error && <ErrorToast message={error.message} />}
-      <TodoForm onSubmit={addTodo} disabled={pending} />
-      {todos.map((todo) => (
-        <TodoItem
-          key={todo.id}
-          todo={todo}
-          onToggle={() => toggleTodo(todo.id)}
-        />
-      ))}
-    </div>
-  );
-}
-```
-
-## Use Cases
-
-### Component Library Architecture
-
-```tsx
-// lib/components/index.ts - Barrel exports
-export { Button, type ButtonProps } from './Button';
-export { Input, type InputProps } from './Input';
-export { Select, SelectTrigger, SelectContent, SelectItem } from './Select';
-
-// lib/components/Button/Button.tsx
-import { forwardRef, ButtonHTMLAttributes } from 'react';
-import { cva, type VariantProps } from 'class-variance-authority';
-import { cn } from '@/lib/utils';
-
-const buttonVariants = cva(
-  'inline-flex items-center justify-center rounded-md font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 disabled:pointer-events-none disabled:opacity-50',
-  {
-    variants: {
-      variant: {
-        default: 'bg-primary text-primary-foreground hover:bg-primary/90',
-        destructive: 'bg-destructive text-destructive-foreground hover:bg-destructive/90',
-        outline: 'border border-input bg-background hover:bg-accent hover:text-accent-foreground',
-        secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
-        ghost: 'hover:bg-accent hover:text-accent-foreground',
-        link: 'text-primary underline-offset-4 hover:underline',
-      },
-      size: {
-        default: 'h-10 px-4 py-2',
-        sm: 'h-9 rounded-md px-3',
-        lg: 'h-11 rounded-md px-8',
-        icon: 'h-10 w-10',
-      },
-    },
-    defaultVariants: {
-      variant: 'default',
-      size: 'default',
-    },
-  }
-);
-
-export interface ButtonProps
-  extends ButtonHTMLAttributes<HTMLButtonElement>,
-    VariantProps<typeof buttonVariants> {
-  loading?: boolean;
-}
-
-export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
-  ({ className, variant, size, loading, children, disabled, ...props }, ref) => {
-    return (
-      <button
-        className={cn(buttonVariants({ variant, size, className }))}
-        ref={ref}
-        disabled={disabled || loading}
-        {...props}
-      >
-        {loading && <Spinner className="mr-2 h-4 w-4" />}
-        {children}
-      </button>
-    );
-  }
-);
-
-Button.displayName = 'Button';
-```
-
-### Form Architecture Pattern
-
-```tsx
-// hooks/useForm.ts
-interface UseFormConfig<T> {
-  initialValues: T;
-  validate: (values: T) => Partial<Record<keyof T, string>>;
-  onSubmit: (values: T) => Promise<void>;
-}
-
-export function useForm<T extends Record<string, any>>({
-  initialValues,
-  validate,
-  onSubmit,
-}: UseFormConfig<T>) {
-  const [values, setValues] = useState<T>(initialValues);
-  const [errors, setErrors] = useState<Partial<Record<keyof T, string>>>({});
-  const [touched, setTouched] = useState<Partial<Record<keyof T, boolean>>>({});
-  const [submitting, setSubmitting] = useState(false);
-
-  const handleChange = useCallback(
-    (field: keyof T) => (e: React.ChangeEvent<HTMLInputElement>) => {
-      const value = e.target.type === 'checkbox' ? e.target.checked : e.target.value;
-      setValues((prev) => ({ ...prev, [field]: value }));
-    },
-    []
-  );
-
-  const handleBlur = useCallback(
-    (field: keyof T) => () => {
-      setTouched((prev) => ({ ...prev, [field]: true }));
-      const fieldErrors = validate(values);
-      if (fieldErrors[field]) {
-        setErrors((prev) => ({ ...prev, [field]: fieldErrors[field] }));
-      } else {
-        setErrors((prev) => {
-          const { [field]: _, ...rest } = prev;
-          return rest as Partial<Record<keyof T, string>>;
-        });
-      }
-    },
-    [values, validate]
-  );
-
-  const handleSubmit = useCallback(
-    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) return;
-
-      setSubmitting(true);
-      try {
-        await onSubmit(values);
-      } finally {
-        setSubmitting(false);
-      }
-    },
-    [values, validate, onSubmit]
-  );
-
-  const reset = useCallback(() => {
-    setValues(initialValues);
-    setErrors({});
-    setTouched({});
-  }, [initialValues]);
-
-  const getFieldProps = useCallback(
-    (field: keyof T) => ({
-      value: values[field],
-      onChange: handleChange(field),
-      onBlur: handleBlur(field),
-      error: touched[field] ? errors[field] : undefined,
-    }),
-    [values, errors, touched, handleChange, handleBlur]
-  );
-
-  return {
-    values,
-    errors,
-    touched,
-    submitting,
-    handleChange,
-    handleBlur,
-    handleSubmit,
-    reset,
-    getFieldProps,
-    setValues,
-    setFieldValue: (field: keyof T, value: T[keyof T]) =>
-      setValues((prev) => ({ ...prev, [field]: value })),
-  };
-}
 ```
 
 ## Best Practices
 
-### Do's
-
-- Use compound components for complex UI with shared state
-- Create custom hooks to encapsulate reusable logic
-- Implement state machines for complex state transitions
-- Use TypeScript for type-safe component APIs
-- Prefer composition over inheritance
-- Keep components focused with single responsibility
-- Colocate related code and styles
-- Use forwardRef for component library primitives
-- Implement proper error boundaries
-- Use render props for maximum flexibility
-
-### Don'ts
-
-- Don't overuse HOCs (prefer hooks)
-- Don't mutate state directly
-- Don't create deeply nested component hierarchies
-- Don't pass too many props (use context or composition)
-- Don't ignore TypeScript errors
-- Don't create components with side effects in render
-- Don't forget to memoize expensive computations
-- Don't skip accessibility in component design
-- Don't use prop drilling for deeply nested data
-- Don't forget cleanup in useEffect
-
-## References
-
-- [React Patterns](https://reactpatterns.com/)
-- [Patterns.dev](https://www.patterns.dev/)
-- [Kent C. Dodds - Advanced React Patterns](https://kentcdodds.com/blog/advanced-react-patterns)
-- [XState Documentation](https://xstate.js.org/docs/)
-- [React TypeScript Cheatsheet](https://react-typescript-cheatsheet.netlify.app/)
+| Do | Avoid |
+|----|-------|
+| Use compound components for complex UI with shared state | Overusing HOCs (prefer hooks) |
+| Create custom hooks to encapsulate reusable logic | Mutating state directly |
+| Implement state machines for complex state transitions | Deeply nested component hierarchies |
+| Use TypeScript for type-safe component APIs | Passing too many props (use context/composition) |
+| Use forwardRef for component library primitives | Creating components with side effects in render |
+| Keep components focused with single responsibility | Prop drilling for deeply nested data |