@opendata-ai/openchart-engine 8.0.0-rc.2 → 8.0.0-rc.20

package/src/endpoint-labels/format.ts

@@ -1,60 +0,0 @@
-/**
- * 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

@@ -1,139 +0,0 @@
-/**
- * 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

@@ -1,164 +0,0 @@
-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

@@ -1,27 +0,0 @@
-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);
-}