@opendata-ai/openchart-engine 2.0.0 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-engine",
-  "version": "2.0.0",
+  "version": "2.2.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": "2.0.0",
+    "@opendata-ai/openchart-core": "2.2.0",
     "d3-array": "^3.2.0",
     "d3-format": "^3.1.2",
     "d3-interpolate": "^3.0.0",

package/src/__test-fixtures__/specs.ts

@@ -66,6 +66,7 @@ export function makeLineSpec(): NormalizedChartSpec {
     theme: {},
     darkMode: 'off',
     labels: { density: 'auto', format: '' },
+    hiddenSeries: [],
   };
 }
 
@@ -92,6 +93,7 @@ export function makeBarSpec(): NormalizedChartSpec {
     theme: {},
     darkMode: 'off',
     labels: { density: 'auto', format: '' },
+    hiddenSeries: [],
   };
 }
 
@@ -120,5 +122,6 @@ export function makeScatterSpec(): NormalizedChartSpec {
     theme: {},
     darkMode: 'off',
     labels: { density: 'auto', format: '' },
+    hiddenSeries: [],
   };
 }

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

@@ -260,6 +260,129 @@ describe('compileChart', () => {
       ),
     ).toThrow('compileTable');
   });
+
+  // ---------------------------------------------------------------------------
+  // hiddenSeries
+  // ---------------------------------------------------------------------------
+
+  it('hiddenSeries filters out data for hidden series from marks', () => {
+    const spec = {
+      ...lineSpec,
+      hiddenSeries: ['UK'],
+    };
+    const layout = compileChart(spec, { width: 600, height: 400 });
+
+    // With UK hidden, only US marks should be present.
+    // Line marks carry a series property.
+    const lineMarks = layout.marks.filter((m) => m.type === 'line');
+    for (const mark of lineMarks) {
+      if (mark.type === 'line') {
+        expect(mark.series).not.toBe('UK');
+      }
+    }
+
+    // Legend should still have entries for both series (hidden ones are dimmed, not removed)
+    expect(layout.legend.entries.length).toBe(2);
+    expect(layout.legend.entries.some((e) => e.label === 'US')).toBe(true);
+    expect(layout.legend.entries.some((e) => e.label === 'UK')).toBe(true);
+  });
+
+  it('hiddenSeries with all series hidden produces no marks', () => {
+    const spec = {
+      ...lineSpec,
+      hiddenSeries: ['US', 'UK'],
+    };
+    const layout = compileChart(spec, { width: 600, height: 400 });
+    // No data left means no marks
+    expect(layout.marks.length).toBe(0);
+  });
+
+  it('hiddenSeries with empty array behaves normally', () => {
+    const spec = {
+      ...lineSpec,
+      hiddenSeries: [],
+    };
+    const layout = compileChart(spec, { width: 600, height: 400 });
+    expect(layout.marks.length).toBeGreaterThan(0);
+  });
+
+  // ---------------------------------------------------------------------------
+  // scale.clip
+  // ---------------------------------------------------------------------------
+
+  it('scale.clip filters data rows outside the y-axis domain', () => {
+    const spec = {
+      type: 'scatter' as const,
+      data: [
+        { x: 1, y: 5 },
+        { x: 2, y: 15 },
+        { x: 3, y: 25 },
+        { x: 4, y: 35 },
+      ],
+      encoding: {
+        x: { field: 'x', type: 'quantitative' as const },
+        y: {
+          field: 'y',
+          type: 'quantitative' as const,
+          scale: { domain: [10, 30] as [number, number], clip: true },
+        },
+      },
+    };
+    const layout = compileChart(spec, { width: 600, height: 400 });
+
+    // Only y=15 and y=25 should remain (y=5 and y=35 are outside [10,30])
+    const pointMarks = layout.marks.filter((m) => m.type === 'point');
+    expect(pointMarks.length).toBe(2);
+  });
+
+  it('scale.clip filters data rows outside the x-axis domain', () => {
+    const spec = {
+      type: 'scatter' as const,
+      data: [
+        { x: 1, y: 10 },
+        { x: 5, y: 20 },
+        { x: 10, y: 30 },
+        { x: 15, y: 40 },
+      ],
+      encoding: {
+        x: {
+          field: 'x',
+          type: 'quantitative' as const,
+          scale: { domain: [3, 12] as [number, number], clip: true },
+        },
+        y: { field: 'y', type: 'quantitative' as const },
+      },
+    };
+    const layout = compileChart(spec, { width: 600, height: 400 });
+
+    // Only x=5 and x=10 should remain
+    const pointMarks = layout.marks.filter((m) => m.type === 'point');
+    expect(pointMarks.length).toBe(2);
+  });
+
+  it('scale.clip=false does not filter data even with domain set', () => {
+    const spec = {
+      type: 'scatter' as const,
+      data: [
+        { x: 1, y: 5 },
+        { x: 2, y: 15 },
+        { x: 3, y: 25 },
+      ],
+      encoding: {
+        x: { field: 'x', type: 'quantitative' as const },
+        y: {
+          field: 'y',
+          type: 'quantitative' as const,
+          scale: { domain: [10, 20] as [number, number], clip: false },
+        },
+      },
+    };
+    const layout = compileChart(spec, { width: 600, height: 400 });
+
+    // All 3 points should still be present (clip is false)
+    const pointMarks = layout.marks.filter((m) => m.type === 'point');
+    expect(pointMarks.length).toBe(3);
+  });
 });
 
 describe('compileTable', () => {

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

@@ -451,4 +451,230 @@ describe('computeAnnotations', () => {
       expect(dy).toBe(-10);
     });
   });
