@opendata-ai/openchart-engine 6.12.0 → 6.13.0

package/src/layout/scales.ts

@@ -140,6 +140,25 @@ function uniqueStrings(values: unknown[]): string[] {
   return result;
 }
 
+/**
+ * Apply sort order to categorical domain values (Vega-Lite aligned).
+ * - 'ascending': sort alphabetically/numerically ascending
+ * - 'descending': sort descending
+ * - null: preserve data order (no sorting)
+ * - undefined: ascending (VL default)
+ */
+function applyCategoricalSort(
+  values: string[],
+  sort: 'ascending' | 'descending' | null | undefined,
+): string[] {
+  // null means use data order
+  if (sort === null) return values;
+
+  const sorted = [...values].sort((a, b) => a.localeCompare(b, undefined, { numeric: true }));
+  if (sort === 'descending') sorted.reverse();
+  return sorted;
+}
+
 // ---------------------------------------------------------------------------
 // Helpers: apply common scale config
 // ---------------------------------------------------------------------------
@@ -439,7 +458,7 @@ function buildBandScale(
 ): ResolvedScale {
   const values = channel.scale?.domain
     ? (channel.scale.domain as string[])
-    : uniqueStrings(fieldValues(data, channel.field));
+    : applyCategoricalSort(uniqueStrings(fieldValues(data, channel.field)), channel.sort);
 
   const padding = channel.scale?.padding ?? 0.35;
   const scale = scaleBand().domain(values).range([rangeStart, rangeEnd]).padding(padding);
@@ -466,7 +485,7 @@ function buildPointScale(
 ): ResolvedScale {
   const values = channel.scale?.domain
     ? (channel.scale.domain as string[])
-    : uniqueStrings(fieldValues(data, channel.field));
+    : applyCategoricalSort(uniqueStrings(fieldValues(data, channel.field)), channel.sort);
 
   const padding = channel.scale?.padding ?? 0.5;
   const scale = scalePoint().domain(values).range([rangeStart, rangeEnd]).padding(padding);
@@ -484,7 +503,11 @@ function buildOrdinalColorScale(
   data: DataRow[],
   palette: string[],
 ): ResolvedScale {
-  const values = uniqueStrings(fieldValues(data, channel.field));
+  // Use explicit domain if provided, otherwise derive from data
+  const explicitDomain = channel.scale?.domain as string[] | undefined;
+  const values = explicitDomain
+    ? explicitDomain.map(String)
+    : applyCategoricalSort(uniqueStrings(fieldValues(data, channel.field)), channel.sort);
 
   const scale = scaleOrdinal<string>().domain(values).range(palette);
 
@@ -622,6 +645,7 @@ export function computeScales(
     // For stacked bars, the x-domain needs the max category sum, not max individual value.
     // Without this, stacked bars would clip past the chart area.
     let xData = data;
+    let xChannel = encoding.x;
     const xStackDisabled = encoding.x.stack === null || encoding.x.stack === false;
     if (
       spec.markType === 'bar' &&
@@ -629,25 +653,51 @@ export function computeScales(
       encoding.x.type === 'quantitative' &&
       !xStackDisabled
     ) {
-      const yField = encoding.y?.field;
-      const xField = encoding.x.field;
-      if (yField) {
-        const sums = new Map<string, number>();
-        for (const row of data) {
-          const cat = String(row[yField] ?? '');
-          const val = Number(row[xField] ?? 0);
-          if (Number.isFinite(val) && val > 0) {
-            sums.set(cat, (sums.get(cat) ?? 0) + val);
+      if (encoding.x.stack === 'normalize') {
+        // Normalize: domain is [0, 1]
+        xChannel = { ...encoding.x, scale: { ...encoding.x.scale, domain: [0, 1], nice: false } };
+      } else if (encoding.x.stack === 'center') {
+        // Center: compute max half-sum for symmetric domain
+        const yField = encoding.y?.field;
+        const xField = encoding.x.field;
+        if (yField) {
+          const sums = new Map<string, number>();
+          for (const row of data) {
+            const cat = String(row[yField] ?? '');
+            const val = Number(row[xField] ?? 0);
+            if (Number.isFinite(val) && val > 0) {
+              sums.set(cat, (sums.get(cat) ?? 0) + val);
+            }
+          }
+          const maxSum = Math.max(...sums.values(), 0);
+          const half = maxSum / 2;
+          xChannel = {
+            ...encoding.x,
+            scale: { ...encoding.x.scale, domain: [-half, half], zero: true },
+          };
+        }
+      } else {
+        // Zero (default): domain extends to max category sum
+        const yField = encoding.y?.field;
+        const xField = encoding.x.field;
+        if (yField) {
+          const sums = new Map<string, number>();
+          for (const row of data) {
+            const cat = String(row[yField] ?? '');
+            const val = Number(row[xField] ?? 0);
+            if (Number.isFinite(val) && val > 0) {
+              sums.set(cat, (sums.get(cat) ?? 0) + val);
+            }
           }
+          const maxSum = Math.max(...sums.values(), 0);
+          // Create a synthetic row with the max stack sum so buildLinearScale sees it
+          xData = [...data, { [xField]: maxSum } as DataRow];
         }
-        const maxSum = Math.max(...sums.values(), 0);
-        // Create a synthetic row with the max stack sum so buildLinearScale sees it
-        xData = [...data, { [xField]: maxSum } as DataRow];
       }
     }
 
     result.x = buildPositionalScale(
-      encoding.x,
+      xChannel,
       xData,
       chartArea.x,
       chartArea.x + chartArea.width,
@@ -662,6 +712,7 @@ export function computeScales(
     // would clip above the chart area.
     // Vertical bar = x is categorical and y is quantitative (old 'column' chart type).
     let yData = data;
+    let yChannel = encoding.y;
     const isVerticalBar =
       spec.markType === 'bar' &&
       (encoding.x?.type === 'nominal' || encoding.x?.type === 'ordinal') &&
@@ -673,26 +724,52 @@ export function computeScales(
       encoding.y.type === 'quantitative' &&
       !yStackDisabled
     ) {
-      const xField = encoding.x?.field;
-      const yField = encoding.y.field;
-      if (xField) {
-        const sums = new Map<string, number>();
-        for (const row of data) {
-          const cat = String(row[xField] ?? '');
-          const val = Number(row[yField] ?? 0);
-          if (Number.isFinite(val) && val > 0) {
-            sums.set(cat, (sums.get(cat) ?? 0) + val);
+      if (encoding.y.stack === 'normalize') {
+        // Normalize: domain is [0, 1] (VL convention)
+        yChannel = { ...encoding.y, scale: { ...encoding.y.scale, domain: [0, 1], nice: false } };
+      } else if (encoding.y.stack === 'center') {
+        // Center: compute max half-sum for symmetric domain
+        const xField = encoding.x?.field;
+        const yField = encoding.y.field;
+        if (xField) {
+          const sums = new Map<string, number>();
+          for (const row of data) {
+            const cat = String(row[xField] ?? '');
+            const val = Number(row[yField] ?? 0);
+            if (Number.isFinite(val) && val > 0) {
+              sums.set(cat, (sums.get(cat) ?? 0) + val);
+            }
+          }
+          const maxSum = Math.max(...sums.values(), 0);
+          const half = maxSum / 2;
+          yChannel = {
+            ...encoding.y,
+            scale: { ...encoding.y.scale, domain: [-half, half], zero: true },
+          };
+        }
+      } else {
+        // Zero (default): domain extends to max category sum
+        const xField = encoding.x?.field;
+        const yField = encoding.y.field;
+        if (xField) {
+          const sums = new Map<string, number>();
+          for (const row of data) {
+            const cat = String(row[xField] ?? '');
+            const val = Number(row[yField] ?? 0);
+            if (Number.isFinite(val) && val > 0) {
+              sums.set(cat, (sums.get(cat) ?? 0) + val);
+            }
           }
+          const maxSum = Math.max(...sums.values(), 0);
+          // Create a synthetic row with the max stack sum so buildLinearScale sees it
+          yData = [...data, { [yField]: maxSum } as DataRow];
         }
-        const maxSum = Math.max(...sums.values(), 0);
-        // Create a synthetic row with the max stack sum so buildLinearScale sees it
-        yData = [...data, { [yField]: maxSum } as DataRow];
       }
     }
 
     // Y axis: range is inverted (SVG y goes down, data y goes up)
     result.y = buildPositionalScale(
-      encoding.y,
+      yChannel,
       yData,
       chartArea.y + chartArea.height,
       chartArea.y,

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);
+  });
+});