basalt-ui 1.30.2 → 1.31.0

package/src/charts/primitives/chart-layout.ts

@@ -0,0 +1,318 @@
+/**
+ * `resolveChartLayout` — the single, pure decision point for a chart's space
+ * (`docs/CHARTS-SPEC.md` §8): container class, height and legend fit. Also hosts the axis-economy
+ * ladder (`resolveYPlacement`, `planXLabels`, `yTickCount`, `compactNumber`, …) that
+ * `CartesianChart`/`useBandPlot` call directly. DOM-free and Mantine-free; deliberately not on any
+ * public barrel.
+ */
+
+import { resolveContainerClass } from '../../tokens/size-classes'
+import type { ContainerClass, SIZE_CLASSES } from '../../tokens/size-classes'
+import { VX } from '../../tokens'
+import type { ChartMargin } from '../../tokens'
+import { measureText } from '../utils/measure-text'
+import type { LegendEntry } from './ChartLegend'
+import {
+  entriesWithinChipRows,
+  entriesWithinDotRows,
+  entriesWithinRows,
+  orderEntries,
+} from './chart-frame-layout'
+
+export type ChartLayout = {
+  containerClass: ContainerClass
+  height: number
+  legend:
+    | { mode: 'none' }
+    | { mode: 'dots' | 'chips'; where: 'header' | 'band'; visible: number; overflow: number }
+}
+
+export type ChartLayoutInput = {
+  /** The chart frame's MEASURED width; `<= 0` is unmeasured (SSR, first paint). */
+  frameW: number
+  /** Width of the card's header legend slot; `0` when there is none (the legend takes a band). */
+  slotW: number
+  /** Viewport height in px (`0` unknown). Only read on a coarse pointer. */
+  viewportH: number
+  legendItems: readonly LegendEntry[]
+  /** Viewport class — decides the container class until the frame is measured. */
+  sizeClass: keyof typeof SIZE_CLASSES
+  coarse: boolean
+  /**
+   * The card's own `short` flag (`ChartCard`'s `measuredHeight < CARD_SHORT_HEIGHT`) — the ONE
+   * source of truth for "this legend gets at most one row", not a second narrower threshold.
+   * Default `false` (no card, or an unmeasured/tall one).
+   */
+  cardShort?: boolean
+  /** The legend's own `groups` config — whether role dividers render (and so count toward the
+   * dots-mode fit). Default `false`. */
+  groups?: boolean
+  /** Consumer-stated values; each wins over the derived one. */
+  override?: { height?: number }
+}
+
+/** Height = width × ratio, per container class. */
+const HEIGHT_RATIO = { micro: 0.5, compact: 0.62, regular: 0.5, wide: 0.4 } as const
+const HEIGHT_MIN = 160
+const HEIGHT_MAX = 420
+/** A coarse pointer never gets a chart taller than this share of the viewport. */
+const COARSE_VIEWPORT_SHARE = 0.45
+/** Width assumed per class before the frame is measured. */
+const UNMEASURED_WIDTH = { micro: 200, compact: 360, regular: 640, wide: 960 } as const
+/** A y-axis tick every ~44px of plot height. */
+const TICK_SPACING = 44
+const COMPACT_LABEL_CHARS = 4
+/** Gap kept between two adjacent x labels. */
+const X_LABEL_GAP = 8
+/** A legend shares one header row; in the band it may wrap to two. */
+const LEGEND_ROWS = { header: 1, band: 2 } as const
+
+/** Before the first measurement a compact viewport implies a compact container. */
+const CONTAINER_CLASS_OF_SIZE_CLASS = {
+  compact: 'compact',
+  medium: 'regular',
+  expanded: 'wide',
+} as const satisfies Record<keyof typeof SIZE_CLASSES, ContainerClass>
+
+function containerClassFromSizeClass(sizeClass: keyof typeof SIZE_CLASSES): ContainerClass {
+  return CONTAINER_CLASS_OF_SIZE_CLASS[sizeClass]
+}
+
+const clamp = (value: number, min: number, max: number): number =>
+  Math.min(Math.max(value, min), max)
+
+function resolveHeight(input: ChartLayoutInput, containerClass: ContainerClass): number {
+  const override = input.override?.height
+  const width = input.frameW > 0 ? input.frameW : UNMEASURED_WIDTH[containerClass]
+  const derived =
+    override ?? clamp(Math.round(width * HEIGHT_RATIO[containerClass]), HEIGHT_MIN, HEIGHT_MAX)
+  if (!input.coarse || input.viewportH <= 0) return derived
+  // A viewport safety cap: it applies to a consumer's literal `height` too, so a fixed-height chart
+  // cannot overflow a short landscape-phone viewport.
+  return Math.min(derived, Math.round(input.viewportH * COARSE_VIEWPORT_SHARE))
+}
+
+/**
+ * A legend never rolls up fewer than 2 entries: "+1 more" hides nothing a chip would not show.
+ * `fitted` may legitimately be 0 — not even the first chip/dot fits once the `All N` chip's own
+ * width is reserved beside it — in which case the row is the disclosure alone (`visible: 0`),
+ * unless that would roll up the single-entry case the "fewer than 2" rule already protects.
+ */
+function rollUp(total: number, fitted: number): { visible: number; overflow: number } {
+  const visible = total - fitted < 2 ? total : fitted
+  return { visible, overflow: total - visible }
+}
+
+function resolveLegend(
+  input: ChartLayoutInput,
+  containerClass: ContainerClass,
+): ChartLayout['legend'] {
+  const total = input.legendItems.length
+  if (containerClass === 'micro' || total === 0) return { mode: 'none' }
+  const where = input.slotW > 0 ? 'header' : 'band'
+  const width = where === 'header' ? input.slotW : input.frameW
+  // Unmeasured (first paint, before P2-8's synchronous slot seed lands): assume everything fits
+  // rather than guessing a fold nothing has measured yet.
+  if (width <= 0) return { mode: 'chips', where, visible: total, overflow: 0 }
+
+  const { entries: ordered, dividerAfter } = orderEntries(input.legendItems, input.groups === true)
+  const chipFit = entriesWithinRows(ordered, width, LEGEND_ROWS[where])
+  const allChipsFit = chipFit >= total
+
+  // Chips whenever every entry fits one header row; dots is a header-only FALLBACK for when chips
+  // do not fit, and only while the card is short or the container itself is compact
+  // (`docs/CHARTS-SPEC.md` §5, Legend). A band legend always stays 'chips'.
+  const wantsDots =
+    where === 'header' && !allChipsFit && (input.cardShort === true || containerClass === 'compact')
+
+  if (!wantsDots) {
+    // Re-measured with the `All N` chip's own width reserved whenever there IS overflow — `chipFit`
+    // above is deliberately the un-reserved number (the `allChipsFit` check needs the answer to
+    // "does everything fit with no chip at all"), so it is not reused for the final count here.
+    const fitted = allChipsFit ? chipFit : entriesWithinChipRows(ordered, width, LEGEND_ROWS[where])
+    const { visible, overflow } = rollUp(total, fitted)
+    return { mode: 'chips', where, visible, overflow }
+  }
+  const dotFit = entriesWithinDotRows(ordered, width, LEGEND_ROWS[where], dividerAfter)
+  const { visible, overflow } = rollUp(total, dotFit)
+  return { mode: 'dots', where, visible, overflow }
+}
+
+/** Compact and micro plots are tight: y labels move inside and terminal x labels anchor inward. */
+export function isTightClass(containerClass: ContainerClass): boolean {
+  return containerClass === 'compact' || containerClass === 'micro'
+}
+
+/**
+ * At a tight container class the y labels move inside the plot (micro: no y axis at all), so the
+ * left gutter drops to its floor. Not-tight, no left axis, or an explicit `margin.left` all keep
+ * the axis outside — the single implementation `CartesianChart`/`useBandPlot` both call.
+ */
+export function resolveYPlacement(
+  containerClass: ContainerClass,
+  opts: { hasLeftAxis?: boolean | undefined; marginOverrideLeft?: number | undefined } = {},
+): 'outside' | 'inside' | 'none' {
+  const { hasLeftAxis = true, marginOverrideLeft } = opts
+  if (!isTightClass(containerClass) || !hasLeftAxis || marginOverrideLeft !== undefined)
+    return 'outside'
+  return containerClass === 'micro' ? 'none' : 'inside'
+}
+
+/**
+ * Left-margin floor once `resolveYPlacement` moves the labels INSIDE the plot: just enough for the
+ * axis line and a hair of breathing room, not the outside axis's full label-width floor. Passing
+ * the tier's own `margin.left` here reserves a gutter for a label that no longer paints.
+ */
+export const INSIDE_Y_FLOOR = 4
+
+/**
+ * The `autoMargin` FLOOR to measure against, once `resolveYPlacement` has decided where the left
+ * axis paints — an axis placed `'outside'` keeps the tier's ordinary margin floor; one placed
+ * `'inside'` (or dropped, `'none'`) paints IN the plot, so the outside label-width floor is dead
+ * space on that side and only {@link INSIDE_Y_FLOOR} applies. `CartesianChart` and `useBandPlot`
+ * used to each spell this same ternary out by hand.
+ */
+export function resolveMarginFloor(
+  yPlacement: 'outside' | 'inside' | 'none',
+  tierMargin: ChartMargin,
+): ChartMargin {
+  return yPlacement === 'outside' ? tierMargin : { ...tierMargin, left: INSIDE_Y_FLOOR }
+}
+
+const COMPACT_UNITS = [
+  [1e12, 'T'],
+  [1e9, 'B'],
+  [1e6, 'M'],
+  [1e3, 'k'],
+] as const
+
+const roundTenth = (value: number): number => Math.round(value * 10) / 10
+
+/**
+ * Ladder step 1: `12500` -> `12.5k`, `1_200_000` -> `1.2M`; `null` below 1000 or non-finite. Rounds
+ * BEFORE choosing the unit's suffix, so `999_950` reads `1M`, never `1000k`; the largest unit caps.
+ */
+export function compactNumber(value: number): string | null {
+  const abs = Math.abs(value)
+  if (!Number.isFinite(value) || abs < 1000) return null
+  let index = COMPACT_UNITS.findIndex(([unit]) => abs >= unit)
+  let scaled = roundTenth(abs / COMPACT_UNITS[index]![0])
+  if (scaled >= 1000 && index > 0) {
+    index -= 1
+    scaled = roundTenth(abs / COMPACT_UNITS[index]![0])
+  }
+  return `${value < 0 ? '-' : ''}${scaled}${COMPACT_UNITS[index]![1]}`
+}
+
+/** Ladder step 1's rule: compact only when the longest y label is over 4 chars. */
+export function shouldCompactYLabels(labels: readonly string[]): boolean {
+  return labels.some((label) => label.length > COMPACT_LABEL_CHARS)
+}
+
+/** Ladder step 2 + the `VX.minPlotHeight` guard: one tick per ~44px, 2 when the plot is under the floor. */
+export function yTickCount(plotHeight: number): number {
+  if (plotHeight < VX.minPlotHeight) return 2
+  return clamp(Math.round(plotHeight / TICK_SPACING), 2, 6)
+}
+
+/** Greedy word wrap by measured px; a single word wider than `maxPx` keeps its own line. */
+export function wrapLabel(label: string, maxPx: number, fontPx: number): string[] {
+  const words = label.split(/\s+/).filter((word) => word !== '')
+  const lines: string[] = []
+  let current = ''
+  for (const word of words) {
+    const candidate = current === '' ? word : `${current} ${word}`
+    if (current !== '' && measureText(candidate, fontPx) > maxPx) {
+      lines.push(current)
+      current = word
+      continue
+    }
+    current = candidate
+  }
+  if (current !== '') lines.push(current)
+  return lines.length > 0 ? lines : [label]
+}
+
+export type XLabelPlan = {
+  wrap: boolean
+  rotate: 0 | 45
+  /** Lines the tallest label takes once wrapped (1 when it does not). */
+  lines: number
+  /** Px one tick label needs: measured width (wrapped width when wrapping) plus the gap. */
+  labelPx: number
+  /** Width labels wrap to; `0` when they do not wrap. */
+  wrapPx: number
+}
+
+/**
+ * Ladder step 4: x labels that do not all fit side by side wrap — categorical (band) domains
+ * only, and only when wrapping shows EVERY key. A wrap that would still drop keys buys nothing
+ * (it costs a line of bottom gutter to thin the same way flat already would), so it falls back to
+ * flat/thinned instead. Rotating is the last resort, reached only once even a full wrap can't fit.
+ */
+export function planXLabels(input: {
+  labels: readonly string[]
+  plotWidth: number
+  fontPx: number
+  categorical: boolean
+}): XLabelPlan {
+  const { labels, plotWidth, fontPx, categorical } = input
+  const count = labels.length
+  const widest = labels.reduce((max, label) => Math.max(max, measureText(label, fontPx)), 0)
+  const flatPx = widest + X_LABEL_GAP
+  const fit = plotWidth > 0 && widest > 0 ? Math.floor(plotWidth / flatPx) : count
+  const flat = {
+    wrap: false,
+    rotate: 0,
+    lines: 1,
+    labelPx: flatPx,
+    wrapPx: 0,
+  } as const satisfies XLabelPlan
+  if (!categorical || count <= fit || plotWidth <= 0) return flat
+
+  const widestWord = labels.reduce(
+    (max, label) => Math.max(max, ...label.split(/\s+/).map((word) => measureText(word, fontPx))),
+    0,
+  )
+  const wrapPx = Math.min(widest, Math.max(widestWord, Math.floor(plotWidth / count) - X_LABEL_GAP))
+  const wrapped = labels.map((label) => wrapLabel(label, wrapPx, fontPx))
+  const lines = wrapped.reduce((max, parts) => Math.max(max, parts.length), 1)
+  if (lines === 1) {
+    // Nothing to wrap (single words): rotating is the only remaining answer.
+    return count > 2 * Math.max(fit, 1) ? { ...flat, rotate: 45 } : flat
+  }
+  const wrappedWidest = wrapped.reduce(
+    (max, parts) => Math.max(max, ...parts.map((part) => measureText(part, fontPx))),
+    0,
+  )
+  const wrappedFit = Math.max(Math.floor(plotWidth / (wrappedWidest + X_LABEL_GAP)), 1)
+  if (wrappedFit >= count) {
+    return {
+      wrap: true,
+      rotate: 0,
+      lines,
+      labelPx: wrappedWidest + X_LABEL_GAP,
+      wrapPx,
+    }
+  }
+  return count > 2 * wrappedFit ? { ...flat, rotate: 45 } : flat
+}
+
+/** The container class: the measured width's, or the viewport-implied one while unmeasured. */
+export function resolveFrameClass(input: {
+  frameW: number
+  sizeClass: keyof typeof SIZE_CLASSES
+}): ContainerClass {
+  return input.frameW > 0
+    ? resolveContainerClass(input.frameW)
+    : containerClassFromSizeClass(input.sizeClass)
+}
+
+export function resolveChartLayout(input: ChartLayoutInput): ChartLayout {
+  const containerClass = resolveFrameClass(input)
+  return {
+    containerClass,
+    height: resolveHeight(input, containerClass),
+    legend: resolveLegend(input, containerClass),
+  }
+}

