@opendata-ai/openchart-engine 2.5.0 → 2.7.0

package/package.json

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

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/__tests__/compute.test.ts

@@ -291,4 +291,55 @@ describe('computeBarLabels', () => {
     expect(texts).toContain('30');
     expect(texts).toContain('70');
   });
+
+  it('applies d3 label format string', () => {
+    const spec = makeSimpleBarSpec();
+    const scales = computeScales(spec, chartArea, spec.data);
+    const marks = computeBarMarks(spec, scales, chartArea, fullStrategy);
+    const labels = computeBarLabels(marks, chartArea, 'auto', '$,.0f');
+
+    const texts = labels.map((l) => l.text);
+    expect(texts).toContain('$50');
+    expect(texts).toContain('$30');
+    expect(texts).toContain('$70');
+  });
+
+  it('applies format with literal alpha suffix (e.g. "T")', () => {
+    const spec: NormalizedChartSpec = {
+      type: 'bar',
+      data: [
+        { company: 'Apple', cap: 3.75 },
+        { company: 'Meta', cap: 1.63 },
+      ],
+      encoding: {
+        x: { field: 'cap', type: 'quantitative' },
+        y: { field: 'company', type: 'nominal' },
+      },
+      chrome: {},
+      annotations: [],
+      responsive: true,
+      theme: {},
+      darkMode: 'off',
+      labels: { density: 'all', format: '$,.2~fT' },
+    };
+    const scales = computeScales(spec, chartArea, spec.data);
+    const marks = computeBarMarks(spec, scales, chartArea, fullStrategy);
+    const labels = computeBarLabels(marks, chartArea, 'all', '$,.2~fT');
+
+    const texts = labels.map((l) => l.text);
+    expect(texts).toContain('$3.75T');
+    expect(texts).toContain('$1.63T');
+  });
+
+  it('applies format with non-alpha suffix (e.g. "%")', () => {
+    const spec = makeSimpleBarSpec();
+    const scales = computeScales(spec, chartArea, spec.data);
+    const marks = computeBarMarks(spec, scales, chartArea, fullStrategy);
+    const labels = computeBarLabels(marks, chartArea, 'auto', '.0f%');
+
+    const texts = labels.map((l) => l.text);
+    expect(texts).toContain('50%');
+    expect(texts).toContain('30%');
+    expect(texts).toContain('70%');
+  });
 });

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

@@ -17,7 +17,11 @@ import type {
   RectMark,
   ResolvedLabel,
 } from '@opendata-ai/openchart-core';
-import { estimateTextWidth, resolveCollisions } from '@opendata-ai/openchart-core';
+import {
+  buildD3Formatter,
+  estimateTextWidth,
+  resolveCollisions,
+} from '@opendata-ai/openchart-core';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -43,6 +47,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 +58,23 @@ export function computeBarLabels(
 
   const candidates: LabelCandidate[] = [];
 
+  const formatter = buildD3Formatter(labelFormat);
+
   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/column/__tests__/compute.test.ts

@@ -274,4 +274,80 @@ describe('computeColumnLabels', () => {
     expect(texts).toContain('120');
     expect(texts).toContain('200');
   });
+
+  it('applies d3 label format string', () => {
+    const spec = makeSimpleColumnSpec();
+    const scales = computeScales(spec, chartArea, spec.data);
+    const marks = computeColumnMarks(spec, scales, chartArea, fullStrategy);
+    const labels = computeColumnLabels(marks, chartArea, 'auto', '$,.0f');
+
+    const texts = labels.map((l) => l.text);
+    expect(texts).toContain('$120');
+    expect(texts).toContain('$200');
+  });
+
+  it('applies format with trailing zero trim (~)', () => {
+    const spec: NormalizedChartSpec = {
+      type: 'column',
+      data: [
+        { company: 'A', cap: 3.1 },
+        { company: 'B', cap: 2.85 },
+      ],
+      encoding: {
+        x: { field: 'company', type: 'nominal' },
+        y: { field: 'cap', type: 'quantitative' },
+      },
+      chrome: {},
+      annotations: [],
+      responsive: true,
+      theme: {},
+      darkMode: 'off',
+      labels: { density: 'all', format: '$,.2~f' },
+    };
+    const scales = computeScales(spec, chartArea, spec.data);
+    const marks = computeColumnMarks(spec, scales, chartArea, fullStrategy);
+    const labels = computeColumnLabels(marks, chartArea, 'all', '$,.2~f');
+
+    const texts = labels.map((l) => l.text);
+    expect(texts).toContain('$3.1');
+    expect(texts).toContain('$2.85');
+  });
+
+  it('applies format with literal alpha suffix (e.g. "T")', () => {
+    const spec: NormalizedChartSpec = {
+      type: 'column',
+      data: [
+        { company: 'Apple', cap: 3.75 },
+        { company: 'Meta', cap: 1.63 },
+      ],
+      encoding: {
+        x: { field: 'company', type: 'nominal' },
+        y: { field: 'cap', type: 'quantitative' },
+      },
+      chrome: {},
+      annotations: [],
+      responsive: true,
+      theme: {},
+      darkMode: 'off',
+      labels: { density: 'all', format: '$,.2~fT' },
+    };
+    const scales = computeScales(spec, chartArea, spec.data);
+    const marks = computeColumnMarks(spec, scales, chartArea, fullStrategy);
+    const labels = computeColumnLabels(marks, chartArea, 'all', '$,.2~fT');
+
+    const texts = labels.map((l) => l.text);
+    expect(texts).toContain('$3.75T');
+    expect(texts).toContain('$1.63T');
+  });
+
+  it('applies format with non-alpha suffix (e.g. "%")', () => {
+    const spec = makeSimpleColumnSpec();
+    const scales = computeScales(spec, chartArea, spec.data);
+    const marks = computeColumnMarks(spec, scales, chartArea, fullStrategy);
+    const labels = computeColumnLabels(marks, chartArea, 'auto', '.0f%');
+
+    const texts = labels.map((l) => l.text);
+    expect(texts).toContain('120%');
+    expect(texts).toContain('200%');
+  });
 });

