@opendata-ai/openchart-engine 2.8.1 → 2.9.0

package/package.json

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

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

@@ -136,6 +136,102 @@ describe('computeAnnotations', () => {
       expect(annotations[0].fill).toBeDefined();
       expect(annotations[0].opacity).toBeDefined();
     });
+
+    it('interpolates range position for values between ordinal data points', () => {
+      const ordinalSpec: NormalizedChartSpec = {
+        type: 'line',
+        data: [
+          { year: '2005', value: 10 },
+          { year: '2007', value: 20 },
+          { year: '2009', value: 30 },
+          { year: '2012', value: 40 },
+        ],
+        encoding: {
+          x: { field: 'year', type: 'ordinal' },
+          y: { field: 'value', type: 'quantitative' },
+        },
+        chrome: {},
+        annotations: [{ type: 'range', x1: '2008', x2: '2010', label: 'Interpolated' }],
+        responsive: true,
+        theme: {},
+        darkMode: 'off',
+        labels: { density: 'auto', format: '' },
+      };
+      const scales = computeScales(ordinalSpec, chartArea, ordinalSpec.data);
+      const annotations = computeAnnotations(ordinalSpec, scales, chartArea, fullStrategy);
+
+      expect(annotations).toHaveLength(1);
+      expect(annotations[0].rect).toBeDefined();
+      expect(annotations[0].rect!.width).toBeGreaterThan(0);
+
+      // Also verify the interpolated range sits between the known data points
+      const rangeWithKnownPoints: NormalizedChartSpec = {
+        ...ordinalSpec,
+        annotations: [{ type: 'range', x1: '2007', x2: '2012', label: 'Known' }],
+      };
+      const knownAnnotations = computeAnnotations(
+        rangeWithKnownPoints,
+        scales,
+        chartArea,
+        fullStrategy,
+      );
+      // The interpolated range (2008-2010) should be narrower than and inside (2007-2012)
+      expect(annotations[0].rect!.width).toBeLessThan(knownAnnotations[0].rect!.width);
+      expect(annotations[0].rect!.x).toBeGreaterThan(knownAnnotations[0].rect!.x);
+    });
+
+    it('clamps interpolation for values outside the ordinal domain range', () => {
+      const ordinalSpec: NormalizedChartSpec = {
+        type: 'line',
+        data: [
+          { year: '2005', value: 10 },
+          { year: '2007', value: 20 },
+          { year: '2009', value: 30 },
+        ],
+        encoding: {
+          x: { field: 'year', type: 'ordinal' },
+          y: { field: 'value', type: 'quantitative' },
+        },
+        chrome: {},
+        annotations: [{ type: 'range', x1: '2003', x2: '2011', label: 'Outside range' }],
+        responsive: true,
+        theme: {},
+        darkMode: 'off',
+        labels: { density: 'auto', format: '' },
+      };
+      const scales = computeScales(ordinalSpec, chartArea, ordinalSpec.data);
+      const annotations = computeAnnotations(ordinalSpec, scales, chartArea, fullStrategy);
+
+      expect(annotations).toHaveLength(1);
+      expect(annotations[0].rect).toBeDefined();
+      expect(annotations[0].rect!.width).toBeGreaterThan(0);
+    });
+
+    it('returns null for non-numeric ordinal domain values', () => {
+      const catSpec: NormalizedChartSpec = {
+        type: 'column',
+        data: [
+          { category: 'Jan', value: 10 },
+          { category: 'Feb', value: 20 },
+          { category: 'Mar', value: 30 },
+        ],
+        encoding: {
+          x: { field: 'category', type: 'ordinal' },
+          y: { field: 'value', type: 'quantitative' },
+        },
+        chrome: {},
+        annotations: [{ type: 'range', x1: 'Jan-15', x2: 'Feb-15', label: 'Non-numeric' }],
+        responsive: true,
+        theme: {},
+        darkMode: 'off',
+        labels: { density: 'auto', format: '' },
+      };
+      const scales = computeScales(catSpec, chartArea, catSpec.data);
+      const annotations = computeAnnotations(catSpec, scales, chartArea, fullStrategy);
+
+      // Non-numeric domain can't interpolate, annotation is dropped
+      expect(annotations).toHaveLength(0);
+    });
   });
 
   describe('reference line annotations', () => {

package/src/annotations/compute.ts

@@ -49,6 +49,42 @@ const DARK_REFLINE_STROKE = '#9ca3af';
 /** Default label offset when using anchor directions. */
 const ANCHOR_OFFSET = 8;
 
+/**
+ * Interpolate a numeric value between sorted domain entries.
+ * Used when an annotation references a value not present in a categorical domain
+ * (e.g. "2008" on an axis with data points at "2007" and "2009").
+ * Returns null if domain values aren't numeric or the domain is too small.
+ */
+function interpolateInDomain(
+  numValue: number,
+  domain: string[],
+  positionOf: (entry: string) => number,
+): number | null {
+  if (domain.length < 2) return null;
+  const nums = domain.map(Number);
+  if (!nums.every(Number.isFinite)) return null;
+
+  // Sort by numeric value so bracket-finding works regardless of data order
+  const sorted = nums.map((n, i) => ({ n, i })).sort((a, b) => a.n - b.n);
+
+  // Find the two sorted neighbors that bracket this value
+  let lower = 0;
+  let upper = sorted.length - 1;
+  for (let i = 0; i < sorted.length; i++) {
+    if (sorted[i].n <= numValue) lower = i;
+    if (sorted[i].n >= numValue) {
+      upper = i;
+      break;
+    }
+  }
+
+  const lowerPos = positionOf(domain[sorted[lower].i]);
+  const upperPos = positionOf(domain[sorted[upper].i]);
+  if (lower === upper) return lowerPos;
+  const t = (numValue - sorted[lower].n) / (sorted[upper].n - sorted[lower].n);
+  return lowerPos + t * (upperPos - lowerPos);
+}
+
 /** Resolve a data value to a pixel position on a given axis. */
 function resolvePosition(
   value: string | number,
@@ -73,17 +109,33 @@ function resolvePosition(
 
   if (type === 'band') {
     const bandScale = s as ScaleBand<string>;
-    const pos = bandScale(String(value));
-    if (pos === undefined) return null;
-    return pos + (bandScale.bandwidth?.() ?? 0) / 2;
+    const strValue = String(value);
+    const pos = bandScale(strValue);
+    if (pos !== undefined) return pos + (bandScale.bandwidth?.() ?? 0) / 2;
+
+    const bw = bandScale.bandwidth?.() ?? 0;
+    return interpolateInDomain(
+      Number(strValue),
+      bandScale.domain(),
+      (entry) => (bandScale(entry) ?? 0) + bw / 2,
+    );
   }
 
-  // point or ordinal: try calling it directly
-  try {
-    return (s as (v: string) => number)(String(value));
-  } catch {
-    return null;
+  // point or ordinal: try direct lookup, fall back to interpolation
+  const strValue = String(value);
+  const directResult = (s as (v: string) => number | undefined)(strValue);
+  if (directResult !== undefined) return directResult;
+
+  if (type === 'point' || type === 'ordinal') {
+    const domain = (s as { domain(): string[] }).domain();
+    return interpolateInDomain(
+      Number(strValue),
+      domain,
+      (entry) => (s as (v: string) => number)(entry) ?? 0,
+    );
   }
+
+  return null;
 }
 
 function makeAnnotationLabelStyle(