@opendata-ai/openchart-engine 6.12.0 → 6.15.0

package/src/layout/scales.ts

@@ -140,6 +140,23 @@ function uniqueStrings(values: unknown[]): string[] {
   return result;
 }
 
+/**
+ * Apply sort order to categorical domain values.
+ * - 'ascending': sort alphabetically/numerically ascending
+ * - 'descending': sort descending
+ * - null | undefined: preserve data order (no sorting)
+ */
+function applyCategoricalSort(
+  values: string[],
+  sort: 'ascending' | 'descending' | null | undefined,
+): string[] {
+  if (!sort) 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
 // ---------------------------------------------------------------------------
@@ -175,7 +192,11 @@ function buildTimeScale(
 
   const scale = scaleTime().domain(domain).range([rangeStart, rangeEnd]);
 
-  if (channel.scale?.nice !== false) {
+  // Temporal scales default to nice: false because date data typically starts
+  // at clean boundaries and nice() rounds the domain outward, creating visible
+  // gaps (e.g. data starting 2018-01-01 gets rounded to 2017-01-01).
+  // Users can opt in with scale: { nice: true }.
+  if (!channel.scale?.domain && channel.scale?.nice === true) {
     scale.nice();
   }
   applyContinuousConfig(scale, channel);
@@ -196,7 +217,8 @@ function buildUtcScale(
 
   const scale = scaleUtc().domain(domain).range([rangeStart, rangeEnd]);
 
-  if (channel.scale?.nice !== false) {
+  // Temporal scales default to nice: false (see buildTimeScale comment).
+  if (!channel.scale?.domain && channel.scale?.nice === true) {
     scale.nice();
   }
   applyContinuousConfig(scale, channel);
@@ -232,7 +254,7 @@ function buildLinearScale(
 
   const scale = scaleLinear().domain([domainMin, domainMax]).range([rangeStart, rangeEnd]);
 
-  if (channel.scale?.nice !== false) {
+  if (!channel.scale?.domain && channel.scale?.nice !== false) {
     scale.nice();
   }
   applyContinuousConfig(scale, channel);
@@ -259,7 +281,7 @@ function buildLogScale(
   if (channel.scale?.base !== undefined) {
     scale.base(channel.scale.base);
   }
-  if (channel.scale?.nice !== false) {
+  if (!channel.scale?.domain && channel.scale?.nice !== false) {
     scale.nice();
   }
   applyContinuousConfig(scale, channel);
@@ -294,7 +316,7 @@ function buildPowScale(
   if (channel.scale?.exponent !== undefined) {
     scale.exponent(channel.scale.exponent);
   }
-  if (channel.scale?.nice !== false) {
+  if (!channel.scale?.domain && channel.scale?.nice !== false) {
     scale.nice();
   }
   applyContinuousConfig(scale, channel);
@@ -326,7 +348,7 @@ function buildSqrtScale(
 
   const scale = scaleSqrt().domain([domainMin, domainMax]).range([rangeStart, rangeEnd]);
 
-  if (channel.scale?.nice !== false) {
+  if (!channel.scale?.domain && channel.scale?.nice !== false) {
     scale.nice();
   }
   applyContinuousConfig(scale, channel);
@@ -361,7 +383,7 @@ function buildSymlogScale(
   if (channel.scale?.constant !== undefined) {
     scale.constant(channel.scale.constant);
   }
-  if (channel.scale?.nice !== false) {
+  if (!channel.scale?.domain && channel.scale?.nice !== false) {
     scale.nice();
   }
   applyContinuousConfig(scale, channel);
@@ -439,7 +461,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 +488,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 +506,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 +648,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 +656,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 +715,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 +727,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/legend/compute.ts

@@ -219,11 +219,9 @@ export function computeLegend(
       1,
       Math.floor((maxLegendHeight - LEGEND_PADDING * 2) / (entryHeight + 4)),
     );
-    // symbolLimit overrides the space-based limit when set (minimum 1)
+    // symbolLimit overrides the space-based limit when explicitly set (minimum 1)
     const maxEntries =
-      spec.legend?.symbolLimit != null
-        ? Math.min(Math.max(1, spec.legend.symbolLimit), maxFromSpace)
-        : maxFromSpace;
+      spec.legend?.symbolLimit != null ? Math.max(1, spec.legend.symbolLimit) : maxFromSpace;
     if (entries.length > maxEntries) {
       entries = truncateEntries(entries, maxEntries);
     }

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)),
   }));
 }
 
@@ -74,28 +84,45 @@ function buildFields(row: DataRow, encoding: Encoding, color?: string): TooltipF
 
   const fields: TooltipField[] = [];
 
+  // Color/series field (e.g. "Source: Coal") so the user knows which series
+  if (encoding.color && 'field' in encoding.color) {
+    fields.push({
+      label: resolveLabel(encoding.color),
+      value: formatValue(
+        row[encoding.color.field],
+        encoding.color.type,
+        resolveFormat(encoding.color),
+      ),
+      color,
+    });
+  }
+
   // 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,
+      label: resolveLabel(encoding.y),
+      value: formatValue(row[encoding.y.field], encoding.y.type, resolveFormat(encoding.y)),
+      color: encoding.color ? undefined : 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),
+      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),
+      ),
     });
   }
 
@@ -124,6 +151,21 @@ function getTooltipTitle(row: DataRow, encoding: Encoding): string | undefined {
     return String(row[encoding.y.field] ?? '');
   }
 
+  // For scatter/bubble (both axes quantitative), find a name-like string field
+  // in the data row that isn't already used by an encoding channel
+  if (encoding.x?.type === 'quantitative' && encoding.y?.type === 'quantitative') {
+    const encodedFields = new Set(
+      [encoding.x, encoding.y, encoding.color, encoding.size, encoding.detail]
+        .filter((ch): ch is EncodingChannel => !!ch && 'field' in ch)
+        .map((ch) => ch.field),
+    );
+    for (const [key, value] of Object.entries(row)) {
+      if (!encodedFields.has(key) && typeof value === 'string') {
+        return value;
+      }
+    }
+  }
+
   // For color-encoded series, use the series name (skip conditional defs)
   if (encoding.color && 'field' in encoding.color) {
     return String(row[encoding.color.field] ?? '');
@@ -191,14 +233,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),
     });
   }