# emilkowalski/vaul architecture

> Architecture diagram of the GitHub repository emilkowalski/vaul, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/emilkowalski/vaul
- Repository: https://github.com/emilkowalski/vaul

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Public API Layer"
        API["src/index.tsx"]:::api
    end

    subgraph "Context & State Manager"
        Context["src/context.ts"]:::state
        Controllable["src/use-controllable-state.ts"]:::state
    end

    subgraph "Behavioral Hooks"
        PosFixed["src/use-position-fixed.ts"]:::hook
        PreventScroll["src/use-prevent-scroll.ts"]:::hook
        ScaleBg["src/use-scale-background.ts"]:::hook
        SnapPts["src/use-snap-points.ts"]:::hook
        ComposedRefs["src/use-composed-refs.ts"]:::hook
    end

    subgraph "Browser Utilities & Helpers"
        BrowserUtil["src/browser.ts"]:::util
        Helpers["src/helpers.ts"]:::util
    end

    subgraph "Shared Types & Constants"
        Types["src/types.ts"]:::shared
        Constants["src/constants.ts"]:::shared
    end

    subgraph "Base Styles"
        Styles["src/style.css"]:::shared
    end

    subgraph "Runtime Constructs"
        Portal["Drawer.Portal"]:::runtime
        Content["Drawer.Content & Overlay"]:::runtime
    end

    subgraph "Test Harness (Demo App)"
        Demo["test/src/app/"]:::demo
    end

    subgraph "End-to-End Tests"
        E2E["test/tests/"]:::demo
    end

    subgraph "CI/CD & Build Tools"
        CI1[".github/workflows/playwright.yml"]:::infra
        CI2["pnpm-workspace.yaml"]:::infra
        CI3["turbo.json"]:::infra
        CI4["playwright.config.ts"]:::infra
        CI5["tsconfig.json"]:::infra
        CI6a[".eslintrc.js"]:::infra
        CI6b[".prettierrc.js"]:::infra
    end

    API -->|"uses"| Context
    Context -->|"provides state to"| PosFixed
    Context -->|"provides state to"| PreventScroll
    Context -->|"provides state to"| ScaleBg
    Context -->|"provides state to"| SnapPts
    Context -->|"provides state to"| ComposedRefs
    PosFixed -->|"calls"| BrowserUtil
    PreventScroll -->|"calls"| Helpers
    ScaleBg -->|"calls"| BrowserUtil
    SnapPts -->|"calls"| BrowserUtil
    API -->|"exports Portal"| Portal
    Portal -->|"renders"| Content
    Demo -->|"imports from"| API
    CI1 -->|"runs against"| Demo
    CI1 -->|"runs tests in"| E2E
    CI2 -->|"manages workspace for"| API
    CI3 -->|"build pipeline for"| API
    CI4 -->|"configures tests in"| E2E
    CI5 -->|"types for"| API
    CI6a -->|"lint rules for"| API
    CI6b -->|"format rules for"| API

    click API "https://github.com/emilkowalski/vaul/blob/main/src/index.tsx"
    click Context "https://github.com/emilkowalski/vaul/blob/main/src/context.ts"
    click Controllable "https://github.com/emilkowalski/vaul/blob/main/src/use-controllable-state.ts"
    click PosFixed "https://github.com/emilkowalski/vaul/blob/main/src/use-position-fixed.ts"
    click PreventScroll "https://github.com/emilkowalski/vaul/blob/main/src/use-prevent-scroll.ts"
    click ScaleBg "https://github.com/emilkowalski/vaul/blob/main/src/use-scale-background.ts"
    click SnapPts "https://github.com/emilkowalski/vaul/blob/main/src/use-snap-points.ts"
    click ComposedRefs "https://github.com/emilkowalski/vaul/blob/main/src/use-composed-refs.ts"
    click BrowserUtil "https://github.com/emilkowalski/vaul/blob/main/src/browser.ts"
    click Helpers "https://github.com/emilkowalski/vaul/blob/main/src/helpers.ts"
    click Types "https://github.com/emilkowalski/vaul/blob/main/src/types.ts"
    click Constants "https://github.com/emilkowalski/vaul/blob/main/src/constants.ts"
    click Styles "https://github.com/emilkowalski/vaul/blob/main/src/style.css"
    click Demo "https://github.com/emilkowalski/vaul/tree/main/test/src/app/"
    click E2E "https://github.com/emilkowalski/vaul/tree/main/test/tests/"
    click CI1 "https://github.com/emilkowalski/vaul/blob/main/.github/workflows/playwright.yml"
    click CI2 "https://github.com/emilkowalski/vaul/blob/main/pnpm-workspace.yaml"
    click CI3 "https://github.com/emilkowalski/vaul/blob/main/turbo.json"
    click CI4 "https://github.com/emilkowalski/vaul/blob/main/playwright.config.ts"
    click CI5 "https://github.com/emilkowalski/vaul/blob/main/tsconfig.json"
    click CI6a "https://github.com/emilkowalski/vaul/blob/main/.eslintrc.js"
    click CI6b "https://github.com/emilkowalski/vaul/blob/main/.prettierrc.js"

    classDef api fill:#D0E6FF,stroke:#0B69C7,color:#0B69C7;
    classDef state fill:#E0F7FA,stroke:#00838F,color:#006064;
    classDef hook fill:#E8F5E9,stroke:#43A047,color:#1B5E20;
    classDef util fill:#FFF3E0,stroke:#FB8C00,color:#E65100;
    classDef shared fill:#F5F5F5,stroke:#9E9E9E,color:#616161;
    classDef runtime fill:#F3E5F5,stroke:#8E24AA,color:#4A148C;
    classDef demo fill:#FFFDE7,stroke:#FBC02D,color:#F57F17;
    classDef infra fill:#FFEBEE,stroke:#E53935,color:#B71C1C;
```
