@opendata-ai/openchart-engine 6.27.0 → 6.28.2

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

@@ -0,0 +1,200 @@
+import type { BarListSpec, CompileOptions } from '@opendata-ai/openchart-core';
+import { describe, expect, it } from 'vitest';
+
+import { compileBarList } from '../compile-barlist';
+
+const BASE_OPTIONS: CompileOptions = {
+  width: 600,
+  height: 400,
+};
+
+function makeSpec(overrides?: Partial<BarListSpec>): BarListSpec {
+  return {
+    type: 'barlist',
+    data: [
+      { label: 'Alpha', count: 100 },
+      { label: 'Beta', count: 75 },
+      { label: 'Gamma', count: 50 },
+      { label: 'Delta', count: 25 },
+    ],
+    encoding: {
+      label: { field: 'label', type: 'nominal' },
+      value: { field: 'count', type: 'quantitative' },
+    },
+    ...overrides,
+  };
+}
+
+describe('compileBarList', () => {
+  it('compiles a basic barlist spec with correct row count', () => {
+    const layout = compileBarList(makeSpec(), BASE_OPTIONS);
+    expect(layout.rows).toHaveLength(4);
+  });
+
+  it('sorts rows by value descending', () => {
+    const spec = makeSpec({
+      data: [
+        { label: 'Low', count: 10 },
+        { label: 'High', count: 100 },
+        { label: 'Mid', count: 50 },
+      ],
+    });
+    const layout = compileBarList(spec, BASE_OPTIONS);
+    expect(layout.rows[0].label.text).toBe('High');
+    expect(layout.rows[1].label.text).toBe('Mid');
+    expect(layout.rows[2].label.text).toBe('Low');
+  });
+
+  it('limits rows to maxItems', () => {
+    const spec = makeSpec({ maxItems: 2 });
+    const layout = compileBarList(spec, BASE_OPTIONS);
+    expect(layout.rows).toHaveLength(2);
+    expect(layout.rows[0].label.text).toBe('Alpha');
+    expect(layout.rows[1].label.text).toBe('Beta');
+  });
+
+  it('filters out null values', () => {
+    const spec = makeSpec({
+      data: [
+        { label: 'Valid', count: 50 },
+        { label: 'Null', count: null },
+        { label: 'Also valid', count: 25 },
+      ],
+    });
+    const layout = compileBarList(spec, BASE_OPTIONS);
+    expect(layout.rows).toHaveLength(2);
+  });
+
+  it('assigns cycling colors to rows', () => {
+    const layout = compileBarList(makeSpec(), BASE_OPTIONS);
+    const colors = layout.rows.map((r) => r.bar.fill);
+    expect(colors[0]).not.toBe(colors[1]);
+    expect(colors[1]).not.toBe(colors[2]);
+  });
+
+  it('bar width is proportional to value', () => {
+    const layout = compileBarList(makeSpec(), BASE_OPTIONS);
+    const maxWidth = layout.rows[0].bar.width;
+    const halfWidth = layout.rows[2].bar.width;
+    expect(halfWidth).toBeCloseTo(maxWidth * 0.5, 0);
+  });
+
+  it('first row gets full-width bar', () => {
+    const layout = compileBarList(makeSpec(), BASE_OPTIONS);
+    const row0 = layout.rows[0];
+    expect(row0.bar.width).toBe(row0.track.width);
+  });
+
+  it('pill cornerRadius is half the bar height', () => {
+    const spec = makeSpec({ barHeight: 8, cornerRadius: 'pill' });
+    const layout = compileBarList(spec, BASE_OPTIONS);
+    expect(layout.rows[0].bar.cornerRadius).toBe(4);
+    expect(layout.rows[0].track.cornerRadius).toBe(4);
+  });
+
+  it('numeric cornerRadius is used directly', () => {
+    const spec = makeSpec({ cornerRadius: 3 });
+    const layout = compileBarList(spec, BASE_OPTIONS);
+    expect(layout.rows[0].bar.cornerRadius).toBe(3);
+  });
+
+  it('default barHeight is 6', () => {
+    const layout = compileBarList(makeSpec(), BASE_OPTIONS);
+    expect(layout.rows[0].bar.height).toBe(6);
+  });
+
+  it('custom barHeight applies', () => {
+    const spec = makeSpec({ barHeight: 10 });
+    const layout = compileBarList(spec, BASE_OPTIONS);
+    expect(layout.rows[0].bar.height).toBe(10);
+  });
+
+  it('builds tooltip descriptors keyed by row index', () => {
+    const layout = compileBarList(makeSpec(), BASE_OPTIONS);
+    expect(layout.tooltipDescriptors.size).toBe(4);
+    const tooltip = layout.tooltipDescriptors.get('0');
+    expect(tooltip?.title).toBe('Alpha');
+    expect(tooltip?.fields[0].value).toBeDefined();
+  });
+
+  it('builds a11y metadata', () => {
+    const layout = compileBarList(makeSpec(), BASE_OPTIONS);
+    expect(layout.a11y.altText).toContain('4 items');
+    expect(layout.a11y.dataTableFallback).toHaveLength(4);
+    expect(layout.a11y.role).toBe('list');
+  });
+
+  it('returns animation indices matching row order', () => {
+    const layout = compileBarList(makeSpec(), BASE_OPTIONS);
+    expect(layout.rows[0].animationIndex).toBe(0);
+    expect(layout.rows[1].animationIndex).toBe(1);
+    expect(layout.rows[2].animationIndex).toBe(2);
+  });
+
+  it('throws when data is empty', () => {
+    const spec = makeSpec({ data: [] });
+    expect(() => compileBarList(spec, BASE_OPTIONS)).toThrow(/empty/i);
+  });
+
+  it('formats values with valueFormat', () => {
+    const spec = makeSpec({ valueFormat: '$,.0f' });
+    const layout = compileBarList(spec, BASE_OPTIONS);
+    expect(layout.rows[0].formattedValue).toBe('$100');
+  });
+
+  it('formats values with SI suffix format', () => {
+    const spec = makeSpec({
+      data: [
+        { label: 'Big', count: 1500 },
+        { label: 'Small', count: 200 },
+      ],
+      valueFormat: '~s',
+    });
+    const layout = compileBarList(spec, BASE_OPTIONS);
+    expect(layout.rows[0].formattedValue).toBe('1.5k');
+  });
+
+  it('dark mode changes label colors', () => {
+    const lightLayout = compileBarList(makeSpec(), { ...BASE_OPTIONS, darkMode: false });
+    const darkLayout = compileBarList(makeSpec(), { ...BASE_OPTIONS, darkMode: true });
+    expect(lightLayout.rows[0].valueLabel.style.fill).not.toBe(
+      darkLayout.rows[0].valueLabel.style.fill,
+    );
+  });
+
+  it('rejects non-barlist specs', () => {
+    const invalidSpec = {
+      type: 'tilemap',
+      data: { CA: 100 },
+    };
+    expect(() => compileBarList(invalidSpec, BASE_OPTIONS)).toThrow('non-barlist');
+  });
+
+  it('uses color encoding for consistent category colors', () => {
+    const spec = makeSpec({
+      data: [
+        { label: 'A', count: 100, cat: 'x' },
+        { label: 'B', count: 50, cat: 'x' },
+        { label: 'C', count: 25, cat: 'y' },
+      ],
+      encoding: {
+        label: { field: 'label', type: 'nominal' },
+        value: { field: 'count', type: 'quantitative' },
+        color: { field: 'cat', type: 'nominal' },
+      },
+    });
+    const layout = compileBarList(spec, BASE_OPTIONS);
+    expect(layout.rows[0].bar.fill).toBe(layout.rows[1].bar.fill);
+    expect(layout.rows[0].bar.fill).not.toBe(layout.rows[2].bar.fill);
+  });
+
+  it('preserves original data in row marks', () => {
+    const layout = compileBarList(makeSpec(), BASE_OPTIONS);
+    expect(layout.rows[0].data).toEqual({ label: 'Alpha', count: 100 });
+  });
+
+  it('rows have correct aria labels', () => {
+    const layout = compileBarList(makeSpec(), BASE_OPTIONS);
+    expect(layout.rows[0].aria.label).toContain('Alpha');
+  });
+});

