@opendata-ai/openchart-engine 1.2.0

package/src/tables/heatmap.ts

@@ -0,0 +1,121 @@
+/**
+ * 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 } 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
+  let stops = resolvePalette(config.palette, theme);
+  if (darkMode) {
+    const lightBg = '#ffffff';
+    const darkBg = theme.colors.background;
+    stops = stops.map((c) => adaptColorForDarkMode(c, lightBg, darkBg));
+  }
+
+  const interpolator = interpolatorFromStops(stops);
+  const scale = scaleSequential(interpolator).domain(domain).clamp(true);
+
+  // Apply to each row
+  for (const { index, value } of numericValues) {
+    const bg = scale(value);
+    const textColor = accessibleTextColor(bg);
+
+    result.set(index, {
+      backgroundColor: bg,
+      color: textColor,
+    });
+  }
+
+  return result;
+}

package/src/tables/pagination.ts

@@ -0,0 +1,46 @@
+/**
+ * Table pagination: slice data into pages.
+ */
+
+/**
+ * Paginate data rows.
+ *
+ * Returns the current page's rows along with pagination metadata.
+ * Page is 0-indexed and clamped to valid range.
+ * If pageSize is 0 or negative, pagination is disabled (returns all rows).
+ */
+export function paginateData(
+  data: Record<string, unknown>[],
+  page: number,
+  pageSize: number,
+): {
+  rows: Record<string, unknown>[];
+  totalRows: number;
+  totalPages: number;
+  page: number;
+} {
+  const totalRows = data.length;
+
+  // Disabled pagination
+  if (pageSize <= 0) {
+    return {
+      rows: data,
+      totalRows,
+      totalPages: 1,
+      page: 0,
+    };
+  }
+
+  const totalPages = Math.max(1, Math.ceil(totalRows / pageSize));
+  // Clamp page to valid range
+  const clampedPage = Math.max(0, Math.min(page, totalPages - 1));
+  const start = clampedPage * pageSize;
+  const end = Math.min(start + pageSize, totalRows);
+
+  return {
+    rows: data.slice(start, end),
+    totalRows,
+    totalPages,
+    page: clampedPage,
+  };
+}

package/src/tables/search.ts

@@ -0,0 +1,66 @@
+/**
+ * Table search: build a search index and filter rows by query.
+ *
+ * The search index concatenates formatted cell values per row so
+ * substring matching works across all columns.
+ */
+
+import type { ColumnConfig } from '@opendata-ai/openchart-core';
+import { formatValueForSearch } from './format-cells';
+
+/**
+ * Build a search index mapping original data indices to searchable strings.
+ * Each row's searchable string is the concatenation of all column values,
+ * separated by spaces, lowercased.
+ */
+export function buildSearchIndex(
+  data: Record<string, unknown>[],
+  columns: ColumnConfig[],
+): Map<number, string> {
+  const index = new Map<number, string>();
+
+  for (let i = 0; i < data.length; i++) {
+    const row = data[i];
+    const parts: string[] = [];
+
+    for (const col of columns) {
+      parts.push(formatValueForSearch(row[col.key], col));
+    }
+
+    index.set(i, parts.join(' ').toLowerCase());
+  }
+
+  return index;
+}
+
+/**
+ * Filter data by a search query using the pre-built search index.
+ *
+ * Returns the filtered data and the original indices of matching rows.
+ * Empty query returns all data.
+ */
+export function filterBySearch(
+  data: Record<string, unknown>[],
+  query: string,
+  searchIndex: Map<number, string>,
+  originalIndices: number[],
+): { data: Record<string, unknown>[]; indices: number[] } {
+  if (!query || query.trim() === '') {
+    return { data, indices: originalIndices };
+  }
+
+  const lowerQuery = query.toLowerCase();
+  const filteredData: Record<string, unknown>[] = [];
+  const filteredIndices: number[] = [];
+
+  for (let i = 0; i < data.length; i++) {
+    const originalIdx = originalIndices[i];
+    const searchText = searchIndex.get(originalIdx);
+    if (searchText?.includes(lowerQuery)) {
+      filteredData.push(data[i]);
+      filteredIndices.push(originalIdx);
+    }
+  }
+
+  return { data: filteredData, indices: filteredIndices };
+}

package/src/tables/sort.ts

