@opendata-ai/openchart-engine 6.2.1 → 6.3.0

package/package.json

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

package/src/__tests__/legend.test.ts

@@ -111,6 +111,108 @@ describe('computeLegend', () => {
     expect(legend.entries).toHaveLength(3);
   });
 
+  it('with columns: 3 and 6 series, shows all 6 entries across 2 rows', () => {
+    const sixSeriesSpec: NormalizedChartSpec = {
+      ...specWithColor,
+      data: [
+        { date: '2020', value: 10, country: 'A' },
+        { date: '2020', value: 10, country: 'B' },
+        { date: '2020', value: 10, country: 'C' },
+        { date: '2020', value: 10, country: 'D' },
+        { date: '2020', value: 10, country: 'E' },
+        { date: '2020', value: 10, country: 'F' },
+      ],
+      legend: { columns: 3 },
+      hiddenSeries: [],
+      seriesStyles: {},
+    };
+    const legend = computeLegend(sixSeriesSpec, compactStrategy, theme, chartArea);
+    // All 6 entries visible (no overflow indicator)
+    expect(legend.entries).toHaveLength(6);
+    expect(legend.entries.every((e) => !e.overflow)).toBe(true);
+  });
+
+  it('with symbolLimit: 3 and 6 series, truncates to 3 entries + overflow', () => {
+    const sixSeriesSpec: NormalizedChartSpec = {
+      ...specWithColor,
+      data: [
+        { date: '2020', value: 10, country: 'A' },
+        { date: '2020', value: 10, country: 'B' },
+        { date: '2020', value: 10, country: 'C' },
+        { date: '2020', value: 10, country: 'D' },
+        { date: '2020', value: 10, country: 'E' },
+        { date: '2020', value: 10, country: 'F' },
+      ],
+      legend: { symbolLimit: 3 },
+      hiddenSeries: [],
+      seriesStyles: {},
+    };
+    const legend = computeLegend(sixSeriesSpec, compactStrategy, theme, chartArea);
+    // 3 real entries + 1 overflow indicator
+    expect(legend.entries).toHaveLength(4);
+    expect(legend.entries[3].label).toBe('+3 more');
+    expect(legend.entries[3].overflow).toBe(true);
+  });
+
+  it('with symbolLimit on right-positioned legend, truncates entries', () => {
+    const sixSeriesSpec: NormalizedChartSpec = {
+      ...specWithColor,
+      data: [
+        { date: '2020', value: 10, country: 'A' },
+        { date: '2020', value: 10, country: 'B' },
+        { date: '2020', value: 10, country: 'C' },
+        { date: '2020', value: 10, country: 'D' },
+        { date: '2020', value: 10, country: 'E' },
+        { date: '2020', value: 10, country: 'F' },
+      ],
+      legend: { symbolLimit: 2 },
+      hiddenSeries: [],
+      seriesStyles: {},
+    };
+    const legend = computeLegend(sixSeriesSpec, fullStrategy, theme, chartArea);
+    // 2 real entries + 1 overflow indicator
+    expect(legend.entries).toHaveLength(3);
+    expect(legend.entries[2].label).toBe('+4 more');
+    expect(legend.entries[2].overflow).toBe(true);
+  });
+
+  it('symbolLimit: 0 is clamped to 1 (minimum 1 entry)', () => {
+    const sixSeriesSpec: NormalizedChartSpec = {
+      ...specWithColor,
+      data: [
+        { date: '2020', value: 10, country: 'A' },
+        { date: '2020', value: 10, country: 'B' },
+        { date: '2020', value: 10, country: 'C' },
+      ],
+      encoding: {
+        x: { field: 'date', type: 'temporal' },
+        y: { field: 'value', type: 'quantitative' },
+        color: { field: 'country', type: 'nominal' },
+      },
+    };
+    const compactStrategy: LayoutStrategy = {
+      legend: { symbolLimit: 0 },
+      hiddenSeries: [],
+      seriesStyles: {},
+    };
+    const legend = computeLegend(sixSeriesSpec, compactStrategy, theme, chartArea);
+    // symbolLimit: 0 gets clamped to 1, so 1 real entry + overflow
+    expect(legend.entries.length).toBeGreaterThanOrEqual(1);
+    expect(legend.entries.filter((e) => !e.overflow).length).toBeGreaterThanOrEqual(1);
+  });
+
+  it('symbolLimit greater than entry count shows all entries', () => {
+    const largeLimit: LayoutStrategy = {
+      legend: { symbolLimit: 100 },
+      hiddenSeries: [],
+      seriesStyles: {},
+    };
+    const legend = computeLegend(specWithColor, largeLimit, theme, chartArea);
+    // All 3 entries shown, no overflow
+    expect(legend.entries).toHaveLength(3);
+    expect(legend.entries.every((e) => !e.overflow)).toBe(true);
+  });
+
   it('uses correct swatch shape for chart type', () => {
     const lineLegend = computeLegend(specWithColor, fullStrategy, theme, chartArea);
     expect(lineLegend.entries[0].shape).toBe('line');

package/src/annotations/__tests__/compute.test.ts

@@ -946,4 +946,111 @@ describe('computeAnnotations', () => {
       expect(moved).toBe(true);
     });
   });
