@opendata-ai/openchart-engine 8.0.0-rc.8 → 8.0.0

package/src/tables/compile-table.ts

@@ -1,427 +0,0 @@
-/**
- * Table compilation pipeline.
- *
- * Takes a NormalizedTableSpec and produces a fully resolved TableLayout:
- *   resolve columns -> build search index -> sort data -> filter by search ->
- *   paginate -> format visible cells -> apply visual enhancements -> return
- */
-
-import type {
-  CellStyle,
-  ColumnConfig,
-  CompileTableOptions,
-  PaginationState,
-  ResolvedColumn,
-  ResolvedTheme,
-  TableCell,
-  TableLayout,
-  TableRow,
-} from '@opendata-ai/openchart-core';
-import { computeChrome, estimateTextWidth } from '@opendata-ai/openchart-core';
-
-import { resolveAnimation } from '../compiler/animation';
-import type { NormalizedTableSpec } from '../compiler/types';
-import { computeBarCell, computeColumnMax, computeColumnMin } from './bar-column';
-import { computeCategoryColors } from './category-colors';
-import { formatCell } from './format-cells';
-import { computeHeatmapColors } from './heatmap';
-import { paginateData } from './pagination';
-import { buildSearchIndex, filterBySearch } from './search';
-import { sortData } from './sort';
-import { computeSparklineForRow, type SparklineData } from './sparkline';
-
-// ---------------------------------------------------------------------------
-// Column resolution
-// ---------------------------------------------------------------------------
-
-/**
- * Determine the cell type for a column based on its config.
- * Precedence: sparkline > bar > heatmap > image > flag > categoryColors > text
- */
-function determineCellType(col: ColumnConfig): ResolvedColumn['cellType'] {
-  if (col.sparkline) return 'sparkline';
-  if (col.bar) return 'bar';
-  if (col.heatmap) return 'heatmap';
-  if (col.image) return 'image';
-  if (col.flag) return 'flag';
-  if (col.categoryColors) return 'category';
-  return 'text';
-}
-
-/**
- * Infer alignment for a column.
- * Explicit align wins. Otherwise: right for numeric data, left for everything else.
- */
-function inferAlignment(
-  col: ColumnConfig,
-  data: Record<string, unknown>[],
-): 'left' | 'center' | 'right' {
-  if (col.align) return col.align;
-
-  // Check first non-null value in the data
-  for (const row of data) {
-    const val = row[col.key];
-    if (val != null) {
-      return typeof val === 'number' ? 'right' : 'left';
-    }
-  }
-  return 'left';
-}
-
-/**
- * Estimate the needed width for a column by measuring header and data values.
- * Samples up to 100 rows for estimation.
- */
-function estimateColumnWidth(
-  col: ColumnConfig,
-  data: Record<string, unknown>[],
-  fontSize: number,
-): number {
-  const MIN_WIDTH = 60;
-  const PADDING = 24; // cell padding
-
-  // Visual columns get fixed widths (they render graphics, not text)
-  if (col.sparkline) return 140;
-  if (col.image) return (col.image.width ?? 24) + PADDING;
-  if (col.flag) return 60;
-
-  // Header width
-  const label = col.label ?? col.key;
-  const headerWidth = estimateTextWidth(label, fontSize, 600) + PADDING;
-
-  // Sample data values
-  const sampleSize = Math.min(100, data.length);
-  let maxDataWidth = 0;
-
-  for (let i = 0; i < sampleSize; i++) {
-    const val = data[i][col.key];
-    const text = val == null ? '' : String(val);
-    const width = estimateTextWidth(text, fontSize, 400) + PADDING;
-    if (width > maxDataWidth) maxDataWidth = width;
-  }
-
-  return Math.max(MIN_WIDTH, headerWidth, maxDataWidth);
-}
-
-/**
- * Resolve all columns: compute widths, types, alignment.
- */
-function resolveColumns(
-  columns: ColumnConfig[],
-  data: Record<string, unknown>[],
-  totalWidth: number,
-  theme: ResolvedTheme,
-): ResolvedColumn[] {
-  const fontSize = theme.fonts.sizes.body;
-
-  // Compute natural widths and identify fixed-width visual columns.
-  // Visual columns (sparkline, image, flag) get fixed sizes; only text
-  // columns participate in proportional scaling to fill the container.
-  const isFixed = columns.map((col) => !!(col.sparkline || col.image || col.flag));
-
-  const naturalWidths = columns.map((col) => {
-    if (col.width) {
-      // Parse explicit width
-      if (col.width.endsWith('px')) {
-        return parseInt(col.width, 10) || 100;
-      }
-      if (col.width.endsWith('%')) {
-        return (parseFloat(col.width) / 100) * totalWidth || 100;
-      }
-      return parseInt(col.width, 10) || 100;
-    }
-    return estimateColumnWidth(col, data, fontSize);
-  });
-
-  // Fixed columns keep their natural width; remaining space goes to text columns
-  const fixedTotal = naturalWidths.reduce((sum, w, i) => sum + (isFixed[i] ? w : 0), 0);
-  const flexTotal = naturalWidths.reduce((sum, w, i) => sum + (isFixed[i] ? 0 : w), 0);
-  const remainingWidth = totalWidth - fixedTotal;
-  const flexScale = flexTotal > 0 && remainingWidth > 0 ? remainingWidth / flexTotal : 1;
-
-  return columns.map((col, i) => ({
-    key: col.key,
-    label: col.label ?? col.key,
-    width: Math.max(60, isFixed[i] ? naturalWidths[i] : Math.round(naturalWidths[i] * flexScale)),
-    sortable: col.sortable ?? true,
-    align: inferAlignment(col, data),
-    cellType: determineCellType(col),
-  }));
-}
-
-// ---------------------------------------------------------------------------
-// Cell building
-// ---------------------------------------------------------------------------
-
-/**
- * Build a fully resolved TableCell from a data value and column config.
- */
-function buildCell(
-  value: unknown,
-  column: ColumnConfig,
-  resolvedColumn: ResolvedColumn,
-  heatmapStyle: CellStyle | undefined,
-  categoryStyle: CellStyle | undefined,
-  barData:
-    | { barPercent: number; barOffset: number; barColor: string; isNegative: boolean }
-    | undefined,
-  sparklineData: SparklineData | null,
-): TableCell {
-  const base = formatCell(value, column);
-
-  // Apply font variant for number columns
-  if (typeof value === 'number') {
-    base.style = { ...base.style, fontVariant: 'tabular-nums' };
-  }
-
-  const cellType = resolvedColumn.cellType;
-
-  switch (cellType) {
-    case 'heatmap': {
-      const merged = heatmapStyle ? { ...base.style, ...heatmapStyle } : base.style;
-      return {
-        ...base,
-        cellType: 'heatmap',
-        style: merged,
-      };
-    }
-    case 'category': {
-      const merged = categoryStyle ? { ...base.style, ...categoryStyle } : base.style;
-      return {
-        ...base,
-        cellType: 'category',
-        style: merged,
-      };
-    }
-    case 'bar': {
-      return {
-        ...base,
-        cellType: 'bar',
-        barWidth: barData?.barPercent ?? 0,
-        barOffset: barData?.barOffset ?? 0,
-        barColor: barData?.barColor ?? '#ccc',
-        isNegative: barData?.isNegative ?? false,
-      };
-    }
-    case 'sparkline': {
-      return {
-        ...base,
-        cellType: 'sparkline',
-        sparklineData,
-      };
-    }
-    case 'image': {
-      const src = typeof value === 'string' ? value : '';
-      const imgConfig = column.image ?? {};
-      return {
-        ...base,
-        cellType: 'image',
-        src,
-        imageWidth: imgConfig.width ?? 24,
-        imageHeight: imgConfig.height ?? 24,
-        rounded: imgConfig.rounded ?? false,
-      };
-    }
-    case 'flag': {
-      const code = typeof value === 'string' ? value : '';
-      return {
-        ...base,
-        cellType: 'flag',
-        countryCode: code,
-      };
-    }
-    default: {
-      return {
-        ...base,
-        cellType: 'text',
-      };
-    }
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Main pipeline
-// ---------------------------------------------------------------------------
-
-/**
- * Compile a normalized table spec into a TableLayout.
- *
- * Pipeline:
- * 1. Resolve columns (widths, types, alignment)
- * 2. Build search index
- * 3. Sort data
- * 4. Filter by search
- * 5. Paginate
- * 6. Format visible cells and apply visual enhancements
- * 7. Return TableLayout
- */
-export function compileTableLayout(
-  spec: NormalizedTableSpec,
-  options: CompileTableOptions,
-  theme: ResolvedTheme,
-): TableLayout {
-  const data = spec.data;
-  const darkMode = theme.isDark;
-
-  // 1. Resolve columns
-  const resolvedColumns = resolveColumns(spec.columns, data, options.width, theme);
-
-  // 2. Build search index (over full dataset, using original indices)
-  const searchIndex = spec.search
-    ? buildSearchIndex(data, spec.columns)
-    : new Map<number, string>();
-
-  // 3. Track original indices through the pipeline
-  let currentData = data;
-  let originalIndices = data.map((_, i) => i);
-
-  // 4. Sort
-  if (options.sort) {
-    const sorted = sortData(currentData, options.sort);
-    // Map sorted originalIndices back through our current index mapping
-    originalIndices = sorted.originalIndices.map((i) => originalIndices[i]);
-    currentData = sorted.data;
-  }
-
-  // 5. Filter by search
-  if (spec.search && options.search) {
-    const filtered = filterBySearch(currentData, options.search, searchIndex, originalIndices);
-    currentData = filtered.data;
-    originalIndices = filtered.indices;
-  }
-
-  const totalFiltered = currentData.length;
-
-  // 6. Paginate
-  let pageSize = 0;
-  let currentPage = 0;
-  let paginationState: PaginationState | undefined;
-
-  if (spec.pagination) {
-    pageSize =
-      options.pageSize ?? (typeof spec.pagination === 'object' ? spec.pagination.pageSize : 25);
-    currentPage = options.page ?? 0;
-    const paginated = paginateData(currentData, currentPage, pageSize);
-
-    // Slice indices too
-    const start = paginated.page * pageSize;
-    const end = start + paginated.rows.length;
-    const pageIndices = originalIndices.slice(start, end);
-
-    currentData = paginated.rows;
-    originalIndices = pageIndices;
-
-    paginationState = {
-      page: paginated.page,
-      pageSize,
-      totalRows: paginated.totalRows,
-      totalPages: paginated.totalPages,
-    };
-  }
-
-  // 7. Pre-compute visual enhancements for visible data columns
-  // We need heatmap/category colors computed over the FULL dataset, then
-  // applied only to visible rows.
-  const heatmapMaps = new Map<string, Map<number, CellStyle>>();
-  const categoryMaps = new Map<string, Map<number, CellStyle>>();
-  const barMaxes = new Map<string, number>();
-  const barMins = new Map<string, number>();
-
-  for (let c = 0; c < spec.columns.length; c++) {
-    const col = spec.columns[c];
-    const resolved = resolvedColumns[c];
-
-    if (resolved.cellType === 'heatmap' && col.heatmap) {
-      heatmapMaps.set(col.key, computeHeatmapColors(data, col, theme, darkMode));
-    }
-    if (resolved.cellType === 'category' && col.categoryColors) {
-      categoryMaps.set(col.key, computeCategoryColors(data, col, theme, darkMode));
-    }
-    if (resolved.cellType === 'bar' && col.bar) {
-      barMaxes.set(col.key, computeColumnMax(data, col.key));
-      barMins.set(col.key, computeColumnMin(data, col.key));
-    }
-  }
-
-  // 8. Build rows from visible data
-  const rows: TableRow[] = currentData.map((row, i) => {
-    const origIdx = originalIndices[i];
-    const rowId = spec.rowKey ? String(row[spec.rowKey] ?? origIdx) : String(origIdx);
-
-    const cells: TableCell[] = spec.columns.map((col, c) => {
-      const resolved = resolvedColumns[c];
-      const value = row[col.key];
-
-      // Lookup visual enhancement data
-      const heatmapStyle = heatmapMaps.get(col.key)?.get(origIdx);
-      const categoryStyle = categoryMaps.get(col.key)?.get(origIdx);
-
-      let barData:
-        | { barPercent: number; barOffset: number; barColor: string; isNegative: boolean }
-        | undefined;
-      if (resolved.cellType === 'bar' && col.bar && typeof value === 'number') {
-        barData = computeBarCell(
-          value,
-          col.bar,
-          barMaxes.get(col.key) ?? 0,
-          barMins.get(col.key) ?? 0,
-          theme,
-          darkMode,
-        );
-      }
-
-      let sparklineData: SparklineData | null = null;
-      if (resolved.cellType === 'sparkline' && col.sparkline) {
-        sparklineData = computeSparklineForRow(row, col.key, col.sparkline, theme, darkMode);
-      }
-
-      return buildCell(value, col, resolved, heatmapStyle, categoryStyle, barData, sparklineData);
-    });
-
-    return { id: rowId, cells, data: row };
-  });
-
-  // 9. Compute chrome
-  const watermark = spec.watermark;
-  const chrome = computeChrome(
-    {
-      title: spec.chrome.title,
-      subtitle: spec.chrome.subtitle,
-      source: spec.chrome.source,
-      byline: spec.chrome.byline,
-      footer: spec.chrome.footer,
-    },
-    theme,
-    options.width,
-    options.measureText,
-    'full',
-    undefined,
-    watermark,
-  );
-
-  // 10. Build a11y
-  const titleText = spec.chrome.title?.text ?? '';
-  const caption = titleText ? `Table: ${titleText}` : `Data table with ${data.length} rows`;
-
-  return {
-    chrome,
-    columns: resolvedColumns,
-    rows,
-    sort: options.sort,
-    pagination: paginationState,
-    search: {
-      enabled: spec.search,
-      placeholder: 'Search...',
-      query: options.search ?? '',
-    },
-    stickyFirstColumn: spec.stickyFirstColumn,
-    compact: spec.compact,
-    a11y: {
-      caption,
-      summary: `${resolvedColumns.length} columns, ${totalFiltered} rows`,
-    },
-    theme,
-    animation: resolveAnimation(spec.animation),
-    watermark,
-  };
-}

package/src/tables/format-cells.ts

@@ -1,115 +0,0 @@
-/**
- * Cell value formatting for table columns.
- *
- * Handles number formatting (d3-format), date formatting, and
- * null/undefined values. Produces the formattedValue string and
- * base style for each cell.
- */
-
-import type { CellStyle, ColumnConfig, TableCellBase } from '@opendata-ai/openchart-core';
-import {
-  buildD3Formatter,
-  defaultNumberFormatter,
-  formatDate,
-  resolveNumberFormatter,
-} from '@opendata-ai/openchart-core';
-
-/**
- * Check if a value is numeric (finite number or parseable numeric string).
- */
-function isNumericValue(value: unknown): value is number {
-  if (typeof value === 'number') return Number.isFinite(value);
-  return false;
-}
-
-/**
- * Check if a value is a date.
- */
-function isDateValue(value: unknown): boolean {
-  if (value instanceof Date) return !Number.isNaN(value.getTime());
-  return false;
-}
-
-/**
- * Format a raw cell value into a display string with styling.
- *
- * Formatting precedence:
- * 1. null/undefined -> ""
- * 2. column.format (d3-format string) for numbers
- * 3. Auto-format: numbers via formatNumber, dates via formatDate
- * 4. Fallback: String(value)
- */
-export function formatCell(value: unknown, column: ColumnConfig): TableCellBase {
-  const style: CellStyle = {};
-
-  // Null/undefined -> empty
-  if (value == null) {
-    return {
-      value,
-      formattedValue: '',
-      style,
-    };
-  }
-
-  // If column has a format string and value is numeric
-  if (column.format && isNumericValue(value)) {
-    const formatter =
-      resolveNumberFormatter(column.format, { surface: 'table' }) ??
-      buildD3Formatter(column.format);
-    if (formatter) {
-      return {
-        value,
-        formattedValue: formatter(value),
-        style,
-      };
-    }
-  }
-
-  // Auto-format numbers (tables get full precision, no compact notation)
-  if (isNumericValue(value)) {
-    return {
-      value,
-      formattedValue: defaultNumberFormatter({ surface: 'table' })(value),
-      style,
-    };
-  }
-
-  // Auto-format dates
-  if (isDateValue(value)) {
-    return {
-      value,
-      formattedValue: formatDate(value as Date),
-      style,
-    };
-  }
-
-  // String and everything else
-  return {
-    value,
-    formattedValue: String(value),
-    style,
-  };
-}
-
-/**
- * Format a value into a string for search indexing.
- * Uses d3-format for numeric columns, otherwise String().
- */
-export function formatValueForSearch(value: unknown, column: ColumnConfig): string {
-  if (value == null) return '';
-
-  if (column.format && isNumericValue(value)) {
-    const formatter =
-      resolveNumberFormatter(column.format, { surface: 'table' }) ??
-      buildD3Formatter(column.format);
-    if (formatter) {
-      return formatter(value);
-    }
-  }
-
-  if (isNumericValue(value)) {
-    return defaultNumberFormatter({ surface: 'table' })(value);
-  }
-
-  return String(value);
-}

package/src/tables/heatmap.ts

@@ -1,141 +0,0 @@
-/**
- * Heatmap coloring for table columns.
- *
- * Colors cell backgrounds using sequential or diverging color scales,
- * then picks an accessible text color for each background.
- */
-
-import type { CellStyle, ColumnConfig, ResolvedTheme } from '@opendata-ai/openchart-core';
-import { adaptColorForDarkMode, contrastRatio } from '@opendata-ai/openchart-core';
-import { interpolateRgb } from 'd3-interpolate';
-import { scaleSequential } from 'd3-scale';
-import { accessibleTextColor } from './utils';
-
-/**
- * Build an interpolator from an array of color stops.
- * Uses d3-interpolate for smooth color transitions.
- */
-function interpolatorFromStops(stops: string[]): (t: number) => string {
-  if (stops.length === 0) return () => '#ffffff';
-  if (stops.length === 1) return () => stops[0];
-
-  return (t: number) => {
-    const clamped = Math.max(0, Math.min(1, t));
-    const segment = clamped * (stops.length - 1);
-    const lo = Math.floor(segment);
-    const hi = Math.min(lo + 1, stops.length - 1);
-    const frac = segment - lo;
-    return interpolateRgb(stops[lo], stops[hi])(frac);
-  };
-}
-
-/**
- * Resolve palette from column config or theme.
- *
- * - If palette is an array of color stops, use directly
- * - If palette is a string name, look it up in theme sequential then diverging
- * - If no palette specified, use the first sequential palette from the theme
- */
-function resolvePalette(palette: string | string[] | undefined, theme: ResolvedTheme): string[] {
-  if (Array.isArray(palette)) return palette;
-
-  const seqPalettes = theme.colors.sequential;
-  const divPalettes = theme.colors.diverging;
-
-  if (typeof palette === 'string') {
-    if (seqPalettes[palette]) return seqPalettes[palette];
-    if (divPalettes[palette]) return divPalettes[palette];
-  }
-
-  // Default: first sequential palette
-  const firstSeqKey = Object.keys(seqPalettes)[0];
-  return firstSeqKey ? seqPalettes[firstSeqKey] : ['#deebf7', '#08519c'];
-}
-
-/**
- * Compute heatmap cell styles for a column.
- *
- * Returns a Map keyed by original data index with background and text colors.
- */
-export function computeHeatmapColors(
-  data: Record<string, unknown>[],
-  column: ColumnConfig,
-  theme: ResolvedTheme,
-  darkMode: boolean,
-): Map<number, CellStyle> {
-  const result = new Map<number, CellStyle>();
-  const config = column.heatmap;
-  if (!config) return result;
-
-  // Determine which field provides the color values
-  const colorField = config.colorByField ?? column.key;
-
-  // Extract numeric values and compute domain
-  const numericValues: { index: number; value: number }[] = [];
-  for (let i = 0; i < data.length; i++) {
-    const raw = data[i][colorField];
-    if (typeof raw === 'number' && Number.isFinite(raw)) {
-      numericValues.push({ index: i, value: raw });
-    }
-  }
-
-  if (numericValues.length === 0) return result;
-
-  // Domain: from config or data min/max
-  let domain: [number, number];
-  if (config.domain) {
-    domain = config.domain;
-  } else {
-    let min = Infinity;
-    let max = -Infinity;
-    for (const { value } of numericValues) {
-      if (value < min) min = value;
-      if (value > max) max = value;
-    }
-    domain = [min, max];
-  }
-
-  // Resolve palette and build scale.
-  // For dark mode with custom palettes: replace near-white low-end stops
-  // with the dark background so the gradient blends into the table surface.
-  // Theme-named palettes use the standard adaptColorForDarkMode path.
-  let stops = resolvePalette(config.palette, theme);
-  if (darkMode) {
-    const lightBg = '#ffffff';
-    const themeBg = theme.colors.background;
-    // Use an opaque dark surface for palette blending even when the theme
-    // bg is transparent, so interpolation never passes through alpha=0
-    // (which breaks accessibleTextColor via NaN contrast ratios).
-    const darkBg = themeBg === 'transparent' ? '#09090b' : themeBg;
-    if (Array.isArray(config.palette)) {
-      // Custom arrays: swap near-white stops for the dark bg so the low end
-      // blends in, then adapt the remaining (saturated) stops normally.
-      stops = stops.map((c) => {
-        const ratio = contrastRatio(c, lightBg);
-        if (ratio < 1.15) return darkBg;
-        return adaptColorForDarkMode(c, lightBg, darkBg);
-      });
-    } else {
-      stops = stops.map((c) => adaptColorForDarkMode(c, lightBg, darkBg));
-    }
-  }
-
-  const interpolator = interpolatorFromStops(stops);
-  const scale = scaleSequential(interpolator).domain(domain).clamp(true);
-
-  // Apply to each row. Skip cells at the domain minimum so the normal
-  // row background (striping) shows through instead of painting an
-  // opaque low-end color that clashes with the table chrome.
-  for (const { index, value } of numericValues) {
-    if (value <= domain[0]) continue;
-    const bg = scale(value);
-    const textColor = accessibleTextColor(bg);
-
-    result.set(index, {
-      backgroundColor: bg,
-      color: textColor,
-    });
-  }
-
-  return result;
-}