+
+  // -----------------------------------------------------------------
+  // Connector origin auto-selection
+  // -----------------------------------------------------------------
+
+  describe('connector origin auto-selection', () => {
+    it('connector starts from top edge when data point is above label', () => {
+      // Push label far below AND to the right so the top-center is unambiguously closest
+      const spec = makeSpec([
+        {
+          type: 'text',
+          x: '2020-01-01',
+          y: 20,
+          text: 'Below point',
+          anchor: 'bottom',
+          offset: { dx: 0, dy: 150 },
+        },
+      ]);
+      const scales = computeScales(spec, chartArea, spec.data);
+      const annotations = computeAnnotations(spec, scales, chartArea, fullStrategy);
+
+      const label = annotations[0].label!;
+      const connector = label.connector!;
+      const fontSize = 12; // DEFAULT_ANNOTATION_FONT_SIZE
+
+      // Data point is far above the label, so connector should exit from the top edge
+      const topEdgeY = label.y - fontSize;
+      expect(connector.from.y).toBeCloseTo(topEdgeY, 0);
+    });
+
+    it('connector starts from bottom edge when data point is below label', () => {
+      // Push label far above the data point
+      const spec = makeSpec([
+        {
+          type: 'text',
+          x: '2020-01-01',
+          y: 20,
+          text: 'Above point',
+          anchor: 'top',
+          offset: { dx: 0, dy: -80 },
+        },
+      ]);
+      const scales = computeScales(spec, chartArea, spec.data);
+      const annotations = computeAnnotations(spec, scales, chartArea, fullStrategy);
+
+      const label = annotations[0].label!;
+      const connector = label.connector!;
+      const fontSize = 12;
+      const lineHeight = 1.3;
+      const lines = label.text.split('\n');
+
+      // Data point is below the label, so connector should exit from the bottom edge
+      const bottomEdgeY = label.y - fontSize + lines.length * fontSize * lineHeight;
+      expect(connector.from.y).toBeCloseTo(bottomEdgeY, 0);
+    });
+
+    it('connector starts from left edge when data point is left of label', () => {
+      // Push label far to the right of the data point
+      const spec = makeSpec([
+        {
+          type: 'text',
+          x: '2020-01-01',
+          y: 20,
+          text: 'Right of point',
+          anchor: 'right',
+          offset: { dx: 120, dy: 0 },
+        },
+      ]);
+      const scales = computeScales(spec, chartArea, spec.data);
+      const annotations = computeAnnotations(spec, scales, chartArea, fullStrategy);
+
+      const label = annotations[0].label!;
+      const connector = label.connector!;
+
+      // Data point is to the left, so connector should exit from the left edge
+      // For single-line text, left edge x = label.x
+      expect(connector.from.x).toBeCloseTo(label.x, 0);
+    });
+
+    it('connector starts from right edge when data point is right of label', () => {
+      // Push label far to the left of the data point
+      const spec = makeSpec([
+        {
+          type: 'text',
+          x: '2021-01-01',
+          y: 20,
+          text: 'Left of point',
+          anchor: 'left',
+          offset: { dx: -120, dy: 0 },
+        },
+      ]);
+      const scales = computeScales(spec, chartArea, spec.data);
+      const annotations = computeAnnotations(spec, scales, chartArea, fullStrategy);
+
+      const label = annotations[0].label!;
+      const connector = label.connector!;
+
+      // Data point is to the right, so connector should exit from the right edge
+      // Right edge is at label.x + textWidth
+      // For single-line "Left of point" with fontSize=12, weight=400:
+      // textWidth = 14 chars * 12 * 0.55 * 1.0 = 92.4
+      expect(connector.from.x).toBeGreaterThan(label.x + 50); // well past the center
+    });
+
+    it('multi-line text connector uses correct centered bounding box', () => {
+      // Multi-line text with label pushed below data point
+      const spec = makeSpec([
+        {
+          type: 'text',
+          x: '2020-01-01',
+          y: 20,
+          text: 'First line\nSecond line',
+          anchor: 'bottom',
+          offset: { dx: 0, dy: 80 },
+        },
+      ]);
+      const scales = computeScales(spec, chartArea, spec.data);
+      const annotations = computeAnnotations(spec, scales, chartArea, fullStrategy);
+
+      const label = annotations[0].label!;
+      const connector = label.connector!;
+
+      // For multi-line, labelX is the center. The connector should exit
+      // from the top-center since data point is above.
+      // Top-center x should be at labelX (the center of the multi-line text)
+      expect(connector.from.x).toBeCloseTo(label.x, 0);
+    });
+
+    it('connector origin changes when label moves to the other side', () => {
+      // Same data point, label pushed right vs left
+      const specRight = makeSpec([
+        {
+          type: 'text',
+          x: '2020-01-01',
+          y: 20,
+          text: 'Test label',
+          anchor: 'right',
+          offset: { dx: 120, dy: 0 },
+        },
+      ]);
+      const specLeft = makeSpec([
+        {
+          type: 'text',
+          x: '2020-01-01',
+          y: 20,
+          text: 'Test label',
+          anchor: 'left',
+          offset: { dx: -120, dy: 0 },
+        },
+      ]);
+      const scalesRight = computeScales(specRight, chartArea, specRight.data);
+      const scalesLeft = computeScales(specLeft, chartArea, specLeft.data);
+
+      const annotationsRight = computeAnnotations(specRight, scalesRight, chartArea, fullStrategy);
+      const annotationsLeft = computeAnnotations(specLeft, scalesLeft, chartArea, fullStrategy);
+
+      const labelRight = annotationsRight[0].label!;
+      const labelLeft = annotationsLeft[0].label!;
+      const fromRight = labelRight.connector!.from;
+      const fromLeft = labelLeft.connector!.from;
+
+      // When label is to the right of data, connector exits from left edge (= label.x)
+      expect(fromRight.x).toBeCloseTo(labelRight.x, 0);
+      // When label is to the left of data, connector exits from right edge (label.x + textWidth)
+      expect(fromLeft.x).toBeGreaterThan(labelLeft.x + 30); // well past the left edge
+    });
+
+    it('connectorOffset is still applied on top of auto-selected origin', () => {
+      const specWithOffset = makeSpec([
+        {
+          type: 'text',
+          x: '2020-01-01',
+          y: 20,
+          text: 'Offset test',
+          anchor: 'bottom',
+          offset: { dx: 0, dy: 80 },
+          connectorOffset: { from: { dx: 10, dy: 5 } },
+        },
+      ]);
+      const specNoOffset = makeSpec([
+        {
+          type: 'text',
+          x: '2020-01-01',
+          y: 20,
+          text: 'Offset test',
+          anchor: 'bottom',
+          offset: { dx: 0, dy: 80 },
+        },
+      ]);
+      const scales = computeScales(specWithOffset, chartArea, specWithOffset.data);
+
+      const withOffset = computeAnnotations(specWithOffset, scales, chartArea, fullStrategy);
+      const withoutOffset = computeAnnotations(specNoOffset, scales, chartArea, fullStrategy);
+
+      const fromWith = withOffset[0].label!.connector!.from;
+      const fromWithout = withoutOffset[0].label!.connector!.from;
+
+      expect(fromWith.x - fromWithout.x).toBeCloseTo(10, 0);
+      expect(fromWith.y - fromWithout.y).toBeCloseTo(5, 0);
+    });
+
+    it('curve connector still uses right edge regardless of data point position', () => {
+      // Push label below and to the right, but curve should still start from right edge
+      const spec = makeSpec([
+        {
+          type: 'text',
+          x: '2020-01-01',
+          y: 20,
+          text: 'Curve test',
+          anchor: 'bottom',
+          offset: { dx: 0, dy: 80 },
+          connector: 'curve',
+        },
+      ]);
+      const scales = computeScales(spec, chartArea, spec.data);
+      const annotations = computeAnnotations(spec, scales, chartArea, fullStrategy);
+
+      const label = annotations[0].label!;
+      const connector = label.connector!;
+
+      // Curve should start from right edge of text, not top edge
+      // Right edge x ≈ label.x + textWidth
+      // "Curve test" = 10 chars * 12 * 0.55 = 66
+      expect(connector.from.x).toBeCloseTo(label.x + 66, 1);
+    });
+  });
 });

