omgkit 2.1.1 → 2.2.0

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

@@ -1,47 +1,1325 @@
 ---
 name: frontend-design
-description: Frontend design patterns. Use for component architecture, state management.
+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
 ---
 
-# Frontend Design Skill
+# Frontend Design Patterns
 
-## Component 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
 
-### Compound Components
 ```tsx
-<Select>
-  <SelectTrigger>Select option</SelectTrigger>
-  <SelectContent>
-    <SelectItem value="1">Option 1</SelectItem>
-  </SelectContent>
-</Select>
+// 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;
+}
+
+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) {
+  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>
+  );
+}
+
+// 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>
+  );
+}
 ```
 
-### Render Props
+### 2. Render Props Pattern
+
 ```tsx
-<DataFetcher url="/api/users">
-  {({ data, loading }) => loading ? <Spinner /> : <UserList users={data} />}
-</DataFetcher>
+// 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)}</>;
+}
+
+// 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>
+
+      {/* Mouse tracker */}
+      <MouseTracker>
+        {({ x, y }) => (
+          <div className="fixed pointer-events-none" style={{ left: x, top: y }}>
+            Custom cursor at ({x}, {y})
+          </div>
+        )}
+      </MouseTracker>
+
+      {/* 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>
+    </>
+  );
+}
 ```
 
-### Custom Hooks
+### 3. Custom Hooks Pattern
+
 ```tsx
-function useLocalStorage<T>(key: string, initial: T) {
-  const [value, setValue] = useState<T>(() => {
-    const stored = localStorage.getItem(key);
-    return stored ? JSON.parse(stored) : initial;
+// 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(() => {
-    localStorage.setItem(key, JSON.stringify(value));
-  }, [key, value]);
+    const timer = setTimeout(() => {
+      setDebouncedValue(value);
+    }, delay);
 
-  return [value, setValue] as const;
+    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 }));
+
+    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;
+  });
+
+  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]);
+
+  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>
+  );
+}
+```
+
+### 4. 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' };
+
+interface FormContext {
+  data: FormData | null;
+  errors: Record<string, string>;
+  response: any;
+  submitError: string | 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;
+    }
+    send({ type: 'VALIDATE_SUCCESS' });
+
+    // 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>
+  );
+}
+```
+
+### 5. Higher-Order Components (HOC)
+
+```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} />;
+      }
+
+      return <WrappedComponent {...this.props} />;
+    }
+  }
+
+  return ErrorBoundaryHOC;
+}
+
+// hocs/withLoading.tsx
+interface WithLoadingProps {
+  isLoading?: boolean;
+}
+
+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 />;
+    }
+
+    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]
+  );
+
+  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
-- Single responsibility components
-- Lift state appropriately
-- Colocate related code
-- Use composition over inheritance
+
+### 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/)