@opendata-ai/openchart-engine 8.0.0-rc.12 → 8.0.0-rc.3

package/src/endpoint-labels/format.ts

@@ -0,0 +1,60 @@
+/**
+ * Shared value-formatting helpers for the endpoint-labels predictor and
+ * compute pass. Keeping the format-string path in one place guarantees
+ * predicted column width matches the eventual rendered text.
+ */
+
+import type { EndpointLabelContent, NumberFormatter } from '@opendata-ai/openchart-core';
+import { defaultNumberFormatter } from '@opendata-ai/openchart-core';
+
+const defaultFmt = defaultNumberFormatter();
+
+/**
+ * Format a value for an endpoint label. When a pre-built formatter is
+ * supplied (resolved from the spec's format/encoding), it is used directly.
+ * Otherwise falls back to the smart default (compact notation with
+ * magnitude-aware units).
+ */
+export function formatEndpointValue(
+  value: number | string | null,
+  formatter?: NumberFormatter | null,
+): string {
+  if (value == null) return '';
+  if (typeof value === 'string') return value;
+  if (formatter) return formatter(value);
+  return defaultFmt(value);
+}
+
+/**
+ * Compose the single-line text an endpoint entry renders when the spec sets
+ * `endpointLabels.content`. `'label value'` joins the series name and its
+ * formatted value on one line, which is the slope-chart convention. Returns
+ * the series name alone when the value is empty so a missing value never
+ * leaves a trailing space.
+ */
+export function composeEndpointText(
+  content: EndpointLabelContent,
+  label: string,
+  value: string,
+): string {
+  if (content === 'label') return label;
+  if (content === 'value') return value;
+  return value ? `${label} ${value}` : label;
+}
+
+/**
+ * Resolve the content mode for one column from the config's `content` field,
+ * which accepts either a single mode for both columns or a per-side object.
+ * Returns undefined when unset (the classic name-plus-value-below layout).
+ */
+export function resolveEndpointContent(
+  content:
+    | EndpointLabelContent
+    | { leading?: EndpointLabelContent; trailing?: EndpointLabelContent }
+    | undefined,
+  side: 'leading' | 'trailing',
+): EndpointLabelContent | undefined {
+  if (content == null) return undefined;
+  if (typeof content === 'string') return content;
+  return content[side];
+}

package/src/endpoint-labels/predict.ts

