@opendata-ai/openchart-engine 6.10.0 → 6.11.0

package/package.json

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

package/src/charts/bar/compute.ts

@@ -10,12 +10,13 @@ import type {
   ConditionalValueDef,
   DataRow,
   Encoding,
+  GradientDef,
   LayoutStrategy,
   MarkAria,
   Rect,
   RectMark,
 } from '@opendata-ai/openchart-core';
-import { abbreviateNumber, formatNumber } 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';
@@ -339,11 +340,14 @@ function computeSimpleBars(
     const bandY = yScale(category);
     if (bandY === undefined) continue;
 
-    let color: string;
+    let color: string | GradientDef;
     if (conditionalColor) {
-      color = String(
-        resolveConditionalValue(row, conditionalColor) ?? getColor(scales, '__default__'),
-      );
+      const resolved = resolveConditionalValue(row, conditionalColor);
+      if (resolved != null) {
+        color = isGradientDef(resolved) ? resolved : String(resolved);
+      } else {
+        color = getColor(scales, '__default__');
+      }
     } else if (sequentialColor) {
       color = getSequentialColor(scales, value);
     } else {

package/src/charts/bar/labels.ts

@@ -20,6 +20,7 @@ import type {
 import {
   buildD3Formatter,
   estimateTextWidth,
+  getRepresentativeColor,
   resolveCollisions,
 } from '@opendata-ai/openchart-core';
 
@@ -141,7 +142,7 @@ export function computeBarLabels(
     } else {
       // Outside: just past the bar's right edge
       anchorX = mark.x + mark.width + LABEL_PADDING;
-      fill = mark.fill;
+      fill = getRepresentativeColor(mark.fill);
       textAnchor = 'start';
     }
 

package/src/charts/column/compute.ts

@@ -14,12 +14,13 @@ import type {
   ConditionalValueDef,
   DataRow,
   Encoding,
+  GradientDef,
   LayoutStrategy,
   MarkAria,
   Rect,
   RectMark,
 } from '@opendata-ai/openchart-core';
-import { abbreviateNumber, formatNumber } 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';
@@ -169,11 +170,14 @@ function computeSimpleColumns(
     const bandX = xScale(category);
     if (bandX === undefined) continue;
 
-    let color: string;
+    let color: string | GradientDef;
     if (conditionalColor) {
-      color = String(
-        resolveConditionalValue(row, conditionalColor) ?? getColor(scales, '__default__'),
-      );
+      const resolved = resolveConditionalValue(row, conditionalColor);
+      if (resolved != null) {
+        color = isGradientDef(resolved) ? resolved : String(resolved);
+      } else {
+        color = getColor(scales, '__default__');
+      }
     } else if (sequentialColor) {
       color = getSequentialColor(scales, value);
     } else {

package/src/charts/column/labels.ts

@@ -20,6 +20,7 @@ import type {
 import {
   buildD3Formatter,
   estimateTextWidth,
+  getRepresentativeColor,
   resolveCollisions,
 } from '@opendata-ai/openchart-core';
 
@@ -99,7 +100,7 @@ export function computeColumnLabels(
         fontFamily: 'system-ui, -apple-system, sans-serif',
         fontSize: LABEL_FONT_SIZE,
         fontWeight: LABEL_FONT_WEIGHT,
-        fill: mark.fill,
+        fill: getRepresentativeColor(mark.fill),
         lineHeight: 1.2,
         textAnchor: 'middle',
         dominantBaseline: isNegative ? 'hanging' : 'auto',

package/src/charts/dot/labels.ts

@@ -17,7 +17,11 @@ import type {
   Rect,
   ResolvedLabel,
 } from '@opendata-ai/openchart-core';
-import { estimateTextWidth, resolveCollisions } from '@opendata-ai/openchart-core';
+import {
+  estimateTextWidth,
+  getRepresentativeColor,
+  resolveCollisions,
+} from '@opendata-ai/openchart-core';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -74,7 +78,7 @@ export function computeDotLabels(
         fontFamily: 'system-ui, -apple-system, sans-serif',
         fontSize: LABEL_FONT_SIZE,
         fontWeight: LABEL_FONT_WEIGHT,
-        fill: mark.fill,
+        fill: getRepresentativeColor(mark.fill),
         lineHeight: 1.2,
         textAnchor: 'start',
         dominantBaseline: 'central',

package/src/charts/line/area.ts

@@ -7,6 +7,7 @@
  */
 
 import type { AreaMark, DataRow, Encoding, MarkAria, Rect } from '@opendata-ai/openchart-core';
+import { getRepresentativeColor } from '@opendata-ai/openchart-core';
 import type { ScaleLinear } from 'd3-scale';
 import { area, line, stack, stackOffsetNone, stackOrderNone } from 'd3-shape';
 
@@ -122,7 +123,7 @@ function computeSingleArea(
       topPath: topPathStr,
       fill: color,
       fillOpacity: DEFAULT_FILL_OPACITY,
-      stroke: color,
+      stroke: getRepresentativeColor(color),
       strokeWidth: 2,
       seriesKey: seriesKey === '__default__' ? undefined : seriesKey,
       data: validPoints.map((p) => p.row),
@@ -258,7 +259,7 @@ function computeStackedArea(
       topPath: topPathStr,
       fill: color,
       fillOpacity: 0.7, // Higher opacity for stacked so layers are visible
-      stroke: color,
+      stroke: getRepresentativeColor(color),
       strokeWidth: 1,
       seriesKey,
       data: layer.map((d) => {

package/src/charts/line/compute.ts

@@ -10,12 +10,14 @@
 import type {
   DataRow,
   Encoding,
+  GradientDef,
   LayoutStrategy,
   LineMark,
   MarkAria,
   PointMark,
   Rect,
 } from '@opendata-ai/openchart-core';
+import { getRepresentativeColor } from '@opendata-ai/openchart-core';
 import { line } from 'd3-shape';
 
 import type { NormalizedChartSpec } from '../../compiler/types';
@@ -68,9 +70,10 @@ export function computeLineMarks(
 
   for (const [seriesKey, rows] of groups) {
     // For sequential color, use a mid-range color for the line stroke
-    const color = isSequentialColor
+    const color: string | GradientDef = isSequentialColor
       ? getSequentialColor(scales, _getMidValue(rows, sequentialColorField!))
       : getColor(scales, seriesKey);
+    const strokeColor = getRepresentativeColor(color);
 
     // Sort rows by x-axis field so lines draw left-to-right
     const sortedRows = sortByField(rows, xChannel.field);
@@ -165,7 +168,7 @@ export function computeLineMarks(
       type: 'line',
       points: allPoints,
       path: combinedPath,
-      stroke: color,
+      stroke: strokeColor,
       strokeWidth: styleOverride?.strokeWidth ?? DEFAULT_STROKE_WIDTH,
       strokeDasharray,
       opacity: styleOverride?.opacity,

package/src/charts/pie/compute.ts

@@ -8,17 +8,21 @@
 
 import type {
   ArcMark,
+  ConditionalValueDef,
   DataRow,
   Encoding,
+  GradientDef,
   LayoutStrategy,
   MarkAria,
   Rect,
 } from '@opendata-ai/openchart-core';
+import { isConditionalDef, isGradientDef } from '@opendata-ai/openchart-core';
 import type { PieArcDatum } from 'd3-shape';
 import { arc as d3Arc, pie as d3Pie } from 'd3-shape';
 
 import type { NormalizedChartSpec } from '../../compiler/types';
 import type { ResolvedScales } from '../../layout/scales';
+import { resolveConditionalValue } from '../../transforms/conditional';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -109,6 +113,10 @@ export function computePieMarks(
   const valueChannel = encoding.y ?? encoding.x;
   const categoryField =
     encoding.color && 'field' in encoding.color ? encoding.color.field : undefined;
+  const conditionalColor =
+    encoding.color && isConditionalDef(encoding.color)
+      ? (encoding.color as ConditionalValueDef)
+      : undefined;
 
   if (!valueChannel) return [];
 
@@ -190,9 +198,22 @@ export function computePieMarks(
     const arcDatum = arcs[i];
     const slice = arcDatum.data;
 
-    // Get color from scale or default palette
-    let color: string;
-    if (scales.color && categoryField) {
+    // Get color: conditional (supports gradients) > scale > default palette
+    let color: string | GradientDef;
+    if (conditionalColor) {
+      const resolved = resolveConditionalValue(
+        slice.originalRow as Record<string, unknown>,
+        conditionalColor,
+      );
+      if (resolved != null) {
+        color = isGradientDef(resolved) ? resolved : String(resolved);
+      } else if (scales.color && categoryField) {
+        const colorScale = scales.color.scale as (v: string) => string;
+        color = colorScale(slice.label);
+      } else {
+        color = DEFAULT_PALETTE[i % DEFAULT_PALETTE.length];
+      }
+    } else if (scales.color && categoryField) {
       const colorScale = scales.color.scale as (v: string) => string;
       color = colorScale(slice.label);
     } else {

package/src/charts/rule/index.ts

@@ -7,6 +7,7 @@
  */
 
 import type { Encoding, Mark, MarkAria, Rect, RuleMarkLayout } from '@opendata-ai/openchart-core';
+import { getRepresentativeColor } from '@opendata-ai/openchart-core';
 
 import type { NormalizedChartSpec } from '../../compiler/types';
 import type { ResolvedScales } from '../../layout/scales';
@@ -84,9 +85,11 @@ export function computeRuleMarks(
       if (y2Val != null) y2 = y2Val;
     }
 
-    const color = colorField
-      ? getColor(scales, String(row[colorField] ?? '__default__'))
-      : getColor(scales, '__default__');
+    const color = getRepresentativeColor(
+      colorField
+        ? getColor(scales, String(row[colorField] ?? '__default__'))
+        : getColor(scales, '__default__'),
+    );
 
     const strokeDashEncoding =
       encoding.strokeDash && 'field' in encoding.strokeDash ? encoding.strokeDash : undefined;

package/src/charts/scatter/compute.ts

@@ -10,6 +10,7 @@
 import type {
   Encoding,
   FieldType,
+  GradientDef,
   LayoutStrategy,
   MarkAria,
   PointMark,
@@ -139,7 +140,7 @@ export function computeScatterMarks(
     if (cx === undefined || cy === undefined) continue;
 
     const category = colorField && !isSequentialColor ? String(row[colorField] ?? '') : undefined;
-    let color: string;
+    let color: string | GradientDef;
     if (isSequentialColor && colorField) {
       const val = Number(row[colorField]);
       color = Number.isFinite(val)

package/src/charts/text/index.ts

@@ -7,6 +7,7 @@
  */
 
 import type { Encoding, Mark, MarkAria, TextMarkLayout } from '@opendata-ai/openchart-core';
+import { getRepresentativeColor } from '@opendata-ai/openchart-core';
 
 import type { NormalizedChartSpec } from '../../compiler/types';
 import type { ResolvedScales } from '../../layout/scales';
@@ -52,9 +53,11 @@ export function computeTextMarks(
     const text = String(row[textChannel.field] ?? '');
     if (!text) continue;
 
-    const color = colorField
-      ? getColor(scales, String(row[colorField] ?? '__default__'))
-      : getColor(scales, '__default__');
+    const color = getRepresentativeColor(
+      colorField
+        ? getColor(scales, String(row[colorField] ?? '__default__'))
+        : getColor(scales, '__default__'),
+    );
 
     const fontSize = sizeEncoding
       ? Math.max(8, Math.min(48, Number(row[sizeEncoding.field]) || 12))

package/src/charts/tick/index.ts

@@ -7,6 +7,7 @@
  */
 
 import type { Encoding, Mark, MarkAria, Rect, TickMarkLayout } from '@opendata-ai/openchart-core';
+import { getRepresentativeColor } from '@opendata-ai/openchart-core';
 
 import type { NormalizedChartSpec } from '../../compiler/types';
 import type { ResolvedScales } from '../../layout/scales';
@@ -48,9 +49,11 @@ export function computeTickMarks(
     const yVal = scaleValue(scales.y.scale, scales.y.type, row[yChannel.field]);
     if (xVal == null || yVal == null) continue;
 
-    const color = colorField
-      ? getColor(scales, String(row[colorField] ?? '__default__'))
-      : getColor(scales, '__default__');
+    const color = getRepresentativeColor(
+      colorField
+        ? getColor(scales, String(row[colorField] ?? '__default__'))
+        : getColor(scales, '__default__'),
+    );
 
     const aria: MarkAria = {
       label: `${row[xChannel.field]}, ${row[yChannel.field]}`,

package/src/charts/utils.ts

@@ -5,7 +5,7 @@
  * data grouping, color lookup, and shared constants.
  */
 
-import type { DataRow } from '@opendata-ai/openchart-core';
+import type { DataRow, GradientDef } from '@opendata-ai/openchart-core';
 import type { ScaleBand, ScaleLinear, ScalePoint, ScaleTime } from 'd3-scale';
 import type { D3Scale, ResolvedScales } from '../layout/scales';
 
@@ -143,7 +143,7 @@ export function getColor(
   key: string,
   _index?: number,
   fallback: string = DEFAULT_COLOR,
-): string {
+): string | GradientDef {
   if (scales.color && key !== '__default__') {
     const colorScale = scales.color.scale as (v: string) => string;
     return colorScale(key);
@@ -159,7 +159,7 @@ export function getSequentialColor(
   scales: ResolvedScales,
   value: number,
   fallback: string = DEFAULT_COLOR,
-): string {
+): string | GradientDef {
   if (scales.color?.type === 'sequential') {
     const colorScale = scales.color.scale as unknown as (v: number) => string;
     return colorScale(value);

package/src/compile.ts

@@ -386,8 +386,9 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
     }
   }
 
-  // Set default color for single-series charts (no color encoding)
-  scales.defaultColor = theme.colors.categorical[0];
+  // Set default color for single-series charts. If the user set a fill on the mark def
+  // (string or gradient), that takes priority over the theme's first categorical color.
+  scales.defaultColor = chartSpec.markDef.fill ?? theme.colors.categorical[0];
 
   // Arc charts (pie/donut) don't use axes or gridlines
   const isRadial = chartSpec.markType === 'arc';

package/src/layout/scales.ts

@@ -99,8 +99,8 @@ export interface ResolvedScales {
   y?: ResolvedScale;
   color?: ResolvedScale;
   size?: ResolvedScale;
-  /** Default color for single-series charts (first categorical palette color). */
-  defaultColor?: string;
+  /** Default color for single-series charts (first categorical palette color or markDef.fill gradient). */
+  defaultColor?: string | import('@opendata-ai/openchart-core').GradientDef;
 }
 
 // ---------------------------------------------------------------------------

package/src/tooltips/compute.ts

@@ -19,7 +19,12 @@ import type {
   TooltipContent,
   TooltipField,
 } from '@opendata-ai/openchart-core';
-import { buildTemporalFormatter, formatDate, formatNumber } from '@opendata-ai/openchart-core';
+import {
+  buildTemporalFormatter,
+  formatDate,
+  formatNumber,
+  getRepresentativeColor,
+} from '@opendata-ai/openchart-core';
 import { format as d3Format } from 'd3-format';
 
 import type { NormalizedChartSpec } from '../compiler/types';
@@ -155,7 +160,7 @@ function tooltipsForPoint(
   markIndex: number,
 ): Array<[string, TooltipContent]> {
   const title = getTooltipTitle(mark.data, encoding);
-  const fields = buildFields(mark.data, encoding, mark.fill);
+  const fields = buildFields(mark.data, encoding, getRepresentativeColor(mark.fill));
 
   return [[`point-${markIndex}`, { title, fields }]];
 }
@@ -166,7 +171,7 @@ function tooltipsForRect(
   markIndex: number,
 ): Array<[string, TooltipContent]> {
   const title = getTooltipTitle(mark.data, encoding);
-  const fields = buildFields(mark.data, encoding, mark.fill);
+  const fields = buildFields(mark.data, encoding, getRepresentativeColor(mark.fill));
 
   return [[`rect-${markIndex}`, { title, fields }]];
 }
@@ -187,14 +192,14 @@ function tooltipsForArc(
       fields.push({
         label: categoryName,
         value: formatValue(row[encoding.y.field], encoding.y.type, encoding.y.axis?.format),
-        color: mark.fill,
+        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),
-      color: mark.fill,
+      color: getRepresentativeColor(mark.fill),
     });
   }
 
@@ -214,7 +219,7 @@ function tooltipsForArea(
     for (const dp of mark.dataPoints) {
       dp.tooltip = {
         title: getTooltipTitle(dp.datum, encoding),
-        fields: buildFields(dp.datum, encoding, mark.fill),
+        fields: buildFields(dp.datum, encoding, getRepresentativeColor(mark.fill)),
       };
     }
   }