@opendata-ai/openchart-engine 7.2.4 → 7.4.0

package/src/__tests__/axes.test.ts

@@ -1,4 +1,4 @@
-import type { AxisTick, LayoutStrategy } from '@opendata-ai/openchart-core';
+import type { AxisTick, Encoding, LayoutStrategy } from '@opendata-ai/openchart-core';
 import { resolveTheme } from '@opendata-ai/openchart-core';
 import { scaleLinear, scaleLog } from 'd3-scale';
 import { describe, expect, it } from 'vitest';
@@ -1057,3 +1057,131 @@ describe('axis tickPosition', () => {
     expect(axes.y!.tickPosition).toBe('gutter');
   });
 });
+
+describe('axis extent and titlePosition', () => {
+  it('emits x-axis extent for a basic line chart', () => {
+    const scales = computeScales(lineSpec, chartArea, lineSpec.data);
+    const axes = computeAxes(scales, chartArea, fullStrategy, theme);
+
+    expect(axes.x!.extent).toBeGreaterThan(0);
+    expect(axes.x!.extent).toBeLessThan(200);
+  });
+
+  it('extent is larger when axis has a title', () => {
+    const specWithTitle: NormalizedChartSpec = {
+      ...lineSpec,
+      encoding: {
+        ...lineSpec.encoding,
+        x: { ...lineSpec.encoding.x, axis: { title: 'Year' } },
+      },
+    };
+    const scales = computeScales(specWithTitle, chartArea, specWithTitle.data);
+    const axesWithTitle = computeAxes(scales, chartArea, fullStrategy, theme);
+
+    const scalesNoTitle = computeScales(lineSpec, chartArea, lineSpec.data);
+    const axesNoTitle = computeAxes(scalesNoTitle, chartArea, fullStrategy, theme);
+
+    expect(axesWithTitle.x!.extent).toBeGreaterThan(axesNoTitle.x!.extent!);
+  });
+
+  it('emits titlePosition for x-axis with title', () => {
+    const specWithTitle: NormalizedChartSpec = {
+      ...lineSpec,
+      encoding: {
+        ...lineSpec.encoding,
+        x: { ...lineSpec.encoding.x, axis: { title: 'Year' } },
+      },
+    };
+    const scales = computeScales(specWithTitle, chartArea, specWithTitle.data);
+    const axes = computeAxes(scales, chartArea, fullStrategy, theme);
+
+    expect(axes.x!.titlePosition).toBeDefined();
+    expect(axes.x!.titlePosition!.x).toBeCloseTo(chartArea.x + chartArea.width / 2, 0);
+    expect(axes.x!.titlePosition!.y).toBeGreaterThan(chartArea.y + chartArea.height);
+  });
+
+  it('emits titlePosition for y-axis with title', () => {
+    const specWithYTitle: NormalizedChartSpec = {
+      ...lineSpec,
+      encoding: {
+        ...lineSpec.encoding,
+        y: { ...lineSpec.encoding.y, axis: { title: 'Value' } },
+      },
+    };
+    const scales = computeScales(specWithYTitle, chartArea, specWithYTitle.data);
+    const axes = computeAxes(scales, chartArea, fullStrategy, theme, undefined, {
+      data: specWithYTitle.data,
+      encoding: specWithYTitle.encoding as Encoding,
+      skipX: false,
+      skipY: false,
+      markType: 'line',
+      totalWidth: 600,
+    });
+
+    expect(axes.y!.titlePosition).toBeDefined();
+    expect(axes.y!.titlePosition!.x).toBeLessThan(chartArea.x);
+    expect(axes.y!.titlePosition!.angle).toBe(-90);
+  });
+});
+
+describe('quantitative axis minimum tick floor', () => {
+  // A tight domain like [73, 88] makes D3's `scale.ticks(2)` collapse to a
+  // single nice value ([80]). Before the floor, this rendered as a lone tick
+  // (a real iPhone blog chart showed only "80"). The floor must hold even at
+  // very narrow widths where the target count drops to 2.
+  const tightDomainSpec: NormalizedChartSpec = {
+    markType: 'bar',
+    markDef: { type: 'bar', orient: 'horizontal' },
+    data: [
+      { district: 'A', score: 79 },
+      { district: 'B', score: 73 },
+      { district: 'C', score: 88 },
+    ],
+    encoding: {
+      y: { field: 'district', type: 'nominal' },
+      x: {
+        field: 'score',
+        type: 'quantitative',
+        axis: { format: '.0f', grid: true },
+        scale: { domain: [73, 88], nice: false },
+      },
+    },
+    chrome: {},
+    annotations: [],
+    responsive: true,
+    theme: {},
+    darkMode: 'off',
+    labels: { density: 'all', format: '.0f' },
+  };
+
+  it('renders >= 2 ticks at a very narrow (320px-ish) chart width', () => {
+    // Narrow chart area forces the minimal density target count down to 2,
+    // where D3 collapses [73, 88] to the single tick "80" without the floor.
+    const narrowArea = { x: 90, y: 50, width: 90, height: 180 };
+    const scales = computeScales(tightDomainSpec, narrowArea, tightDomainSpec.data);
+    const axes = computeAxes(scales, narrowArea, minimalStrategy, theme, undefined, {
+      data: tightDomainSpec.data,
+      encoding: tightDomainSpec.encoding as Encoding,
+      markType: 'bar',
+    });
+
+    expect(axes.x).toBeDefined();
+    expect(axes.x!.ticks.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it('holds the 2-tick floor across a sweep of narrow widths', () => {
+    for (const width of [60, 90, 120, 220, 320]) {
+      const area = { x: 90, y: 50, width, height: 180 };
+      const scales = computeScales(tightDomainSpec, area, tightDomainSpec.data);
+      const axes = computeAxes(scales, area, minimalStrategy, theme, undefined, {
+        data: tightDomainSpec.data,
+        encoding: tightDomainSpec.encoding as Encoding,
+        markType: 'bar',
+      });
+      expect(
+        axes.x!.ticks.length,
+        `expected >= 2 ticks at width ${width}, got ${axes.x!.ticks.length}`,
+      ).toBeGreaterThanOrEqual(2);
+    }
+  });
+});

package/src/__tests__/compile-chart.test.ts

@@ -123,6 +123,12 @@ describe('compileChart', () => {
     expect(layout.chrome.source!.style.fontSize).toBeGreaterThan(0);
   });
 
+  it('emits bottomAnchorY below the chart area', () => {
+    const layout = compileChart(lineSpec, { width: 600, height: 400 });
+    expect(layout.chrome.bottomAnchorY).toBeDefined();
+    expect(layout.chrome.bottomAnchorY).toBeGreaterThanOrEqual(layout.area.y + layout.area.height);
+  });
+
   it('has axes with ticks and valid positions for a line chart', () => {
     const layout = compileChart(lineSpec, { width: 600, height: 400 });
 

package/src/__tests__/compile-layer.test.ts

@@ -391,6 +391,55 @@ describe('compileLayer', () => {
     expect(layout.axes.x).toBeDefined();
   });
 
+  it('positions y2 axis title on the right side of the chart', () => {
+    const spec: LayerSpec = {
+      resolve: { scale: { y: 'independent' } },
+      layer: [
+        {
+          mark: 'bar' as const,
+          data: [
+            { year: '2025', revenue: 10_000_000 },
+            { year: '2026', revenue: 15_000_000 },
+          ],
+          encoding: {
+            x: { field: 'year', type: 'ordinal' as const },
+            y: { field: 'revenue', type: 'quantitative' as const, axis: { title: 'Revenue ($)' } },
+          },
+        },
+        {
+          mark: 'line' as const,
+          data: [
+            { year: '2025', enrollment: 30_000 },
+            { year: '2026', enrollment: 40_000 },
+          ],
+          encoding: {
+            x: { field: 'year', type: 'ordinal' as const },
+            y: {
+              field: 'enrollment',
+              type: 'quantitative' as const,
+              axis: { title: 'Enrollment' },
+            },
+          },
+        },
+      ],
+    };
+
+    const layout = compileLayer(spec, compileOpts);
+    const y1Title = layout.axes.y!.titlePosition;
+    const y2Title = layout.axes.y2!.titlePosition;
+
+    expect(y1Title).toBeDefined();
+    expect(y2Title).toBeDefined();
+
+    // y1 title should be left of chart area, y2 title should be right
+    expect(y1Title!.x).toBeLessThan(layout.area.x);
+    expect(y2Title!.x).toBeGreaterThan(layout.area.x + layout.area.width);
+
+    // y2 title should rotate clockwise (90), y1 counter-clockwise (-90)
+    expect(y1Title!.angle).toBe(-90);
+    expect(y2Title!.angle).toBe(90);
+  });
+
   it('tags layer-1 marks with yScale y2', () => {
     const spec: LayerSpec = {
       resolve: { scale: { y: 'independent' } },

package/src/__tests__/dimensions.test.ts

@@ -182,7 +182,11 @@ describe('computeDimensions', () => {
       ],
       encoding: {
         x: { field: 'date', type: 'temporal' },
-        y: { field: 'value', type: 'quantitative', axis: { title: 'Revenue ($)' } },
+        y: {
+          field: 'value',
+          type: 'quantitative',
+          axis: { title: 'Revenue ($)', format: ',.0f' },
+        },
       },
     };
 
@@ -199,7 +203,8 @@ describe('computeDimensions', () => {
       lightTheme,
     );
 
-    // Larger numeric values produce wider tick labels (e.g. "1.5M" vs "0.0"),
+    // Explicit format ",.0f" on large values produces "2,000,000" tick labels
+    // that are much wider than the abbreviated "0.0" from small values,
     // so the y-axis title margin should grow to keep clearance
     expect(dimsLarge.margins.left).toBeGreaterThan(dimsSmall.margins.left);
   });
@@ -650,4 +655,67 @@ describe('bottom legend placement (defect-3 regression)', () => {
     expect(sourceAbsoluteY).toBeGreaterThan(legendBottom);
     expect(bylineAbsoluteY).toBeGreaterThan(sourceAbsoluteY);
   });
+
+  // Guards issue 2 (narrow-width space efficiency). The responsive metrics
+  // (scaled container padding, halved horizontal padding, collapsed legend/
+  // chrome gaps below the compact breakpoint) already keep the plot area's
+  // share of a phone-sized container within a couple of points of desktop.
+  // These floors lock that in: if a future change stops scaling padding down
+  // on narrow viewports, the plot share drops and the test fails.
+  describe('plot-area share stays efficient at narrow widths', () => {
+    const titledSpec: NormalizedChartSpec = {
+      ...baseSpec,
+      markType: 'bar',
+      markDef: { type: 'bar' },
+      encoding: {
+        x: { field: 'date', type: 'nominal' },
+        y: { field: 'value', type: 'quantitative' },
+      },
+      chrome: {
+        title: { text: 'A representative chart title' },
+        subtitle: { text: 'A subtitle line' },
+        source: { text: 'Source: somewhere' },
+      },
+    };
+
+    it('reserves at least 85% of container width for the plot at 375px', () => {
+      const dims = computeDimensions(
+        titledSpec,
+        { width: 375, height: 500 },
+        emptyLegend,
+        lightTheme,
+      );
+      expect(dims.chartArea.width / 375).toBeGreaterThanOrEqual(0.85);
+    });
+
+    it('reserves at least 55% of container height for the plot at 375px', () => {
+      const dims = computeDimensions(
+        titledSpec,
+        { width: 375, height: 500 },
+        emptyLegend,
+        lightTheme,
+      );
+      expect(dims.chartArea.height / 500).toBeGreaterThanOrEqual(0.55);
+    });
+
+    it('narrow plot width share is no worse than desktop', () => {
+      const narrow = computeDimensions(
+        titledSpec,
+        { width: 375, height: 500 },
+        emptyLegend,
+        lightTheme,
+      );
+      const desktop = computeDimensions(
+        titledSpec,
+        { width: 700, height: 500 },
+        emptyLegend,
+        lightTheme,
+      );
+      // Narrow viewports must not waste more horizontal space than desktop:
+      // the halved horizontal padding keeps the share on par (allow 2pt slack).
+      expect(narrow.chartArea.width / 375).toBeGreaterThanOrEqual(
+        desktop.chartArea.width / 700 - 0.02,
+      );
+    });
+  });
 });

package/src/__tests__/helpers/invariants.ts

@@ -0,0 +1,265 @@
+/**
+ * Layout invariant assertions.
+ *
+ * Extracts bounding boxes from a compiled ChartLayout and checks that
+ * layout elements don't overlap where they shouldn't.
+ */
+
+import type {
+  CategoricalLegendLayout,
+  ChartLayout,
+  LegendLayout,
+  Rect,
+} from '@opendata-ai/openchart-core';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface NamedRect extends Rect {
+  name: string;
+}
+
+// ---------------------------------------------------------------------------
+// Type guards
+// ---------------------------------------------------------------------------
+
+function isCategoricalLegend(legend: LegendLayout): legend is CategoricalLegendLayout {
+  return 'entries' in legend && (!legend.type || legend.type === 'categorical');
+}
+
+// ---------------------------------------------------------------------------
+// Box extraction
+// ---------------------------------------------------------------------------
+
+const CHROME_KEYS = [
+  'eyebrow',
+  'title',
+  'subtitle',
+  'source',
+  'byline',
+  'footer',
+  'brand',
+] as const;
+
+/**
+ * Extracts every layout element's bounding box as a NamedRect.
+ */
+export function extractBoxes(layout: ChartLayout): NamedRect[] {
+  const boxes: NamedRect[] = [];
+
+  // Chart area
+  boxes.push({ ...layout.area, name: 'chartArea' });
+
+  // Legend bounds
+  boxes.push({ ...layout.legend.bounds, name: 'legend' });
+
+  // Legend entry positions (categorical only)
+  if (isCategoricalLegend(layout.legend) && layout.legend.entryPositions) {
+    const rowHeight = layout.legend.rowHeight ?? 16;
+    for (let i = 0; i < layout.legend.entryPositions.length; i++) {
+      const pos = layout.legend.entryPositions[i];
+      boxes.push({
+        x: pos.x,
+        y: pos.y,
+        width: pos.width,
+        height: rowHeight,
+        name: `legend-entry-${i}`,
+      });
+    }
+  }
+
+  // X-axis label band
+  if (layout.axes.x?.extent && layout.axes.x.extent > 0) {
+    boxes.push({
+      x: layout.area.x,
+      y: layout.area.y + layout.area.height,
+      width: layout.area.width,
+      height: layout.axes.x.extent,
+      name: 'x-axis-labels',
+    });
+  }
+
+  // Y-axis label band
+  if (layout.axes.y?.extent && layout.axes.y.extent > 0) {
+    boxes.push({
+      x: layout.area.x - layout.axes.y.extent,
+      y: layout.area.y,
+      width: layout.axes.y.extent,
+      height: layout.area.height,
+      name: 'y-axis-labels',
+    });
+  }
+
+  // Chrome elements store y as the TOP edge of the text box (renderers convert
+  // to the alphabetic baseline via textAscent), so y is the box top directly.
+  for (const key of CHROME_KEYS) {
+    const el = layout.chrome[key];
+    if (el) {
+      const h = el.style.fontSize * el.style.lineHeight;
+      boxes.push({ x: el.x, y: el.y, width: el.maxWidth, height: h, name: key });
+    }
+  }
+
+  // Annotation bounds
+  for (let i = 0; i < layout.annotations.length; i++) {
+    const annotation = layout.annotations[i];
+    if (annotation.bounds) {
+      boxes.push({ ...annotation.bounds, name: `annotation-${i}` });
+    }
+  }
+
+  // Endpoint labels
+  if (layout.endpointLabels?.bounds) {
+    boxes.push({ ...layout.endpointLabels.bounds, name: 'endpoint-labels' });
+  }
+
+  return boxes;
+}
+
+// ---------------------------------------------------------------------------
+// Overlap check
+// ---------------------------------------------------------------------------
+
+/**
+ * Throws if two rects overlap by more than epsilon pixels.
+ */
+export function assertNoOverlap(a: NamedRect, b: NamedRect, epsilon = 0.5): void {
+  const overlaps =
+    a.x < b.x + b.width - epsilon &&
+    a.x + a.width > b.x + epsilon &&
+    a.y < b.y + b.height - epsilon &&
+    a.y + a.height > b.y + epsilon;
+
+  if (overlaps) {
+    throw new Error(
+      `Overlap detected between "${a.name}" and "${b.name}": ` +
+        `a=${JSON.stringify({ x: a.x, y: a.y, width: a.width, height: a.height })}, ` +
+        `b=${JSON.stringify({ x: b.x, y: b.y, width: b.width, height: b.height })}`,
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Containment helper
+// ---------------------------------------------------------------------------
+
+function isContained(inner: Rect, outer: Rect, tolerance: number): boolean {
+  return (
+    inner.x >= outer.x - tolerance &&
+    inner.y >= outer.y - tolerance &&
+    inner.x + inner.width <= outer.x + outer.width + tolerance &&
+    inner.y + inner.height <= outer.y + outer.height + tolerance
+  );
+}
+
+function rectsOverlap(a: Rect, b: Rect, epsilon: number): boolean {
+  return (
+    a.x < b.x + b.width - epsilon &&
+    a.x + a.width > b.x + epsilon &&
+    a.y < b.y + b.height - epsilon &&
+    a.y + a.height > b.y + epsilon
+  );
+}
+
+function formatRect(r: Rect): string {
+  return JSON.stringify({ x: r.x, y: r.y, width: r.width, height: r.height });
+}
+
+// ---------------------------------------------------------------------------
+// Full invariant check
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns a list of violation strings. Empty when clean.
+ */
+export function checkLayoutInvariants(
+  layout: ChartLayout,
+  opts: { svgWidth: number; svgHeight: number },
+): string[] {
+  const violations: string[] = [];
+
+  // 1. Legend doesn't intrude into chartArea (top/bottom only; right/bottom-right
+  //    use area.width reduction, so overlap is a horizontal concern checked by rule 4)
+  if (isCategoricalLegend(layout.legend)) {
+    const pos = layout.legend.position;
+    if (pos === 'top' || pos === 'bottom') {
+      if (rectsOverlap(layout.legend.bounds, layout.area, 0.5)) {
+        violations.push(
+          `legend intrudes into chartArea: legend=${formatRect(layout.legend.bounds)} chartArea=${formatRect(layout.area)}`,
+        );
+      }
+    }
+  }
+
+  // 2. Every legend entryPosition box lies inside legend bounds
+  if (isCategoricalLegend(layout.legend) && layout.legend.entryPositions) {
+    const rowHeight = layout.legend.rowHeight ?? 16;
+    // Entry width includes trailing entryGap; the last entry in a row doesn't
+    // need that gap to fit inside bounds, so allow entryGap as extra tolerance.
+    const gapTolerance = layout.legend.entryGap + 1;
+    for (let i = 0; i < layout.legend.entryPositions.length; i++) {
+      const pos = layout.legend.entryPositions[i];
+      const entryBox: Rect = {
+        x: pos.x,
+        y: pos.y,
+        width: pos.width,
+        height: rowHeight,
+      };
+      if (!isContained(entryBox, layout.legend.bounds, gapTolerance)) {
+        violations.push(
+          `legend entry ${i} outside legend bounds: entry=${formatRect(entryBox)} bounds=${formatRect(layout.legend.bounds)}`,
+        );
+      }
+    }
+  }
+
+  // 3. X-axis label band doesn't intersect bottom chrome
+  const xExtent = layout.axes.x?.extent;
+  if (xExtent && xExtent > 0) {
+    const xAxisBand: Rect = {
+      x: layout.area.x,
+      y: layout.area.y + layout.area.height,
+      width: layout.area.width,
+      height: xExtent,
+    };
+    const bottomChromeKeys = ['source', 'byline', 'footer'] as const;
+    for (const key of bottomChromeKeys) {
+      const el = layout.chrome[key];
+      if (el) {
+        const h = el.style.fontSize * el.style.lineHeight;
+        const chromeBox: Rect = { x: el.x, y: el.y, width: el.maxWidth, height: h };
+        if (rectsOverlap(xAxisBand, chromeBox, 0.5)) {
+          violations.push(
+            `x-axis labels intersect ${key}: xAxis=${formatRect(xAxisBand)} ${key}=${formatRect(chromeBox)}`,
+          );
+        }
+      }
+    }
+  }
+
+  // 4. All boxes stay within SVG viewport
+  const viewport: Rect = {
+    x: 0,
+    y: 0,
+    width: opts.svgWidth,
+    height: opts.svgHeight,
+  };
+  const allBoxes = extractBoxes(layout);
+  for (const box of allBoxes) {
+    if (!isContained(box, viewport, 2)) {
+      violations.push(
+        `${box.name} outside SVG viewport: box=${formatRect(box)} viewport=${formatRect(viewport)}`,
+      );
+    }
+  }
+
+  // 5. Reserved margins cover drawn content
+  if (layout.area.y < layout.chrome.topHeight - 1) {
+    violations.push(
+      `top chrome overflows into chart area: area.y=${layout.area.y} chrome.topHeight=${layout.chrome.topHeight}`,
+    );
+  }
+
+  return violations;
+}

package/src/__tests__/known-bugs.test.ts

@@ -0,0 +1,113 @@
+import type { ChartLayout, LineMark } from '@opendata-ai/openchart-core';
+import { estimateTextWidth } from '@opendata-ai/openchart-core';
+import { describe, expect, test } from 'vitest';
+import { compileChart } from '../compile';
+
+describe('known layout bugs', () => {
+  test('annotation label does not overlap the line it annotates', () => {
+    // Generate ~25 smooth sine-wave data points over two years
+    const data: { date: string; value: number }[] = [];
+    const startDate = new Date('2022-01-01');
+    for (let i = 0; i < 25; i++) {
+      const d = new Date(startDate);
+      d.setDate(d.getDate() + i * 30); // ~monthly
+      // Sine wave: value ranges ~20-80 with a peak near i=6 (mid-2022)
+      const value = 50 + 30 * Math.sin((i / 25) * 2 * Math.PI);
+      data.push({ date: d.toISOString().slice(0, 10), value });
+    }
+
+    // The peak is near i=6 (~July 2022), where sin peaks
+    const peakIndex = 6;
+    const peakDate = data[peakIndex].date;
+    const peakValue = data[peakIndex].value;
+
+    const spec = {
+      mark: 'line' as const,
+      data,
+      encoding: {
+        x: { field: 'date' as const, type: 'temporal' as const },
+        y: { field: 'value' as const, type: 'quantitative' as const },
+      },
+      annotations: [
+        {
+          type: 'text' as const,
+          x: peakDate,
+          y: peakValue,
+          text: 'Peak season',
+        },
+      ],
+    };
+
+    const layout: ChartLayout = compileChart(spec, { width: 600, height: 400 });
+
+    // Find the annotation
+    const annotation = layout.annotations[0];
+    expect(annotation).toBeDefined();
+    expect(annotation.label).toBeDefined();
+
+    const label = annotation.label!;
+    const fontSize = label.style.fontSize;
+    const fontWeight = label.style.fontWeight;
+
+    // Estimate the label bounding box
+    const labelWidth = estimateTextWidth(label.text, fontSize, fontWeight);
+    const labelHeight = fontSize * 1.3;
+
+    // Label bounding box (y is the baseline, so top of text is y - fontSize)
+    const labelLeft =
+      label.style.textAnchor === 'middle'
+        ? label.x - labelWidth / 2
+        : label.style.textAnchor === 'end'
+          ? label.x - labelWidth
+          : label.x;
+    const labelRight = labelLeft + labelWidth;
+    const labelTop = label.y - fontSize;
+    const labelBottom = labelTop + labelHeight;
+
+    // Find the LineMark
+    const lineMark = layout.marks.find((m): m is LineMark => m.type === 'line');
+    expect(lineMark).toBeDefined();
+
+    const points = lineMark!.points;
+
+    // Find line segments that fall within the label's x-range
+    let lineMinY = Infinity;
+    let lineMaxY = -Infinity;
+
+    for (let i = 0; i < points.length - 1; i++) {
+      const p1 = points[i];
+      const p2 = points[i + 1];
+
+      // Check if this segment overlaps the label's x-range
+      const segLeft = Math.min(p1.x, p2.x);
+      const segRight = Math.max(p1.x, p2.x);
+
+      if (segRight >= labelLeft && segLeft <= labelRight) {
+        // This segment is within the label's x-range
+        // Find the y-range of the line within the label's x-span
+        const overlapLeft = Math.max(segLeft, labelLeft);
+        const overlapRight = Math.min(segRight, labelRight);
+
+        // Interpolate y values at the overlap boundaries
+        const segWidth = p2.x - p1.x;
+        if (Math.abs(segWidth) < 0.001) {
+          lineMinY = Math.min(lineMinY, p1.y, p2.y);
+          lineMaxY = Math.max(lineMaxY, p1.y, p2.y);
+        } else {
+          const t1 = (overlapLeft - p1.x) / segWidth;
+          const t2 = (overlapRight - p1.x) / segWidth;
+          const y1 = p1.y + t1 * (p2.y - p1.y);
+          const y2 = p1.y + t2 * (p2.y - p1.y);
+          lineMinY = Math.min(lineMinY, y1, y2);
+          lineMaxY = Math.max(lineMaxY, y1, y2);
+        }
+      }
+    }
+
+    // The label bounding box should NOT vertically overlap with the line's y-range.
+    // Today the label sits only ANCHOR_OFFSET (8px) from its anchor point ON the line,
+    // so the label box almost certainly overlaps the line path.
+    const verticallyOverlaps = labelTop < lineMaxY && labelBottom > lineMinY;
+    expect(verticallyOverlaps).toBe(false);
+  });
+});