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

package/src/compile/layer.ts

@@ -9,15 +9,15 @@ import type {
 } from '@opendata-ai/openchart-core';
 import {
   AXIS_TITLE_TRAILING_PAD,
-  abbreviateNumber,
   BREAKPOINT_COMPACT_MAX,
+  computeFieldFormatContext,
+  defaultNumberFormatter,
   estimateTextWidth,
-  formatNumber,
   getAxisTitleOffset,
+  resolveNumberFormatter,
   resolveTheme,
   TICK_LABEL_OFFSET,
 } from '@opendata-ai/openchart-core';
-import { format as d3Format } from 'd3-format';
 import { scaleLinear } from 'd3-scale';
 import { curveMonotoneX, area as d3area, line as d3line } from 'd3-shape';
 import { flattenLayers } from '../compiler/index';
@@ -75,9 +75,16 @@ export function compileLayer(
   // axes. Freeze the primary's area (and inherit its theme) for every leaf.
   const leafOptions: CompileOptions = { ...options, frozenChartArea: primaryLayout.area };
 
+  // Shared scales means shared *domains*, not just a shared plot rect. Each leaf
+  // otherwise re-fits its own domain from its own rows, so a layer holding fewer
+  // or narrower rows than its siblings (a label layer naming only the notable
+  // points, say) lands on a different scale and its marks slide off the ones
+  // they annotate. Union the quantitative domains across every leaf and pin them.
+  const sharedDomains = computeSharedDomains(leaves);
+
   for (const { leaf } of indexedLeaves) {
     const themedLeaf = {
-      ...(leaf as ChartSpec),
+      ...withSharedDomains(leaf as ChartSpec, sharedDomains),
       theme: (leaf as ChartSpec).theme ?? spec.theme,
       darkMode: (leaf as ChartSpec).darkMode ?? spec.darkMode,
     };
@@ -96,13 +103,20 @@ export function compileLayer(
     }
   }
 
+  const mergedLegend = {
+    ...primaryLayout.legend,
+    ...('entries' in pLegend ? { entries: mergedLegendEntries } : {}),
+  } as typeof primaryLayout.legend;
+
   return {
     ...primaryLayout,
     marks: allMarks,
-    legend: {
-      ...primaryLayout.legend,
-      ...('entries' in pLegend ? { entries: mergedLegendEntries } : {}),
-    } as typeof primaryLayout.legend,
+    legend: mergedLegend,
+    // `legends` is what the renderer iterates, so the merged color legend has to
+    // land in it too. Spreading `primaryLayout` alone would leave legends[0] as
+    // the *pre-merge* legend and every leaf past the first would vanish from the
+    // rendered key while `layout.legend` claimed otherwise.
+    legends: [mergedLegend, ...primaryLayout.legends.slice(1)],
   };
 }
 
@@ -142,18 +156,15 @@ function estimateYAxisLabelWidth(
     const v = Number(row[yField]);
     if (Number.isFinite(v) && Math.abs(v) > maxAbsVal) maxAbsVal = Math.abs(v);
   }
+  const ctx = computeFieldFormatContext(data.map((r) => r[yField]));
   let sampleLabel: string;
   if (yAxisFormat) {
-    try {
-      const fmt = d3Format(yAxisFormat);
-      sampleLabel = fmt(maxAbsVal);
-    } catch {
-      sampleLabel = String(maxAbsVal);
-    }
+    const fmt = resolveNumberFormatter(yAxisFormat, ctx);
+    sampleLabel = fmt ? fmt(maxAbsVal) : String(maxAbsVal);
   } else {
-    // Use the same formatting as tick labels instead of hardcoded magnitude guesses
-    sampleLabel =
-      Math.abs(maxAbsVal) >= 1000 ? abbreviateNumber(maxAbsVal) : formatNumber(maxAbsVal);
+    sampleLabel = defaultNumberFormatter({ ...ctx, extent: ctx.extent ?? [0, maxAbsVal] })(
+      maxAbsVal,
+    );
   }
   const hasNeg = data.some((r) => Number(r[yField]) < 0);
   const labelEst = (hasNeg ? '-' : '') + sampleLabel;
