pivot table · model + canvas

Fold multidimensional data
into a 2D table

Aggregation produces one row per dimension combination; a matrix transform maps member indices to [x, y]; Canvas draws only the cells inside the viewport. Model, layout, and rendering stay independent.

  • Zero dependencies
  • Matrix layout
  • Viewport virtualization
  • Multi-level headers
  • ES Modules
Core modules
2
Runtime dependencies
0
Draw cost
O(visible cells)
Stress grid
150×150

02 · pipeline

One core data flow, one set of extension mounts

Aggregation, layout, geometry, and rendering are independent. Built-in and example features attach between stages or after rendering, and new capabilities reuse the same mount points.

Core stage Built-in / example feature Extension mount point
  1. 01

    Detail rows

    Input

    Business detail rows, not yet aggregated. Each row is one raw record.

    rows[]rows[]
    Mount point Filter / sort· preprocessing (planned)
  2. 02

    aggregate

    Aggregate

    Group by dimension keys, keep one row per combination, and compute count / sum / avg / min / max.

    rows[]cube.rows[]
    Mount point dual-measure· combineMeasures() Custom measures / rollup· derived cube
  3. 03

    layoutPivot

    Layout

    Encode member values as indices, derive integer grid coordinates through an affine matrix, and build recursively renderable headers.

    cube.rows[]layout
    Mount point totals· rollupTotals(cube) + withTotals(layout) collapse· collapseCube() + header interaction Display layout derivation· sorting / merging / custom derivation
  4. 04

    computePivotGeometry

    Geometry

    Compute screen rectangles, visible range, and clip regions from the viewport and scroll offset; never touches Canvas.

    layoutgeometry
    Mount point viewport / overscan· header size
  5. 05

    renderPivot

    Render

    Draw background, grid lines, text, and frozen headers; iterate only over cells inside the viewport.

    layout + geometryCanvas
    Mount point heatmap· cellStyle overlay· renderWithOverlay() scrollbar· post-render overlay + auto-hide cell-marker· example feature (cellStyle + overlay) formatValue / theme· render config
Interaction loop scrollX / scrollY changes → recompute geometry → redraw Hit testing / collapse / drill-down → re-enter collapseCube, aggregate, or layoutPivot
The core does not depend on features. Dependencies always point from site / features → model / render; features only read core output and extend it through the mount points above. An architecture guard test blocks the core from importing features in reverse.

03 · matrix transform

One matrix multiplication locates every cell

A dimension hierarchy is a mixed-radix number: parents position coarsely, and children position finely inside the parent block. The whole tree collapses into one fixed matrix.

A record becomes an augmented vector. Each dimension contributes a member index id, followed by a constant 1:

v = [i₁, i₂, ..., i_D, 1]ᵀ

Column d of matrix M is the unit vector of that dimension axis scaled by spand; the last column is the translation:

[x, y]ᵀ = M · v

Parent and child spans multiply. Each step of a parent dimension crosses exactly the child member count times the child span:

span_parent = n_child × span_child
span_d      = Π n_c (c is a descendant of d)

cartesian Default

Every parent member is padded with the full global set of child members, forming a regular grid. The span is independent of the parent, so the entire layout is one fixed matrix—at the cost of empty cells.

compact Compact

Only combinations that actually occur are placed, so parent blocks vary in size. There is no global fixed matrix, but each record still yields a piecewise affine transform.

  • Header member offset / size maps directly to rowspan / colspan.
  • Duplicate dimension combinations throw by default, forcing aggregation first instead of silently merging in the layout layer.
  • Each axis supports one hierarchy chain: a single root and at most one child per parent.

04 · live demo

Scroll a real pivot table

5 regions, 20 cities, 6 years, and 3 product categories: 867 detail rows aggregate into 288 rows. Headers stay frozen, and only the visible part of the data area is drawn.

Loading…
Demo extensions
Click parent row/column headers to collapse; works with row/column totals and dual measures; unavailable in cartesian mode

Pan with the wheel or drag; drag the right / bottom scrollbar for precise jumps. Scrollbars auto-hide after you stop interacting and stay visible while hovered or dragged; Shift + wheel scrolls horizontally; when the canvas is focused, use the arrow keys, PageUp / PageDown, Home / End. With dual measures, the heatmap and row/column totals split by measure. Corner labels demonstrate a custom overlay; high-value markers demonstrate a custom feature: cellStyle changes the background and renderWithOverlay draws a corner badge. Collapse mode lets you click parent row/column headers; it works with row/column totals and dual measures, but not cartesian. Row/column subtotals and grand totals are inserted at the end of the region and year dimensions.

