@opendata-ai/openchart-engine 8.0.0-rc.10 → 8.0.0-rc.11

package/src/charts/range/compute.ts

@@ -1,273 +0,0 @@
-/**
- * Range chart mark computation (dumbbell / arrow / range bar).
- *
- * A band scale on the nominal axis and two quantitative positions per row
- * (x + x2 horizontal, or y + y2 vertical). Three styles via markDef.style:
- * - 'dumbbell' (default): connector rule + a dot at each end. The start dot
- *   is muted, the end dot carries the accent color.
- * - 'arrow': shaft rule + chevron arrowhead at the x2/y2 end, built from the
- *   shared computeArrowheadPoints geometry.
- * - 'bar': plain floating RectMark spanning start to end.
- *
- * Coloring precedence for the accent (connector/shaft/bar + end dot):
- * field-based encoding.color > markDef.colorByDirection (positive/negative
- * semantic tokens) > scales.defaultColor (markDef.fill or first palette color).
- */
-
-import type {
-  Encoding,
-  LayoutStrategy,
-  Mark,
-  MarkAria,
-  Rect,
-  ResolvedTheme,
-} from '@opendata-ai/openchart-core';
-import { getRepresentativeColor } from '@opendata-ai/openchart-core';
-import type { ScaleBand, ScaleLinear } from 'd3-scale';
-
-import { computeArrowheadPoints } from '../../annotations/geometry';
-import { dedupeKeys, serializeKeyValue } from '../../compiler/keys';
-import type { NormalizedChartSpec } from '../../compiler/types';
-import type { ResolvedScales } from '../../layout/scales';
-import { getColor } from '../utils';
-
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-
-const DOT_RADIUS = 6;
-const CONNECTOR_WIDTH = 2;
-const CONNECTOR_COLOR = '#cccccc';
-const ARROW_STROKE_WIDTH = 2;
-const ARROWHEAD_LENGTH = 8;
-const ARROWHEAD_HALF_WIDTH = 4;
-
-/** Range mark style variants. */
-export type RangeStyle = 'dumbbell' | 'arrow' | 'bar';
-
-// ---------------------------------------------------------------------------
-// Orientation helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Resolve the range orientation from resolved scales.
- * Horizontal (nominal y, the common editorial form) when y is a band scale;
- * vertical when x is a band scale.
- */
-export function resolveRangeOrientation(scales: ResolvedScales): 'horizontal' | 'vertical' | null {
-  if (
-    scales.y?.type === 'band' &&
-    typeof (scales.y.scale as ScaleBand<string>).bandwidth === 'function'
-  ) {
-    return 'horizontal';
-  }
-  if (
-    scales.x?.type === 'band' &&
-    typeof (scales.x.scale as ScaleBand<string>).bandwidth === 'function'
-  ) {
-    return 'vertical';
-  }
-  return null;
-}
-
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-
-/**
- * Compute range marks from a normalized chart spec.
- *
- * Emission order per data row is stable and load-bearing for the label pass:
- * connector/shaft/bar first (so dots layer on top), then the start dot, then
- * the end dot (dumbbell style only).
- */
-export function computeRangeMarks(
-  spec: NormalizedChartSpec,
-  scales: ResolvedScales,
-  _chartArea: Rect,
-  _strategy: LayoutStrategy,
-  theme: ResolvedTheme,
-): Mark[] {
-  const encoding = spec.encoding as Encoding;
-  const orientation = resolveRangeOrientation(scales);
-  if (!orientation || !scales.x || !scales.y) return [];
-
-  const horizontal = orientation === 'horizontal';
-  const catChannel = horizontal ? encoding.y : encoding.x;
-  const startChannel = horizontal ? encoding.x : encoding.y;
-  const endChannel = horizontal ? encoding.x2 : encoding.y2;
-  if (!catChannel || !startChannel || !endChannel) return [];
-
-  const bandScale = (horizontal ? scales.y.scale : scales.x.scale) as ScaleBand<string>;
-  const valueScale = (horizontal ? scales.x.scale : scales.y.scale) as ScaleLinear<number, number>;
-  const bandwidth = bandScale.bandwidth();
-
-  const style: RangeStyle = spec.markDef.style ?? 'dumbbell';
-  const colorEnc = encoding.color && 'field' in encoding.color ? encoding.color : undefined;
-  const colorByDirection = spec.markDef.colorByDirection === true && !colorEnc;
-
-  // Stable identity keys per category row (deduped for repeated categories).
-  const catKeys = dedupeKeys(spec.data.map((row) => serializeKeyValue(row[catChannel.field])));
-
-  const marks: Mark[] = [];
-
-  for (let i = 0; i < spec.data.length; i++) {
-    const row = spec.data[i];
-    const category = String(row[catChannel.field] ?? '');
-    const bandPos = bandScale(category);
-    if (bandPos === undefined) continue;
-
-    const startRaw = row[startChannel.field];
-    const endRaw = row[endChannel.field];
-    if (startRaw == null || endRaw == null) continue;
-    const startVal = Number(startRaw);
-    const endVal = Number(endRaw);
-    if (!Number.isFinite(startVal) || !Number.isFinite(endVal)) continue;
-
-    const center = bandPos + bandwidth / 2;
-    const pStart = valueScale(startVal);
-    const pEnd = valueScale(endVal);
-    const delta = endVal - startVal;
-    const catKey = catKeys[i];
-
-    // Accent: field color > direction color > default (markDef.fill / palette).
-    const accent = colorEnc
-      ? getColor(scales, String(row[colorEnc.field] ?? ''))
-      : colorByDirection
-        ? delta > 0
-          ? theme.colors.positive
-          : delta < 0
-            ? theme.colors.negative
-            : theme.colors.axis
-        : getColor(scales, '__default__');
-    const accentStroke = getRepresentativeColor(accent);
-
-    const spanAria: MarkAria = {
-      label: `${category}: ${startVal} to ${endVal}`,
-    };
-
-    // Pixel endpoints in x/y space
-    const x1 = horizontal ? pStart : center;
-    const y1 = horizontal ? center : pStart;
-    const x2 = horizontal ? pEnd : center;
-    const y2 = horizontal ? center : pEnd;
-    const spanLength = Math.abs(pEnd - pStart);
-
-    if (style === 'bar') {
-      marks.push({
-        type: 'rect',
-        x: horizontal ? Math.min(pStart, pEnd) : bandPos,
-        y: horizontal ? bandPos : Math.min(pStart, pEnd),
-        width: horizontal ? spanLength : bandwidth,
-        height: horizontal ? bandwidth : spanLength,
-        fill: accent,
-        data: row as Record<string, unknown>,
-        aria: spanAria,
-        key: catKey,
-        orient: horizontal ? 'horizontal' : 'vertical',
-      });
-      continue;
-    }
-
-    if (style === 'arrow') {
-      if (spanLength > 0) {
-        marks.push({
-          type: 'rule',
-          x1,
-          y1,
-          x2,
-          y2,
-          stroke: accentStroke,
-          strokeWidth: ARROW_STROKE_WIDTH,
-          data: row as Record<string, unknown>,
-          aria: spanAria,
-          key: `${catKey}|range`,
-        });
-
-        // Chevron arrowhead at the end value, from the shared geometry helper.
-        const head = computeArrowheadPoints(
-          x2,
-          y2,
-          x2 - x1,
-          y2 - y1,
-          ARROWHEAD_LENGTH,
-          ARROWHEAD_HALF_WIDTH,
-        );
-        const headAria: MarkAria = { label: spanAria.label, decorative: true };
-        marks.push(
-          {
-            type: 'rule',
-            x1: head.baseLeft.x,
-            y1: head.baseLeft.y,
-            x2: head.tip.x,
-            y2: head.tip.y,
-            stroke: accentStroke,
-            strokeWidth: ARROW_STROKE_WIDTH,
-            data: row as Record<string, unknown>,
-            aria: headAria,
-            key: `${catKey}|head-left`,
-          },
-          {
-            type: 'rule',
-            x1: head.baseRight.x,
-            y1: head.baseRight.y,
-            x2: head.tip.x,
-            y2: head.tip.y,
-            stroke: accentStroke,
-            strokeWidth: ARROW_STROKE_WIDTH,
-            data: row as Record<string, unknown>,
-            aria: headAria,
-            key: `${catKey}|head-right`,
-          },
-        );
-      }
-      continue;
-    }
-
-    // Dumbbell (default): connector + muted start dot + accent end dot.
-    if (spanLength > 0) {
-      const connectorColor = colorEnc || colorByDirection ? accentStroke : CONNECTOR_COLOR;
-      marks.push({
-        type: 'rule',
-        x1,
-        y1,
-        x2,
-        y2,
-        stroke: connectorColor,
-        strokeWidth: CONNECTOR_WIDTH,
-        data: row as Record<string, unknown>,
-        aria: spanAria,
-        key: `${catKey}|range`,
-      });
-    }
-
-    marks.push(
-      {
-        type: 'point',
-        cx: x1,
-        cy: y1,
-        r: DOT_RADIUS,
-        fill: theme.colors.axis,
-        stroke: '#ffffff',
-        strokeWidth: 2,
-        data: row as Record<string, unknown>,
-        aria: { label: `${category}, start: ${startVal}` },
-        key: `${catKey}|start`,
-      },
-      {
-        type: 'point',
-        cx: x2,
-        cy: y2,
-        r: DOT_RADIUS,
-        fill: accent,
-        stroke: '#ffffff',
-        strokeWidth: 2,
-        data: row as Record<string, unknown>,
-        aria: { label: `${category}, end: ${endVal}` },
-        key: `${catKey}|end`,
-      },
-    );
-  }
-
-  return marks;
-}