+
+  // -----------------------------------------------------------------
+  // Boundary clamping (SVG edge overflow prevention)
+  // -----------------------------------------------------------------
+
+  describe('boundary clamping', () => {
+    const svgDimensions = { width: 600, height: 400 };
+
+    it('shifts annotation left when it overflows the right SVG edge', () => {
+      // Place annotation at the far right of the chart area so the label
+      // text extends past the SVG boundary.
+      const spec = makeSpec([
+        {
+          type: 'text',
+          x: '2022-01-01',
+          y: 40,
+          text: 'This is a long annotation label',
+          anchor: 'right',
+          offset: { dx: 80, dy: 0 },
+        },
+      ]);
+      const scales = computeScales(spec, chartArea, spec.data);
+      const annotations = computeAnnotations(
+        spec,
+        scales,
+        chartArea,
+        fullStrategy,
+        false,
+        [],
+        svgDimensions,
+      );
+
+      expect(annotations).toHaveLength(1);
+      const label = annotations[0].label!;
+      const fontSize = label.style.fontSize ?? 12;
+      const fontWeight = label.style.fontWeight ?? 400;
+      // Estimate bounds to verify the right edge is within SVG
+      const textWidth = label.text
+        .split('\n')
+        .reduce(
+          (max, line) => Math.max(max, line.length * fontSize * (fontWeight >= 600 ? 0.65 : 0.55)),
+          0,
+        );
+      // The label's right edge should not exceed the SVG width
+      expect(label.x + textWidth).toBeLessThanOrEqual(svgDimensions.width);
+    });
+
+    it('shifts annotation down when it overflows the top SVG edge', () => {
+      // Place annotation near the top of the chart and push it upward
+      const spec = makeSpec([
+        {
+          type: 'text',
+          x: '2020-01-01',
+          y: 40,
+          text: 'Top overflow',
+          anchor: 'top',
+          offset: { dx: 0, dy: -80 },
+        },
+      ]);
+      const scales = computeScales(spec, chartArea, spec.data);
+      const annotations = computeAnnotations(
+        spec,
+        scales,
+        chartArea,
+        fullStrategy,
+        false,
+        [],
+        svgDimensions,
+      );
+
+      expect(annotations).toHaveLength(1);
+      const label = annotations[0].label!;
+      const fontSize = label.style.fontSize ?? 12;
+      // The top of the label bounds (y - fontSize) should be >= 0
+      expect(label.y - fontSize).toBeGreaterThanOrEqual(0);
+    });
+
+    it('does not modify annotation that is well within bounds', () => {
+      // Place annotation in the center of the chart
+      const spec = makeSpec([
+        {
+          type: 'text',
+          x: '2020-06-01',
+          y: 25,
+          text: 'Centered',
+        },
+      ]);
+      const scales = computeScales(spec, chartArea, spec.data);
+
+      // Compute with and without SVG dimensions to verify no change
+      const withClamping = computeAnnotations(
+        spec,
+        scales,
+        chartArea,
+        fullStrategy,
+        false,
+        [],
+        svgDimensions,
+      );
+      const withoutClamping = computeAnnotations(spec, scales, chartArea, fullStrategy, false, []);
+
+      expect(withClamping).toHaveLength(1);
+      expect(withoutClamping).toHaveLength(1);
+      expect(withClamping[0].label!.x).toBe(withoutClamping[0].label!.x);
+      expect(withClamping[0].label!.y).toBe(withoutClamping[0].label!.y);
+    });
+  });
 });

