@opendata-ai/openchart-engine 2.6.0 → 2.8.0

package/package.json

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

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

@@ -509,4 +509,82 @@ describe('compileGraph', () => {
     // Rotated labels should shrink the chart area height
     expect(layoutRotated.area.height).toBeLessThan(layoutNormal.area.height);
   });
+
+  it('hides legend when legend.show is false', () => {
+    const spec = {
+      ...lineSpec,
+      legend: { show: false },
+    };
+    const layout = compileChart(spec, { width: 600, height: 400 });
+    expect(layout.legend.entries).toHaveLength(0);
+    expect(layout.legend.bounds.width).toBe(0);
+    expect(layout.legend.bounds.height).toBe(0);
+  });
+
+  it('applies compact breakpoint overrides to chrome', () => {
+    const spec = {
+      ...lineSpec,
+      chrome: {
+        title: 'Full width title with extra context',
+        subtitle: 'Long subtitle with methodology details',
+      },
+      overrides: {
+        compact: {
+          chrome: {
+            title: 'Short title',
+            subtitle: 'Short sub',
+          },
+        },
+      },
+    };
+
+    // At compact width (< 400), overrides should apply
+    const compactLayout = compileChart(spec, { width: 350, height: 400 });
+    expect(compactLayout.chrome.title!.text).toBe('Short title');
+    expect(compactLayout.chrome.subtitle!.text).toBe('Short sub');
+
+    // At full width, base spec should apply
+    const fullLayout = compileChart(spec, { width: 800, height: 400 });
+    expect(fullLayout.chrome.title!.text).toBe('Full width title with extra context');
+    expect(fullLayout.chrome.subtitle!.text).toBe('Long subtitle with methodology details');
+  });
+
+  it('applies medium breakpoint overrides', () => {
+    const spec = {
+      ...lineSpec,
+      chrome: { title: 'Full title' },
+      overrides: {
+        medium: {
+          chrome: { title: 'Medium title' },
+        },
+      },
+    };
+
+    // At medium width (400-700), override should apply
+    const mediumLayout = compileChart(spec, { width: 500, height: 400 });
+    expect(mediumLayout.chrome.title!.text).toBe('Medium title');
+
+    // At full width, base spec should apply
+    const fullLayout = compileChart(spec, { width: 800, height: 400 });
+    expect(fullLayout.chrome.title!.text).toBe('Full title');
+  });
+
+  it('applies breakpoint override for legend show', () => {
+    const spec = {
+      ...lineSpec,
+      overrides: {
+        compact: {
+          legend: { show: false },
+        },
+      },
+    };
+
+    // At compact, legend hidden
+    const compactLayout = compileChart(spec, { width: 350, height: 400 });
+    expect(compactLayout.legend.entries).toHaveLength(0);
+
+    // At full, legend shown
+    const fullLayout = compileChart(spec, { width: 800, height: 400 });
+    expect(fullLayout.legend.entries.length).toBeGreaterThan(0);
+  });
 });

package/src/__tests__/legend.test.ts

@@ -82,6 +82,30 @@ describe('computeLegend', () => {
     expect(legend.bounds.height).toBeGreaterThan(0);
   });
 
+  it('returns empty entries when show is false', () => {
+    const specHidden: NormalizedChartSpec = {
+      ...specWithColor,
+      legend: { show: false },
+      hiddenSeries: [],
+      seriesStyles: {},
+    };
+    const legend = computeLegend(specHidden, fullStrategy, theme, chartArea);
+    expect(legend.entries).toHaveLength(0);
+    expect(legend.bounds.width).toBe(0);
+    expect(legend.bounds.height).toBe(0);
+  });
+
+  it('still shows legend when show is true', () => {
+    const specShown: NormalizedChartSpec = {
+      ...specWithColor,
+      legend: { show: true },
+      hiddenSeries: [],
+      seriesStyles: {},
+    };
+    const legend = computeLegend(specShown, fullStrategy, theme, chartArea);
+    expect(legend.entries).toHaveLength(3);
+  });
+
   it('uses correct swatch shape for chart type', () => {
     const lineLegend = computeLegend(specWithColor, fullStrategy, theme, chartArea);
     expect(lineLegend.entries[0].shape).toBe('line');

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/labels.ts

@@ -17,8 +17,11 @@ import type {
   RectMark,
   ResolvedLabel,
 } from '@opendata-ai/openchart-core';
-import { estimateTextWidth, resolveCollisions } from '@opendata-ai/openchart-core';
-import { format as d3Format } from 'd3-format';
+import {
+  buildD3Formatter,
+  estimateTextWidth,
+  resolveCollisions,
+} from '@opendata-ai/openchart-core';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -55,27 +58,7 @@ 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
-        }
-      }
-    }
-  }
+  const formatter = buildD3Formatter(labelFormat);
 
   for (const mark of targetMarks) {
     // Extract the display value from the aria label.

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/compile.ts

@@ -159,7 +159,58 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
     throw new Error('compileChart received a graph spec. Use compileGraph instead.');
   }
 
