@opendata-ai/openchart-engine 6.27.2 → 6.28.2

package/src/compiler/normalize.ts

@@ -10,6 +10,7 @@
 
 import type {
   Annotation,
+  BarListSpec,
   ChartSpec,
   Chrome,
   ChromeText,
@@ -25,6 +26,7 @@ import type {
   VizSpec,
 } from '@opendata-ai/openchart-core';
 import {
+  isBarListSpec,
   isChartSpec,
   isGraphSpec,
   isLayerSpec,
@@ -34,6 +36,7 @@ import {
   resolveMarkDef,
   resolveMarkType,
 } from '@opendata-ai/openchart-core';
+import type { NormalizedBarListSpec } from '../barlist/types';
 import type { NormalizedSankeySpec } from '../sankey/types';
 import { STATE_CODE_SET } from '../tilemap/layout';
 import type { NormalizedTileMapSpec } from '../tilemap/types';
@@ -206,6 +209,7 @@ function normalizeLabels(labels?: LabelSpec): NormalizedChartSpec['labels'] {
     format: labels.format ?? '',
     prefix: labels.prefix ?? '',
     offsets: labels.offsets,
+    color: labels.color,
   };
 }
 
@@ -382,6 +386,23 @@ function normalizeTileMapSpec(spec: TileMapSpec, warnings: string[]): Normalized
   };
 }
 