package/src/charts/column/index.ts

@@ -17,7 +17,7 @@ export const columnRenderer: ChartRenderer = (spec, scales, chartArea, strategy,
   const marks = computeColumnMarks(spec, scales, chartArea, strategy);
 
   // Compute and attach value labels (respects spec.labels.density)
-  const labels = computeColumnLabels(marks, chartArea, spec.labels.density);
+  const labels = computeColumnLabels(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/column/labels.ts

@@ -17,7 +17,11 @@ import type {
   RectMark,
   ResolvedLabel,
 } from '@opendata-ai/openchart-core';
-import { estimateTextWidth, resolveCollisions } from '@opendata-ai/openchart-core';
+import {
+  buildD3Formatter,
+  estimateTextWidth,
+  resolveCollisions,
+} from '@opendata-ai/openchart-core';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -40,6 +44,7 @@ export function computeColumnLabels(
   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 [];
@@ -48,6 +53,8 @@ export function computeColumnLabels(
   const targetMarks =
     density === 'endpoints' && marks.length > 1 ? [marks[0], marks[marks.length - 1]] : marks;
 
+  const formatter = buildD3Formatter(labelFormat);
+
   const candidates: LabelCandidate[] = [];
 
   for (const mark of targetMarks) {
@@ -56,8 +63,15 @@ export function computeColumnLabels(
     // 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 numericValue = parseFloat(valuePart);
     const isNegative = Number.isFinite(numericValue) && numericValue < 0;
@@ -67,7 +81,7 @@ export function computeColumnLabels(
 
     // For positive values, place label above the column top.
     // For negative values, place label below the column bottom.
-    const anchorX = mark.x + mark.width / 2 - textWidth / 2;
+    const anchorX = mark.x + mark.width / 2;
     const anchorY = isNegative
       ? mark.y + mark.height + LABEL_OFFSET_Y
       : mark.y - LABEL_OFFSET_Y - textHeight;

package/src/layout/axes.ts

@@ -15,7 +15,12 @@ import type {
   ResolvedTheme,
   TextStyle,
 } from '@opendata-ai/openchart-core';
-import { abbreviateNumber, formatDate, formatNumber } from '@opendata-ai/openchart-core';
+import {
+  abbreviateNumber,
+  buildD3Formatter,
+  formatDate,
+  formatNumber,
+} from '@opendata-ai/openchart-core';
 import type { ScaleBand } from 'd3-scale';
 import type {
   D3CategoricalScale,
@@ -147,7 +152,10 @@ 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) {
+      const fmt = buildD3Formatter(formatStr);
+      if (fmt) return fmt(num);
+    }
     // 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) {