@opendata-ai/openchart-engine 1.2.0

package/src/tooltips/__tests__/compute.test.ts

@@ -0,0 +1,328 @@
+import type { ArcMark, Mark, PointMark, Rect, RectMark } from '@opendata-ai/openchart-core';
+import { describe, expect, it } from 'vitest';
+import type { NormalizedChartSpec } from '../../compiler/types';
+import { computeTooltipDescriptors } from '../compute';
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+const _chartArea: Rect = { x: 50, y: 20, width: 500, height: 300 };
+
+function makeLineSpec(): NormalizedChartSpec {
+  return {
+    type: 'line',
+    data: [
+      { date: '2020-01-01', value: 10, country: 'US' },
+      { date: '2021-01-01', value: 40, country: 'US' },
+      { date: '2020-01-01', value: 15, country: 'UK' },
+      { date: '2021-01-01', value: 35, country: 'UK' },
+    ],
+    encoding: {
+      x: { field: 'date', type: 'temporal' },
+      y: { field: 'value', type: 'quantitative' },
+      color: { field: 'country', type: 'nominal' },
+    },
+    chrome: {},
+    annotations: [],
+    responsive: true,
+    theme: {},
+    darkMode: 'off',
+    labels: { density: 'auto', format: '' },
+  };
+}
+
+function makeBarSpec(): NormalizedChartSpec {
+  return {
+    type: 'bar',
+    data: [
+      { category: 'A', value: 100 },
+      { category: 'B', value: 200 },
+      { category: 'C', value: 150 },
+    ],
+    encoding: {
+      x: { field: 'value', type: 'quantitative' },
+      y: { field: 'category', type: 'nominal' },
+    },
+    chrome: {},
+    annotations: [],
+    responsive: true,
+    theme: {},
+    darkMode: 'off',
+    labels: { density: 'auto', format: '' },
+  };
+}
+
+function makePieSpec(): NormalizedChartSpec {
+  return {
+    type: 'pie',
+    data: [
+      { segment: 'Alpha', amount: 30 },
+      { segment: 'Beta', amount: 50 },
+      { segment: 'Gamma', amount: 20 },
+    ],
+    encoding: {
+      y: { field: 'amount', type: 'quantitative' },
+      color: { field: 'segment', type: 'nominal' },
+    },
+    chrome: {},
+    annotations: [],
+    responsive: true,
+    theme: {},
+    darkMode: 'off',
+    labels: { density: 'auto', format: '' },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('computeTooltipDescriptors', () => {
+  describe('point marks (from line charts)', () => {
+    it('generates tooltip for each point mark', () => {
+      const spec = makeLineSpec();
+      const pointMarks: PointMark[] = [
+        {
+          type: 'point',
+          cx: 100,
+          cy: 200,
+          r: 3,
+          fill: '#1b7fa3',
+          stroke: '#fff',
+          strokeWidth: 1.5,
+          fillOpacity: 0,
+          data: { date: '2020-01-01', value: 10, country: 'US' },
+          aria: { label: 'point' },
+        },
+        {
+          type: 'point',
+          cx: 300,
+          cy: 100,
+          r: 3,
+          fill: '#c44e52',
+          stroke: '#fff',
+          strokeWidth: 1.5,
+          fillOpacity: 0,
+          data: { date: '2021-01-01', value: 40, country: 'US' },
+          aria: { label: 'point' },
+        },
+      ];
+
+      const descriptors = computeTooltipDescriptors(spec, pointMarks);
+
+      expect(descriptors.size).toBe(2);
+      expect(descriptors.has('point-0')).toBe(true);
+      expect(descriptors.has('point-1')).toBe(true);
+    });
+
+    it('tooltip includes formatted values', () => {
+      const spec = makeLineSpec();
+      const pointMarks: PointMark[] = [
+        {
+          type: 'point',
+          cx: 100,
+          cy: 200,
+          r: 3,
+          fill: '#1b7fa3',
+          stroke: '#fff',
+          strokeWidth: 1.5,
+          data: { date: '2020-01-01', value: 1500, country: 'US' },
+          aria: { label: 'point' },
+        },
+      ];
+
+      const descriptors = computeTooltipDescriptors(spec, pointMarks);
+      const content = descriptors.get('point-0')!;
+
+      // Should have fields for y (value) and x (date)
+      expect(content.fields.length).toBeGreaterThanOrEqual(1);
+
+      // The value field should be formatted with commas
+      const valueField = content.fields.find((f) => f.label === 'value');
+      expect(valueField).toBeDefined();
+      expect(valueField!.value).toBe('1,500');
+    });
+
+    it('tooltip title uses temporal x-axis value', () => {
+      const spec = makeLineSpec();
+      const pointMarks: PointMark[] = [
+        {
+          type: 'point',
+          cx: 100,
+          cy: 200,
+          r: 3,
+          fill: '#1b7fa3',
+          stroke: '#fff',
+          strokeWidth: 1.5,
+          data: { date: '2020-01-01', value: 10, country: 'US' },
+          aria: { label: 'point' },
+        },
+      ];
+
+      const descriptors = computeTooltipDescriptors(spec, pointMarks);
+      const content = descriptors.get('point-0')!;
+
+      // Title should be the date value
+      expect(content.title).toBeDefined();
+      expect(content.title!.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe('rect marks (from bar charts)', () => {
+    it('generates tooltip for each rect mark', () => {
+      const spec = makeBarSpec();
+      const rectMarks: RectMark[] = [
+        {
+          type: 'rect',
+          x: 50,
+          y: 30,
+          width: 200,
+          height: 40,
+          fill: '#1b7fa3',
+          data: { category: 'A', value: 100 },
+          aria: { label: 'bar' },
+        },
+        {
+          type: 'rect',
+          x: 50,
+          y: 80,
+          width: 400,
+          height: 40,
+          fill: '#1b7fa3',
+          data: { category: 'B', value: 200 },
+          aria: { label: 'bar' },
+        },
+      ];
+
+      const descriptors = computeTooltipDescriptors(spec, rectMarks);
+
+      expect(descriptors.size).toBe(2);
+      expect(descriptors.has('rect-0')).toBe(true);
+      expect(descriptors.has('rect-1')).toBe(true);
+    });
+
+    it('rect tooltip includes category as title', () => {
+      const spec = makeBarSpec();
+      const rectMarks: RectMark[] = [
+        {
+          type: 'rect',
+          x: 50,
+          y: 30,
+          width: 200,
+          height: 40,
+          fill: '#1b7fa3',
+          data: { category: 'A', value: 100 },
+          aria: { label: 'bar' },
+        },
+      ];
+
+      const descriptors = computeTooltipDescriptors(spec, rectMarks);
+      const content = descriptors.get('rect-0')!;
+
+      // Nominal y-axis = category as title
+      expect(content.title).toBe('A');
+    });
+  });
+
+  describe('arc marks (from pie charts)', () => {
+    it('generates tooltip for each arc mark', () => {
+      const spec = makePieSpec();
+      const arcMarks: ArcMark[] = [
+        {
+          type: 'arc',
+          path: 'M0,0L10,0A10,10,0,0,1,0,10Z',
+          centroid: { x: 5, y: 5 },
+          innerRadius: 0,
+          outerRadius: 100,
+          startAngle: 0,
+          endAngle: 1.5,
+          fill: '#1b7fa3',
+          stroke: '#fff',
+          strokeWidth: 1,
+          data: { segment: 'Alpha', amount: 30 },
+          aria: { label: 'arc' },
+        },
+      ];
+
+      const descriptors = computeTooltipDescriptors(spec, arcMarks);
+
+      expect(descriptors.size).toBe(1);
+      expect(descriptors.has('arc-0')).toBe(true);
+    });
+
+    it('arc tooltip uses color field as title', () => {
+      const spec = makePieSpec();
+      const arcMarks: ArcMark[] = [
+        {
+          type: 'arc',
+          path: 'M0,0',
+          centroid: { x: 5, y: 5 },
+          innerRadius: 0,
+          outerRadius: 100,
+          startAngle: 0,
+          endAngle: 1.5,
+          fill: '#1b7fa3',
+          stroke: '#fff',
+          strokeWidth: 1,
+          data: { segment: 'Alpha', amount: 30 },
+          aria: { label: 'arc' },
+        },
+      ];
+
+      const descriptors = computeTooltipDescriptors(spec, arcMarks);
+      const content = descriptors.get('arc-0')!;
+
+      expect(content.title).toBe('Alpha');
+    });
+  });
+
+  describe('line and area marks', () => {
+    it('line marks do not generate tooltips (points do instead)', () => {
+      const spec = makeLineSpec();
+      const marks: Mark[] = [
+        {
+          type: 'line',
+          points: [
+            { x: 100, y: 200 },
+            { x: 300, y: 100 },
+          ],
+          stroke: '#1b7fa3',
+          strokeWidth: 2,
+          data: [{ date: '2020-01-01', value: 10 }],
+          aria: { label: 'line' },
+        },
+      ];
+
+      const descriptors = computeTooltipDescriptors(spec, marks);
+      expect(descriptors.size).toBe(0);
+    });
+
+    it('area marks do not generate tooltips (points do instead)', () => {
+      const spec = makeLineSpec();
+      const marks: Mark[] = [
+        {
+          type: 'area',
+          topPoints: [{ x: 100, y: 200 }],
+          bottomPoints: [{ x: 100, y: 300 }],
+          path: 'M0,0',
+          fill: '#1b7fa3',
+          fillOpacity: 0.3,
+          data: [{ date: '2020-01-01', value: 10 }],
+          aria: { label: 'area' },
+        },
+      ];
+
+      const descriptors = computeTooltipDescriptors(spec, marks);
+      expect(descriptors.size).toBe(0);
+    });
+  });
+
+  describe('empty data', () => {
+    it('returns empty map for no marks', () => {
+      const spec = makeLineSpec();
+      const descriptors = computeTooltipDescriptors(spec, []);
+      expect(descriptors.size).toBe(0);
+    });
+  });
+});

package/src/tooltips/compute.ts

@@ -0,0 +1,231 @@
+/**
+ * Tooltip descriptor computation.
+ *
+ * Generates a Map of mark-id -> TooltipContent from the spec encoding and marks.
+ * Each mark gets a tooltip that shows relevant field values formatted for display.
+ * The mark-id keys match the data-mark-id attributes set by the SVG renderer.
+ */
+
+import type {
+  ArcMark,
+  AreaMark,
+  DataRow,
+  Encoding,
+  LineMark,
+  Mark,
+  PointMark,
+  RectMark,
+  TooltipContent,
+  TooltipField,
+} from '@opendata-ai/openchart-core';
+import { formatDate, formatNumber } from '@opendata-ai/openchart-core';
+import { format as d3Format } from 'd3-format';
+
+import type { NormalizedChartSpec } from '../compiler/types';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Format a raw data value for tooltip display. */
+function formatValue(value: unknown, fieldType?: string, format?: string): string {
+  if (value == null) return '';
+
+  if (fieldType === 'temporal' || value instanceof Date) {
+    return formatDate(value as Date | string | number);
+  }
+
+  if (typeof value === 'number') {
+    if (format) {
+      try {
+        return d3Format(format)(value);
+      } catch {
+        return formatNumber(value);
+      }
+    }
+    return formatNumber(value);
+  }
+
+  return String(value);
+}
+
+/** Build tooltip fields from a data row based on the spec encoding. */
+function buildFields(row: DataRow, encoding: Encoding, color?: string): TooltipField[] {
+  const fields: TooltipField[] = [];
+
+  // Y-axis value (the "main" value in most charts)
+  if (encoding.y) {
+    fields.push({
+      label: encoding.y.axis?.label ?? encoding.y.field,
+      value: formatValue(row[encoding.y.field], encoding.y.type, encoding.y.axis?.format),
+      color,
+    });
+  }
+
+  // X-axis value (often the category or date)
+  if (encoding.x) {
+    fields.push({
+      label: encoding.x.axis?.label ?? encoding.x.field,
+      value: formatValue(row[encoding.x.field], encoding.x.type, encoding.x.axis?.format),
+    });
+  }
+
+  // Size (for scatter/bubble)
+  if (encoding.size) {
+    fields.push({
+      label: encoding.size.axis?.label ?? encoding.size.field,
+      value: formatValue(row[encoding.size.field], encoding.size.type, encoding.size.axis?.format),
+    });
+  }
+
+  return fields;
+}
+
+/** Determine the title for a tooltip based on encoding. */
+function getTooltipTitle(row: DataRow, encoding: Encoding): string | undefined {
+  // For charts with a temporal x-axis, use the date as the title
+  if (encoding.x?.type === 'temporal') {
+    return formatValue(row[encoding.x.field], 'temporal');
+  }
+
+  // For nominal x, use the category
+  if (encoding.x?.type === 'nominal' || encoding.x?.type === 'ordinal') {
+    return String(row[encoding.x.field] ?? '');
+  }
+
+  // For nominal y (e.g. horizontal bar charts), use the category
+  if (encoding.y?.type === 'nominal' || encoding.y?.type === 'ordinal') {
+    return String(row[encoding.y.field] ?? '');
+  }
+
+  // For color-encoded series, use the series name
+  if (encoding.color) {
+    return String(row[encoding.color.field] ?? '');
+  }
+
+  return undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Per-mark-type tooltip generation
+// ---------------------------------------------------------------------------
+
+function tooltipsForLine(
+  _mark: LineMark,
+  _encoding: Encoding,
+  _markIndex: number,
+): Array<[string, TooltipContent]> {
+  // Line marks themselves don't get individual tooltips.
+  // The point marks at each data point handle that.
+  return [];
+}
+
+function tooltipsForPoint(
+  mark: PointMark,
+  encoding: Encoding,
+  markIndex: number,
+): Array<[string, TooltipContent]> {
+  const title = getTooltipTitle(mark.data, encoding);
+  const fields = buildFields(mark.data, encoding, mark.fill);
+
+  return [[`point-${markIndex}`, { title, fields }]];
+}
+
+function tooltipsForRect(
+  mark: RectMark,
+  encoding: Encoding,
+  markIndex: number,
+): Array<[string, TooltipContent]> {
+  const title = getTooltipTitle(mark.data, encoding);
+  const fields = buildFields(mark.data, encoding, mark.fill);
+
+  return [[`rect-${markIndex}`, { title, fields }]];
+}
+
+function tooltipsForArc(
+  mark: ArcMark,
+  encoding: Encoding,
+  markIndex: number,
+): Array<[string, TooltipContent]> {
+  const row = mark.data;
+  const fields: TooltipField[] = [];
+
+  // For pie/donut, show the category and its value
+  if (encoding.color) {
+    const categoryName = String(row[encoding.color.field] ?? '');
+    if (encoding.y) {
+      fields.push({
+        label: categoryName,
+        value: formatValue(row[encoding.y.field], encoding.y.type, encoding.y.axis?.format),
+        color: mark.fill,
+      });
+    }
+  } else if (encoding.y) {
+    fields.push({
+      label: encoding.y.field,
+      value: formatValue(row[encoding.y.field], encoding.y.type, encoding.y.axis?.format),
+      color: mark.fill,
+    });
+  }
+
+  const title = encoding.color ? String(row[encoding.color.field] ?? '') : undefined;
+
+  return [[`arc-${markIndex}`, { title, fields }]];
+}
+
+function tooltipsForArea(
+  _mark: AreaMark,
+  _encoding: Encoding,
+  _markIndex: number,
+): Array<[string, TooltipContent]> {
+  // Area marks are background fills; point marks on top handle tooltips.
+  return [];
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute tooltip descriptors for all marks in the layout.
+ *
+ * Returns a Map keyed by data-mark-id (matching the SVG attribute)
+ * to TooltipContent objects. The vanilla adapter uses this to show
+ * tooltips on hover/tap/keyboard focus.
+ */
+export function computeTooltipDescriptors(
+  spec: NormalizedChartSpec,
+  marks: Mark[],
+): Map<string, TooltipContent> {
+  const encoding = spec.encoding as Encoding;
+  const descriptors = new Map<string, TooltipContent>();
+
+  for (let i = 0; i < marks.length; i++) {
+    const mark = marks[i];
+    let entries: Array<[string, TooltipContent]> = [];
+
+    switch (mark.type) {
+      case 'line':
+        entries = tooltipsForLine(mark, encoding, i);
+        break;
+      case 'area':
+        entries = tooltipsForArea(mark, encoding, i);
+        break;
+      case 'point':
+        entries = tooltipsForPoint(mark, encoding, i);
+        break;
+      case 'rect':
+        entries = tooltipsForRect(mark, encoding, i);
+        break;
+      case 'arc':
+        entries = tooltipsForArc(mark, encoding, i);
+        break;
+    }
+
+    for (const [key, content] of entries) {
+      descriptors.set(key, content);
+    }
+  }
+
+  return descriptors;
+}