feat: paired histogram cells in Storybook (DRC-3390 Stage A)

[danyelf]

Summary

Stage A of the DRC-3390 paired-histograms 4-stage restructure. Storybook-only, no API or backend
dependency — reviewers can clone this branch, run Storybook, and visually verify the chart cells in isolation.

Why Stage A first

Lowest-risk PR in the restructure: pure additive component-library work, no integration with SchemaView, no API plumbing, no Python. Reviewable
in parallel with Stage B (which owns the backend + API contract). Supersedes the closed #1391
(lifted verbatim minus the wrapper + hook, which move to Stage C).

Components shipped

• PairedHistogramContinuous — quantile-bin constant-area paired histogram. Bar widths track quantile spans, heights track density, so
  bar area reads as the row-share in that bin. formatValue prop for caller-supplied label formatting.
• PairedHistogramDiscrete — top-K paired histogram with two rendering modes (discriminated on data.mode):
  • mode: "counts" (default): paired bars sized by proportion, gap-on-absent semantics — a value with count 0 on one side simply doesn't
    render, leaving a visible empty half-slot.
  • mode: "ranks": rank-staircase for DuckDB's counts-less approx_top_k payloads. Bar height = (k − rank + 1) / k; slots are
    base-rank-ordered with current-only values appended right. Stable case reads as two matching descending staircases; order changes show as current
    bars zig-zagging against base's smooth descent. Stage B guarantees both-or-neither (no mixed mode).
  • formatValue?: (v: unknown) => string prop for caller-supplied label formatting (NULL handling, numeric abbreviation, date rendering). Stage
    C dispatches per column.type.
• ProfileDistributionUnsupportedBanner — one-time MUI Alert for {status: "unsupported", reason} envelopes (Postgres / MySQL / SQLite / SQL
  Server pre-2022).
• Supporting infrastructure: pairedHistogramCanvas.tsx (shared SVG frame + baseline rule + tooltip formatters), chartColors.ts (theme/palette
  helpers extracted from HistogramChart so the leaf cells don't drag Chart.js into the bundle).

CELL_WIDTH = 140, CELL_HEIGHT = 28 — sized to fit inside the existing SchemaView row (rowHeight = 35).

Test plan

• pnpm install clean.
• pnpm --filter @datarecce/ui type:check — no errors in new files (baseline CSS-module / useTrackLineageRender errors unchanged).
• Vitest: 40 tests pass across the 3 new test files (PairedHistogramContinuous, PairedHistogramDiscrete, ProfileDistributionUnsupportedBanner).
• pnpm --filter @datarecce/storybook build builds clean.
• pnpm --filter @datarecce/storybook storybook (port 6006) — all 12 stories render.
• Visual proofs:
  • Continuous Cell — order amount — bar widths visibly differ across bins (constant-area).
  • Continuous Degenerate range — flat checkerboard, no crash.
  • Discrete Cell — gap-on-absent — literal visual gaps where one side absent.
  • Discrete Cell — trimmed top-K marker — corner "trimmed" marker renders.
  • Storybook toolbar toggles dark theme — bar palette inverts on every story.

Ranked

To reproduce: pnpm install && pnpm --filter @datarecce/storybook storybook from js/, then open Visualizations / Profile Distribution in the Storybook sidebar.

[danyelf]

Cross-linking from the Stage B backend (#1399) — there's a contract inconsistency here we need to settle together before either lands.

PairedHistogramContinuousData takes a single shared binEdges, but the component's premise is constant-area — "bar area reads directly as the proportion of rows in that bin," every bar an equal row-share. That equal-area property only holds when each env is binned on its own quantile edges. The moment base and current share one edge array, at most one of them is constant-area.

The backend can't fix this with a shared array. All we get back from the warehouse is approx percentiles (APPROX_PERCENTILE/approx_quantile) — inverse-CDF sample points per env, not bin counts. There's no way to measure an env's true mass in an arbitrary shared bin. The only assumption-free rendering is each env on its own quantile spans, density = (1/NUM_BINS)/span. Base and current edges genuinely don't line up (base might break at 10/20/40/60/70, current at 5/15/40/50/80) — and that's correct: two independent equal-area staircases overlaid on a shared value axis.

(Related: in Stage B as written, the shared-edge averaging makes base_density and current_density come out byte-for-byte identical — the curves can never diverge. Same root cause.)

Contract both PRs should freeze on:

• payload carries per-env edges — base_bin_edges + current_bin_edges (each length 12) — alongside base_density/current_density (each length 11)
• PairedHistogramContinuousData takes both edge arrays
• the component renders two non-aligned staircases, not aligned paired bars on one x-grid

Purely visual overlay — we're explicitly giving up bin-aligned diffing (no shared "bin 3" to subtract), which is fine for this surface.

I'll update the Stage B backend + API types (#1399) to emit per-env edges; this component, its stories, and the binEdges type need the matching rework.

[gcko]

Code Review: PR #1398

SHA 01662e58 · Verdict GO

Stage A is genuinely low-risk: two new SVG leaf cells, a shared canvas helper, a banner, and a chart-theme/​formatter consolidation. The new components are defensively written (length-mismatch guards, NaN/degenerate-range fallbacks, rank clamping) and the tests cover merged-edge geometry, gap-on-absent, both palettes, degenerate inputs, and tooltip formatting. Verified locally on 01662e58: frozen install ✓; @datarecce/ui type:check introduces 0 new errors (16 baseline CSS-module / useTrackLineageRender errors are identical on main); 75 tests pass across the 4 touched test files; Biome clean (633 files); Storybook build succeeds.

Blockers

None.

Issues

None.

Notes

1. TopKBarChart.tsx:514 — formatIntervalMinMax(proportion) ?? "" is dead defensive code: formatIntervalMinMax (utils/formatters.ts:25) always returns a string, never nullish. The sibling call at :311 correctly omits the ?? "". Harmless, but the inconsistency invites a future reader to assume the function is nullable.
   Pass C.

2. HistogramChart.tsx / TopKBarChart.tsx — the PR is described as "Storybook-only, no API or backend, pure additive," but it also swaps two production charts' local number formatters for the shared formatAsAbbreviatedNumber. This is a real (cosmetic) output change on detail/popover surfaces: e.g. a bin edge of 5 now renders 5 instead of 5.00, and 0 renders 0 instead of 0.00e+0. Percentages are unchanged (formatIntervalMinMax is behaviorally equivalent to the old formatPercentage — verified). No test asserts the new numeric format (the HistogramChart.test.tsx diff only updates imports), and the PR's visual proofs are all Storybook cells, not the affected production charts. The change is an improvement (unifies on the app's canonical formatter), but worth a spot-check of the live HistogramChart/TopKBarChart axis + tooltip rendering before merge, since it falls outside the stated scope.
   Pass F.

---

Checked and cleared: the getChartBarColors/getChartThemeColors/ChartBarColors/ChartThemeColors move out of HistogramChart — all in-repo consumers import from ../../theme; recce-cloud-infra only mocks the two functions (still on the main barrel), and nothing consumes the types dropped from the @datarecce/ui/types subpath. No downstream break. Also cleared: getChartBarColors correctly returns the new required info field; densityAt half-open/closed logic is safe because merged-segment midpoints never coincide with an original edge; degenerate-range fallback can't divide by zero (validity guard ensures n ≥ 1).

[gcko]

GO — 0 blockers, 0 issues, 2 non-blocking notes. Full review: #1398 (comment)