Add Heatmap plot with a grid ↔ stacked-bar pivot

[IPWright83]

Summary

• Adds a self-contained <Heatmap> chart: a grid of cells - one per rows/columns combination in the data - colored by value along a sequential (or diverging) scale. Like <Treemap>, it accepts chart-level props (data/width/height/etc.) directly - no <XYChart>/<XAxis>/<YAxis> wrapper needed - but internally it composes <XYChart> plus real <XAxis>/<YAxis> (via <HeatmapAxes>), since it always needs both a row and a column axis.
• The core feature, based on the "Desk Occupancy Heatmap" Observable notebook (https://observablehq.com/d/2eaec302ac0bbfb4): set pivotable to let the user switch between the full grid and two stacked-bar-chart layouts - "rows" collapses the column axis into a linear scale, stacking each row's cells into a single horizontal bar; "columns" does the same collapsing the row axis instead. Every cell is keyed by its row/column pair, so pivoting transitions each one to its new position/size rather than re-creating it.
• The pivot is switched via the "Pivot" action on the chart's right-click <ContextMenu> (previously a stub added in Add a pluggable radial ContextMenu component #266) - wired up to real pivotable/pivot chart-level state in @chart-io/core, mirroring how zoomable/zoom back <Treemap zoomable>.
• Pass an odd-length colors palette (3, 5, ...) - e.g. for a correlation matrix - and the color scale centers on 0 instead of the data's own midpoint, so equal-and-opposite values get equally saturated, opposite colors.
• Includes Storybook stories + MDX docs (Charts/Miscellaneous/Heatmap) covering the basic grid, Canvas rendering, the pivot toggle, a Desk Occupancy example matching the notebook, and a correlation-matrix example (diverging colors), plus unit tests for <Heatmap>, <HeatmapAxes>, <HeatmapPlot> and the new pivotable/pivot store state.

Test plan

• pnpm --filter @chart-io/core types / pnpm --filter @chart-io/react types (tsc --noEmit) pass
• pnpm --filter @chart-io/core lint / pnpm --filter @chart-io/react lint (eslint) pass with no errors
• Full @chart-io/core unit test suite passes (270/270)
• Full @chart-io/react unit test suite passes (471/471), including Heatmap.unit.tsx, HeatmapAxes.unit.tsx, HeatmapPlot.unit.tsx and the createPivotAction/pivotable/pivot tests
• Manual check in Storybook (Charts/Miscellaneous/Heatmap) - Basic, Canvas, Pivotable, Desk Occupancy and Correlation Matrix stories
• Chromatic baselines for the new stories accepted

[changeset-bot]

🦋 Changeset detected

Latest commit: 7be174c

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@chart-io/core	Minor
@chart-io/react	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[IPWright83]

Thanks for the detailed review, and for pulling the notebook source - that made everything unambiguous. Pushed a rework addressing all of it:

• Rebuilt around the actual pivot mechanic, not clustering. The notebook shares one d3 update pattern across three layouts: the full grid, each row collapsed into a stacked horizontal bar (column axis → linear), each column collapsed into a stacked vertical bar (row axis → linear). <Heatmap pivotable> now does exactly that via pivot: "grid" | "rows" | "columns".
• Uses real <XAxis>/<YAxis> with band scales (switching to a linear scale over value on whichever axis is pivoted away) instead of hand-rolled band positions and text labels. <Heatmap> still stays a single self-contained component though (like <Treemap>) - it composes <XYChart> + a new <HeatmapAxes> + <HeatmapPlot> internally, so nobody has to wire that up themselves.
• Pivot state lives in the store, mirroring the existing zoom/zoomable pattern (pivotable/pivot on IChartState, setPivotable/setPivot actions) - a usePivot hook and a <PivotControl> overlay (mirroring <ZoomBreadcrumb>) sit on top of that.
• Dropped the padding prop - cells are sized straight from the band scale now, same as everything else.
• Added a real gradient legend (<HeatmapLegend>), and colors: an odd-length palette (3, 5, ...) is now treated as diverging and centers on 0 rather than the data's midpoint - added a Correlation Matrix story to show that off, plus a like-for-like recreation of the notebook's own desk-occupancy dataset so the two can be compared directly.
• One thing worth flagging: getting <HeatmapAxes> right surfaced a real render/dispatch loop - if the same component both renders <XAxis>/<YAxis> and reads the scale those axes register, it re-renders itself into re-registering that scale forever. <HeatmapAxes> only reads pivot/data now, never the scale it produces; <HeatmapPlot> reads the scale but doesn't touch the axis elements. Also merged in master (Sankey/Chord) and swapped onto the new shared RectsPlot rather than keeping my own duplicate of it.

Still on colors - I kept it as an optional override (defaulting fully to the theme, 2-stop background→series-color) rather than removing it, since without it there's no way to express a diverging palette. Let me know if you'd rather see that done differently.

---

Generated by Claude Code

[IPWright83]

Addressing two open review comments (couldn't reply inline directly - the force-pushed rebases seem to have made GitHub treat their original diff context as invalid for direct replies):

1. "Could we instead pivot on the field (the x, y, or undefined for the grid)" - Done. IPivot is now "x" | "y", with pivot: undefined meaning the full grid, rather than "grid" | "rows" | "columns". It's generic to which axis is collapsed into a linear scale, not tied to <Heatmap>'s own rows/columns field names, so the pivotable/pivot store state and the <ContextMenu>'s "Pivot" action (which lives in @chart-io/core, not Heatmap-specific) can be reused by other chart types later. <Heatmap>'s own heatmapAxisFor maps "x" → the column axis collapses (each row becomes a horizontal bar) and "y" → the row axis collapses (each column becomes a vertical bar) - same behavior as before, just renamed at the state/action layer.

2. "We're going to do the pivot a different way, take this out for now" (on <PivotControl>) - Done. <PivotControl> has been removed entirely. The pivot is now switched via the "Pivot" action on the chart's right-click <ContextMenu> instead, since that's already wired up to the store for every <XYChart>/<RadialChart> - no need for a bespoke overlay component.

---

Generated by Claude Code

[IPWright83]

Re the "UI Tests"/"UI Review" failure statuses on this and prior commits: the underlying chromatic GitHub Actions job itself completes successfully each time (build/upload works fine) - the "failure" is Chromatic's own status check reporting that the new/changed Heatmap stories (Basic, Canvas, Pivotable, Desk Occupancy, Correlation Matrix) have no accepted baseline yet, which is expected for brand-new stories and already called out as an open item in this PR's test plan. There's no code fix for that - it just needs a human to review and accept the baselines at the Chromatic review link in the check. I'll keep watching for any other CI issues, but this specific status is blocked on that review rather than on anything in the PR.

---

Generated by Claude Code

[IPWright83]

Moved the color scale to be embedded at the bottom of the chart's <Legend>, matching the <ZAxis> size-legend convention, instead of rendering as a fixed gradient bar under the plot:

• Added useColorLegend (mirroring useSizeLegend) plus colorLegend/setColorLegend/clearColorLegend store state in @chart-io/core, alongside the existing sizeLegend.
• Added <ColorLegend> under LegendOverlay/Legend/, rendered by <Legend> right alongside <SizeLegend> with the same divider styling.
• <HeatmapPlot> now registers the palette/domain via useColorLegend (only in the full grid layout) instead of rendering its own <HeatmapLegend>, which has been removed.
• Updated tests/stories/docs accordingly.

---

Generated by Claude Code

[IPWright83]

Pushed 9f0069d with two fixes:

1. Chromatic crash fixed - the Pivotable story's play function clicked the "Pivot" context-menu item synchronously right after opening the menu, but the menu renders imperatively via D3 inside a useEffect and can take an extra tick to appear under a real browser. That's exactly the TypeError: Cannot read properties of undefined (reading 'querySelector') you saw. Now it polls briefly for the item before clicking, mirroring the same fix already in Heatmap.unit.tsx.

2. Legend now defaults to SE for <Heatmap> - added a legendPosition prop (XYChart → LegendOverlay) so <Heatmap> docks its Legend at "SE" by default instead of <XYChart>'s usual "E", with the option to override via the prop. This surfaced a real bug along the way: <LegendOverlay> distinguishes "never dragged" from "dragged to E" by reading the raw store value directly, but defaultChartState.legend.position was hardcoded to "E" rather than undefined, so that check always short-circuited and any default-position prop was silently ignored. Fixed by seeding it undefined instead - chartSelectors.legend.position's own ?? "E" fallback still covers every other caller.

Full core (291) and react (505) suites pass, along with tsc --noEmit and eslint on both packages.

---

Generated by Claude Code

[IPWright83]

Could we get a stories with the pivoted data, and a story for the menu with the pivot/column or row selection

[IPWright83]

Pushed 1a88a86 with three new stories:

• "Pivoted to Rows" / "Pivoted to Columns" - each layout shown at rest (the play function pivots once/twice and stops there), rather than mid-cycle like the existing "Pivotable" story.
• "Pivot Context-Menu Action" - right-clicks the chart and leaves the menu open (rather than selecting anything), so the "Pivot: ..." action is visible for review alongside the other menu items - same at-rest-menu convention <ContextMenuOverlay>'s own stories already use.

Verified all four Heatmap stories with play functions (including the two pre-existing ones) against a real headless-Chromium build of Storybook - no thrown exceptions, and the DOM state after each play function matches what's expected (varying cell widths/heights per pivot, the "Pivot: x" menu item visible and correctly labelled).

---

Generated by Claude Code

[IPWright83]

When pivoting, all the sections contributing to the bar or column should be the same colour. We need to lose the colour part of the scale.

The pivot menu can be tested in isolation as a menu story, rather than via the heatmap. But I expected a clear pivot icon (currently looks like a refresh? With a 2nd layer of segments like an outer tier in a stacked donut for rows or columns - I'm not seeing that)

[IPWright83]

Pushed 71d66af addressing all three points:

1. Flat color when pivoted - found the actual bug: useHeatmapLayout's cell coloring always ran every cell's value through the value-based gradient, regardless of pivot state, so each segment of a stacked bar kept its own shade. Now, once pivoted, every cell renders in one flat color (the palette's "high" stop, so a custom colors prop still carries through) - the bar's height/width already encodes the value, so per-segment shading was redundant. Added a unit test asserting all segments share one fill once pivoted.

2. Pivot menu in isolation - moved it out of the Heatmap stories into ContextMenuOverlay's own stories as "Pivot Action". Turns out pivotable is dispatched by a small hook (usePivot) rather than being a generic chart prop, so the isolated story just calls that hook directly on a plain <Bar> chart - no <Heatmap> needed to see the menu item. Also fixed a stale doc line in ContextMenu.mdx that still called Pivot "a stub" from before it was wired up.

3. Icon - replaced the two-curved-arrows "refresh" glyph with two separate cells folding into one bar divided into their segments, matching what the action actually does. This is a first pass at the icon - happy to iterate further if the shape doesn't land, since icon design is inherently a matter of taste. I verified it renders distinctly from the other menu icons at the real 18px size (screenshot below).

Verified all three changes against a real headless-Chromium build of Storybook: the pivoted stories now show a single flat fill across all cells, and the isolated Pivot Action story opens correctly with the new icon visible. Full core (291) and react (506) suites pass, tsc --noEmit/eslint clean on both packages.

---

Generated by Claude Code

[IPWright83]

Pushed 104f83b, per your sketch:

• Restored the original two-curved-arrows "Pivot" icon.
• Added a new general IContextMenuItem.activeIcon field (not Pivot-specific) - an alternate icon that crossfades in over the resting one while a segment is hovered, so any action can reveal more detail without cluttering its resting state. createPivotAction sets this to two small bars, hinting at the stacked-bar result.
• Added a "Pivot Action (Hovered)" story to ContextMenuOverlay's stories so the hovered state renders for review without anyone needing to actually hold the mouse over it.

Along the way I found and fixed a real race: a menu's icon fades in via its own animation right when the menu opens, and if a hover landed inside that same ~220ms window, it would silently overwrite the crossfade once that animation finished - the segment would end up stuck showing the resting icon even while "active". Fixed with a .interrupt() call, with a regression test that fails without it and passes with it.

Screenshot of the hovered state:

Resting: arrows icon, unchanged from before.
Hovered: crossfades to two bars, matching your sketch's "something over the active segment" idea.

Full core (294) and react (506) suites pass, tsc --noEmit/eslint clean on both packages.

---

Generated by Claude Code

[IPWright83]

Pushed 13bed0c fixing the rendering artifacts on pivoted bars (the "Industry" bar screenshot). Found three compounding causes, all specific to a pivoted Heatmap's edge-to-edge stacked segments (never visible in the grid, since cells aren't adjacent there):

1. Fractional-pixel seams - each segment's start/end were scaled independently from cumulative sums, which can each land on a different fractional pixel even though mathematically contiguous. Two SVG rects meeting at a fractional boundary render with a hairline anti-aliased seam. Fixed by rounding both sides through the same function so adjacent segments always share the identical pixel edge.
2. Rounded-corner notches - cornerRadius was applied to every segment individually, leaving a rounded notch at every internal boundary once packed edge-to-edge into one bar. Fixed by zeroing it out once pivoted.
3. That fix had no effect at first - <RectsPlot> only ever set rx/ry on newly-entering rects, never on ones already on screen. Since Heatmap's cells persist and transition across a pivot rather than being recreated, a changed cornerRadius was silently ignored on every existing cell. Fixed by also applying it on the merged enter+update selection - a real, separate bug in RectsPlot itself, not Heatmap-specific.

I isolated each cause with before/after screenshots against a real headless-Chromium build of Storybook before fixing all three (screenshot attached to confirm the "Industry" bar specifically). Full react suite (508 tests, +4 new covering each fix) passes, tsc --noEmit/eslint clean.

---

Generated by Claude Code

[IPWright83]

Pushed 5ce8602 and 53e3bcf addressing both points:

1. Real outer-tier segment, not an icon swap (5ce8602) - you were right, the previous version just crossfaded the icon glyph. Replaced IContextMenuItem.activeIcon with a general activeSegments capability: the number of equal-width mini arcs to reveal as an extra ring band just outside a segment's own arc while it's hovered, matching a stacked donut's outer tier from your sketch. createPivotAction sets this to 2 (for the two collapsed-axis layouts pivoting cycles between). The base "Pivot" icon (the two arrows) stays as-is at rest and on hover - only the new band appears/disappears now. Screenshot attached showing it live.

2. Pivot on left-click of a datum (53e3bcf) - left-clicking any Heatmap cell now advances the pivot by one step (grid -> rows -> columns -> grid), the same cycle the context-menu "Pivot" action drives - a quicker path to the same thing rather than a separate mechanism. Stays a no-op unless pivotable is set. Extracted the cycle order into a shared nextPivot utility so both triggers agree.

Verified both against a real headless-Chromium build of Storybook (not just Jest) - the outer band renders correctly and is absent at rest, and left-clicking a cell pivots it live with no console errors. Full core (295) and react (510) suites pass, tsc --noEmit/eslint clean on both packages.

---

Generated by Claude Code

[IPWright83]

Pushed c5d0f6d addressing all four points:

1. Desk Occupancy references removed - the large-dataset Heatmap story is now "Weekly Pattern" with its value field renamed occupancy -> level, and the Observable-notebook mentions dropped from both the story and the docs.
2. Pivot added to the datum menu - getDefaultDatumItems now includes it, same as the background menu. Needed a small signature change (now takes state) so it can compute its disabled/label state. Screenshot attached showing it enabled in the "Click a Bar" story.
3. Icons on the 2nd-tier mini segments - activeSegments was a bare count with nothing to distinguish one mini segment from another. Changed it to an array of icons instead - a horizontal-bar icon for "rows" and a vertical-bar icon for "columns", each centered in its own mini segment. Screenshot attached.
4. "Cancel pivot" story added - "Pivot Action (Cancel)" in ContextMenuOverlay's stories, pre-pivoted to "y" on mount so the label reads "Pivot: grid". Same plain-Bar-chart convention as the other Pivot stories, no <Heatmap> in the background.

Verified all four against a real headless-Chromium build of Storybook. Full core (296) and react (510) suites pass, tsc --noEmit/eslint clean on both packages.

---

Generated by Claude Code

[IPWright83]

Pushed faf11f0, addressing the latest icon-legibility feedback:

Redesigned the Pivot action's mini icons
The single-rectangle pivotRows/pivotColumns icons weren't reading clearly at their size. Each is now three bars of increasing length/height capped with arrowheads, so they read as a growing bar/column chart rather than an ambiguous block. Since the outer active-segment band is a menu hint (not real data), it's no longer space-constrained to match the main ring's proportions — ACTIVE_BAND_THICKNESS went 12→26px and MINI_ICON_SIZE 9→22px, with ACTIVE_BAND_GAP nudged 3→4px.

Added a cancel state
Once pivot === "y" (already collapsed to columns), selecting Pivot again cycles back to the grid rather than collapsing further. createPivotAction now swaps the columns slot for a new pivotCancel (✕) icon in that state, so hovering shows the same two nested items with one replaced by a cross — matching what pivoting back to the grid actually does. The PivotActionCancel story now hovers the Pivot item automatically in its own play function, so the state is visible without manual interaction.

Verified both against a real headless-Chromium render of the built Storybook (not just Jest/jsdom) — screenshots attached to the conversation. Full suites green: core 297 tests, react 510 tests, typecheck and lint clean (a pre-existing moduleResolution=node10 deprecation warning in core's typecheck is unrelated to this change — reproduces on c5d0f6d too).

---

Generated by Claude Code

[IPWright83]

Pushed 2171c0f - removed the arrowheads from the pivotRows/pivotColumns icons, leaving just the plain bars. They read clearly as a growing bar/column chart on their own. Verified against a real headless-Chromium render of Storybook, screenshots attached to the conversation. Core suite still green (297 tests) and lint clean.

---

Generated by Claude Code

[IPWright83]

Pushed 86b39fb, addressing four issues from this round of review:

1. Janky pivot animation
Root-caused via a real-browser timing trace: HeatmapPlot recreated its cell handlers (onMouseOver/onMouseOut/onClick) and an inline cursor prop on every render, not just when the pivot changed. <RectsPlot>'s D3 join restarts its whole position transition whenever those props change identity, so an entirely unrelated re-render — e.g. hovering a cell while the grid was still animating into a bar chart — would interrupt and restart the transition mid-flight. A width trace confirmed two overlapping ~250ms transitions instead of one (a plateau-then-slow-decay stutter). Fixed by stabilizing the handlers with a "latest ref" pattern and memoizing cursor, so only a real pivot/data change retriggers the transition. Confirmed clean via the same trace method - now a single smooth decay start-to-finish.

2. Clicking a bar/column now also shows the menu
Left-clicking a Heatmap cell already advanced the pivot; it now also opens the same datum <ContextMenu> every other interactive plot's left-click wires up, via the shared useDatumContextMenu hook - same click, same instant pivot, plus the rest of the datum actions.

3. Thicker/more padded pivot icons
Increased the pivotRows/pivotColumns/pivotCancel bar stroke-width and inset them further from the mini-icon's edges.

4. Fixed the hover gap between the Pivot wedge and its sub-icon band
The active-segments band sits a few pixels outside the main wedge; moving the pointer from one to the other crossed that unpainted gap, which read as leaving the item and hid the band before it was reached. Added an invisible hover-bridge spanning the gap, sharing the wedge's own hover state - verified via a real-browser event trace and a new regression test.

All four verified against a real headless-Chromium render of Storybook (screenshots attached to the conversation). Full suites green - core 298 tests (including a new bridge-continuity regression test), react 510 - typecheck and lint clean.

---

Generated by Claude Code

[IPWright83]

Pushed 7be174c, fixing the race you hit: tapping a bar on the Pivotable story pivoted before you could pick a menu option.

The previous commit added "click opens the datum menu" alongside the existing "click also pivots instantly" behavior - but both firing on the same click meant the layout had already changed by the time the menu was there to choose from.

Removed the direct pivot-on-click entirely. Now a cell's left-click only opens its datum menu; selecting "Pivot" from that menu is what actually changes the layout - the same as the right-click background menu, and consistent with every other interactive plot's left-click behavior.

Verified in a real browser: after clicking a cell, the chart stays in the grid (uniform cell widths) with the menu open showing "Pivot: x" - only clicking that menu item actually pivots (varied widths, menu closes). Updated the two Heatmap.unit.tsx tests that asserted the old instant-pivot behavior, plus the docs/comments describing it. Full suites green (react 511, core 298), typecheck and lint clean.

---

Generated by Claude Code