# observablehq/inputs architecture

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

- Interactive diagram: https://gitdiagram.com/observablehq/inputs
- Repository: https://github.com/observablehq/inputs

## Overview

##### Project Type & Purpose
- It’s a client-side JavaScript library (“Observable Inputs”) providing discrete, reusable HTML input components (buttons, sliders, selects, tables, etc.).
- It is neither a full-stack app nor a microservice platform but a bundlable, importable UI-widget toolkit intended for any web environment (including Observable notebooks/framework).

##### High-Level Architecture

A. Source Modules (src/)
– One module per input type (button.js, checkbox.js, range.js, table.js, form.js, bind.js, disposal.js, format.js, etc.).
– index.js aggregates and re-exports all components as the public API.

B. Build & Packaging
– rollup.config.js: defines the bundling pipeline.
– bin/clean-css.js and DEV scripts: post-build CSS extraction/cleanup.
– bundle.js: the single-file UMD/ESM bundle generated for npm and CDN distribution.
– index.css: the stylesheet generated from src/style.css.

C. Distribution
– package.json: npm settings, entry points (main/module fields), versioning.
– GitHub Actions workflows:
- test.yml runs unit tests (test/ folder using jsdom).
- publish.yml handles version bump, tagging, npm publish.

D. Testing
– test/output/: golden HTML snapshots for regression.
– test/jsdom.js sets up DOM environment.
– test/.eslintrc.json: test linting rules.