@@ -0,0 +1,69 @@
+/**
+ * Stable sort for table data.
+ *
+ * Sorts data by a column key with type-aware comparison:
+ * - Numbers: numeric comparison
+ * - Strings: localeCompare
+ * - Dates: timestamp comparison
+ * - Nulls: always sorted last regardless of direction
+ */
+
+import type { SortState } from '@opendata-ai/openchart-core';
+
+/** Result of sorting: sorted data rows with their original indices preserved. */
+export interface SortResult {
+  data: Record<string, unknown>[];
+  originalIndices: number[];
+}
+
+/**
+ * Sort data rows by the specified column.
+ * Returns a new array (no mutation). Stable sort preserves
+ * original order for rows with equal values.
+ *
+ * Also returns the original indices so callers can track
+ * which row came from where (needed for heatmap/category color lookups).
+ */
+export function sortData(data: Record<string, unknown>[], sort: SortState): SortResult {
+  const { column, direction } = sort;
+  const multiplier = direction === 'asc' ? 1 : -1;
+
+  // Create index-value pairs for stable sort
+  const indexed = data.map((row, i) => ({ row, index: i }));
+
+  indexed.sort((a, b) => {
+    const aVal = a.row[column];
+    const bVal = b.row[column];
+
+    // Nulls always last
+    const aNull = aVal == null;
+    const bNull = bVal == null;
+    if (aNull && bNull) return a.index - b.index; // preserve order
+    if (aNull) return 1;
+    if (bNull) return -1;
+
+    let cmp = 0;
+
+    // Number comparison
+    if (typeof aVal === 'number' && typeof bVal === 'number') {
+      cmp = aVal - bVal;
+    }
+    // Date comparison
+    else if (aVal instanceof Date && bVal instanceof Date) {
+      cmp = aVal.getTime() - bVal.getTime();
+    }
+    // String comparison (or mixed types)
+    else {
+      cmp = String(aVal).localeCompare(String(bVal));
+    }
+
+    // Stable sort: fall back to original index for equal values
+    if (cmp === 0) return a.index - b.index;
+    return cmp * multiplier;
+  });
+
+  return {
+    data: indexed.map((item) => item.row),
+    originalIndices: indexed.map((item) => item.index),
+  };
+}

package/src/tables/sparkline.ts

@@ -0,0 +1,113 @@
+/**
+ * Sparkline computation for inline mini-charts in table cells.
+ *
+ * Produces normalized data points (0-1 range) for sparkline rendering.
+ * The adapter handles the actual drawing.
+ */
+
+import type {
+  ResolvedTheme,
+  SparklineColumnConfig,
+  SparklineData,
+} from '@opendata-ai/openchart-core';
+
+export type { SparklineData };
+
+/**
+ * Extract numeric values from a row for sparkline rendering.
+ *
+ * If valuesField is specified, reads an array from that field.
+ * Otherwise uses the column's own key (expects an array value).
+ */
+function extractValues(
+  row: Record<string, unknown>,
+  columnKey: string,
+  config: SparklineColumnConfig,
+): number[] {
+  const field = config.valuesField ?? columnKey;
+  const raw = row[field];
+
+  if (!Array.isArray(raw)) return [];
+
+  return raw
+    .map((v) => (typeof v === 'number' && Number.isFinite(v) ? v : null))
+    .filter((v): v is number => v !== null);
+}
+
+/**
+ * Compute sparkline data for a single row.
+ *
+ * Normalizes values to 0-1 range. Returns null if no valid values.
+ */
+export function computeSparkline(
+  values: number[],
+  config: SparklineColumnConfig,
+  theme: ResolvedTheme,
+  _darkMode: boolean,
+): SparklineData | null {
+  if (values.length === 0) return null;
+
+  const type = config.type ?? 'line';
+  const color = config.color ?? theme.colors.categorical[0];
+
+  let min = Infinity;
+  let max = -Infinity;
+  for (const v of values) {
+    if (v < min) min = v;
+    if (v > max) max = v;
+  }
+
+  const range = max - min;
+  const normalize = (v: number): number => (range === 0 ? 0.5 : (v - min) / range);
+
+  const startValue = values[0];
+  const endValue = values[values.length - 1];
+
+  if (type === 'line') {
+    const points = values.map((v, i) => ({
+      x: values.length === 1 ? 0.5 : i / (values.length - 1),
+      y: normalize(v),
+    }));
+
+    return {
+      type,
+      points,
+      bars: [],
+      color,
+      count: values.length,
+      startValue,
+      endValue,
+    };
+  }
+
+  // Bar (horizontal) or column (vertical): normalized as proportions
+  const bars = values.map(normalize);
+  const points = values.map((v, i) => ({
+    x: values.length === 1 ? 0.5 : i / (values.length - 1),
+    y: normalize(v),
+  }));
+
+  return {
+    type,
+    points,
+    bars,
+    color,
+    count: values.length,
+    startValue,
+    endValue,
+  };
+}
+
+/**
+ * Extract values and compute sparkline data for a cell.
+ */
+export function computeSparklineForRow(
+  row: Record<string, unknown>,
+  columnKey: string,
+  config: SparklineColumnConfig,
+  theme: ResolvedTheme,
+  darkMode: boolean,
+): SparklineData | null {
+  const values = extractValues(row, columnKey, config);
+  return computeSparkline(values, config, theme, darkMode);
+}

package/src/tables/utils.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared utilities for table column computations.
+ */
+
+import { contrastRatio } from '@opendata-ai/openchart-core';
+
+/**
+ * Pick a text color (black or white) that meets better contrast against the background.
+ */
+export function accessibleTextColor(bg: string): string {
+  const white = '#ffffff';
+  const black = '#000000';
+  const whiteRatio = contrastRatio(white, bg);
+  const blackRatio = contrastRatio(black, bg);
+  return whiteRatio >= blackRatio ? white : black;
+}