package/src/charts/primitives/chart-tier.tsx

@@ -1,37 +1,82 @@
-import { createContext, useContext } from 'react'
+import { createContext, useContext, useSyncExternalStore } from 'react'
 import type { ReactNode } from 'react'
-import { chartTierMetrics, resolveChartTier } from './chart-frame-layout'
-import type { ChartTier, ChartTierMetrics } from './chart-frame-layout'
+import { useMediaQuery } from '../../common/use-media-query'
+import type { ContainerClass } from '../../tokens/size-classes'
+import { chartMetrics } from './chart-frame-layout'
+import type { ChartTierMetrics } from './chart-frame-layout'
 
 /**
- * Ambient chart tier. `ChartFrame` publishes the tier it resolved from its own MEASURED width;
- * the axes, the legend, the crosshair dots and the tooltip read it back without every kind having
- * to thread a prop it does not otherwise care about.
+ * Ambient container class. `ChartFrame` publishes the class it resolved (`resolveChartLayout`:
+ * its own MEASURED width, or the viewport-implied class before the first measurement); the axes,
+ * the legend, the crosshair dots and the tooltip read their metrics back without every kind
+ * threading a prop it does not otherwise care about.
  *
- * Default `'desktop'`, so a primitive rendered outside a `ChartFrame` (a hand-composed plot, a
- * `TooltipRow` in a consumer's own tooltip) keeps exactly today's sizes.
+ * Default `'regular'` (desktop metrics), so a primitive rendered outside a `ChartFrame` (a
+ * hand-composed plot, a `TooltipRow` in a consumer's own tooltip) keeps today's sizes.
  */