package/src/annotations/compute.ts

@@ -667,7 +667,7 @@ function nudgeAnnotationFromObstacles(
     // need to shift into that space to avoid marks or the brand watermark.
     const inBounds =
       labelCenterX >= chartArea.x &&
-      labelCenterX <= chartArea.x + chartArea.width + 100 &&
+      labelCenterX <= chartArea.x + chartArea.width + 10 &&
       labelCenterY >= chartArea.y - fontSize &&
       labelCenterY <= chartArea.y + chartArea.height + fontSize * 3;
 
@@ -755,7 +755,7 @@ function resolveAnnotationCollisions(
             const labelCenterY = candidateBounds.y + candidateBounds.height / 2;
             const inBounds =
               labelCenterX >= chartArea.x &&
-              labelCenterX <= chartArea.x + chartArea.width + 100 &&
+              labelCenterX <= chartArea.x + chartArea.width + 10 &&
               labelCenterY >= chartArea.y - fontSize &&
               labelCenterY <= chartArea.y + chartArea.height + fontSize;
 
@@ -799,6 +799,81 @@ function resolveAnnotationCollisions(
   }
 }
 
+// ---------------------------------------------------------------------------
+// Boundary clamping
+// ---------------------------------------------------------------------------
+
+/** Small inset margin so labels don't touch the SVG edge. */
+const CLAMP_MARGIN = 4;
+
+/**
+ * Shift text annotation labels so they stay within the total SVG bounds.
+ * If a label overflows the right, left, top, or bottom edge, its position
+ * is adjusted inward by the overflow amount. Connector geometry is updated
+ * to match.
+ */
+function clampAnnotationsToBounds(
+  annotations: ResolvedAnnotation[],
+  svgWidth: number,
+  svgHeight: number,
+): void {
+  for (const annotation of annotations) {
+    if (annotation.type !== 'text' || !annotation.label) continue;
+
+    const bounds = estimateLabelBounds(annotation.label);
+    let dx = 0;
+    let dy = 0;
+
+    // Right overflow
+    if (bounds.x + bounds.width > svgWidth - CLAMP_MARGIN) {
+      dx = svgWidth - CLAMP_MARGIN - (bounds.x + bounds.width);
+    }
+    // Left overflow
+    if (bounds.x + dx < CLAMP_MARGIN) {
+      dx = CLAMP_MARGIN - bounds.x;
+    }
+    // Top overflow
+    if (bounds.y < CLAMP_MARGIN) {
+      dy = CLAMP_MARGIN - bounds.y;
+    }
+    // Bottom overflow
+    if (bounds.y + bounds.height + dy > svgHeight - CLAMP_MARGIN) {
+      dy = svgHeight - CLAMP_MARGIN - (bounds.y + bounds.height);
+    }
+
+    if (dx === 0 && dy === 0) continue;
+
+    const newX = annotation.label.x + dx;
+    const newY = annotation.label.y + dy;
+
+    // Update connector origin if present
+    let newConnector = annotation.label.connector;
+    if (newConnector) {
+      const fontSize = annotation.label.style.fontSize ?? DEFAULT_ANNOTATION_FONT_SIZE;
+      const fontWeight = annotation.label.style.fontWeight ?? DEFAULT_ANNOTATION_FONT_WEIGHT;
+      const connStyle = newConnector.style === 'curve' ? ('curve' as const) : ('straight' as const);
+      const newFrom = computeConnectorOrigin(
+        newX,
+        newY,
+        annotation.label.text,
+        fontSize,
+        fontWeight,
+        newConnector.to.x,
+        newConnector.to.y,
+        connStyle,
+      );
+      newConnector = { ...newConnector, from: newFrom };
+    }
+
+    annotation.label = {
+      ...annotation.label,
+      x: newX,
+      y: newY,
+      connector: newConnector,
+    };
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -814,6 +889,7 @@ function resolveAnnotationCollisions(
  * that overlap with them are automatically repositioned using alternate
  * anchor directions. After individual obstacle avoidance, annotation-to-
  * annotation collisions are resolved using a greedy placement algorithm.
+ * Finally, labels are clamped to stay within the total SVG bounds.
  */
 export function computeAnnotations(
   spec: NormalizedChartSpec,
@@ -822,6 +898,7 @@ export function computeAnnotations(
   strategy: LayoutStrategy,
   isDark = false,
   obstacles: Rect[] = [],
+  svgDimensions?: { width: number; height: number },
 ): ResolvedAnnotation[] {
   // At compact breakpoints, skip all annotations
   if (strategy.annotationPosition === 'tooltip-only') {
@@ -857,6 +934,11 @@ export function computeAnnotations(
   // Resolve annotation-to-annotation collisions (greedy, order-preserving)
   resolveAnnotationCollisions(annotations, spec.annotations, scales, chartArea);
 
+  // Clamp labels that overflow the SVG boundary back inside
+  if (svgDimensions) {
+    clampAnnotationsToBounds(annotations, svgDimensions.width, svgDimensions.height);
+  }
+
   // Sort by zIndex (lower first, undefined treated as 0)
   annotations.sort((a, b) => (a.zIndex ?? 0) - (b.zIndex ?? 0));
 

package/src/charts/bar/__tests__/labels.test.ts

@@ -73,3 +73,115 @@ describe('computeBarLabels density modes', () => {
     expect(withDefault.length).toBe(withAuto.length);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Stacked bar segment-fit tests (BUG-4)
+// ---------------------------------------------------------------------------
+
+function makeStackedMark(index: number, value: number, width: number): RectMark {
+  return {
+    type: 'rect',
+    x: index * 50,
+    y: 0,
+    width,
+    height: 25,
+    fill: '#4e79a7',
+    cornerRadius: 0, // cornerRadius 0 = stacked segment
+    data: { category: `Cat${index}`, value },
+    aria: { label: `Cat${index}: ${value}` },
+  };
+}
+
+describe('stacked bar label segment-fit', () => {
+  it('density "all" hides labels that do not fit in narrow stacked segments', () => {
+    const stackedMarks: RectMark[] = [
+      // Narrow segment: 30px wide, label for "8003" will be wider than 30 - 12 = 18px
+      makeStackedMark(0, 8003, 30),
+      // Wide segment: 200px wide, label should fit easily
+      makeStackedMark(1, 5000, 200),
+    ];
+    const labels = computeBarLabels(stackedMarks, chartArea, 'all');
+    expect(labels).toHaveLength(2);
+    // Narrow segment label should be hidden
+    expect(labels[0].visible).toBe(false);
+    // Wide segment label should still be visible
+    expect(labels[1].visible).toBe(true);
+  });
+
+  it('density "auto" hides labels that do not fit in narrow stacked segments', () => {
+    const stackedMarks: RectMark[] = [makeStackedMark(0, 8003, 30), makeStackedMark(1, 5000, 200)];
+    const labels = computeBarLabels(stackedMarks, chartArea, 'auto');
+    expect(labels).toHaveLength(2);
+    // Narrow segment label should be hidden
+    expect(labels[0].visible).toBe(false);
+    // Wide segment label should still be visible
+    expect(labels[1].visible).toBe(true);
+  });
+
+  it('non-stacked bars still show labels regardless of width', () => {
+    // Non-stacked marks (no cornerRadius = undefined, not 0)
+    const nonStackedMarks: RectMark[] = [
+      makeMark(0, 10), // width = 50
+      makeMark(1, 20), // width = 100
+    ];
+    const labels = computeBarLabels(nonStackedMarks, chartArea, 'all');
+    expect(labels).toHaveLength(2);
+    expect(labels.every((l) => l.visible === true)).toBe(true);
+  });
+
+  it('wide stacked segments still show labels', () => {
+    const wideStacked: RectMark[] = [makeStackedMark(0, 42, 200), makeStackedMark(1, 99, 200)];
+    const labels = computeBarLabels(wideStacked, chartArea, 'all');
+    expect(labels).toHaveLength(2);
+    expect(labels.every((l) => l.visible === true)).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Format with abbreviated aria values (BUG-3)
+// ---------------------------------------------------------------------------
+
+describe('computeBarLabels with $~s format and abbreviated aria values', () => {
+  function makeAbbreviatedMark(index: number, value: number, abbr: string): RectMark {
+    return {
+      type: 'rect',
+      x: 0,
+      y: index * 30,
+      width: 200,
+      height: 25,
+      fill: '#4e79a7',
+      data: { category: `Cat${index}`, value },
+      aria: { label: `Cat${index}: ${abbr}` },
+    };
+  }
+
+  it('$~s format preserves SI suffix for low thousands', () => {
+    const thousandMarks: RectMark[] = [
+      makeAbbreviatedMark(0, 6000, '6K'),
+      makeAbbreviatedMark(1, 7000, '7K'),
+      makeAbbreviatedMark(2, 14000, '14K'),
+    ];
+
+    const labels = computeBarLabels(thousandMarks, chartArea, 'all', '$~s');
+    expect(labels).toHaveLength(3);
+    expect(labels[0].text).toBe('$6k');
+    expect(labels[1].text).toBe('$7k');
+    expect(labels[2].text).toBe('$14k');
+  });
+
+  it('$~s format works for millions', () => {
+    const millionMarks: RectMark[] = [makeAbbreviatedMark(0, 1500000, '1.5M')];
+
+    const labels = computeBarLabels(millionMarks, chartArea, 'all', '$~s');
+    expect(labels).toHaveLength(1);
+    expect(labels[0].text).toBe('$1.5M');
+  });
+
+  it('handles comma-formatted aria values', () => {
+    const commaMarks: RectMark[] = [makeAbbreviatedMark(0, 500, '500')];
+
+    const labels = computeBarLabels(commaMarks, chartArea, 'all', '$,.0f');
+    expect(labels).toHaveLength(1);
+    expect(labels[0].text).toBe('$500');
+  });
+});

package/src/charts/bar/labels.ts

@@ -23,6 +23,40 @@ import {
   resolveCollisions,
 } from '@opendata-ai/openchart-core';
 
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Suffix multipliers mirroring core's abbreviateNumber output (K/M/B/T). */
+const SUFFIX_MULTIPLIERS: Record<string, number> = {
+  K: 1_000,
+  M: 1_000_000,
+  B: 1_000_000_000,
+  T: 1_000_000_000_000,
+};
+
+/**
+ * Parse a numeric string that may include comma separators and/or a
+ * K/M/B/T abbreviation suffix (as produced by `abbreviateNumber`).
+ * Returns NaN when the string cannot be parsed.
+ */
+function parseDisplayNumber(raw: string): number {
+  const trimmed = raw.trim();
+  if (!trimmed) return NaN;
+
+  // Check for trailing abbreviation suffix (case-insensitive)
+  const last = trimmed[trimmed.length - 1].toUpperCase();
+  const multiplier = SUFFIX_MULTIPLIERS[last];
+  if (multiplier) {
+    const numPart = trimmed.slice(0, -1).replace(/,/g, '');
+    const n = Number(numPart);
+    return Number.isNaN(n) ? NaN : n * multiplier;
+  }
+
+  // No suffix — strip commas and parse
+  return Number(trimmed.replace(/,/g, ''));
+}
+
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -57,6 +91,9 @@ export function computeBarLabels(
     density === 'endpoints' && marks.length > 1 ? [marks[0], marks[marks.length - 1]] : marks;
 
   const candidates: LabelCandidate[] = [];
+  // Track whether each candidate fits within its stacked segment.
+  // Non-stacked bars are always considered fitting (undefined = fits).
+  const fitsInSegment: boolean[] = [];
 
   const formatter = buildD3Formatter(labelFormat);
 
@@ -72,7 +109,7 @@ export function computeBarLabels(
     // Apply label format if provided (re-parse the number from the aria string)
     let valuePart = rawValue;
     if (formatter) {
-      const num = Number(rawValue.replace(/[^0-9.-]/g, ''));
+      const num = parseDisplayNumber(rawValue);
       if (!Number.isNaN(num)) valuePart = formatter(num);
     }
 
@@ -110,6 +147,10 @@ export function computeBarLabels(
     // SVG places the text center at this y coordinate.
     const anchorY = mark.y + mark.height / 2;
 
+    // Check if label text fits within the stacked segment
+    const fits = !(isStacked && textWidth > mark.width - 2 * LABEL_PADDING);
+
+    fitsInSegment.push(fits);
     candidates.push({
       text: valuePart,
       anchorX,
@@ -132,15 +173,47 @@ export function computeBarLabels(
   if (candidates.length === 0) return [];
 
   // 'all': skip collision detection, mark everything visible
+  // (but hide labels that don't fit in their stacked segment)
   if (density === 'all') {
-    return candidates.map((c) => ({
+    return candidates.map((c, i) => ({
       text: c.text,
       x: c.anchorX,
       y: c.anchorY,
       style: c.style,
-      visible: true,
+      visible: fitsInSegment[i] !== false,
     }));
   }
 
-  return resolveCollisions(candidates);
+  // For 'auto' and 'endpoints': pre-mark candidates that don't fit their
+  // stacked segment as hidden before running collision detection.
+  const fittingCandidates: LabelCandidate[] = [];
+  const unfittingIndices = new Set<number>();
+  for (let i = 0; i < candidates.length; i++) {
+    if (fitsInSegment[i] === false) {
+      unfittingIndices.add(i);
+    } else {
+      fittingCandidates.push(candidates[i]);
+    }
+  }
+
+  const resolved = resolveCollisions(fittingCandidates);
+
+  // Re-insert hidden labels for candidates that didn't fit, preserving order
+  const results: ResolvedLabel[] = [];
+  let resolvedIdx = 0;
+  for (let i = 0; i < candidates.length; i++) {
+    if (unfittingIndices.has(i)) {
+      results.push({
+        text: candidates[i].text,
+        x: candidates[i].anchorX,
+        y: candidates[i].anchorY,
+        style: candidates[i].style,
+        visible: false,
+      });
+    } else {
+      results.push(resolved[resolvedIdx++]);
+    }
+  }
+
+  return results;
 }

package/src/charts/line/labels.ts

@@ -19,7 +19,11 @@ import type {
   LineMark,
   ResolvedLabel,
 } from '@opendata-ai/openchart-core';
-import { estimateTextWidth, resolveCollisions } from '@opendata-ai/openchart-core';
+import {
+  EXTENDED_OFFSET_STRATEGIES,
+  estimateTextWidth,
+  resolveCollisions,
+} from '@opendata-ai/openchart-core';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -127,7 +131,7 @@ export function computeLineLabels(
   // label (which is what we already compute). This is the same as 'auto' for lines
   // since we only compute the endpoint label per series.
 
-  const resolved = resolveCollisions(candidates);
+  const resolved = resolveCollisions(candidates, EXTENDED_OFFSET_STRATEGIES);
   for (let i = 0; i < resolved.length; i++) {
     const seriesKey = seriesOrder[i];
     const label = resolved[i];