05 · performance

Cost follows the viewport, not the whole table

Scrolling iterates only over visible cells; headers are binary-pruned by offset; the canvas buffer is reused while dimensions stay unchanged; heatmap ranges are cached per layout.

22,500 Total cells in the 150×150 stress grid
50 Cells actually drawn in a 480×280 data viewport
1 Heatmap range scan per layout

What the renderer does

  • Viewport virtualization: iterate only the visible range; total cell count never enters the per-frame loop.
  • O(1) cell lookup: the model exposes cellMap.
  • Grid lines are merged into one beginPath() + stroke().
  • Header offsets are monotonic; binary search skips off-screen members and their subtrees.
  • The data area and two header bands are clipped separately, so frozen headers do not trigger a full redraw.
  • DPR transform is set once; the canvas buffer is not reset when dimensions are unchanged.

Trade-offs

  • Canvas 2D · current ~1k–100k cells; zero dependencies, fast batched text and rectangle drawing.
  • Canvas + offscreen cache Large tables with continuous scrolling; cache headers, grid, and zebra-stripe bitmaps.
  • WebGL / WebGPU 100k–1M cells with smooth zoom; text layout and hit testing cost more.
  • DOM / SVG Small tables, text selection, screen readers; performance drops sharply with many nodes.
Read the full rendering pipeline and performance guide

06 · benchmark

Measured locally: 10k to 10M detail rows

Runs the real aggregate + layoutPivot pipeline in a separate Node process for each scale, repeated 3 times, and takes the median total time. At 10M rows the available memory is insufficient, so chunked aggregation is used; the table labels both modes explicitly.

— 1M rows · single transform
— 10M rows · chunked transform
— Peak memory at 1M single run
Rows Generate Aggregate Merge Layout Transform Peak memory Mode
Loading benchmark results…

Benchmark data comes from bench/results.json; the page must be served over HTTP.

How it was measured

  • Loading…

Reading the numbers

  • Aggregation dominates Each order-of-magnitude increase in rows roughly increases aggregation time; single samples are affected by GC and host load.
  • Layout is nearly constant With 1,536 dimension combinations fixed, layout time stays flat regardless of input row count.
  • Chunking keeps 10M rows in memory A single 1M-row run already needs ~250 MB; chunked 10M keeps the peak under 200 MB.

Result file: bench/results.json · Reproduce: node bench/run.mjs · Script: bench/transform.mjs

07 · depth sweep

How long does the matrix transform take as dimensions deepen?

With 1M detail rows fixed, add row dimensions first and then column dimensions, with 2 members per level. The stop condition is the matrix transform (layoutPivot) exceeding 3 seconds; aggregation time and peak memory are recorded too.

— Completed at · row depth / column depth
— Last step · matrix transform
— Last step · peak memory

Loading depth experiment results…

Add row dimensions first (column depth 0)

Row depth Column depth Aggregate Matrix transform Total Peak memory Output
Loading…

Then add column dimensions (row depth 10)

Row depth Column depth Aggregate Matrix transform Total Peak memory Output
Loading…

How it was measured

  • Loading…

Reading the numbers

  • Row depth mainly increases aggregation cost In this run the row grid reached at most 1,024 cells, and the matrix transform took 1.9–25.9 ms; most time went into grouping 1M detail rows.
  • Column depth doubles the grid With the row grid fixed at 1,024, every column level doubles the grid; the matrix transform grew from 75 ms to 2.74 s.
  • Memory hits the limit first Column depth 7 peaked at 744.8 MB; depth 8 OOMed on the 768 MB heap and did not finish, so the 3-second threshold was never reached.

Experiment data comes from bench/depth-results.json; the page must be served over HTTP.

Result file: bench/depth-results.json · Reproduce: node bench/depth-run.mjs · Script: bench/depth-run.mjs

08 · quickstart

Use it directly

No build step and no runtime dependencies. Minimal snippets for each demo feature, ready to copy.

Run locally

node examples/demo.mjs
node --test test/model/*.test.mjs test/render/*.test.mjs \
  test/features/*.test.mjs test/site/*.test.mjs

Browser examples must be served over HTTP; ES modules do not work over file://.

python3 -m http.server 8000
# http://localhost:8000/

Custom features

The core does not depend on features; pick a mount point and write a function that only reads core output.

  1. Pick a mount point Data derivation, layout derivation, render config, or post-render overlay.
  2. Write createXxx() Return cellStyle, draw, or a new display layout.
  3. Pass it to the core renderPivot / renderWithOverlay, without modifying the core.

Mount point docs