package/src/annotations/compute.ts

@@ -35,6 +35,7 @@ import type { ResolvedScales } from '../layout/scales';
 
 const DEFAULT_ANNOTATION_FONT_SIZE = 12;
 const DEFAULT_ANNOTATION_FONT_WEIGHT = 400;
+const DEFAULT_LINE_HEIGHT = 1.3;
 const DEFAULT_RANGE_FILL = '#f0c040';
 const DEFAULT_RANGE_OPACITY = 0.15;
 const DEFAULT_REFLINE_DASH = '4 3';
@@ -97,11 +98,36 @@ function makeAnnotationLabelStyle(
     fontSize: fontSize ?? DEFAULT_ANNOTATION_FONT_SIZE,
     fontWeight: fontWeight ?? DEFAULT_ANNOTATION_FONT_WEIGHT,
     fill: fill ?? defaultFill,
-    lineHeight: 1.3,
+    lineHeight: DEFAULT_LINE_HEIGHT,
     textAnchor: 'start',
   };
 }
 
+/**
+ * Compute the bounding box of annotation text at a given label position.
+ * Multi-line text is centered at labelX; single-line starts at labelX.
+ */
+function computeTextBounds(
+  labelX: number,
+  labelY: number,
+  text: string,
+  fontSize: number,
+  fontWeight: number,
+): Rect {
+  const lines = text.split('\n');
+  const isMultiLine = lines.length > 1;
+  const maxWidth = Math.max(...lines.map((line) => estimateTextWidth(line, fontSize, fontWeight)));
+  const totalHeight = lines.length * fontSize * DEFAULT_LINE_HEIGHT;
+  const x = isMultiLine ? labelX - maxWidth / 2 : labelX;
+
+  return {
+    x,
+    y: labelY - fontSize,
+    width: maxWidth,
+    height: totalHeight,
+  };
+}
+
 /**
  * Apply anchor direction to compute label offset from data point.
  * Returns { dx, dy } pixel offsets.
@@ -144,6 +170,57 @@ function applyOffset(
   };
 }
 
+// ---------------------------------------------------------------------------
+// Connector origin: pick the edge midpoint closest to the data point
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute the connector origin point on the text bounding box.
+ * For straight connectors, finds the edge midpoint (top, bottom, left, right)
+ * closest to the data point. For curve connectors, always uses the right edge.
+ */
+function computeConnectorOrigin(
+  labelX: number,
+  labelY: number,
+  text: string,
+  fontSize: number,
+  fontWeight: number,
+  targetX: number,
+  targetY: number,
+  connectorStyle: 'straight' | 'curve',
+): { x: number; y: number } {
+  const box = computeTextBounds(labelX, labelY, text, fontSize, fontWeight);
+  const boxCenterX = box.x + box.width / 2;
+  const boxCenterY = box.y + box.height / 2;
+
+  // Curve connectors always start from the right edge
+  if (connectorStyle === 'curve') {
+    return {
+      x: box.x + box.width,
+      y: boxCenterY,
+    };
+  }
+
+  // Normalize the vector from box center to target by the box half-dimensions.
+  // This accounts for the box aspect ratio: a wide text box should prefer
+  // top/bottom exits even when the target is also offset horizontally.
+  const halfW = box.width / 2 || 1;
+  const halfH = box.height / 2 || 1;
+  const ndx = (targetX - boxCenterX) / halfW;
+  const ndy = (targetY - boxCenterY) / halfH;
+
+  if (Math.abs(ndy) >= Math.abs(ndx)) {
+    // Target is more above/below than left/right → use top or bottom edge
+    return ndy < 0
+      ? { x: boxCenterX, y: box.y } // top
+      : { x: boxCenterX, y: box.y + box.height }; // bottom
+  }
+  // Target is more left/right → use left or right edge
+  return ndx < 0
+    ? { x: box.x, y: boxCenterY } // left
+    : { x: box.x + box.width, y: boxCenterY }; // right
+}
+
 // ---------------------------------------------------------------------------
 // Text annotation
 // ---------------------------------------------------------------------------
