@opendata-ai/openchart-engine 6.11.0 → 6.13.0

package/src/tables/compile-table.ts

@@ -382,6 +382,7 @@ export function compileTableLayout(
   });
 
   // 9. Compute chrome
+  const watermark = spec.watermark;
   const chrome = computeChrome(
     {
       title: spec.chrome.title,
@@ -393,6 +394,9 @@ export function compileTableLayout(
     theme,
     options.width,
     options.measureText,
+    'full',
+    undefined,
+    watermark,
   );
 
   // 10. Build a11y
@@ -418,5 +422,6 @@ export function compileTableLayout(
     },
     theme,
     animation: resolveAnimation(spec.animation),
+    watermark,
   };
 }

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

@@ -384,6 +384,194 @@ describe('computeTooltipDescriptors', () => {
     });
   });
 
+  describe('tooltip title and format on encoding channels', () => {
+    it('uses channel title as label instead of field name in explicit tooltip', () => {
+      const spec: NormalizedChartSpec = {
+        ...makeBarSpec(),
+        encoding: {
+          ...makeBarSpec().encoding,
+          tooltip: [
+            { field: 'category', type: 'nominal', title: 'Category Name' },
+            { field: 'value', type: 'quantitative', title: 'Total Sales' },
+          ],
+        },
+      };
+      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[0].label).toBe('Category Name');
+      expect(content.fields[1].label).toBe('Total Sales');
+    });
+
+    it('uses channel format to format values in explicit tooltip', () => {
+      const spec: NormalizedChartSpec = {
+        ...makeBarSpec(),
+        encoding: {
+          ...makeBarSpec().encoding,
+          tooltip: [{ field: 'value', type: 'quantitative', format: '$,.0f' }],
+        },
+      };
+      const rectMarks: RectMark[] = [
+        {
+          type: 'rect',
+          x: 50,
+          y: 30,
+          width: 200,
+          height: 40,
+          fill: '#1b7fa3',
+          data: { category: 'A', value: 1500 },
+          aria: { label: 'bar' },
+        },
+      ];
+
+      const descriptors = computeTooltipDescriptors(spec, rectMarks);
+      const content = descriptors.get('rect-0')!;
+
+      expect(content.fields[0].value).toBe('$1,500');
+    });
+
+    it('channel title takes precedence over axis.title', () => {
+      const spec: NormalizedChartSpec = {
+        ...makeBarSpec(),
+        encoding: {
+          ...makeBarSpec().encoding,
+          tooltip: [
+            {
+              field: 'value',
+              type: 'quantitative',
+              title: 'Channel Title',
+              axis: { title: 'Axis Title' },
+            },
+          ],
+        },
+      };
+      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[0].label).toBe('Channel Title');
+    });
+
+    it('channel format takes precedence over axis.format', () => {
+      const spec: NormalizedChartSpec = {
+        ...makeBarSpec(),
+        encoding: {
+          ...makeBarSpec().encoding,
+          tooltip: [
+            {
+              field: 'value',
+              type: 'quantitative',
+              format: ',.0f',
+              axis: { format: '.2f' },
+            },
+          ],
+        },
+      };
+      const rectMarks: RectMark[] = [
+        {
+          type: 'rect',
+          x: 50,
+          y: 30,
+          width: 200,
+          height: 40,
+          fill: '#1b7fa3',
+          data: { category: 'A', value: 1500 },
+          aria: { label: 'bar' },
+        },
+      ];
+
+      const descriptors = computeTooltipDescriptors(spec, rectMarks);
+      const content = descriptors.get('rect-0')!;
+
+      expect(content.fields[0].value).toBe('1,500');
+    });
+
+    it('uses title and format on auto-generated tooltip fields (no explicit tooltip)', () => {
+      const spec: NormalizedChartSpec = {
+        ...makeBarSpec(),
+        encoding: {
+          x: { field: 'value', type: 'quantitative', title: 'Sales', format: '$,.0f' },
+          y: { field: 'category', type: 'nominal', title: 'Product' },
+        },
+      };
+      const rectMarks: RectMark[] = [
+        {
+          type: 'rect',
+          x: 50,
+          y: 30,
+          width: 200,
+          height: 40,
+          fill: '#1b7fa3',
+          data: { category: 'A', value: 2000 },
+          aria: { label: 'bar' },
+        },
+      ];
+
+      const descriptors = computeTooltipDescriptors(spec, rectMarks);
+      const content = descriptors.get('rect-0')!;
+
+      const productField = content.fields.find((f) => f.label === 'Product');
+      expect(productField).toBeDefined();
+      expect(productField!.value).toBe('A');
+
+      const salesField = content.fields.find((f) => f.label === 'Sales');
+      expect(salesField).toBeDefined();
+      expect(salesField!.value).toBe('$2,000');
+    });
+
+    it('falls back to axis.title when channel title is not set', () => {
+      const spec: NormalizedChartSpec = {
+        ...makeBarSpec(),
+        encoding: {
+          ...makeBarSpec().encoding,
+          tooltip: [{ field: 'value', type: 'quantitative', axis: { title: 'Axis Label' } }],
+        },
+      };
+      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[0].label).toBe('Axis Label');
+    });
+  });
+
   describe('empty data', () => {
     it('returns empty map for no marks', () => {
       const spec = makeLineSpec();

package/src/tooltips/compute.ts

@@ -57,11 +57,21 @@ function formatValue(value: unknown, fieldType?: string, format?: string): strin
   return String(value);
 }
 
+/** Resolve the display label for an encoding channel: title > axis.title > field name. */
+function resolveLabel(ch: EncodingChannel): string {
+  return ch.title ?? ch.axis?.title ?? ch.field;
+}
+
+/** Resolve the format string for an encoding channel: format > axis.format. */
+function resolveFormat(ch: EncodingChannel): string | undefined {
+  return ch.format ?? ch.axis?.format;
+}
+
 /** 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),
+    label: resolveLabel(ch),
+    value: formatValue(row[ch.field], ch.type, resolveFormat(ch)),
   }));
 }
 
@@ -77,8 +87,8 @@ function buildFields(row: DataRow, encoding: Encoding, color?: string): TooltipF
   // 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),
+      label: resolveLabel(encoding.y),
+      value: formatValue(row[encoding.y.field], encoding.y.type, resolveFormat(encoding.y)),
       color,
     });
   }
@@ -86,16 +96,20 @@ function buildFields(row: DataRow, encoding: Encoding, color?: string): TooltipF
   // 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),
+      label: resolveLabel(encoding.x),
+      value: formatValue(row[encoding.x.field], encoding.x.type, resolveFormat(encoding.x)),
     });
   }
 
   // Size (for scatter/bubble) - skip conditional size definitions
   if (encoding.size && 'field' in 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),
+      label: resolveLabel(encoding.size),
+      value: formatValue(
+        row[encoding.size.field],
+        encoding.size.type,
+        resolveFormat(encoding.size),
+      ),
     });
   }
 
@@ -191,14 +205,14 @@ function tooltipsForArc(
     if (encoding.y) {
       fields.push({
         label: categoryName,
-        value: formatValue(row[encoding.y.field], encoding.y.type, encoding.y.axis?.format),
+        value: formatValue(row[encoding.y.field], encoding.y.type, resolveFormat(encoding.y)),
         color: getRepresentativeColor(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),
+      label: resolveLabel(encoding.y),
+      value: formatValue(row[encoding.y.field], encoding.y.type, resolveFormat(encoding.y)),
       color: getRepresentativeColor(mark.fill),
     });
   }

package/src/transforms/__tests__/aggregate.test.ts

@@ -0,0 +1,159 @@
+import { describe, expect, it } from 'vitest';
+import { runAggregate } from '../aggregate';
+
+describe('runAggregate', () => {
+  const data = [
+    { region: 'North', product: 'A', revenue: 100, qty: 10 },
+    { region: 'North', product: 'B', revenue: 200, qty: 20 },
+    { region: 'South', product: 'A', revenue: 150, qty: 15 },
+    { region: 'South', product: 'B', revenue: 250, qty: 25 },
+    { region: 'South', product: 'A', revenue: 50, qty: 5 },
+  ];
+
+  it('computes sum aggregate grouped by one field', () => {
+    const result = runAggregate(data, {
+      aggregate: [{ op: 'sum', field: 'revenue', as: 'total_revenue' }],
+      groupby: ['region'],
+    });
+
+    expect(result).toHaveLength(2);
+    const north = result.find((r) => r.region === 'North');
+    const south = result.find((r) => r.region === 'South');
+    expect(north?.total_revenue).toBe(300);
+    expect(south?.total_revenue).toBe(450);
+  });
+
+  it('computes mean aggregate', () => {
+    const result = runAggregate(data, {
+      aggregate: [{ op: 'mean', field: 'revenue', as: 'avg_revenue' }],
+      groupby: ['region'],
+    });
+
+    const north = result.find((r) => r.region === 'North');
+    const south = result.find((r) => r.region === 'South');
+    expect(north?.avg_revenue).toBe(150); // (100+200)/2
+    expect(south?.avg_revenue).toBe(150); // (150+250+50)/3
+  });
+
+  it('computes count aggregate', () => {
+    const result = runAggregate(data, {
+      aggregate: [{ op: 'count', field: 'revenue', as: 'num_rows' }],
+      groupby: ['region'],
+    });
+
+    const north = result.find((r) => r.region === 'North');
+    const south = result.find((r) => r.region === 'South');
+    expect(north?.num_rows).toBe(2);
+    expect(south?.num_rows).toBe(3);
+  });
+
+  it('computes median aggregate', () => {
+    const result = runAggregate(data, {
+      aggregate: [{ op: 'median', field: 'revenue', as: 'med_revenue' }],
+      groupby: ['region'],
+    });
+
+    const north = result.find((r) => r.region === 'North');
+    const south = result.find((r) => r.region === 'South');
+    expect(north?.med_revenue).toBe(150); // median of [100, 200]
+    expect(south?.med_revenue).toBe(150); // median of [50, 150, 250]
+  });
+
+  it('computes min and max aggregates', () => {
+    const result = runAggregate(data, {
+      aggregate: [
+        { op: 'min', field: 'revenue', as: 'min_rev' },
+        { op: 'max', field: 'revenue', as: 'max_rev' },
+      ],
+      groupby: ['region'],
+    });
+
+    const south = result.find((r) => r.region === 'South');
+    expect(south?.min_rev).toBe(50);
+    expect(south?.max_rev).toBe(250);
+  });
+
+  it('supports multiple groupby fields', () => {
+    const result = runAggregate(data, {
+      aggregate: [{ op: 'sum', field: 'revenue', as: 'total' }],
+      groupby: ['region', 'product'],
+    });
+
+    expect(result).toHaveLength(4);
+    const southA = result.find((r) => r.region === 'South' && r.product === 'A');
+    expect(southA?.total).toBe(200); // 150 + 50
+  });
+
+  it('supports multiple aggregate ops in one transform', () => {
+    const result = runAggregate(data, {
+      aggregate: [
+        { op: 'sum', field: 'revenue', as: 'total_rev' },
+        { op: 'mean', field: 'qty', as: 'avg_qty' },
+      ],
+      groupby: ['region'],
+    });
+
+    const north = result.find((r) => r.region === 'North');
+    expect(north?.total_rev).toBe(300);
+    expect(north?.avg_qty).toBe(15); // (10+20)/2
+  });
+
+  it('computes variance aggregate', () => {
+    const result = runAggregate(data, {
+      aggregate: [{ op: 'variance', field: 'revenue', as: 'var_rev' }],
+      groupby: ['region'],
+    });
+
+    const south = result.find((r) => r.region === 'South');
+    // South values: [150, 250, 50], mean=150, variance = ((0)^2 + (100)^2 + (-100)^2) / 3
+    expect(south?.var_rev).toBeCloseTo(6666.667, 0);
+  });
+
+  it('computes stdev aggregate', () => {
+    const result = runAggregate(data, {
+      aggregate: [{ op: 'stdev', field: 'revenue', as: 'sd_rev' }],
+      groupby: ['region'],
+    });
+
+    const south = result.find((r) => r.region === 'South');
+    // sqrt(6666.667) ≈ 81.65
+    expect(south?.sd_rev).toBeCloseTo(81.65, 1);
+  });
+
+  it('computes distinct aggregate (counts unique raw values)', () => {
+    const result = runAggregate(data, {
+      aggregate: [{ op: 'distinct', field: 'product', as: 'n_products' }],
+      groupby: ['region'],
+    });
+
+    const north = result.find((r) => r.region === 'North');
+    const south = result.find((r) => r.region === 'South');
+    expect(north?.n_products).toBe(2); // A, B
+    expect(south?.n_products).toBe(2); // A, B (A appears twice but distinct=2)
+  });
+
+  it('computes q1 and q3 aggregates', () => {
+    const result = runAggregate(data, {
+      aggregate: [
+        { op: 'q1', field: 'revenue', as: 'q1_rev' },
+        { op: 'q3', field: 'revenue', as: 'q3_rev' },
+      ],
+      groupby: ['region'],
+    });
+
+    const south = result.find((r) => r.region === 'South');
+    // South values sorted: [50, 150, 250]
+    // q1: index = (3-1)*0.25 = 0.5 -> 50 + 0.5*(150-50) = 100
+    // q3: index = (3-1)*0.75 = 1.5 -> 150 + 0.5*(250-150) = 200
+    expect(south?.q1_rev).toBe(100);
+    expect(south?.q3_rev).toBe(200);
+  });
+
+  it('handles empty data', () => {
+    const result = runAggregate([], {
+      aggregate: [{ op: 'sum', field: 'revenue', as: 'total' }],
+      groupby: ['region'],
+    });
+    expect(result).toHaveLength(0);
+  });
+});

package/src/transforms/__tests__/fold.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from 'vitest';
+import { runFold } from '../fold';
+
+describe('runFold', () => {
+  const data = [
+    { country: 'US', gold: 10, silver: 20, bronze: 30 },
+    { country: 'UK', gold: 5, silver: 15, bronze: 25 },
+  ];
+
+  it('folds two columns with default key/value names', () => {
+    const result = runFold(data, {
+      fold: ['gold', 'silver'],
+    });
+
+    expect(result).toHaveLength(4); // 2 rows x 2 fold fields
+    expect(result[0]).toEqual({ country: 'US', bronze: 30, key: 'gold', value: 10 });
+    expect(result[1]).toEqual({ country: 'US', bronze: 30, key: 'silver', value: 20 });
+    expect(result[2]).toEqual({ country: 'UK', bronze: 25, key: 'gold', value: 5 });
+    expect(result[3]).toEqual({ country: 'UK', bronze: 25, key: 'silver', value: 15 });
+  });
+
+  it('folds three columns', () => {
+    const result = runFold(data, {
+      fold: ['gold', 'silver', 'bronze'],
+    });
+
+    expect(result).toHaveLength(6); // 2 rows x 3 fold fields
+    // First row's fold outputs
+    expect(result[0].key).toBe('gold');
+    expect(result[0].value).toBe(10);
+    expect(result[1].key).toBe('silver');
+    expect(result[1].value).toBe(20);
+    expect(result[2].key).toBe('bronze');
+    expect(result[2].value).toBe(30);
+  });
+
+  it('uses custom as names', () => {
+    const result = runFold(data, {
+      fold: ['gold', 'silver'],
+      as: ['medal', 'count'],
+    });
+
+    expect(result[0].medal).toBe('gold');
+    expect(result[0].count).toBe(10);
+    expect(result[1].medal).toBe('silver');
+    expect(result[1].count).toBe(20);
+    // Default key/value shouldn't be present
+    expect(result[0].key).toBeUndefined();
+    expect(result[0].value).toBeUndefined();
+  });
+
+  it('preserves non-fold fields', () => {
+    const result = runFold(data, {
+      fold: ['gold'],
+    });
+
+    // country and bronze are non-fold fields
+    expect(result[0].country).toBe('US');
+    expect(result[0].bronze).toBe(30);
+    // gold should not be a direct field (it's now key/value)
+    expect(result[0].gold).toBeUndefined();
+  });
+
+  it('handles undefined fold field values', () => {
+    const sparse = [{ name: 'test', a: 1 }]; // no 'b' field
+    const result = runFold(sparse, {
+      fold: ['a', 'b'],
+    });
+
+    expect(result).toHaveLength(2);
+    expect(result[0].value).toBe(1);
+    expect(result[1].value).toBeUndefined();
+  });
+
+  it('handles empty data', () => {
+    const result = runFold([], { fold: ['gold', 'silver'] });
+    expect(result).toHaveLength(0);
+  });
+});

package/src/transforms/aggregate.ts

@@ -0,0 +1,130 @@
+/**
+ * Aggregate transform: groups rows and computes summary statistics.
+ *
+ * Follows Vega-Lite aggregate transform conventions.
+ * Groups input data by the specified fields, then applies aggregate
+ * operations (sum, mean, count, etc.) to produce one row per group.
+ */
+
+import type { AggregateOp, AggregateTransform, DataRow } from '@opendata-ai/openchart-core';
+
+/**
+ * Compute a single aggregate operation over an array of numeric values.
+ */
+function computeAggregate(op: AggregateOp, values: number[]): number {
+  if (values.length === 0) return 0;
+
+  switch (op) {
+    case 'count':
+      return values.length;
+    case 'sum':
+      return values.reduce((a, b) => a + b, 0);
+    case 'mean': {
+      const sum = values.reduce((a, b) => a + b, 0);
+      return sum / values.length;
+    }
+    case 'median': {
+      const sorted = [...values].sort((a, b) => a - b);
+      const mid = Math.floor(sorted.length / 2);
+      return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+    }
+    case 'min':
+      return Math.min(...values);
+    case 'max':
+      return Math.max(...values);
+    case 'variance': {
+      if (values.length < 2) return 0;
+      const mean = values.reduce((a, b) => a + b, 0) / values.length;
+      return values.reduce((a, v) => a + (v - mean) ** 2, 0) / values.length;
+    }
+    case 'stdev': {
+      if (values.length < 2) return 0;
+      const m = values.reduce((a, b) => a + b, 0) / values.length;
+      return Math.sqrt(values.reduce((a, v) => a + (v - m) ** 2, 0) / values.length);
+    }
+    case 'q1': {
+      const s = [...values].sort((a, b) => a - b);
+      const i = (s.length - 1) * 0.25;
+      const lo = Math.floor(i);
+      const frac = i - lo;
+      return s[lo] + frac * ((s[lo + 1] ?? s[lo]) - s[lo]);
+    }
+    case 'q3': {
+      const s = [...values].sort((a, b) => a - b);
+      const i = (s.length - 1) * 0.75;
+      const lo = Math.floor(i);
+      const frac = i - lo;
+      return s[lo] + frac * ((s[lo + 1] ?? s[lo]) - s[lo]);
+    }
+    default:
+      return 0;
+  }
+}
+
+/**
+ * Build a composite group key from a row's groupby field values.
+ */
+function groupKey(row: DataRow, groupby: string[]): string {
+  return groupby.map((f) => String(row[f] ?? '')).join('\x00');
+}
+
+/**
+ * Apply an aggregate transform to data rows.
+ *
+ * Groups rows by the groupby fields, then computes each aggregate
+ * operation within each group. Returns one row per group containing
+ * the groupby field values plus computed aggregate fields.
+ *
+ * @param data - Input rows.
+ * @param transform - Aggregate transform definition.
+ * @returns Aggregated rows (one per group).
+ */
+export function runAggregate(data: DataRow[], transform: AggregateTransform): DataRow[] {
+  const { aggregate, groupby } = transform;
+
+  // Group rows by the groupby fields
+  const groups = new Map<string, DataRow[]>();
+  for (const row of data) {
+    const key = groupKey(row, groupby);
+    const existing = groups.get(key);
+    if (existing) {
+      existing.push(row);
+    } else {
+      groups.set(key, [row]);
+    }
+  }
+
+  // Compute aggregates for each group
+  const result: DataRow[] = [];
+  for (const rows of groups.values()) {
+    // Start with groupby field values from the first row in the group
+    const outRow: DataRow = {};
+    for (const field of groupby) {
+      outRow[field] = rows[0][field];
+    }
+
+    // Compute each aggregate operation
+    for (const agg of aggregate) {
+      // distinct counts unique raw values (not just numeric)
+      if (agg.op === 'distinct') {
+        outRow[agg.as] = new Set(rows.map((r) => r[agg.field])).size;
+        continue;
+      }
+
+      const values = rows
+        .map((r) => {
+          // For count, the field value doesn't matter, just count rows
+          if (agg.op === 'count') return 1;
+          const v = Number(r[agg.field]);
+          return Number.isFinite(v) ? v : NaN;
+        })
+        .filter((v) => !Number.isNaN(v));
+
+      outRow[agg.as] = computeAggregate(agg.op, values);
+    }
+
+    result.push(outRow);
+  }
+
+  return result;
+}