@opendata-ai/openchart-engine 6.27.2 → 6.28.4

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/tables/__tests__/heatmap.test.ts

@@ -112,6 +112,28 @@ describe('computeHeatmapColors', () => {
     }
   });
 
+  it('preserves luminance ordering in dark mode with custom color stops', () => {
+    const col: ColumnConfig = {
+      key: 'value',
+      heatmap: { palette: ['#fca5a5', '#c44e52'], domain: [0, 100] },
+    };
+    const lightTheme = getTheme(false);
+    const darkTheme = getTheme(true);
+    const lightColors = computeHeatmapColors(data, col, lightTheme, false);
+    const darkColors = computeHeatmapColors(data, col, darkTheme, true);
+
+    // Low value should have a visually lighter/less intense background than high value
+    // in both modes. Extract the backgrounds and compare luminance ordering.
+    const lightLowBg = lightColors.get(0)!.backgroundColor!;
+    const lightHighBg = lightColors.get(4)!.backgroundColor!;
+    const darkLowBg = darkColors.get(0)!.backgroundColor!;
+    const darkHighBg = darkColors.get(4)!.backgroundColor!;
+
+    // The low-value cell and high-value cell should have different backgrounds in both modes
+    expect(lightLowBg).not.toBe(lightHighBg);
+    expect(darkLowBg).not.toBe(darkHighBg);
+  });
+
   it('supports array of color stops as palette', () => {
     const col: ColumnConfig = {
       key: 'value',

package/src/tables/heatmap.ts

@@ -11,6 +11,17 @@ import { interpolateRgb } from 'd3-interpolate';
 import { scaleSequential } from 'd3-scale';
 import { accessibleTextColor } from './utils';
 
+/** WCAG relative luminance from a hex color string. */
+function relativeLuminance(hex: string): number {
+  const m = /^#?([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i.exec(hex);
+  if (!m) return 0;
+  const [r, g, b] = [m[1], m[2], m[3]].map((c) => {
+    const v = Number.parseInt(c, 16) / 255;
+    return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
+  });
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
 /**
  * Build an interpolator from an array of color stops.
  * Uses d3-interpolate for smooth color transitions.
@@ -100,7 +111,24 @@ export function computeHeatmapColors(
   if (darkMode) {
     const lightBg = '#ffffff';
     const darkBg = theme.colors.background;
+    const originalStops = stops;
     stops = stops.map((c) => adaptColorForDarkMode(c, lightBg, darkBg));
+
+    // adaptColorForDarkMode preserves contrast ratios independently per stop,
+    // which can invert the luminance ordering (light-to-dark becomes dark-to-light).
+    // Detect this and reverse the adapted stops to preserve the intended gradient direction.
+    if (originalStops.length >= 2) {
+      const origDirection = Math.sign(
+        relativeLuminance(originalStops[originalStops.length - 1]) -
+          relativeLuminance(originalStops[0]),
+      );
+      const adaptedDirection = Math.sign(
+        relativeLuminance(stops[stops.length - 1]) - relativeLuminance(stops[0]),
+      );
+      if (origDirection !== 0 && adaptedDirection !== 0 && origDirection !== adaptedDirection) {
+        stops = stops.slice().reverse();
+      }
+    }
   }
 
   const interpolator = interpolatorFromStops(stops);

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', () => {
@@ -294,18 +297,20 @@ describe('compileTileMap', () => {
   });
 
   describe('dimensions', () => {
-    it('reflects the compile options', () => {
+    it('width matches compile options, height fits content', () => {
       const result = compileTileMap(basicSpec, defaultOptions);
 
       expect(result.width).toBe(600);
-      expect(result.height).toBe(400);
+      expect(result.height).toBeGreaterThan(0);
+      expect(result.height).toBeLessThanOrEqual(400);
     });
 
     it('works with different container sizes', () => {
       const result = compileTileMap(basicSpec, { width: 800, height: 600 });
 
       expect(result.width).toBe(800);
-      expect(result.height).toBe(600);
+      expect(result.height).toBeGreaterThan(0);
+      expect(result.height).toBeLessThanOrEqual(600);
     });
   });