@@ -382,6 +393,11 @@ function compileLayerIndependent(
   const marks =
     z0 <= z1 ? [...adjustedMarks0, ...taggedMarks1] : [...taggedMarks1, ...adjustedMarks0];
 
+  const mergedLegend = {
+    ...layout0.legend,
+    ...('entries' in l0Legend ? { entries: mergedLegendEntries } : {}),
+  } as typeof layout0.legend;
+
   return {
     ...layout0,
     axes: {
@@ -390,10 +406,10 @@ function compileLayerIndependent(
       y2: y2Axis,
     },
     marks,
-    legend: {
-      ...layout0.legend,
-      ...('entries' in l0Legend ? { entries: mergedLegendEntries } : {}),
-    } as typeof layout0.legend,
+    legend: mergedLegend,
+    // See the note in compileLayer: the renderer reads `legends`, so the merged
+    // legend must replace the primary's entry there as well.
+    legends: [mergedLegend, ...layout0.legends.slice(1)],
     tooltipDescriptors: mergedTooltips,
   };
 }
@@ -508,6 +524,86 @@ function withYDomain(leaf: ChartSpec, domain: [number, number]): ChartSpec {
   } as ChartSpec;
 }
 
+type SharedDomains = { x?: [number, number]; y?: [number, number] };
+
+/**
+ * Union the quantitative x/y extents across every leaf.
+ *
+ * Only channels that every leaf encodes *quantitatively* are unioned — a leaf
+ * mixing a nominal x with a quantitative one has no common numeric domain, and
+ * an author-pinned `scale.domain` on any leaf is left to win on its own.
+ */
+function computeSharedDomains(leaves: ChartSpec[]): SharedDomains {
+  const shared: SharedDomains = {};
+
+  for (const channel of ['x', 'y'] as const) {
+    let lo = Number.POSITIVE_INFINITY;
+    let hi = Number.NEGATIVE_INFINITY;
+    let sawAny = false;
+    let usable = true;
+
+    for (const leaf of leaves) {
+      const enc = (leaf.encoding as Encoding | undefined)?.[channel];
+      // Skip *this channel* if any leaf can't take part: no encoding, a
+      // non-quantitative type, or a domain the author already pinned. Bailing
+      // out of the whole function here would abandon the other channel too --
+      // a nominal x would silently strand a quantitative y, which is the most
+      // common layered shape there is (bars plus their value labels).
+      if (!enc || !('field' in enc) || enc.type !== 'quantitative' || enc.scale?.domain) {
+        usable = false;
+        break;
+      }
+
+      for (const row of leaf.data ?? []) {
+        const v = Number((row as DataRow)[enc.field]);
+        if (!Number.isFinite(v)) continue;
+        if (v < lo) lo = v;
+        if (v > hi) hi = v;
+        sawAny = true;
+      }
+    }
+
+    if (!usable || !sawAny || lo > hi) continue;
+
+    // Pin the union through zero the way an unpinned scale would.
+    //
+    // `withSharedDomains` writes this extent onto each leaf as `scale.domain`,
+    // and `resolveQuantitativeScale` takes an explicit domain *verbatim* --
+    // skipping the `zero !== false` baselining it would otherwise apply. So a
+    // raw [50, 100] union lands as a literal domain and the 50-bar collapses
+    // to a sliver against its own baseline. Fold zero in here, honouring an
+    // explicit `zero: false` on any leaf (a sparkline opting out of it).
+    const wantsZero = leaves.every((leaf) => {
+      const enc = (leaf.encoding as Encoding | undefined)?.[channel];
+      return enc && 'scale' in enc ? enc.scale?.zero !== false : true;
+    });
+    shared[channel] = wantsZero ? [Math.min(0, lo), Math.max(0, hi)] : [lo, hi];
+  }
+
+  return shared;
+}
+
+/** Pin the shared domains onto a leaf's quantitative x/y channels. */
+function withSharedDomains(leaf: ChartSpec, shared: SharedDomains): ChartSpec {
+  if (!shared.x && !shared.y) return leaf;
+
+  const encoding = { ...(leaf.encoding as Record<string, unknown>) };
+
+  for (const channel of ['x', 'y'] as const) {
+    const domain = shared[channel];
+    const ch = encoding[channel] as Record<string, unknown> | undefined;
+    if (!domain || !ch) continue;
+    encoding[channel] = {
+      ...ch,
+      scale: { ...((ch.scale as object) ?? {}), domain },
+    };
+  }
+
+  // ChartSpec is a union discriminated on `mark`, and spreading widens the
+  // encoding past whichever member `leaf` is, so re-assert the original type.
+  return { ...leaf, encoding } as unknown as ChartSpec;
+}
+
 function buildPrimarySpec(leaves: ChartSpec[], layerSpec: LayerSpec): ChartSpec {
   const allData = leaves.flatMap((leaf) => leaf.data);
 

package/src/compile/size-scale.ts

@@ -0,0 +1,139 @@
+/**
+ * Shared `size` channel scale.
+ *
+ * Three marks map a quantitative field onto a visual magnitude, and each used to
+ * build this scale inline with the same six lines and a different pair of
+ * constants. A size legend has to resolve the *same* scale the marks resolve or
+ * the key silently lies about what a big circle means, so the builder lives in
+ * one place and everyone -- marks and legend -- calls it.
+ *
+ * The curve is the one thing that genuinely differs, and it is a perceptual
+ * call, not a preference:
+ *
+ * - `sqrt` for circles (scatter, beeswarm). Perceived magnitude of a disc tracks
+ *   its *area*, and area goes as r^2, so radius must go as sqrt(value).
+ * - `linear` for glyphs (text). A word reads by its *height*, which is linear in
+ *   font size. Running font size through sqrt would be cargo-culting the bubble
+ *   math onto a channel that doesn't share its geometry.
+ */
+
+import type { DataRow, EncodingChannel } from '@opendata-ai/openchart-core';
+import { max, min } from 'd3-array';
+import { scaleLinear, scaleSqrt } from 'd3-scale';
+
+/** How a size value maps onto its visual magnitude. */
+export type SizeCurve = 'sqrt' | 'linear';
+
+/**
+ * Per-mark size-scale defaults.
+ *
+ * These live here, next to the builder, rather than in each mark's compute
+ * module -- because the size *legend* needs the exact same numbers, and a key
+ * whose circles are a different size from the bubbles they explain is worse
+ * than no key. One definition, imported by both, so they cannot drift.
+ */
+export const SIZE_SCALE_DEFAULTS = {
+  /** Scatter bubbles. */
+  point: { curve: 'sqrt', range: [3, 30] },
+  /**
+   * Beeswarm dots. Tighter than scatter's 3-30: large radii make the dodge
+   * layout stack dots far past the lane, so the default cap stays low.
+   */
+  beeswarm: { curve: 'sqrt', range: [2, 10] },
+  /**
+   * Text glyphs. Linear, not sqrt -- a word reads by its height, which is
+   * linear in font size, where a disc reads by its area.
+   */
+  text: { curve: 'linear', range: [11, 32] },
+} as const satisfies Record<string, { curve: SizeCurve; range: readonly [number, number] }>;
+
+/** Size-scale options for a mark, or null when the mark has no size channel. */
+export function sizeScaleDefaultsFor(
+  markType: string,
+): { curve: SizeCurve; range: [number, number] } | null {
+  const found = (
+    SIZE_SCALE_DEFAULTS as Record<
+      string,
+      { curve: SizeCurve; range: readonly [number, number] } | undefined
+    >
+  )[markType];
+  return found ? { curve: found.curve, range: [found.range[0], found.range[1]] } : null;
+}
+
+/** A resolved size scale plus the domain and range it was built from. */
+export interface ResolvedSizeScale {
+  /** Maps a data value to a visual magnitude (radius, or font size). */
+  scale: (value: number) => number;
+  /** The domain actually used: an explicit `scale.domain` wins over the data extent. */
+  domain: [number, number];
+  /** The output range actually used: an explicit `scale.range` wins over the default. */
+  range: [number, number];
+  /** The field the scale reads. */
+  field: string;
+}
+
+/**
+ * Build the size scale for a quantitative `size` encoding.
+ *
+ * Author overrides come from the encoding, mirroring the color path: an explicit
+ * `scale.domain` (e.g. `[0, 900]`) keeps the largest datum below the max radius
+ * so dense clusters don't blob together, and an explicit `scale.range` caps the
+ * output magnitudes.
+ *
+ * The scale is **clamped**: a datum outside an explicit domain renders at the
+ * range endpoint rather than running off to an absurd radius. A legend built
+ * from this must therefore key the *domain*, not the data extent -- above an
+ * explicit `domain[1]` every datum looks identical.
+ *
+ * Holes (`null`, `undefined`, `''`) are not zeros -- they are absent data --
+ * and are dropped before the extent is fitted rather than coerced into it.
+ *
+ * @returns null when there is no size field, or when the domain is degenerate
+ * (no finite values, or every value identical). A zero-width domain would map
+ * every datum to the range's first value, so there is nothing to encode and
+ * nothing to legend.
+ */
+export function buildSizeScale(
+  sizeEncoding: EncodingChannel | undefined,
+  data: readonly DataRow[],
+  options: { curve: SizeCurve; range: readonly [number, number] },
+): ResolvedSizeScale | null {
+  if (!sizeEncoding || !('field' in sizeEncoding) || !sizeEncoding.field) return null;
+  const field = sizeEncoding.field;
+
+  const values: number[] = [];
+  for (const row of data) {
+    const raw = row[field];
+    // Reject holes before coercing: `Number(null)` and `Number('')` are both a
+    // finite 0, so a null would enter the extent as a real zero and drag the
+    // domain floor down -- rescaling every genuine mark, and drawing a
+    // minimum-size mark for a datum that has no size at all.
+    if (raw == null || raw === '') continue;
+    const v = Number(raw);
+    if (Number.isFinite(v)) values.push(v);
+  }
+
+  const explicitDomain = sizeEncoding.scale?.domain as [number, number] | undefined;
+
+  // Nothing to fit a domain to. An explicit domain still stands on its own --
+  // it is the author's, not the data's -- but without one there is no extent,
+  // and `min([]) ?? 0` / `max([]) ?? 1` would fabricate a bogus [0, 1].
+  if (!explicitDomain && values.length === 0) return null;
+
+  const domain: [number, number] = explicitDomain ?? [min(values) as number, max(values) as number];
+
+  // A zero-width domain maps every datum to range[0]: no magnitude is encoded,
+  // so callers fall back to their static default rather than render a field of
+  // identical minimum-size marks.
+  if (!Number.isFinite(domain[0]) || !Number.isFinite(domain[1]) || domain[0] >= domain[1]) {
+    return null;
+  }
+
+  const explicitRange = sizeEncoding.scale?.range as [number, number] | undefined;
+  const range: [number, number] = explicitRange ?? [options.range[0], options.range[1]];
+
+  const build = options.curve === 'linear' ? scaleLinear : scaleSqrt;
+  const scale = build().domain(domain).range(range).clamp(true);
+
+  return { scale: (value: number) => scale(value), domain, range, field };
+}