# tanstack/ranger architecture

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

- Interactive diagram: https://gitdiagram.com/tanstack/ranger
- Repository: https://github.com/tanstack/ranger

## Overview

##### Project Type and Purpose
- This is an open‑source, monorepo library (“TanStack Ranger”) providing a headless UI component for building range/slider controls in JS/TS and React.
- It ships two packages: a framework‑agnostic core (packages/ranger) and a React wrapper (packages/react-ranger), plus docs and runnable React examples.

##### Main System Components
a. Monorepo Root
- pnpm‑workspace.yaml & lerna.json: orchestrate all packages
- Config files (tsconfig.base.json, babel.config.js, rollup.config.*)
- CI workflows (.github/workflows/ci.yml & pr.yml)
- Publishing scripts (scripts/publish.ts)
b. Core Package (packages/ranger)
- Pure logic: range calculations, utilities
- Exports TS API for any JS framework
c. React Package (packages/react-ranger)
- React hooks & components consuming core API
d. Documentation Site (docs/)
- Markdown overviews, API reference, guides
- Config for static site generation
e. Examples (examples/react/…)
- Multiple Vite‑based demo apps illustrating features
f. External Services
- GitHub (repo, Issues, Actions)
- npm registry (package publishing)
- Bundlephobia, shields.io badges

##### Component Relationships & Data Flows
- Core → React: React package imports core module
- Examples & Docs → Packages: both reference built packages via local workspace paths
- CI Pipeline → Packages: on PR or push, Actions run build/test on each package
- Publish Script → npm: on release, packages are bundled via Rollup and published
- GitHub CI → Badges: reads workflow results to update status badges

##### Architectural Patterns & Design Principles
- Monorepo with pnpm & Lerna for unified dependency/version management
- Headless UI pattern: UI‑agnostic core logic separated from rendering layer
- Modular packaging: each package has its own tsconfig, tests, and package.json
- Static site docs: decoupled from code but versioned alongside