E. Consumers & Environments
– Direct npm consumers: import via ES modules or require UMD build.
– CDN consumers: load from jsDelivr (https://cdn.jsdelivr.net/npm/@observablehq/inputs@…).
– Observable Framework: `view(Inputs.xxx)` reactive integration.
– Observable notebooks: `viewof x = Inputs.xxx` usage.

F. External Dependencies & Tools
– Runtime: pure JS, no external runtime dependencies beyond standard DOM APIs.
– Development: Node.js, Rollup, ESLint, GitHub Actions, jsdom for testing.

##### Relationships & Data Flow
- Source modules → (Rollup bundler) → bundle.js + styles → (npm/CND) → consumer app or notebook.
- Tests consume source modules in a jsdom environment and compare rendered HTML to golden snapshots.
- GitHub Actions orchestrate: on push → run tests; on tag/release → build & publish.

##### Architectural Patterns & Principles
– Modular design: each input type encapsulated in its own module.
– Single responsibility: format utilities, disposal logic, binding utilities separated out.
– Build-time composition: Rollup tree-shaking to include only used modules in consumer bundles.
– Snapshot-based testing for HTML output regression.
– CI/CD via GitHub Actions.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Source Modules
    subgraph "Source Modules" 
        direction TB
        IDX["src/index.js"]:::source
        BTN["src/button.js"]:::source
        CHK["src/checkbox.js"]:::source
        RNG["src/range.js"]:::source
        TBL["src/table.js"]:::source
        FRM["src/form.js"]:::source
        BND["src/bind.js"]:::source
        DSP["src/disposal.js"]:::source
        FMT["src/format.js"]:::source
        STY_SRC["src/style.css"]:::source
    end

    %% Build & Packaging
    subgraph "Build & Packaging"
        direction TB
        ROLLUP["rollup.config.js"]:::build
        CLEAN_CSS["bin/clean-css.js"]:::build
        ROLLR["Rollup Bundler"]:::build
        BUNDLE["bundle.js (UMD/ESM)"]:::build
        CSS_OUT["index.css"]:::build
    end

    %% Testing
    subgraph "Testing" 
        direction TB
        TEST_DIR["test/"]:::testing
        ESLINT_RULES["test/.eslintrc.json"]:::testing
        JSDOM["test/jsdom.js"]:::testing
        SNAPSHOTS["test/output/"]:::testing
    end

    %% CI/CD
    subgraph "CI/CD (GitHub Actions)"
        direction TB
        CI_TEST[".github/workflows/test.yml"]:::ci
        CI_PUB[".github/workflows/publish.yml"]:::ci
    end

    %% Consumers & External
    subgraph "Consumers & Environments"
        direction TB
        NPM["npm registry"]:::consumer
        CDN["jsDelivr CDN"]:::consumer
        OBSFW["Observable Framework"]:::consumer
        OBSNB["Observable Notebooks"]:::consumer
    end

    %% External Service
    GITHUB["GitHub"]:::external

    %% Relationships
    BTN -->|imports| IDX
    CHK -->|imports| IDX
    RNG -->|imports| IDX
    TBL -->|imports| IDX
    FRM -->|imports| IDX
    BND -->|imports| IDX
    DSP -->|imports| IDX
    FMT -->|imports| IDX
    STY_SRC -->|imported by| ROLLR

    IDX -->|entry for| ROLLR
    ROLLUP -->|configures| ROLLR
    ROLLR -->|produces| BUNDLE
    ROLLR -->|produces| CSS_OUT
    CLEAN_CSS -->|processes| CSS_OUT

    TEST_DIR -->|uses| BTN
    TEST_DIR -->|uses| CHK
    TEST_DIR -->|uses| RNG
    TEST_DIR -->|uses| TBL
    TEST_DIR -->|uses| FRM
    TEST_DIR -->|uses| BND
    TEST_DIR -->|uses| DSP
    TEST_DIR -->|uses| FMT
    TEST_DIR -->|uses| JSDOM
    TEST_DIR -->|compares to| SNAPSHOTS
    ESLINT_RULES -->|lint rules for| TEST_DIR

    GITHUB -->|on push| CI_TEST
    GITHUB -->|on tag/release| CI_PUB
    CI_TEST -->|runs| TEST_DIR
    CI_PUB -->|build & publish| ROLLR
    CI_PUB -->|publish bundle| NPM

    BUNDLE -->|published to| NPM
    BUNDLE -->|served by| CDN
    BUNDLE -->|importable by| OBSFW
    BUNDLE -->|importable by| OBSNB

    %% Click Events
    click IDX "https://github.com/observablehq/inputs/blob/main/src/index.js"
    click BTN "https://github.com/observablehq/inputs/blob/main/src/button.js"
    click CHK "https://github.com/observablehq/inputs/blob/main/src/checkbox.js"
    click RNG "https://github.com/observablehq/inputs/blob/main/src/range.js"
    click TBL "https://github.com/observablehq/inputs/blob/main/src/table.js"
    click FRM "https://github.com/observablehq/inputs/blob/main/src/form.js"
    click BND "https://github.com/observablehq/inputs/blob/main/src/bind.js"
    click DSP "https://github.com/observablehq/inputs/blob/main/src/disposal.js"
    click FMT "https://github.com/observablehq/inputs/blob/main/src/format.js"
    click STY_SRC "https://github.com/observablehq/inputs/blob/main/src/style.css"
    click ROLLUP "https://github.com/observablehq/inputs/blob/main/rollup.config.js"
    click CLEAN_CSS "https://github.com/observablehq/inputs/blob/main/bin/clean-css.js"
    click BUNDLE "https://github.com/observablehq/inputs/blob/main/bundle.js"
    click NPM "https://github.com/observablehq/inputs/blob/main/package.json"
    click ESLINT_RULES "https://github.com/observablehq/inputs/blob/main/test/.eslintrc.json"
    click JSDOM "https://github.com/observablehq/inputs/blob/main/test/jsdom.js"
    click TEST_DIR "https://github.com/observablehq/inputs/tree/main/test/"
    click SNAPSHOTS "https://github.com/observablehq/inputs/tree/main/test/output/"
    click CI_TEST "https://github.com/observablehq/inputs/blob/main/.github/workflows/test.yml"
    click CI_PUB "https://github.com/observablehq/inputs/blob/main/.github/workflows/publish.yml"

    %% Styles
    classDef source fill:#cfe2f3,stroke:#0b5394,color:#073763
    classDef build fill:#fce5cd,stroke:#e69138,color:#b45f06
    classDef testing fill:#d9ead3,stroke:#6aa84f,color:#274e13
    classDef ci fill:#d9d2e9,stroke:#8e7cc3,color:#3c1f5f
    classDef consumer fill:#eeeeee,stroke:#aaaaaa,color:#555555
    classDef external fill:#ffffff,stroke:#999999,color:#000000,stroke-dasharray: 5 5
```
