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

package/src/annotations/thinning.ts

@@ -3,8 +3,9 @@
  * overlap to numbered dot markers with footnote text below the chart.
  *
  * Single deterministic pass: run collision resolution once at the full chart
- * area, then greedily place by priority. Annotations that overlap an
- * already-placed one get demoted. No iterative layout convergence.
+ * area, then greedily place by priority. A candidate is demoted when it either
+ * overlaps an already-placed label or escapes the plot area. No iterative
+ * layout convergence.
  */
 
 import type {
@@ -22,6 +23,17 @@ export interface ThinningResult {
   footnotes: AnnotationFootnote[];
 }
 
+/**
+ * Max share of the plot area inline annotation labels may collectively claim
+ * before further candidates demote to footnotes. Measured coverage for a
+ * 6-callout line chart runs ~5% at 860px and ~16% at 300px, so 10% leaves wide
+ * charts fully inline and demotes the crowded tail on narrow ones.
+ */
+const COVERAGE_BUDGET = 0.1;
+
+/** Gap enforced between inline labels; labels closer than this count as colliding. */
+const COLLISION_PADDING = 4;
+
 /**
  * Apply auto-thinning to resolved annotations. Text annotations that still
  * overlap after collision resolution are demoted to footnote markers.
@@ -37,11 +49,22 @@ export interface ThinningResult {
  *   minus any that were skipped by `computeAnnotations`).
  * @param specs - The full spec annotations array, index-aligned with `annotations`.
  *   Non-text specs are ignored; text specs provide `priority` and `responsive`.
+ * @param plotArea - The plot rect. Sizes the coverage budget: labels are charged
+ *   against the plot they crowd, so the same label costs a larger share of a
+ *   smaller plot. Omit to skip the budget test.
+ * @param containerBounds - The rect a label must fit inside to stay inline. This
+ *   is the whole chart, NOT the plot: annotations render outside the clip path and
+ *   legitimately sit in the margins (above a peak, below a trough), which is what
+ *   collision avoidance already assumes. Fencing them to the plot would demote
+ *   ordinary callouts. Only labels escaping the chart entirely are demoted.
+ *   Omit to skip the containment test.
  */
 export function thinAnnotations(
   annotations: ResolvedAnnotation[],
   specs: Annotation[],
   measure: AnnotationMeasureTextFn,
+  plotArea?: Rect,
+  containerBounds?: Rect,
 ): ThinningResult {
   if (annotations.length <= 1) {
     return { annotations, footnotes: [] };
@@ -49,11 +72,20 @@ export function thinAnnotations(
 
   // Build index pairs: (resolved, spec, original index).
   // Only text specs carry priority/responsive; non-text specs are ignored.
-  const entries = annotations.map((a, i) => ({
-    resolved: a,
-    spec: i < specs.length && specs[i].type === 'text' ? (specs[i] as TextAnnotation) : undefined,
-    index: i,
-  }));
+  //
+  // `annotations` is a filtered view of `specs` -- an annotation that resolves to
+  // nothing (position outside the domain) is dropped -- so index into `specs` by
+  // the stamped `specIndex`, never by position in `annotations`. Falling back to
+  // `i` keeps a hand-built layout (no specIndex) working as it did before.
+  const entries = annotations.map((a, i) => {
+    const specIndex = a.specIndex ?? i;
+    const spec = specs[specIndex];
+    return {
+      resolved: a,
+      spec: spec?.type === 'text' ? (spec as TextAnnotation) : undefined,
+      index: i,
+    };
+  });
 
   // Separate pinned (responsive: false) from candidates
   const pinned: typeof entries = [];
@@ -85,8 +117,26 @@ export function thinAnnotations(
     }
   }
 
-  // Greedily place candidates; demote overlapping ones to footnotes
+  // Greedily place candidates; demote overlapping ones to footnotes.
+  //
+  // Overlap and containment alone under-thin at narrow widths: collision
+  // resolution spreads labels apart and clamping pulls them back inside, so
+  // they neither collide nor escape the plot — they just crowd it. Layer a
+  // coverage budget on top: inline labels may claim at most COVERAGE_BUDGET of
+  // the plot area, and candidates that push past it demote. Coverage rises as
+  // the plot shrinks (a fixed label costs a larger share of a smaller plot),
+  // so this only bites at small sizes and leaves roomy charts untouched.
+  //
+  // Pinned labels are exempt: they are guaranteed placement, so charging them
+  // against the budget could exhaust it before any candidate is seen and evict
+  // labels that would otherwise fit. They still block via `placedBounds`.
   const footnotes: AnnotationFootnote[] = [];
+  const plotAreaSize = plotArea ? plotArea.width * plotArea.height : 0;
+  const coverageBudget = plotAreaSize * COVERAGE_BUDGET;
+  // Containment is checked against the chart, not the plot — see the param docs.
+  // Callers that pass no container fall back to the plot rect.
+  const containment = containerBounds ?? plotArea;
+  let usedArea = 0;
 
   for (const entry of candidates) {
     const bounds = entry.resolved.bounds ?? estimateLabelBounds(entry.resolved.label!, measure);
@@ -96,11 +146,20 @@ export function thinAnnotations(
       continue;
     }
 
+    const padded = {
+      x: bounds.x - COLLISION_PADDING,
+      y: bounds.y - COLLISION_PADDING,
+      width: bounds.width + COLLISION_PADDING * 2,
+      height: bounds.height + COLLISION_PADDING * 2,
+    };
     const overlaps = placedBounds.some(
-      (pb) => pb.width > 0 && pb.height > 0 && detectCollision(bounds, pb),
+      (pb) => pb.width > 0 && pb.height > 0 && detectCollision(padded, pb),
     );
 
-    if (overlaps) {
+    const candidateArea = bounds.width * bounds.height;
+    const overBudget = plotAreaSize > 0 && usedArea + candidateArea > coverageBudget;
+
+    if (overlaps || !fitsWithin(bounds, containment) || overBudget) {
       const footnoteIndex = footnotes.length + 1;
       footnotes.push({
         index: footnoteIndex,
@@ -109,8 +168,23 @@ export function thinAnnotations(
       entry.resolved.footnoteIndex = footnoteIndex;
     } else {
       placedBounds.push(bounds);
+      usedArea += candidateArea;
     }
   }
 
   return { annotations, footnotes };
 }
+
+/**
+ * Whether a label's bounds sit entirely inside the plot. No plot area means no
+ * containment constraint, so everything fits.
+ */
+function fitsWithin(bounds: Rect, plotArea: Rect | undefined): boolean {
+  if (!plotArea || plotArea.width <= 0 || plotArea.height <= 0) return true;
+  return (
+    bounds.x >= plotArea.x &&
+    bounds.y >= plotArea.y &&
+    bounds.x + bounds.width <= plotArea.x + plotArea.width &&
+    bounds.y + bounds.height <= plotArea.y + plotArea.height
+  );
+}

package/src/barlist/compile-barlist.ts

@@ -24,15 +24,14 @@ import type {
 } from '@opendata-ai/openchart-core';
 import {
   adaptTheme,
-  buildD3Formatter,
   computeChrome,
   estimateTextWidth,
-  formatNumber,
   resolveTheme,
 } from '@opendata-ai/openchart-core';
-
+import { emitSpecWarnings, expandSpecSugar } from '../compile/spec-sugar';
 import { resolveAnimation } from '../compiler/animation';
 import { compile as compileSpec } from '../compiler/index';
+import { resolveFieldFormatter } from '../format/field-format';
 import type { NormalizedBarListSpec } from './types';
 
 // ---------------------------------------------------------------------------
@@ -57,7 +56,15 @@ const BARLIST_COLORS = ['#06b6d4', '#34d399', '#fbbf24', '#f472b6', '#a78bfa'];
 // ---------------------------------------------------------------------------
 
 export function compileBarList(spec: unknown, options: CompileOptions): BarListLayout {
-  const { spec: normalized } = compileSpec(spec);
+  // Expand deprecated top-level sugar (valueFormat -> encoding.value.format)
+  // before validation, then validate + normalize via the shared pipeline.
+  const sugarWarnings: string[] = [];
+  const expandedSpec =
+    spec && typeof spec === 'object' && !Array.isArray(spec)
+      ? expandSpecSugar(spec as Record<string, unknown>, sugarWarnings)
+      : spec;
+  const { spec: normalized, warnings } = compileSpec(expandedSpec);
+  emitSpecWarnings([...sugarWarnings, ...warnings], options.onWarn);
 
   if (!('type' in normalized) || normalized.type !== 'barlist') {
     throw new Error(
@@ -158,8 +165,11 @@ export function compileBarList(spec: unknown, options: CompileOptions): BarListL
     return palette[idx % palette.length];
   }
 
-  // Value formatter
-  const formatter = buildD3Formatter(barlistSpec.valueFormat) ?? formatNumber;
+  // Value formatter: prefer encoding-level format (v8 canonical), fall back to deprecated valueFormat
+  const formatter = resolveFieldFormatter({
+    surfaceFormat: barlistSpec.encoding.value.format ?? barlistSpec.valueFormat,
+    values: validRows.map((r) => r[valueField]),
+  });
 
   // Compute label width: measure all labels and use a consistent width
   const measureText =

package/src/charts/_shared/format-label-value.ts

@@ -1,15 +1,16 @@
 /**
  * Shared numeric value formatter for data labels.
  *
- * Used by bar, column, and dot label computation to display a value:
- * abbreviated (K/M/B/T) for magnitudes >= 1000, otherwise the default
- * numeric format.
+ * Used by bar, column, and dot label computation to display a value
+ * with smart compact defaults (k/M/B/T).
  */
 
-import { abbreviateNumber, formatNumber } from '@opendata-ai/openchart-core';
+import type { FieldFormatContext } from '@opendata-ai/openchart-core';
+import { defaultNumberFormatter } from '@opendata-ai/openchart-core';
 
-/** Format a label value for display (abbreviate large numbers). */
-export function formatLabelValue(value: number): string {
-  if (Math.abs(value) >= 1000) return abbreviateNumber(value);
-  return formatNumber(value);
+const defaultFmt = defaultNumberFormatter();
+
+/** Format a label value for display (compact by default). */
+export function formatLabelValue(value: number, ctx?: FieldFormatContext): string {
+  return (ctx ? defaultNumberFormatter(ctx) : defaultFmt)(value);
 }

package/src/charts/bar/__tests__/compute.test.ts

@@ -1,4 +1,5 @@
 import type { LayoutStrategy, Rect } from '@opendata-ai/openchart-core';
+import { buildD3Formatter } from '@opendata-ai/openchart-core';
 import { describe, expect, it } from 'vitest';
 import type { NormalizedChartSpec } from '../../../compiler/types';
 import { computeScales } from '../../../layout/scales';
@@ -58,7 +59,9 @@ function makeGroupedBarSpec(): NormalizedChartSpec {
       { category: 'Q3', value: 70, region: 'West' },
     ],
     encoding: {
-      x: { field: 'value', type: 'quantitative' },
+      // Grouped is opt-out since v8 (stacked is now the default): stamp
+      // stack: null explicitly so this fixture stays grouped.
+      x: { field: 'value', type: 'quantitative', stack: null },
       y: { field: 'category', type: 'nominal' },
       color: { field: 'region', type: 'nominal' },
     },
@@ -214,7 +217,46 @@ describe('computeBarMarks', () => {
     });
   });
 
-  describe('grouped bars (default)', () => {
+  describe('stack: undefined (omitted) stacks by default (v8 VL-aligned default)', () => {
+    function makeDefaultStackBarSpec(): NormalizedChartSpec {
+      return {
+        markType: 'bar',
+        markDef: { type: 'bar' },
+        data: [
+          { category: 'Q1', value: 50, region: 'East' },
+          { category: 'Q1', value: 40, region: 'West' },
+          { category: 'Q2', value: 60, region: 'East' },
+          { category: 'Q2', value: 55, region: 'West' },
+        ],
+        encoding: {
+          x: { field: 'value', type: 'quantitative' },
+          y: { field: 'category', type: 'nominal' },
+          color: { field: 'region', type: 'nominal' },
+        },
+        chrome: {},
+        annotations: [],
+        responsive: true,
+        theme: {},
+        darkMode: 'off',
+        labels: { density: 'auto', format: '' },
+      };
+    }
+
+    it('stacks segments end-to-end without an explicit stack property', () => {
+      const spec = makeDefaultStackBarSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeBarMarks(spec, scales, chartArea, fullStrategy, CONTAINER_WIDTH);
+
+      const q1Marks = marks.filter((m) => m.aria.label.includes('Q1'));
+      expect(q1Marks).toHaveLength(2);
+      expect(q1Marks[0].y).toBe(q1Marks[1].y);
+      const [first, second] = q1Marks;
+      expect(second.x).toBeCloseTo(first.x + first.width, 0);
+      expect(marks.every((m) => m.stackGroup !== undefined)).toBe(true);
+    });
+  });
+
+  describe('grouped bars (stack: null)', () => {
     it('produces marks for all data rows', () => {
       const spec = makeGroupedBarSpec();
       const scales = computeScales(spec, chartArea, spec.data);
@@ -329,7 +371,10 @@ describe('computeBarMarks', () => {
         markDef: { type: 'bar' },
         data,
         encoding: {
-          x: { field: 'dollars', type: 'quantitative' },
+          // Grouped is opt-out since v8 (stacked is now the default): stamp
+          // stack: null explicitly since this test exercises the
+          // grouped-bar-only readable-floor reclaim.
+          x: { field: 'dollars', type: 'quantitative', stack: null },
           y: { field: 'district', type: 'nominal' },
           color: { field: 'source', type: 'nominal' },
         },
@@ -470,10 +515,12 @@ describe('computeBarMarks', () => {
         markDef: { type: 'bar' },
         data: wageData,
         encoding: {
+          // Grouped is opt-out since v8 (stacked is now the default): stamp
+          // stack: null explicitly for the grouped case.
           x: {
             field: 'pay',
             type: 'quantitative',
-            ...(stackZero ? { stack: 'zero' } : {}),
+            stack: stackZero ? 'zero' : null,
           },
           y: { field: 'size', type: 'nominal' },
           color: { field: 'year', type: 'nominal' },
@@ -487,7 +534,7 @@ describe('computeBarMarks', () => {
       };
     }
 
-    it('groups by default: bars sit at different y positions within each category', () => {
+    it('grouped (stack: null): bars sit at different y positions within each category', () => {
       const spec = makeWageSpec(false);
       const scales = computeScales(spec, chartArea, spec.data);
       const marks = computeBarMarks(spec, scales, chartArea, fullStrategy, CONTAINER_WIDTH);
@@ -500,12 +547,12 @@ describe('computeBarMarks', () => {
       expect(smallFirmMarks[0].y).not.toBe(smallFirmMarks[1].y);
     });
 
-    it('groups by default: scale domain covers max individual value, not stacked sum', () => {
+    it('grouped (stack: null): scale domain covers max individual value, not stacked sum', () => {
       const spec = makeWageSpec(false);
       const scales = computeScales(spec, chartArea, spec.data);
 
       // Max individual pay is 74800. Stacked sum for 5000+ employees = 62300 + 74800 = 137100.
-      // Default grouped bars should NOT extend domain to 137100.
+      // Grouped bars should NOT extend domain to 137100.
       const xScale = scales.x!.scale;
       const domain = xScale.domain() as number[];
       expect(domain[1]).toBeLessThan(137100);
@@ -711,7 +758,7 @@ describe('computeBarLabels', () => {
     const spec = makeSimpleBarSpec();
     const scales = computeScales(spec, chartArea, spec.data);
     const marks = computeBarMarks(spec, scales, chartArea, fullStrategy, CONTAINER_WIDTH);
-    const labels = computeBarLabels(marks, chartArea, 'auto', '$,.0f');
+    const labels = computeBarLabels(marks, chartArea, 'auto', buildD3Formatter('$,.0f'));
 
     const texts = labels.map((l) => l.text);
     expect(texts).toContain('$50');
@@ -740,7 +787,7 @@ describe('computeBarLabels', () => {
     };
     const scales = computeScales(spec, chartArea, spec.data);
     const marks = computeBarMarks(spec, scales, chartArea, fullStrategy, CONTAINER_WIDTH);
-    const labels = computeBarLabels(marks, chartArea, 'all', '$,.2~fT');
+    const labels = computeBarLabels(marks, chartArea, 'all', buildD3Formatter('$,.2~fT'));
 
     const texts = labels.map((l) => l.text);
     expect(texts).toContain('$3.75T');
@@ -751,7 +798,7 @@ describe('computeBarLabels', () => {
     const spec = makeSimpleBarSpec();
     const scales = computeScales(spec, chartArea, spec.data);
     const marks = computeBarMarks(spec, scales, chartArea, fullStrategy, CONTAINER_WIDTH);
-    const labels = computeBarLabels(marks, chartArea, 'auto', '.0f%');
+    const labels = computeBarLabels(marks, chartArea, 'auto', buildD3Formatter('.0f%'));
 
     const texts = labels.map((l) => l.text);
     expect(texts).toContain('50%');

package/src/charts/bar/__tests__/labels.test.ts

@@ -1,4 +1,5 @@
 import type { RectMark } from '@opendata-ai/openchart-core';
+import { buildD3Formatter } from '@opendata-ai/openchart-core';
 import { describe, expect, it } from 'vitest';
 import { computeBarLabels } from '../labels';
 
@@ -163,7 +164,7 @@ describe('computeBarLabels with $~s format and abbreviated aria values', () => {
       makeAbbreviatedMark(2, 14000, '14K'),
     ];
 
-    const labels = computeBarLabels(thousandMarks, chartArea, 'all', '$~s');
+    const labels = computeBarLabels(thousandMarks, chartArea, 'all', buildD3Formatter('$~s'));
     expect(labels).toHaveLength(3);
     expect(labels[0].text).toBe('$6k');
     expect(labels[1].text).toBe('$7k');
@@ -173,7 +174,7 @@ describe('computeBarLabels with $~s format and abbreviated aria values', () => {
   it('$~s format works for millions', () => {
     const millionMarks: RectMark[] = [makeAbbreviatedMark(0, 1500000, '1.5M')];
 
-    const labels = computeBarLabels(millionMarks, chartArea, 'all', '$~s');
+    const labels = computeBarLabels(millionMarks, chartArea, 'all', buildD3Formatter('$~s'));
     expect(labels).toHaveLength(1);
     expect(labels[0].text).toBe('$1.5M');
   });
@@ -181,7 +182,7 @@ describe('computeBarLabels with $~s format and abbreviated aria values', () => {
   it('handles comma-formatted aria values', () => {
     const commaMarks: RectMark[] = [makeAbbreviatedMark(0, 500, '500')];
 
-    const labels = computeBarLabels(commaMarks, chartArea, 'all', '$,.0f');
+    const labels = computeBarLabels(commaMarks, chartArea, 'all', buildD3Formatter('$,.0f'));
     expect(labels).toHaveLength(1);
     expect(labels[0].text).toBe('$500');
   });
@@ -211,7 +212,7 @@ describe('computeBarLabels with Unicode minus (U+2212) in aria values', () => {
       makeUnicodeMinusMark(1, '\u22125'), // −5
     ];
 
-    const labels = computeBarLabels(unicodeMarks, chartArea, 'all', '+.0f%');
+    const labels = computeBarLabels(unicodeMarks, chartArea, 'all', buildD3Formatter('+.0f%'));
     expect(labels).toHaveLength(2);
     expect(labels[0].text).toBe('\u221234%'); // −34%
     expect(labels[1].text).toBe('\u22125%'); // −5%

package/src/charts/bar/compute.ts

@@ -138,12 +138,8 @@ export function computeBarMarks(
     const needsStacking = Array.from(categoryGroups.values()).some((rows) => rows.length > 1);
 
     if (needsStacking) {
-      // stack: true/'zero'/'normalize'/'center' -> stacked; default (undefined/null/false) -> grouped
-      const stackEnabled =
-        xChannel.stack === true ||
-        xChannel.stack === 'zero' ||
-        xChannel.stack === 'normalize' ||
-        xChannel.stack === 'center';
+      // stack: undefined/true/'zero'/'normalize'/'center' -> stacked (default); null/false -> grouped
+      const stackEnabled = xChannel.stack !== null && xChannel.stack !== false;
 
       if (!stackEnabled) {
         marks = computeGroupedBars(

package/src/charts/bar/index.ts

@@ -5,6 +5,7 @@
  */
 
 import type { Mark } from '@opendata-ai/openchart-core';
+import { resolveFieldFormatter } from '../../format/field-format';
 import type { ChartRenderer } from '../registry';
 import { computeBarMarks } from './compute';
 import { computeBarLabels } from './labels';
@@ -26,11 +27,17 @@ export const barRenderer: ChartRenderer = (
   // Compute and attach value labels (respects spec.labels.density)
   const valueField =
     spec.encoding?.x && 'field' in spec.encoding.x ? spec.encoding.x.field : undefined;
+  const labelFormatter = resolveFieldFormatter({
+    surfaceFormat: spec.labels.format,
+    channelFormat:
+      spec.encoding?.x && 'format' in spec.encoding.x ? spec.encoding.x.format : undefined,
+    values: valueField ? spec.data.map((r) => r[valueField]) : [],
+  });
   const labels = computeBarLabels(
     marks,
     chartArea,
     spec.labels.density,
-    spec.labels.format,
+    labelFormatter,
     spec.labels.prefix,
     valueField,
     spec.labels.color,

package/src/charts/bar/labels.ts

@@ -16,11 +16,11 @@
 import type {
   LabelCandidate,
   LabelDensity,
+  NumberFormatter,
   RectMark,
   ResolvedLabel,
 } from '@opendata-ai/openchart-core';
 import {
-  buildD3Formatter,
   estimateTextWidth,
   getRepresentativeColor,
   pickLabelColor,
@@ -93,7 +93,7 @@ export function computeBarLabels(
   marks: RectMark[],
   _chartArea: { x: number; y: number; width: number; height: number },
   density: LabelDensity = 'auto',
-  labelFormat?: string,
+  labelFormatter?: NumberFormatter | null,
   labelPrefix?: string,
   valueField?: string,
   labelColor?: string,
@@ -113,7 +113,7 @@ export function computeBarLabels(
   // horizontal nudge back onto this display anchor so textAnchor stays honored.
   const displayAnchorX: number[] = [];
 
-  const formatter = buildD3Formatter(labelFormat);
+  const formatter = labelFormatter ?? null;
 
   for (const mark of targetMarks) {
     // Get the original numeric value from the data row when possible,