@opendata-ai/openchart-engine 6.2.0 → 6.3.0

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

@@ -248,6 +248,127 @@ describe('computeScatterMarks', () => {
       expect(marks).toHaveLength(2);
     });
   });
+
+  describe('nominal y axis', () => {
+    function makeNominalYSpec(): NormalizedChartSpec {
+      return {
+        markType: 'point',
+        markDef: { type: 'point' },
+        data: [
+          { value: 10, category: 'A' },
+          { value: 30, category: 'B' },
+          { value: 50, category: 'C' },
+        ],
+        encoding: {
+          x: { field: 'value', type: 'quantitative' },
+          y: { field: 'category', type: 'nominal' },
+        },
+        chrome: {},
+        annotations: [],
+        responsive: true,
+        theme: {},
+        darkMode: 'off',
+        labels: { density: 'auto', format: '' },
+      };
+    }
+
+    it('produces one PointMark per data row', () => {
+      const spec = makeNominalYSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeScatterMarks(spec, scales, chartArea, fullStrategy);
+
+      expect(marks).toHaveLength(3);
+      expect(marks.every((m) => m.type === 'point')).toBe(true);
+    });
+
+    it('positions are within chart area bounds', () => {
+      const spec = makeNominalYSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeScatterMarks(spec, scales, chartArea, fullStrategy);
+
+      for (const mark of marks) {
+        expect(mark.cx).toBeGreaterThanOrEqual(chartArea.x);
+        expect(mark.cx).toBeLessThanOrEqual(chartArea.x + chartArea.width);
+        expect(mark.cy).toBeGreaterThanOrEqual(chartArea.y);
+        expect(mark.cy).toBeLessThanOrEqual(chartArea.y + chartArea.height);
+      }
+    });
+
+    it('different categories get different y positions', () => {
+      const spec = makeNominalYSpec();
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeScatterMarks(spec, scales, chartArea, fullStrategy);
+
+      const yPositions = marks.map((m) => m.cy);
+      const uniqueYs = new Set(yPositions);
+      expect(uniqueYs.size).toBe(3);
+    });
+  });
+
+  describe('temporal x axis', () => {
+    it('produces marks for temporal x with quantitative y', () => {
+      const spec: NormalizedChartSpec = {
+        markType: 'point',
+        markDef: { type: 'point' },
+        data: [
+          { date: '2020-01-01', value: 10 },
+          { date: '2021-01-01', value: 30 },
+          { date: '2022-01-01', value: 20 },
+        ],
+        encoding: {
+          x: { field: 'date', type: 'temporal' },
+          y: { field: 'value', type: 'quantitative' },
+        },
+        chrome: {},
+        annotations: [],
+        responsive: true,
+        theme: {},
+        darkMode: 'off',
+        labels: { density: 'auto', format: '' },
+      };
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeScatterMarks(spec, scales, chartArea, fullStrategy);
+
+      expect(marks).toHaveLength(3);
+      for (const mark of marks) {
+        expect(mark.cx).toBeGreaterThanOrEqual(chartArea.x);
+        expect(mark.cx).toBeLessThanOrEqual(chartArea.x + chartArea.width);
+      }
+    });
+  });
+
+  describe('nominal x axis', () => {
+    it('produces marks for nominal x with quantitative y', () => {
+      const spec: NormalizedChartSpec = {
+        markType: 'point',
+        markDef: { type: 'point' },
+        data: [
+          { category: 'X', value: 10 },
+          { category: 'Y', value: 30 },
+          { category: 'Z', value: 20 },
+        ],
+        encoding: {
+          x: { field: 'category', type: 'nominal' },
+          y: { field: 'value', type: 'quantitative' },
+        },
+        chrome: {},
+        annotations: [],
+        responsive: true,
+        theme: {},
+        darkMode: 'off',
+        labels: { density: 'auto', format: '' },
+      };
+      const scales = computeScales(spec, chartArea, spec.data);
+      const marks = computeScatterMarks(spec, scales, chartArea, fullStrategy);
+
+      expect(marks).toHaveLength(3);
+
+      // Different categories should produce different x positions
+      const xPositions = marks.map((m) => m.cx);
+      const uniqueXs = new Set(xPositions);
+      expect(uniqueXs.size).toBe(3);
+    });
+  });
 });
 
 // ---------------------------------------------------------------------------

package/src/charts/scatter/compute.ts

