How observablehq/inputs works
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.