How emilkowalski/vaul works
Project Type and Purpose
• Vaul is a React component library providing an unstyled “drawer” UI primitive for mobile/tablet.
• It is not a full application but a reusable widget; it bundles source files, hooks, and context logic, and offers a demo/test harness under test/.
File Structure
• Top level:
– Configuration: .eslintrc.js, .prettierrc.js, tsconfig.json, CI (.github/workflows/playwright.yml), pnpm-workspace.yaml, turbo.json
– Package manifest: package.json
– Lockfiles: pnpm-lock.yaml
• Source code (src/):
– index.tsx – public API exports (Drawer.Root, Trigger, Portal, etc.)
– browser.ts – browser detection utilities
– context.ts – React context provider for drawer state
– helpers.ts – utility functions (e.g., scroll locking)
– many custom hooks:
• use-position-fixed.ts (positioning in viewport)
• use-prevent-scroll.ts (body scroll lock)
• use-scale-background.ts (background scaling effect)
• use-snap-points.ts (snap-to-points logic)
• plus use-controllable-state.ts, use-composed-refs.ts
– constants.ts and types.ts for shared types and values
– style.css – minimal base CSS
• Test harness (test/):
– Next.js example app under test/src/app/* covering various use‐cases
– Playwright tests in test/tests/
– Per‐demo configs (next.config.js, tailwind.config.ts, etc.)
README
• Confirms the library nature, install steps, and demo usage.
Main Components & Their Relationships
a. Public API Layer
• index.tsx: re‑exports Drawer.Root, Drawer.Trigger, Drawer.Portal, Drawer.Content, Drawer.Overlay, Drawer.Title
• Consumers import from this layer.
b. Context & State Management
• context.ts: provides open/close state and actions to descendent hooks/components.
• use-controllable-state.ts: toggles between controlled/uncontrolled mode.
c. Behavioral Hooks
• Hooks under src/ implement low‐level browser behaviors: scroll‐locking, positioning, background scaling, snap‐points.
• They all read from or dispatch to the drawer context.
d. Rendering & Portals
• Drawer.Portal uses ReactDOM.createPortal to append drawer markup to document body.
• Drawer.Content and Drawer.Overlay render inside that portal.
e. Demo & E2E Test Infrastructure
• A Next.js application wraps the library for manual and automated testing.
• Playwright workflow runs against these demos.
Key Architectural Patterns & Principles
• Compound Components: Root/Trigger/Portal/Content pattern allows flexible composition.
• Hooks + Context: Centralize state and behavior; keep components lean.
• Portal Pattern: Decouple drawer UI from original React tree position.
• Controlled vs. Uncontrolled API: use-controllable-state allows library to support both modes.
• Test Harness as Consumer: Example app lives in test/ to validate real‐world integration.