basalt-ui 1.30.2 → 1.31.0

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

@@ -3,104 +3,106 @@
  * is testable without a `ResizeObserver` and `ChartFrame.tsx` stays the measuring/rendering shell.
  */
 
+import { HIT_COARSE } from '../../common/hit-floor'
 import { VX } from '../../tokens'
+import type { ContainerClass } from '../../tokens/size-classes'
 import type { ChartMargin } from '../../tokens'
 import type { LegendEntry } from './ChartLegend'
+import type { SeriesRole } from '../series'
 import { measureText } from '../utils/measure-text'
 
 /** Line box of one legend row at `VX.legendFontSize`. */
 const LEGEND_LINE_H = Math.ceil(VX.legendFontSize * 1.35)
 /** `ChartLegend`'s own vertical wrapper padding (`8px 0 2px`). */
 const LEGEND_PAD_Y = 10
+/** Gap between two wrapped legend rows — tight (4-6px); the wider `VX.legendGap` separates entries. */
+export const LEGEND_ROW_GAP = 6
 /** Swatch plus the gap to its label — the fixed part of a legend entry's width. */
 const LEGEND_SWATCH_W = 24
 
 /**
- * The two size tiers a chart resolves to. There are exactly two, and there is no `tablet`: the
- * tier exists to answer "is there room for full-size chrome around the plot", which is a yes/no
- * question, and a third rung would need a third calibrated metric set nothing has asked for.
+ * The real gap a dots-mode entry needs so its `[data-basalt-hit]::after` overlay can reach the
+ * full 44px coarse floor with NO overlap into its neighbour's overlay (`hit-floor.layout.test.ts` +
+ * `hit-overlap.layout.test.ts`, wave 4's cap: `styles.css`'s `::after` grows to
+ * `min(max(size,44), size + 2 + gap)`). Two 44px-wide overlays centred on same-size hosts touch
+ * with zero overlap only once their PITCH (real gap + host size) is itself >= 44 — below that, the
+ * cap can only shrink the overlay below 44 (honouring WCAG 2.5.8's spacing route) or let it overlap;
+ * there is no gap value that lets it hit 44 exactly while staying flush against a same-size sibling.
+ * `LEGEND_DOT_SIZE` is 8px, so the floor is 44 − 8 − 2 = 34; a few px of headroom against rounding.
  */
-export type ChartTier = 'phone' | 'desktop'
+export const LEGEND_DOT_SIZE = 8
+export const DOTS_HIT_GAP = HIT_COARSE - LEGEND_DOT_SIZE - 2 + 4
+/** One dot's full visual footprint in a wrapped row — the fit basis for dots mode. A chip's
+ * swatch+label width badly overstates what a dot costs, so measuring dots as chips wrapped a
+ * 4-entry legend to its own `All N` row. */
+const DOT_PITCH = LEGEND_DOT_SIZE + DOTS_HIT_GAP
+
+const GROUP_ORDER: SeriesRole[] = ['series', 'overlay', 'reference']
+const roleOf = (item: LegendEntry): SeriesRole => item.role ?? 'series'
 
 /**
- * The tier a chart's chrome resolves to, from the width of the box it was MEASURED in — never
- * from a media query.
- *
- * A viewport breakpoint answers the wrong question. A chart in a 2-column grid cell on a 1440px
- * desktop is exactly as narrow as one filling a phone, and `@media` cannot see that; the
- * `ResizeObserver` `ChartFrame` already runs can. It also keeps this file (and the whole chart
- * layer) Mantine-free — `theme.breakpoints` is on the coupled side of the boundary.
- *
- * An UNMEASURED box (`containerW <= 0` — SSR, or before the observer's first callback) resolves
- * to `'desktop'`: the first frame must not paint phone chrome that then re-lays-out one frame
- * later, and `resolvePlotRect` already treats an unmeasured width as the first-frame case.
+ * Order entries series → overlay → reference and record where a divider belongs — the ONE ordering
+ * both `ChartLegend`'s render and the resolver's fit math (`chart-layout.ts`) use, so a dots-mode
+ * fit never disagrees with what actually wraps (a grouped legend renders dividers as flex items).
  */
