@opendata-ai/openchart-engine 2.4.0 → 2.6.0

package/package.json

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

package/src/__test-fixtures__/specs.ts

@@ -67,6 +67,7 @@ export function makeLineSpec(): NormalizedChartSpec {
     darkMode: 'off',
     labels: { density: 'auto', format: '' },
     hiddenSeries: [],
+    seriesStyles: {},
   };
 }
 
@@ -94,6 +95,7 @@ export function makeBarSpec(): NormalizedChartSpec {
     darkMode: 'off',
     labels: { density: 'auto', format: '' },
     hiddenSeries: [],
+    seriesStyles: {},
   };
 }
 
@@ -123,5 +125,6 @@ export function makeScatterSpec(): NormalizedChartSpec {
     darkMode: 'off',
     labels: { density: 'auto', format: '' },
     hiddenSeries: [],
+    seriesStyles: {},
   };
 }

package/src/annotations/compute.ts

@@ -356,18 +356,33 @@ function resolveRangeAnnotation(
 
   const rect: Rect = { x, y, width, height };
 
-  // Label at the top-left of the range, with optional offset
+  // Label positioned within the range, with optional offset.
+  // labelAnchor controls horizontal placement:
+  //   "left" (default): left edge, text-anchor start
+  //   "top"/"auto": horizontally centered, text-anchor middle
+  //   "right": right edge, text-anchor end
   let label: ResolvedLabel | undefined;
   if (annotation.label) {
-    const baseDx = 4;
+    const anchor = annotation.labelAnchor ?? 'left';
+    const centered = anchor === 'top' || anchor === 'bottom' || anchor === 'auto';
+    const baseDx = centered ? 0 : anchor === 'right' ? -4 : 4;
     const baseDy = 14;
     const labelDelta = applyOffset({ dx: baseDx, dy: baseDy }, annotation.labelOffset);
 
+    const style = makeAnnotationLabelStyle(11, 500, undefined, isDark);
+    if (centered) {
+      style.textAnchor = 'middle';
+    } else if (anchor === 'right') {
+      style.textAnchor = 'end';
+    }
+
+    const baseX = centered ? x + width / 2 : anchor === 'right' ? x + width : x;
+
     label = {
       text: annotation.label,
-      x: x + labelDelta.dx,
+      x: baseX + labelDelta.dx,
       y: y + labelDelta.dy,
-      style: makeAnnotationLabelStyle(11, 500, undefined, isDark),
+      style,
       visible: true,
     };
   }
@@ -428,11 +443,15 @@ function resolveRefLineAnnotation(
 
   // Label at the right end for horizontal, top end for vertical, with optional offset.
   // Horizontal refline labels use text-anchor 'end' so text stays inside the chart.
+  // labelAnchor controls which side of the line the label sits on:
+  //   "top" (default): above horizontal, left of vertical
+  //   "bottom": below horizontal, right of vertical
   let label: ResolvedLabel | undefined;
   if (annotation.label) {
     const isHorizontal = annotation.y !== undefined;
+    const anchor = annotation.labelAnchor ?? 'top';
     const baseDx = isHorizontal ? -4 : 4;
-    const baseDy = -4;
+    const baseDy = anchor === 'bottom' ? 14 : -4;
     const labelDelta = applyOffset({ dx: baseDx, dy: baseDy }, annotation.labelOffset);
 
     const defaultStroke = isDark ? DARK_REFLINE_STROKE : LIGHT_REFLINE_STROKE;

package/src/charts/bar/index.ts

@@ -17,7 +17,7 @@ export const barRenderer: ChartRenderer = (spec, scales, chartArea, strategy, _t
   const marks = computeBarMarks(spec, scales, chartArea, strategy);
 
   // Compute and attach value labels (respects spec.labels.density)
-  const labels = computeBarLabels(marks, chartArea, spec.labels.density);
+  const labels = computeBarLabels(marks, chartArea, spec.labels.density, spec.labels.format);
   for (let i = 0; i < marks.length && i < labels.length; i++) {
     marks[i].label = labels[i];
   }

package/src/charts/bar/labels.ts

@@ -18,6 +18,7 @@ import type {
   ResolvedLabel,
 } from '@opendata-ai/openchart-core';
 import { estimateTextWidth, resolveCollisions } from '@opendata-ai/openchart-core';
+import { format as d3Format } from 'd3-format';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -43,6 +44,7 @@ export function computeBarLabels(
   marks: RectMark[],
   _chartArea: { x: number; y: number; width: number; height: number },
   density: LabelDensity = 'auto',
+  labelFormat?: string,
 ): ResolvedLabel[] {
   // 'none': no labels at all
   if (density === 'none') return [];
@@ -53,14 +55,43 @@ export function computeBarLabels(
 
   const candidates: LabelCandidate[] = [];
 
+  // Build a d3 formatter if a label format string was provided.
+  // Supports a literal suffix after the d3 format, e.g. ".1f%" formats as "12.5%"
+  // (the trailing "%" is appended literally, not d3's multiply-by-100 percent type).
+  let formatter: ((v: number) => string) | null = null;
+  if (labelFormat) {
+    try {
+      formatter = d3Format(labelFormat);
+    } catch {
+      // If d3-format rejects it, try stripping a trailing suffix
+      const suffixMatch = labelFormat.match(/^(.+[a-z])([^a-z]+)$/i);
+      if (suffixMatch) {
+        try {
+          const d3Fmt = d3Format(suffixMatch[1]);
+          const suffix = suffixMatch[2];
+          formatter = (v: number) => d3Fmt(v) + suffix;
+        } catch {
+          // Give up on formatting
+        }
+      }
+    }
+  }
+
   for (const mark of targetMarks) {
     // Extract the display value from the aria label.
     // Format is "category: value" or "category, group: value".
     // Use the last colon to split, which handles colons in category names.
     const ariaLabel = mark.aria.label;
     const lastColon = ariaLabel.lastIndexOf(':');
-    const valuePart = lastColon >= 0 ? ariaLabel.slice(lastColon + 1).trim() : '';
-    if (!valuePart) continue;
+    const rawValue = lastColon >= 0 ? ariaLabel.slice(lastColon + 1).trim() : '';
+    if (!rawValue) continue;
+
+    // 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, ''));
+      if (!Number.isNaN(num)) valuePart = formatter(num);
+    }
 
     const textWidth = estimateTextWidth(valuePart, LABEL_FONT_SIZE, LABEL_FONT_WEIGHT);
     const textHeight = LABEL_FONT_SIZE * 1.2;

package/src/charts/line/__tests__/compute.test.ts

@@ -799,3 +799,112 @@ describe('computeLineLabels', () => {
     expect(labelMap.size).toBe(0);
   });
 });
+
+// ---------------------------------------------------------------------------
+// seriesStyles tests
+// ---------------------------------------------------------------------------
+
+describe('seriesStyles', () => {
+  it('applies dashed line style to a specific series', () => {
+    const spec = makeMultiSeriesSpec();
+    spec.seriesStyles = { UK: { lineStyle: 'dashed' } };
+    const scales = computeScales(spec, chartArea, spec.data);
+    const marks = computeLineMarks(spec, scales, chartArea, fullStrategy);
+
+    const lineMarks = marks.filter((m): m is LineMark => m.type === 'line');
+    const ukLine = lineMarks.find((m) => m.seriesKey === 'UK');
+    const usLine = lineMarks.find((m) => m.seriesKey === 'US');
+
+    expect(ukLine?.strokeDasharray).toBe('6 4');
+    expect(usLine?.strokeDasharray).toBeUndefined();
+  });
+
+  it('applies dotted line style', () => {
+    const spec = makeMultiSeriesSpec();
+    spec.seriesStyles = { US: { lineStyle: 'dotted' } };
+    const scales = computeScales(spec, chartArea, spec.data);
+    const marks = computeLineMarks(spec, scales, chartArea, fullStrategy);
+
+    const usLine = marks.find((m): m is LineMark => m.type === 'line' && m.seriesKey === 'US');
+    expect(usLine?.strokeDasharray).toBe('2 3');
+  });
+
+  it('hides point markers when showPoints is false', () => {
+    const spec = makeMultiSeriesSpec();
+    spec.seriesStyles = { UK: { showPoints: false } };
+    const scales = computeScales(spec, chartArea, spec.data);
+    const marks = computeLineMarks(spec, scales, chartArea, fullStrategy);
+
+    const ukPoints = marks.filter(
+      (m): m is PointMark => m.type === 'point' && m.data.country === 'UK',
+    );
+    const usPoints = marks.filter(
+      (m): m is PointMark => m.type === 'point' && m.data.country === 'US',
+    );
+
+    // UK points should have r=0 (hidden)
+    expect(ukPoints.every((p) => p.r === 0)).toBe(true);
+    // US points should still have default radius
+    expect(usPoints.every((p) => p.r > 0)).toBe(true);
+  });
+
+  it('overrides strokeWidth for a series', () => {
+    const spec = makeMultiSeriesSpec();
+    spec.seriesStyles = { UK: { strokeWidth: 1.5 } };
+    const scales = computeScales(spec, chartArea, spec.data);
+    const marks = computeLineMarks(spec, scales, chartArea, fullStrategy);
+
+    const lineMarks = marks.filter((m): m is LineMark => m.type === 'line');
+    const ukLine = lineMarks.find((m) => m.seriesKey === 'UK');
+    const usLine = lineMarks.find((m) => m.seriesKey === 'US');
+
+    expect(ukLine?.strokeWidth).toBe(1.5);
+    expect(usLine?.strokeWidth).toBe(2.5); // default
+  });
+
+  it('sets opacity on a series', () => {
+    const spec = makeMultiSeriesSpec();
+    spec.seriesStyles = { UK: { opacity: 0.5 } };
+    const scales = computeScales(spec, chartArea, spec.data);
+    const marks = computeLineMarks(spec, scales, chartArea, fullStrategy);
+
+    const ukLine = marks.find((m): m is LineMark => m.type === 'line' && m.seriesKey === 'UK');
+    const usLine = marks.find((m): m is LineMark => m.type === 'line' && m.seriesKey === 'US');
+
+    expect(ukLine?.opacity).toBe(0.5);
+    expect(usLine?.opacity).toBeUndefined();
+  });
+
+  it('combines multiple style overrides on the same series', () => {
+    const spec = makeMultiSeriesSpec();
+    spec.seriesStyles = {
+      UK: { lineStyle: 'dashed', showPoints: false, strokeWidth: 1, opacity: 0.6 },
+    };
+    const scales = computeScales(spec, chartArea, spec.data);
+    const marks = computeLineMarks(spec, scales, chartArea, fullStrategy);
+
+    const ukLine = marks.find((m): m is LineMark => m.type === 'line' && m.seriesKey === 'UK');
+    expect(ukLine?.strokeDasharray).toBe('6 4');
+    expect(ukLine?.strokeWidth).toBe(1);
+    expect(ukLine?.opacity).toBe(0.6);
+
+    const ukPoints = marks.filter(
+      (m): m is PointMark => m.type === 'point' && m.data.country === 'UK',
+    );
+    expect(ukPoints.every((p) => p.r === 0)).toBe(true);
+  });
+
+  it('does not apply styles when seriesStyles is empty', () => {
+    const spec = makeMultiSeriesSpec();
+    spec.seriesStyles = {};
+    const scales = computeScales(spec, chartArea, spec.data);
+    const marks = computeLineMarks(spec, scales, chartArea, fullStrategy);
+
+    const lineMarks = marks.filter((m): m is LineMark => m.type === 'line');
+    for (const line of lineMarks) {
+      expect(line.strokeDasharray).toBeUndefined();
+      expect(line.opacity).toBeUndefined();
+      expect(line.strokeWidth).toBe(2.5);
+    }
+  });
+});

package/src/charts/line/compute.ts

@@ -140,6 +140,15 @@ export function computeLineMarks(
     // segments are created by starting a new M command.
     const combinedPath = pathParts.join(' ');
 
+    // Look up per-series style overrides
+    const seriesStyleKey = seriesKey === '__default__' ? undefined : seriesKey;
+    const styleOverride = seriesStyleKey ? spec.seriesStyles?.[seriesStyleKey] : undefined;
+
+    // Map lineStyle to SVG strokeDasharray
+    let strokeDasharray: string | undefined;
+    if (styleOverride?.lineStyle === 'dashed') strokeDasharray = '6 4';
+    else if (styleOverride?.lineStyle === 'dotted') strokeDasharray = '2 3';
+
     // Create the LineMark with the combined path points.
     // The points array includes all valid points across all segments.
     const lineMark: LineMark = {
@@ -147,25 +156,28 @@ export function computeLineMarks(
       points: allPoints,
       path: combinedPath,
       stroke: color,
-      strokeWidth: DEFAULT_STROKE_WIDTH,
-      seriesKey: seriesKey === '__default__' ? undefined : seriesKey,
+      strokeWidth: styleOverride?.strokeWidth ?? DEFAULT_STROKE_WIDTH,
+      strokeDasharray,
+      opacity: styleOverride?.opacity,
+      seriesKey: seriesStyleKey,
       data: pointsWithData.map((p) => p.row),
       aria,
     };
 
     marks.push(lineMark);
 
-    // Create point marks for hover targets
+    // Create point marks for hover targets (skip if showPoints is false)
+    const showPoints = styleOverride?.showPoints !== false;
     for (let i = 0; i < pointsWithData.length; i++) {
       const p = pointsWithData[i];
       const pointMark: PointMark = {
         type: 'point',
         cx: p.x,
         cy: p.y,
-        r: DEFAULT_POINT_RADIUS,
+        r: showPoints ? DEFAULT_POINT_RADIUS : 0,
         fill: color,
-        stroke: '#ffffff',
-        strokeWidth: 1.5,
+        stroke: showPoints ? '#ffffff' : 'transparent',
+        strokeWidth: showPoints ? 1.5 : 0,
         fillOpacity: 0,
         data: p.row,
         aria: {

package/src/compiler/normalize.ts

@@ -197,6 +197,7 @@ function normalizeChartSpec(spec: ChartSpec, warnings: string[]): NormalizedChar
     theme: spec.theme ?? {},
     darkMode: spec.darkMode ?? 'off',
     hiddenSeries: spec.hiddenSeries ?? [],
+    seriesStyles: spec.seriesStyles ?? {},
   };
 }
 

package/src/compiler/types.ts

@@ -73,6 +73,8 @@ export interface NormalizedChartSpec {
   darkMode: DarkMode;
   /** Series names to hide from rendering. */
   hiddenSeries: string[];
+  /** Per-series visual style overrides. */
+  seriesStyles: Record<string, import('@opendata-ai/openchart-core').SeriesStyle>;
 }
 
 /** A TableSpec with all optional fields filled with sensible defaults. */

package/src/layout/axes.ts

@@ -16,6 +16,7 @@ import type {
   TextStyle,
 } from '@opendata-ai/openchart-core';
 import { abbreviateNumber, formatDate, formatNumber } from '@opendata-ai/openchart-core';
+import { format as d3Format } from 'd3-format';
 import type { ScaleBand } from 'd3-scale';
 import type {
   D3CategoricalScale,
@@ -147,7 +148,21 @@ function formatTickLabel(value: unknown, resolvedScale: ResolvedScale): string {
 
   if (resolvedScale.type === 'linear' || resolvedScale.type === 'log') {
     const num = value as number;
-    if (formatStr) return formatNumber(num);
+    if (formatStr) {
+      try {
+        return d3Format(formatStr)(num);
+      } catch {
+        // Support literal suffix after d3 format, e.g. ".1f%" → d3(".1f") + "%"
+        const suffixMatch = formatStr.match(/^(.+[a-z])([^a-z]+)$/i);
+        if (suffixMatch) {
+          try {
+            return d3Format(suffixMatch[1])(num) + suffixMatch[2];
+          } catch {
+            // Fall through to default formatting
+          }
+        }
+      }
+    }
     // Abbreviate large numbers for axis labels
     if (Math.abs(num) >= 1000) return abbreviateNumber(num);
     return formatNumber(num);

package/src/layout/dimensions.ts

@@ -127,8 +127,10 @@ export function computeDimensions(
     left: padding + (isRadial ? padding : axisMargin),
   };
 
-  // Dynamic right margin for line/area end-of-line labels
-  if (spec.type === 'line' || spec.type === 'area') {
+  // Dynamic right margin for line/area end-of-line labels.
+  // Only reserve space when labels will actually render (density != 'none').
+  const labelDensity = spec.labels.density;
+  if ((spec.type === 'line' || spec.type === 'area') && labelDensity !== 'none') {
     // Estimate label width from longest series name (color encoding domain)
     const colorField = encoding.color?.field;
     if (colorField) {