Static documentation

Data Visualisation Catalogue Gallery

Rendered markdown notes for the catalogue review, compiler mapping, implementation tracker, and chart method specs.

38 chart methods
10 with reference assets
43 documents
DashboardCompiler

System Docs

Compiler Schema System Overview

Overview

Data Visualisation Catalogue Gallery Review

Chart Methods

Arc DiagramArea GraphBar ChartBubble ChartBullet GraphCalendarCandlestick ChartCircle PackingDensity PlotDonut ChartDot Matrix ChartError BarsGantt ChartHeatmapHistogramLine GraphMarimekko ChartMulti-set Bar ChartNightingale Rose ChartOpen-high-low-close ChartParallel Coordinates PlotPie ChartPopulation PyramidProportional Area ChartRadar ChartRadial Bar ChartRadial Column ChartScatterplotSpan ChartStacked Area GraphStacked Bar GraphStream GraphSunburst DiagramTimelineTimetableTree DiagramTreemapViolin Plot

Project Notes

Chart Catalogue Implementation TrackerChart Compiler Gap Analysis For The Data Visualisation CataloguePolar-Axis And Arc Layout PassStatistical And Financial Interval Pass

Polar-Axis And Arc Layout Pass

Date: 2026-05-12

Scope And Context

The request was to attack the most useful remaining items in compiler-gap-analysis.md, keep that document current, update the compiler gallery, and add missing Data Visualisation Catalogue charts that depend on the new capabilities.

This pass targeted the next practical non-Cartesian/link gaps after the existing hierarchy, polar-sector, bullet, parallel-coordinate, and timetable work: first-pass polar-axis layouts and first-pass edge-list arc diagrams.

Major Changes Delivered

  • Added focused polar layout executors in app/src/lib/viz/compiler/polar-layouts.ts:
    • radarAxes
    • radarRings
    • radarPolygons
    • radarPoints
    • radialBars
  • Added focused edge-list layout executors in app/src/lib/viz/compiler/network-layouts.ts:
    • arcDiagramNodes
    • arcDiagramLinks
  • Extended the transform option surface in app/src/lib/viz/compiler/spec.ts with source/target fields, max-value hints, and the new layout kinds.
  • Registered transform execution in app/src/lib/viz/compiler/transforms.ts.
  • Added compiler gallery specs:
    • app/src/lib/viz/compiler/gallery-specs/arc-diagram.ts
    • app/src/lib/viz/compiler/gallery-specs/radar-chart.ts
    • app/src/lib/viz/compiler/gallery-specs/radial-bar-chart.ts
  • Registered the new routes in app/src/lib/viz/compiler/gallery-specs.ts and the gallery kind union in app/src/lib/viz/compiler/gallery-specs/types.ts.
  • Added docs:
  • Updated README.md, implementation-tracker.md, and compiler-gap-analysis.md.

Intentionally unchanged: general polar coordinate systems, production graph layout, Sankey/chord/ribbon geometry, geographic projection, and label collision handling remain follow-up work.

Design Decisions And Tradeoffs

  • Decision: use focused layout modes instead of adding a broad coordinate-system abstraction.
    • Alternative: introduce a general polar coordinate system now.
    • Why chosen: the current compiler pattern already uses focused layout executors, and these charts can ship useful derived tables without destabilizing scale resolution.
    • Tradeoff: radar/radial behavior is duplicated in focused helpers until a general coordinate-system layer exists.
  • Decision: emit direct pathD rows for radar rings, radar polygons, radial bars, tracks, and arc links.
    • Alternative: expand the path glyph API with radial generators immediately.
    • Why chosen: direct compiler-generated path data is already inspectable and used by polar sectors, tree links, sunburst sectors, and violins.
    • Tradeoff: reusable path semantics are still implicit in layout output rather than first-class generator specs.
  • Decision: mark Arc Diagram as partial in the tracker.
    • Alternative: call it implemented because it renders in the gallery.
    • Why chosen: node ordering, directed edge styling, and general graph policies are still too limited for broader arc-diagram fidelity.

Problems Encountered And Resolutions

  • Symptom: starting pnpm -C app dev inside the sandbox failed with Unable to find a random port on any host.
    • Root cause: Vinxi port allocation did not work in the sandboxed run.
    • Resolution: reran pnpm -C app dev --port 3007 with approved escalation and used that server for browser smoke testing.
    • Preventative action: when browser verification is needed for Vinxi routes and sandbox port allocation fails, rerun the same dev-server command outside the sandbox rather than trying unrelated workarounds.
  • Symptom: browser body text matched /Error/ during a smoke check.
    • Root cause: the gallery navigation includes chart names such as Error Bars, so body-text matching was too broad.
    • Resolution: verified route headings, SVG glyph counts, and browser console severity instead.
    • Preventative action: prefer console logs and specific visible route labels over broad body regex checks.

Verification And Validation

  • pnpm -C app type-check: passed.
  • pnpm -C app test: passed, 19 tests.
  • Browser smoke test at http://localhost:3007/_internal/chart-compiler/*: passed for arcDiagram, radarChart, and radialBarChart.
  • Browser console severity check: no warnings or errors reported for the new routes.
  • Dev server was stopped after verification.

Validation not run: screenshot-by-screenshot visual critique was not performed. The smoke test verified rendered SVG surfaces and console health, but dense label placement should still be reviewed visually before treating the charts as polished examples.

Process Improvements

  • Use the living gap document as a prioritization board, then immediately update it with implemented evidence before final verification.
  • Keep each new catalogue chart backed by raw data rows plus a transform-output test proving geometry is compiler-derived.
  • For local route smoke tests, first try existing servers only if they respond; otherwise start a dedicated known port and stop it after verification.

Agent And Skill Improvements

  • Current pain: browser route smoke tests can produce false positives when body text contains unrelated chart names.
    • Proposed change: add a compiler-gallery smoke checklist that checks route-specific heading text, SVG glyph counts, and browser console severity separately.
    • Expected benefit: less noise in manual validation and clearer verification logs.
    • Suggested owner/place: post-work-doc-playbook or a chart-gallery-specific local skill.
  • Current pain: repeated focused layout executors are useful but can accumulate into a large transform surface.
    • Proposed change: add an AGENTS note that new focused catalogue layout modes should include a stated generalization path.
    • Expected benefit: preserves momentum while avoiding a permanent pile of one-off layout names.
    • Suggested owner/place: repository AGENTS.md chart compiler guidance.

Follow-Ups And Open Risks

  • High: generalize radar*, radialBars, and polarSectors into a reusable polar/radial coordinate-system layer.
  • High: add richer label collision and guide policies for radar axes, radial bars, and arc node labels.
  • Medium: generalize arc-diagram node/link layout into a typed edge-list model.
  • Medium: add directed edge styling or arrow/marker support for arc diagrams.
  • Medium: add screenshot-based visual review for the three new gallery routes.