package/src/charts/range/index.ts

@@ -1,82 +0,0 @@
-/**
- * Range chart module (dumbbell / arrow / range bar).
- *
- * Exports the range chart renderer and computation functions.
- */
-
-import type { PointMark } from '@opendata-ai/openchart-core';
-import { resolveFieldFormatter } from '../../format/field-format';
-import type { ChartRenderer } from '../registry';
-import { computeRangeMarks, resolveRangeOrientation } from './compute';
-import { computeRangeLabels, type RangeDotPair } from './labels';
-
-// ---------------------------------------------------------------------------
-// Range chart renderer
-// ---------------------------------------------------------------------------
-
-/**
- * Range chart renderer.
- *
- * Produces connector/shaft/bar spans plus dot pairs (dumbbell style).
- * Both-end value labels are attached to the dumbbell dot marks; arrow and
- * bar styles have no dot anchors and render without value labels.
- */
-export const rangeRenderer: ChartRenderer = (spec, scales, chartArea, strategy, theme) => {
-  const marks = computeRangeMarks(spec, scales, chartArea, strategy, theme);
-
-  const style = spec.markDef.style ?? 'dumbbell';
-  if (style !== 'dumbbell') return marks;
-
-  // Dumbbell dots are emitted in (start, end) order per row; pair them up
-  // for the both-end label pass.
-  const dots = marks.filter((m): m is PointMark => m.type === 'point');
-  const pairs: RangeDotPair[] = [];
-  for (let i = 0; i + 1 < dots.length; i += 2) {
-    pairs.push({ start: dots[i], end: dots[i + 1] });
-  }
-
-  const orientation = resolveRangeOrientation(scales);
-  const horizontal = orientation !== 'vertical';
-  const encoding = spec.encoding;
-  const startChannel = horizontal ? encoding.x : encoding.y;
-  const endChannel = horizontal ? encoding.x2 : encoding.y2;
-
-  const startField = startChannel && 'field' in startChannel ? startChannel.field : undefined;
-  const endField = endChannel && 'field' in endChannel ? endChannel.field : undefined;
-  const startValues = startField ? spec.data.map((r) => r[startField]) : [];
-  const endValues = endField ? spec.data.map((r) => r[endField]) : [];
-  const labelFormatter = resolveFieldFormatter({
-    surfaceFormat: spec.labels.format,
-    channelFormat: startChannel && 'format' in startChannel ? startChannel.format : undefined,
-    values: [...startValues, ...endValues],
-  });
-  const labels = computeRangeLabels(
-    pairs,
-    horizontal,
-    spec.labels.density,
-    spec.labels.prefix,
-    labelFormatter,
-    startField,
-    endField,
-  );
-
-  // Attach labels back onto their dots via the index carried through the
-  // label pass (pairIndex * 2 = start dot, pairIndex * 2 + 1 = end dot).
-  for (const label of labels) {
-    if (label.index === undefined) continue;
-    const pair = pairs[Math.floor(label.index / 2)];
-    if (!pair) continue;
-    const dot = label.index % 2 === 0 ? pair.start : pair.end;
-    dot.label = label;
-  }
-
-  return marks;
-};
-
-// ---------------------------------------------------------------------------
-// Public exports
-// ---------------------------------------------------------------------------
-
-export { computeRangeMarks, resolveRangeOrientation } from './compute';
-export type { RangeDotPair } from './labels';
-export { computeRangeLabels } from './labels';

