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

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

@@ -0,0 +1,280 @@
+import type { PointMark } from '@opendata-ai/openchart-core';
+import { describe, expect, it } from 'vitest';
+import { compileChart } from '../../../compile';
+import { compile } from '../../../compiler';
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+/** Deterministic pseudo-random sequence (mulberry32) for repeatable fixtures. */
+function seededRandom(seed: number): () => number {
+  let a = seed;
+  return () => {
+    a |= 0;
+    a = (a + 0x6d2b79f5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+const REGIONS = ['Northeast', 'Midwest', 'South', 'West'];
+
+/** Deterministic observation rows: income value, region lane, population size. */
+function makeRows(count: number, seed = 1): Array<Record<string, unknown>> {
+  const rand = seededRandom(seed);
+  return Array.from({ length: count }, (_, i) => ({
+    income: Math.round(((rand() + rand()) / 2) * 120 + 20),
+    region: REGIONS[i % REGIONS.length],
+    pop: Math.round(rand() * 900 + 10),
+  }));
+}
+
+function singleLaneSpec(count = 300) {
+  return {
+    mark: 'beeswarm' as const,
+    data: makeRows(count),
+    encoding: {
+      x: { field: 'income', type: 'quantitative' as const },
+    },
+  };
+}
+
+function groupedSpec(count = 200) {
+  return {
+    mark: 'beeswarm' as const,
+    data: makeRows(count),
+    encoding: {
+      x: { field: 'income', type: 'quantitative' as const },
+      y: { field: 'region', type: 'nominal' as const },
+      color: { field: 'region', type: 'nominal' as const },
+    },
+  };
+}
+
+const OPTIONS = { width: 800, height: 500 };
+
+function pointMarks(layout: ReturnType<typeof compileChart>): PointMark[] {
+  return layout.marks.filter((m): m is PointMark => m.type === 'point');
+}
+
+/** Assert every pair of circles keeps at least (r1 + r2) separation. */
+function expectNoOverlap(marks: PointMark[]): void {
+  const epsilon = 1e-6;
+  for (let i = 0; i < marks.length; i++) {
+    for (let j = i + 1; j < marks.length; j++) {
+      const dx = marks[i].cx - marks[j].cx;
+      const dy = marks[i].cy - marks[j].cy;
+      const dist = Math.sqrt(dx * dx + dy * dy);
+      expect(dist).toBeGreaterThanOrEqual(marks[i].r + marks[j].r - epsilon);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('beeswarm compile', () => {
+  it('renders a 300-point single-lane swarm with zero overlapping circles', () => {
+    const layout = compileChart(singleLaneSpec(300), OPTIONS);
+    const marks = pointMarks(layout);
+    expect(marks).toHaveLength(300);
+    expectNoOverlap(marks);
+  });
+
+  it('compiles the same spec twice to identical positions (determinism)', () => {
+    const spec = singleLaneSpec(300);
+    const first = pointMarks(compileChart(spec, OPTIONS)).map((m) => [m.cx, m.cy, m.r]);
+    const second = pointMarks(compileChart(spec, OPTIONS)).map((m) => [m.cx, m.cy, m.r]);
+    expect(second).toEqual(first);
+  });
+
+  it('drops rows whose value is null or the field is missing', () => {
+    // The validator rejects a quantitative field that carries non-numeric or
+    // non-finite values (strings, NaN, Infinity), but tolerates null/undefined
+    // (`val != null` skips them). Those null/missing rows must then be dropped
+    // by the compute pass rather than producing NaN-positioned dots.
+    const spec = {
+      mark: 'beeswarm' as const,
+      data: [
+        { income: 40 },
+        { income: null },
+        { notIncome: 5 }, // field missing entirely -> undefined
+        { income: 90 },
+      ],
+      encoding: {
+        x: { field: 'income', type: 'quantitative' as const },
+      },
+    };
+    const marks = pointMarks(compileChart(spec, OPTIONS));
+    // Only the two rows with finite values (40 and 90) survive.
+    expect(marks).toHaveLength(2);
+    for (const mark of marks) {
+      expect(Number.isFinite(mark.cx)).toBe(true);
+      expect(Number.isFinite(mark.cy)).toBe(true);
+    }
+  });
+
+  it('renders only the value axis for a single-lane swarm', () => {
+    const layout = compileChart(singleLaneSpec(60), OPTIONS);
+    expect(layout.axes.x?.ticks.length).toBeGreaterThan(0);
+    expect(layout.axes.y).toBeUndefined();
+  });
+
+  it('centers a single-lane horizontal swarm on the middle of the chart area', () => {
+    const layout = compileChart(singleLaneSpec(1), OPTIONS);
+    const [mark] = pointMarks(layout);
+    expect(mark.cy).toBeCloseTo(layout.area.y + layout.area.height / 2, 6);
+  });
+
+  it('renders 4 grouped lanes as non-overlapping swarms with lane labels', () => {
+    const layout = compileChart(groupedSpec(200), OPTIONS);
+    const marks = pointMarks(layout);
+    expect(marks).toHaveLength(200);
+    expectNoOverlap(marks);
+
+    // One swarm per lane: 4 distinct lane groups in the data
+    const lanes = new Set(marks.map((m) => String(m.data.region)));
+    expect(lanes).toEqual(new Set(REGIONS));
+
+    // Lane labels render on the band axis
+    const tickLabels = (layout.axes.y?.ticks ?? []).map((t) => t.label);
+    for (const region of REGIONS) {
+      expect(tickLabels).toContain(region);
+    }
+
+    // Each lane's dots cluster around its own band center: lanes must not
+    // share a mean cross-axis position.
+    const meansByLane = REGIONS.map((region) => {
+      const laneMarks = marks.filter((m) => m.data.region === region);
+      return laneMarks.reduce((sum, m) => sum + m.cy, 0) / laneMarks.length;
+    });
+    const uniqueMeans = new Set(meansByLane.map((m) => Math.round(m / 10)));
+    expect(uniqueMeans.size).toBe(REGIONS.length);
+  });
+
+  it('renders a vertical swarm when y is quantitative', () => {
+    const data = [
+      { income: 20, region: 'West' },
+      { income: 140, region: 'West' },
+    ];
+    const layout = compileChart(
+      {
+        mark: 'beeswarm' as const,
+        data,
+        encoding: {
+          y: { field: 'income', type: 'quantitative' as const },
+          x: { field: 'region', type: 'nominal' as const },
+        },
+      },
+      OPTIONS,
+    );
+    const marks = pointMarks(layout);
+    expect(marks).toHaveLength(2);
+    // SVG y grows downward: the larger value sits higher (smaller cy)
+    const low = marks.find((m) => m.data.income === 20)!;
+    const high = marks.find((m) => m.data.income === 140)!;
+    expect(high.cy).toBeLessThan(low.cy);
+  });
+
+  it('sizes dots from the size encoding and keeps them collision-free', () => {
+    const spec = {
+      ...groupedSpec(120),
+      encoding: {
+        ...groupedSpec(120).encoding,
+        size: { field: 'pop', type: 'quantitative' as const },
+      },
+    };
+    const layout = compileChart(spec, OPTIONS);
+    const marks = pointMarks(layout);
+    const radii = new Set(marks.map((m) => m.r));
+    expect(radii.size).toBeGreaterThan(1);
+    for (const mark of marks) {
+      expect(mark.r).toBeGreaterThanOrEqual(2);
+      expect(mark.r).toBeLessThanOrEqual(10);
+    }
+    expectNoOverlap(marks);
+  });
+
+  it('stamps stable unique keys on every dot', () => {
+    const layout = compileChart(singleLaneSpec(100), OPTIONS);
+    const keys = pointMarks(layout).map((m) => m.key);
+    expect(keys.every((k) => typeof k === 'string' && k.length > 0)).toBe(true);
+    expect(new Set(keys).size).toBe(keys.length);
+  });
+
+  it('produces tooltips and a11y coverage for every dot', () => {
+    const layout = compileChart(groupedSpec(40), OPTIONS);
+    const marks = pointMarks(layout);
+    expect(layout.tooltipDescriptors.size).toBe(marks.length);
+    expect(layout.a11y.keyboardNavigable).toBe(true);
+    expect(layout.a11y.altText).toContain('Beeswarm chart');
+    expect(layout.a11y.altText).toContain('distribution of income by region');
+    for (const mark of marks) {
+      expect(mark.aria.label).toContain('income=');
+    }
+  });
+});
+
+describe('beeswarm validation', () => {
+  it('rejects a spec with two quantitative axes', () => {
+    expect(() =>
+      compileChart(
+        {
+          mark: 'beeswarm',
+          data: [{ a: 1, b: 2 }],
+          encoding: {
+            x: { field: 'a', type: 'quantitative' },
+            y: { field: 'b', type: 'quantitative' },
+          },
+        },
+        OPTIONS,
+      ),
+    ).toThrow(/only one quantitative axis/);
+  });
+
+  it('rejects a spec with no positional channel', () => {
+    expect(() =>
+      compileChart({ mark: 'beeswarm', data: [{ a: 1 }], encoding: {} }, OPTIONS),
+    ).toThrow(/quantitative encoding\.x or encoding\.y/);
+  });
+
+  it('rejects a spec where no declared axis is quantitative', () => {
+    expect(() =>
+      compileChart(
+        {
+          mark: 'beeswarm',
+          data: [{ a: 'x', b: 'y' }],
+          encoding: {
+            x: { field: 'a', type: 'nominal' },
+            y: { field: 'b', type: 'nominal' },
+          },
+        },
+        OPTIONS,
+      ),
+    ).toThrow(/requires one quantitative axis/);
+  });
+});
+
+describe('beeswarm overplotting guard', () => {
+  it('warns past the ~2000-point budget and suggests alternatives', () => {
+    const { warnings } = compile(singleLaneSpec(2001));
+    const warning = warnings.find((w) => w.includes('beeswarm'));
+    expect(warning).toBeDefined();
+    expect(warning).toContain('2001 data points');
+    expect(warning).toContain("mark: 'tick'");
+    expect(warning).toContain('histogram');
+  });
+
+  it('stays quiet at or under the budget', () => {
+    const { warnings } = compile(singleLaneSpec(2000));
+    expect(warnings.filter((w) => w.includes('beeswarm'))).toEqual([]);
+  });
+
+  it('never escalates the budget to an error: the chart still compiles', () => {
+    const layout = compileChart(singleLaneSpec(2001), OPTIONS);
+    expect(pointMarks(layout)).toHaveLength(2001);
+  });
+});

package/src/charts/beeswarm/__tests__/dodge.test.ts

@@ -0,0 +1,148 @@
+import { describe, expect, it } from 'vitest';
+import { DEFAULT_DODGE_PADDING, dodgeOffsets } from '../dodge';
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+/** Deterministic pseudo-random sequence (mulberry32) for repeatable fixtures. */
+function seededRandom(seed: number): () => number {
+  let a = seed;
+  return () => {
+    a |= 0;
+    a = (a + 0x6d2b79f5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/** Clustered value-axis positions in [0, 500] that force many collisions. */
+function makePositions(count: number, seed = 42): number[] {
+  const rand = seededRandom(seed);
+  return Array.from({ length: count }, () => {
+    // Sum of two draws clusters values around the middle (triangular-ish)
+    return ((rand() + rand()) / 2) * 500;
+  });
+}
+
+/** Assert every pair of circles keeps at least (r1 + r2) separation. */
+function expectNoOverlap(
+  positions: readonly number[],
+  offsets: readonly number[],
+  radii: readonly number[],
+): void {
+  const epsilon = 1e-6;
+  for (let i = 0; i < positions.length; i++) {
+    for (let j = i + 1; j < positions.length; j++) {
+      const dx = positions[i] - positions[j];
+      const dy = offsets[i] - offsets[j];
+      const dist = Math.sqrt(dx * dx + dy * dy);
+      expect(dist).toBeGreaterThanOrEqual(radii[i] + radii[j] - epsilon);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('dodgeOffsets', () => {
+  it('leaves a single dot at offset 0', () => {
+    expect(dodgeOffsets([100], [4])).toEqual([0]);
+  });
+
+  it('leaves non-colliding dots at offset 0', () => {
+    const offsets = dodgeOffsets([0, 100, 200], [4, 4, 4]);
+    expect(offsets).toEqual([0, 0, 0]);
+  });
+
+  it('produces zero overlapping circles at 300 clustered points', () => {
+    const positions = makePositions(300);
+    const radii = positions.map(() => 4);
+    const offsets = dodgeOffsets(positions, radii);
+    expectNoOverlap(positions, offsets, radii);
+  });
+
+  it('respects per-dot radii (sized dots stay collision-free)', () => {
+    const positions = makePositions(150, 7);
+    const rand = seededRandom(99);
+    const radii = positions.map(() => 2 + rand() * 8);
+    const offsets = dodgeOffsets(positions, radii);
+    expectNoOverlap(positions, offsets, radii);
+  });
+
+  it('is deterministic: same input yields identical output', () => {
+    const positions = makePositions(200, 3);
+    const radii = positions.map(() => 4);
+    const first = dodgeOffsets(positions, radii);
+    const second = dodgeOffsets(positions, radii);
+    expect(second).toEqual(first);
+  });
+
+  it('keeps the first placed dot on the lane center and breaks symmetric ties to the negative side', () => {
+    // Two dots at the same position: the first (by index) stays at 0, the
+    // second must move; both interval edges have equal magnitude, so the
+    // documented tie-break picks the negative side.
+    const offsets = dodgeOffsets([100, 100], [4, 4]);
+    expect(offsets[0]).toBe(0);
+    expect(offsets[1]).toBeLessThan(0);
+    expect(Math.abs(offsets[1])).toBeCloseTo(8 + DEFAULT_DODGE_PADDING, 6);
+  });
+
+  it('places dots at the minimal offset avoiding collisions', () => {
+    // Three dots at one position: center, one side, other side; the third
+    // dot must not leapfrog to a farther slot.
+    const offsets = dodgeOffsets([50, 50, 50], [4, 4, 4]);
+    expect(offsets[0]).toBe(0);
+    const sep = 8 + DEFAULT_DODGE_PADDING;
+    expect(Math.abs(offsets[1])).toBeCloseTo(sep, 6);
+    expect(Math.abs(offsets[2])).toBeCloseTo(sep, 6);
+    expect(Math.sign(offsets[1])).not.toBe(Math.sign(offsets[2]));
+  });
+
+  it('maps offsets back to input order, not sweep order', () => {
+    // Descending input positions: the sweep runs ascending, but each offset
+    // must land on its own input index.
+    const positions = [300, 100, 200];
+    const offsets = dodgeOffsets(positions, [4, 4, 4]);
+    expect(offsets).toEqual([0, 0, 0]);
+  });
+
+  it('dodges only within a lane', () => {
+    // Same position, different lanes: no collision, both stay centered.
+    const separate = dodgeOffsets([100, 100], [4, 4], ['a', 'b']);
+    expect(separate).toEqual([0, 0]);
+
+    // Same lane collides as usual.
+    const together = dodgeOffsets([100, 100], [4, 4], ['a', 'a']);
+    expect(together[1]).not.toBe(0);
+  });
+
+  it('keeps lanes independent and collision-free in mixed input', () => {
+    const rand = seededRandom(11);
+    const lanesPool = ['a', 'b', 'c', 'd'];
+    const positions = makePositions(200, 5);
+    const radii = positions.map(() => 4);
+    const lanes = positions.map(() => lanesPool[Math.floor(rand() * lanesPool.length)]);
+    const offsets = dodgeOffsets(positions, radii, lanes);
+
+    for (const lane of lanesPool) {
+      const idx = positions.map((_, i) => i).filter((i) => lanes[i] === lane);
+      expectNoOverlap(
+        idx.map((i) => positions[i]),
+        idx.map((i) => offsets[i]),
+        idx.map((i) => radii[i]),
+      );
+    }
+  });
+
+  it('honors a custom padding', () => {
+    const offsets = dodgeOffsets([100, 100], [4, 4], undefined, 5);
+    expect(Math.abs(offsets[1])).toBeCloseTo(13, 6);
+  });
+
+  it('returns an empty array for empty input', () => {
+    expect(dodgeOffsets([], [])).toEqual([]);
+  });
+});

package/src/charts/beeswarm/compute.ts

@@ -0,0 +1,203 @@
+/**
+ * Beeswarm chart mark computation.
+ *
+ * One quantitative value axis positions every observation; the deterministic
+ * dodge layout (see ./dodge) spreads colliding dots along the cross axis so
+ * each dot stays visible. An optional nominal channel on the other axis
+ * groups the dots into lanes (one swarm per category via a band scale).
+ * The cross axis has no scale: offsets are pure pixel-space.
+ *
+ * Orientation follows the bar convention: quantitative x = horizontal swarm,
+ * quantitative y = vertical swarm.
+ */
+
+import type {
+  Encoding,
+  GradientDef,
+  LayoutStrategy,
+  MarkAria,
+  PointMark,
+  Rect,
+} from '@opendata-ai/openchart-core';
+import type { ScaleBand, ScaleLinear } from 'd3-scale';
+import { buildSizeScale, SIZE_SCALE_DEFAULTS } from '../../compile/size-scale';
+import { dedupeKeys, serializeKeyValue } from '../../compiler/keys';
+import type { NormalizedChartSpec } from '../../compiler/types';
+import type { ResolvedScales } from '../../layout/scales';
+import { getColor, getSequentialColor } from '../utils';
+import { dodgeOffsets } from './dodge';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/**
+ * Default dot radius (px). Smaller than the scatter default (5) because
+ * beeswarms carry hundreds of dots and the dodge layout trades radius for
+ * swarm height: at r=4 a 300-dot swarm stays inside a typical chart area.
+ */
+const DEFAULT_DOT_RADIUS = 4;
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute beeswarm marks from a normalized chart spec.
+ *
+ * The quantitative channel is the value axis (x = horizontal swarm,
+ * y = vertical). The opposite channel, when present, must be nominal/ordinal
+ * and lanes the dots via its band scale; otherwise all dots share one lane
+ * centered on the cross axis. Radii come from the optional `size` encoding
+ * (sqrt scale, area-proportional) or the default dot radius; the dodge
+ * layout consumes per-dot radii so sized swarms stay collision-free.
+ */
+export function computeBeeswarmMarks(
+  spec: NormalizedChartSpec,
+  scales: ResolvedScales,
+  chartArea: Rect,
+  _strategy: LayoutStrategy,
+): PointMark[] {
+  const encoding = spec.encoding as Encoding;
+
+  // Orientation: prefer a quantitative x (horizontal swarm), else quantitative y.
+  const isHorizontal = encoding.x?.type === 'quantitative';
+  const valueChannel = isHorizontal ? encoding.x : encoding.y;
+  const laneChannel = isHorizontal ? encoding.y : encoding.x;
+  const valueScale = isHorizontal ? scales.x : scales.y;
+  const laneScale = isHorizontal ? scales.y : scales.x;
+
+  if (!valueChannel || valueChannel.type !== 'quantitative' || !valueScale) {
+    return [];
+  }
+
+  const positionScale = valueScale.scale as ScaleLinear<number, number>;
+
+  // Lane centers: band scale when the nominal channel is present, else the
+  // middle of the cross axis. The cross axis itself has no scale: dodge
+  // offsets are pixel-space around each lane center.
+  const bandScale =
+    laneScale && laneScale.type === 'band' ? (laneScale.scale as ScaleBand<string>) : undefined;
+  const defaultLaneCenter = isHorizontal
+    ? chartArea.y + chartArea.height / 2
+    : chartArea.x + chartArea.width / 2;
+
+  const colorEnc = encoding.color && 'field' in encoding.color ? encoding.color : undefined;
+  const isSequentialColor = colorEnc?.type === 'quantitative';
+  const colorField = colorEnc?.field;
+  const sizeEnc = encoding.size && 'field' in encoding.size ? encoding.size : undefined;
+  const sizeField = sizeEnc?.field;
+
+  // Sized dots: sqrt (area-proportional), same override surface as scatter.
+  // Shared builder so the marks and any size legend resolve one scale.
+  const resolvedSize = buildSizeScale(sizeEnc, spec.data, SIZE_SCALE_DEFAULTS.beeswarm);
+  const sizeScale = resolvedSize?.scale;
+
+  // Resolve every renderable dot first: dodge needs the full position/radius
+  // arrays before any mark can be placed.
+  interface ResolvedDot {
+    row: Record<string, unknown>;
+    value: number;
+    position: number;
+    radius: number;
+    lane: string;
+    laneCenter: number;
+  }
+  const dots: ResolvedDot[] = [];
+
+  for (const row of spec.data) {
+    const raw = row[valueChannel.field];
+    // Drop null/undefined explicitly: the validator tolerates them (it only
+    // rejects non-numeric or non-finite present values), but Number(null) is 0,
+    // which would silently place a phantom dot at value 0 instead of skipping.
+    if (raw == null) continue;
+    const value = Number(raw);
+    if (!Number.isFinite(value)) continue;
+
+    const position = positionScale(value);
+    if (!Number.isFinite(position)) continue;
+
+    let lane = '__default__';
+    let laneCenter = defaultLaneCenter;
+    if (bandScale && laneChannel) {
+      lane = String(row[laneChannel.field] ?? '');
+      const bandStart = bandScale(lane);
+      if (bandStart === undefined) continue;
+      laneCenter = bandStart + bandScale.bandwidth() / 2;
+    }
+
+    let radius = DEFAULT_DOT_RADIUS;
+    if (sizeScale && sizeField) {
+      const sizeVal = Number(row[sizeField]);
+      if (Number.isFinite(sizeVal)) {
+        radius = sizeScale(sizeVal);
+      }
+    }
+
+    dots.push({ row: row as Record<string, unknown>, value, position, radius, lane, laneCenter });
+  }
+
+  const offsets = dodgeOffsets(
+    dots.map((d) => d.position),
+    dots.map((d) => d.radius),
+    dots.map((d) => d.lane),
+  );
+
+  const keyEnc = encoding.key && 'field' in encoding.key ? encoding.key : undefined;
+  const keyField = keyEnc?.field;
+  const marks: PointMark[] = [];
+
+  for (let i = 0; i < dots.length; i++) {
+    const dot = dots[i];
+    const cross = dot.laneCenter + offsets[i];
+
+    let color: string | GradientDef;
+    if (isSequentialColor && colorField) {
+      const colorVal = Number(dot.row[colorField]);
+      color = Number.isFinite(colorVal)
+        ? getSequentialColor(scales, colorVal)
+        : getColor(scales, '__default__');
+    } else if (colorField) {
+      color = getColor(scales, String(dot.row[colorField] ?? '__default__'));
+    } else {
+      color = getColor(scales, '__default__');
+    }
+
+    const labelParts = [`${valueChannel.field}=${dot.row[valueChannel.field]}`];
+    if (laneChannel && dot.lane !== '__default__') {
+      labelParts.push(`${laneChannel.field}=${dot.lane}`);
+    }
+    if (sizeField && dot.row[sizeField] != null) {
+      labelParts.push(`${sizeField}=${dot.row[sizeField]}`);
+    }
+
+    const aria: MarkAria = {
+      label: `Data point: ${labelParts.join(', ')}`,
+    };
+
+    marks.push({
+      type: 'point',
+      cx: isHorizontal ? dot.position : cross,
+      cy: isHorizontal ? cross : dot.position,
+      r: dot.radius,
+      fill: color,
+      stroke: '#ffffff',
+      strokeWidth: 1,
+      data: dot.row,
+      aria,
+    });
+  }
+
+  // Stamp keys: encoding.key field when set, else lane|value composite
+  const rawKeys = marks.map((m, i) => {
+    if (keyField) return serializeKeyValue(m.data[keyField]);
+    const valueKey = serializeKeyValue(m.data[valueChannel.field]);
+    return dots[i].lane !== '__default__' ? `${dots[i].lane}|${valueKey}` : valueKey;
+  });
+  const keys = dedupeKeys(rawKeys);
+  for (let i = 0; i < marks.length; i++) {
+    marks[i].key = keys[i];
+  }
+
+  return marks;
+}