gampleman/elm-visualization

Purpose and Package Boundary

elm-visualization is an Elm library of composable data-visualization primitives, not a prebuilt charting framework. Consumers retain rendering ownership (typically SVG through external Elm packages) and compose this package’s data transforms, layout algorithms, interaction state, and path/axis generation. Library modules are rooted in src/; package metadata is elm.json.

Public Building Blocks

Scales convert data domains into visual ranges and are the central bridge from data to geometry/color: src/Scale.elm, src/Scale/Continuous.elm, src/Scale/Band.elm. Axis derives tick and label geometry from scales in src/Axis.elm. Shape generation creates chart paths and derived series geometry—lines/areas, arcs/pies, and stacks—through src/Shape.elm, src/Shape/Generators.elm, src/Shape/Pie.elm.

Data Preparation and Analysis

Data can be reduced before rendering with histogram binning and statistical functions: src/Histogram.elm, src/Histogram/Array.elm, src/Statistics.elm. Color-space and generic interpolation support continuous color/value mapping and intermediate values: src/Color/Lab.elm, src/Interpolation.elm. These modules are pure transformations; application code supplies source data and decides how results become DOM/SVG.

Layout Engines

Force simulation lays out graph nodes using composable physical forces, collision handling, and a quadtree acceleration structure: src/Force.elm, src/Force/Collision.elm, src/Force/QuadTree.elm. Hierarchical layouts transform trees into node positions and partitions for tidy trees, treemaps, and sunbursts: src/Hierarchy.elm, src/Hierarchy/Tidy.elm, src/Hierarchy/Treemap.elm.

Interaction, View State, and Animation

Interactive selection is modeled by brush operations in src/Brush.elm. Pan/zoom maintains and applies transforms via src/Zoom.elm, src/Zoom/Transform.elm, and src/Zoom/Matrix.elm. Event helpers in src/Events.elm connect rendered elements to Elm application messages. Animation is composed from interpolation and transition orchestration in src/Transition.elm and src/Interpolation.elm; consumers integrate outputs into their Elm update/subscription lifecycle.

Integration Flow and Runtime Boundaries

A typical consumer flow is: ingest application data → aggregate/layout (Histogram, Statistics, Hierarchy, or Force) → map values through Scale → generate axes/shapes → render with an external typed SVG/DOM package → feed pointer events through Events, Brush, or Zoom back into Elm state. The package itself has no backend, database, or browser-side service dependency. Material ecosystem boundaries named by the project are Elm runtime/compiler plus external packages for Color, typed SVG rendering, SVG path types, and rose trees.

Executable Entry Points and Delivery

There is no single application entry point; exported src modules are the product. Runnable reference applications are individual Elm example modules such as examples/LineChart.elm, examples/ForceDirectedGraph.elm, and examples/Treemap.elm, configured by examples/elm.json. Documentation is an Elm application rooted at docs/Docs.elm with docs/elm.json; examples/docs are deployed through Netlify configuration in netlify.toml. CI is defined in .github/workflows/ci.yml.