-const ChartTierContext = createContext<ChartTier>('desktop')
+const ChartContainerClassContext = createContext<ContainerClass>('regular')
 
 export type ChartTierProviderProps = {
-  tier: ChartTier
+  containerClass: ContainerClass
   children: ReactNode
 }
 
-/** Publishes a resolved tier to the subtree. Mounted once, by `ChartFrame`. */
-export function ChartTierProvider({ tier, children }: ChartTierProviderProps): ReactNode {
-  return <ChartTierContext.Provider value={tier}>{children}</ChartTierContext.Provider>
+/** Publishes a resolved container class to the subtree. Mounted once, by `ChartFrame`. */
+export function ChartTierProvider({ containerClass, children }: ChartTierProviderProps): ReactNode {
+  return (
+    <ChartContainerClassContext.Provider value={containerClass}>
+      {children}
+    </ChartContainerClassContext.Provider>
+  )
 }
 
-/** The tier of the nearest measured `ChartFrame`, or `'desktop'` outside one. */
-export function useChartTier(): ChartTier {
-  return useContext(ChartTierContext)
+/** The ambient container class (`'regular'` outside a `ChartFrame`). Internal. */
+export function useChartContainerClass(): ContainerClass {
+  return useContext(ChartContainerClassContext)
 }
 
-/** The resolved sizes for the ambient tier — the form every primitive actually wants. */
-export function useChartTierMetrics(): ChartTierMetrics {
-  return chartTierMetrics(useContext(ChartTierContext))
+/** The resolved sizes for the ambient container class — what every internal primitive wants. */
+export function useChartMetrics(): ChartTierMetrics {
+  return chartMetrics(useChartContainerClass())
 }
 
-export { chartTierMetrics, resolveChartTier }
-export type { ChartTier, ChartTierMetrics }
+const subscribeNothing = (): (() => void) => () => {}
+
+/** Whether the primary pointer is coarse. Server snapshot `false`: hydration agrees, then updates. */
+export function useCoarsePointer(): boolean {
+  return useMediaQuery('(pointer: coarse)', false)
+}
+
+/** Viewport height is quantized so a mobile URL bar collapsing does not re-lay-out every chart. */
+const VIEWPORT_H_STEP = 50
+
+// One shared `resize` listener for the whole page (like `common/use-media-query.ts`'s one
+// `MediaQueryList` per query) rather than every mounted `ChartFrame` installing its own — a
+// dashboard with a dozen charts used to mean a dozen native listeners for the same value.
+const viewportHListeners = new Set<() => void>()
+let viewportHListenerAttached = false
+
+function ensureViewportHListener(): void {
+  if (viewportHListenerAttached || typeof window === 'undefined') return
+  viewportHListenerAttached = true
+  window.addEventListener('resize', () => {
+    for (const listener of viewportHListeners) listener()
+  })
+}
+
+function subscribeViewportH(onChange: () => void): () => void {
+  if (typeof window === 'undefined') return subscribeNothing()
+  ensureViewportHListener()
+  viewportHListeners.add(onChange)
+  return () => viewportHListeners.delete(onChange)
+}
+
+function readViewportH(): number {
+  if (typeof window === 'undefined') return 0
+  return Math.round(window.innerHeight / VIEWPORT_H_STEP) * VIEWPORT_H_STEP
+}
+
+/** Viewport height in px (`0` on the server). Only the coarse-pointer height clamp reads it. */
+export function useViewportHeight(): number {
+  return useSyncExternalStore(subscribeViewportH, readViewportH, () => 0)
+}

package/src/charts/series.ts

@@ -85,7 +85,10 @@ export type ChartLegendConfig = {
   placement?: LegendPlacement
   /** Visually separate role: series | overlay | reference. */
   groups?: boolean
-  /** Wrap cap → "+N more" rollup at high cardinality. */
+  /**
+   * @deprecated Removed in 1.32.0 — the legend fits by measured width and folds overflow into an
+   * `All N` disclosure on its own. An explicit value still wins this release (entry count).
+   */
   maxRows?: number
   /** Clicking an entry hides that series. Default: on whenever there is more than one entry. */
   toggle?: boolean

package/src/charts/utils/ticks.ts

@@ -12,47 +12,123 @@ const X_TICK_LABEL_GAP = 8
  * `useBandPlot` and `DualPanel` — the three call sites that used to reimplement this formula.
  *
  * `fontPx` defaults to `VX.axisFont`; a phone-tier chart passes its own smaller tick font
- * (`chartTierMetrics().axisFont`) so the spacing is derived from the size actually painted.
+ * (`chartMetrics().axisFont`) so the spacing is derived from the size actually painted.
  */
 export function xLabelPxFor(labels: string[], fontPx: number = VX.axisFont): number {
   return maxTextWidth(labels, fontPx) + X_TICK_LABEL_GAP
 }
 
+/**
+ * The horizontal room one 45°-rotated x label takes: its projected box (`cos 45°` of the width plus
+ * one line box) plus the gap. A tilted label still competes with its neighbour for this much, so
+ * thinning by the bare `VX.minPxPerTick` floor let two of them touch as soon as the plot widened.
+ */
+export function rotatedXLabelPx(labels: string[], fontPx: number = VX.axisFont): number {
+  return (
+    Math.ceil(COS_45 * (maxTextWidth(labels, fontPx) + Math.ceil(fontPx * 1.35))) + X_TICK_LABEL_GAP
+  )
+}
+
 /**
  * Pick evenly-spaced tick values that fit the available width.
  *
  * `labelPx` is the width one formatted label actually needs (measured, plus the gap it wants from
- * its neighbour) and overrides the `VX.minPxPerTick` floor whenever it is wider. Without it the
- * spacing came from that constant alone regardless of what was painted, so a `formatX` returning
- * `Mar 08 14:00` overlapped at every width — the one side of the chart that did not follow §1's
- * "measure what you paint" law. Omit it and nothing moves.
+ * its neighbour) and REPLACES the `VX.minPxPerTick` constant whenever it is supplied, in either
+ * direction — a wide label needs more room than the constant assumed (a `formatX` returning
+ * `Mar 08 14:00` used to overlap at every width, the one side of the chart that did not follow
+ * §1's "measure what you paint" law), and a narrow one (single-digit band labels) can pack in
+ * MORE ticks than the constant would allow, which the floor used to suppress (R2C-11). Omit it and
+ * the constant is what governs, same as before.
  *
  * The final key is still appended when the step misses the last index — a thinned axis would
  * otherwise paint no label at the right edge at all — but it no longer prints ON TOP of its
  * neighbour. An appended tick lands a PARTIAL step from the last one on the grid, so at any tick
  * count wide enough labels overlap there; measured at `/charts-stress` block (f1), `Mar 13 14:00`
  * and `Mar 14 14:00` printed over each other at 1440px. When that gap is narrower than one label,
- * the grid tick before it is dropped instead. Index 0 is never dropped: the left edge is the one
- * label a reader orients from.
+ * the grid tick before it is dropped instead.
+ *
+ * `anchorTerminals` (default false) mirrors the SAME flag `autoMargin`/`Axes.tsx` take: when the
+ * axis anchors index 0 and the last index at their TEXT edge rather than their centre
+ * (`terminalAnchor`), each reaches a FULL label's width toward its neighbour instead of half, so
+ * the plain per-tick pitch above (sized for two centred labels) isn't enough at either boundary —
+ * `Bars` with 30 daily "Jan DD HH:MM" keys overlapped there at phone width even though the interior
+ * pitch was fine (R2C-6). The SAME rule then applies, symmetrically, to the tick right after
+ * index 0. 1.5× is a deliberately generous (cheap, simple) stand-in for "one label plus half a
+ * label" rather than measuring the split precisely; it's skipped when `labelPx` is only the bare
+ * `VX.minPxPerTick` floor, which has no relationship to how wide a label actually is. Index 0
+ * always survives (never the one dropped here) and `last` is always (re-)added below, so dropping
+ * any OTHER index never breaks the "at least 2 ticks" floor.
  */
-export function smartTicks(dates: string[], xMax: number, labelPx?: number): string[] {
+export function smartTicks(
+  dates: string[],
+  xMax: number,
+  labelPx?: number,
+  anchorTerminals = false,
+): string[] {
   if (dates.length === 0) return []
-  const perTick = Math.max(VX.minPxPerTick, labelPx ?? 0)
+  // A non-positive `labelPx` (a caller's own arithmetic gone wrong, or an explicit 0) is not "no
+  // measurement" — `labelPx ?? VX.minPxPerTick` let it through as-is, and `xMax / 0` then floors
+  // `maxTicks` to `Infinity`, which used to make EVERY tick "fit" and skip thinning entirely.
+  const perTick = labelPx !== undefined && labelPx > 0 ? labelPx : VX.minPxPerTick
   const maxTicks = Math.max(2, Math.floor(xMax / perTick))
-  if (dates.length <= maxTicks) return dates
-  const step = Math.ceil(dates.length / maxTicks)
   const last = dates.length - 1
+  // `scalePoint({ padding: 0.5 })` spreads N points over `xMax`, so one index is `xMax / N` wide.
+  const pxPerIndex = dates.length > 0 ? xMax / dates.length : 0
+  // Only a REAL measured label (not the bare `VX.minPxPerTick` floor, which knows nothing about how
+  // wide a label actually is) earns the wider terminal clearance below.
+  const anchored = anchorTerminals && labelPx !== undefined && labelPx > 0
 
   const keep = new Set<number>()
-  for (let i = 0; i <= last; i += step) keep.add(i)
+  if (dates.length <= maxTicks) {
+    // Every date already fits with no thinning — round 3: this used to `return dates` here,
+    // skipping the terminal-clearance pass below entirely. A terminal-anchored label still reaches
+    // a FULL label's width toward its neighbour (not half, like a centred one), which the plain
+    // per-tick spacing above does not itself guarantee, so the same pass has to run here too.
+    for (let i = 0; i <= last; i += 1) keep.add(i)
+  } else {
+    const step = Math.ceil(dates.length / maxTicks)
+    for (let i = 0; i <= last; i += step) keep.add(i)
 
-  const lastOnGrid = Math.floor(last / step) * step
-  if (lastOnGrid !== last) {
-    // `scalePoint({ padding: 0.5 })` spreads N points over `xMax`, so one index is `xMax / N` wide.
-    const pxPerIndex = dates.length > 0 ? xMax / dates.length : 0
-    const gapPx = (last - lastOnGrid) * pxPerIndex
-    if (lastOnGrid > 0 && gapPx > 0 && gapPx < perTick) keep.delete(lastOnGrid)
-    keep.add(last)
+    const BOUNDARY_FACTOR = 1.5
+    const boundaryPx = anchored ? perTick * BOUNDARY_FACTOR : perTick
+    // The final key is appended unconditionally, even when the step misses it — but only dropping
+    // the grid tick right before it when the two would otherwise sit closer than one tick's width.
+    // This is the "would an APPEND overlap" concern; it does nothing when the step already lands on
+    // `last` (nothing is being appended), which is the gap the anchored pass below closes.
+    const lastOnGrid = Math.floor(last / step) * step
+    if (lastOnGrid !== last) {
+      const gapPx = (last - lastOnGrid) * pxPerIndex
+      if (lastOnGrid > 0 && gapPx > 0 && gapPx < boundaryPx) keep.delete(lastOnGrid)
+      keep.add(last)
+    }
+  }
+
+  if (anchored && keep.size > 1) {
+    const BOUNDARY_FACTOR = 1.5
+    const boundaryPx = perTick * BOUNDARY_FACTOR
+    // START: the kept index right after 0 needs a FULL label's clearance from it, not the plain
+    // per-tick pitch a centred label would settle for.
+    const sorted = [...keep].toSorted((a, b) => a - b)
+    const second = sorted[1]
+    if (second !== undefined && second !== last && second * pxPerIndex < boundaryPx) {
+      keep.delete(second)
+    }
+    // END: the same check, mirrored, against whatever is now the second-to-last kept index —
+    // computed AFTER the START drop above (not from the original grid), and unconditional of
+    // whether `last` was naturally on the grid or had to be appended (round 3's fix: previously this
+    // only ran inside the `lastOnGrid !== last` branch above, so a grid that already landed on
+    // `last` skipped it — the 13-dates/60px-label/260px-width counter-example this closes: step 4
+    // lands on index 12, leaving its neighbour at index 8 only 80px away, under the 90px a
+    // full-width terminal label needs).
+    const afterHead = [...keep].toSorted((a, b) => a - b)
+    const secondLast = afterHead[afterHead.length - 2]
+    if (
+      secondLast !== undefined &&
+      secondLast !== 0 &&
+      (last - secondLast) * pxPerIndex < boundaryPx
+    ) {
+      keep.delete(secondLast)
+    }
   }
 
   return dates.filter((_, i) => keep.has(i))

package/src/common/errors.ts

@@ -48,10 +48,11 @@ export function deprecatedProp(
   oldProp: string,
   newProp: string,
   removeIn: string,
+  note?: string,
 ): string {
   return message(
     component,
-    `prop "${oldProp}" is deprecated — use "${newProp}" instead. "${oldProp}" is removed in ${removeIn}.`,
+    `prop "${oldProp}" is deprecated — use "${newProp}" instead. "${oldProp}" is removed in ${removeIn}.${note === undefined ? '' : ` ${note}`}`,
   )
 }
 
@@ -69,6 +70,19 @@ export function ignoredProp(component: string, prop: string, because: string): s
   return message(component, `prop "${prop}" is ignored because ${because}`)
 }
 
+/**
+ * A numeric `height` the caller stated that, once the legend band is taken out, leaves the plot
+ * under the floor. The frame keeps the plot at the floor and grows past the number, so the chart
+ * is taller than the caller asked for and nothing else says why.
+ */
+export function plotBelowFloor(component: string, height: number, floor: number): string {
+  return message(
+    component,
+    `prop "height" (${height}) leaves less than the ${floor}px plot floor once the legend band is ` +
+      'subtracted, so the frame grows past it. Raise the height or drop the legend.',
+  )
+}
+
 /**
  * An imperative call needs a layer that is not there — the optional peer is not installed, or the
  * mount that subscribes to its event bus is disabled. Both halves are named because the remedy
@@ -86,6 +100,16 @@ export function duplicateMount(component: string): string {
   )
 }
 
+/** Two frames inside one `ChartCard` both want the header legend slot (`docs/waves/PLAN.md` wave
+ * 3, P2-9) — only the first to mount keeps it, every later one falls back to its own band legend
+ * rather than silently overwriting the portal. */
+export function legendSlotContention(component: string): string {
+  return message(
+    component,
+    'more than one chart in this ChartCard wants the header legend slot — only the first keeps it, the rest fall back to their own band legend.',
+  )
+}
+
 // ── Transport-agnostic error decoding ────────────────────────────────────────────────────────────
 //
 // Deliberately in this module, with NO `@tanstack/react-query` import — `dashboard/query-state.tsx`

package/src/common/hit-floor.ts

@@ -0,0 +1,9 @@
+/**
+ * The pointer-tier hit floors, in px — WCAG 2.5.8 Target Size Minimum (24) and 2.5.5 Target Size
+ * Enhanced (44). One home for the number `--vx-hit` resolves to under `(pointer: coarse)` and for
+ * the components that compare a MEASURED px against it (a virtual list's row height, a column-fold
+ * toggle's width, the chart legend's dot pitch). Deliberately not re-exported through
+ * `common/index.ts`: a CSS-var's numeric value is not a public symbol.
+ */
+export const HIT_FINE = 24
+export const HIT_COARSE = 44

package/src/{shell → common}/isomorphic-layout-effect.ts

@@ -5,9 +5,10 @@
  * nothing on the server" warning. The branch reads a global that cannot change between renders, so
  * the hook identity is stable across every render of every caller.
  *
- * One module rather than one `const` per file: `page-bar.tsx` and `page-aside.tsx` declared the
- * same line with the same doc, and the second copy's doc already said "see `page-bar.tsx`'s copy".
- * Not exported from any barrel — this is a shell-internal utility, not a published hook.
+ * Lives in `common/` rather than beside the shell because both halves use it — the shell chrome, the
+ * provider, and the Mantine-free measured-fold core — and `common/` is the one module both may
+ * import from. One module rather than one `const` per file. Not exported from any barrel; import it
+ * by path.
  */
 import { useEffect, useLayoutEffect } from 'react'