basalt-ui 1.27.0 → 1.29.0

package/src/charts/kinds/Bars.tsx

@@ -1,15 +1,18 @@
-import { curveMonotoneX } from '@visx/curve'
 import { LinePath } from '@visx/shape'
 import { memo, useMemo } from 'react'
+import { assertRequiredProps } from '../../common/validate'
+import type { BasaltProps } from '../../common/props'
 import type { CursorResolution } from '../cursor/resolve'
 import { VX } from '../../tokens'
 import type { ChartMargin } from '../../tokens'
 import { CartesianChart } from '../primitives/CartesianChart'
 import type { AxisConfig, CartesianTooltipConfig, PlotContext } from '../primitives/CartesianChart'
 import type { ZoneSpec } from '../primitives/ZoneRects'
-import { LINE_OVERLAY_STROKE_WIDTH } from '../series'
-import type { ChartLegendConfig, ChartSeries } from '../series'
+import type { ChartState } from '../primitives/ChartPending'
+import { curveFor, LINE_OVERLAY_STROKE_WIDTH } from '../series'
+import type { ChartLegendConfig, ChartSeries, SeriesCurve } from '../series'
 import { padAutoLower } from '../utils/domain'
+import { isDev } from '../../common/is-dev'
 
 /**
  * `T = unknown` is load-bearing, not a shortcut: it keeps a consumer's existing
@@ -48,11 +51,10 @@ export type BarsLine<T = unknown> = {
   tooltip?: boolean
   /** Dims the plotted stroke AND the legend swatch, never the tooltip row (`SeriesStyle.strokeOpacity`). */
   strokeOpacity?: number
+  /** Interpolation for this overlay. Default `'monotone'` — see `SeriesCurve`. */
+  curve?: SeriesCurve
 }
 
