@opendata-ai/openchart-engine 6.15.1 → 6.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-engine",
-  "version": "6.15.1",
+  "version": "6.17.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.1",
+    "@opendata-ai/openchart-core": "6.17.0",
     "d3-array": "^3.2.0",
     "d3-format": "^3.1.2",
     "d3-interpolate": "^3.0.0",

package/src/__tests__/axes.test.ts

@@ -127,7 +127,7 @@ describe('computeAxes', () => {
     const axesShort = computeAxes(scales, shortArea, fullStrategy, theme);
 
     // Even though the strategy says 'full', height < 120 forces minimal (3 ticks)
-    expect(axesShort.y!.ticks.length).toBeLessThanOrEqual(3);
+    expect(axesShort.y!.ticks.length).toBeLessThanOrEqual(4);
   });
 
   it('reduces y-axis ticks for medium-short chart areas (120-200px)', () => {
@@ -150,7 +150,7 @@ describe('computeAxes', () => {
 
     // Strategy already says minimal - short height shouldn't change anything
     const axes = computeAxes(scales, shortArea, minimalStrategy, theme);
-    expect(axes.y!.ticks.length).toBeLessThanOrEqual(3);
+    expect(axes.y!.ticks.length).toBeLessThanOrEqual(4);
   });
 
   // -------------------------------------------------------------------------
@@ -163,7 +163,7 @@ describe('computeAxes', () => {
     const axes = computeAxes(scales, narrowArea, fullStrategy, theme);
 
     // Width < 150 forces minimal density for x-axis
-    expect(axes.x!.ticks.length).toBeLessThanOrEqual(3);
+    expect(axes.x!.ticks.length).toBeLessThanOrEqual(4);
   });
 
   it('reduces x-axis ticks for medium-narrow chart areas (150-300px)', () => {
@@ -194,8 +194,8 @@ describe('computeAxes', () => {
     const axesFull = computeAxes(scalesFull, fullArea, fullStrategy, theme);
 
     // Both axes should have minimal ticks in a thumbnail
-    expect(axesThumb.x!.ticks.length).toBeLessThanOrEqual(3);
-    expect(axesThumb.y!.ticks.length).toBeLessThanOrEqual(3);
+    expect(axesThumb.x!.ticks.length).toBeLessThanOrEqual(4);
+    expect(axesThumb.y!.ticks.length).toBeLessThanOrEqual(4);
 
     // And fewer than full-size
     expect(axesThumb.x!.ticks.length).toBeLessThanOrEqual(axesFull.x!.ticks.length);

package/src/__tests__/compile-chart.test.ts

@@ -66,8 +66,8 @@ describe('compileChart', () => {
     // Annotations array exists (empty for this spec since none were specified)
     expect(layout.annotations).toEqual([]);
 
-    // Legend has entries for the two series
-    expect(layout.legend.entries.length).toBe(2);
+    // Legend is auto-suppressed for line charts with endpoint labels
+    expect(layout.legend.entries.length).toBe(0);
 
     // Tooltip descriptors is a Map (may or may not have entries depending on marks)
     expect(layout.tooltipDescriptors).toBeInstanceOf(Map);
@@ -147,8 +147,11 @@ describe('compileChart', () => {
     expect(layout.axes.y!.start.y).not.toBe(layout.axes.y!.end.y);
   });
 
-  it('has a legend when color encoding is present', () => {
-    const layout = compileChart(lineSpec, { width: 600, height: 400 });
+  it('has a legend when color encoding is present and legend forced on', () => {
+    const layout = compileChart(
+      { ...lineSpec, legend: { show: true } },
+      { width: 600, height: 400 },
+    );
     expect(layout.legend.entries.length).toBeGreaterThan(0);
     expect(layout.legend.entries.some((e) => e.label === 'US')).toBe(true);
     expect(layout.legend.entries.some((e) => e.label === 'UK')).toBe(true);
@@ -280,6 +283,7 @@ describe('compileChart', () => {
     const spec = {
       ...lineSpec,
       hiddenSeries: ['UK'],
+      legend: { show: true },
     };
     const layout = compileChart(spec, { width: 600, height: 400 });
 
@@ -583,6 +587,7 @@ describe('compileGraph', () => {
   it('applies breakpoint override for legend show', () => {
     const spec = {
       ...lineSpec,
+      legend: { show: true },
       overrides: {
         compact: {
           legend: { show: false },

package/src/__tests__/legend.test.ts

@@ -22,7 +22,7 @@ const specWithColor: NormalizedChartSpec = {
   responsive: true,
   theme: {},
   darkMode: 'off',
-  labels: { density: 'auto', format: '' },
+  labels: { density: 'none', format: '', prefix: '' },
 };
 
 const specWithoutColor: NormalizedChartSpec = {
@@ -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');
@@ -273,4 +305,92 @@ describe('computeLegend', () => {
     const scatterLegend = computeLegend(scatterSpec, fullStrategy, theme, chartArea);
     expect(scatterLegend.entries[0].shape).toBe('circle');
   });
+
+  describe('auto-suppression for line/area with endpoint labels', () => {
+    /** Line spec with labels enabled for suppression tests. */
+    const lineWithLabels: NormalizedChartSpec = {
+      ...specWithColor,
+      labels: { density: 'auto', format: '', prefix: '' },
+    };
+
+    it('suppresses legend for multi-series line chart with default labels', () => {
+      const legend = computeLegend(lineWithLabels, fullStrategy, theme, chartArea);
+      expect(legend.entries).toHaveLength(0);
+    });
+
+    it('preserves legend when legend.show is explicitly true', () => {
+      const spec: NormalizedChartSpec = {
+        ...lineWithLabels,
+        legend: { show: true },
+        hiddenSeries: [],
+        seriesStyles: {},
+      };
+      const legend = computeLegend(spec, fullStrategy, theme, chartArea);
+      expect(legend.entries).toHaveLength(3);
+    });
+
+    it('preserves legend when labels density is none', () => {
+      const spec: NormalizedChartSpec = {
+        ...lineWithLabels,
+        labels: { density: 'none', format: '', prefix: '' },
+      };
+      const legend = computeLegend(spec, fullStrategy, theme, chartArea);
+      expect(legend.entries).toHaveLength(3);
+    });
+
+    it('preserves legend at compact breakpoint where labelMode is none', () => {
+      const legend = computeLegend(lineWithLabels, compactStrategy, theme, chartArea);
+      expect(legend.entries).toHaveLength(3);
+    });
+
+    it('preserves legend for stacked area chart (default stacking)', () => {
+      const areaSpec: NormalizedChartSpec = {
+        ...lineWithLabels,
+        markType: 'area',
+        markDef: { type: 'area' },
+      };
+      const legend = computeLegend(areaSpec, fullStrategy, theme, chartArea);
+      expect(legend.entries).toHaveLength(3);
+    });
+
+    it('suppresses legend for unstacked area chart with labels', () => {
+      const areaSpec: NormalizedChartSpec = {
+        ...lineWithLabels,
+        markType: 'area',
+        markDef: { type: 'area' },
+        encoding: {
+          x: { field: 'date', type: 'temporal' },
+          y: { field: 'value', type: 'quantitative', stack: null },
+          color: { field: 'country', type: 'nominal' },
+        },
+      };
+      const legend = computeLegend(areaSpec, fullStrategy, theme, chartArea);
+      expect(legend.entries).toHaveLength(0);
+    });
+
+    it('preserves legend for bar chart (not line/area)', () => {
+      const barSpec: NormalizedChartSpec = {
+        ...lineWithLabels,
+        markType: 'bar',
+        markDef: { type: 'bar' },
+        encoding: {
+          x: { field: 'date', type: 'nominal' },
+          y: { field: 'value', type: 'quantitative' },
+          color: { field: 'country', type: 'nominal' },
+        },
+      };
+      const legend = computeLegend(barSpec, fullStrategy, theme, chartArea);
+      expect(legend.entries).toHaveLength(3);
+    });
+
+    it('does not suppress for single-series line (no color encoding)', () => {
+      const noColorWithLabels: NormalizedChartSpec = {
+        ...specWithoutColor,
+        labels: { density: 'auto', format: '', prefix: '' },
+      };
+      const legend = computeLegend(noColorWithLabels, fullStrategy, theme, chartArea);
+      expect(legend.entries).toHaveLength(0);
+      expect(legend.bounds.width).toBe(0);
+    });
+  });
 });

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/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/layout/axes.ts

@@ -38,9 +38,9 @@ import type {
 
 /** Base tick counts by axis label density. */
 const TICK_COUNTS: Record<AxisLabelDensity, number> = {
-  full: 10,
-  reduced: 7,
-  minimal: 3,
+  full: 12,
+  reduced: 8,
+  minimal: 4,
 };
 
 /**

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,
+    };
+  });
 }
 
 /**
@@ -173,6 +184,27 @@ export function computeLegend(
 
   let entries = extractColorEntries(spec, theme);
 
+  // Auto-suppress legend when endpoint labels identify series on line/area charts.
+  // Guards: keep legend at compact breakpoints (labels hidden), for stacked areas
+  // (endpoint labels overlap), and when user explicitly forces legend on.
+  const isLineOrArea = spec.markType === 'line' || spec.markType === 'area';
+  const hasLabels = spec.labels.density !== 'none';
+  const labelsWillRender = strategy.labelMode !== 'none';
+  const hasColorEncoding = spec.encoding.color != null;
+  const legendNotForced = spec.legend?.show !== true;
+
+  if (isLineOrArea && hasLabels && labelsWillRender && hasColorEncoding && legendNotForced) {
+    const isArea = spec.markType === 'area';
+    const quantChannel =
+      spec.encoding.y?.type === 'quantitative' ? spec.encoding.y : spec.encoding.x;
+    const stackValue = quantChannel?.stack;
+    const isStacked = stackValue !== null && stackValue !== false;
+
+    if (!isArea || !isStacked) {
+      entries = [];
+    }
+  }
+
   const labelStyle: TextStyle = {
     fontFamily: theme.fonts.family,
     fontSize: theme.fonts.sizes.small,

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

@@ -27,32 +27,53 @@ describe('computeCategoryColors', () => {
     const theme = getTheme();
     const colors = computeCategoryColors(data, col, theme, false);
 
-    expect(colors.size).toBe(4);
+    expect(colors.size).toBe(3);
     // "active" rows (indices 0, 2) should have green background
     expect(colors.get(0)!.backgroundColor).toBe('#00ff00');
     expect(colors.get(2)!.backgroundColor).toBe('#00ff00');
     // "inactive" row (index 1) should have red background
     expect(colors.get(1)!.backgroundColor).toBe('#ff0000');
+    // "pending" (index 3) is not in the explicit map, should be skipped
+    expect(colors.has(3)).toBe(false);
+  });
+
+  it('unmapped values are skipped by default', () => {
+    const col: ColumnConfig = {
+      key: 'status',
+      categoryColors: {
+        active: '#00ff00',
+      },
+    };
+    const theme = getTheme();
+    const colors = computeCategoryColors(data, col, theme, false);
+
+    // Only "active" rows (indices 0, 2) should be colored
+    expect(colors.size).toBe(2);
+    expect(colors.get(0)!.backgroundColor).toBe('#00ff00');
+    expect(colors.get(2)!.backgroundColor).toBe('#00ff00');
+    // Unmapped values should not have entries
+    expect(colors.has(1)).toBe(false); // inactive
+    expect(colors.has(3)).toBe(false); // pending
   });
 
-  it('unmapped values get palette colors', () => {
+  it('autoAssign: true assigns palette colors to unmapped values', () => {
     const col: ColumnConfig = {
       key: 'status',
       categoryColors: {
         active: '#00ff00',
       },
+      autoAssign: true,
     };
     const theme = getTheme();
     const colors = computeCategoryColors(data, col, theme, false);
 
-    // "inactive" and "pending" are not in the explicit map, should get palette colors
+    // All 4 rows should be colored
+    expect(colors.size).toBe(4);
+    // "inactive" and "pending" should get palette colors (not the explicit green)
     const inactiveBg = colors.get(1)!.backgroundColor!;
     const pendingBg = colors.get(3)!.backgroundColor!;
-
-    // They should be assigned from the categorical palette
     expect(inactiveBg).toBeTruthy();
     expect(pendingBg).toBeTruthy();
-    // They should not be the explicit mapped color
     expect(inactiveBg).not.toBe('#00ff00');
   });
 
@@ -89,7 +110,7 @@ describe('computeCategoryColors', () => {
     }
   });
 
-  it('dark mode adapts colors', () => {
+  it('dark mode preserves explicit user-provided colors', () => {
     const col: ColumnConfig = {
       key: 'status',
       categoryColors: {
@@ -97,18 +118,46 @@ describe('computeCategoryColors', () => {
         inactive: '#ff0000',
       },
     };
-    const lightTheme = getTheme(false);
     const darkTheme = getTheme(true);
+    const colors = computeCategoryColors(data, col, darkTheme, true);
+
+    // Explicit colors should NOT be adapted for dark mode
+    expect(colors.get(0)!.backgroundColor).toBe('#00ff00');
+    expect(colors.get(1)!.backgroundColor).toBe('#ff0000');
+  });
 
-    const lightColors = computeCategoryColors(data, col, lightTheme, false);
+  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',
+      },
+      autoAssign: true,
+    };
+    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');
+
+    // 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('autoAssign: true gives same value consistent color across rows', () => {
+    const col: ColumnConfig = {
+      key: 'status',
+      categoryColors: {},
+      autoAssign: true,
+    };
+    const theme = getTheme();
+    const colors = computeCategoryColors(data, col, theme, false);
 
-    // 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);
+    // Both "active" rows should get the same auto-assigned color
+    expect(colors.get(0)!.backgroundColor).toBe(colors.get(2)!.backgroundColor);
   });
 
   it('dark mode text contrast still meets AA', () => {
@@ -137,6 +186,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,20 +39,31 @@ 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];
-    } else if (autoAssigned.has(key)) {
-      bg = autoAssigned.get(key)!;
+      isExplicit = true;
+    } else if (column.autoAssign) {
+      // Auto-assign from palette only when explicitly opted in
+      if (autoAssigned.has(key)) {
+        bg = autoAssigned.get(key)!;
+      } else {
+        bg = categoricalPalette[nextPaletteIndex % categoricalPalette.length];
+        nextPaletteIndex++;
+        autoAssigned.set(key, bg);
+      }
     } else {
-      // Assign from categorical palette
-      bg = categoricalPalette[nextPaletteIndex % categoricalPalette.length];
-      nextPaletteIndex++;
-      autoAssigned.set(key, bg);
+      // Default: skip unmapped values (no color assigned)
+      continue;
     }
 
-    // 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