@opendata-ai/openchart-engine 7.10.0 → 8.0.0-rc.1

package/src/layout/plan.ts

@@ -1,6 +1,8 @@
 import type {
   CompileOptions,
   Encoding,
+  EncodingChannel,
+  FieldFormatContext,
   LayoutStrategy,
   MeasureTextFn,
   Rect,
@@ -9,15 +11,17 @@ import type {
 } from '@opendata-ai/openchart-core';
 import {
   AXIS_TITLE_TRAILING_PAD,
-  abbreviateNumber,
   axisTitleOffset,
   BREAKPOINT_COMPACT_MAX,
+  COMPACT_WIDTH,
   computeChrome,
+  computeFieldFormatContext,
   computeXAxisExtentFromLabels,
+  defaultNumberFormatter,
   estimateTextWidth,
-  formatNumber,
   HPAD_COMPACT_FRACTION,
   HPAD_COMPACT_MIN,
+  isAxislessMark,
   LABEL_GAP_COMPACT,
   LABEL_GAP_DEFAULT,
   MAX_LEFT_LABEL_FRACTION_COMPACT,
@@ -25,14 +29,20 @@ import {
   MAX_LEFT_LABEL_FRACTION_MEDIUM,
   MAX_LEFT_LABEL_FRACTION_MEDIUM_MAX,
   NARROW_VIEWPORT_MAX,
+  resolveNumberFormatter,
   TOP_PAD_EXTRA_NARROW,
 } from '@opendata-ai/openchart-core';
-import { format as d3Format } from 'd3-format';
 
 import type { NormalizedChartSpec } from '../compiler/types';
 import { predictEndpointLabelsWidth } from '../endpoint-labels/predict';
-import { computeLegendContent, type LegendContent } from '../legend/compute';
-import { legendGap } from '../legend/wrap';
+import { computeLegendContent, hasLegendContent, type LegendContent } from '../legend/compute';
+import {
+  computeSizeLegendContent,
+  SIZE_LEGEND_GAP,
+  type SizeLegendContent,
+  sizeLegendScaleFor,
+} from '../legend/size';
+import { legendGap, TOP_LEGEND_GAP_ABOVE } from '../legend/wrap';
 import { yTickPositionIsInline } from './axes';
 import { resolveBandTickAngle } from './axes/rotation';
 import { buildContinuousTicks, scaleSupportsTickCount, targetTickCount } from './axes/ticks';
@@ -55,6 +65,15 @@ export interface LayoutPlan {
   leftGutter: number;
   xAxisExtent: number;
   legendContent: LegendContent;
+  /**
+   * Size legend content, when a quantitative `size` channel is encoded.
+   *
+   * Kept beside `legendContent` rather than inside it: a chart can carry BOTH a
+   * color legend and a size legend, and folding them into one slot is what made
+   * the size channel unkeyable in the first place. `dimensions.ts` reserves
+   * right-margin for this independently of the color legend's position.
+   */
+  sizeLegendContent?: SizeLegendContent | null;
   chrome: ResolvedChrome;
   yTickValues: unknown[];
   yTickCount: number;
@@ -85,9 +104,16 @@ export function createMeasureFn(measureText?: MeasureTextFn): MeasureFn {
 // Helpers
 // ---------------------------------------------------------------------------
 
-/** Format a sample label from magnitude for gutter seeding. */
-function sampleLabelFromMagnitude(maxAbsVal: number): string {
-  return maxAbsVal >= 1_000 ? abbreviateNumber(maxAbsVal) : formatNumber(maxAbsVal);
+function sampleLabelFromContext(
+  maxAbsVal: number,
+  yAxisFormat: string | undefined,
+  ctx: FieldFormatContext,
+): string {
+  if (yAxisFormat) {
+    const fmt = resolveNumberFormatter(yAxisFormat, ctx);
+    if (fmt) return fmt(maxAbsVal);
+  }
+  return defaultNumberFormatter({ ...ctx, extent: ctx.extent ?? [0, maxAbsVal] })(maxAbsVal);
 }
 
 // ---------------------------------------------------------------------------
@@ -126,7 +152,7 @@ export function resolveLayoutPlan(
       ? Math.max(Math.round(padding * HPAD_COMPACT_FRACTION), HPAD_COMPACT_MIN)
       : padding;
   const encoding = renderSpec.encoding as Encoding;
-  const isRadial = renderSpec.markType === 'arc';
+  const isRadial = isAxislessMark(renderSpec.markType);
   const axisMargin = theme.spacing.axisMargin;
 
   // Resolve chromeMode
@@ -149,7 +175,7 @@ export function resolveLayoutPlan(
       measure,
     );
     const bottomLegendReservation =
-      legendContent.entries.length > 0 && legendContent.position === 'bottom'
+      hasLegendContent(legendContent) && legendContent.position === 'bottom'
         ? legendContent.height + legendGap(width)
         : 0;
     const chrome = computeChrome(
@@ -166,6 +192,8 @@ export function resolveLayoutPlan(
       leftGutter: hPad,
       xAxisExtent: 0,
       legendContent,
+      // Sparkline / radial: no positional axes and no bubbles, so no size key.
+      sizeLegendContent: null,
       chrome,
       yTickValues: [],
       yTickCount: 0,
@@ -231,7 +259,7 @@ export function resolveLayoutPlan(
         leftGutter = Math.max(leftGutter, reserved);
       }
     } else {
-      // Quantitative: seed with a formatted label (better than '1.5B' guess)
+      // Quantitative: seed with a formatted label
       const yField = encoding.y.field;
       const yAxisFormat = yAxisCfg?.format as string | undefined;
       let maxAbsVal = 0;
@@ -239,16 +267,8 @@ export function resolveLayoutPlan(
         const v = Number(row[yField]);
         if (Number.isFinite(v) && Math.abs(v) > maxAbsVal) maxAbsVal = Math.abs(v);
       }
-      let sampleLabel: string;
-      if (yAxisFormat) {
-        try {
-          sampleLabel = d3Format(yAxisFormat)(maxAbsVal);
-        } catch {
-          sampleLabel = String(maxAbsVal);
-        }
-      } else {
-        sampleLabel = sampleLabelFromMagnitude(maxAbsVal);
-      }
+      const ctx = computeFieldFormatContext(renderSpec.data.map((r) => r[yField]));
+      const sampleLabel = sampleLabelFromContext(maxAbsVal, yAxisFormat, ctx);
       const negPrefix = renderSpec.data.some((r) => Number(r[yField]) < 0) ? '-' : '';
       const labelWidth = measure(
         negPrefix + sampleLabel,
@@ -300,6 +320,26 @@ export function resolveLayoutPlan(
     }
   }
 
+  // Size legend: keys a quantitative `size` channel with graduated circles.
+  // Independent of the color legend -- a bubble chart keys BOTH continent
+  // (color) and population (size), so this is computed alongside, not instead.
+  // Its content is width-independent, so it sits outside the convergence loop.
+  //
+  // Dropped below COMPACT_WIDTH. The block is a fixed ~90px (it can't reflow the
+  // way a categorical legend's entries can), which on a phone-width chart is a
+  // quarter of the SVG spent on the key and a plot too narrow to read the bubbles
+  // it explains. The same threshold the color legend goes compact at.
+  const sizeScaleOpts = sizeLegendScaleFor(renderSpec.markType);
+  const sizeLegendContent =
+    sizeScaleOpts && chartSpec.legend?.show !== false && width >= COMPACT_WIDTH
+      ? computeSizeLegendContent(
+          renderSpec.encoding.size as EncodingChannel | undefined,
+          renderSpec.data,
+          theme,
+          sizeScaleOpts,
+        )
+      : null;
+
   for (let iter = 0; iter < 2; iter++) {
     // Legend content
     const legendAvailWidth = width - padding - leftGutter;
@@ -316,7 +356,7 @@ export function resolveLayoutPlan(
 
     // Chrome
     const bottomLegendReservation =
-      legendContent.entries.length > 0 && legendContent.position === 'bottom'
+      hasLegendContent(legendContent) && legendContent.position === 'bottom'
         ? legendContent.height + legendGap(width)
         : 0;
     const chrome = computeChrome(
@@ -336,7 +376,24 @@ export function resolveLayoutPlan(
     // footprint in the bottom margin instead of the (smaller) flat one.
     let effectiveXTickAngle = xTickAngle;
     if (xTickAngle === undefined && xLabels.length > 1) {
-      const rightMarginEst = hPad + (isRadial ? hPad : axisMargin);
+      // The right-hand legend column narrows the plot (dimensions.ts reserves
+      // it), so it has to be in this estimate too. Without it the planner sizes
+      // bands against a plot up to ~100px wider than the real one, concludes the
+      // labels fit flat, and computeAxes then rotates them against the true
+      // bandwidth -- reserving the flat footprint for rotated labels and clipping
+      // the axis. Bites a nominal-x beeswarm with a size channel.
+      //
+      // Mirrors the shared-column reservation in dimensions.ts: the color and
+      // size legends stack in ONE column, so it is the wider of the two, not the
+      // sum. These two must agree -- an estimate wider than the real margin
+      // rotates labels that would have fit.
+      const colorInGutter =
+        hasLegendContent(legendContent) &&
+        (legendContent.position === 'right' || legendContent.position === 'bottom-right');
+      const colorLegendReserve = colorInGutter ? legendContent.legendWidth + 8 : 0;
+      const sizeLegendReserve = sizeLegendContent ? sizeLegendContent.width + SIZE_LEGEND_GAP : 0;
+      const legendReserve = Math.max(colorLegendReserve, sizeLegendReserve);
+      const rightMarginEst = hPad + (isRadial ? hPad : axisMargin) + legendReserve;
       const plotWidth = Math.max(0, width - leftGutter - Math.max(rightMarginEst, hPad));
       // Mirror d3 scaleBand: step = plotWidth / (n - paddingInner + 2*paddingOuter),
       // bandwidth = step * (1 - paddingInner). Uses the same override resolution
@@ -386,7 +443,7 @@ export function resolveLayoutPlan(
 
     // Top margin
     const topPad = width < NARROW_VIEWPORT_MAX ? padding + TOP_PAD_EXTRA_NARROW : padding;
-    const hasTopLegend = legendContent.entries.length > 0 && legendContent.position === 'top';
+    const hasTopLegend = hasLegendContent(legendContent) && legendContent.position === 'top';
     const gap = legendGap(width);
     const inlineTickOverhang = yIsInline
       ? theme.fonts.sizes.axisTick + INLINE_TICK_OVERHANG_PAD
@@ -395,7 +452,8 @@ export function resolveLayoutPlan(
     const effectiveTopAxisGap = hasTopLegend ? inlineTickOverhang : topAxisGap;
 
     let topMargin = topPad + chrome.topHeight;
-    if (hasTopLegend) topMargin += legendContent.height + gap;
+    // Mirrors the dimensions.ts margin stack: min gap above the top legend.
+    if (hasTopLegend) topMargin += TOP_LEGEND_GAP_ABOVE + legendContent.height + gap;
     topMargin += effectiveTopAxisGap;
 
     const bMargin = bottomMargin(chrome.bottomHeight, padding, xAxisExtent);
@@ -500,16 +558,8 @@ export function resolveLayoutPlan(
             const v = Number(row[yField]);
             if (Number.isFinite(v) && Math.abs(v) > maxAbsVal) maxAbsVal = Math.abs(v);
           }
-          let sample: string;
-          if (yAxisFormat) {
-            try {
-              sample = d3Format(yAxisFormat)(maxAbsVal);
-            } catch {
-              sample = String(maxAbsVal);
-            }
-          } else {
-            sample = sampleLabelFromMagnitude(maxAbsVal);
-          }
+          const ctx = computeFieldFormatContext(renderSpec.data.map((r) => r[yField]));
+          const sample = sampleLabelFromContext(maxAbsVal, yAxisFormat, ctx);
           const neg = renderSpec.data.some((r) => Number(r[encoding.y!.field]) < 0) ? '-' : '';
           const maxLabelWidth = measure(
             neg + sample,
@@ -561,6 +611,7 @@ export function resolveLayoutPlan(
         leftGutter: gutterWithTitle,
         xAxisExtent,
         legendContent,
+        sizeLegendContent,
         chrome,
         yTickValues,
         yTickCount,

package/src/layout/scales.ts

@@ -10,9 +10,11 @@ import type {
   DataRow,
   Encoding,
   EncodingChannel,
+  FieldFormatContext,
   Rect,
   ScaleType,
 } from '@opendata-ai/openchart-core';
+import { computeFieldFormatContext } from '@opendata-ai/openchart-core';
 import { extent, max, min } from 'd3-array';
 import type {
   ScaleBand,
@@ -44,6 +46,7 @@ import {
 } from 'd3-scale';
 
 import type { NormalizedChartSpec } from '../compiler/types';
+import { DEFAULT_BIN_COUNT, sampleRampColors } from '../legend/continuous';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -91,6 +94,8 @@ export interface ResolvedScale {
   type: ResolvedScaleType;
   /** The encoding channel this scale was derived from. */
   channel: EncodingChannel;
+  /** Per-field formatting context (extent, allIntegers) from the ORIGINAL data. */
+  formatContext?: FieldFormatContext;
 }
 
 /** All resolved scales for a chart. */
@@ -145,12 +150,13 @@ function uniqueStrings(values: unknown[]): string[] {
  * - 'ascending': sort alphabetically/numerically ascending
  * - 'descending': sort descending
  * - null | undefined: preserve data order (no sorting)
+ *
+ * VL sort forms ('-y', value arrays, { field, op, order }) are resolved into
+ * an explicit scale.domain by the pre-validation sugar expansion; any that
+ * reach this point fall back to data order.
  */
-function applyCategoricalSort(
-  values: string[],
-  sort: 'ascending' | 'descending' | null | undefined,
-): string[] {
-  if (!sort) return values;
+export function applyCategoricalSort(values: string[], sort: EncodingChannel['sort']): string[] {
+  if (sort !== 'ascending' && sort !== 'descending') return values;
 
   const sorted = [...values].sort((a, b) => a.localeCompare(b, undefined, { numeric: true }));
   if (sort === 'descending') sorted.reverse();
@@ -509,17 +515,27 @@ export function estimateBandStep(
   return plotWidth / denom;
 }
 
+/**
+ * Gap between bands, as a fraction of the step. The 0.35 default is a *bar*
+ * value: bars need air between them to read as separate quantities. Heatmap
+ * cells are the opposite -- they tile, and the gap is a hairline gutter that
+ * only exists to keep adjacent fills from bleeding into each other.
+ */
+const DEFAULT_BAND_PADDING = 0.35;
+const HEATMAP_BAND_PADDING = 0.04;
+
 function buildBandScale(
   channel: EncodingChannel,
   data: DataRow[],
   rangeStart: number,
   rangeEnd: number,
+  defaultPadding: number = DEFAULT_BAND_PADDING,
 ): ResolvedScale {
   const values = channel.scale?.domain
     ? (channel.scale.domain as string[])
     : applyCategoricalSort(uniqueStrings(fieldValues(data, channel.field)), channel.sort);
 
-  const padding = channel.scale?.padding ?? 0.35;
+  const padding = channel.scale?.padding ?? defaultPadding;
   const scale = scaleBand().domain(values).range([rangeStart, rangeEnd]).padding(padding);
 
   if (channel.scale?.paddingInner !== undefined) {
@@ -594,10 +610,20 @@ function buildSequentialColorScale(
   const explicitRange = channel.scale?.range as string[] | undefined;
   const colors = explicitRange ?? palette;
 
-  const scale = scaleLinear<string>()
-    .domain([domainMin, domainMax])
-    .range([colors[0], colors[colors.length - 1]])
-    .clamp(true);
+  // Explicit multi-stop ranges (e.g. a diverging scheme) interpolate piecewise
+  // through every stop, with evenly-spaced domain pivots to match. Without an
+  // explicit range the endpoints-only form is kept so applyColorScaleRange can
+  // swap in the theme ramp endpoints post-hoc.
+  const stops =
+    explicitRange && explicitRange.length > 2
+      ? explicitRange
+      : [colors[0], colors[colors.length - 1]];
+  const domain =
+    stops.length > 2
+      ? stops.map((_, i) => domainMin + ((domainMax - domainMin) * i) / (stops.length - 1))
+      : [domainMin, domainMax];
+
+  const scale = scaleLinear<string>().domain(domain).range(stops).clamp(true);
 
   // Cast: sequential color scale (number -> string) is structurally incompatible
   // with D3Scale (number -> number), but is only ever accessed via scales.color
@@ -605,6 +631,45 @@ function buildSequentialColorScale(
   return { scale: scale as unknown as D3Scale, type: 'sequential', channel };
 }
 
+/**
+ * Build a binned color scale (quantile/quantize/threshold) for a quantitative
+ * color encoding with an explicit `scale.type`. The range holds colors: an
+ * explicit `scale.range` wins; otherwise a placeholder sampled from the
+ * default palette that `applyColorScaleRange` replaces with the theme's
+ * sequential ramp.
+ */
+function buildBinnedColorScale(
+  channel: EncodingChannel,
+  data: DataRow[],
+  palette: string[],
+): ResolvedScale {
+  const values = parseNumbers(fieldValues(data, channel.field));
+  const explicitRange = channel.scale?.range as string[] | undefined;
+  const scaleType = channel.scale?.type as 'quantile' | 'quantize' | 'threshold';
+
+  if (scaleType === 'threshold') {
+    // Threshold scales require explicit domain breakpoints; colors = breaks + 1.
+    const breaks = (channel.scale?.domain as number[] | undefined) ?? [0.5];
+    const colors = sampleRampColors(explicitRange ?? palette, breaks.length + 1);
+    const scale = scaleThreshold<number, string>().domain(breaks).range(colors);
+    return { scale: scale as unknown as D3Scale, type: 'threshold', channel };
+  }
+
+  const binCount = explicitRange?.length ?? DEFAULT_BIN_COUNT;
+  const colors = explicitRange ?? sampleRampColors(palette, binCount);
+
+  if (scaleType === 'quantile') {
+    const scale = scaleQuantile<string>().domain(values).range(colors);
+    return { scale: scale as unknown as D3Scale, type: 'quantile', channel };
+  }
+
+  const explicitDomain = channel.scale?.domain as [number, number] | undefined;
+  const domainMin = explicitDomain?.[0] ?? min(values) ?? 0;
+  const domainMax = explicitDomain?.[1] ?? max(values) ?? 1;
+  const scale = scaleQuantize<string>().domain([domainMin, domainMax]).range(colors);
+  return { scale: scale as unknown as D3Scale, type: 'quantize', channel };
+}
+
 // ---------------------------------------------------------------------------
 // Positional scale selection
 // ---------------------------------------------------------------------------
@@ -661,9 +726,23 @@ function buildPositionalScale(
       return buildLinearScale(channel, data, rangeStart, rangeEnd);
     case 'nominal':
     case 'ordinal':
-      // Bar charts use band scales for their categorical axis (both orientations)
+      // Bar and range charts use band scales for their categorical axis (both
+      // orientations). Beeswarm lanes are band scales too: each category gets
+      // a band whose center anchors one swarm, on whichever axis carries the
+      // nominal channel.
+      //
+      // `rect` is the only mark that needs a band on *both* axes: a heatmap cell
+      // is sized by the bandwidth of each axis, so it takes no `axis` guard. A
+      // point scale would give it zero width and height (and it did: `rect` cells
+      // rendered as invisible zero-area marks). It also tiles, so it takes the
+      // hairline gutter rather than the bar-sized gap.
+      if (chartType === 'rect') {
+        return buildBandScale(channel, data, rangeStart, rangeEnd, HEATMAP_BAND_PADDING);
+      }
       if (
         chartType === 'bar' ||
+        chartType === 'beeswarm' ||
+        chartType === 'range' ||
         ((chartType === 'circle' || chartType === 'lollipop') && axis === 'y')
       ) {
         return buildBandScale(channel, data, rangeStart, rangeEnd);
@@ -694,8 +773,17 @@ export function computeScales(
   const result: ResolvedScales = {};
   const encoding = spec.encoding as Encoding;
 
-  // Scatter/bubble charts should NOT include zero by default (tight domain fits data range)
-  if (spec.markType === 'point') {
+  // Marks that encode position (not length) default to zero: false so the
+  // domain fits the data range. Line charts show trends — anchoring at zero
+  // wastes space. Scatter/beeswarm encode raw observations whose spread is
+  // the story. Text marks must match the point layer they label.
+  if (
+    spec.markType === 'point' ||
+    spec.markType === 'line' ||
+    spec.markType === 'beeswarm' ||
+    spec.markType === 'range' ||
+    spec.markType === 'text'
+  ) {
     if (encoding.x?.type === 'quantitative' && encoding.x.scale?.zero === undefined) {
       if (!encoding.x.scale) {
         (encoding.x as { scale?: Record<string, unknown> }).scale = { zero: false };
@@ -717,6 +805,13 @@ export function computeScales(
     // Without this, stacked bars would clip past the chart area.
     let xData = data;
     let xChannel = encoding.x;
+    // Range charts span x to x2: the x-domain must cover both endpoint fields.
+    // Synthetic rows map x2 values into the x field so buildLinearScale sees them.
+    if (spec.markType === 'range' && encoding.x2 && encoding.x.type === 'quantitative') {
+      const xField = encoding.x.field;
+      const x2Field = encoding.x2.field;
+      xData = [...data, ...data.map((row) => ({ [xField]: row[x2Field] }) as DataRow)];
+    }
     const xStackEnabled =
       encoding.x.stack === true ||
       encoding.x.stack === 'zero' ||
@@ -788,6 +883,9 @@ export function computeScales(
       spec.markType,
       'x',
     );
+    if (result.x && encoding.x.type === 'quantitative' && encoding.x.field) {
+      result.x.formatContext = computeFieldFormatContext(data.map((r) => r[encoding.x!.field]));
+    }
   }
 
   if (encoding.y) {
@@ -797,6 +895,12 @@ export function computeScales(
     // Vertical bar = x is categorical and y is quantitative (old 'column' chart type).
     let yData = data;
     let yChannel = encoding.y;
+    // Range charts span y to y2 (vertical form): cover both endpoint fields.
+    if (spec.markType === 'range' && encoding.y2 && encoding.y.type === 'quantitative') {
+      const yField = encoding.y.field;
+      const y2Field = encoding.y2.field;
+      yData = [...data, ...data.map((row) => ({ [yField]: row[y2Field] }) as DataRow)];
+    }
     const isVerticalBar =
       spec.markType === 'bar' &&
       (encoding.x?.type === 'nominal' || encoding.x?.type === 'ordinal') &&
@@ -904,6 +1008,9 @@ export function computeScales(
       spec.markType,
       'y',
     );
+    if (result.y && encoding.y.type === 'quantitative' && encoding.y.field) {
+      result.y.formatContext = computeFieldFormatContext(data.map((r) => r[encoding.y!.field]));
+    }
   }
 
   if (encoding.color) {
@@ -923,8 +1030,18 @@ export function computeScales(
     // Only build color scales for field-based encodings, not conditional value defs
     if ('field' in encoding.color) {
       if (encoding.color.type === 'quantitative') {
-        // Sequential color scale for value-based coloring
-        result.color = buildSequentialColorScale(encoding.color, data, defaultPalette);
+        const colorScaleType = encoding.color.scale?.type;
+        if (
+          colorScaleType === 'quantile' ||
+          colorScaleType === 'quantize' ||
+          colorScaleType === 'threshold'
+        ) {
+          // Binned color scale: discrete classes for value-based coloring
+          result.color = buildBinnedColorScale(encoding.color, data, defaultPalette);
+        } else {
+          // Sequential color scale for value-based coloring
+          result.color = buildSequentialColorScale(encoding.color, data, defaultPalette);
+        }
       } else {
         // Categorical color scale for nominal/ordinal grouping
         result.color = buildOrdinalColorScale(encoding.color, data, defaultPalette);