@opendata-ai/openchart-engine 6.15.0 → 6.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-engine",
-  "version": "6.15.0",
+  "version": "6.16.0",
   "description": "Headless compiler for openchart: spec validation, data compilation, scales, and layout",
   "license": "Apache-2.0",
   "author": "Riley Hilliard",
@@ -45,7 +45,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@opendata-ai/openchart-core": "6.15.0",
+    "@opendata-ai/openchart-core": "6.16.0",
     "d3-array": "^3.2.0",
     "d3-format": "^3.1.2",
     "d3-interpolate": "^3.0.0",

package/src/__tests__/legend.test.ts

@@ -243,6 +243,38 @@ describe('computeLegend', () => {
     expect(maxRowsVisible).toBeGreaterThan(defaultVisible);
   });
 
+  it('uses explicit domain+range colors in legend entries', () => {
+    const specExplicit: NormalizedChartSpec = {
+      ...specWithColor,
+      data: [
+        { date: '2020', value: 10, country: 'UK' },
+        { date: '2021', value: 20, country: 'US' },
+        { date: '2022', value: 30, country: 'Germany' },
+      ],
+      encoding: {
+        x: { field: 'date', type: 'temporal' },
+        y: { field: 'value', type: 'quantitative' },
+        color: {
+          field: 'country',
+          type: 'nominal',
+          scale: {
+            domain: ['US', 'UK', 'Germany'],
+            range: ['#ff0000', '#0000ff', '#00ff00'],
+          },
+        },
+      },
+    };
+    const legend = computeLegend(specExplicit, compactStrategy, theme, chartArea);
+    // Data order is UK, US, Germany but domain order is US, UK, Germany
+    // Legend should match colors to domain indices, not data order
+    const ukEntry = legend.entries.find((e) => e.label === 'UK')!;
+    const usEntry = legend.entries.find((e) => e.label === 'US')!;
+    const deEntry = legend.entries.find((e) => e.label === 'Germany')!;
+    expect(usEntry.color).toBe('#ff0000');
+    expect(ukEntry.color).toBe('#0000ff');
+    expect(deEntry.color).toBe('#00ff00');
+  });
+
   it('uses correct swatch shape for chart type', () => {
     const lineLegend = computeLegend(specWithColor, fullStrategy, theme, chartArea);
     expect(lineLegend.entries[0].shape).toBe('line');

package/src/annotations/resolve-text.ts

@@ -50,6 +50,7 @@ export function resolveTextAnnotation(
   if (px === null || py === null) return null;
 
   const defaultTextFill = isDark ? DARK_TEXT_FILL : LIGHT_TEXT_FILL;
+
   const labelStyle = makeAnnotationLabelStyle(
     annotation.fontSize,
     annotation.fontWeight,

package/src/charts/bar/compute.ts

@@ -12,18 +12,41 @@ import type {
   Encoding,
   GradientDef,
   LayoutStrategy,
+  LinearGradient,
   MarkAria,
   Rect,
   RectMark,
 } from '@opendata-ai/openchart-core';
 import { abbreviateNumber, formatNumber, isGradientDef } from '@opendata-ai/openchart-core';
 import type { ScaleBand, ScaleLinear } from 'd3-scale';
-
 import type { NormalizedChartSpec } from '../../compiler/types';
 import type { ResolvedScales } from '../../layout/scales';
 import { isConditionalValueDef, resolveConditionalValue } from '../../transforms/conditional';
 import { getColor, getSequentialColor, groupByField } from '../utils';
 
+/**
+ * Auto-orient a gradient for horizontal bars.
+ *
+ * If the gradient uses the default top-to-bottom direction (no explicit
+ * x1/y1/x2/y2, or the defaults x1:0, y1:0, x2:0, y2:1), rotate it to
+ * left-to-right so the gradient follows the bar's data direction.
+ *
+ * Gradients with explicit non-default coordinates are left unchanged.
+ */
+function orientGradientForHorizontalBar(grad: GradientDef): GradientDef {
+  if (grad.gradient !== 'linear') return grad;
+  const lg = grad as LinearGradient;
+  // Only auto-orient if using the default vertical direction.
+  // Default is x1:0, y1:0, x2:0, y2:1 (top-to-bottom).
+  const isDefaultVertical =
+    (lg.x1 === undefined || lg.x1 === 0) &&
+    (lg.y1 === undefined || lg.y1 === 0) &&
+    (lg.x2 === undefined || lg.x2 === 0) &&
+    (lg.y2 === undefined || lg.y2 === 1);
+  if (!isDefaultVertical) return grad;
+  return { ...lg, x1: 0, y1: 0, x2: 1, y2: 0 };
+}
+
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -207,7 +230,7 @@ function computeStackedBars(
         y: bandY,
         width: barWidth,
         height: bandwidth,
-        fill: color,
+        fill: isGradientDef(color) ? orientGradientForHorizontalBar(color) : color,
         cornerRadius: 0,
         data: row as Record<string, unknown>,
         aria,
@@ -277,7 +300,7 @@ function computeGroupedBars(
         y: subY,
         width: barWidth,
         height: subBandHeight,
-        fill: color,
+        fill: isGradientDef(color) ? orientGradientForHorizontalBar(color) : color,
         cornerRadius: 2,
         data: row as Record<string, unknown>,
         aria,
@@ -327,7 +350,7 @@ function computeColoredBars(
       y: bandY,
       width: barWidth,
       height: bandwidth,
-      fill: color,
+      fill: isGradientDef(color) ? orientGradientForHorizontalBar(color) : color,
       cornerRadius: 2,
       data: row as Record<string, unknown>,
       aria,
@@ -387,7 +410,7 @@ function computeSimpleBars(
       y: bandY,
       width: barWidth,
       height: bandwidth,
-      fill: color,
+      fill: isGradientDef(color) ? orientGradientForHorizontalBar(color) : color,
       cornerRadius: 2,
       data: row as Record<string, unknown>,
       aria,

package/src/compile.ts

@@ -375,19 +375,28 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   // Compute scales
   const scales = computeScales(renderSpec, chartArea, renderSpec.data);
 
-  // Update color scale to use theme palette
+  // Update color scale to use theme palette (only when user hasn't provided an explicit range)
   if (scales.color) {
+    const hasExplicitRange = !!(
+      renderSpec.encoding.color &&
+      'field' in renderSpec.encoding.color &&
+      (renderSpec.encoding.color.scale?.range as string[] | undefined)?.length
+    );
     if (scales.color.type === 'sequential') {
       // Sequential: use first sequential palette (or fall back to categorical endpoints)
-      const seqStops = Object.values(theme.colors.sequential)[0] ?? theme.colors.categorical;
-      (scales.color.scale as unknown as import('d3-scale').ScaleLinear<string, string>).range([
-        seqStops[0],
-        seqStops[seqStops.length - 1],
-      ]);
+      if (!hasExplicitRange) {
+        const seqStops = Object.values(theme.colors.sequential)[0] ?? theme.colors.categorical;
+        (scales.color.scale as unknown as import('d3-scale').ScaleLinear<string, string>).range([
+          seqStops[0],
+          seqStops[seqStops.length - 1],
+        ]);
+      }
     } else {
-      (scales.color.scale as import('d3-scale').ScaleOrdinal<string, string>).range(
-        theme.colors.categorical,
-      );
+      if (!hasExplicitRange) {
+        (scales.color.scale as import('d3-scale').ScaleOrdinal<string, string>).range(
+          theme.colors.categorical,
+        );
+      }
     }
   }
 

package/src/compiler/validate.ts

@@ -186,7 +186,7 @@ function validateChartSpec(spec: Record<string, unknown>, errors: ValidationErro
         message: `Spec error: encoding.${channel} must have a "field" string`,
         path: `encoding.${channel}.field`,
         code: 'MISSING_FIELD',
-        suggestion: `Add a field name from your data columns: ${availableColumns}`,
+        suggestion: `For constant colors, use mark.fill (e.g., mark: { type: "bar", fill: "#1b7fa3" }) instead of encoding.${channel}. Encoding channels require a data field: ${availableColumns}`,
       });
       continue;
     }

package/src/layout/dimensions.ts

@@ -185,7 +185,7 @@ export function computeDimensions(
         }
       }
       if (maxLabelWidth > 0) {
-        margins.right = Math.max(margins.right, padding + maxLabelWidth + 16);
+        margins.right = Math.max(margins.right, padding + maxLabelWidth + 8);
       }
     }
   }

package/src/layout/scales.ts

@@ -512,7 +512,11 @@ function buildOrdinalColorScale(
     ? explicitDomain.map(String)
     : applyCategoricalSort(uniqueStrings(fieldValues(data, channel.field)), channel.sort);
 
-  const scale = scaleOrdinal<string>().domain(values).range(palette);
+  // Use explicit range if provided, otherwise fall back to theme palette
+  const explicitRange = channel.scale?.range as string[] | undefined;
+  const colors = explicitRange ?? palette;
+
+  const scale = scaleOrdinal<string>().domain(values).range(colors);
 
   return { scale, type: 'ordinal', channel };
 }
@@ -526,9 +530,13 @@ function buildSequentialColorScale(
   const domainMin = min(values) ?? 0;
   const domainMax = max(values) ?? 1;
 
+  // Use explicit range if provided, otherwise fall back to theme palette endpoints
+  const explicitRange = channel.scale?.range as string[] | undefined;
+  const colors = explicitRange ?? palette;
+
   const scale = scaleLinear<string>()
     .domain([domainMin, domainMax])
-    .range([palette[0], palette[palette.length - 1]])
+    .range([colors[0], colors[colors.length - 1]])
     .clamp(true);
 
   // Cast: sequential color scale (number -> string) is structurally incompatible

package/src/legend/compute.ts

@@ -70,15 +70,26 @@ function extractColorEntries(spec: NormalizedChartSpec, theme: ResolvedTheme): L
   if (colorEnc.type === 'quantitative') return [];
 
   const uniqueValues = [...new Set(spec.data.map((d) => String(d[colorEnc.field])))];
-  const palette = theme.colors.categorical;
+  const explicitDomain = colorEnc.scale?.domain as string[] | undefined;
+  const explicitRange = colorEnc.scale?.range as string[] | undefined;
+  const palette = explicitRange ?? theme.colors.categorical;
   const shape = swatchShapeForType(spec.markType);
 
-  return uniqueValues.map((value, i) => ({
-    label: value,
-    color: palette[i % palette.length],
-    shape,
-    active: true,
-  }));
+  return uniqueValues.map((value, i) => {
+    // When explicit domain+range are provided, look up the color by domain index
+    // so legend colors match the mark colors exactly.
+    let colorIndex = i;
+    if (explicitDomain && explicitRange) {
+      const domainIdx = explicitDomain.indexOf(value);
+      if (domainIdx >= 0) colorIndex = domainIdx;
+    }
+    return {
+      label: value,
+      color: palette[colorIndex % palette.length],
+      shape,
+      active: true,
+    };
+  });
 }
 
 /**

package/src/tables/__tests__/category-colors.test.ts

@@ -89,7 +89,7 @@ describe('computeCategoryColors', () => {
     }
   });
 
-  it('dark mode adapts colors', () => {
+  it('dark mode preserves explicit user-provided colors', () => {
     const col: ColumnConfig = {
       key: 'status',
       categoryColors: {
@@ -97,18 +97,32 @@ describe('computeCategoryColors', () => {
         inactive: '#ff0000',
       },
     };
-    const lightTheme = getTheme(false);
     const darkTheme = getTheme(true);
+    const colors = computeCategoryColors(data, col, darkTheme, true);
 
-    const lightColors = computeCategoryColors(data, col, lightTheme, false);
+    // Explicit colors should NOT be adapted for dark mode
+    expect(colors.get(0)!.backgroundColor).toBe('#00ff00');
+    expect(colors.get(1)!.backgroundColor).toBe('#ff0000');
+  });
+
+  it('dark mode adapts auto-assigned palette colors but not explicit ones', () => {
+    // Use a bright yellow that will definitely get adapted in dark mode
+    const col: ColumnConfig = {
+      key: 'status',
+      categoryColors: {
+        active: '#ffff00',
+      },
+    };
+    const darkTheme = getTheme(true);
     const darkColors = computeCategoryColors(data, col, darkTheme, true);
 
-    expect(lightColors.size).toBe(darkColors.size);
+    // Explicit color should be preserved as-is (not adapted)
+    expect(darkColors.get(0)!.backgroundColor).toBe('#ffff00');
 
-    // Dark mode colors should be adapted (different from light mode)
-    const lightBg = lightColors.get(0)!.backgroundColor;
-    const darkBg = darkColors.get(0)!.backgroundColor;
-    expect(darkBg).not.toBe(lightBg);
+    // Auto-assigned palette colors should still be present (adaptation may or
+    // may not visually change them, but the code path runs adaptColorForDarkMode)
+    expect(darkColors.has(1)).toBe(true); // inactive
+    expect(darkColors.has(3)).toBe(true); // pending
   });
 
   it('dark mode text contrast still meets AA', () => {
@@ -137,6 +151,34 @@ describe('computeCategoryColors', () => {
     expect(colors.size).toBe(0);
   });
 
+  it('skips transparent and none category colors', () => {
+    const dataWithSpecial = [
+      { status: 'active' },
+      { status: 'inactive' },
+      { status: 'pending' },
+      { status: 'disabled' },
+    ];
+    const col: ColumnConfig = {
+      key: 'status',
+      categoryColors: {
+        active: '#00ff00',
+        inactive: 'transparent',
+        pending: 'none',
+        disabled: '#cccccc',
+      },
+    };
+    const theme = getTheme();
+    const colors = computeCategoryColors(dataWithSpecial, col, theme, false);
+
+    // transparent and none rows should be skipped
+    expect(colors.has(1)).toBe(false); // inactive = transparent
+    expect(colors.has(2)).toBe(false); // pending = none
+    // explicit colors should still be present
+    expect(colors.get(0)!.backgroundColor).toBe('#00ff00');
+    expect(colors.get(3)!.backgroundColor).toBe('#cccccc');
+    expect(colors.size).toBe(2);
+  });
+
   it('skips null values', () => {
     const dataWithNull = [{ status: 'active' }, { status: null }, { status: 'inactive' }];
     const col: ColumnConfig = {

package/src/tables/category-colors.ts

@@ -39,9 +39,15 @@ export function computeCategoryColors(
 
     const key = String(raw);
     let bg: string;
+    let isExplicit = false;
 
-    if (explicitMap[key]) {
+    if (explicitMap[key] != null) {
+      if (explicitMap[key] === 'transparent' || explicitMap[key] === 'none') {
+        // Skip transparent/none — let the cell inherit default table styling
+        continue;
+      }
       bg = explicitMap[key];
+      isExplicit = true;
     } else if (autoAssigned.has(key)) {
       bg = autoAssigned.get(key)!;
     } else {
@@ -51,8 +57,8 @@ export function computeCategoryColors(
       autoAssigned.set(key, bg);
     }
 
-    // Dark mode adaptation
-    if (darkMode) {
+    // Dark mode adaptation (skip for explicit user-provided colors)
+    if (darkMode && !isExplicit) {
       bg = adaptColorForDarkMode(bg, lightBg, darkBg);
     }
 

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

@@ -14,6 +14,15 @@ describe('evaluatePredicate', () => {
     it('matches equal numeric value', () => {
       expect(evaluatePredicate({ age: 30 }, { field: 'age', equal: 30 })).toBe(true);
     });
+
+    it('matches string value against numeric predicate via loose equality', () => {
+      // CSV/JSON parsing often produces string values for numeric fields
+      expect(evaluatePredicate({ id: '181' }, { field: 'id', equal: 181 })).toBe(true);
+    });
+
+    it('matches numeric value against string predicate via loose equality', () => {
+      expect(evaluatePredicate({ id: 181 }, { field: 'id', equal: '181' })).toBe(true);
+    });
   });
 
   describe('FieldPredicate: lt/lte/gt/gte', () => {
@@ -62,6 +71,14 @@ describe('evaluatePredicate', () => {
     it('rejects values not in the set', () => {
       expect(evaluatePredicate({ c: 'green' }, { field: 'c', oneOf: ['red', 'blue'] })).toBe(false);
     });
+
+    it('matches string value against numeric oneOf via loose equality', () => {
+      expect(evaluatePredicate({ id: '181' }, { field: 'id', oneOf: [181, 200] })).toBe(true);
+    });
+
+    it('rejects value not in numeric oneOf set', () => {
+      expect(evaluatePredicate({ id: '999' }, { field: 'id', oneOf: [181, 200] })).toBe(false);
+    });
   });
 
   describe('FieldPredicate: valid', () => {

package/src/transforms/predicates.ts

@@ -26,9 +26,11 @@ function evaluateFieldPredicate(datum: DataRow, pred: FieldPredicate): boolean {
     return pred.valid ? isValid : !isValid;
   }
 
-  // equal
+  // equal: use loose equality so "181" == 181 matches across type boundaries
+  // (data values may arrive as strings from CSV/JSON parsing)
   if (pred.equal !== undefined) {
-    return value === pred.equal;
+    // biome-ignore lint/suspicious/noDoubleEquals: intentional loose equality for CSV/JSON type coercion
+    return value == pred.equal;
   }
 
   // Numeric comparisons
@@ -53,9 +55,10 @@ function evaluateFieldPredicate(datum: DataRow, pred: FieldPredicate): boolean {
     return numValue >= min && numValue <= max;
   }
 
-  // oneOf: value is in the set
+  // oneOf: use loose equality (same rationale as equal above)
   if (pred.oneOf !== undefined) {
-    return pred.oneOf.includes(value);
+    // biome-ignore lint/suspicious/noDoubleEquals: intentional loose equality for CSV/JSON type coercion
+    return pred.oneOf.some((v) => v == value);
   }
 
   // No condition specified, default to true