+function normalizeBarListSpec(spec: BarListSpec, _warnings: string[]): NormalizedBarListSpec {
+  return {
+    type: 'barlist',
+    data: spec.data,
+    encoding: spec.encoding,
+    barHeight: spec.barHeight ?? 6,
+    cornerRadius: spec.cornerRadius ?? 'pill',
+    maxItems: spec.maxItems ?? 20,
+    chrome: normalizeChrome(spec.chrome),
+    theme: spec.theme ?? {},
+    darkMode: spec.darkMode ?? 'off',
+    watermark: spec.watermark ?? true,
+    animation: spec.animation ?? true,
+    valueFormat: spec.valueFormat,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -419,9 +440,12 @@ export function normalizeSpec(spec: VizSpec, warnings: string[] = []): Normalize
   if (isTileMapSpec(spec)) {
     return normalizeTileMapSpec(spec, warnings);
   }
+  if (isBarListSpec(spec)) {
+    return normalizeBarListSpec(spec, warnings);
+  }
   // Should never happen after validation
   throw new Error(
-    `Unknown spec shape. Expected mark (chart), layer, type: 'table', type: 'graph', type: 'sankey', or type: 'tilemap'.`,
+    `Unknown spec shape. Expected mark (chart), layer, type: 'table', type: 'graph', type: 'sankey', type: 'tilemap', or type: 'barlist'.`,
   );
 }
 

package/src/compiler/types.ts

@@ -29,6 +29,7 @@ import type {
   ScaleConfig,
   ThemeConfig,
 } from '@opendata-ai/openchart-core';
+import type { NormalizedBarListSpec } from '../barlist/types';
 import type { NormalizedSankeySpec } from '../sankey/types';
 import type { NormalizedTileMapSpec } from '../tilemap/types';
 
@@ -101,9 +102,9 @@ export interface NormalizedChartSpec {
   encoding: Encoding;
   chrome: NormalizedChrome;
   annotations: Annotation[];
-  /** Normalized label configuration with defaults applied. density, format, and prefix are always set; offsets stays optional. */
+  /** Normalized label configuration with defaults applied. density, format, and prefix are always set; offsets and color stay optional. */
   labels: Required<Pick<LabelConfig, 'density' | 'format' | 'prefix'>> &
-    Pick<LabelConfig, 'offsets'>;
+    Pick<LabelConfig, 'offsets' | 'color'>;
   /** Legend configuration (position override). */
   legend?: LegendConfig;
   responsive: boolean;
@@ -164,7 +165,8 @@ export type NormalizedSpec =
   | NormalizedTableSpec
   | NormalizedGraphSpec
   | NormalizedSankeySpec
-  | NormalizedTileMapSpec;
+  | NormalizedTileMapSpec
+  | NormalizedBarListSpec;
 
 // ---------------------------------------------------------------------------
 // Validation types

package/src/compiler/validate.ts

@@ -759,6 +759,117 @@ function validateTileMapSpec(spec: Record<string, unknown>, errors: ValidationEr
   }
 }
 
+// ---------------------------------------------------------------------------
+// BarList validation
+// ---------------------------------------------------------------------------
+
+function validateBarListSpec(spec: Record<string, unknown>, errors: ValidationError[]): void {
+  if (!Array.isArray(spec.data)) {
+    errors.push({
+      message: 'Spec error: barlist spec requires a "data" array',
+      path: 'data',
+      code: 'INVALID_TYPE',
+      suggestion:
+        'Provide data as an array of objects, e.g. data: [{ label: "Category A", value: 42 }]',
+    });
+    return;
+  }
+
+  if (spec.data.length === 0) {
+    errors.push({
+      message: 'Spec error: "data" array must be non-empty',
+      path: 'data',
+      code: 'EMPTY_DATA',
+      suggestion: 'Add at least one data row',
+    });
+    return;
+  }
+
+  const firstRow = spec.data[0] as unknown;
+  if (typeof firstRow !== 'object' || firstRow === null || Array.isArray(firstRow)) {
+    errors.push({
+      message: 'Spec error: each item in "data" must be a plain object',
+      path: 'data[0]',
+      code: 'INVALID_TYPE',
+      suggestion: 'Each data item should be an object, e.g. { label: "Category A", value: 42 }',
+    });
+    return;
+  }
+
+  if (!spec.encoding || typeof spec.encoding !== 'object') {
+    errors.push({
+      message:
+        'Spec error: barlist spec requires an "encoding" object with label and value channels',
+      path: 'encoding',
+      code: 'MISSING_FIELD',
+      suggestion:
+        'Add an encoding object, e.g. encoding: { label: { field: "name", type: "nominal" }, value: { field: "count", type: "quantitative" } }',
+    });
+    return;
+  }
+
+  const encoding = spec.encoding as Record<string, unknown>;
+  const dataColumns = new Set(Object.keys(firstRow as Record<string, unknown>));
+  const availableColumns = [...dataColumns].join(', ');
+
+  for (const channel of ['label', 'value'] as const) {
+    const ch = encoding[channel] as Record<string, unknown> | undefined;
+    if (!ch || typeof ch !== 'object') {
+      errors.push({
+        message: `Spec error: barlist encoding requires "${channel}" channel`,
+        path: `encoding.${channel}`,
+        code: 'MISSING_FIELD',
+        suggestion: `Add encoding.${channel} with a field from your data (${availableColumns}). Example: ${channel}: { field: "${[...dataColumns][0] ?? 'myField'}", type: "${channel === 'value' ? 'quantitative' : 'nominal'}" }`,
+      });
+      continue;
+    }
+
+    if (!ch.field || typeof ch.field !== 'string') {
+      errors.push({
+        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}`,
+      });
+      continue;
+    }
+
+    if (!dataColumns.has(ch.field as string)) {
+      errors.push({
+        message: `Spec error: encoding.${channel}.field "${ch.field}" does not exist in data. Available columns: ${availableColumns}`,
+        path: `encoding.${channel}.field`,
+        code: 'DATA_FIELD_MISSING',
+        suggestion: `Use one of the available data columns: ${availableColumns}`,
+      });
+    }
+  }
+
+  // Validate optional encoding channels
+  for (const channel of ['subtitle', 'color', 'tooltip'] as const) {
+    const ch = encoding[channel] as Record<string, unknown> | undefined;
+    if (!ch) continue;
+    const field = ch.field;
+    if (field && typeof field === 'string' && !dataColumns.has(field)) {
+      errors.push({
+        message: `Spec error: encoding.${channel}.field "${field}" does not exist in data. Available columns: ${availableColumns}`,
+        path: `encoding.${channel}.field`,
+        code: 'DATA_FIELD_MISSING',
+        suggestion: `Use one of the available data columns: ${availableColumns}`,
+      });
+    }
+  }
+
+  if (spec.darkMode !== undefined && !VALID_DARK_MODES.has(spec.darkMode as string)) {
+    errors.push({
+      message: 'Spec error: darkMode must be "auto", "force", or "off"',
+      path: 'darkMode',
+      code: 'INVALID_VALUE',
+      suggestion:
+        'Use one of: "auto" (system preference), "force" (always dark), or "off" (always light)',
+    });
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Layer validation
 // ---------------------------------------------------------------------------
@@ -897,19 +1008,21 @@ export function validateSpec(spec: unknown): ValidationResult {
   const isGraph = obj.type === 'graph';
   const isSankey = obj.type === 'sankey';
   const isTileMap = obj.type === 'tilemap';
-  const isLayer = hasLayer && !isTable && !isGraph && !isSankey && !isTileMap;
-  const isChart = hasMark && !hasLayer && !isTable && !isGraph && !isSankey && !isTileMap;
+  const isBarList = obj.type === 'barlist';
+  const isLayer = hasLayer && !isTable && !isGraph && !isSankey && !isTileMap && !isBarList;
+  const isChart =
+    hasMark && !hasLayer && !isTable && !isGraph && !isSankey && !isTileMap && !isBarList;
 
-  if (!isChart && !isTable && !isGraph && !isSankey && !isTileMap && !isLayer) {
+  if (!isChart && !isTable && !isGraph && !isSankey && !isTileMap && !isBarList && !isLayer) {
     return {
       valid: false,
       errors: [
         {
           message:
-            'Spec error: spec must have a "mark" field for charts, a "layer" array for layered charts, or a "type" field for tables/graphs/sankey/tilemap',
+            'Spec error: spec must have a "mark" field for charts, a "layer" array for layered charts, or a "type" field for tables/graphs/sankey/tilemap/barlist',
           path: 'mark',
           code: 'MISSING_FIELD',
-          suggestion: `Add a "mark" field for charts (e.g. mark: "bar"), a "layer" array for layered charts, or a "type" field for tables/graphs/sankey/tilemap (type: "table", type: "graph", type: "sankey", or type: "tilemap"). Valid mark types: ${[...MARK_TYPES].join(', ')}`,
+          suggestion: `Add a "mark" field for charts (e.g. mark: "bar"), a "layer" array for layered charts, or a "type" field (type: "table", type: "graph", type: "sankey", type: "tilemap", or type: "barlist"). Valid mark types: ${[...MARK_TYPES].join(', ')}`,
         },
       ],
       normalized: null,
@@ -956,6 +1069,8 @@ export function validateSpec(spec: unknown): ValidationResult {
     validateSankeySpec(obj, errors);
   } else if (isTileMap) {
     validateTileMapSpec(obj, errors);
+  } else if (isBarList) {
+    validateBarListSpec(obj, errors);
   }
 
   if (errors.length > 0) {

package/src/index.ts

@@ -13,6 +13,7 @@
 // ---------------------------------------------------------------------------
 
 export {
+  compileBarList,
   compileChart,
   compileGraph,
   compileLayer,
@@ -48,6 +49,8 @@ export type { NormalizedSankeySpec } from './sankey/types';
 // TileMap compilation types
 // ---------------------------------------------------------------------------
 
+export type { NormalizedBarListSpec } from './barlist/types';
+
 export type { NormalizedTileMapSpec } from './tilemap/types';
 
 // ---------------------------------------------------------------------------
@@ -102,6 +105,8 @@ export {
 // ---------------------------------------------------------------------------
 
 export type {
+  BarListLayout,
+  BarListSpec,
   ChartLayout,
   ChartSpec,
   CompileOptions,

package/src/layout/axes/ticks.ts

@@ -130,7 +130,8 @@ const TEMPORAL_SCALE_TYPES = new Set(['time', 'utc']);
 
 /** Format a tick value based on the scale type. */
 function formatTickLabel(value: unknown, resolvedScale: ResolvedScale): string {
-  const formatStr = resolvedScale.channel.axis?.format;
+  const axisConfig = resolvedScale.channel.axis || undefined;
+  const formatStr = axisConfig?.format;
 
   if (TEMPORAL_SCALE_TYPES.has(resolvedScale.type)) {
     const temporalFmt = buildTemporalFormatter(formatStr);
@@ -179,8 +180,8 @@ export function continuousTicks(
     }));
   }
 
-  const explicitCount = resolvedScale.channel.axis?.tickCount;
-  const count = explicitCount ?? targetCount ?? TICK_COUNTS[density];
+  const axCfg = resolvedScale.channel.axis || undefined;
+  const count = axCfg?.tickCount ?? targetCount ?? TICK_COUNTS[density];
   return buildContinuousTicks(resolvedScale, count);
 }
 
@@ -257,7 +258,8 @@ export function categoricalTicks(
 ): AxisTick[] {
   const scale = resolvedScale.scale as D3CategoricalScale;
   const domain: string[] = scale.domain();
-  const explicitTickCount = resolvedScale.channel.axis?.tickCount;
+  const catAxisCfg = resolvedScale.channel.axis || undefined;
+  const explicitTickCount = catAxisCfg?.tickCount;
 
   let selectedValues = domain;
 

package/src/layout/axes.ts

@@ -271,7 +271,7 @@ export function computeAxes(
   const { fontSize } = tickLabelStyle;
   const { fontWeight } = tickLabelStyle;
 
-  if (scales.x && !dataContext?.skipX) {
+  if (scales.x && !dataContext?.skipX && scales.x.channel.axis !== false) {
     const axisConfig = scales.x.channel.axis;
     const isContinuousX =
       scales.x.type !== 'band' && scales.x.type !== 'point' && scales.x.type !== 'ordinal';
@@ -373,7 +373,7 @@ export function computeAxes(
     };
   }
 
-  if (scales.y && !dataContext?.skipY) {
+  if (scales.y && !dataContext?.skipY && scales.y.channel.axis !== false) {
     const axisConfig = scales.y.channel.axis;
     const isContinuousY =
       scales.y.type !== 'band' && scales.y.type !== 'point' && scales.y.type !== 'ordinal';

package/src/layout/dimensions.ts

@@ -114,7 +114,9 @@ function getMinChartDims(display: import('@opendata-ai/openchart-core').Display)
  */
 function getSparklinePad(spec: NormalizedChartSpec): number {
   const strokeWidth = (spec.markDef as { strokeWidth?: number }).strokeWidth ?? 2;
-  return Math.max(strokeWidth / 2 + 1, 2);
+  const hasPoints = !!(spec.markDef as { point?: unknown }).point;
+  const pointRadius = hasPoints ? 3 : 0;
+  return Math.max(strokeWidth / 2 + 1, pointRadius + 1, 2);
 }
 
 // ---------------------------------------------------------------------------
@@ -222,12 +224,15 @@ export function computeDimensions(
   // Estimate x-axis height below chart area: tick labels sit 14px below,
   // axis title sits 35px below. These extend past the chart area bottom
   // and source/footer chrome must be positioned below them.
-  const xAxis = encoding.x?.axis as (Record<string, unknown> & { labelAngle?: number }) | undefined;
+  const xAxisSuppressed = encoding.x?.axis === false;
+  const xAxis = (!xAxisSuppressed && encoding.x?.axis) as
+    | (Record<string, unknown> & { labelAngle?: number })
+    | undefined;
   const hasXAxisLabel = !!xAxis?.title;
   const xTickAngle = xAxis?.labelAngle;
 
   let xAxisHeight: number;
-  if (isRadial) {
+  if (isRadial || xAxisSuppressed) {
     xAxisHeight = 0;
   } else if (xTickAngle && Math.abs(xTickAngle) > 10) {
     // Rotated labels: estimate height from the longest label text.
@@ -339,7 +344,8 @@ export function computeDimensions(
   }
 
   // Dynamic left margin for y-axis labels
-  if (encoding.y && !isRadial) {
+  const yAxisSuppressed = encoding.y?.axis === false;
+  if (encoding.y && !isRadial && !yAxisSuppressed) {
     if (
       spec.markType === 'bar' ||
       spec.markType === 'circle' ||

package/src/layout/scales.ts

@@ -256,6 +256,16 @@ function buildLinearScale(
 
   if (!channel.scale?.domain && channel.scale?.nice !== false) {
     scale.nice();
+
+    // nice() can round the domain min down to 0 even when zero: false.
+    // Re-nice with more ticks to tighten the domain around the data range.
+    if (channel.scale?.zero === false) {
+      const [nicedMin, nicedMax] = scale.domain();
+      if (nicedMin < domainMin || nicedMax > domainMax) {
+        scale.domain([domainMin, domainMax]);
+        scale.nice(20);
+      }
+    }
   }
   applyContinuousConfig(scale, channel);
 

package/src/legend/wrap.ts

@@ -32,7 +32,7 @@ export const ENTRY_GAP = 16;
 export const ENTRY_GAP_COMPACT = 10;
 
 /** Default gap between legend bounds and chart area. Zero on narrow viewports. */
-export const LEGEND_GAP = 4;
+export const LEGEND_GAP = 8;
 
 /** Gap between legend and chart area, responsive to container width. */
 export function legendGap(width: number): number {

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

@@ -112,7 +112,7 @@ describe('compileTileMap', () => {
     }
   });
 
-  it('data tiles have fill colors from the sequential palette', () => {
+  it('data tiles use opacity-based encoding with a single base color', () => {
     const result = compileTileMap(basicSpec, defaultOptions);
 
     const dataTiles = result.tiles.filter((t) => t.hasData);
@@ -122,7 +122,10 @@ describe('compileTileMap', () => {
     }
 
     const fills = new Set(dataTiles.map((t) => t.fill));
-    expect(fills.size).toBeGreaterThan(1);
+    expect(fills.size).toBe(1);
+
+    const opacities = new Set(dataTiles.map((t) => t.fillOpacity));
+    expect(opacities.size).toBeGreaterThan(1);
   });
 
   it('compiles tabular DataRow[] data with encoding', () => {

package/src/tilemap/compile-tilemap.ts

@@ -44,8 +44,8 @@ import type { NormalizedTileMapSpec } from './types';
 // Constants
 // ---------------------------------------------------------------------------
 
-const TILE_CORNER_RADIUS = 2;
-const TILE_STROKE_WIDTH = 0;
+const TILE_CORNER_RADIUS = 6;
+const TILE_STROKE_WIDTH = 1;
 
 // ---------------------------------------------------------------------------
 // Public API
@@ -143,23 +143,22 @@ export function compileTileMap(spec: unknown, options: CompileOptions): TileMapL
   const min = values.length > 0 ? Math.min(...values) : 0;
   const max = values.length > 0 ? Math.max(...values) : 100;
 
-  // 8. Build color scale (fallback to 'blue' if palette name is invalid)
+  // 8. Build opacity scale: single base color, opacity encodes value
   const paletteStops = [...(SEQUENTIAL_PALETTES[tilemapSpec.palette] ?? SEQUENTIAL_PALETTES.blue)];
-  if (isDarkMode) paletteStops.reverse();
-
-  const domain = paletteStops.map((_, i) => min + (i / (paletteStops.length - 1)) * (max - min));
-  const colorScale = scaleLinear<string>().domain(domain).range(paletteStops).clamp(true);
+  const baseColor = isDarkMode ? paletteStops[0] : paletteStops[paletteStops.length - 1];
+  const opacityRange: [number, number] = isDarkMode ? [0.15, 1] : [0.2, 1];
+  const opacityScale = scaleLinear<number>().domain([min, max]).range(opacityRange).clamp(true);
 
   // 9. Reserve space for gradient legend at bottom (unless hidden)
   const showLegend = tilemapSpec.legend?.show !== false;
-  const legendBarHeight = 12;
-  const legendLabelGap = 4;
+  const legendBarHeight = 6;
+  const legendLabelGap = 6;
   const legendTotalHeight = showLegend ? legendBarHeight + legendLabelGap + 14 : 0;
 
   // 10. Compute tile positions in the remaining area
   const legendGap = showLegend ? 8 : 0;
   const tileAreaHeight = fullArea.height - legendTotalHeight - legendGap;
-  const tilePositions = computeTilePositions(fullArea.width, tileAreaHeight, 4);
+  const tilePositions = computeTilePositions(fullArea.width, tileAreaHeight, 5);
 
   // Center tile grid horizontally
   const tileGridOffsetX = fullArea.x + (fullArea.width - tilePositions.gridWidth) / 2;
@@ -173,9 +172,9 @@ export function compileTileMap(spec: unknown, options: CompileOptions): TileMapL
   // 11. Build TileMapTileMark[]
   const formatter = buildD3Formatter(tilemapSpec.valueFormat) ?? formatNumber;
   const neutralFillLight = '#e0e0e0';
-  const neutralFillDark = '#2a2a3e';
+  const neutralFillDark = '#1e2a30';
   const neutralStrokeLight = '#d0d0d0';
-  const neutralStrokeDark = '#3a3a50';
+  const neutralStrokeDark = 'rgba(255,255,255,0.08)';
 
   const neutralFill = isDarkMode ? neutralFillDark : neutralFillLight;
   const neutralStroke = isDarkMode ? neutralStrokeDark : neutralStrokeLight;
@@ -188,12 +187,18 @@ export function compileTileMap(spec: unknown, options: CompileOptions): TileMapL
 
     const hasData = stateValueMap.has(stateCode);
     const value = hasData ? stateValueMap.get(stateCode)! : null;
-    const fill = hasData ? colorScale(value!) : neutralFill;
+    const opacity = hasData ? opacityScale(value!) : 0;
+    const fill = hasData ? baseColor : neutralFill;
+    const stroke = hasData
+      ? isDarkMode
+        ? 'rgba(255,255,255,0.1)'
+        : 'rgba(0,0,0,0.1)'
+      : neutralStroke;
     const formattedValue = hasData ? formatter(value!) : '–';
 
     const labelStyle: TextStyle = {
       fontFamily: theme.fonts.family,
-      fontSize: tilePositions.tileSize > 24 ? 14 : 11,
+      fontSize: tilePositions.tileSize > 24 ? 10 : 7,
       fontWeight: 700,
       fill: '#ffffff',
       lineHeight: 1.2,
@@ -201,20 +206,24 @@ export function compileTileMap(spec: unknown, options: CompileOptions): TileMapL
 
     const valueLabelStyle: TextStyle = {
       fontFamily: theme.fonts.family,
-      fontSize: tilePositions.tileSize > 24 ? 12 : 10,
-      fontWeight: 400,
-      fill: '#ffffff',
+      fontSize: tilePositions.tileSize > 24 ? 10 : 7,
+      fontWeight: 300,
+      fill: 'rgba(255,255,255,0.6)',
       lineHeight: 1.2,
     };
 
+    const tileCenterX = tileGridOffsetX + pos.x + tilePositions.tileSize / 2;
+    const tileTopY = tileGridOffsetY + pos.y;
+    const sz = tilePositions.tileSize;
+
     // Only show value label on larger tiles
     const valueLabel =
-      tilePositions.tileSize < 24
+      sz < 24
         ? { text: '', x: 0, y: 0, style: valueLabelStyle, visible: false }
         : {
             text: formattedValue,
-            x: tileGridOffsetX + pos.x + tilePositions.tileSize / 2,
-            y: tileGridOffsetY + pos.y + tilePositions.tileSize / 2 + 8,
+            x: tileCenterX,
+            y: tileTopY + sz * 0.78,
             style: valueLabelStyle,
             visible: true,
           };
@@ -223,10 +232,11 @@ export function compileTileMap(spec: unknown, options: CompileOptions): TileMapL
       type: 'tile' as const,
       stateCode,
       x: tileGridOffsetX + pos.x,
-      y: tileGridOffsetY + pos.y,
-      size: tilePositions.tileSize,
+      y: tileTopY,
+      size: sz,
       fill,
-      stroke: neutralStroke,
+      fillOpacity: hasData ? opacity : 1,
+      stroke,
       strokeWidth: TILE_STROKE_WIDTH,
       cornerRadius: TILE_CORNER_RADIUS,
       value: value ?? null,
@@ -234,8 +244,8 @@ export function compileTileMap(spec: unknown, options: CompileOptions): TileMapL
       hasData,
       label: {
         text: stateCode,
-        x: tileGridOffsetX + pos.x + tilePositions.tileSize / 2,
-        y: tileGridOffsetY + pos.y + tilePositions.tileSize / 2 - 4,
+        x: tileCenterX,
+        y: tileTopY + sz * 0.28,
         style: labelStyle,
         visible: true,
       },
@@ -269,10 +279,12 @@ export function compileTileMap(spec: unknown, options: CompileOptions): TileMapL
   let gradientLegend: GradientLegendLayout | null = null;
 
   if (showLegend) {
-    const gradientColorStops: GradientColorStop[] = paletteStops.map((color, i) => ({
-      offset: i / (paletteStops.length - 1),
-      color,
-    }));
+    const numStops = 5;
+    const gradientColorStops: GradientColorStop[] = Array.from({ length: numStops }, (_, i) => {
+      const t = i / (numStops - 1);
+      const o = opacityRange[0] + t * (opacityRange[1] - opacityRange[0]);
+      return { offset: t, color: baseColor, opacity: o };
+    });
 
     gradientLegend = {
       type: 'gradient',

package/src/tooltips/compute.ts

@@ -59,12 +59,14 @@ function formatValue(value: unknown, fieldType?: string, format?: string): strin
 
 /** 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;
+  const ax = ch.axis || undefined;
+  return ch.title ?? ax?.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;
+  const ax = ch.axis || undefined;
+  return ch.format ?? ax?.format;
 }
 
 /** Build tooltip fields from explicit tooltip encoding channels. */