##### Essential Elements
- Version control flow: developer commits → GitHub Actions → test/build → publish
- Headless pattern: separate “logic” layer and “UI adapter” layer

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Services
    GH["GitHub"]:::external
    NPM["npm Registry"]:::external

    %% Monorepo Root
    subgraph "Monorepo Root"
        MR["Monorepo Root"]:::code
    end

    %% Configuration Files
    subgraph "Configuration Files" 
        PW["pnpm-workspace.yaml"]:::code
        LJ["lerna.json"]:::code
        PJ["package.json"]:::code
        TSB["tsconfig.base.json"]:::code
        BCFG["babel.config.js"]:::code
        RCFG["rollup.config.js"]:::code
        JCFG["jest.config.ts"]:::code
    end

    MR -->|"includes"| PW
    MR -->|"includes"| LJ
    MR -->|"includes"| PJ
    MR -->|"includes"| TSB
    MR -->|"includes"| BCFG
    MR -->|"includes"| RCFG
    MR -->|"includes"| JCFG

    %% CI/CD Processes
    subgraph "CI Workflows" 
        CI["CI Workflow"]:::ci
        PR["PR Checks"]:::ci
    end

    MR -->|"triggers"| CI
    MR -->|"triggers"| PR
    GH -->|"push/PR events"| CI
    GH -->|"push/PR events"| PR

    %% Publishing Scripts
    subgraph "Publish Scripts"
        PS["scripts/publish.ts"]:::ci
        SC["scripts/config.ts"]:::ci
        ST["scripts/types.ts"]:::ci
        STS["scripts/tsconfig.json"]:::ci
    end

    CI -->|"on release"| PS
    PS -->|"uses"| SC
    PS -->|"uses"| ST
    PS -->|"uses"| STS
    PS -->|"publish to npm"| NPM

    %% Core Package
    subgraph "Core Package (Headless Logic)" 
        CP["packages/ranger"]:::code
        CPI["packages/ranger/src/index.ts"]:::code
        CPU["packages/ranger/src/utils.ts"]:::code
        CPT["packages/ranger/__tests__/core/core.test.tsx"]:::code
        CPS["packages/ranger/__tests__/jest.setup.js"]:::code
    end

    MR -->|"contains"| CP
    CP --> CPI
    CP --> CPU
    CP --> CPT
    CP --> CPS

    %% React Adapter Package
    subgraph "React Package (UI Adapter)" 
        RP["packages/react-ranger"]:::code
        RPI["packages/react-ranger/src/index.tsx"]:::code
        RPT["packages/react-ranger/__tests__/core/core.test.tsx"]:::code
        RPS["packages/react-ranger/__tests__/jest.setup.js"]:::code
    end

    MR -->|"contains"| RP
    RP --> RPI
    RP --> RPT
    RP --> RPS

    %% Documentation Site
    Docs["Documentation Site (docs/)"]:::code
    MR -->|"contains"| Docs

    %% Examples
    Ex["Examples (examples/react/)"]:::code
    MR -->|"contains"| Ex

    %% Dependencies and Flows
    CP -->|"import core api"| RP
    CP -->|"referenced by"| Docs
    RP -->|"referenced by"| Docs
    CP -->|"referenced by"| Ex
    RP -->|"referenced by"| Ex

    %% Connections between CI and Packages
    CI -->|"build & test"| CP
    CI -->|"build & test"| RP

    %% External Flows
    CI -->|"status badges"| GH
    PS -->|"published packages"| GH

    %% Click Events
    click PW "https://github.com/tanstack/ranger/blob/main/pnpm-workspace.yaml"
    click LJ "https://github.com/tanstack/ranger/blob/main/lerna.json"
    click PJ "https://github.com/tanstack/ranger/blob/main/package.json"
    click TSB "https://github.com/tanstack/ranger/blob/main/tsconfig.base.json"
    click BCFG "https://github.com/tanstack/ranger/blob/main/babel.config.js"
    click RCFG "https://github.com/tanstack/ranger/blob/main/rollup.config.js"
    click JCFG "https://github.com/tanstack/ranger/blob/main/jest.config.ts"
    click CI "https://github.com/tanstack/ranger/blob/main/.github/workflows/ci.yml"
    click PR "https://github.com/tanstack/ranger/blob/main/.github/workflows/pr.yml"
    click PS "https://github.com/tanstack/ranger/blob/main/scripts/publish.ts"
    click SC "https://github.com/tanstack/ranger/blob/main/scripts/config.ts"
    click ST "https://github.com/tanstack/ranger/blob/main/scripts/types.ts"
    click STS "https://github.com/tanstack/ranger/blob/main/scripts/tsconfig.json"
    click CP "https://github.com/tanstack/ranger/blob/main/packages/ranger/package.json"
    click CPI "https://github.com/tanstack/ranger/blob/main/packages/ranger/src/index.ts"
    click CPU "https://github.com/tanstack/ranger/blob/main/packages/ranger/src/utils.ts"
    click CPT "https://github.com/tanstack/ranger/blob/main/packages/ranger/__tests__/core/core.test.tsx"
    click CPS "https://github.com/tanstack/ranger/blob/main/packages/ranger/__tests__/jest.setup.js"
    click RP "https://github.com/tanstack/ranger/blob/main/packages/react-ranger/package.json"
    click RPI "https://github.com/tanstack/ranger/blob/main/packages/react-ranger/src/index.tsx"
    click RPT "https://github.com/tanstack/ranger/blob/main/packages/react-ranger/__tests__/core/core.test.tsx"
    click RPS "https://github.com/tanstack/ranger/blob/main/packages/react-ranger/__tests__/jest.setup.js"

    %% Styles
    classDef code fill:#cce5ff,stroke:#3399ff,color:#000;
    classDef ci fill:#d4edda,stroke:#28a745,color:#000;
    classDef external fill:#fff3cd,stroke:#ffc107,color:#000
```
