basalt-ui 1.30.2 → 1.31.0

package/dist/charts/primitives/chart-frame-layout.d.ts

@@ -2,66 +2,68 @@
  * Pure, DOM-free layout math behind `ChartFrame`'s plot/legend split — extracted so the arithmetic
  * is testable without a `ResizeObserver` and `ChartFrame.tsx` stays the measuring/rendering shell.
  */
+import type { ContainerClass } from '../../tokens/size-classes.js';
 import type { ChartMargin } from '../../tokens/index.js';
 import type { LegendEntry } from './ChartLegend.js';
+/** Gap between two wrapped legend rows — tight (4-6px); the wider `VX.legendGap` separates entries. */
+export declare const LEGEND_ROW_GAP = 6;
 /**
- * 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 declare const LEGEND_DOT_SIZE = 8;
+export declare const DOTS_HIT_GAP: number;
 /**
- * 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 declare function orderEntries(items: readonly LegendEntry[], groups: boolean): {
+    entries: LegendEntry[];
+    dividerAfter: ReadonlySet<number>;
+};
+/**
+ * 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 declare function resolveChartTier(containerW: number): ChartTier;
+export type ChartTier = 'phone' | 'desktop';
 /**
- * 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".
+ * 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;
 };
 /**
- * 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 declare function resolveFrameHeight(height: number | ResponsiveChartHeight, containerClass: ContainerClass): number;
+/**
+ * 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 declare function resolveFrameHeight(height: number | ResponsiveChartHeight, containerW: number): number;
-/** 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. */
 export type ChartTierMetrics = {
     /** Which tier these are, so a consumer of the metrics never needs both values threaded. */
     tier: ChartTier;
@@ -74,58 +76,28 @@ 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;
 };
-/** The resolved sizes for one tier. Frozen module constants — never a new object per render. */
-export declare function chartTierMetrics(tier: ChartTier): ChartTierMetrics;
-/**
- * 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 declare function resolveLegendMaxRows(input: {
-    callerMaxRows?: number | undefined;
-    tier: ChartTier;
-}): number | undefined;
+/** The metric set a container class resolves to (`micro`/`compact` → phone, else desktop). */
+export declare function chartMetrics(containerClass: ContainerClass): ChartTierMetrics;
 /**
  * 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 declare 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[];
@@ -140,22 +112,13 @@ export declare 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 declare function resolvePlotRect(input: {
     containerW: number;
@@ -176,20 +139,37 @@ export declare function resolvePlotRect(input: {
     width: number;
     height: number;
 };
+/** 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 declare function entriesWithinRows(items: readonly LegendEntry[], width: number, rows: number): number;
+/**
+ * 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 declare function entriesWithinChipRows(items: readonly LegendEntry[], width: number, rows: number): number;
 /**
- * The entry cap a `fill` frame's legend must respect so the plot keeps `VX.minPlotHeight`.
+ * 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 declare function entriesWithinDotRows(items: readonly LegendEntry[], width: number, rows: number, dividerAfter?: ReadonlySet<number>): number;
+/**
+ * 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 declare function legendEntryCap(input: {
     items: readonly LegendEntry[];
@@ -197,8 +177,8 @@ export declare 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;

package/dist/charts/primitives/chart-frame-layout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chart-frame-layout.d.ts","sourceRoot":"","sources":["../../../src/charts/primitives/chart-frame-layout.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"chart-frame-layout.d.ts","sourceRoot":"","sources":["../../../src/charts/primitives/chart-frame-layout.ts"],"names":[],"mappings":"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"}

package/dist/charts/primitives/chart-frame-layout.js

@@ -1,25 +1,36 @@
+import { HIT_COARSE } from "../../common/hit-floor.js";
 import { VX } from "../../tokens/index.js";
 import { measureText } from "../utils/measure-text.js";
 const LEGEND_LINE_H = Math.ceil(VX.legendFontSize * 1.35);
 const LEGEND_PAD_Y = 10;
+const LEGEND_ROW_GAP = 6;
 const LEGEND_SWATCH_W = 24;
-function resolveChartTier(containerW) {
-  return containerW > 0 && containerW < VX.phoneChartWidth ? "phone" : "desktop";
+const LEGEND_DOT_SIZE = 8;
+const DOTS_HIT_GAP = HIT_COARSE - LEGEND_DOT_SIZE - 2 + 4;
+const DOT_PITCH = LEGEND_DOT_SIZE + DOTS_HIT_GAP;
+const GROUP_ORDER = ["series", "overlay", "reference"];
+const roleOf = (item) => item.role ?? "series";
+function orderEntries(items, groups) {
+  if (!groups) return { entries: [...items], dividerAfter: /* @__PURE__ */ new Set() };
+  const dividerAfter = /* @__PURE__ */ new Set();
+  const entries = [];
+  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 };
 }