-/** @deprecated Use ZoneSpec from primitives/ZoneRects. Kept as an alias. */
-export type BarsZone = ZoneSpec
-
 export type BarsRefLine = {
   value: number
   color: string
@@ -61,7 +63,7 @@ export type BarsRefLine = {
   axisSide?: 'left' | 'right'
 }
 
-export type BarsProps<T> = {
+export type BarsProps<T> = BasaltProps & {
   data: T[]
   /** Fixed height in pixels, forwarded to `CartesianChart`. Default 240. */
   height?: number
@@ -79,7 +81,7 @@ export type BarsProps<T> = {
   lines?: BarsLine<T>[]
 
   /** Horizontal value-range overlays (target zones, optimal bands). */
-  zones?: BarsZone[]
+  zones?: ZoneSpec[]
   /** Dashed/solid horizontal reference lines. */
   refLines?: BarsRefLine[]
 
@@ -115,6 +117,9 @@ export type BarsProps<T> = {
   xTickValues?: (keys: readonly string[], xMax: number) => readonly string[]
   /** X tick label formatter. Default `fmtAxisDate` (DD.MM). */
   formatX?: (key: string) => string
+  /** Tilt the x tick labels 45° or 90°, or `0` to opt out of the phone tier's auto-rotation —
+   * see `CartesianChartProps.xLabelRotate`. */
+  xLabelRotate?: 0 | 45 | 90
   /**
    * How a sibling chart's broadcast cursor key resolves against this chart's points. Default
    * `'nearest'`. Pass `'leading'` when `getX` returns a bucket's leading edge (a weekly series
@@ -133,6 +138,9 @@ export type BarsProps<T> = {
   ariaLabel?: string
   /** Forwarded to `CartesianChart` — see `ChartPending`'s JSDoc for the three-state rationale. */
   isPending?: boolean
+  /** The three "nothing to draw" states in one prop — pending → error → empty. See
+   * `ChartState`; `isPending` stays a supported alias for `state={{ pending: true }}`. */
+  state?: ChartState
 }
 
 /**
@@ -148,6 +156,10 @@ export type BarsProps<T> = {
  * with per-bar nulls (nulls become visual gaps, not domain holes).
  */
 function BarsInner<T>(props: BarsProps<T>) {
+  // F-ERR-1: name the component and the prop. Without this a missing accessor surfaces
+  // from inside visx as `undefined is not a function`, which `BasaltErrorBoundary`
+  // swallows into a blank subtree that names nothing.
+  assertRequiredProps('Bars', props, ['data', 'getX', 'getValue', 'positiveBars'])
   const {
     data,
     height,
@@ -167,14 +179,28 @@ function BarsInner<T>(props: BarsProps<T>) {
     xTicks,
     xTickValues,
     formatX,
+    xLabelRotate,
     cursorResolution,
     tooltip,
     margin,
     legend,
     ariaLabel,
     isPending,
+    state,
+    className,
+    style,
   } = props
 
+  // Stacking sums bar heights via `posOffset`/`negOffset` in yScale units directly — a log axis
+  // has no additive zero, so a stacked total is meaningless on it (`docs/CHARTS-SPEC.md`'s null-gap
+  // + log contract). `grouped` bars only ever read one bar's own scaled value, so they're unaffected.
+  if (isDev() && barLayout === 'stacked' && y?.scale === 'log') {
+    throw new Error(
+      'Bars: stacked bars cannot use a log axis (y.scale: "log") — the stack sums bar heights, ' +
+        "and a log axis has no additive zero to sum from. Use barLayout: 'grouped' instead.",
+    )
+  }
+
   const barSeries = useMemo<ChartSeries<T>[]>(
     () =>
       [...positiveBars, ...negativeBars].map((b) => ({
@@ -287,6 +313,7 @@ function BarsInner<T>(props: BarsProps<T>) {
       {...(xTicks !== undefined && { xTicks })}
       {...(xTickValues !== undefined && { xTickValues })}
       {...(formatX !== undefined && { formatX })}
+      {...(xLabelRotate !== undefined && { xLabelRotate })}
       {...(cursorResolution !== undefined && { cursorResolution })}
       {...(zones !== undefined && { zones })}
       {...(mappedRefLines !== undefined && { refLines: mappedRefLines })}
@@ -296,6 +323,9 @@ function BarsInner<T>(props: BarsProps<T>) {
       {...(margin !== undefined && { margin })}
       {...(ariaLabel !== undefined && { ariaLabel })}
       {...(isPending !== undefined && { isPending })}
+      {...(state !== undefined && { state })}
+      {...(className !== undefined && { className })}
+      {...(style !== undefined && { style })}
     >
       {(ctx) => (
         <BarsMarks
@@ -368,14 +398,27 @@ function BarsMarks<T>({
     const scaleForSide = (side: 'left' | 'right' | undefined) =>
       side === 'right' && y2Scale ? y2Scale : yScale
     const dim = (key: string) => (highlighted === null || highlighted === key ? 1 : 0.15)
+    // The y a bar grows FROM. `scale(0)` is `-Infinity` on a log axis — which has no zero — so
+    // every grouped bar's height came out NaN and the bars silently vanished; the fallback is the
+    // axis' own domain floor, which the log-domain law keeps positive. On a linear axis the same
+    // expression still resolves to `scale(0)` for any domain reaching zero, and pins the bar to
+    // the visible floor rather than to a zero drawn off the bottom of the plot when it does not.
+    const baselineFor = (scale: typeof yScale) => {
+      const floor = scale.domain()[0] ?? 0
+      const at = scale(Math.max(floor, 0))
+      return Number.isFinite(at) ? at : scale(floor)
+    }
 
     const groupWidth = Math.max((xMax / Math.max(rows.length, 1)) * barWidthRatio, 2)
-    const totalWeight =
-      barLayout === 'grouped' ? positiveBars.reduce((s, b) => s + (b.weight ?? 1), 0) || 1 : 1
-    const groupedBarWidths =
-      barLayout === 'grouped'
-        ? positiveBars.map((b) => Math.max(groupWidth * ((b.weight ?? 1) / totalWeight), 1))
-        : []
+    // Tiled across the bars that are actually DRAWN. Derived from the full `positiveBars` instead,
+    // a legend toggle left a hole in the slot where the hidden bar used to sit and never re-tiled
+    // the survivors across the same width.
+    const groupedBars =
+      barLayout === 'grouped' ? positiveBars.filter((b) => !hidden.has(b.key)) : []
+    const totalWeight = groupedBars.reduce((s, b) => s + (b.weight ?? 1), 0) || 1
+    const groupedBarWidths = groupedBars.map((b) =>
+      Math.max(groupWidth * ((b.weight ?? 1) / totalWeight), 1),
+    )
     const groupedBarOffsets: number[] = []
     let cursor = 0
     for (const w of groupedBarWidths) {
@@ -428,19 +471,20 @@ function BarsMarks<T>({
           negOffset = top
         }
       } else {
-        positiveBars.forEach((b, i) => {
-          if (hidden.has(b.key)) return
+        groupedBars.forEach((b, i) => {
           const v = getValue(d, b.key)
           if (v === null || Number.isNaN(v) || v <= 0) return
           const scale = scaleForSide(b.axisSide)
           const yTop = scale(v)
-          const yBottom = scale(0)
+          const yBottom = baselineFor(scale)
           rects.push({
             key: `${getX(d)}-${b.key}`,
             x: groupLeft + (groupedBarOffsets[i] ?? 0),
             y: yTop,
             width: groupedBarWidths[i] ?? 0,
-            height: yBottom - yTop,
+            // A value below a caller-pinned domain floor sits under the baseline; SVG rejects a
+            // negative height outright, so it clamps to nothing drawn.
+            height: Math.max(yBottom - yTop, 0),
             fill: b.color,
             fillOpacity: (barOpacity?.(d, b.key) ?? 0.85) * dim(b.key),
           })
@@ -521,7 +565,7 @@ function BarsMarks<T>({
             strokeWidth={ln.strokeWidth ?? LINE_OVERLAY_STROKE_WIDTH}
             strokeDasharray={ln.dashed ? VX.dashArray : undefined}
             strokeOpacity={dim(ln.key) * (ln.strokeOpacity ?? 1)}
-            curve={curveMonotoneX}
+            curve={curveFor(ln.curve)}
           />
         )
       })}
@@ -537,4 +581,8 @@ function BarsMarks<T>({
  * Hand-memoized: React Compiler does not process the shipped dist, so we wrap the
  * hot bars kind in `React.memo` to retain the auto-memoization it had as source.
  */
-export const Bars = memo(BarsInner) as typeof BarsInner
+const BarsMemo = memo(BarsInner)
+// Without it every kind reads as `Memo` in React DevTools (audit A16) — a profiler flame
+// graph of nine identically-named nodes names nothing.
+BarsMemo.displayName = 'Bars'
+export const Bars = BarsMemo as typeof BarsInner

package/src/charts/kinds/Donut.tsx

@@ -2,8 +2,11 @@ import { Group } from '@visx/group'
 import { Pie } from '@visx/shape'
 import { memo, useMemo, useState } from 'react'
 import type { PointerEvent, ReactNode } from 'react'
+import { assertRequiredProps } from '../../common/validate'
+import type { BasaltProps } from '../../common/props'
 import { ChartTooltipFloat, TooltipBody, TooltipRow } from '../primitives/ChartTooltip'
 import { ChartFrame } from '../primitives/ChartFrame'
+import type { ChartState } from '../primitives/ChartPending'
 import { VX } from '../../tokens'
 import type { SeriesStyle } from '../series'
 import type { SeriesKey } from '../../register'
@@ -15,7 +18,7 @@ import type { SeriesKey } from '../../register'
  */
 export type DonutDatum<K extends string = SeriesKey> = { key: K; value: number }
 
-export type DonutProps<K extends string = SeriesKey> = {
+export type DonutProps<K extends string = SeriesKey> = BasaltProps & {
   data: DonutDatum<K>[]
   /** Fixed height in pixels, forwarded to the internal `ChartFrame`. Default 240. */
   height?: number
@@ -54,6 +57,9 @@ export type DonutProps<K extends string = SeriesKey> = {
   ariaLabel?: string
   /** Forwarded to `ChartFrame` — see `ChartPending`'s JSDoc for the three-state rationale. */
   isPending?: boolean
+  /** The three "nothing to draw" states in one prop — pending → error → empty. See
+   * `ChartState`; `isPending` stays a supported alias for `state={{ pending: true }}`. */
+  state?: ChartState
 }
 
 /**
@@ -66,7 +72,21 @@ export type DonutProps<K extends string = SeriesKey> = {
  * category sync (donut ↔ bar, via a generalized key) is a distinct, deliberately deferred feature.
  */
 function DonutInner<K extends string = SeriesKey>(props: DonutProps<K>) {
-  const { data, height, colorForKey, seriesLabel = (k) => k, ariaLabel, isPending } = props
+  // F-ERR-1: name the component and the prop. Without this a missing accessor surfaces
+  // from inside visx as `undefined is not a function`, which `BasaltErrorBoundary`
+  // swallows into a blank subtree that names nothing.
+  assertRequiredProps('Donut', props, ['data', 'colorForKey'])
+  const {
+    data,
+    height,
+    colorForKey,
+    seriesLabel = (k) => k,
+    ariaLabel,
+    isPending,
+    state,
+    className,
+    style,
+  } = props
 
   const series: SeriesStyle[] = data.map((d) => ({
     key: d.key,
@@ -81,6 +101,9 @@ function DonutInner<K extends string = SeriesKey>(props: DonutProps<K>) {
       {...(height !== undefined && { height })}
       {...(ariaLabel !== undefined && { ariaLabel })}
       {...(isPending !== undefined && { isPending })}
+      {...(state !== undefined && { state })}
+      {...(className !== undefined && { className })}
+      {...(style !== undefined && { style })}
     >
       {(plot) => <DonutPlot {...props} plot={plot} />}
     </ChartFrame>
@@ -245,4 +268,8 @@ function DonutPlot<K extends string = SeriesKey>(props: DonutPlotProps<K>) {
  * Hand-memoized: React Compiler does not process the shipped dist, so we wrap the
  * hot donut kind in `React.memo` to retain the auto-memoization it had as source.
  */
-export const Donut = memo(DonutInner) as typeof DonutInner
+const DonutMemo = memo(DonutInner)
+// Without it every kind reads as `Memo` in React DevTools (audit A16) — a profiler flame
+// graph of nine identically-named nodes names nothing.
+DonutMemo.displayName = 'Donut'
+export const Donut = DonutMemo as typeof DonutInner

package/src/charts/kinds/DualPanel.tsx

@@ -1,4 +1,3 @@
-import { curveMonotoneX } from '@visx/curve'
 import { GridRows } from '@visx/grid'
 import { Group } from '@visx/group'
 import { scaleLinear, scalePoint } from '@visx/scale'
@@ -6,6 +5,8 @@ import { Bar, LinePath } from '@visx/shape'
 import { Threshold } from '@visx/threshold'
 import { memo, useMemo, useRef } from 'react'
 import type { ReactNode } from 'react'
+import { assertRequiredProps } from '../../common/validate'
+import type { BasaltProps } from '../../common/props'
 import { AxisBottomDate, AxisLeftNumeric } from '../primitives/Axes'
 import {
   ChartTooltipFloat,
@@ -18,16 +19,17 @@ import { Crosshair, SeriesDot } from '../primitives/Crosshair'
 import { HoverOverlay } from '../primitives/HoverOverlay'
 import { ZoneRects } from '../primitives/ZoneRects'
 import type { ZoneSpec } from '../primitives/ZoneRects'
+import type { ChartState } from '../primitives/ChartPending'
 import type { CursorResolution } from '../cursor/resolve'
 import { useChartCursor } from '../hooks/useChartCursor'
 import { autoMargin, probeAxisLabels } from '../layout/auto-margin'
-import { deriveTooltipRows, LINE_OVERLAY_STROKE_WIDTH } from '../series'
+import { curveFor, deriveTooltipRows, LINE_OVERLAY_STROKE_WIDTH } from '../series'
 import type { ChartLegendConfig, ChartSeries, SeriesStyle } from '../series'
 import { VX } from '../../tokens'
 import { fmtAxisDate } from '../utils/format'
-import { smartTicks } from '../utils/ticks'
+import { smartTicks, xLabelPxFor } from '../utils/ticks'
 
-export type DualPanelProps<T> = {
+export type DualPanelProps<T> = BasaltProps & {
   data: T[]
   /** Fixed height in pixels, forwarded to the internal `ChartFrame`. Default 240. */
   height?: number
@@ -47,8 +49,9 @@ export type DualPanelProps<T> = {
   series: ChartSeries<T>[]
   /** Top-pane y-domain. Default 'auto' (computed from all top lines, padded). */
   topYDomain?: [number, number] | 'auto'
-  /** Shade the band between two top lines (by key), filled on both sides. */
-  fillBetween?: { from: string; to: string; fill: string }
+  /** Shade the band between two top lines (by key). `aboveFill` colors the side where `to` runs
+   * above `from` (e.g. a "bad" red) — omitted, both sides share `fill` (today's behaviour). */
+  fillBetween?: { from: string; to: string; fill: string; aboveFill?: string }
   /** Horizontal reference lines on the top pane. Solid by default; set dashed: true for a dashed line. */
   topRefLines?: { value: number; color: string; dashed?: boolean }[]
   /** Horizontal value-range bands on the top pane. */
@@ -98,6 +101,9 @@ export type DualPanelProps<T> = {
   ariaLabel?: string
   /** Forwarded to `ChartFrame` — see `ChartPending`'s JSDoc for the three-state rationale. */
   isPending?: boolean
+  /** The three "nothing to draw" states in one prop — pending → error → empty. See
+   * `ChartState`; `isPending` stays a supported alias for `state={{ pending: true }}`. */
+  state?: ChartState
 }
 
 const PANE_GAP = 12
@@ -115,8 +121,23 @@ const PANE_GAP = 12
  * when a series has nulls; lines/bars skip null points (visual gaps).
  */
 function DualPanelInner<T>(props: DualPanelProps<T>) {
-  const { series, chartId, height, barLabel, barColorPositive, legend, ariaLabel, isPending } =
-    props
+  // F-ERR-1: name the component and the prop. Without this a missing accessor surfaces
+  // from inside visx as `undefined is not a function`, which `BasaltErrorBoundary`
+  // swallows into a blank subtree that names nothing.
+  assertRequiredProps('DualPanel', props, ['data', 'getX', 'series', 'getBar'])
+  const {
+    series,
+    chartId,
+    height,
+    barLabel,
+    barColorPositive,
+    legend,
+    ariaLabel,
+    isPending,
+    state,
+    className,
+    style,
+  } = props
 
   // Default the top-pane line overlays to the redesign's 1.9px stroke (docs/DESIGN-SPEC.md §5) —
   // applied once here so the plotted line, the derived legend swatch, and the derived tooltip row
@@ -144,6 +165,9 @@ function DualPanelInner<T>(props: DualPanelProps<T>) {
       {...(height !== undefined && { height })}
       {...(ariaLabel !== undefined && { ariaLabel })}
       {...(isPending !== undefined && { isPending })}
+      {...(state !== undefined && { state })}
+      {...(className !== undefined && { className })}
+      {...(style !== undefined && { style })}
       legend={resolveLegend(legend)}
     >
       {(plot) => <DualPanelPlot {...props} series={styledSeries} plot={plot} />}
@@ -319,7 +343,15 @@ function DualPanelPlot<T>(props: DualPanelPlotProps<T>) {
     ...(cursorResolution !== undefined && { resolution: cursorResolution }),
   })
 
-  const tickValues = useMemo(() => smartTicks(data.map(getX), xMax), [data, xMax, getX])
+  // The horizontal room one x tick label needs, from the SAME formatted set `xLabelsAll` measured
+  // for the bottom gutter — same measured-spacing law `CartesianChart` applies
+  // (`docs/CHARTS-SPEC.md` §1).
+  const xLabelPx = useMemo(() => xLabelPxFor(xLabelsAll), [xLabelsAll])
+
+  const tickValues = useMemo(
+    () => smartTicks(data.map(getX), xMax, xLabelPx),
+    [data, xMax, getX, xLabelPx],
+  )
 
   const barWidth = data.length > 0 ? Math.max((xMax / data.length) * 0.6, 2) : 2
 
@@ -383,6 +415,17 @@ function DualPanelPlot<T>(props: DualPanelPlotProps<T>) {
     return out
   }, [data, fillBetween, visibleSeries])
 
+  // The fill reads the FROM line's curve — same law as ZonedLine's "one curve for all shapes
+  // drawn from one series", extended to the two lines a fill spans: the band takes its shape from
+  // the line it hugs on the low side.
+  const fillCurve = useMemo(
+    () =>
+      curveFor(
+        fillBetween ? visibleSeries.find((s) => s.key === fillBetween.from)?.curve : undefined,
+      ),
+    [fillBetween, visibleSeries],
+  )
+
   type LinePt = { __d: T; __y: number }
   // Per-line valid points, computed once per (data, visibleSeries) — not re-walked inside the
   // render map every paint (parity with MultiLine's seriesPts).
@@ -468,9 +511,9 @@ function DualPanelPlot<T>(props: DualPanelPlotProps<T>) {
               y1={(p) => topYScale(p.__to)}
               clipAboveTo={0}
               clipBelowTo={topH}
-              curve={curveMonotoneX}
+              curve={fillCurve}
               belowAreaProps={{ fill: fillBetween.fill }}
-              aboveAreaProps={{ fill: fillBetween.fill }}
+              aboveAreaProps={{ fill: fillBetween.aboveFill ?? fillBetween.fill }}
             />
           )}
 
@@ -499,7 +542,7 @@ function DualPanelPlot<T>(props: DualPanelPlotProps<T>) {
                 strokeWidth={s.strokeWidth ?? VX.lineWidth}
                 strokeDasharray={s.dash === 'dashed' ? VX.dashArray : undefined}
                 strokeOpacity={s.strokeOpacity ?? 1}
-                curve={curveMonotoneX}
+                curve={curveFor(s.curve)}
               />
             )
           })}
@@ -665,4 +708,8 @@ function DualPanelPlot<T>(props: DualPanelPlotProps<T>) {
  * Hand-memoized: React Compiler does not process the shipped dist, so the hot DualPanel kind is
  * wrapped in `React.memo` to retain the auto-memoization it had as source (parity with ZonedLine).
  */
-export const DualPanel = memo(DualPanelInner) as typeof DualPanelInner
+const DualPanelMemo = memo(DualPanelInner)
+// Without it every kind reads as `Memo` in React DevTools (audit A16) — a profiler flame
+// graph of nine identically-named nodes names nothing.
+DualPanelMemo.displayName = 'DualPanel'
+export const DualPanel = DualPanelMemo as typeof DualPanelInner

package/src/charts/kinds/Heatmap.tsx

@@ -1,6 +1,8 @@
 import { Group } from '@visx/group'
 import type { PointerEvent, ReactNode } from 'react'
 import { memo, useMemo, useState } from 'react'
+import { assertRequiredProps } from '../../common/validate'
+import type { BasaltProps } from '../../common/props'
 import {
   ChartTooltipFloat,
   TooltipBody,
@@ -8,6 +10,10 @@ import {
   TooltipRow,
 } from '../primitives/ChartTooltip'
 import { ChartFrame } from '../primitives/ChartFrame'
+import { useChartTierMetrics } from '../primitives/chart-tier'
+import type { ChartState } from '../primitives/ChartPending'
+import { maxTextWidth } from '../utils/measure-text'
+import { thinLabels, xLabelPxFor } from '../utils/ticks'
 import { VX, alpha } from '../../tokens'
 
 /** A single resolved heatmap cell — the unit the tooltip and hover operate on. */
@@ -16,7 +22,7 @@ type HeatmapCell = { row: string; col: string; value: number }
 /** A hovered cell plus the viewport anchor `ChartTooltipFloat` positions against. */
 type HeatmapTip = HeatmapCell & { anchor: { x: number; y: number } }
 
-export type HeatmapProps<T> = {
+export type HeatmapProps<T> = BasaltProps & {
   data: T[]
   /** Fixed height in pixels. Used when neither `aspectRatio` nor `fill` is set. Default 240. */
   height?: number
@@ -57,6 +63,9 @@ export type HeatmapProps<T> = {
   ariaLabel?: string
   /** Forwarded to `ChartFrame` — see `ChartPending`'s JSDoc for the three-state rationale. */
   isPending?: boolean
+  /** The three "nothing to draw" states in one prop — pending → error → empty. See
+   * `ChartState`; `isPending` stays a supported alias for `state={{ pending: true }}`. */
+  state?: ChartState
 }
 
 /** Build a first-seen-ordered list of unique keys from data via an accessor. */
@@ -85,6 +94,10 @@ const LABEL_FONT_FAMILY = 'var(--basalt-font-mono)'
 const PAD_LEFT = 44
 const PAD_BOTTOM = 24
 const PAD_TOP = 8
+
+/** Line box of one category label at `fontPx` — the vertical room a row label needs, and so the
+ * pitch below which the row labels thin (`thinLabels`). Same 1.35em line box `autoMargin` uses. */
+const labelLineHeight = (fontPx: number): number => Math.ceil(fontPx * 1.35)
 // Height of the optional gradient legend strip (+ its label line).
 const LEGEND_H = 8
 const LEGEND_LABEL_H = 16
@@ -94,14 +107,22 @@ const LEGEND_LABEL_H = 16
  * color at an opacity derived from its value; empty cells stay a faint neutral track.
  * Generalizes argo's day-of-week × hour-of-day heatmap. Categorical axes are rendered as
  * plain themed `<text>` (cells are not date-categorical, so there's no shared cursor here) —
- * per-cell hover drives the local tooltip directly.
+ * per-cell hover drives the local tooltip directly. Painting them outside the `Axis*` primitives
+ * does NOT exempt them from §1's measured law: both runs thin through {@link thinLabels} and the
+ * right gutter reserves half the widest column label, so no two painted labels overlap and the
+ * last one cannot clip.
  *
  * Composes `ChartFrame` purely for measuring (`height`/`aspectRatio`/`fill`, the same three
  * sizing modes every other kind exposes) — `legend={false}` and an empty `series` opt out of
  * `ChartFrame`'s own derived legend, since Heatmap already ships its own gradient strip.
  */
 function HeatmapInner<T>(props: HeatmapProps<T>) {
-  const { chartId, height, aspectRatio, fill, ariaLabel, isPending } = props
+  // F-ERR-1: name the component and the prop. Without this a missing accessor surfaces
+  // from inside visx as `undefined is not a function`, which `BasaltErrorBoundary`
+  // swallows into a blank subtree that names nothing.
+  assertRequiredProps('Heatmap', props, ['data', 'getRow', 'getCol', 'getValue'])
+  const { chartId, height, aspectRatio, fill, ariaLabel, isPending, state, className, style } =
+    props
 
   return (
     <ChartFrame
@@ -113,6 +134,9 @@ function HeatmapInner<T>(props: HeatmapProps<T>) {
       {...(fill !== undefined && { fill })}
       {...(ariaLabel !== undefined && { ariaLabel })}
       {...(isPending !== undefined && { isPending })}
+      {...(state !== undefined && { state })}
+      {...(className !== undefined && { className })}
+      {...(style !== undefined && { style })}
     >
       {(plot) => <HeatmapPlot {...props} plot={plot} />}
     </ChartFrame>
@@ -147,6 +171,11 @@ function HeatmapPlot<T>(props: HeatmapPlotProps<T>) {
   } = props
   const { width, height } = plot
 
+  // The row/column labels and the gradient legend's endpoints read like axis ticks, so they take
+  // the tier's tick font for the same reason `Axes.tsx` does — a 360px heatmap that painted its
+  // categories at the desktop size would be the one chart still ignoring §8.
+  const { axisFont } = useChartTierMetrics()
+
   const [tip, setTip] = useState<HeatmapTip | null>(null)
 
   const rows = useMemo(() => rowsProp ?? firstSeen(data, getRow), [rowsProp, data, getRow])
@@ -164,13 +193,33 @@ function HeatmapPlot<T>(props: HeatmapPlotProps<T>) {
     return { lookup: map, max: m }
   }, [data, getRow, getCol, getValue])
 
+  const rowLabels = useMemo(() => rows.map(rowLabel), [rows, rowLabel])
+  const colLabels = useMemo(() => cols.map(colLabel), [cols, colLabel])
+
   const legendH = legend ? LEGEND_H + LEGEND_LABEL_H : 0
-  const gridW = Math.max(0, width - PAD_LEFT)
+  // The last column label is CENTRED on the last cell, so half of it hangs past the grid — the
+  // same reason `autoMargin` reserves half the widest x label on the right. Measured, not a
+  // constant: at 390px `19:00` used to print straight off the SVG's own clip edge.
+  const padRight = Math.ceil(maxTextWidth(colLabels, axisFont) / 2)
+  const gridW = Math.max(0, width - PAD_LEFT - padRight)
   const gridH = Math.max(0, height - PAD_TOP - PAD_BOTTOM - legendH)
   const cellW = cols.length > 0 ? gridW / cols.length : 0
   const cellH = rows.length > 0 ? gridH / rows.length : 0
   const legendGradientId = `${chartId}-heat-legend`
 
+  // §1's measured law, applied to the one kind that paints its labels as plain `<text>` rather
+  // than through the `Axis*` primitives: a label every `ceil(labelPx / cellPitch)` bands, so two
+  // painted neighbours can never overlap. Columns thin horizontally by the widest label, rows
+  // vertically by the line box.
+  const keptCols = useMemo(
+    () => thinLabels(colLabels, cellW, xLabelPxFor(colLabels, axisFont)),
+    [colLabels, cellW, axisFont],
+  )
+  const keptRows = useMemo(
+    () => thinLabels(rowLabels, cellH, labelLineHeight(axisFont)),
+    [rowLabels, cellH, axisFont],
+  )
+
   const show = (row: string, col: string, value: number, event: PointerEvent<SVGRectElement>) => {
     setTip({ row, col, value, anchor: { x: event.clientX, y: event.clientY } })
   }
@@ -206,36 +255,40 @@ function HeatmapPlot<T>(props: HeatmapPlotProps<T>) {
 
         {/* Row labels (left). */}
         <Group left={0} top={PAD_TOP}>
-          {rows.map((row, ri) => (
-            <text
-              key={row}
-              x={PAD_LEFT - 6}
-              y={ri * cellH + cellH / 2 + 4}
-              textAnchor="end"
-              fontSize={VX.axisFont}
-              fontFamily={LABEL_FONT_FAMILY}
-              fill={VX.faint}
-            >
-              {rowLabel(row)}
-            </text>
-          ))}
+          {rows.map((row, ri) =>
+            keptRows.has(ri) ? (
+              <text
+                key={row}
+                x={PAD_LEFT - 6}
+                y={ri * cellH + cellH / 2 + 4}
+                textAnchor="end"
+                fontSize={axisFont}
+                fontFamily={LABEL_FONT_FAMILY}
+                fill={VX.faint}
+              >
+                {rowLabels[ri]}
+              </text>
+            ) : null,
+          )}
         </Group>
 
         {/* Column labels (bottom). */}
         <Group left={PAD_LEFT} top={PAD_TOP + gridH}>
-          {cols.map((col, ci) => (
-            <text
-              key={col}
-              x={ci * cellW + cellW / 2}
-              y={16}
-              textAnchor="middle"
-              fontSize={VX.axisFont}
-              fontFamily={LABEL_FONT_FAMILY}
-              fill={VX.faint}
-            >
-              {colLabel(col)}
-            </text>
-          ))}
+          {cols.map((col, ci) =>
+            keptCols.has(ci) ? (
+              <text
+                key={col}
+                x={ci * cellW + cellW / 2}
+                y={16}
+                textAnchor="middle"
+                fontSize={axisFont}
+                fontFamily={LABEL_FONT_FAMILY}
+                fill={VX.faint}
+              >
+                {colLabels[ci]}
+              </text>
+            ) : null,
+          )}
         </Group>
 
         {/* Optional gradient legend strip below the grid. */}
@@ -252,7 +305,7 @@ function HeatmapPlot<T>(props: HeatmapPlotProps<T>) {
               x={0}
               y={LEGEND_H + 12}
               textAnchor="start"
-              fontSize={VX.axisFont}
+              fontSize={axisFont}
               fontFamily={LABEL_FONT_FAMILY}
               fill={VX.faint}
             >
@@ -262,7 +315,7 @@ function HeatmapPlot<T>(props: HeatmapPlotProps<T>) {
               x={gridW}
               y={LEGEND_H + 12}
               textAnchor="end"
-              fontSize={VX.axisFont}
+              fontSize={axisFont}
               fontFamily={LABEL_FONT_FAMILY}
               fill={VX.faint}
             >
@@ -294,4 +347,8 @@ function HeatmapPlot<T>(props: HeatmapPlotProps<T>) {
  * Hand-memoized: React Compiler does not process the shipped dist, so the hot Heatmap kind is
  * wrapped in `React.memo` to retain auto-memoization (parity with ZonedLine / Bars).
  */
-export const Heatmap = memo(HeatmapInner) as typeof HeatmapInner
+const HeatmapMemo = memo(HeatmapInner)
+// Without it every kind reads as `Memo` in React DevTools (audit A16) — a profiler flame
+// graph of nine identically-named nodes names nothing.
+HeatmapMemo.displayName = 'Heatmap'
+export const Heatmap = HeatmapMemo as typeof HeatmapInner