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

package/src/endpoint-labels/__tests__/compute.test.ts

@@ -323,9 +323,17 @@ describe('computeEndpointLabels', () => {
   });
 
   it('handles area marks (overlap, not stacked)', () => {
+    // v8: area stacks by default, and stacked areas suppress the endpoint
+    // column in favor of the traditional legend. Stamp stack: null to
+    // exercise the overlap path this test targets.
     const spec = makeSpec({
       markType: 'area',
       markDef: { type: 'area' },
+      encoding: {
+        x: { field: 'date', type: 'temporal' },
+        y: { field: 'value', type: 'quantitative', stack: null },
+        color: { field: 'country', type: 'nominal' },
+      },
     });
     const marks: Mark[] = [makeAreaMark('US', 100, 40), makeAreaMark('UK', 200, 35, '#cc6633')];
     const layout = computeEndpointLabels(spec, marks, theme, chartArea);
@@ -338,9 +346,16 @@ describe('computeEndpointLabels', () => {
     // derived LineMark per series (see linesFromAreas in
     // packages/engine/src/charts/line/index.ts). Without dedupe, each series
     // produces two endpoint entries.
+    // v8: stamp stack: null so this overlap-mode fixture still shows the
+    // endpoint column (stacked areas suppress it in favor of the legend).
     const spec = makeSpec({
       markType: 'area',
       markDef: { type: 'area' },
+      encoding: {
+        x: { field: 'date', type: 'temporal' },
+        y: { field: 'value', type: 'quantitative', stack: null },
+        color: { field: 'country', type: 'nominal' },
+      },
     });
     const lineColor = '#3366cc';
     const areaColor = '#ddee99'; // fake gradient-derived color, distinct from the line stroke
@@ -420,9 +435,16 @@ describe('computeEndpointLabels', () => {
   it('dedupe prefers line mark even when area appears later in the marks array', () => {
     // Defect-1 regression: area marks listed AFTER line marks should not
     // overwrite the line's canonical stroke color in the endpoint entry.
+    // v8: stamp stack: null so this overlap-mode fixture still shows the
+    // endpoint column (stacked areas suppress it in favor of the legend).
     const spec = makeSpec({
       markType: 'area',
       markDef: { type: 'area' },
+      encoding: {
+        x: { field: 'date', type: 'temporal' },
+        y: { field: 'value', type: 'quantitative', stack: null },
+        color: { field: 'country', type: 'nominal' },
+      },
     });
     const lineColor = '#3366cc';
     const areaColor = '#ddee99';
@@ -496,4 +518,70 @@ describe('computeEndpointLabels', () => {
       expect(entry.marker!.x).toBe(chartArea.x - ENDPOINT_MARKER_RADIUS);
     }
   });
+
+  it("content: 'label value' joins name and value on one line and drops the value line", () => {
+    const spec = makeSpec({ endpointLabels: { content: 'label value' } });
+    const marks: Mark[] = [makeLineMark('US', 100, 40), makeLineMark('UK', 200, 35, '#cc6633')];
+    const layout = computeEndpointLabels(spec, marks, theme, chartArea);
+
+    const us = layout.entries.find((e) => e.seriesKey === 'US');
+    expect(us!.labelLines[0]).toBe('US 40');
+    expect(us!.value).toBe('');
+  });
+
+  it("content: 'value' renders the formatted value alone", () => {
+    const spec = makeSpec({ endpointLabels: { content: 'value' } });
+    const marks: Mark[] = [makeLineMark('US', 100, 40), makeLineMark('UK', 200, 35, '#cc6633')];
+    const layout = computeEndpointLabels(spec, marks, theme, chartArea);
+
+    const us = layout.entries.find((e) => e.seriesKey === 'US');
+    expect(us!.labelLines).toEqual(['40']);
+    expect(us!.value).toBe('');
+  });
+
+  it("content: 'label' renders the series name alone", () => {
+    const spec = makeSpec({ endpointLabels: { content: 'label' } });
+    const marks: Mark[] = [makeLineMark('US', 100, 40), makeLineMark('UK', 200, 35, '#cc6633')];
+    const layout = computeEndpointLabels(spec, marks, theme, chartArea);
+
+    const us = layout.entries.find((e) => e.seriesKey === 'US');
+    expect(us!.labelLines).toEqual(['US']);
+    expect(us!.value).toBe('');
+  });
+
+  it('per-side content object resolves leading and trailing independently', () => {
+    const spec = makeSpec({
+      endpointLabels: {
+        ends: 'both',
+        content: { leading: 'label value', trailing: 'value' },
+      },
+    });
+    const marks: Mark[] = [makeLineMark('US', 100, 40), makeLineMark('UK', 200, 35, '#cc6633')];
+    const layout = computeEndpointLabels(spec, marks, theme, chartArea);
+
+    // Leading: first data point value (value - 5) joined with the name.
+    const usLeading = layout.leading!.find((e) => e.seriesKey === 'US');
+    expect(usLeading!.labelLines[0]).toBe('US 35');
+    // Trailing: last value alone.
+    const usTrailing = layout.entries.find((e) => e.seriesKey === 'US');
+    expect(usTrailing!.labelLines).toEqual(['40']);
+  });
+
+  it('keeps the column at compact breakpoints when endpoint labels are explicitly on', () => {
+    // Slope/bump recipes carry their values on the labels: explicit user
+    // config must survive the compact strategy strip (labelMode: 'none').
+    const spec = makeSpec({ endpointLabels: { ends: 'both', content: 'label value' } });
+    const marks: Mark[] = [makeLineMark('US', 100, 40), makeLineMark('UK', 200, 35, '#cc6633')];
+    const layout = computeEndpointLabels(spec, marks, theme, chartArea, {
+      labelMode: 'none',
+      legendPosition: 'top',
+      annotationPosition: 'tooltip-only',
+      axisLabelDensity: 'minimal',
+      chromeMode: 'full',
+      legendMaxHeight: -1,
+    });
+
+    expect(layout.entries).toHaveLength(2);
+    expect(layout.leading).toHaveLength(2);
+  });
 });

package/src/endpoint-labels/compute.ts

@@ -30,7 +30,12 @@ import type {
 import { estimateTextWidth, wrapText } from '@opendata-ai/openchart-core';
 
 import type { NormalizedChartSpec } from '../compiler/types';
-import { countColorSeries, resolveSuppression } from '../legend/suppression';
+import { resolveFieldFormatter } from '../format/field-format';
+import {
+  countColorSeries,
+  endpointLabelsExplicitlyOn,
+  resolveSuppression,
+} from '../legend/suppression';
 import {
   ENDPOINT_COLUMN_GAP,
   ENDPOINT_ENTRY_GAP,
@@ -47,7 +52,7 @@ import {
   ENDPOINT_VALUE_GAP,
   ENDPOINT_WRAP_WIDTH_DEFAULT,
 } from './constants';
-import { formatEndpointValue } from './format';
+import { composeEndpointText, formatEndpointValue, resolveEndpointContent } from './format';
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -251,15 +256,20 @@ export function computeEndpointLabels(
   endpointLabelsDemoted?: boolean,
 ): EndpointLabelsLayout {
   // Compact strategy: drop the column entirely. The traditional legend takes
-  // over series identification at the compact breakpoint.
-  if (strategy?.labelMode === 'none') return emptyLayout(theme);
+  // over series identification at the compact breakpoint. Explicit user
+  // opt-in overrides the strip: slope/bump recipes are unreadable without
+  // their labels, so an author who wrote endpointLabels config keeps it.
+  if (strategy?.labelMode === 'none' && !endpointLabelsExplicitlyOn(spec)) {
+    return emptyLayout(theme);
+  }
 
   const highlight = spec.highlight ?? [];
   const highlightActive = highlight.length > 0;
   const seriesCount = countColorSeries(spec);
   const sup = resolveSuppression(spec, {
     seriesCount,
-    // The 'none' branch above returned; by here labelMode is not 'none'.
+    // The 'none' branch above returned unless the user explicitly opted in,
+    // in which case resolveSuppression's explicit-on override applies anyway.
     labelsHiddenByStrategy: false,
     labelsDensityNone: spec.labels.density === 'none',
     endpointLabelsDemoted,
@@ -291,13 +301,20 @@ export function computeEndpointLabels(
   const config = typeof spec.endpointLabels === 'object' ? spec.endpointLabels : undefined;
   const wrapWidth = config?.width ?? ENDPOINT_WRAP_WIDTH_DEFAULT;
   const valueField = config?.valueField ?? spec.encoding.y?.field;
-  const formatString =
+  const surfaceFormat =
     config?.format ??
     ((spec.encoding.y?.axis as Record<string, unknown> | undefined)?.format as string | undefined);
+  const endpointFormatter = resolveFieldFormatter({
+    surfaceFormat,
+    channelFormat: spec.encoding.y?.format,
+    values: valueField ? spec.data.map((r) => r[valueField]) : [],
+  });
   const showMarker = config?.showMarker !== false;
   const markerRadius = config?.markerStyle?.radius ?? ENDPOINT_MARKER_RADIUS;
   const markerStrokeWidth = config?.markerStyle?.strokeWidth ?? ENDPOINT_MARKER_STROKE_WIDTH;
   const markerFill = config?.markerStyle?.fill ?? theme.colors.background;
+  const trailingContent = resolveEndpointContent(config?.content, 'trailing');
+  const leadingContent = resolveEndpointContent(config?.content, 'leading');
 
   // Resolve the styles once.
   const labelStyle: TextStyle = {
@@ -340,14 +357,21 @@ export function computeEndpointLabels(
     const last = lastDataPoint(mark);
     if (!last) continue;
 
+    const rawValue = readValue(mark, valueField);
+    const formatted = formatEndpointValue(rawValue, endpointFormatter);
+
+    // Content composition: when `content` is set, the composed text becomes
+    // the label lines and the second-line value is dropped.
+    const labelText = trailingContent
+      ? composeEndpointText(trailingContent, seriesKey, formatted)
+      : seriesKey;
+    const value = trailingContent ? '' : formatted;
     const labelLines = wrapText(
-      seriesKey,
+      labelText,
       ENDPOINT_LABEL_FONT_SIZE,
       ENDPOINT_LABEL_FONT_WEIGHT,
       wrapWidth,
     );
-    const rawValue = readValue(mark, valueField);
-    const value = formatEndpointValue(rawValue, formatString);
 
     // Width of the widest line in this entry (used to size the column).
     let entryWidth = 0;
@@ -475,14 +499,18 @@ export function computeEndpointLabels(
       const first = firstDataPoint(mark);
       if (!first) continue;
 
+      const rawValue = readFirstValue(mark, valueField);
+      const formatted = formatEndpointValue(rawValue, endpointFormatter);
+      const labelText = leadingContent
+        ? composeEndpointText(leadingContent, seriesKey, formatted)
+        : seriesKey;
+      const value = leadingContent ? '' : formatted;
       const labelLines = wrapText(
-        seriesKey,
+        labelText,
         ENDPOINT_LABEL_FONT_SIZE,
         ENDPOINT_LABEL_FONT_WEIGHT,
         wrapWidth,
       );
-      const rawValue = readFirstValue(mark, valueField);
-      const value = formatEndpointValue(rawValue, formatString);
 
       let entryWidth = 0;
       for (const line of labelLines) {

package/src/endpoint-labels/format.ts

@@ -4,27 +4,57 @@
  * predicted column width matches the eventual rendered text.
  */
 
-import { format as d3Format } from 'd3-format';
+import type { EndpointLabelContent, NumberFormatter } from '@opendata-ai/openchart-core';
+import { defaultNumberFormatter } from '@opendata-ai/openchart-core';
+
+const defaultFmt = defaultNumberFormatter();
 
 /**
- * Format a value with a d3-format string, falling back to String() on
- * unknown specifiers. When no format string is supplied, applies a
- * sensible default: integers under 1000 render as-is, anything else gets
- * two decimals.
+ * 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,
-  formatString: string | undefined,
+  formatter?: NumberFormatter | null,
 ): string {
   if (value == null) return '';
   if (typeof value === 'string') return value;
-  if (formatString) {
-    try {
-      return d3Format(formatString)(value);
-    } catch {
-      return String(value);
-    }
-  }
-  if (Number.isInteger(value) && Math.abs(value) < 1000) return String(value);
-  return value.toFixed(2);
+  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

@@ -16,6 +16,7 @@ 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,
@@ -26,7 +27,7 @@ import {
   ENDPOINT_VALUE_FONT_WEIGHT,
   ENDPOINT_WRAP_WIDTH_DEFAULT,
 } from './constants';
-import { formatEndpointValue } from './format';
+import { composeEndpointText, formatEndpointValue, resolveEndpointContent } from './format';
 
 /**
  * Predict the pixel width the endpoint-labels column will need, including
@@ -45,10 +46,11 @@ export function predictEndpointLabelsWidth(
   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 = 'field' in colorEnc ? colorEnc.field : undefined;
+  const colorField = colorEnc.field;
   if (!colorField) return 0;
   const seriesNames = new Set<string>();
   for (const row of spec.data) {
@@ -70,48 +72,60 @@ export function predictEndpointLabelsWidth(
   const config = typeof spec.endpointLabels === 'object' ? spec.endpointLabels : undefined;
   const wrapWidth = config?.width ?? ENDPOINT_WRAP_WIDTH_DEFAULT;
 
-  // Wrap each series name and find the widest wrapped line.
-  let maxLabelWidth = 0;
-  for (const name of seriesNames) {
-    const lines = wrapText(name, 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 > maxLabelWidth) maxLabelWidth = w;
-    }
-  }
-
-  // Estimate value width 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.
+  // 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 yFormat =
+  const surfaceFormat =
     config?.format ??
     ((spec.encoding.y?.axis as Record<string, unknown> | undefined)?.format as string | undefined);
-  let valueWidth = 0;
+  let sample = '';
   if (yField) {
+    const values = spec.data.map((r) => r[yField]);
     let maxAbs = 0;
-    for (const row of spec.data) {
-      const v = Number(row[yField]);
-      if (Number.isFinite(v) && Math.abs(v) > maxAbs) maxAbs = Math.abs(v);
+    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;
+      }
     }
-    // When the user supplied a format string, run it through the same
-    // formatter compute.ts will use so width prediction matches reality.
-    // Without one, fall back to a magnitude-aware sample that bounds the
-    // expected unformatted value width (compute.ts uses toFixed(2) here,
-    // which is roughly the same character count as "1.5K"-style abbreviations
-    // for the upper end of each band).
-    let sample: string;
-    if (yFormat) {
-      sample = formatEndpointValue(maxAbs, yFormat);
-    } else if (maxAbs >= 1_000_000_000) sample = '1.5B';
-    else if (maxAbs >= 1_000_000) sample = '1.5M';
-    else if (maxAbs >= 1_000) sample = '1.5K';
-    else sample = String(Math.round(maxAbs * 100) / 100);
-    valueWidth = estimateTextWidth(sample, ENDPOINT_VALUE_FONT_SIZE, ENDPOINT_VALUE_FONT_WEIGHT);
+    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 + max(label width, value width) + small trailing pad.
-  const textColumn = Math.max(maxLabelWidth, valueWidth);
+  // Column = swatch + gap + text column + small trailing pad.
   return ENDPOINT_SWATCH_SIZE + ENDPOINT_GAP + textColumn + 4;
 }
 

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);
+}