-const HEIGHT_STEP_WIDTH = { sm: 768, md: 992, lg: 1200 };
-const HEIGHT_STEPS = ["lg", "md", "sm"];
-function resolveFrameHeight(height, containerW) {
+function resolveFrameHeight(height, containerClass) {
   if (typeof height === "number") return height;
-  const widest = HEIGHT_STEPS.find((step2) => height[step2] !== void 0);
-  if (containerW <= 0) return widest === void 0 ? height.base : height[widest] ?? height.base;
-  const step = HEIGHT_STEPS.find(
-    (name) => containerW >= HEIGHT_STEP_WIDTH[name] && height[name] !== void 0
-  );
-  return step === void 0 ? 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;
 }
 const PHONE_MARGIN_SCALE = 0.75;
 const PHONE_DOT_R = Math.max(VX.dotR - 1, 2);
-const PHONE_LEGEND_MAX_ROWS = 2;
 const TOOLTIP_MIN_WIDTH = { desktop: 140, phone: 110 };
 const DESKTOP_METRICS = {
   tier: "desktop",
@@ -27,7 +38,6 @@ const DESKTOP_METRICS = {
   legendFontSize: VX.legendFontSize,
   dotR: VX.dotR,
   tooltipMinWidth: TOOLTIP_MIN_WIDTH.desktop,
-  legendMaxRows: void 0,
   margin: VX.margin
 };
 const PHONE_METRICS = {
@@ -38,7 +48,6 @@ const PHONE_METRICS = {
   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),
@@ -46,23 +55,19 @@ const PHONE_METRICS = {
     left: Math.round(VX.margin.left * PHONE_MARGIN_SCALE)
   }
 };
-function chartTierMetrics(tier) {
-  return tier === "phone" ? PHONE_METRICS : DESKTOP_METRICS;
-}
-function resolveLegendMaxRows(input) {
-  return input.callerMaxRows ?? chartTierMetrics(input.tier).legendMaxRows;
+function chartMetrics(containerClass) {
+  return containerClass === "micro" || containerClass === "compact" ? PHONE_METRICS : DESKTOP_METRICS;
 }
 function resolveLegendRollup(input) {
-  const { statedMaxRows, tier, fillBand, items, containerW, available } = input;
+  const { statedMaxRows, fittedMaxRows, fillBand, items, containerW, available } = input;
   if (statedMaxRows !== void 0) return { maxRows: statedMaxRows, legendWins: fillBand };
-  const tierMaxRows = resolveLegendMaxRows({ callerMaxRows: void 0, tier });
-  if (!fillBand) return { maxRows: tierMaxRows, legendWins: false };
+  if (!fillBand) return { maxRows: fittedMaxRows, legendWins: false };
   return {
     maxRows: legendEntryCap({
       items,
       containerW,
       available,
-      ...tierMaxRows !== void 0 && { defaultMaxRows: tierMaxRows }
+      ...fittedMaxRows !== void 0 && { defaultMaxRows: fittedMaxRows }
     }),
     legendWins: false
   };
@@ -87,18 +92,19 @@ const SELF_MEASURED_SLACK = 0.5;
 function isSelfMeasured(room) {
   return room >= 0 && room < SELF_MEASURED_SLACK;
 }
-const legendBandHeight = (rows) => LEGEND_PAD_Y + rows * LEGEND_LINE_H + Math.max(rows - 1, 0) * VX.legendGap;
+const legendBandHeight = (rows) => LEGEND_PAD_Y + rows * LEGEND_LINE_H + Math.max(rows - 1, 0) * LEGEND_ROW_GAP;
 const legendEntryWidth = (item) => LEGEND_SWATCH_W + measureText(
   item.note === void 0 ? item.label : `${item.label} ${item.note}`,
   VX.legendFontSize
 );
-function entriesWithinRows(items, width, rows) {
+function fitChipRows(items, width, rows, allowZero = false) {
   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;
@@ -110,12 +116,48 @@ function entriesWithinRows(items, width, rows) {
   }
   return fitted;
 }
+function entriesWithinRows(items, width, rows) {
+  return fitChipRows(items, width, rows);
+}
+function entriesWithinChipRows(items, width, rows) {
+  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);
+}
+function fitDotRows(items, width, rows, dividerAfter, allowZero = false) {
+  let row = 1;
+  let x = 0;
+  let fitted = 0;
+  for (let i = 0; i < items.length; i += 1) {
+    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;
+}
+function entriesWithinDotRows(items, width, rows, dividerAfter = /* @__PURE__ */ new Set()) {
+  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);
+}
 function legendEntryCap(input) {
   const { items, containerW, available, defaultMaxRows } = 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 && entriesWithinRows(items, containerW, rows) >= items.length) {
     return defaultMaxRows;
@@ -124,11 +166,16 @@ function legendEntryCap(input) {
   return defaultMaxRows === void 0 ? fitted : Math.min(fitted, defaultMaxRows);
 }
 export {
-  chartTierMetrics,
+  DOTS_HIT_GAP,
+  LEGEND_DOT_SIZE,
+  LEGEND_ROW_GAP,
+  chartMetrics,
+  entriesWithinChipRows,
+  entriesWithinDotRows,
+  entriesWithinRows,
   legendEntryCap,
-  resolveChartTier,
+  orderEntries,
   resolveFrameHeight,
-  resolveLegendMaxRows,
   resolveLegendRollup,
   resolvePlotRect
 };

package/dist/charts/primitives/chart-layout.d.ts

@@ -0,0 +1,112 @@
+/**
+ * `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 type { ContainerClass, SIZE_CLASSES } from '../../tokens/size-classes.js';
+import type { ChartMargin } from '../../tokens/index.js';
+import type { LegendEntry } from './ChartLegend.js';
+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;
+    };
+};
+/** Compact and micro plots are tight: y labels move inside and terminal x labels anchor inward. */
+export declare function isTightClass(containerClass: ContainerClass): boolean;
+/**
+ * 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 declare function resolveYPlacement(containerClass: ContainerClass, opts?: {
+    hasLeftAxis?: boolean | undefined;
+    marginOverrideLeft?: number | undefined;
+}): 'outside' | 'inside' | 'none';
+/**
+ * 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 declare 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 declare function resolveMarginFloor(yPlacement: 'outside' | 'inside' | 'none', tierMargin: ChartMargin): ChartMargin;
+/**
+ * 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 declare function compactNumber(value: number): string | null;
+/** Ladder step 1's rule: compact only when the longest y label is over 4 chars. */
+export declare function shouldCompactYLabels(labels: readonly string[]): boolean;
+/** Ladder step 2 + the `VX.minPlotHeight` guard: one tick per ~44px, 2 when the plot is under the floor. */
+export declare function yTickCount(plotHeight: number): number;
+/** Greedy word wrap by measured px; a single word wider than `maxPx` keeps its own line. */
+export declare function wrapLabel(label: string, maxPx: number, fontPx: number): string[];
+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 declare function planXLabels(input: {
+    labels: readonly string[];
+    plotWidth: number;
+    fontPx: number;
+    categorical: boolean;
+}): XLabelPlan;
+/** The container class: the measured width's, or the viewport-implied one while unmeasured. */
+export declare function resolveFrameClass(input: {
+    frameW: number;
+    sizeClass: keyof typeof SIZE_CLASSES;
+}): ContainerClass;
+export declare function resolveChartLayout(input: ChartLayoutInput): ChartLayout;
+//# sourceMappingURL=chart-layout.d.ts.map

package/dist/charts/primitives/chart-layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chart-layout.d.ts","sourceRoot":"","sources":["../../../src/charts/primitives/chart-layout.ts"],"names":[],"mappings":"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"}