package/src/charts/range/labels.ts

@@ -1,169 +0,0 @@
-/**
- * Range chart label computation (dumbbell style).
- *
- * Produces value labels at both ends of each dumbbell: outside the range span
- * so labels never sit on the connector. Horizontal ranges label left of the
- * lower-value dot and right of the higher-value dot; vertical ranges label
- * below the lower dot and above the upper dot.
- *
- * Respects the spec's label density setting the same way dot labels do:
- * - 'all': show every label, skip collision detection
- * - 'auto': collision detection drops overlapping labels
- * - 'endpoints': first and last rows only
- * - 'none': return empty array
- */
-
-import type {
-  LabelCandidate,
-  LabelDensity,
-  NumberFormatter,
-  PointMark,
-  ResolvedLabel,
-} from '@opendata-ai/openchart-core';
-import {
-  estimateTextWidth,
-  getRepresentativeColor,
-  resolveCollisions,
-} from '@opendata-ai/openchart-core';
-import { filterByDensity } from '../_shared/density-filter';
-import { formatLabelValue } from '../_shared/format-label-value';
-
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-
-const LABEL_FONT_SIZE = 11;
-const LABEL_FONT_WEIGHT = 600;
-const LABEL_OFFSET = 10;
-
-/** A start/end dot pair for one data row. */
-export interface RangeDotPair {
-  start: PointMark;
-  end: PointMark;
-}
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/** Format one endpoint value using the spec's label format/prefix. */
-function formatEndpoint(
-  value: unknown,
-  formatter: ((n: number) => string) | null,
-  prefix: string | undefined,
-): string | null {
-  const num = Number(value);
-  if (!Number.isFinite(num)) return null;
-  const text = formatter ? formatter(num) : formatLabelValue(num);
-  return prefix ? prefix + text : text;
-}
-
-/** Build one label candidate placed outside the range span. */
-function buildCandidate(
-  mark: PointMark,
-  text: string,
-  horizontal: boolean,
-  outerSide: 'min' | 'max',
-  index: number,
-): LabelCandidate {
-  const textWidth = estimateTextWidth(text, LABEL_FONT_SIZE, LABEL_FONT_WEIGHT);
-  const textHeight = LABEL_FONT_SIZE * 1.2;
-
-  let anchorX: number;
-  let anchorY: number;
-  if (horizontal) {
-    // 'min' dot: label to the left; 'max' dot: label to the right.
-    anchorX =
-      outerSide === 'min'
-        ? mark.cx - mark.r - LABEL_OFFSET - textWidth
-        : mark.cx + mark.r + LABEL_OFFSET;
-    anchorY = mark.cy - textHeight / 2;
-  } else {
-    // SVG y grows downward: the 'min' value dot sits lower, label below it.
-    anchorX = mark.cx - textWidth / 2;
-    anchorY =
-      outerSide === 'min'
-        ? mark.cy + mark.r + LABEL_OFFSET - textHeight / 2
-        : mark.cy - mark.r - LABEL_OFFSET - textHeight / 2;
-  }
-
-  return {
-    text,
-    anchorX,
-    anchorY,
-    width: textWidth,
-    height: textHeight,
-    priority: 'data',
-    index,
-    style: {
-      fontFamily: 'system-ui, -apple-system, sans-serif',
-      fontSize: LABEL_FONT_SIZE,
-      fontWeight: LABEL_FONT_WEIGHT,
-      fill: getRepresentativeColor(mark.fill),
-      lineHeight: 1.2,
-      textAnchor: 'start',
-      dominantBaseline: 'central',
-      fontVariant: 'tabular-nums',
-    },
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-
-/**
- * Compute both-end value labels for dumbbell range marks.
- *
- * Each returned label carries `index` = pairIndex * 2 (start dot) or
- * pairIndex * 2 + 1 (end dot) so the caller can attach labels back onto the
- * right dot marks after density filtering. Labels dropped by collision
- * resolution come back with `visible: false`.
- */
-export function computeRangeLabels(
-  pairs: RangeDotPair[],
-  horizontal: boolean,
-  density: LabelDensity = 'auto',
-  labelPrefix?: string,
-  labelFormatter?: NumberFormatter | null,
-  startField?: string,
-  endField?: string,
-): ResolvedLabel[] {
-  if (density === 'none' || !startField || !endField) return [];
-
-  const indexed = pairs.map((pair, pairIndex) => ({ pair, pairIndex }));
-  const targetPairs = filterByDensity(indexed, density);
-  const formatter = labelFormatter ?? null;
-  const candidates: LabelCandidate[] = [];
-
-  for (const { pair, pairIndex } of targetPairs) {
-    const startText = formatEndpoint(pair.start.data[startField], formatter, labelPrefix);
-    const endText = formatEndpoint(pair.end.data[endField], formatter, labelPrefix);
-    if (startText == null || endText == null) continue;
-
-    // Place each label on the outer side of its dot. For horizontal ranges
-    // the lower pixel position is the left dot; vertical is inverted (SVG y
-    // grows downward), so the larger cy is the lower-value dot.
-    const startIsMin = horizontal ? pair.start.cx <= pair.end.cx : pair.start.cy >= pair.end.cy;
-    candidates.push(
-      buildCandidate(pair.start, startText, horizontal, startIsMin ? 'min' : 'max', pairIndex * 2),
-      buildCandidate(pair.end, endText, horizontal, startIsMin ? 'max' : 'min', pairIndex * 2 + 1),
-    );
-  }
-
-  if (candidates.length === 0) return [];
-
-  // 'all': skip collision detection, mark everything visible
-  if (density === 'all') {
-    return candidates.map((c) => ({
-      text: c.text,
-      x: c.anchorX,
-      y: c.anchorY,
-      style: c.style,
-      visible: true,
-      index: c.index,
-    }));
-  }
-
-  return resolveCollisions(candidates);
-}

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

@@ -1,120 +0,0 @@
-import type { RectMark } from '@opendata-ai/openchart-core';
-import { describe, expect, it } from 'vitest';
-import { compileChart } from '../../../compile';
-
-/** A 3x2 day/hour grid with a quantitative value: the canonical heatmap shape. */
-const grid = [
-  { day: 'Mon', hour: '9am', v: 3 },
-  { day: 'Mon', hour: '10am', v: 7 },
-  { day: 'Tue', hour: '9am', v: 5 },
-  { day: 'Tue', hour: '10am', v: 9 },
-  { day: 'Wed', hour: '9am', v: 1 },
-  { day: 'Wed', hour: '10am', v: 4 },
-];
-
-function heatmap(data = grid) {
-  return {
-    mark: { type: 'rect' as const },
-    data: [...data],
-    encoding: {
-      x: { field: 'day', type: 'nominal' as const },
-      y: { field: 'hour', type: 'nominal' as const },
-      color: { field: 'v', type: 'quantitative' as const },
-    },
-  };
-}
-
-function cellsOf(spec: Parameters<typeof compileChart>[0]): RectMark[] {
-  const layout = compileChart(spec, { width: 600, height: 400 });
-  return layout.marks.filter((m): m is RectMark => m.type === 'rect');
-}
-
-describe('rect mark (heatmap)', () => {
-  /**
-   * Regression: `rect` used to alias `columnRenderer`, which requires a *linear*
-   * y-scale (it anchors cells to `yScale(0)`). A heatmap bands both axes, so the
-   * renderer hit its bandwidth guard and returned []. `mark: 'rect'` rendered a
-   * blank chart with no error.
-   */
-  it('emits one cell per row instead of a blank chart', () => {
-    const cells = cellsOf(heatmap());
-    expect(cells).toHaveLength(grid.length);
-  });
-
-  it('gives every cell a positive width and height', () => {
-    for (const cell of cellsOf(heatmap())) {
-      expect(cell.width).toBeGreaterThan(0);
-      expect(cell.height).toBeGreaterThan(0);
-    }
-  });
-
-  it('tiles cells into a grid: one distinct x per day, one distinct y per hour', () => {
-    const cells = cellsOf(heatmap());
-    expect(new Set(cells.map((c) => c.x)).size).toBe(3); // Mon/Tue/Wed
-    expect(new Set(cells.map((c) => c.y)).size).toBe(2); // 9am/10am
-  });
-
-  it('colors cells from the quantitative color scale, not a flat default', () => {
-    const fills = new Set(cellsOf(heatmap()).map((c) => String(c.fill)));
-    // Six distinct values -> a sequential ramp must produce more than one color.
-    expect(fills.size).toBeGreaterThan(1);
-  });
-
-  it('keys each cell on its x/y pair so updates match by cell', () => {
-    const keys = cellsOf(heatmap()).map((c) => c.key);
-    expect(new Set(keys).size).toBe(grid.length);
-  });
-
-  it('skips rows whose color value is not finite', () => {
-    const cells = cellsOf(
-      heatmap([...grid, { day: 'Thu', hour: '9am', v: Number.NaN as unknown as number }]),
-    );
-    expect(cells).toHaveLength(grid.length);
-  });
-
-  /**
-   * Cells tile. The band default (0.35) is a *bar* value -- bars need air
-   * between them to read as separate quantities -- and it left the heatmap
-   * looking like a scatter of floating rectangles. A cell gap should be a
-   * hairline gutter, so each cell claims nearly its whole step.
-   */
-  it('tiles cells with only a hairline gutter, not a bar-sized gap', () => {
-    const cells = cellsOf(heatmap());
-    const xs = [...new Set(cells.map((c) => c.x))].sort((a, b) => a - b);
-    const step = xs[1] - xs[0];
-    const cellWidth = cells[0].width;
-    // Cell fills at least 90% of its step (0.35 padding would give ~65%).
-    expect(cellWidth / step).toBeGreaterThan(0.9);
-  });
-
-  it('draws no gridlines: the cells are the grid', () => {
-    const layout = compileChart(heatmap(), { width: 600, height: 400 });
-    expect(layout.axes.y?.gridlines ?? []).toHaveLength(0);
-  });
-
-  /**
-   * A quantitative axis has no bandwidth, so a cell has no width. Emitting
-   * zero-area marks would render an invisible chart -- the exact failure this
-   * renderer exists to end. Bail instead of pretending.
-   */
-  it('emits nothing when an axis is quantitative (no bandwidth to size a cell)', () => {
-    const cells = cellsOf({
-      mark: { type: 'rect' as const },
-      data: [...grid],
-      encoding: {
-        x: { field: 'v', type: 'quantitative' as const },
-        y: { field: 'hour', type: 'nominal' as const },
-        color: { field: 'v', type: 'quantitative' as const },
-      },
-    });
-    expect(cells).toHaveLength(0);
-  });
-
-  it('labels each cell with its x, y, and value for screen readers', () => {
-    const cells = cellsOf(heatmap());
-    const mon9 = cells.find((c) => c.data?.day === 'Mon' && c.data?.hour === '9am');
-    expect(mon9?.aria.label).toContain('Mon');
-    expect(mon9?.aria.label).toContain('9am');
-    expect(mon9?.aria.label).toContain('3');
-  });
-});