-export function resolveChartTier(containerW: number): ChartTier {
-  return containerW > 0 && containerW < VX.phoneChartWidth ? 'phone' : 'desktop'
+export function orderEntries(
+  items: readonly LegendEntry[],
+  groups: boolean,
+): { entries: LegendEntry[]; dividerAfter: ReadonlySet<number> } {
+  if (!groups) return { entries: [...items], dividerAfter: new Set() }
+
+  const dividerAfter = new Set<number>()
+  const entries: LegendEntry[] = []
+  const nonEmptyGroups = GROUP_ORDER.map((role) =>
+    items.filter((item) => roleOf(item) === role),
+  ).filter((group) => group.length > 0)
+  nonEmptyGroups.forEach((group, i) => {
+    entries.push(...group)
+    if (i < nonEmptyGroups.length - 1) dividerAfter.add(entries.length - 1)
+  })
+  return { entries, dividerAfter }
 }
 
 /**
- * A chart height stated per size step instead of as one number — the declarative escape from "every
- * chart on this page is 260px tall on a 375px phone too".
+ * The two metric sets a chart's chrome resolves to. Internally the container class
+ * (`micro`/`compact` → `'phone'`, `regular`/`wide` → `'desktop'`) picks one; there is no `tablet`.
+ * Internal only — not on any public barrel.
+ */
+export type ChartTier = 'phone' | 'desktop'
+
+/**
+ * A chart height stated per container step instead of as one number — the declarative escape from
+ * "every chart on this page is 260px tall on a 375px phone too".
  *
- * `base` is required and is the height a box narrower than every named step gets; each further key
- * is the height from that step UP. Keys are Mantine's breakpoint names so a consumer writes the
- * vocabulary they already write, and nothing more than `sm`/`md`/`lg` is offered: `xs`/`xl` would
- * be two more rungs nobody has asked a chart to have.
+ * `base` is the height below the `regular` class; `regular` and `wide` take effect from
+ * `CONTAINER_CLASSES.regular` / `.wide` of the frame's MEASURED width (never the viewport).
  *
  * ```tsx
- * <ChartFrame series={series} height={{ base: 180, md: 260 }}>{…}</ChartFrame>
+ * <ChartFrame series={series} height={{ base: 180, wide: 260 }}>{…}</ChartFrame>
  * ```
  */
 export type ResponsiveChartHeight = {
-  /** Below the narrowest STATED step — and NOT the first-frame value; see {@link resolveFrameHeight}. */
   base: number
-  /** From 768px of MEASURED container width up. */
-  sm?: number
-  /** From 992px up. */
-  md?: number
-  /** From 1200px up. */
-  lg?: number
+  /** From the `regular` container class (480px) up. */
+  regular?: number
+  /** From the `wide` container class (800px) up. */
+  wide?: number
 }
 
 /**
- * The measured CONTAINER width, in px, each {@link ResponsiveChartHeight} key takes effect at.
- *
- * The numbers are what Mantine's `sm`/`md`/`lg` breakpoints resolve to at the 16px initial font
- * size, so a consumer's mental model transfers — but they are compared against the element's own
- * MEASURED box, never the viewport, for the reason {@link resolveChartTier} states: a chart in a
- * `PageAside`-squeezed grid cell on a 1440px desktop is as narrow as one on a phone, and the
- * viewport agrees with neither. Keeping them as plain numbers here is also what keeps this file
- * Mantine-free — `theme.breakpoints` is on the coupled side of the boundary.
- */
-const HEIGHT_STEP_WIDTH = { sm: 768, md: 992, lg: 1200 } as const
-
-/** Widest-first, so the first step that fits is the answer. */
-const HEIGHT_STEPS = ['lg', 'md', 'sm'] as const
-
-/**
- * Resolve a `height` prop — a plain number, or a {@link ResponsiveChartHeight} — against the
- * measured container width.
- *
- * A plain number passes through untouched: this is a WIDENING of the prop, not a replacement, and
- * every existing `height={240}` must keep meaning exactly 240.
- *
- * An UNMEASURED box (`containerW <= 0` — SSR, or before the `ResizeObserver`'s first callback)
- * resolves to the LARGEST stated step, matching {@link resolveChartTier}'s first-frame rule: the
- * first paint must not be phone-shaped chrome that grows one frame later. Falling to `base` there
- * would make every SSR'd chart short and then jump.
+ * Resolve a `height` prop — a plain number, or a {@link ResponsiveChartHeight} — for a container
+ * class. A plain number passes through untouched. The class is the measured one, or, before the
+ * first measurement, the one implied by the viewport ({@link resolveChartLayout}), so the first
+ * frame is not a different height from the second.
  */
 export function resolveFrameHeight(
   height: number | ResponsiveChartHeight,
-  containerW: number,
+  containerClass: ContainerClass,
 ): number {
   if (typeof height === 'number') return height
-  const widest = HEIGHT_STEPS.find((step) => height[step] !== undefined)
-  if (containerW <= 0) return widest === undefined ? height.base : (height[widest] ?? height.base)
-  const step = HEIGHT_STEPS.find(
-    (name) => containerW >= HEIGHT_STEP_WIDTH[name] && height[name] !== undefined,
-  )
-  return step === undefined ? height.base : (height[step] ?? height.base)
+  if (containerClass === 'wide') return height.wide ?? height.regular ?? height.base
+  if (containerClass === 'regular') return height.regular ?? height.base
+  return height.base
 }
 
 /**
@@ -114,16 +116,14 @@ const PHONE_MARGIN_SCALE = 0.75
  * the smaller stroke widths a narrow chart draws. */
 const PHONE_DOT_R = Math.max(VX.dotR - 1, 2)
 
-/** Legend entries a phone-tier legend renders before rolling the rest into `+N more`. Two is the
- * cap because a third entry wraps at every realistic phone width, and a wrapped legend is what
- * eats the plot (`legendEntryCap`). */
-const PHONE_LEGEND_MAX_ROWS = 2
-
 /** Tooltip `minWidth`, per tier — 140px is 39% of a 360px screen. */
 const TOOLTIP_MIN_WIDTH = { desktop: 140, phone: 110 } as const
 
-/** Every size a chart's chrome resolves per tier. One object so a new tier-sensitive size is added
- * in one place and read by name, rather than each primitive branching on the tier itself. */
+/**
+ * Every size a chart's chrome resolves per tier. One object so a new tier-sensitive size is added
+ * in one place and read by name, rather than each primitive branching on the tier itself. Internal
+ * only — not on any public barrel.
+ */
 export type ChartTierMetrics = {
   /** Which tier these are, so a consumer of the metrics never needs both values threaded. */
   tier: ChartTier
@@ -136,9 +136,6 @@ export type ChartTierMetrics = {
   dotR: number
   /** Floating tooltip `minWidth`, px. */
   tooltipMinWidth: number
-  /** Default entry cap on the legend, or `undefined` for no default cap. An explicit
-   * `legend.maxRows` replaces it outright ({@link resolveLegendMaxRows}). */
-  legendMaxRows: number | undefined
   /** Per-side margin FLOORS (`VX.margin` is a floor, never a ceiling — §1). */
   margin: ChartMargin
 }
@@ -149,7 +146,6 @@ const DESKTOP_METRICS: ChartTierMetrics = {
   legendFontSize: VX.legendFontSize,
   dotR: VX.dotR,
   tooltipMinWidth: TOOLTIP_MIN_WIDTH.desktop,
-  legendMaxRows: undefined,
   margin: VX.margin,
 }
 
@@ -161,7 +157,6 @@ const PHONE_METRICS: ChartTierMetrics = {
   legendFontSize: VX.text.xs,
   dotR: PHONE_DOT_R,
   tooltipMinWidth: TOOLTIP_MIN_WIDTH.phone,
-  legendMaxRows: PHONE_LEGEND_MAX_ROWS,
   margin: {
     top: Math.round(VX.margin.top * PHONE_MARGIN_SCALE),
     right: Math.round(VX.margin.right * PHONE_MARGIN_SCALE),
@@ -170,58 +165,30 @@ const PHONE_METRICS: ChartTierMetrics = {
   },
 }
 
-/** The resolved sizes for one tier. Frozen module constants — never a new object per render. */
-export function chartTierMetrics(tier: ChartTier): ChartTierMetrics {
-  return tier === 'phone' ? PHONE_METRICS : DESKTOP_METRICS
-}
-
-/**
- * Which legend cap applies: the caller's, or the tier's own default.
- *
- * **An explicit `callerMaxRows` wins OUTRIGHT.** This used to be `Math.min(caller, tier)`, which
- * made the documented per-chart opt-out ("opt back out with an explicit `legend.maxRows`") false in
- * the one direction anybody needs it. The tier's `PHONE_LEGEND_MAX_ROWS` is a DEFAULT for charts
- * that said nothing — a chart that names a number has already answered the question the default
- * exists to answer, and it matters because the tier keys on the measured box: a 380px inspector
- * panel on a 1440px desktop is "a phone", so a six-series legend rolled up to two rows + `+4 more`
- * with no way to say no. `margin` and `xLabelRotate` always had that escape; the legend did not.
- *
- * The measured {@link legendEntryCap} a `fill` frame applies is NOT a second ceiling on top of
- * this: it resolves an ABSENT cap only. 1.30.0 ran it over the caller's number as well
- * (`Math.min(fitted, caller)`), which made "wins outright" false again in the one place it was
- * needed — meteo measured a 7-entry legend pinned to 2 entries at `maxRows` 3, 6 AND 99, with 5
- * series drawn in colours the legend refused to name. The fit is not physics either: it derives
- * from `VX.minPlotHeight`, which is a framework DEFAULT about the plot. Two defaults do not
- * outvote the one number a caller stated, so the PLOT yields the height instead
- * ({@link resolvePlotRect}'s `legendWins`) — visibly, in the frame the caller sized.
- */
-export function resolveLegendMaxRows(input: {
-  callerMaxRows?: number | undefined
-  tier: ChartTier
-}): number | undefined {
-  return input.callerMaxRows ?? chartTierMetrics(input.tier).legendMaxRows
+/** The metric set a container class resolves to (`micro`/`compact` → phone, else desktop). */
+export function chartMetrics(containerClass: ContainerClass): ChartTierMetrics {
+  return containerClass === 'micro' || containerClass === 'compact'
+    ? PHONE_METRICS
+    : DESKTOP_METRICS
 }
 
 /**
  * The whole legend-cap decision in one place: which cap `ChartLegend` gets, and whether the plot
- * pays for it.
- *
- * It lives here rather than inline in `ChartFrame` because the COMPOSITION is what broke. 1.30.0
- * had both halves right on their own — {@link resolveLegendMaxRows} honoured a stated cap,
- * {@link legendEntryCap} measured a fit — and then ran the second over the first, which no test
- * could see because neither pure function was wrong and the frame that combined them needs a
- * `ResizeObserver` to test. Now the combination is a pure function too.
+ * pays for it. Pure, because the COMPOSITION is what once broke (1.30.0 ran a measured fit over a
+ * caller's stated number) and the frame that combines them needs a `ResizeObserver` to test.
  *
  * Three cases, in order:
- * 1. The caller STATED a number → it is the cap, and on a `fill` band the plot yields
- *    (`legendWins`). Nothing measured or defaulted trims it.
- * 2. No `fill` band → the tier's default (or none), because the frame simply grows.
- * 3. A `fill` band with nothing stated → the measured fit, bounded by the tier's default.
+ * 1. The caller STATED `legend.maxRows` (deprecated, still honoured) → it is the cap, and on a
+ *    `fill` band the plot yields (`legendWins`). Nothing measured trims it.
+ * 2. No `fill` band → the resolver's width-measured fit (`fittedMaxRows`), because the frame grows.
+ * 3. A `fill` band with nothing stated → the tighter of that fit and the height-measured
+ *    {@link legendEntryCap}, because a `fill` box cannot grow.
  */
 export function resolveLegendRollup(input: {
   /** The caller's own `legend.maxRows`. */
   statedMaxRows?: number | undefined
-  tier: ChartTier
+  /** `resolveChartLayout().legend.visible` when it overflows, else `undefined`. */
+  fittedMaxRows?: number | undefined
   /** A visible top/bottom legend on a `fill` frame — the one shape whose box cannot grow. */
   fillBand: boolean
   items: readonly LegendEntry[]
@@ -229,16 +196,15 @@ export function resolveLegendRollup(input: {
   /** Frame height the legend may consume — `resolvedHeight - VX.minPlotHeight`. */
   available: number
 }): { maxRows: number | undefined; legendWins: boolean } {
-  const { statedMaxRows, tier, fillBand, items, containerW, available } = input
+  const { statedMaxRows, fittedMaxRows, fillBand, items, containerW, available } = input
   if (statedMaxRows !== undefined) return { maxRows: statedMaxRows, legendWins: fillBand }
-  const tierMaxRows = resolveLegendMaxRows({ callerMaxRows: undefined, tier })
-  if (!fillBand) return { maxRows: tierMaxRows, legendWins: false }
+  if (!fillBand) return { maxRows: fittedMaxRows, legendWins: false }
   return {
     maxRows: legendEntryCap({
       items,
       containerW,
       available,
-      ...(tierMaxRows !== undefined && { defaultMaxRows: tierMaxRows }),
+      ...(fittedMaxRows !== undefined && { defaultMaxRows: fittedMaxRows }),
     }),
     legendWins: false,
   }
@@ -248,22 +214,13 @@ export function resolveLegendRollup(input: {
  * Resolve the plot rect from the measured box and the measured legend band. Pure and exported so
  * the two floors below are testable without a `ResizeObserver`.
  *
- * Two floors, and each is only a floor while it is honest:
- * - **width** — `minWidth` is a FIRST-FRAME guard, applied only while `containerW` is still 0
- *   (unmeasured, or SSR, where the observer never fires). Once measured the plot tracks the box
- *   exactly, floored at 1 so no scale divides by zero: applying a 200px floor forever drew an SVG
- *   wider than its own container inside any narrower grid cell.
- * - **height** — the legend band is subtracted first (it always was), but the remainder can no
- *   longer collapse: eight entries wrapping to five rows at phone width ate a fixed
- *   `height={240}` toward zero and the body stopped rendering entirely. The plot stops at
- *   `VX.minPlotHeight` and the frame's own box grows by the difference instead — it is a flex
- *   column with `height: auto`, so that growth is automatic. Under `fill` the box CANNOT grow, so
- *   the legend is capped instead ({@link legendEntryCap}) — UNLESS the caller stated
- *   `legend.maxRows`, which is `legendWins`: there the floor itself yields, because a floor is a
- *   default and the caller's number is not, but only as far as the box HAS room
- *   ({@link SELF_MEASURED_SLACK}). An unmeasured box (`resolvedHeight <= 0`, i.e. a `fill` frame
- *   before its first measurement) stays at 0 and renders nothing, exactly as before — the floor
- *   must never invent a height for a box nobody has measured.
+ * `minWidth` is a FIRST-FRAME guard, applied only while `containerW` is still 0 (unmeasured, or
+ * SSR); once measured the plot tracks the box exactly, floored at 1 so no scale divides by zero.
+ * The legend band is subtracted first, and the remainder stops at `VX.minPlotHeight` — the frame's
+ * flex box grows by the difference under a fixed height, and under `fill` (which cannot grow) the
+ * legend is capped instead ({@link legendEntryCap}). A caller-stated `legend.maxRows` yields the
+ * floor itself (`legendWins`) as far as the box has room ({@link SELF_MEASURED_SLACK}); an
+ * unmeasured box (`resolvedHeight <= 0`) stays 0 and renders nothing.
  */
 export function resolvePlotRect(input: {
   containerW: number
@@ -297,33 +254,20 @@ export function resolvePlotRect(input: {
   }
 }
 
-/**
- * Sub-pixel slack on "the frame measures its own legend band and nothing else".
- *
- * MEASURED exact in the collapse this guards (both `ResizeObserver` contentRects read 29.375 in
- * headless Chrome, `tests/layout/charts.layout.test.ts` INVARIANT 7) — the slack exists only so a
- * future rounding or border difference between the two observers cannot re-open a fixpoint that
- * has no other way out. A plot this thin has nothing to draw either way.
- */
+/** Sub-pixel slack on "the frame measures its own legend band and nothing else" — absorbs a
+ * future rounding or border difference between the two observers without re-opening the zero
+ * fixpoint below. */
 const SELF_MEASURED_SLACK = 0.5
 
 /**
  * Is the frame's height its OWN content rather than a box something else stated?
  *
- * `ChartFrame` measures its own node (`useChartSize` → visx `useParentSize` observes the element
- * the ref is attached to, its name notwithstanding), and under `fill` its `height: 100%` resolves
- * to `auto` in any parent that states no height. Its only children are the plot and the legend, so
- * `room === 0` means the box IS the legend band — which happens exactly when no plot was drawn.
- *
- * That is why `legendWins` cannot yield the floor there: with the floor gone the sequence has a
- * FIXPOINT AT ZERO — plot 0 → content is the legend → box = band → room 0 → plot 0, forever, and
- * the chart never appears. Keeping the floor while `room` is 0 converges on the same box a `fill`
- * frame in an unsized parent has always had (plot `VX.minPlotHeight`, box = plot + band), from
- * which `room` is positive and `legendWins` applies normally.
- *
- * A NEGATIVE `room` is not this case and must keep yielding: a self-measured box can never be
- * shorter than its own content, so a band taller than the box means the box was stated by
- * something else, and spending all of it on legend rows is the caller's own arithmetic.
+ * Under `fill` a frame in an unsized parent resolves its height to `auto`; its only children are
+ * the plot and the legend, so `room === 0` means the box IS the legend band. There `legendWins`
+ * must NOT yield the floor — with the floor gone the sequence has a fixpoint at zero (plot 0 →
+ * content is the legend → box = band → room 0 → plot 0 forever). A NEGATIVE `room` is not this
+ * case: a self-measured box can never be shorter than its own content, so the box was stated by
+ * something else, and spending all of it on legend rows is the caller's arithmetic.
  */
 function isSelfMeasured(room: number): boolean {
   return room >= 0 && room < SELF_MEASURED_SLACK
@@ -331,7 +275,7 @@ function isSelfMeasured(room: number): boolean {
 
 /** Height of a legend band `rows` rows tall, wrapper padding included. */
 const legendBandHeight = (rows: number): number =>
-  LEGEND_PAD_Y + rows * LEGEND_LINE_H + Math.max(rows - 1, 0) * VX.legendGap
+  LEGEND_PAD_Y + rows * LEGEND_LINE_H + Math.max(rows - 1, 0) * LEGEND_ROW_GAP
 
 /** Width one legend entry occupies — swatch, gap, label, and the note that rides after it. */
 const legendEntryWidth = (item: LegendEntry): number =>
@@ -341,15 +285,27 @@ const legendEntryWidth = (item: LegendEntry): number =>
     VX.legendFontSize,
   )
 
-/** How many of `items` fit in `rows` wrapped rows of `width` — the same greedy wrap the flex
- * container performs, measured rather than assumed (`docs/CHARTS-SPEC.md` §1). */
-function entriesWithinRows(items: readonly LegendEntry[], width: number, rows: number): number {
+/**
+ * The greedy chip-width wrap {@link entriesWithinRows} runs — split out so
+ * {@link entriesWithinChipRows} can run it a second time against a narrower, reserve-adjusted
+ * width without duplicating the wrap arithmetic. `allowZero` (default false) drops the "the first
+ * entry always fits" guarantee a bare row-fit needs (a raw width-vs-0 check is meaningless
+ * otherwise): without it, the SAME entry the caller is about to also draw an `All N` chip beside
+ * would always be counted as fitting even when the two together provably don't.
+ */
+function fitChipRows(
+  items: readonly LegendEntry[],
+  width: number,
+  rows: number,
+  allowZero = false,
+): number {
   let row = 1
   let x = 0
   let fitted = 0
   for (const item of items) {
     const w = legendEntryWidth(item)
     const next = x === 0 ? w : x + VX.legendGap + w
+    if (x === 0 && allowZero && next > width) return 0
     if (next > width && x > 0) {
       row += 1
       if (row > rows) return fitted
@@ -362,20 +318,101 @@ function entriesWithinRows(items: readonly LegendEntry[], width: number, rows: n
   return fitted
 }
 
+/** How many of `items` fit in `rows` wrapped rows of `width` — the same greedy wrap the flex
+ * container performs, measured rather than assumed (`docs/CHARTS-SPEC.md` §1). */
+export function entriesWithinRows(
+  items: readonly LegendEntry[],
+  width: number,
+  rows: number,
+): number {
+  return fitChipRows(items, width, rows)
+}
+
 /**
- * The entry cap a `fill` frame's legend must respect so the plot keeps `VX.minPlotHeight`.
+ * Chips-mode counterpart of {@link entriesWithinDotRows}: once the un-reserved fit overflows, a
+ * second pass measures against the width LESS the `All N` chip's own footprint, so the count this
+ * returns still leaves the chip room to sit beside it in the same row — same reserve law the dots
+ * fit already applied, now applied to chip width instead of a dot's pitch. Returns 0 when not even
+ * the first chip fits once the chip's width is reserved, so the row renders the disclosure alone
+ * rather than one crowded chip plus a chip that doesn't actually fit next to it.
+ */
+export function entriesWithinChipRows(
+  items: readonly LegendEntry[],
+  width: number,
+  rows: number,
+): number {
+  const total = items.length
+  const fittedNoReserve = fitChipRows(items, width, rows)
+  if (fittedNoReserve >= total) return fittedNoReserve
+  const reserve = measureText(`All ${total}`, VX.legendFontSize) + VX.legendGap
+  return fitChipRows(items, Math.max(width - reserve, 0), rows, true)
+}
+
+/** The greedy dot-pitch wrap `entriesWithinDotRows` runs twice — once optimistically, once against
+ * a width that already gave up the `All N` chip's room. A group divider is its own flex item, so it
+ * costs one more pitch before the next dot. `allowZero` (default false) mirrors {@link fitChipRows}'s
+ * own flag: without it the first dot always counts as fitted regardless of `width`, which is wrong
+ * for the reserved pass once reserving has left no usable room at all. */
+function fitDotRows(
+  items: readonly LegendEntry[],
+  width: number,
+  rows: number,
+  dividerAfter: ReadonlySet<number>,
+  allowZero = false,
+): number {
+  let row = 1
+  let x = 0
+  let fitted = 0
+  for (let i = 0; i < items.length; i += 1) {
+    // `DOT_PITCH` already IS one dot's full footprint (its own size plus the gap to a neighbour,
+    // `LEGEND_DOT_SIZE + DOTS_HIT_GAP`) — adding `LEGEND_DOT_SIZE` again here double-counted every
+    // dot after the row's first, wrapping a legend to `All N` well before it actually overflowed.
+    const next = x === 0 ? LEGEND_DOT_SIZE : x + DOT_PITCH
+    if (x === 0 && allowZero && next > width) return 0
+    if (next > width && x > 0) {
+      row += 1
+      if (row > rows) return fitted
+      x = LEGEND_DOT_SIZE
+    } else {
+      x = next
+    }
+    fitted += 1
+    if (dividerAfter.has(i)) x += DOT_PITCH
+  }
+  return fitted
+}
+
+/**
+ * How many of `items` fit as DOTS in `rows` wrapped rows of `width` — the dots-mode counterpart of
+ * {@link entriesWithinRows}, measured at the dot's own pitch rather than a chip's width.
+ * `dividerAfter` (from {@link orderEntries}) counts a rendered group divider's own gap.
  *
- * A fixed-height frame grows to fit its legend; a `fill` frame is pinned to its cell, so the only
- * remaining lever is `ChartLegend`'s `maxRows` rollup (an ENTRY cap — see its JSDoc). The rows the
- * legend may take follow from the height left over; how many entries that is follows from
- * MEASURING the labels, not from assuming one entry per row — otherwise a five-entry legend that
- * fits on one line would roll up to `+2 more` in every 240px cell, moving rendering for charts
- * that never had the bug. Returns `undefined` when the whole legend already fits.
+ * Two passes: every entry visible with no `All N` chip (if that fits, no chip is drawn); otherwise
+ * reserve the chip's measured width up front so it can never wrap to a row of its own — and, once
+ * reserved, allow the answer to be 0: a chip wide enough to leave no room for even the first dot
+ * means the row draws the disclosure alone, not one dot crowding a chip that no longer fits beside it.
+ */
+export function entriesWithinDotRows(
+  items: readonly LegendEntry[],
+  width: number,
+  rows: number,
+  dividerAfter: ReadonlySet<number> = new Set(),
+): number {
+  const total = items.length
+  const fittedNoReserve = fitDotRows(items, width, rows, dividerAfter)
+  if (fittedNoReserve >= total) return fittedNoReserve
+  const reserve = measureText(`All ${total}`, VX.legendFontSize) + DOT_PITCH
+  return fitDotRows(items, Math.max(width - reserve, 0), rows, dividerAfter, true)
+}
+
+/**
+ * The entry cap a `fill` frame's legend must respect so the plot keeps `VX.minPlotHeight`. A
+ * `fill` frame is pinned to its cell, so the only lever is `ChartLegend`'s `maxRows` rollup; how
+ * many entries fit follows from MEASURING the labels, not assuming one per row. Returns
+ * `undefined` when the whole legend already fits.
  *
- * This resolves an ABSENT cap. A caller who stated `legend.maxRows` never reaches here at all —
- * `ChartFrame` routes around it — because `Math.min`-ing a stated number against this one made the
- * documented escape inert in exactly the narrow `fill` panel it exists for
- * ({@link resolveLegendMaxRows}).
+ * Resolves an ABSENT cap only: a caller who stated `legend.maxRows` never reaches here
+ * ({@link resolveLegendRollup} routes around it), so the documented escape is never made inert.
  */
 export function legendEntryCap(input: {
   items: readonly LegendEntry[]
@@ -383,8 +420,8 @@ export function legendEntryCap(input: {
   /** Frame height the legend may consume — `resolvedHeight - VX.minPlotHeight`. */
   available: number
   /**
-   * The cap that applies when nothing explicit was stated — today only the tier's own default
-   * ({@link chartTierMetrics}). Two defaults contending: the smaller wins.
+   * The cap that applies when nothing explicit was stated — the resolver's width fit. Two
+   * defaults contending: the smaller wins.
    */
   defaultMaxRows?: number
 }): number | undefined {
@@ -392,7 +429,7 @@ export function legendEntryCap(input: {
   if (containerW <= 0 || items.length === 0) return defaultMaxRows
   const rows = Math.max(
     1,
-    Math.floor((available - LEGEND_PAD_Y + VX.legendGap) / (LEGEND_LINE_H + VX.legendGap)),
+    Math.floor((available - LEGEND_PAD_Y + LEGEND_ROW_GAP) / (LEGEND_LINE_H + LEGEND_ROW_GAP)),
   )
   if (
     legendBandHeight(rows) <= available &&