package/src/barlist/compile-barlist.ts

@@ -0,0 +1,380 @@
+/**
+ * BarList compilation pipeline.
+ *
+ * Takes a raw barlist spec, validates, normalizes, resolves theme, computes
+ * chrome, lays out rows with proportional bars, builds tooltips and a11y,
+ * and returns a BarListLayout.
+ *
+ * Pipeline:
+ *   validate -> normalize -> resolve theme -> dark mode adapt ->
+ *   compute chrome -> extract data -> sort/limit rows ->
+ *   compute row layout -> build row marks -> tooltips -> a11y ->
+ *   animation -> return BarListLayout
+ */
+
+import type {
+  BarListLayout,
+  BarListRowMark,
+  CompileOptions,
+  ResolvedAnimation,
+  ResolvedTheme,
+  TextStyle,
+  TooltipContent,
+  TooltipField,
+} from '@opendata-ai/openchart-core';
+import {
+  adaptTheme,
+  buildD3Formatter,
+  computeChrome,
+  estimateTextWidth,
+  formatNumber,
+  resolveTheme,
+} from '@opendata-ai/openchart-core';
+
+import { resolveAnimation } from '../compiler/animation';
+import { compile as compileSpec } from '../compiler/index';
+import type { NormalizedBarListSpec } from './types';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const DEFAULT_ROW_GAP = 8;
+const LABEL_BAR_GAP = 12;
+const BAR_VALUE_GAP = 12;
+const VALUE_WIDTH = 56;
+const LABEL_FONT_SIZE = 13;
+const LABEL_FONT_WEIGHT = 500;
+const SUBTITLE_FONT_SIZE = 12;
+const SUBTITLE_FONT_WEIGHT = 400;
+const VALUE_FONT_SIZE = 12;
+const VALUE_FONT_WEIGHT = 400;
+
+const BARLIST_COLORS = ['#06b6d4', '#34d399', '#fbbf24', '#f472b6', '#a78bfa'];
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export function compileBarList(spec: unknown, options: CompileOptions): BarListLayout {
+  const { spec: normalized } = compileSpec(spec);
+
+  if (!('type' in normalized) || normalized.type !== 'barlist') {
+    throw new Error(
+      'compileBarList received a non-barlist spec. Use compileChart, compileTable, compileGraph, compileSankey, or compileTileMap instead.',
+    );
+  }
+
+  const barlistSpec = normalized as NormalizedBarListSpec;
+
+  const rawWatermark = (spec as Record<string, unknown>).watermark;
+  const watermark =
+    rawWatermark !== undefined ? barlistSpec.watermark : (options.watermark ?? true);
+
+  // Resolve theme
+  const mergedThemeConfig = options.theme
+    ? { ...barlistSpec.theme, ...options.theme }
+    : barlistSpec.theme;
+  const lightTheme: ResolvedTheme = resolveTheme(mergedThemeConfig);
+  let theme: ResolvedTheme = lightTheme;
+  if (options.darkMode) {
+    theme = adaptTheme(theme);
+  }
+
+  // Compute chrome
+  const chrome = computeChrome(
+    {
+      title: barlistSpec.chrome.title,
+      subtitle: barlistSpec.chrome.subtitle,
+      source: barlistSpec.chrome.source,
+      byline: barlistSpec.chrome.byline,
+      footer: barlistSpec.chrome.footer,
+    },
+    theme,
+    options.width,
+    options.measureText,
+    'full',
+    undefined,
+    watermark,
+  );
+
+  // Compute drawing area
+  const padding = theme.spacing.padding;
+  const fullArea = {
+    x: padding,
+    y: padding + chrome.topHeight,
+    width: options.width - padding * 2,
+    height: options.height - chrome.topHeight - chrome.bottomHeight - padding * 2,
+  };
+
+  if (fullArea.width <= 0 || fullArea.height <= 0) {
+    return emptyLayout(chrome, theme, options, watermark);
+  }
+
+  // Extract data
+  const labelField = barlistSpec.encoding.label.field;
+  const valueField = barlistSpec.encoding.value.field;
+  const subtitleField = barlistSpec.encoding.subtitle?.field;
+  const colorField = barlistSpec.encoding.color?.field;
+
+  // Compute row dimensions up front so we can auto-cap maxItems to fit available height
+  const barHeight = barlistSpec.barHeight;
+  const cornerRadius =
+    barlistSpec.cornerRadius === 'pill' ? barHeight / 2 : barlistSpec.cornerRadius;
+  const rowContentHeight = Math.max(barHeight, LABEL_FONT_SIZE * 1.4);
+  const rowHeight = rowContentHeight + DEFAULT_ROW_GAP;
+  const maxFittingRows = Math.max(1, Math.floor(fullArea.height / rowHeight));
+
+  // Filter valid rows, sort descending, cap to the lesser of maxItems and available height
+  const validRows = barlistSpec.data
+    .filter((row) => {
+      const val = row[valueField];
+      return val !== null && val !== undefined && !Number.isNaN(Number(val));
+    })
+    .sort((a, b) => Number(b[valueField]) - Number(a[valueField]))
+    .slice(0, Math.min(barlistSpec.maxItems, maxFittingRows));
+
+  if (validRows.length === 0) {
+    return emptyLayout(chrome, theme, options, watermark);
+  }
+
+  // Use absolute max so negative-only datasets produce valid proportions (e.g. [-100,-50] -> maxAbs=100)
+  const maxValue = Math.max(...validRows.map((r) => Math.abs(Number(r[valueField]))));
+
+  // Color assignment: cycle through barlist-specific palette
+  const colorMap = new Map<string, string>();
+  let colorIndex = 0;
+  const palette = BARLIST_COLORS;
+
+  function getColor(row: Record<string, unknown>, idx: number): string {
+    if (colorField) {
+      const key = String(row[colorField] ?? '');
+      if (!colorMap.has(key)) {
+        colorMap.set(key, palette[colorIndex % palette.length]);
+        colorIndex++;
+      }
+      return colorMap.get(key)!;
+    }
+    return palette[idx % palette.length];
+  }
+
+  // Value formatter
+  const formatter = buildD3Formatter(barlistSpec.valueFormat) ?? formatNumber;
+
+  // Compute label width: measure all labels and use a consistent width
+  const measureText =
+    options.measureText ??
+    ((text: string, fontSize: number) => ({
+      width: estimateTextWidth(text, fontSize),
+      height: fontSize,
+    }));
+
+  // When subtitles are present the column must fit: labelText + 6px gap + subtitleText
+  const perRowLabelWidths = new Map<number, number>();
+  let maxCombinedWidth = 0;
+  for (let i = 0; i < validRows.length; i++) {
+    const row = validRows[i];
+    const label = String(row[labelField] ?? '');
+    const labelW = measureText(label, LABEL_FONT_SIZE, LABEL_FONT_WEIGHT).width;
+    perRowLabelWidths.set(i, labelW);
+    let combined = labelW + 4;
+    if (subtitleField && row[subtitleField] != null) {
+      const subtitle = String(row[subtitleField]);
+      combined =
+        labelW + 6 + measureText(subtitle, SUBTITLE_FONT_SIZE, SUBTITLE_FONT_WEIGHT).width + 4;
+    }
+    maxCombinedWidth = Math.max(maxCombinedWidth, combined);
+  }
+  const isNarrow = fullArea.width < 400;
+  const labelBarGap = isNarrow ? 8 : LABEL_BAR_GAP;
+  const barValueGap = isNarrow ? 6 : BAR_VALUE_GAP;
+  const valueWidth = isNarrow ? 44 : VALUE_WIDTH;
+  const maxLabelPct = isNarrow ? 0.35 : 0.4;
+  const labelWidth = Math.max(50, Math.min(maxCombinedWidth, fullArea.width * maxLabelPct));
+
+  const barAreaWidth = fullArea.width - labelWidth - labelBarGap - barValueGap - valueWidth;
+
+  const labelColor = theme.colors.text;
+  const subtitleColor = options.darkMode ? 'rgba(255,255,255,0.5)' : 'rgba(0,0,0,0.45)';
+  const valueColor = options.darkMode ? 'rgba(255,255,255,0.6)' : 'rgba(0,0,0,0.55)';
+
+  // Build row marks
+  const rows: BarListRowMark[] = [];
+
+  for (let i = 0; i < validRows.length; i++) {
+    const row = validRows[i];
+    const value = Number(row[valueField]);
+    const labelText = String(row[labelField] ?? '');
+    const formattedValue = formatter(value);
+    const barColor = getColor(row, i);
+    const pct = maxValue > 0 ? Math.abs(value) / maxValue : 0;
+
+    const rowY = fullArea.y + i * rowHeight;
+    const centerY = rowY + rowContentHeight / 2;
+
+    // Label (left-aligned)
+    const labelX = fullArea.x;
+    const labelStyle: TextStyle = {
+      fontFamily: theme.fonts.family,
+      fontSize: LABEL_FONT_SIZE,
+      fontWeight: LABEL_FONT_WEIGHT,
+      fill: labelColor,
+      lineHeight: 1.4,
+    };
+
+    // Subtitle (left-aligned, positioned after this row's measured label width + gap)
+    let subtitle: BarListRowMark['subtitle'];
+    if (subtitleField && row[subtitleField] != null) {
+      const subtitleText = String(row[subtitleField]);
+      const subtitleX = labelX + (perRowLabelWidths.get(i) ?? 0) + 6;
+      subtitle = {
+        text: subtitleText,
+        x: subtitleX,
+        y: centerY,
+        style: {
+          fontFamily: theme.fonts.family,
+          fontSize: SUBTITLE_FONT_SIZE,
+          fontWeight: SUBTITLE_FONT_WEIGHT,
+          fill: subtitleColor,
+          lineHeight: 1.4,
+        },
+        visible: true,
+      };
+    }
+
+    // Track (muted background bar)
+    const trackX = fullArea.x + labelWidth + labelBarGap;
+    const trackY = centerY - barHeight / 2;
+    const trackWidth = Math.max(barAreaWidth, 0);
+
+    // Fill bar (proportional width)
+    const barWidth = Math.max(pct * trackWidth, 0);
+
+    // Value label (right-aligned)
+    const valueLabelX = trackX + trackWidth + barValueGap + valueWidth;
+    const valueLabelStyle: TextStyle = {
+      fontFamily: `${theme.fonts.family}, ui-monospace, monospace`,
+      fontSize: VALUE_FONT_SIZE,
+      fontWeight: VALUE_FONT_WEIGHT,
+      fill: valueColor,
+      lineHeight: 1.4,
+    };
+
+    const rowMark: BarListRowMark = {
+      type: 'barlist-row',
+      index: i,
+      y: rowY,
+      height: rowHeight,
+      label: {
+        text: labelText,
+        x: labelX,
+        y: centerY,
+        style: labelStyle,
+        visible: true,
+      },
+      subtitle,
+      track: {
+        x: trackX,
+        y: trackY,
+        width: trackWidth,
+        height: barHeight,
+        cornerRadius,
+      },
+      bar: {
+        x: trackX,
+        y: trackY,
+        width: barWidth,
+        height: barHeight,
+        cornerRadius,
+        fill: barColor,
+      },
+      valueLabel: {
+        text: formattedValue,
+        x: valueLabelX,
+        y: centerY,
+        style: valueLabelStyle,
+        visible: true,
+      },
+      value,
+      formattedValue,
+      aria: {
+        role: 'listitem',
+        label: `${labelText}: ${formattedValue}`,
+      },
+      animationIndex: i,
+      data: row,
+    };
+
+    rows.push(rowMark);
+  }
+
+  // Build tooltip descriptors.
+  // TODO: honour encoding.tooltip channel to let callers add extra fields beyond the default value field.
+  const tooltipDescriptors = new Map<string, TooltipContent>();
+  for (const row of rows) {
+    const fields: TooltipField[] = [
+      { label: barlistSpec.encoding.value.title ?? valueField, value: row.formattedValue },
+    ];
+    tooltipDescriptors.set(String(row.index), {
+      title: row.label.text,
+      fields,
+    });
+  }
+
+  // Build a11y metadata
+  const a11y = {
+    altText: `Bar list showing ${rows.length} items ranked by ${valueField}`,
+    dataTableFallback: rows.map((r) => [r.label.text, r.formattedValue]),
+    role: 'list' as const,
+    keyboardNavigable: rows.length > 0,
+  };
+
+  // Resolve animation
+  const resolvedAnimation: ResolvedAnimation | undefined = resolveAnimation(barlistSpec.animation);
+
+  return {
+    area: fullArea,
+    chrome,
+    rows,
+    tooltipDescriptors,
+    a11y,
+    theme,
+    width: options.width,
+    height: options.height,
+    animation: resolvedAnimation,
+    watermark,
+    measureText,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Empty layout fallback
+// ---------------------------------------------------------------------------
+
+function emptyLayout(
+  chrome: ReturnType<typeof computeChrome>,
+  theme: ResolvedTheme,
+  options: CompileOptions,
+  watermark: boolean,
+): BarListLayout {
+  return {
+    area: { x: 0, y: 0, width: 0, height: 0 },
+    chrome,
+    rows: [],
+    tooltipDescriptors: new Map(),
+    a11y: {
+      altText: 'Empty bar list',
+      dataTableFallback: [],
+      role: 'list',
+      keyboardNavigable: false,
+    },
+    theme,
+    width: options.width,
+    height: options.height,
+    watermark,
+    animation: undefined,
+    measureText:
+      options.measureText ??
+      ((text, fontSize) => ({ width: estimateTextWidth(text, fontSize), height: fontSize })),
+  };
+}

package/src/barlist/types.ts

@@ -0,0 +1,28 @@
+/**
+ * Internal normalized barlist spec type used by the compilation pipeline.
+ */
+
+import type {
+  AnimationSpec,
+  BarListEncoding,
+  DarkMode,
+  DataRow,
+  ThemeConfig,
+} from '@opendata-ai/openchart-core';
+
+import type { NormalizedChrome } from '../compiler/types';
+
+export interface NormalizedBarListSpec {
+  type: 'barlist';
+  data: DataRow[];
+  encoding: BarListEncoding;
+  barHeight: number;
+  cornerRadius: number | 'pill';
+  maxItems: number;
+  chrome: NormalizedChrome;
+  theme: ThemeConfig;
+  darkMode: DarkMode;
+  watermark: boolean;
+  animation?: AnimationSpec;
+  valueFormat?: string;
+}