@opendata-ai/openchart-engine 7.9.1 → 7.9.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-engine",
-  "version": "7.9.1",
+  "version": "7.9.3",
   "description": "Headless compiler for openchart: spec validation, data compilation, scales, and layout",
   "license": "Apache-2.0",
   "author": "Riley Hilliard",
@@ -48,7 +48,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@opendata-ai/openchart-core": "7.9.1",
+    "@opendata-ai/openchart-core": "7.9.3",
     "d3-array": "^3.2.0",
     "d3-format": "^3.1.2",
     "d3-interpolate": "^3.0.0",

package/src/__tests__/axes.test.ts

@@ -482,12 +482,11 @@ describe('text-aware tick density', () => {
     expect(axes.x!.ticks.length).toBe(categories.length);
   });
 
-  it('keeps narrow band labels when one label is much wider (no global decimation)', () => {
+  it('keeps all band labels when one label is much wider (no decimation)', () => {
     // Regression: 5 rotated year labels where "2026 (to wk 17)" is much wider
-    // than the others. The old every-other thinning dropped BOTH "2023" and
-    // "2025" even though the narrow labels had ample room — a single wide label
-    // forced global decimation. Greedy per-label retention keeps the narrow
-    // ones; only the neighbor immediately crowded by the wide final label drops.
+    // than the others. Label width cannot cause rotated-label collisions
+    // (parallel ribbons — see ./layout/axes/rotation), so every label is kept.
+    // The old span-based thinning dropped "2023" and "2025" here.
     const categories = ['2022', '2023', '2024', '2025', '2026 (to wk 17)'];
     const barSpec: NormalizedChartSpec = {
       ...lineSpec,
@@ -507,16 +506,13 @@ describe('text-aware tick density', () => {
       height: 12,
     });
 
-    // Narrow area (280px) forces -45° rotation. The middle narrow labels survive
-    // — old every-other thinning would have dropped 2023 too.
+    // Narrow area (280px) forces -45° rotation. Every label survives — the
+    // ~47px step separates the diagonal ribbons by far more than a line height.
     const narrowArea = { x: 50, y: 50, width: 280, height: 300 };
     const narrowScales = computeScales(barSpec, narrowArea, barSpec.data);
     const narrowAxes = computeAxes(narrowScales, narrowArea, fullStrategy, theme, measure);
-    const narrowKept = narrowAxes.x!.ticks.map((t) => t.label);
     expect(narrowAxes.x!.tickAngle).toBe(-45);
-    expect(narrowKept).toContain('2023');
-    expect(narrowKept).toContain('2024');
-    expect(narrowKept).toContain('2026 (to wk 17)');
+    expect(narrowAxes.x!.ticks.map((t) => t.label)).toEqual(categories);
 
     // Wider area (500px) has room for every label — none are thinned.
     const wideArea = { x: 50, y: 50, width: 500, height: 300 };
@@ -525,11 +521,68 @@ describe('text-aware tick density', () => {
     expect(wideAxes.x!.ticks.length).toBe(categories.length);
   });
 
-  it('drops every neighbor a very wide final label overlaps, not just the nearest', () => {
-    // A final category long enough to project across several bands at -45° must
-    // clear ALL kept labels its footprint overlaps. The last-label protection
-    // pass drops each colliding neighbor, not only the immediate one — otherwise
-    // an earlier kept label still overlaps the forced final label.
+  it('keeps a short neighbor beside a wide final label at phone width', () => {
+    // Regression (mobile): "2025" beside "2026 (to wk 17)" at ~300px. Two
+    // earlier span-model revisions dropped "2025" here (once via minGap
+    // comfort padding, once via a genuine 1-D span overlap at larger fonts)
+    // even though the rendered -45° diagonals never touch.
+    const categories = ['2022', '2023', '2024', '2025', '2026 (to wk 17)'];
+    const barSpec: NormalizedChartSpec = {
+      ...lineSpec,
+      markType: 'bar',
+      markDef: { type: 'bar', orient: 'vertical' },
+      data: categories.map((cat, i) => ({ cat, val: [122, 47, 266, 2000, 1600][i] })),
+      encoding: {
+        x: { field: 'cat', type: 'nominal' },
+        y: { field: 'val', type: 'quantitative' },
+      },
+    };
+
+    // Uses default (real) text measurement. At 300px the band centers sit ~56px
+    // apart; the year labels project to ~17px at -45° and the wide label to
+    // ~54px, leaving "2025" and "2026 (to wk 17)" ~2px apart — a near miss.
+    const area = { x: 60, y: 50, width: 300, height: 300 };
+    const scales = computeScales(barSpec, area, barSpec.data);
+    const axes = computeAxes(scales, area, fullStrategy, theme);
+    expect(axes.x!.tickAngle).toBe(-45);
+    const kept = axes.x!.ticks.map((t) => t.label);
+    expect(kept).toContain('2025');
+    expect(kept).toContain('2026 (to wk 17)');
+    expect(kept.length).toBe(categories.length);
+  });
+
+  it('keeps all labels with a larger themed tick font at phone width (deployed blog regression)', () => {
+    // Regression: the deployed blog theme sets axisTick: 14 (default 11). At
+    // ~61px steps the larger font made the 1-D span overlap genuine, so 7.9.2
+    // still dropped "2025" in production while the default theme passed every
+    // test. Ribbon separation at -45° is 61·sin45 ≈ 43px vs the ~21px one line
+    // at 14px needs — the labels never touch, so all five must survive.
+    const categories = ['2022', '2023', '2024', '2025', '2026 (to wk 17)'];
+    const barSpec: NormalizedChartSpec = {
+      ...lineSpec,
+      markType: 'bar',
+      markDef: { type: 'bar', orient: 'vertical' },
+      data: categories.map((cat, i) => ({ cat, val: [122, 47, 266, 2026, 1602][i] })),
+      encoding: {
+        x: { field: 'cat', type: 'nominal' },
+        y: { field: 'val', type: 'quantitative' },
+      },
+    };
+    const blogTheme = resolveTheme({ fonts: { sizes: { axisTick: 14 } } });
+
+    const area = { x: 60, y: 50, width: 330, height: 300 };
+    const scales = computeScales(barSpec, area, barSpec.data);
+    const axes = computeAxes(scales, area, fullStrategy, blogTheme);
+    expect(axes.x!.tickAngle).toBe(-45);
+    expect(axes.x!.ticks.map((t) => t.label)).toEqual(categories);
+  });
+
+  it('keeps every label when one is very long — rotated labels are parallel ribbons', () => {
+    // A very long final category does NOT force neighbors to drop. Rotated
+    // labels all lean at the same angle from their own anchors, so adjacent
+    // labels are parallel ribbons separated by step·sin(angle) — label LENGTH
+    // is irrelevant to collision. The old 1-D horizontal-span model reported
+    // phantom overlaps here and dropped "B", "C", and "D".
     const categories = ['A', 'B', 'C', 'D', 'This Is A Very Long Final Category Name'];
     const barSpec: NormalizedChartSpec = {
       ...lineSpec,
@@ -547,15 +600,63 @@ describe('text-aware tick density', () => {
     const axes = computeAxes(scales, narrowArea, fullStrategy, theme, measure);
     expect(axes.x!.tickAngle).toBe(-45);
 
+    // Every category keeps its label — the diagonals never touch.
     const kept = axes.x!.ticks.map((t) => t.label);
-    // The forced final label is always retained.
-    expect(kept).toContain('This Is A Very Long Final Category Name');
-    // Every middle label the wide final label's footprint overlaps is dropped —
-    // not just the nearest one. Before the fix, "B" and "C" would survive and
-    // overlap the final label; only "D" (the immediate neighbor) was dropped.
-    expect(kept).not.toContain('B');
-    expect(kept).not.toContain('C');
-    expect(kept).not.toContain('D');
+    expect(kept).toEqual(categories);
+  });
+
+  it('measures collision at the drawn tick spacing when an explicit tickCount thins upstream', () => {
+    // 40 categories with tickCount: 8 — categoricalTicks retains every 5th
+    // category, so the drawn ticks sit 5 band steps apart. The angle and
+    // stride must use that real spacing: at ~45px apart the 8 labels fit at
+    // -45° with no thinning. Keying on the raw ~9px band step would wrongly
+    // escalate to -90° and stride away half the requested labels.
+    const categories = Array.from({ length: 40 }, (_, i) => `Cat ${i + 1}`);
+    const barSpec: NormalizedChartSpec = {
+      ...lineSpec,
+      markType: 'bar',
+      markDef: { type: 'bar', orient: 'vertical' },
+      data: categories.map((cat, i) => ({ cat, val: (i + 1) * 10 })),
+      encoding: {
+        x: { field: 'cat', type: 'nominal', axis: { tickCount: 8 } },
+        y: { field: 'val', type: 'quantitative' },
+      },
+    };
+    const measure = (text: string) => ({ width: text.length * 6, height: 12 });
+    const area = { x: 50, y: 50, width: 360, height: 300 };
+    const scales = computeScales(barSpec, area, barSpec.data);
+    const axes = computeAxes(scales, area, fullStrategy, theme, measure);
+
+    expect(axes.x!.tickAngle).toBe(-45);
+    expect(axes.x!.ticks.length).toBe(8);
+  });
+
+  it('applies the last-anchored stride when even vertical labels cannot fit', () => {
+    // 40 short categories on a 360px chart: ~9px steps fit nothing at any
+    // angle (a vertical label ribbon needs ~17px), so the safety net keeps
+    // every 2nd label counting back from the LAST category.
+    const categories = Array.from({ length: 40 }, (_, i) => `C${i + 1}`);
+    const barSpec: NormalizedChartSpec = {
+      ...lineSpec,
+      markType: 'bar',
+      markDef: { type: 'bar', orient: 'vertical' },
+      data: categories.map((cat, i) => ({ cat, val: (i + 1) * 10 })),
+      encoding: {
+        x: { field: 'cat', type: 'nominal' },
+        y: { field: 'val', type: 'quantitative' },
+      },
+    };
+    const measure = (text: string) => ({ width: text.length * 6, height: 12 });
+    const area = { x: 50, y: 50, width: 360, height: 300 };
+    const scales = computeScales(barSpec, area, barSpec.data);
+    const axes = computeAxes(scales, area, fullStrategy, theme, measure);
+
+    expect(axes.x!.tickAngle).toBe(-90);
+    const kept = axes.x!.ticks.map((t) => t.label);
+    expect(kept.length).toBe(20);
+    // The stride anchors at the final category — the most recent one is
+    // always labeled.
+    expect(kept[kept.length - 1]).toBe('C40');
   });
 
   it('y-axis gridlines match ticks so every gridline has a label', () => {
@@ -946,7 +1047,7 @@ describe('horizontal bar y-axis label thinning regression', () => {
     expect(axes.y!.ticks.length).toBe(countries.length);
   });
 
-  it('still thins x-axis band scale labels at minimal density (column chart)', () => {
+  it('rotates to vertical instead of thinning when diagonals would touch (column chart)', () => {
     const vBarSpec: NormalizedChartSpec = {
       ...hBarSpec,
       markDef: { type: 'bar', orient: 'vertical' },
@@ -959,9 +1060,11 @@ describe('horizontal bar y-axis label thinning regression', () => {
     const scales = computeScales(vBarSpec, narrowArea, vBarSpec.data);
     const axes = computeAxes(scales, narrowArea, minimalStrategy, theme);
 
-    // X-axis band scale with 10 categories at minimal density on a narrow chart
-    // should thin -- showing all 10 on 200px would overlap
-    expect(axes.x!.ticks.length).toBeLessThan(countries.length);
+    // 10 categories at ~19px steps: -45° ribbons would touch (19·sin45 ≈ 14px
+    // < one line height), so the ladder escalates to vertical, where the 19px
+    // step separation fits — every bar keeps its label.
+    expect(axes.x!.tickAngle).toBe(-90);
+    expect(axes.x!.ticks.length).toBe(countries.length);
   });
 });
 

package/src/__tests__/dimensions.test.ts

@@ -829,4 +829,45 @@ describe('bottom legend placement (defect-3 regression)', () => {
       );
     });
   });
+
+  it('keeps the inline y-axis title inside the container on narrow, large-font charts', () => {
+    // Regression (mobile): the inline y-tick fix reserved a narrow left margin,
+    // but computeAxes still positioned the rotated y-title with the GUTTER
+    // offset (tick-label width + viewport floor). On a phone at deck-scale
+    // fonts that pushed the title's rotation center to x ≈ -1, clipping the
+    // whole title off the left edge. The title offset now honors the inline
+    // flag, so titlePosition.x stays a comfortable distance inside x = 0.
+    const spec = {
+      mark: { type: 'line' as const, point: true },
+      data: [
+        { year: '2009-10', pct: 94.2 },
+        { year: '2015-16', pct: 93.8 },
+        { year: '2020-21', pct: 95.0 },
+      ],
+      encoding: {
+        x: { field: 'year', type: 'ordinal' as const },
+        y: {
+          field: 'pct',
+          type: 'quantitative' as const,
+          axis: { title: 'Kindergartners with 2-dose MMR', grid: true, format: '.0f' },
+          scale: { domain: [90, 96], nice: false },
+        },
+      },
+      theme: { fonts: { sizes: { body: 21, axisTick: 18 } } },
+      chrome: { title: 'T', subtitle: 'S', source: 'Src' },
+    };
+
+    for (const width of [320, 360, 390]) {
+      const layout = compileChart(spec, { width, height: 600 });
+      const yAxis = layout.axes.y;
+      expect(yAxis?.tickPosition).toBe('inline');
+      const title = yAxis?.titlePosition;
+      expect(title).toBeDefined();
+      // The title is rotated -90° anchored middle; its glyph box straddles the
+      // rotation center by ~half the title font. The left edge must stay on the
+      // canvas (x >= 0). Assert the rotation center clears half a glyph.
+      const halfGlyph = Math.ceil(layout.theme.fonts.sizes.body / 2);
+      expect(title!.x - halfGlyph).toBeGreaterThanOrEqual(0);
+    }
+  });
 });

package/src/__tests__/rotation.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from 'vitest';
+import { bandLabelStride, resolveBandTickAngle } from '../layout/axes/rotation';
+
+// Geometry cheat sheet at the default 11px tick font:
+// - ribbon thickness = 11 * 1.2 + 4 = 17.2px (perpendicular room one label needs)
+// - at -45°, ribbon separation = spacing * 0.707, so the -45 → -90 flip sits
+//   near spacing ≈ 24.3px
+// - at -90°, separation = spacing, so the stride safety net starts below
+//   spacing ≈ 17.2px
+
+describe('resolveBandTickAngle', () => {
+  it('returns the explicit angle untouched', () => {
+    expect(resolveBandTickAngle(-30, 100, 20, 5, 50, 11)).toBe(-30);
+    expect(resolveBandTickAngle(0, 100, 20, 5, 50, 11)).toBe(0);
+  });
+
+  it('never rotates a single label', () => {
+    expect(resolveBandTickAngle(undefined, 100, 20, 1, 50, 11)).toBeUndefined();
+  });
+
+  it('stays flat when the widest label fits its band', () => {
+    expect(resolveBandTickAngle(undefined, 17, 20, 5, 30, 11)).toBeUndefined();
+  });
+
+  it('picks -45 when diagonal ribbons clear one line height', () => {
+    // separation = 25 * sin45 ≈ 17.7 >= 17.2
+    expect(resolveBandTickAngle(undefined, 40, 20, 5, 25, 11)).toBe(-45);
+  });
+
+  it('escalates to -90 when diagonal ribbons would touch', () => {
+    // separation = 24 * sin45 ≈ 17.0 < 17.2, and 24px along-text clearance
+    // cannot fit a 40px label; vertical separation 24 >= 17.2 fits.
+    expect(resolveBandTickAngle(undefined, 40, 20, 5, 24, 11)).toBe(-90);
+  });
+
+  it('keeps -45 for short labels that clear end-to-end along the text direction', () => {
+    // Ribbons touch (24 * sin45 < 17.2) but a 10px label clears via the
+    // 17px along-text offset — finite segments slide past each other.
+    expect(resolveBandTickAngle(undefined, 10, 8, 5, 24, 11)).toBe(-45);
+  });
+
+  it('refuses -90 for labels longer than the rotated-extent cap', () => {
+    // A 150px label projected vertically exceeds the 120px reservation cap
+    // and would clip into the source line; stay at -45 and let the stride
+    // safety net thin instead.
+    expect(resolveBandTickAngle(undefined, 150, 20, 5, 20, 11)).toBe(-45);
+  });
+});
+
+describe('bandLabelStride', () => {
+  it('returns 1 for degenerate spacing', () => {
+    expect(bandLabelStride(50, -45, 11, 0)).toBe(1);
+    expect(bandLabelStride(50, -45, 11, -5)).toBe(1);
+  });
+
+  it('drives the flat stride by label width', () => {
+    // (50 + 4) / 20 → every 3rd label
+    expect(bandLabelStride(50, undefined, 11, 20)).toBe(3);
+    expect(bandLabelStride(10, undefined, 11, 20)).toBe(1);
+  });
+
+  it('keeps every label when vertical separation fits', () => {
+    expect(bandLabelStride(50, -90, 11, 20)).toBe(1);
+  });
+
+  it('thins vertical labels only at tiny steps', () => {
+    // separation 7 < 17.2 → ceil(17.2 / 7) = 3
+    expect(bandLabelStride(50, -90, 11, 7)).toBe(3);
+  });
+
+  it('does not thin a shallow explicit angle whose labels clear end-to-end', () => {
+    // labelAngle -20 at 50px spacing: ribbon separation 17.1 barely misses
+    // one line height, but the 47px along-text offset clears a 30px label.
+    // The old span model dropped every other label here.
+    expect(bandLabelStride(30, -20, 11, 50)).toBe(1);
+  });
+
+  it('thins a shallow explicit angle when labels overlap by both routes', () => {
+    // labelAngle -20 at 30px spacing with 60px labels: separation 10.3 needs
+    // stride 2, along-text clearance 28.2 needs stride 3 → ribbons win.
+    expect(bandLabelStride(60, -20, 11, 30)).toBe(2);
+  });
+});

package/src/layout/axes/rotation.ts

@@ -1,36 +1,152 @@
 /**
- * Auto-rotation decision for band-scale x-axis tick labels.
- *
- * Vertical band x-axes rotate their tick labels to -45° when horizontal
- * labels are wider than the available band. The layout planner and
- * computeAxes must agree on this decision: the planner reserves the bottom
- * margin for the rotated label footprint, and computeAxes emits the same
- * angle. Sharing this rule keeps the reserved space matched to the rendered
- * labels (a mismatch spilled rotated ticks into the source line).
+ * Auto-rotation and thinning policy for band-scale x-axis tick labels.
+ *
+ * Band categories are data: every bar should keep its label. The policy
+ * steepens the label angle until everything fits — flat, then -45°, then -90°
+ * (vertical) — and only thins (uniform every-Nth) when even the steepest
+ * usable angle cannot fit every label, which takes dozens of categories at
+ * tiny steps.
+ *
+ * The collision geometry differs by orientation, and getting it right is what
+ * makes thinning almost never necessary:
+ *
+ * - FLAT labels share a baseline, so adjacent labels collide when the widest
+ *   label's width exceeds the anchor spacing.
+ * - ROTATED labels are PARALLEL RIBBONS: every label leans at the same angle
+ *   from its own anchor, so adjacent labels are parallel segments. They clear
+ *   each other when EITHER the perpendicular separation between the ribbons
+ *   (`spacing * |sin θ|`) exceeds one line height, OR the offset along the
+ *   text direction (`spacing * |cos θ|`) exceeds the label length — finite
+ *   segments slide past each other end-to-end at shallow angles. Earlier
+ *   revisions modeled rotated labels as 1-D horizontal spans, which reported
+ *   phantom collisions for long labels (dropping "2025" beside
+ *   "2026 (to wk 17)") even though the rendered diagonals never touch.
+ *
+ * The layout planner and computeAxes must agree on these decisions: the
+ * planner reserves the bottom margin for the rotated label footprint, and
+ * computeAxes emits the same angle. Sharing this module keeps the reserved
+ * space matched to the rendered labels (a mismatch spilled rotated ticks into
+ * the source line).
  */
 
-/** Band fraction above which horizontal labels are considered too wide to fit. */
+import { TICK_LINE_HEIGHT_FACTOR, X_AXIS_ROTATED_EXTENT_CAP } from '@opendata-ai/openchart-core';
+
+/** Band fraction above which flat labels are considered too wide to fit. */
 const BAND_FIT_FRACTION = 0.85;
 
-/** Angle used when band labels don't fit horizontally. */
+/** Diagonal angle tried first when flat labels don't fit. */
 const AUTO_ROTATE_ANGLE = -45;
 
+/** Vertical angle used when diagonal ribbons would touch. */
+const STEEP_ROTATE_ANGLE = -90;
+
+/** Minimum visible gap between adjacent label ribbons, in px. */
+const LABEL_GAP = 4;
+
 /**
- * Decide the effective x tick angle for a band scale.
+ * Perpendicular separation between adjacent rotated label ribbons.
+ * Labels anchor at points `spacing` apart; leaning at `angleDeg` makes them
+ * parallel lines whose perpendicular distance is `spacing * |sin(angle)|`.
+ */
+function ribbonSeparation(spacing: number, angleDeg: number): number {
+  return spacing * Math.abs(Math.sin((angleDeg * Math.PI) / 180));
+}
+
+/**
+ * Offset between adjacent labels measured along the text direction.
+ * Finite labels clear each other end-to-end when this exceeds the label
+ * length, even if the ribbons are closer than a line height — the escape
+ * route that matters at shallow angles.
+ */
+function alongTextClearance(spacing: number, angleDeg: number): number {
+  return spacing * Math.abs(Math.cos((angleDeg * Math.PI) / 180));
+}
+
+/** Whether every label fits at the given rotation without touching. */
+function rotatedLabelsFit(
+  spacing: number,
+  angleDeg: number,
+  fontSize: number,
+  maxLabelWidth: number,
+): boolean {
+  return (
+    ribbonSeparation(spacing, angleDeg) >= fontSize * TICK_LINE_HEIGHT_FACTOR + LABEL_GAP ||
+    alongTextClearance(spacing, angleDeg) >= maxLabelWidth + LABEL_GAP
+  );
+}
+
+/**
+ * Decide the effective x tick angle for a band scale: the shallowest angle in
+ * the ladder (flat → -45° → -90°) at which adjacent labels don't touch.
+ *
+ * The flat trigger compares the widest label against the bandwidth (does the
+ * flat label fit its band?) — the long-standing rule, kept for stability.
+ * The rotated steps use the parallel-ribbon fit test above.
+ *
+ * -90° projects the full label length vertically, so labels longer than the
+ * reserved-extent cap would clip into the source line. For those the ladder
+ * stays at -45° (smaller vertical footprint) and lets the stride safety net
+ * thin the ribbons instead.
  *
  * @param explicitAngle - User-specified labelAngle (wins if defined).
  * @param maxLabelWidth - Widest tick label width in pixels.
- * @param bandwidth - Band width in pixels.
+ * @param bandwidth - Band width in pixels (excludes inner padding).
  * @param labelCount - Number of category labels (rotation needs >= 2).
- * @returns The explicit angle, `-45` if auto-rotation triggers, or `undefined`.
+ * @param spacing - Distance between the closest adjacent DRAWN tick anchors.
+ *   This is the band step when every category gets a tick, but a multiple of
+ *   it when an explicit tickCount capped the tick set upstream.
+ * @param fontSize - Tick label font size (ribbon thickness term).
+ * @returns The explicit angle, `-45`, `-90`, or `undefined` (no rotation).
  */
 export function resolveBandTickAngle(
   explicitAngle: number | undefined,
   maxLabelWidth: number,
   bandwidth: number,
   labelCount: number,
+  spacing: number,
+  fontSize: number,
 ): number | undefined {
   if (explicitAngle !== undefined) return explicitAngle;
   if (labelCount < 2) return undefined;
-  return maxLabelWidth > bandwidth * BAND_FIT_FRACTION ? AUTO_ROTATE_ANGLE : undefined;
+  if (maxLabelWidth <= bandwidth * BAND_FIT_FRACTION) return undefined;
+  if (rotatedLabelsFit(spacing, AUTO_ROTATE_ANGLE, fontSize, maxLabelWidth)) {
+    return AUTO_ROTATE_ANGLE;
+  }
+  return maxLabelWidth <= X_AXIS_ROTATED_EXTENT_CAP ? STEEP_ROTATE_ANGLE : AUTO_ROTATE_ANGLE;
+}
+
+/**
+ * Uniform every-Nth retention stride for band tick labels — the safety net
+ * for when even the resolved angle cannot fit every label (dozens of
+ * categories at tiny steps, an explicit shallow labelAngle on a crowded axis,
+ * or labels too long for the -90° escalation). Returns 1 (keep every label)
+ * whenever labels fit.
+ *
+ * Callers keep indices counting back from the LAST label
+ * (`(lastIdx - i) % stride === 0`) so the most recent category — usually the
+ * most editorially important — is always labeled.
+ *
+ * Flat labels collide along their shared baseline, so the stride is driven by
+ * the widest label's width. Rotated labels escape by either route — ribbon
+ * separation or along-text clearance — and both scale linearly with the
+ * stride, so the cheaper one wins.
+ */
+export function bandLabelStride(
+  maxLabelWidth: number,
+  angleDeg: number | undefined,
+  fontSize: number,
+  spacing: number,
+): number {
+  if (spacing <= 0) return 1;
+  if (angleDeg === undefined || angleDeg === 0) {
+    return Math.max(1, Math.ceil((maxLabelWidth + LABEL_GAP) / spacing));
+  }
+  const separation = ribbonSeparation(spacing, angleDeg);
+  const clearance = alongTextClearance(spacing, angleDeg);
+  const required = fontSize * TICK_LINE_HEIGHT_FACTOR + LABEL_GAP;
+  const byRibbon = separation > 0 ? Math.ceil(required / separation) : Number.POSITIVE_INFINITY;
+  const byLength =
+    clearance > 0 ? Math.ceil((maxLabelWidth + LABEL_GAP) / clearance) : Number.POSITIVE_INFINITY;
+  const stride = Math.min(byRibbon, byLength);
+  return Number.isFinite(stride) ? Math.max(1, stride) : 1;
 }

package/src/layout/axes/ticks.ts

@@ -256,8 +256,8 @@ export function categoricalTicks(
   if (resolvedScale.type === 'band' && orientation === 'horizontal') {
     // Horizontal band scales delegate thinning to the caller (computeAxes)
     // which knows the effective label angle after auto-rotation. Only apply
-    // an explicit tickCount cap here; density-based thinning happens
-    // downstream in thinBandTicksIfNeeded where rotation is accounted for.
+    // an explicit tickCount cap here; the angle ladder + stride safety net
+    // (see ./rotation) handle collisions downstream.
     if (explicitTickCount && domain.length > explicitTickCount) {
       const step = Math.ceil(domain.length / explicitTickCount);
       selectedValues = domain.filter((_: string, i: number) => i % step === 0);