@@ -0,0 +1,139 @@
+/**
+ * Width-only predictor for the endpoint labels column.
+ *
+ * `computeDimensions` runs BEFORE marks are computed, so it can't read
+ * `mark.dataPoints[-1].y` to lay out the column. But it still needs to reserve
+ * the right margin so marks render inside the data area instead of underneath
+ * the column.
+ *
+ * Single-pass design: this predictor returns ONLY the column's width. The full
+ * entry positions are computed exactly once, in `computeEndpointLabels`, after
+ * dimensions settle. Both call sites use the same wrapping math (font size,
+ * weight, max width) so the predicted width matches the eventual layout.
+ */
+
+import type { ResolvedTheme } from '@opendata-ai/openchart-core';
+import { estimateTextWidth, wrapText } from '@opendata-ai/openchart-core';
+
+import type { NormalizedChartSpec } from '../compiler/types';
+import { resolveFieldFormatter } from '../format/field-format';
+import { endpointLabelsExplicitlyOn } from '../legend/suppression';
+import {
+  ENDPOINT_GAP,
+  ENDPOINT_LABEL_FONT_SIZE,
+  ENDPOINT_LABEL_FONT_WEIGHT,
+  ENDPOINT_SWATCH_SIZE,
+  ENDPOINT_VALUE_FONT_SIZE,
+  ENDPOINT_VALUE_FONT_WEIGHT,
+  ENDPOINT_WRAP_WIDTH_DEFAULT,
+} from './constants';
+import { composeEndpointText, formatEndpointValue, resolveEndpointContent } from './format';
+
+/**
+ * Predict the pixel width the endpoint-labels column will need, including
+ * swatch + label + value + padding. Returns 0 when the column would be empty
+ * (single series, opt-out, non-line/area, etc.).
+ *
+ * Does NOT do collision sweep or full layout. Does the same `wrapText` math
+ * as `computeEndpointLabels` so the two stay aligned by construction.
+ */
+export function predictEndpointLabelsWidth(
+  spec: NormalizedChartSpec,
+  _theme: ResolvedTheme,
+): number {
+  if (spec.endpointLabels === false) return 0;
+  if (spec.markType !== 'line' && spec.markType !== 'area') return 0;
+  const colorEnc = spec.encoding.color;
+  if (!colorEnc) return 0;
+  if ('condition' in colorEnc) return 0;
+  if (!('field' in colorEnc)) return 0;
+  if (colorEnc.type === 'quantitative') return 0;
+
+  // Distinct series count.
+  const colorField = colorEnc.field;
+  if (!colorField) return 0;
+  const seriesNames = new Set<string>();
+  for (const row of spec.data) {
+    seriesNames.add(String(row[colorField]));
+  }
+  if (seriesNames.size < 2) return 0;
+
+  // When the user passed `endpointLabels: false`, predict 0. (Already handled above
+  // for the bare boolean; also handle the object form `{ show: false }`.)
+  if (typeof spec.endpointLabels === 'object' && spec.endpointLabels?.show === false) return 0;
+
+  // Series-count cutoff: above maxSeries (default 8), skip endpoint labels
+  // unless the user explicitly enabled them. Uses the same explicit-on logic
+  // as suppression.ts to keep predict and render decisions aligned.
+  const maxSeries =
+    (typeof spec.endpointLabels === 'object' && spec.endpointLabels?.maxSeries) || 8;
+  if (!endpointLabelsExplicitlyOn(spec) && seriesNames.size > maxSeries) return 0;
+
+  const config = typeof spec.endpointLabels === 'object' ? spec.endpointLabels : undefined;
+  const wrapWidth = config?.width ?? ENDPOINT_WRAP_WIDTH_DEFAULT;
+
+  // Estimate the formatted value from the spec's data + format. We don't know
+  // which row is "last" without computing scales/marks, so we sample the
+  // largest absolute value to bound the formatted width.
+  const yField = config?.valueField ?? spec.encoding.y?.field;
+  const surfaceFormat =
+    config?.format ??
+    ((spec.encoding.y?.axis as Record<string, unknown> | undefined)?.format as string | undefined);
+  let sample = '';
+  if (yField) {
+    const values = spec.data.map((r) => r[yField]);
+    let maxAbs = 0;
+    for (const v of values) {
+      const n = Number(v);
+      if (Number.isFinite(n) && Math.abs(n) > maxAbs) maxAbs = Math.abs(n);
+    }
+    const formatter = resolveFieldFormatter({
+      surfaceFormat,
+      channelFormat: spec.encoding.y?.format,
+      values,
+    });
+    sample = formatEndpointValue(maxAbs, formatter);
+  }
+
+  // Text-column width for one side, using the same composition + wrapping
+  // math as compute.ts. Default (no content mode): widest wrapped series name
+  // vs. the sampled value on its own second line. Content mode: the composed
+  // single-line text in the label font.
+  const sideTextWidth = (side: 'leading' | 'trailing'): number => {
+    const content = resolveEndpointContent(config?.content, side);
+    let maxWidth = 0;
+    for (const name of seriesNames) {
+      const text = content ? composeEndpointText(content, name, sample) : name;
+      const lines = wrapText(text, ENDPOINT_LABEL_FONT_SIZE, ENDPOINT_LABEL_FONT_WEIGHT, wrapWidth);
+      for (const line of lines) {
+        const w = estimateTextWidth(line, ENDPOINT_LABEL_FONT_SIZE, ENDPOINT_LABEL_FONT_WEIGHT);
+        if (w > maxWidth) maxWidth = w;
+      }
+    }
+    if (!content && sample) {
+      const w = estimateTextWidth(sample, ENDPOINT_VALUE_FONT_SIZE, ENDPOINT_VALUE_FONT_WEIGHT);
+      if (w > maxWidth) maxWidth = w;
+    }
+    return maxWidth;
+  };
+
+  // Both columns share one reserved width (dimensions.ts mirrors the right
+  // reservation onto the left in `ends: 'both'` mode), so take the max of
+  // the sides in play.
+  let textColumn = sideTextWidth('trailing');
+  if (config?.ends === 'both') {
+    textColumn = Math.max(textColumn, sideTextWidth('leading'));
+  }
+
+  // Column = swatch + gap + text column + small trailing pad.
+  return ENDPOINT_SWATCH_SIZE + ENDPOINT_GAP + textColumn + 4;
+}
+
+/**
+ * Returns true when the spec requests both-ends endpoint labels.
+ * Used by `computeDimensions` to also reserve left margin space.
+ */
+export function isEndsBoth(spec: NormalizedChartSpec): boolean {
+  const ep = spec.endpointLabels;
+  return typeof ep === 'object' && ep != null && ep.ends === 'both';
+}