@@ -2,20 +2,21 @@
  * Scatter / bubble chart mark computation.
  *
  * Takes a normalized chart spec with resolved scales and produces
- * PointMark[] for rendering scatter plots. Both axes are quantitative.
+ * PointMark[] for rendering scatter plots. Axes can be any field type.
  * Optional size encoding produces area-proportional bubbles via sqrt
  * scaling, and color encoding groups points by category.
  */
 
 import type {
   Encoding,
+  FieldType,
   LayoutStrategy,
   MarkAria,
   PointMark,
   Rect,
 } from '@opendata-ai/openchart-core';
 import { max, min } from 'd3-array';
-import type { ScaleLinear } from 'd3-scale';
+import type { ScaleBand, ScaleLinear, ScalePoint, ScaleTime } from 'd3-scale';
 import { scaleSqrt } from 'd3-scale';
 
 import type { NormalizedChartSpec } from '../../compiler/types';
@@ -30,6 +31,45 @@ const DEFAULT_POINT_RADIUS = 5;
 const MIN_BUBBLE_RADIUS = 3;
 const MAX_BUBBLE_RADIUS = 30;
 
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Resolve a data value to a pixel position based on channel type and scale. */
+function resolvePosition(
+  value: unknown,
+  channelType: FieldType,
+  scale:
+    | ScaleLinear<number, number>
+    | ScaleTime<number, number>
+    | ScaleBand<string>
+    | ScalePoint<string>,
+): number | undefined {
+  switch (channelType) {
+    case 'nominal':
+    case 'ordinal': {
+      const s = String(value);
+      if ('bandwidth' in scale && typeof scale.bandwidth === 'function') {
+        const bw = (scale as ScaleBand<string>).bandwidth();
+        const pos = (scale as ScaleBand<string>)(s);
+        if (pos === undefined) return undefined;
+        // ScalePoint has bandwidth() === 0; ScaleBand has > 0.
+        return bw > 0 ? pos + bw / 2 : pos;
+      }
+      return (scale as ScalePoint<string>)(s);
+    }
+    case 'temporal': {
+      const px = (scale as ScaleTime<number, number>)(new Date(value as string | number));
+      return Number.isNaN(px) ? undefined : px;
+    }
+    default: {
+      const num = Number(value);
+      if (!Number.isFinite(num)) return undefined;
+      return (scale as ScaleLinear<number, number>)(num);
+    }
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -37,8 +77,9 @@ const MAX_BUBBLE_RADIUS = 30;
 /**
  * Compute scatter/bubble marks from a normalized chart spec.
  *
- * Both x and y are quantitative (linear scales). Optional size encoding
- * maps a data field to point radius using sqrt scale (area-proportional).
+ * Axes accept any field type: quantitative (linear), temporal (time),
+ * nominal/ordinal (band or point scale). Optional size encoding maps a
+ * data field to point radius using sqrt scale (area-proportional).
  * Optional color encoding groups points by category with distinct colors.
  */
 export function computeScatterMarks(
@@ -55,8 +96,18 @@ export function computeScatterMarks(
     return [];
   }
 
-  const xScale = scales.x.scale as ScaleLinear<number, number>;
-  const yScale = scales.y.scale as ScaleLinear<number, number>;
+  const xScale = scales.x.scale as
+    | ScaleLinear<number, number>
+    | ScaleTime<number, number>
+    | ScaleBand<string>
+    | ScalePoint<string>;
+  const yScale = scales.y.scale as
+    | ScaleLinear<number, number>
+    | ScaleTime<number, number>
+    | ScaleBand<string>
+    | ScalePoint<string>;
+  const xType = xChannel.type;
+  const yType = yChannel.type;
 
   const colorEnc = encoding.color && 'field' in encoding.color ? encoding.color : undefined;
   const isSequentialColor = colorEnc?.type === 'quantitative';
@@ -79,13 +130,13 @@ export function computeScatterMarks(
   const marks: PointMark[] = [];
 
   for (const row of spec.data) {
-    const xVal = Number(row[xChannel.field]);
-    const yVal = Number(row[yChannel.field]);
+    const rawX = row[xChannel.field];
+    const rawY = row[yChannel.field];
 
-    if (!Number.isFinite(xVal) || !Number.isFinite(yVal)) continue;
+    const cx = resolvePosition(rawX, xType, xScale);
+    const cy = resolvePosition(rawY, yType, yScale);
 
-    const cx = xScale(xVal);
-    const cy = yScale(yVal);
+    if (cx === undefined || cy === undefined) continue;
 
     const category = colorField && !isSequentialColor ? String(row[colorField] ?? '') : undefined;
     let color: string;
@@ -106,7 +157,7 @@ export function computeScatterMarks(
       }
     }
 
-    const labelParts = [`${xChannel.field}=${xVal}`, `${yChannel.field}=${yVal}`];
+    const labelParts = [`${xChannel.field}=${rawX}`, `${yChannel.field}=${rawY}`];
     if (category) labelParts.push(`${colorField}=${category}`);
     if (sizeField && row[sizeField] != null) {
       labelParts.push(`${sizeField}=${row[sizeField]}`);

package/src/compile.ts

@@ -72,6 +72,7 @@ const builtinRenderers: Record<string, ChartRenderer> = {
   arc: pieRenderer, // old 'pie' (donut handled via innerRadius)
   'arc:donut': donutRenderer, // old 'donut'
   circle: dotRenderer, // old 'dot'
+  lollipop: dotRenderer, // semantic alias for dot/circle
   text: textRenderer,
   rule: ruleRenderer,
   tick: tickRenderer,
@@ -442,6 +443,7 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
     strategy,
     theme.isDark,
     obstacles,
+    { width: dims.total.width, height: dims.total.height },
   );
 
   // Compute tooltip descriptors from marks and encoding

package/src/compiler/__tests__/validate.test.ts

@@ -272,6 +272,40 @@ describe('validateSpec', () => {
       expect(fieldError!.code).toBe('MISSING_FIELD');
       expect(fieldError!.suggestion).toContain('a');
     });
+
+    it('accepts tooltip as an array of valid encoding channels', () => {
+      const result = validateSpec({
+        mark: 'bar',
+        data: [{ a: 1, b: 2, c: 3 }],
+        encoding: {
+          x: { field: 'a', type: 'quantitative' },
+          y: { field: 'b', type: 'nominal' },
+          tooltip: [
+            { field: 'a', type: 'quantitative' },
+            { field: 'c', type: 'quantitative' },
+          ],
+        },
+      });
+      expect(result.valid).toBe(true);
+      expect(result.errors).toHaveLength(0);
+    });
+
+    it('rejects tooltip array element with missing field', () => {
+      const result = validateSpec({
+        mark: 'bar',
+        data: [{ a: 1, b: 2 }],
+        encoding: {
+          x: { field: 'a', type: 'quantitative' },
+          y: { field: 'b', type: 'nominal' },
+          tooltip: [{ field: 'a', type: 'quantitative' }, { type: 'quantitative' }],
+        },
+      });
+      expect(result.valid).toBe(false);
+      const err = result.errors.find((e) => e.message.includes('tooltip[1]'));
+      expect(err).toBeDefined();
+      expect(err!.code).toBe('MISSING_FIELD');
+      expect(err!.path).toBe('encoding.tooltip[1].field');
+    });
   });
 
   describe('table specs', () => {

package/src/compiler/validate.ts

@@ -140,6 +140,40 @@ function validateChartSpec(spec: Record<string, unknown>, errors: ValidationErro
   for (const [channel, channelSpec] of Object.entries(encoding)) {
     if (!channelSpec || typeof channelSpec !== 'object') continue;
 
+    // Tooltip can be an array of encoding channels
+    if (channel === 'tooltip' && Array.isArray(channelSpec)) {
+      for (let i = 0; i < channelSpec.length; i++) {
+        const elem = channelSpec[i] as Record<string, unknown> | null;
+        if (!elem || typeof elem !== 'object') continue;
+        if (!elem.field || typeof elem.field !== 'string') {
+          errors.push({
+            message: `Spec error: encoding.tooltip[${i}] must have a "field" string`,
+            path: `encoding.tooltip[${i}].field`,
+            code: 'MISSING_FIELD',
+            suggestion: `Add a field name from your data columns: ${availableColumns}`,
+          });
+          continue;
+        }
+        if (!dataColumns.has(elem.field) && !transformFields.has(elem.field)) {
+          errors.push({
+            message: `Spec error: encoding.tooltip[${i}].field "${elem.field}" does not exist in data. Available columns: ${availableColumns}`,
+            path: `encoding.tooltip[${i}].field`,
+            code: 'DATA_FIELD_MISSING',
+            suggestion: `Use one of the available data columns: ${availableColumns}`,
+          });
+        }
+        if (elem.type && !VALID_FIELD_TYPES.has(elem.type as string)) {
+          errors.push({
+            message: `Spec error: encoding.tooltip[${i}].type "${elem.type}" is not valid. Must be one of: ${[...VALID_FIELD_TYPES].join(', ')}`,
+            path: `encoding.tooltip[${i}].type`,
+            code: 'INVALID_VALUE',
+            suggestion: `Use one of: ${[...VALID_FIELD_TYPES].join(', ')}`,
+          });
+        }
+      }
+      continue;
+    }
+
     const channelObj = channelSpec as Record<string, unknown>;
     const channelRule = rules[channel as keyof typeof rules];
 

package/src/layout/axes.ts

@@ -255,7 +255,8 @@ function formatTickLabel(value: unknown, resolvedScale: ResolvedScale): string {
   if (TEMPORAL_SCALE_TYPES.has(resolvedScale.type)) {
     const temporalFmt = buildTemporalFormatter(formatStr);
     if (temporalFmt) return temporalFmt(value as Date);
-    return formatDate(value as Date);
+    const useUtc = resolvedScale.type === 'utc';
+    return formatDate(value as Date, undefined, undefined, useUtc);
   }
 
   if (NUMERIC_SCALE_TYPES.has(resolvedScale.type)) {

package/src/layout/dimensions.ts

@@ -190,6 +190,7 @@ export function computeDimensions(
 
   // Reserve right margin for text annotations near the chart's right edge.
   // Without this, annotation text at the last data point clips outside the SVG.
+  // Account for anchor direction and offset.dx to avoid over-reserving space.
   if (spec.annotations.length > 0 && encoding.x) {
     const xField = encoding.x.field;
     // Find the maximum x value in the data
@@ -203,7 +204,23 @@ export function computeDimensions(
       for (const ann of spec.annotations) {
         if (ann.type === 'text' && String(ann.x) === maxXStr) {
           const textWidth = estimateTextWidth(ann.text, ann.fontSize ?? 11, ann.fontWeight ?? 600);
-          margins.right = Math.max(margins.right, padding + textWidth + 12);
+          const dx = ann.offset?.dx ?? 0;
+          // How much text extends right of the anchor point depends on alignment:
+          // - anchor "right" or "left": text is off to one side, full width extends
+          // - anchor "top"/"bottom"/"auto"/undefined: text is centered, half extends right
+          const anchor = ann.anchor ?? 'auto';
+          const baseRightExtent =
+            anchor === 'left'
+              ? textWidth
+              : // text is to the right of anchor
+                anchor === 'right'
+                ? 0
+                : // text is to the left of anchor
+                  textWidth / 2; // centered (top/bottom/auto)
+          const rightOverflow = Math.max(0, baseRightExtent + dx);
+          if (rightOverflow > 0) {
+            margins.right = Math.max(margins.right, padding + rightOverflow + 12);
+          }
         }
       }
     }
@@ -214,6 +231,7 @@ export function computeDimensions(
     if (
       spec.markType === 'bar' ||
       spec.markType === 'circle' ||
+      spec.markType === 'lollipop' ||
       encoding.y.type === 'nominal' ||
       encoding.y.type === 'ordinal'
     ) {

package/src/layout/scales.ts

@@ -568,7 +568,10 @@ function buildPositionalScale(
     case 'nominal':
     case 'ordinal':
       // Bar charts use band scales for their categorical axis (both orientations)
-      if (chartType === 'bar' || (chartType === 'circle' && axis === 'y')) {
+      if (
+        chartType === 'bar' ||
+        ((chartType === 'circle' || chartType === 'lollipop') && axis === 'y')
+      ) {
         return buildBandScale(channel, data, rangeStart, rangeEnd);
       }
       return buildPointScale(channel, data, rangeStart, rangeEnd);

package/src/legend/compute.ts

@@ -51,6 +51,7 @@ function swatchShapeForType(markType: string): LegendEntry['shape'] {
       return 'line';
     case 'point':
     case 'circle':
+    case 'lollipop':
       return 'circle';
     default:
       return 'square';
@@ -213,10 +214,15 @@ export function computeLegend(
     const maxLegendHeight = chartArea.height * maxHeightRatio;
 
     // Calculate how many entries fit
-    const maxEntries = Math.max(
+    const maxFromSpace = Math.max(
       1,
       Math.floor((maxLegendHeight - LEGEND_PADDING * 2) / (entryHeight + 4)),
     );
+    // symbolLimit overrides the space-based limit when set (minimum 1)
+    const maxEntries =
+      spec.legend?.symbolLimit != null
+        ? Math.min(Math.max(1, spec.legend.symbolLimit), maxFromSpace)
+        : maxFromSpace;
     if (entries.length > maxEntries) {
       entries = truncateEntries(entries, maxEntries);
     }
@@ -254,7 +260,21 @@ export function computeLegend(
   // Top/bottom-positioned legend: horizontal flow with overflow protection.
   // Reserve space on the right so legend entries don't overlap the brand watermark.
   const availableWidth = chartArea.width - LEGEND_PADDING * 2 - BRAND_RESERVE_WIDTH;
-  const maxFit = entriesThatFit(entries, availableWidth, TOP_LEGEND_MAX_ROWS, labelStyle);
+
+  // Apply symbolLimit first if set (minimum 1), then fit remaining entries to available rows.
+  if (spec.legend?.symbolLimit != null) {
+    const limit = Math.max(1, spec.legend.symbolLimit);
+    if (limit < entries.length) {
+      entries = truncateEntries(entries, limit);
+    }
+  }
+
+  // When columns is explicitly set, allow that many rows instead of the default max.
+  const maxRows =
+    spec.legend?.columns != null
+      ? Math.ceil(entries.length / spec.legend.columns)
+      : TOP_LEGEND_MAX_ROWS;
+  const maxFit = entriesThatFit(entries, availableWidth, maxRows, labelStyle);
 
   if (maxFit < entries.length) {
     entries = truncateEntries(entries, maxFit);

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

@@ -323,6 +323,67 @@ describe('computeTooltipDescriptors', () => {
     });
   });
 
+  describe('explicit tooltip encoding', () => {
+    it('uses tooltip array fields instead of auto-generated defaults', () => {
+      const spec: NormalizedChartSpec = {
+        ...makeBarSpec(),
+        encoding: {
+          ...makeBarSpec().encoding,
+          tooltip: [
+            { field: 'category', type: 'nominal' },
+            { field: 'value', type: 'quantitative' },
+          ],
+        },
+      };
+      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')!;
+
+      expect(content.fields).toHaveLength(2);
+      expect(content.fields[0].label).toBe('category');
+      expect(content.fields[0].value).toBe('A');
+      expect(content.fields[1].label).toBe('value');
+      expect(content.fields[1].value).toBe('100');
+    });
+
+    it('auto-generates tooltip fields when encoding.tooltip is not set', () => {
+      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')!;
+
+      // Default: y field first, then x field
+      expect(content.fields.length).toBeGreaterThanOrEqual(1);
+      const labels = content.fields.map((f) => f.label);
+      expect(labels).toContain('value');
+      expect(labels).toContain('category');
+    });
+  });
+
   describe('empty data', () => {
     it('returns empty map for no marks', () => {
       const spec = makeLineSpec();

package/src/tooltips/compute.ts

@@ -11,6 +11,7 @@ import type {
   AreaMark,
   DataRow,
   Encoding,
+  EncodingChannel,
   LineMark,
   Mark,
   PointMark,
@@ -51,8 +52,21 @@ function formatValue(value: unknown, fieldType?: string, format?: string): strin
   return String(value);
 }
 
+/** Build tooltip fields from explicit tooltip encoding channels. */
+function buildExplicitTooltipFields(row: DataRow, channels: EncodingChannel[]): TooltipField[] {
+  return channels.map((ch) => ({
+    label: ch.axis?.label ?? ch.field,
+    value: formatValue(row[ch.field], ch.type, ch.axis?.format),
+  }));
+}
+
 /** Build tooltip fields from a data row based on the spec encoding. */
 function buildFields(row: DataRow, encoding: Encoding, color?: string): TooltipField[] {
+  if (encoding.tooltip) {
+    const channels = Array.isArray(encoding.tooltip) ? encoding.tooltip : [encoding.tooltip];
+    return buildExplicitTooltipFields(row, channels);
+  }
+
   const fields: TooltipField[] = [];
 
   // Y-axis value (the "main" value in most charts)