-  const chartSpec = normalized as NormalizedChartSpec;
+  let chartSpec = normalized as NormalizedChartSpec;
+
+  // Responsive strategy
+  const breakpoint = getBreakpoint(options.width);
+  const strategy = getLayoutStrategy(breakpoint);
+
+  // Apply breakpoint-conditional overrides from the original spec
+  const rawSpec = spec as Record<string, unknown>;
+  const overrides = rawSpec.overrides as
+    | Partial<
+        Record<
+          string,
+          { chrome?: unknown; labels?: unknown; legend?: unknown; annotations?: unknown }
+        >
+      >
+    | undefined;
+  if (overrides?.[breakpoint]) {
+    const bp = overrides[breakpoint]!;
+    if (bp.chrome) {
+      chartSpec = {
+        ...chartSpec,
+        chrome: {
+          ...chartSpec.chrome,
+          ...(bp.chrome as NormalizedChartSpec['chrome']),
+        },
+      };
+    }
+    if (bp.labels) {
+      chartSpec = {
+        ...chartSpec,
+        labels: {
+          ...chartSpec.labels,
+          ...(bp.labels as NormalizedChartSpec['labels']),
+        },
+      };
+    }
+    if (bp.legend) {
+      chartSpec = {
+        ...chartSpec,
+        legend: {
+          ...chartSpec.legend,
+          ...(bp.legend as NormalizedChartSpec['legend']),
+        },
+      };
+    }
+    if (bp.annotations) {
+      chartSpec = {
+        ...chartSpec,
+        annotations: bp.annotations as NormalizedChartSpec['annotations'],
+      };
+    }
+  }
 
   // Resolve theme: merge spec-level theme with options-level overrides
   const mergedThemeConfig = options.theme
@@ -170,10 +221,6 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
     theme = adaptTheme(theme);
   }
 
-  // Responsive strategy
-  const breakpoint = getBreakpoint(options.width);
-  const strategy = getLayoutStrategy(breakpoint);
-
   // Compute legend first (needs to reserve space)
   const preliminaryArea: Rect = {
     x: 0,

package/src/layout/axes.ts

@@ -15,8 +15,12 @@ import type {
   ResolvedTheme,
   TextStyle,
 } from '@opendata-ai/openchart-core';
-import { abbreviateNumber, formatDate, formatNumber } from '@opendata-ai/openchart-core';
-import { format as d3Format } from 'd3-format';
+import {
+  abbreviateNumber,
+  buildD3Formatter,
+  formatDate,
+  formatNumber,
+} from '@opendata-ai/openchart-core';
 import type { ScaleBand } from 'd3-scale';
 import type {
   D3CategoricalScale,
@@ -149,19 +153,8 @@ function formatTickLabel(value: unknown, resolvedScale: ResolvedScale): string {
   if (resolvedScale.type === 'linear' || resolvedScale.type === 'log') {
     const num = value as number;
     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
-          }
-        }
-      }
+      const fmt = buildD3Formatter(formatStr);
+      if (fmt) return fmt(num);
     }
     // Abbreviate large numbers for axis labels
     if (Math.abs(num) >= 1000) return abbreviateNumber(num);

package/src/legend/compute.ts

@@ -87,6 +87,25 @@ export function computeLegend(
   theme: ResolvedTheme,
   chartArea: Rect,
 ): LegendLayout {
+  // Legend explicitly hidden via show: false
+  if (spec.legend?.show === false) {
+    return {
+      position: 'top',
+      entries: [],
+      bounds: { x: 0, y: 0, width: 0, height: 0 },
+      labelStyle: {
+        fontFamily: theme.fonts.family,
+        fontSize: theme.fonts.sizes.small,
+        fontWeight: theme.fonts.weights.normal,
+        fill: theme.colors.text,
+        lineHeight: 1.3,
+      },
+      swatchSize: SWATCH_SIZE,
+      swatchGap: SWATCH_GAP,
+      entryGap: ENTRY_GAP,
+    };
+  }
+
   const entries = extractColorEntries(spec, theme);
 
   const labelStyle: TextStyle = {