package/src/format/__tests__/field-format.test.ts

@@ -0,0 +1,164 @@
+import { describe, expect, it } from 'vitest';
+import { resolveFieldFormatter } from '../field-format';
+
+describe('resolveFieldFormatter', () => {
+  describe('precedence', () => {
+    it('surfaceFormat wins over channelFormat', () => {
+      const fmt = resolveFieldFormatter({
+        surfaceFormat: '.0%',
+        channelFormat: ',.0f',
+        values: [0.5, 0.75, 1.0],
+      });
+      expect(fmt(0.5)).toBe('50%');
+    });
+
+    it('channelFormat is used when surfaceFormat is absent', () => {
+      const fmt = resolveFieldFormatter({
+        channelFormat: '.0%',
+        values: [0.5, 0.75, 1.0],
+      });
+      expect(fmt(0.5)).toBe('50%');
+    });
+
+    it('falls back to default when both formats are absent', () => {
+      const fmt = resolveFieldFormatter({
+        values: [1000, 2000, 3000],
+      });
+      const result = fmt(2000);
+      expect(result).toBe('2k');
+    });
+
+    it('treats empty string as unset', () => {
+      const fmt = resolveFieldFormatter({
+        surfaceFormat: '',
+        channelFormat: '',
+        values: [10000, 20000],
+      });
+      expect(fmt(10000)).toBe('10k');
+    });
+  });
+
+  describe('semantic keywords', () => {
+    it('percent keyword formats as percentage', () => {
+      const fmt = resolveFieldFormatter({
+        surfaceFormat: 'percent',
+        values: [0.25, 0.5, 0.75],
+      });
+      expect(fmt(0.5)).toBe('50%');
+    });
+
+    it('currency keyword formats with $', () => {
+      const fmt = resolveFieldFormatter({
+        surfaceFormat: 'currency',
+        values: [100, 200, 300],
+      });
+      expect(fmt(200)).toContain('$');
+    });
+
+    it('ordinal keyword formats with suffix', () => {
+      const fmt = resolveFieldFormatter({
+        surfaceFormat: 'ordinal',
+        values: [1, 2, 3],
+      });
+      expect(fmt(1)).toBe('1st');
+      expect(fmt(2)).toBe('2nd');
+      expect(fmt(3)).toBe('3rd');
+    });
+  });
+
+  describe('years guard', () => {
+    it('renders year-like values as bare integers, not compact or comma-grouped', () => {
+      const fmt = resolveFieldFormatter({ values: [1990, 2007, 2024] });
+      expect(fmt(2024)).toBe('2024');
+      expect(fmt(1990)).toBe('1990');
+    });
+
+    it('activates at exact boundaries [1500, 2500]', () => {
+      const fmt = resolveFieldFormatter({ values: [1500, 2500] });
+      expect(fmt(1500)).toBe('1500');
+      expect(fmt(2500)).toBe('2500');
+    });
+
+    it('deactivates when any value falls below 1500', () => {
+      const fmt = resolveFieldFormatter({ values: [1499, 2400] });
+      expect(fmt(1499)).toBe('1.5k');
+    });
+
+    it('deactivates when any value exceeds 2500', () => {
+      const fmt = resolveFieldFormatter({ values: [1600, 2501] });
+      expect(fmt(2501)).toBe('2.5k');
+    });
+
+    it('deactivates for non-integer values', () => {
+      const fmt = resolveFieldFormatter({ values: [2020.5, 2024.5] });
+      expect(fmt(2024.5)).toBe('2k');
+    });
+
+    it('deactivates when mixed with large magnitudes', () => {
+      const fmt = resolveFieldFormatter({ values: [1990, 2024, 50000] });
+      expect(fmt(50000)).toBe('50k');
+    });
+
+    it('deactivates for negative values', () => {
+      const fmtNeg = resolveFieldFormatter({ values: [-2000, 2000] });
+      expect(fmtNeg(2000)).toBe('2k');
+    });
+
+    it('deactivates when range includes zero', () => {
+      const fmtZero = resolveFieldFormatter({ values: [0, 2024] });
+      expect(fmtZero(2024)).toBe('2k');
+    });
+
+    it('explicit format overrides guard: comma-grouped', () => {
+      const fmt = resolveFieldFormatter({
+        surfaceFormat: ',d',
+        values: [1990, 2024],
+      });
+      expect(fmt(2024)).toBe('2,024');
+    });
+
+    it('explicit format overrides guard: SI prefix', () => {
+      const fmt = resolveFieldFormatter({
+        surfaceFormat: '~s',
+        values: [1990, 2024],
+      });
+      expect(fmt(2024)).toContain('k');
+    });
+
+    it('table surface still applies guard (no comma-grouping)', () => {
+      const fmt = resolveFieldFormatter({
+        values: [1990, 2024],
+        surface: 'table',
+      });
+      expect(fmt(2024)).toBe('2024');
+    });
+  });
+
+  describe('step threading', () => {
+    it('step is applied to the context', () => {
+      const fmt = resolveFieldFormatter({
+        values: [0, 5000, 10000, 15000, 20000],
+        step: 5000,
+      });
+      expect(fmt(15000)).toBe('15k');
+    });
+  });
+
+  describe('chart vs table surface', () => {
+    it('chart surface gets compact formatting', () => {
+      const fmt = resolveFieldFormatter({
+        values: [1000, 2000, 3000],
+        surface: 'chart',
+      });
+      expect(fmt(2000)).toBe('2k');
+    });
+
+    it('table surface gets full precision', () => {
+      const fmt = resolveFieldFormatter({
+        values: [1000, 2000, 3000],
+        surface: 'table',
+      });
+      expect(fmt(2000)).toBe('2,000');
+    });
+  });
+});

package/src/format/field-format.ts

@@ -0,0 +1,27 @@
+import type { FieldFormatContext, NumberFormatter } from '@opendata-ai/openchart-core';
+import {
+  computeFieldFormatContext,
+  defaultNumberFormatter,
+  resolveNumberFormatter,
+} from '@opendata-ai/openchart-core';
+
+export interface FieldFormatOptions {
+  surfaceFormat?: string;
+  channelFormat?: string;
+  values?: Iterable<unknown>;
+  context?: FieldFormatContext;
+  surface?: 'chart' | 'table';
+  step?: number;
+}
+
+export function resolveFieldFormatter(opts: FieldFormatOptions): NumberFormatter {
+  const surfFmt = opts.surfaceFormat || undefined;
+  const chanFmt = opts.channelFormat || undefined;
+  const ctx: FieldFormatContext = opts.context
+    ? { ...opts.context }
+    : computeFieldFormatContext(opts.values ?? [], opts.surface);
+  if (opts.step != null) ctx.step = opts.step;
+  if (opts.surface) ctx.surface = opts.surface;
+  const fmt = resolveNumberFormatter(surfFmt ?? chanFmt, ctx);
+  return fmt ?? defaultNumberFormatter(ctx);
+}