@opendata-ai/openchart-engine 1.2.0

package/src/tables/bar-column.ts

@@ -0,0 +1,94 @@
+/**
+ * Bar column computation for inline bar visualization in table cells.
+ *
+ * Computes bar width as a proportion of the max value.
+ * Supports negative values with bidirectional bars.
+ */
+
+import type { BarColumnConfig, ResolvedTheme } from '@opendata-ai/openchart-core';
+
+const NEGATIVE_BAR_COLOR = '#c44e52';
+
+/**
+ * Compute the bar percentage, offset, and color for a single cell value.
+ *
+ * barPercent is 0-1. barOffset is 0-1 (left edge position).
+ * When the column has negative values, bars extend bidirectionally from a zero line.
+ */
+export function computeBarCell(
+  value: number,
+  config: BarColumnConfig,
+  columnMax: number,
+  columnMin: number,
+  theme: ResolvedTheme,
+  _darkMode: boolean,
+): { barPercent: number; barOffset: number; barColor: string; isNegative: boolean } {
+  const barColor = config.color ?? theme.colors.categorical[0];
+  const hasNegatives = columnMin < 0;
+
+  if (!Number.isFinite(value)) {
+    return { barPercent: 0, barOffset: 0, barColor, isNegative: false };
+  }
+
+  if (!hasNegatives) {
+    // Positive-only column: simple left-to-right bars
+    const maxValue = config.maxValue ?? columnMax;
+    if (maxValue <= 0) {
+      return { barPercent: 0, barOffset: 0, barColor, isNegative: false };
+    }
+    const barPercent = Math.max(0, Math.min(1, value / maxValue));
+    return { barPercent, barOffset: 0, barColor, isNegative: false };
+  }
+
+  // Bidirectional: zero line position proportional to data range
+  const maxPos = config.maxValue ?? columnMax;
+  const absMin = Math.abs(columnMin);
+  const totalRange = maxPos + absMin;
+  if (totalRange === 0) {
+    return { barPercent: 0, barOffset: 0, barColor, isNegative: false };
+  }
+
+  const zeroPos = absMin / totalRange;
+
+  if (value >= 0) {
+    const barPercent = value / totalRange;
+    return { barPercent, barOffset: zeroPos, barColor, isNegative: false };
+  }
+
+  // Negative value: red bar extending left from zero
+  const barPercent = Math.abs(value) / totalRange;
+  return {
+    barPercent,
+    barOffset: zeroPos - barPercent,
+    barColor: config.color ?? NEGATIVE_BAR_COLOR,
+    isNegative: true,
+  };
+}
+
+/**
+ * Compute the column max and min from data for bar scaling.
+ */
+export function computeColumnMax(data: Record<string, unknown>[], key: string): number {
+  let max = 0;
+  for (const row of data) {
+    const val = row[key];
+    if (typeof val === 'number' && Number.isFinite(val) && val > max) {
+      max = val;
+    }
+  }
+  return max;
+}
+
+/**
+ * Compute the column minimum from data (for negative bar support).
+ */
+export function computeColumnMin(data: Record<string, unknown>[], key: string): number {
+  let min = 0;
+  for (const row of data) {
+    const val = row[key];
+    if (typeof val === 'number' && Number.isFinite(val) && val < min) {
+      min = val;
+    }
+  }
+  return min;
+}

package/src/tables/category-colors.ts

@@ -0,0 +1,67 @@
+/**
+ * Category color assignment for table columns.
+ *
+ * Maps categorical values to colors using explicit mappings or
+ * theme categorical palette, with AA-contrast text colors.
+ */
+
+import type { CellStyle, ColumnConfig, ResolvedTheme } from '@opendata-ai/openchart-core';
+import { adaptColorForDarkMode } from '@opendata-ai/openchart-core';
+import { accessibleTextColor } from './utils';
+
+/**
+ * Compute category-colored cell styles for a column.
+ *
+ * Uses column.categoryColors for explicit value-to-color mappings.
+ * Unmapped values get colors from the theme's categorical palette.
+ *
+ * Returns a Map keyed by original data index with background and text colors.
+ */
+export function computeCategoryColors(
+  data: Record<string, unknown>[],
+  column: ColumnConfig,
+  theme: ResolvedTheme,
+  darkMode: boolean,
+): Map<number, CellStyle> {
+  const result = new Map<number, CellStyle>();
+  const explicitMap = column.categoryColors;
+  if (!explicitMap) return result;
+
+  const categoricalPalette = theme.colors.categorical;
+  let nextPaletteIndex = 0;
+  const autoAssigned = new Map<string, string>();
+  const lightBg = '#ffffff';
+  const darkBg = theme.colors.background;
+
+  for (let i = 0; i < data.length; i++) {
+    const raw = data[i][column.key];
+    if (raw == null) continue;
+
+    const key = String(raw);
+    let bg: string;
+
+    if (explicitMap[key]) {
+      bg = explicitMap[key];
+    } else if (autoAssigned.has(key)) {
+      bg = autoAssigned.get(key)!;
+    } else {
+      // Assign from categorical palette
+      bg = categoricalPalette[nextPaletteIndex % categoricalPalette.length];
+      nextPaletteIndex++;
+      autoAssigned.set(key, bg);
+    }
+
+    // Dark mode adaptation
+    if (darkMode) {
+      bg = adaptColorForDarkMode(bg, lightBg, darkBg);
+    }
+
+    const textColor = accessibleTextColor(bg);
+    result.set(i, {
+      backgroundColor: bg,
+      color: textColor,
+    });
+  }
+
+  return result;
+}

package/src/tables/compile-table.ts

@@ -0,0 +1,420 @@
+/**
+ * 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 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 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,
+  );
+
+  // 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,
+  };
+}

package/src/tables/format-cells.ts

@@ -0,0 +1,110 @@
+/**
+ * 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 { formatDate, formatNumber } from '@opendata-ai/openchart-core';
+import { format as d3Format } from 'd3-format';
+
+/**
+ * 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 d3-format string and value is numeric
+  if (column.format && isNumericValue(value)) {
+    try {
+      const formatter = d3Format(column.format);
+      return {
+        value,
+        formattedValue: formatter(value),
+        style,
+      };
+    } catch {
+      // Fall through to auto-format if format string is invalid
+    }
+  }
+
+  // Auto-format numbers
+  if (isNumericValue(value)) {
+    return {
+      value,
+      formattedValue: formatNumber(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)) {
+    try {
+      return d3Format(column.format)(value);
+    } catch {
+      // Fall through
+    }
+  }
+
+  if (isNumericValue(value)) {
+    return formatNumber(value);
+  }
+
+  return String(value);
+}