@@ -178,25 +255,19 @@ function resolveTextAnnotation(
   const showConnector = annotation.connector !== false;
   const connectorStyle = annotation.connector === 'curve' ? 'curve' : 'straight';
 
-  // Compute connector origin based on style and text layout
+  // Compute connector origin: pick the edge midpoint closest to the data point
   const fontSize = annotation.fontSize ?? DEFAULT_ANNOTATION_FONT_SIZE;
   const fontWeight = annotation.fontWeight ?? DEFAULT_ANNOTATION_FONT_WEIGHT;
-  const lines = annotation.text.split('\n');
-  const lineHeight = 1.3;
-  let connectorFromX: number;
-  if (connectorStyle === 'curve') {
-    // Curved connectors start from the right edge of the text
-    connectorFromX = labelX + estimateTextWidth(annotation.text, fontSize, fontWeight);
-  } else if (lines.length > 1) {
-    // Multi-line text uses text-anchor: middle, so labelX is already the center
-    connectorFromX = labelX;
-  } else {
-    // Straight connectors start from the horizontal center of the text
-    connectorFromX = labelX + estimateTextWidth(annotation.text, fontSize, fontWeight) / 2;
-  }
-
-  // Connector from.y sits at the bottom of the text block
-  const connectorFromY = labelY + (lines.length - 1) * fontSize * lineHeight + fontSize * 0.3;
+  const { x: connectorFromX, y: connectorFromY } = computeConnectorOrigin(
+    labelX,
+    labelY,
+    annotation.text,
+    fontSize,
+    fontWeight,
+    px,
+    py,
+    connectorStyle,
+  );
 
   // Apply user-provided connector endpoint offsets
   const baseFrom = { x: connectorFromX, y: connectorFromY };
@@ -402,25 +473,9 @@ function resolveRefLineAnnotation(
 
 /** Estimate the bounding box of an annotation label. */
 function estimateLabelBounds(label: ResolvedLabel): Rect {
-  const lines = label.text.split('\n');
   const fontSize = label.style.fontSize ?? DEFAULT_ANNOTATION_FONT_SIZE;
   const fontWeight = label.style.fontWeight ?? DEFAULT_ANNOTATION_FONT_WEIGHT;
-  const lineHeight = label.style.lineHeight ?? 1.3;
-
-  const maxWidth = Math.max(...lines.map((line) => estimateTextWidth(line, fontSize, fontWeight)));
-  const totalHeight = lines.length * fontSize * lineHeight;
-
-  // Multi-line text is rendered with text-anchor: middle by the SVG renderer,
-  // so the text is centered at label.x. Single-line uses the style's textAnchor.
-  const isMultiLine = lines.length > 1;
-  const anchorX = isMultiLine ? label.x - maxWidth / 2 : label.x;
-
-  return {
-    x: anchorX,
-    y: label.y - fontSize,
-    width: maxWidth,
-    height: totalHeight,
-  };
+  return computeTextBounds(label.x, label.y, label.text, fontSize, fontWeight);
 }
 
 /** Check if two rects overlap. */
@@ -491,19 +546,34 @@ function nudgeAnnotationFromObstacles(
   candidates.sort((a, b) => a.distance - b.distance);
 
   for (const { dx, dy } of candidates) {
+    const newLabelX = annotation.label.x + dx;
+    const newLabelY = annotation.label.y + dy;
+
+    // Recompute connector origin for the new label position so the connector
+    // exits from the edge closest to the data point after nudging.
+    let newConnector = annotation.label.connector;
+    if (newConnector) {
+      const annFontSize = annotation.label.style.fontSize ?? DEFAULT_ANNOTATION_FONT_SIZE;
+      const annFontWeight = annotation.label.style.fontWeight ?? DEFAULT_ANNOTATION_FONT_WEIGHT;
+      const connStyle = newConnector.style === 'curve' ? ('curve' as const) : ('straight' as const);
+      const newFrom = computeConnectorOrigin(
+        newLabelX,
+        newLabelY,
+        annotation.label.text,
+        annFontSize,
+        annFontWeight,
+        px,
+        py,
+        connStyle,
+      );
+      newConnector = { ...newConnector, from: newFrom };
+    }
+
     const candidateLabel: ResolvedLabel = {
       ...annotation.label,
-      x: annotation.label.x + dx,
-      y: annotation.label.y + dy,
-      connector: annotation.label.connector
-        ? {
-            ...annotation.label.connector,
-            from: {
-              x: annotation.label.connector.from.x + dx,
-              y: annotation.label.connector.from.y + dy,
-            },
-          }
-        : undefined,
+      x: newLabelX,
+      y: newLabelY,
+      connector: newConnector,
     };
 
     const candidateBounds = estimateLabelBounds(candidateLabel);