@opendata-ai/openchart-engine 7.9.2 → 7.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-engine",
-  "version": "7.9.2",
+  "version": "7.10.0",
   "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.10.0",
     "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);
   });
 });
 
@@ -1294,3 +1365,168 @@ describe('quantitative axis minimum tick floor', () => {
     }
   });
 });
+
+// ---------------------------------------------------------------------------
+// Compact temporal tick formats: pinned pre-change behavior
+// ---------------------------------------------------------------------------
+// These two tests pin the exact tick labels produced BEFORE the compact
+// temporal format rung lands in fitContinuousTicks. They must stay green
+// through that change:
+// - wide desktop axes have room for full-format labels, so compact never fires
+// - temporal y ticks are never compact (planner/renderer gutter agreement;
+//   see plans/compact-temporal-ticks.md)
+
+describe('compact temporal ticks: pinned pre-change output', () => {
+  const monthlyData = Array.from({ length: 12 }, (_, i) => ({
+    date: `2025-${String(i + 1).padStart(2, '0')}-01`,
+    value: 100 + i * 10,
+  }));
+
+  const monthlySpec: NormalizedChartSpec = {
+    ...lineSpec,
+    data: monthlyData,
+  };
+
+  it('desktop unchanged: monthly temporal x at ~900px keeps full-format labels', () => {
+    const wideArea = { x: 50, y: 50, width: 900, height: 300 };
+    const scales = computeScales(monthlySpec, wideArea, monthlySpec.data);
+    const axes = computeAxes(scales, wideArea, fullStrategy, theme);
+
+    expect(axes.x!.ticks.map((t) => t.label)).toEqual(['2025', 'Apr 2025', 'Jul 2025', 'Oct 2025']);
+  });
+
+  it('temporal y-axis unaffected: labels at ~360px stay full-format', () => {
+    const ySpec: NormalizedChartSpec = {
+      ...monthlySpec,
+      markType: 'point',
+      markDef: { type: 'point' },
+      encoding: {
+        x: { field: 'value', type: 'quantitative' },
+        y: { field: 'date', type: 'temporal' },
+      },
+    };
+    const narrowArea = { x: 40, y: 40, width: 360, height: 300 };
+    const scales = computeScales(ySpec, narrowArea, ySpec.data);
+    const axes = computeAxes(scales, narrowArea, fullStrategy, theme);
+
+    expect(axes.y!.ticks.map((t) => t.label)).toEqual(['2025', 'Apr 2025', 'Jul 2025', 'Oct 2025']);
+  });
+
+  it('temporal y-axis stays full-format even at starved heights (fallback path)', () => {
+    // Regression guard for the fallback path: compact is x-axis-only (the
+    // planner/renderer y pair must format identically), so even a height so
+    // short that fitContinuousTicks falls through to thinning must keep the
+    // year on every label — never a bare compact month like 'Oct'.
+    const ySpec: NormalizedChartSpec = {
+      ...monthlySpec,
+      markType: 'point',
+      markDef: { type: 'point' },
+      encoding: {
+        x: { field: 'value', type: 'quantitative' },
+        y: { field: 'date', type: 'temporal' },
+      },
+    };
+    const starvedArea = { x: 40, y: 40, width: 360, height: 55 };
+    const scales = computeScales(ySpec, starvedArea, ySpec.data);
+    const axes = computeAxes(scales, starvedArea, fullStrategy, theme);
+
+    const labels = axes.y!.ticks.map((t) => t.label);
+    expect(labels.length).toBeGreaterThanOrEqual(2);
+    for (const label of labels) {
+      expect(label).toMatch(/\d{4}/);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Compact temporal tick formats: the fitting rung
+// ---------------------------------------------------------------------------
+// When full-format labels overlap on a temporal x-axis, fitContinuousTicks
+// tries the compact format table at the SAME count before dropping ticks.
+// Pre-change counts below were measured by running these exact inputs against
+// the unmodified engine (git stash) — see plans/compact-temporal-ticks.md.
+
+describe('compact temporal ticks: fitting rung', () => {
+  const monthlySpecOver = (
+    months: number,
+    axis?: Record<string, unknown>,
+  ): NormalizedChartSpec => ({
+    ...lineSpec,
+    data: Array.from({ length: months }, (_, i) => ({
+      date: `2025-${String(i + 1).padStart(2, '0')}-01`,
+      value: 100 + i * 10,
+    })),
+    encoding: {
+      x: { field: 'date', type: 'temporal', ...(axis ? { axis } : {}) },
+      y: { field: 'value', type: 'quantitative' },
+    },
+  });
+
+  const xLabelsAt = (spec: NormalizedChartSpec, width: number): string[] => {
+    const area = { x: 40, y: 40, width, height: 300 };
+    const scales = computeScales(spec, area, spec.data);
+    const axes = computeAxes(scales, area, fullStrategy, theme);
+    return axes.x!.ticks.map((t) => t.label);
+  };
+
+  const COMPACT_MONTH = /^[A-Z][a-z]{2}$/; // 'Feb'
+  const FULL_MONTH = /^[A-Z][a-z]{2} \d{4}$/; // 'Feb 2025'
+  const YEAR_ONLY = /^\d{4}$/; // year-boundary tick, same in both tables
+
+  it('keeps more ticks than pre-change when full labels overlap (Jan-Dec 2025 at 160px)', () => {
+    const labels = xLabelsAt(monthlySpecOver(12), 160);
+
+    // Pre-change output at this width: ['2025', 'Oct 2025'] — the overlap
+    // forced a count step-down to 2. Compact keeps all 4 quarterly ticks.
+    expect(labels).toEqual(['2025', 'Apr', 'Jul', 'Oct']);
+    expect(labels.length).toBeGreaterThan(2);
+
+    // No label carries a year except year-boundary ticks.
+    for (const label of labels) {
+      if (/\d{4}/.test(label)) expect(label).toMatch(YEAR_ONLY);
+    }
+  });
+
+  it('renders bare compact months at monthly tick granularity (Jan-Apr 2025 at 160px)', () => {
+    // End the domain mid-April: a domain ending exactly on Apr 1 includes the
+    // Apr tick only when the runner's timezone is UTC (local time scales place
+    // month boundaries at local midnight, so negative offsets push Apr 1 past
+    // the domain end).
+    const base = monthlySpecOver(4);
+    const spec = { ...base, data: [...base.data, { date: '2025-04-15', value: 145 }] };
+    const labels = xLabelsAt(spec, 160);
+
+    // Pre-change output at this width: ['2025', 'Mar 2025'] (2 ticks).
+    expect(labels).toEqual(['2025', 'Feb', 'Mar', 'Apr']);
+    expect(labels).toContain('Feb');
+  });
+
+  it('refit stays internally consistent when D3 overshoots the requested count', () => {
+    // Jan-May 2025: D3 returns 5 monthly ticks for a request of 3 (> the 1.5x
+    // overshoot tolerance), forcing the refit loop. Whatever count/format the
+    // loop lands on, the returned set must be ONE format family — never a mix
+    // of 'Feb' and 'Mar 2025'.
+    const spec = monthlySpecOver(5);
+    for (const width of [100, 140, 180, 240]) {
+      const labels = xLabelsAt(spec, width);
+      const monthLabels = labels.filter((l) => !YEAR_ONLY.test(l));
+      expect(monthLabels.length, `width ${width}`).toBeGreaterThan(0);
+      const allCompact = monthLabels.every((l) => COMPACT_MONTH.test(l));
+      const allFull = monthLabels.every((l) => FULL_MONTH.test(l));
+      expect(
+        allCompact || allFull,
+        `mixed format families at width ${width}: ${JSON.stringify(labels)}`,
+      ).toBe(true);
+    }
+  });
+
+  it('explicit axis.format wins over compact at narrow width', () => {
+    const labels = xLabelsAt(monthlySpecOver(12, { format: '%Y-%m' }), 160);
+
+    expect(labels.length).toBeGreaterThan(0);
+    for (const label of labels) {
+      expect(label).toMatch(/^\d{4}-\d{2}$/);
+    }
+    expect(labels).toEqual(['2025-01', '2025-10']);
+  });
+});

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;
 }