@opendata-ai/openchart-engine 7.9.2 → 7.9.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-engine",
-  "version": "7.9.2",
+  "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.2",
+    "@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,13 +521,11 @@ describe('text-aware tick density', () => {
     expect(wideAxes.x!.ticks.length).toBe(categories.length);
   });
 
-  it('keeps a short neighbor that a wide final label only barely reaches', () => {
-    // Regression (mobile): with a short label whose footprint clears the wide
-    // final label by a couple pixels — less than the comfort minGap but with no
-    // real overlap — the last-label protection must NOT drop it. At the phone
-    // width where "2026 (to wk 17)" sits ~2px from "2025", dropping "2025" to
-    // seat the wide endpoint reads as arbitrary. The protection pass keys on
-    // true pixel overlap, not the comfort gap, so "2025" survives.
+  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,
@@ -557,11 +551,38 @@ describe('text-aware tick density', () => {
     expect(kept.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 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,
@@ -579,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);
+    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);
-    // 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.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', () => {
@@ -978,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' },
@@ -991,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__/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);

package/src/layout/axes.ts

@@ -27,7 +27,7 @@ import {
   X_AXIS_TITLE_BAND_ROTATED,
 } from '@opendata-ai/openchart-core';
 import type { ScaleBand } from 'd3-scale';
-import { resolveBandTickAngle } from './axes/rotation';
+import { bandLabelStride, resolveBandTickAngle } from './axes/rotation';
 import { measureLabel, thinTicksUntilFit, ticksOverlap } from './axes/thinning';
 import {
   buildContinuousTicks,
@@ -295,96 +295,15 @@ function fitContinuousTicks(
 }
 
 /**
- * Horizontal footprint `[left, right]` of a rotated band tick label, in axis
- * pixels. Rotated labels are anchored at the tick position (the rotation
- * pivot), not centered on it: at a negative angle the renderer right-anchors
- * the text so it extends left of the pivot; at a positive angle it left-anchors
- * so it extends right. The horizontal projection is `width * cos(angle)`.
- *
- * Modeling the footprint as centered (the old behavior) over-estimates each
- * label's reach by half its width in the wrong direction, which made a single
- * wide label (e.g. "2026 (to wk 17)") report overlaps against neighbors that
- * actually clear it — triggering needless thinning of the whole axis.
+ * Apply the uniform band-label stride (see bandLabelStride in ./axes/rotation):
+ * keep every Nth label counting back from the LAST one, so the most recent
+ * category is always labeled. Stride 1 — the overwhelmingly common case once
+ * the angle ladder has run — keeps everything.
  */
-function labelSpanAtAngle(
-  tick: AxisTick,
-  angleDeg: number,
-  fontSize: number,
-  fontWeight: number,
-  measureText?: MeasureTextFn,
-): { left: number; right: number } {
-  const angleRad = (Math.abs(angleDeg) * Math.PI) / 180;
-  const cosA = angleRad > 0 ? Math.abs(Math.cos(angleRad)) : 1;
-  const projected = measureLabel(tick.label, fontSize, fontWeight, measureText) * cosA;
-  if (angleDeg === 0) {
-    // Horizontal labels are centered on the tick.
-    return { left: tick.position - projected / 2, right: tick.position + projected / 2 };
-  }
-  if (angleDeg < 0) {
-    // Right-anchored: pivot is the right edge, text extends left.
-    return { left: tick.position - projected, right: tick.position };
-  }
-  // Left-anchored: pivot is the left edge, text extends right.
-  return { left: tick.position, right: tick.position + projected };
-}
-
-/**
- * Thin band-scale tick labels only where they actually collide at their
- * effective angle, greedily keeping every label that clears the last one
- * retained. This preserves narrow labels that have room even when a single
- * wide label elsewhere on the axis forces some thinning near it, instead of
- * decimating the whole axis every-other. First and last labels are always
- * kept. Most grouped bar charts keep every label even at -45°.
- */
-function thinBandTicksIfNeeded(
-  ticks: AxisTick[],
-  angleDeg: number,
-  fontSize: number,
-  fontWeight: number,
-  measureText?: MeasureTextFn,
-): AxisTick[] {
-  if (ticks.length < 3) return ticks;
-  const minGap = fontSize * 0.5;
-
-  const spans = ticks.map((t) => labelSpanAtAngle(t, angleDeg, fontSize, fontWeight, measureText));
-
-  // Greedy left-to-right retention: keep a label only if its footprint clears
-  // the last kept label's right edge by minGap. Always keep the first label.
-  const keep = new Array<boolean>(ticks.length).fill(false);
-  keep[0] = true;
-  let lastRight = spans[0].right;
-  for (let i = 1; i < ticks.length; i++) {
-    if (spans[i].left >= lastRight + minGap) {
-      keep[i] = true;
-      lastRight = spans[i].right;
-    }
-  }
-
-  // Always keep the last label. If keeping it collides with previously kept
-  // labels, drop each colliding neighbor so the endpoint stays labeled. A very
-  // wide final label (long category name) projects across several bands at an
-  // angle, so clear every kept label its footprint overlaps, not just the
-  // nearest one — otherwise an earlier kept label still overlaps the endpoint.
-  //
-  // Use true pixel overlap here (no minGap comfort buffer) so a neighbor that
-  // merely falls a few pixels short of the comfort gap — but does not actually
-  // touch the endpoint label — is kept rather than sacrificed. Dropping a
-  // readable short label to seat a near-miss wide endpoint reads as arbitrary
-  // (e.g. losing "2025" beside "2026 (to wk 17)" that clears it by 2px).
+function applyBandLabelStride(ticks: AxisTick[], stride: number): AxisTick[] {
+  if (stride <= 1 || ticks.length < 3) return ticks;
   const lastIdx = ticks.length - 1;
-  if (!keep[lastIdx]) {
-    keep[lastIdx] = true;
-    for (let i = lastIdx - 1; i > 0; i--) {
-      if (!keep[i]) continue;
-      if (spans[i].right > spans[lastIdx].left) {
-        keep[i] = false;
-        continue;
-      }
-      break;
-    }
-  }
-
-  return ticks.filter((_, i) => keep[i]);
+  return ticks.filter((_, i) => (lastIdx - i) % stride === 0);
 }
 
 // ---------------------------------------------------------------------------
@@ -511,17 +430,40 @@ export function computeAxes(
       major: true,
     }));
 
-    // Determine rotation before thinning so we know the effective label
-    // footprint. Band scales auto-rotate when horizontal labels don't fit.
+    // Band-label policy: choose the shallowest angle at which every label
+    // fits (flat → -45° → -90°), then apply the uniform stride safety net —
+    // stride 1 (keep everything) except at extreme category counts. See
+    // ./axes/rotation for the geometry.
     let tickAngle = axisConfig?.labelAngle;
-    if (tickAngle === undefined && scales.x.type === 'band' && allTicks.length > 1) {
-      const bandwidth = (scales.x.scale as ScaleBand<string>).bandwidth();
+    let bandStride = 1;
+    if (scales.x.type === 'band' && allTicks.length > 1) {
+      const bandScale = scales.x.scale as ScaleBand<string>;
+      const bandwidth = bandScale.bandwidth();
+      // Anchor spacing between the ticks actually drawn — not the raw band
+      // step. categoricalTicks may have applied an explicit tickCount cap, so
+      // retained ticks can sit a multiple of the step apart, and explicit
+      // axis.values subsets can be non-uniform: collision geometry cares
+      // about the closest adjacent pair.
+      let anchorSpacing = Number.POSITIVE_INFINITY;
+      for (let i = 1; i < allTicks.length; i++) {
+        const d = Math.abs(allTicks[i].position - allTicks[i - 1].position);
+        if (d > 0 && d < anchorSpacing) anchorSpacing = d;
+      }
+      if (!Number.isFinite(anchorSpacing)) anchorSpacing = bandScale.step();
       let maxLabelWidth = 0;
       for (const t of allTicks) {
         const w = measureLabel(t.label, fontSize, fontWeight, measureText);
         if (w > maxLabelWidth) maxLabelWidth = w;
       }
-      tickAngle = resolveBandTickAngle(undefined, maxLabelWidth, bandwidth, allTicks.length);
+      tickAngle = resolveBandTickAngle(
+        axisConfig?.labelAngle,
+        maxLabelWidth,
+        bandwidth,
+        allTicks.length,
+        anchorSpacing,
+        fontSize,
+      );
+      bandStride = bandLabelStride(maxLabelWidth, tickAngle, fontSize, anchorSpacing);
     }
 
     // Thin tick labels to prevent overlap (skip for explicit tick values).
@@ -530,10 +472,7 @@ export function computeAxes(
     if (hasExplicitValues) {
       ticks = allTicks;
     } else if (scales.x.type === 'band') {
-      // Band scales: thin only when labels actually overlap at their
-      // effective angle. After rotation, most charts have room for every label.
-      const effectiveAngle = tickAngle ?? 0;
-      ticks = thinBandTicksIfNeeded(allTicks, effectiveAngle, fontSize, fontWeight, measureText);
+      ticks = applyBandLabelStride(allTicks, bandStride);
     } else if (isContinuousX) {
       ticks = fitContinuousTicks(
         scales.x,