@opendata-ai/openchart-engine 6.19.3 → 6.21.0

package/src/charts/column/compute.ts

@@ -20,11 +20,12 @@ import type {
   Rect,
   RectMark,
 } from '@opendata-ai/openchart-core';
-import { abbreviateNumber, formatNumber, isGradientDef } from '@opendata-ai/openchart-core';
+import { isGradientDef } from '@opendata-ai/openchart-core';
 import type { ScaleBand, ScaleLinear } from 'd3-scale';
 import type { NormalizedChartSpec } from '../../compiler/types';
 import type { ResolvedScales } from '../../layout/scales';
 import { isConditionalValueDef, resolveConditionalValue } from '../../transforms/conditional';
+import { formatLabelValue } from '../_shared/format-label-value';
 import { getColor, getSequentialColor, groupByField } from '../utils';
 
 // ---------------------------------------------------------------------------
@@ -33,12 +34,6 @@ import { getColor, getSequentialColor, groupByField } from '../utils';
 
 const MIN_COLUMN_HEIGHT = 1;
 
-/** Format a column value for display (abbreviate large numbers). */
-function formatColumnValue(value: number): string {
-  if (Math.abs(value) >= 1000) return abbreviateNumber(value);
-  return formatNumber(value);
-}
-
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -199,7 +194,7 @@ function computeSimpleColumns(
     const y = value >= 0 ? yPos : baseline;
 
     const aria: MarkAria = {
-      label: `${category}: ${formatColumnValue(value)}`,
+      label: `${category}: ${formatLabelValue(value)}`,
     };
 
     marks.push({
@@ -250,7 +245,7 @@ function computeColoredColumns(
     const y = value >= 0 ? yPos : baseline;
 
     const aria: MarkAria = {
-      label: `${category}, ${groupKey}: ${formatColumnValue(value)}`,
+      label: `${category}, ${groupKey}: ${formatLabelValue(value)}`,
     };
 
     marks.push({
@@ -320,7 +315,7 @@ function computeGroupedColumns(
       const subX = bandX + groupIndex * (subBandWidth + gap);
 
       const aria: MarkAria = {
-        label: `${category}, ${groupKey}: ${formatColumnValue(value)}`,
+        label: `${category}, ${groupKey}: ${formatLabelValue(value)}`,
       };
 
       marks.push({
@@ -389,7 +384,7 @@ function computeStackedColumns(
       const columnHeight = Math.max(Math.abs(yBottom - yTop), MIN_COLUMN_HEIGHT);
 
       const aria: MarkAria = {
-        label: `${category}, ${groupKey}: ${formatColumnValue(rawValue)}`,
+        label: `${category}, ${groupKey}: ${formatLabelValue(rawValue)}`,
       };
 
       marks.push({

package/src/charts/column/labels.ts

@@ -18,23 +18,13 @@ import type {
   ResolvedLabel,
 } from '@opendata-ai/openchart-core';
 import {
-  abbreviateNumber,
   buildD3Formatter,
   estimateTextWidth,
-  formatNumber,
   getRepresentativeColor,
   resolveCollisions,
 } from '@opendata-ai/openchart-core';
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/** Format a column value for display (abbreviate large numbers). */
-function formatColumnValue(value: number): string {
-  if (Math.abs(value) >= 1000) return abbreviateNumber(value);
-  return formatNumber(value);
-}
+import { filterByDensity } from '../_shared/density-filter';
+import { formatLabelValue } from '../_shared/format-label-value';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -61,12 +51,7 @@ export function computeColumnLabels(
   labelPrefix?: string,
   valueField?: string,
 ): ResolvedLabel[] {
-  // 'none': no labels at all
-  if (density === 'none') return [];
-
-  // Filter marks for 'endpoints' density
-  const targetMarks =
-    density === 'endpoints' && marks.length > 1 ? [marks[0], marks[marks.length - 1]] : marks;
+  const targetMarks = filterByDensity(marks, density);
 
   const formatter = buildD3Formatter(labelFormat);
 
@@ -82,7 +67,7 @@ export function computeColumnLabels(
     if (formatter && Number.isFinite(rawNum)) {
       valuePart = formatter(rawNum);
     } else if (Number.isFinite(rawNum)) {
-      valuePart = formatColumnValue(rawNum);
+      valuePart = formatLabelValue(rawNum);
     } else {
       // Fallback: extract from aria label
       const ariaLabel = mark.aria.label;

package/src/charts/dot/labels.ts

@@ -18,23 +18,13 @@ import type {
   ResolvedLabel,
 } from '@opendata-ai/openchart-core';
 import {
-  abbreviateNumber,
   buildD3Formatter,
   estimateTextWidth,
-  formatNumber,
   getRepresentativeColor,
   resolveCollisions,
 } from '@opendata-ai/openchart-core';
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/** Format a dot value for display (abbreviate large numbers). */
-function formatDotValue(value: number): string {
-  if (Math.abs(value) >= 1000) return abbreviateNumber(value);
-  return formatNumber(value);
-}
+import { filterByDensity } from '../_shared/density-filter';
+import { formatLabelValue } from '../_shared/format-label-value';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -61,12 +51,7 @@ export function computeDotLabels(
   labelFormat?: string,
   valueField?: string,
 ): ResolvedLabel[] {
-  // 'none': no labels at all
-  if (density === 'none') return [];
-
-  // Filter marks for 'endpoints' density
-  const targetMarks =
-    density === 'endpoints' && marks.length > 1 ? [marks[0], marks[marks.length - 1]] : marks;
+  const targetMarks = filterByDensity(marks, density);
 
   const formatter = buildD3Formatter(labelFormat);
   const candidates: LabelCandidate[] = [];
@@ -81,7 +66,7 @@ export function computeDotLabels(
     if (formatter && Number.isFinite(rawNum)) {
       valuePart = formatter(rawNum);
     } else if (Number.isFinite(rawNum)) {
-      valuePart = formatDotValue(rawNum);
+      valuePart = formatLabelValue(rawNum);
     } else {
       // Fallback: extract from aria label
       const ariaLabel = mark.aria.label;

package/src/charts/pie/labels.ts

@@ -20,6 +20,7 @@ import type {
   ResolvedLabel,
 } from '@opendata-ai/openchart-core';
 import { estimateTextWidth, resolveCollisions } from '@opendata-ai/openchart-core';
+import { filterByDensity } from '../_shared/density-filter';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -48,16 +49,13 @@ export function computePieLabels(
 ): ResolvedLabel[] {
   if (marks.length === 0) return [];
 
-  // 'none': no labels at all
-  if (density === 'none') return [];
-
   // Get the pie center from the first mark's center property
+  // (read before filtering — 'endpoints' still needs the original center)
   const centerX = marks[0].center.x;
   const centerY = marks[0].center.y;
 
-  // Filter marks for 'endpoints' density
-  const targetMarks =
-    density === 'endpoints' && marks.length > 1 ? [marks[0], marks[marks.length - 1]] : marks;
+  const targetMarks = filterByDensity(marks, density);
+  if (targetMarks.length === 0) return [];
 
   const candidates: LabelCandidate[] = [];
   const targetMarkIndices: number[] = [];

package/src/charts/registry.ts

@@ -58,6 +58,12 @@ export function getChartRenderer(type: string): ChartRenderer | undefined {
 
 /**
  * Clear all registered renderers. Useful for testing.
+ *
+ * Note: the built-in renderers (line, bar, column, ...) register as a
+ * side-effect of importing `./builtin`. Once cleared, they do not come
+ * back on their own — subsequent `compileChart(...)` calls will return
+ * empty marks. Tests that call `clearRenderers()` should follow up with
+ * `registerBuiltinRenderers()` from `./builtin` to restore the defaults.
  */
 export function clearRenderers(): void {
   renderers.clear();

package/src/compile/__tests__/color-scale-range.test.ts

@@ -0,0 +1,79 @@
+import type { Encoding, ResolvedTheme } from '@opendata-ai/openchart-core';
+import { resolveTheme } from '@opendata-ai/openchart-core';
+import { scaleLinear, scaleOrdinal } from 'd3-scale';
+import { describe, expect, it } from 'vitest';
+import type { ResolvedScales } from '../../layout/scales';
+import { applyColorScaleRange } from '../color-scale-range';
+
+const theme: ResolvedTheme = resolveTheme();
+
+describe('applyColorScaleRange', () => {
+  it('is a no-op when no color scale is present', () => {
+    const scales: ResolvedScales = {};
+    const encoding: Encoding = {
+      x: { field: 'x', type: 'quantitative' },
+      y: { field: 'y', type: 'quantitative' },
+    };
+    expect(() => applyColorScaleRange(scales, encoding, theme)).not.toThrow();
+    expect(scales.color).toBeUndefined();
+  });
+
+  it('does not overwrite the range when the encoding declares an explicit palette', () => {
+    // computeScales has already applied the explicit palette to the scale.
+    // The helper must leave it untouched (not replace it with the theme palette).
+    const explicit = ['#111111', '#222222', '#333333'];
+    const ordinal = scaleOrdinal<string, string>().domain(['a', 'b', 'c']).range(explicit);
+    const scales: ResolvedScales = {
+      color: { scale: ordinal, type: 'ordinal', channel: 'color' },
+    };
+    const encoding: Encoding = {
+      x: { field: 'x', type: 'nominal' },
+      y: { field: 'y', type: 'quantitative' },
+      color: {
+        field: 'c',
+        type: 'nominal',
+        scale: { range: explicit },
+      },
+    };
+    applyColorScaleRange(scales, encoding, theme);
+    expect(ordinal.range()).toEqual(explicit);
+    expect(ordinal.range()).not.toEqual(theme.colors.categorical);
+  });
+
+  it('assigns the theme categorical palette when no range is set', () => {
+    const ordinal = scaleOrdinal<string, string>().domain(['a', 'b', 'c']);
+    const scales: ResolvedScales = {
+      color: { scale: ordinal, type: 'ordinal', channel: 'color' },
+    };
+    const encoding: Encoding = {
+      x: { field: 'x', type: 'nominal' },
+      y: { field: 'y', type: 'quantitative' },
+      color: { field: 'c', type: 'nominal' },
+    };
+    applyColorScaleRange(scales, encoding, theme);
+    expect(ordinal.range()).toEqual(theme.colors.categorical);
+  });
+
+  it('uses the first sequential palette endpoints for sequential color scales', () => {
+    const linear = scaleLinear<string, string>().domain([0, 100]);
+    const scales: ResolvedScales = {
+      color: {
+        scale: linear as unknown as ResolvedScales['color'] extends infer T
+          ? T extends { scale: infer S }
+            ? S
+            : never
+          : never,
+        type: 'sequential',
+        channel: 'color',
+      } as NonNullable<ResolvedScales['color']>,
+    };
+    const encoding: Encoding = {
+      x: { field: 'x', type: 'quantitative' },
+      y: { field: 'y', type: 'quantitative' },
+      color: { field: 'v', type: 'quantitative' },
+    };
+    applyColorScaleRange(scales, encoding, theme);
+    const firstSeq = Object.values(theme.colors.sequential)[0] ?? theme.colors.categorical;
+    expect(linear.range()).toEqual([firstSeq[0], firstSeq[firstSeq.length - 1]]);
+  });
+});

package/src/compile/__tests__/data-clip.test.ts

@@ -0,0 +1,59 @@
+import type { Encoding } from '@opendata-ai/openchart-core';
+import { describe, expect, it } from 'vitest';
+import { filterClippedDomains } from '../data-clip';
+
+describe('filterClippedDomains', () => {
+  const data = [
+    { x: -5, y: 10 },
+    { x: 10, y: 20 },
+    { x: 25, y: 80 },
+    { x: 50, y: 110 },
+    { x: 80, y: 200 },
+  ];
+
+  it('returns data unchanged when no channel declares scale.clip', () => {
+    const encoding: Encoding = {
+      x: { field: 'x', type: 'quantitative' },
+      y: { field: 'y', type: 'quantitative' },
+    };
+    const result = filterClippedDomains(data, encoding);
+    expect(result).toBe(data);
+    expect(result).toHaveLength(5);
+  });
+
+  it('filters rows outside the x-axis clipped domain', () => {
+    const encoding: Encoding = {
+      x: {
+        field: 'x',
+        type: 'quantitative',
+        scale: { domain: [0, 30], clip: true },
+      },
+      y: { field: 'y', type: 'quantitative' },
+    };
+    const result = filterClippedDomains(data, encoding);
+    expect(result).toEqual([
+      { x: 10, y: 20 },
+      { x: 25, y: 80 },
+    ]);
+  });
+
+  it('filters rows outside both x- and y-axis clipped domains', () => {
+    const encoding: Encoding = {
+      x: {
+        field: 'x',
+        type: 'quantitative',
+        scale: { domain: [0, 60], clip: true },
+      },
+      y: {
+        field: 'y',
+        type: 'quantitative',
+        scale: { domain: [0, 100], clip: true },
+      },
+    };
+    const result = filterClippedDomains(data, encoding);
+    expect(result).toEqual([
+      { x: 10, y: 20 },
+      { x: 25, y: 80 },
+    ]);
+  });
+});

package/src/compile/__tests__/watermark-obstacle.test.ts

@@ -0,0 +1,93 @@
+import type { AxisLayout, Rect, ResolvedChrome, ResolvedTheme } from '@opendata-ai/openchart-core';
+import { BRAND_RESERVE_WIDTH, resolveTheme } from '@opendata-ai/openchart-core';
+import { describe, expect, it } from 'vitest';
+import type { AxesResult } from '../../layout/axes';
+import type { LayoutDimensions } from '../../layout/dimensions';
+import { computeWatermarkObstacle } from '../watermark-obstacle';
+
+const theme: ResolvedTheme = resolveTheme();
+
+function makeDims(overrides: Partial<LayoutDimensions> = {}): LayoutDimensions {
+  const total: Rect = { x: 0, y: 0, width: 800, height: 500 };
+  const chartArea: Rect = { x: 60, y: 80, width: 700, height: 360 };
+  const chrome: ResolvedChrome = {
+    topHeight: 80,
+    bottomHeight: 40,
+  } as ResolvedChrome;
+  return {
+    total,
+    chartArea,
+    chrome,
+    margins: { top: 80, right: 40, bottom: 40, left: 60 },
+    theme,
+    ...overrides,
+  };
+}
+
+function makeAxis(label?: string): AxisLayout {
+  return {
+    ticks: [],
+    gridlines: [],
+    label,
+    tickLabelStyle: {
+      fontFamily: theme.fonts.family,
+      fontSize: 12,
+      fontWeight: 400,
+      fill: '#000',
+      lineHeight: 1.2,
+    },
+    start: { x: 0, y: 0 },
+    end: { x: 100, y: 0 },
+  };
+}
+
+describe('computeWatermarkObstacle', () => {
+  it('returns null when watermark is disabled', () => {
+    const dims = makeDims();
+    const axes: AxesResult = { x: makeAxis(), y: makeAxis() };
+    expect(computeWatermarkObstacle(dims, false, axes, theme)).toBeNull();
+  });
+
+  it('sits below the x-axis when no bottom chrome is present', () => {
+    const dims = makeDims();
+    const axes: AxesResult = { x: makeAxis('value'), y: makeAxis() };
+    const rect = computeWatermarkObstacle(dims, true, axes, theme);
+    expect(rect).not.toBeNull();
+    // Right-aligned: total.width - padding - BRAND_RESERVE_WIDTH
+    expect(rect!.x).toBe(dims.total.width - theme.spacing.padding - BRAND_RESERVE_WIDTH);
+    expect(rect!.width).toBe(BRAND_RESERVE_WIDTH);
+    expect(rect!.height).toBe(30);
+    // Watermark sits below chart area, offset by x-axis extent + chartToFooter
+    const expectedY = dims.chartArea.y + dims.chartArea.height + 48 + theme.spacing.chartToFooter;
+    expect(rect!.y).toBe(expectedY);
+  });
+
+  it('aligns with bottom chrome when a source element is present', () => {
+    const sourceY = 20;
+    const dims = makeDims({
+      chrome: {
+        topHeight: 80,
+        bottomHeight: 40,
+        source: {
+          text: 'Source: Test',
+          x: 10,
+          y: sourceY,
+          maxWidth: 500,
+          style: {
+            fontFamily: theme.fonts.family,
+            fontSize: 10,
+            fontWeight: 400,
+            fill: '#666',
+            lineHeight: 1.2,
+          },
+        },
+      } as ResolvedChrome,
+    });
+    const axes: AxesResult = { x: makeAxis(), y: makeAxis() };
+    const rect = computeWatermarkObstacle(dims, true, axes, theme);
+    expect(rect).not.toBeNull();
+    // With axis present but no label, extent is 26.
+    // Y is chartArea.y + chartArea.height + 26 + sourceY
+    expect(rect!.y).toBe(dims.chartArea.y + dims.chartArea.height + 26 + sourceY);
+  });
+});

package/src/compile/color-scale-range.ts

@@ -0,0 +1,38 @@
+/**
+ * Apply the theme palette as the color scale range when no explicit range was provided.
+ *
+ * Sequential scales take the first/last stops of the first sequential palette
+ * (or the categorical endpoints as a fallback). Categorical scales get the
+ * full categorical palette. A user-provided `encoding.color.scale.range`
+ * always wins.
+ */
+
+import type { Encoding, ResolvedTheme } from '@opendata-ai/openchart-core';
+import type { ScaleLinear, ScaleOrdinal } from 'd3-scale';
+import type { ResolvedScales } from '../layout/scales';
+
+/** Mutates `scales.color.scale.range` in place when no explicit palette was set. */
+export function applyColorScaleRange(
+  scales: ResolvedScales,
+  encoding: Encoding,
+  theme: ResolvedTheme,
+): void {
+  if (!scales.color) return;
+
+  const hasExplicitRange = !!(
+    encoding.color &&
+    'field' in encoding.color &&
+    (encoding.color.scale?.range as string[] | undefined)?.length
+  );
+  if (hasExplicitRange) return;
+
+  if (scales.color.type === 'sequential') {
+    const seqStops = Object.values(theme.colors.sequential)[0] ?? theme.colors.categorical;
+    (scales.color.scale as unknown as ScaleLinear<string, string>).range([
+      seqStops[0],
+      seqStops[seqStops.length - 1],
+    ]);
+  } else {
+    (scales.color.scale as ScaleOrdinal<string, string>).range(theme.colors.categorical);
+  }
+}

package/src/compile/data-clip.ts

@@ -0,0 +1,33 @@
+/**
+ * Data filter for clipped scale domains.
+ *
+ * When an x or y encoding declares `scale.clip: true` with a numeric
+ * [lo, hi] domain, rows whose field value falls outside that range are
+ * dropped before scales and marks are computed. Pure and side-effect free.
+ */
+
+import type { DataRow, Encoding } from '@opendata-ai/openchart-core';
+
+/**
+ * Return a new data array with rows outside any clipped scale domain removed.
+ *
+ * Only inspects the `x` and `y` channels. Non-numeric domains and channels
+ * without `scale.clip` are passed through unchanged.
+ */
+export function filterClippedDomains(data: DataRow[], encoding: Encoding): DataRow[] {
+  let result = data;
+  for (const channel of ['x', 'y'] as const) {
+    const enc = encoding[channel];
+    if (!enc?.scale?.clip || !enc.scale.domain) continue;
+    const domain = enc.scale.domain;
+    const field = enc.field;
+    if (Array.isArray(domain) && domain.length === 2 && typeof domain[0] === 'number') {
+      const [lo, hi] = domain as [number, number];
+      result = result.filter((row) => {
+        const v = Number(row[field]);
+        return Number.isFinite(v) && v >= lo && v <= hi;
+      });
+    }
+  }
+  return result;
+}

package/src/compile/watermark-obstacle.ts

@@ -0,0 +1,54 @@
+/**
+ * Compute the brand watermark obstacle rect.
+ *
+ * The watermark is right-aligned on the same baseline as the first bottom
+ * chrome element (source, byline, or footer), offset below the chart area
+ * by the x-axis extent (tick labels + axis title). Returns null when the
+ * watermark is disabled so callers can skip obstacle collection entirely.
+ */
+
+import type { Rect, ResolvedTheme } from '@opendata-ai/openchart-core';
+import { BRAND_RESERVE_WIDTH } from '@opendata-ai/openchart-core';
+import type { AxesResult } from '../layout/axes';
+import type { LayoutDimensions } from '../layout/dimensions';
+
+/** Height of the watermark element used for obstacle avoidance. */
+const WATERMARK_HEIGHT = 30;
+
+/** Vertical padding below the x-axis label when an axis title is present. */
+const X_AXIS_EXTENT_WITH_LABEL = 48;
+
+/** Vertical padding below the x-axis ticks when no axis title is present. */
+const X_AXIS_EXTENT_TICKS_ONLY = 26;
+
+/**
+ * Compute the rect occupied by the watermark, or null when it is disabled.
+ *
+ * @param dims - Layout dimensions (for total width and chrome positions).
+ * @param watermark - Whether the watermark is enabled for this chart.
+ * @param axes - Computed axes (the x-axis determines how far below the chart the watermark sits).
+ * @param theme - Resolved theme (padding + fallback spacing).
+ */
+export function computeWatermarkObstacle(
+  dims: LayoutDimensions,
+  watermark: boolean,
+  axes: AxesResult,
+  theme: ResolvedTheme,
+): Rect | null {
+  if (!watermark) return null;
+
+  const chartArea = dims.chartArea;
+  const brandPadding = theme.spacing.padding;
+  const brandX = dims.total.width - brandPadding - BRAND_RESERVE_WIDTH;
+  const xAxisExtent = axes.x?.label
+    ? X_AXIS_EXTENT_WITH_LABEL
+    : axes.x
+      ? X_AXIS_EXTENT_TICKS_ONLY
+      : 0;
+  const firstBottomChrome = dims.chrome.source ?? dims.chrome.byline ?? dims.chrome.footer;
+  const brandY = firstBottomChrome
+    ? chartArea.y + chartArea.height + xAxisExtent + firstBottomChrome.y
+    : chartArea.y + chartArea.height + xAxisExtent + theme.spacing.chartToFooter;
+
+  return { x: brandX, y: brandY, width: BRAND_RESERVE_WIDTH, height: WATERMARK_HEIGHT };
+}