@opendata-ai/openchart-core 2.0.0

package/src/helpers/spec-builders.ts

@@ -0,0 +1,410 @@
+/**
+ * Spec construction helpers: typed builder functions for common chart types.
+ *
+ * These builders reduce boilerplate when creating specs programmatically.
+ * They accept field names as strings (simple case) or full EncodingChannel
+ * objects (when you need to customize type, aggregate, axis, or scale).
+ *
+ * Type inference: when a string field name is provided, the builder samples
+ * data values to infer the encoding type (quantitative, temporal, nominal).
+ */
+
+import type {
+  Annotation,
+  ChartSpec,
+  ChartType,
+  Chrome,
+  DarkMode,
+  DataRow,
+  Encoding,
+  EncodingChannel,
+  FieldType,
+  TableSpec,
+  ThemeConfig,
+} from '../types/spec';
+import type { ColumnConfig } from '../types/table';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** A field reference: either a plain string (field name) or a full EncodingChannel. */
+export type FieldRef = string | EncodingChannel;
+
+/** Common options shared by all chart builder functions. */
+export interface ChartBuilderOptions {
+  /** Color encoding: field name or full channel config for series differentiation. */
+  color?: FieldRef;
+  /** Size encoding: field name or full channel config. */
+  size?: FieldRef;
+  /** Editorial chrome (title, subtitle, source, etc.). */
+  chrome?: Chrome;
+  /** Data annotations. */
+  annotations?: Annotation[];
+  /** Whether the chart adapts to container width. Defaults to true. */
+  responsive?: boolean;
+  /** Theme configuration overrides. */
+  theme?: ThemeConfig;
+  /** Dark mode behavior. */
+  darkMode?: DarkMode;
+}
+
+/** Options for the dataTable builder. */
+export interface TableBuilderOptions {
+  /** Column definitions. Auto-generated from data keys if omitted. */
+  columns?: ColumnConfig[];
+  /** Field to use as a unique row identifier. */
+  rowKey?: string;
+  /** Editorial chrome. */
+  chrome?: Chrome;
+  /** Theme configuration overrides. */
+  theme?: ThemeConfig;
+  /** Dark mode behavior. */
+  darkMode?: DarkMode;
+  /** Enable client-side search/filter. */
+  search?: boolean;
+  /** Pagination configuration. */
+  pagination?: boolean | { pageSize: number };
+  /** Stick the first column during horizontal scroll. */
+  stickyFirstColumn?: boolean;
+  /** Compact mode. */
+  compact?: boolean;
+  /** Whether the table adapts to container width. */
+  responsive?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Type inference
+// ---------------------------------------------------------------------------
+
+/** ISO 8601 date patterns we recognize for temporal inference. */
+const ISO_DATE_RE = /^\d{4}(-\d{2}(-\d{2}(T\d{2}(:\d{2}(:\d{2})?)?)?)?)?$/;
+
+/**
+ * Infer the encoding field type from data values.
+ *
+ * Samples up to 20 values from the data array for the given field.
+ * - If all sampled values are numbers (or null/undefined), returns "quantitative".
+ * - If all sampled string values match ISO date patterns, returns "temporal".
+ * - Otherwise returns "nominal".
+ */
+export function inferFieldType(data: DataRow[], field: string): FieldType {
+  const sampleSize = Math.min(data.length, 20);
+  let hasNumber = false;
+  let hasDateString = false;
+  let hasOtherString = false;
+
+  for (let i = 0; i < sampleSize; i++) {
+    const value = data[i][field];
+
+    // Skip null/undefined
+    if (value == null) continue;
+
+    if (typeof value === 'number') {
+      hasNumber = true;
+    } else if (typeof value === 'string') {
+      if (ISO_DATE_RE.test(value) && !Number.isNaN(Date.parse(value))) {
+        hasDateString = true;
+      } else {
+        hasOtherString = true;
+      }
+    } else if (value instanceof Date) {
+      hasDateString = true;
+    } else {
+      hasOtherString = true;
+    }
+  }
+
+  // Numbers-only: quantitative
+  if (hasNumber && !hasDateString && !hasOtherString) return 'quantitative';
+  // Date strings/Date objects only: temporal
+  if (hasDateString && !hasNumber && !hasOtherString) return 'temporal';
+  // Everything else: nominal
+  return 'nominal';
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a FieldRef into a full EncodingChannel.
+ * If the ref is a string, infer the type from data.
+ */
+function resolveField(ref: FieldRef, data: DataRow[]): EncodingChannel {
+  if (typeof ref === 'string') {
+    return { field: ref, type: inferFieldType(data, ref) };
+  }
+  return ref;
+}
+
+/** Build the encoding object from resolved channels. */
+function buildEncoding(
+  channels: { x?: EncodingChannel; y?: EncodingChannel },
+  options?: ChartBuilderOptions,
+  data?: DataRow[],
+): Encoding {
+  const encoding: Encoding = { ...channels };
+  if (options?.color && data) {
+    encoding.color = resolveField(options.color, data);
+  }
+  if (options?.size && data) {
+    encoding.size = resolveField(options.size, data);
+  }
+  return encoding;
+}
+
+/** Build a ChartSpec from the resolved pieces. */
+function buildChartSpec(
+  type: ChartType,
+  data: DataRow[],
+  encoding: Encoding,
+  options?: ChartBuilderOptions,
+): ChartSpec {
+  const spec: ChartSpec = { type, data, encoding };
+  if (options?.chrome) spec.chrome = options.chrome;
+  if (options?.annotations) spec.annotations = options.annotations;
+  if (options?.responsive !== undefined) spec.responsive = options.responsive;
+  if (options?.theme) spec.theme = options.theme;
+  if (options?.darkMode) spec.darkMode = options.darkMode;
+  return spec;
+}
+
+// ---------------------------------------------------------------------------
+// Builder functions
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a line chart spec.
+ *
+ * @param data - Array of data rows.
+ * @param x - X-axis field (typically temporal or ordinal).
+ * @param y - Y-axis field (typically quantitative).
+ * @param options - Optional color, size, chrome, annotations, theme, etc.
+ */
+export function lineChart(
+  data: DataRow[],
+  x: FieldRef,
+  y: FieldRef,
+  options?: ChartBuilderOptions,
+): ChartSpec {
+  const xChannel = resolveField(x, data);
+  const yChannel = resolveField(y, data);
+  const encoding = buildEncoding({ x: xChannel, y: yChannel }, options, data);
+  return buildChartSpec('line', data, encoding, options);
+}
+
+/**
+ * Create a bar chart spec (horizontal bars).
+ *
+ * Convention: category goes on y-axis, value on x-axis.
+ * The `category` param maps to y, `value` maps to x.
+ *
+ * @param data - Array of data rows.
+ * @param category - Category field (y-axis, nominal/ordinal).
+ * @param value - Value field (x-axis, quantitative).
+ * @param options - Optional color, size, chrome, annotations, theme, etc.
+ */
+export function barChart(
+  data: DataRow[],
+  category: FieldRef,
+  value: FieldRef,
+  options?: ChartBuilderOptions,
+): ChartSpec {
+  const categoryChannel = resolveField(category, data);
+  const valueChannel = resolveField(value, data);
+
+  // Bar charts: category on y, value on x
+  const encoding = buildEncoding({ x: valueChannel, y: categoryChannel }, options, data);
+  return buildChartSpec('bar', data, encoding, options);
+}
+
+/**
+ * Create a column chart spec (vertical columns).
+ *
+ * @param data - Array of data rows.
+ * @param x - X-axis field (category or temporal).
+ * @param y - Y-axis field (quantitative value).
+ * @param options - Optional color, size, chrome, annotations, theme, etc.
+ */
+export function columnChart(
+  data: DataRow[],
+  x: FieldRef,
+  y: FieldRef,
+  options?: ChartBuilderOptions,
+): ChartSpec {
+  const xChannel = resolveField(x, data);
+  const yChannel = resolveField(y, data);
+  const encoding = buildEncoding({ x: xChannel, y: yChannel }, options, data);
+  return buildChartSpec('column', data, encoding, options);
+}
+
+/**
+ * Create a pie chart spec.
+ *
+ * Convention: category maps to the color channel, value maps to y.
+ * Pie charts have no x-axis.
+ *
+ * @param data - Array of data rows.
+ * @param category - Category field (color channel, nominal).
+ * @param value - Value field (y channel, quantitative).
+ * @param options - Optional chrome, annotations, theme, etc.
+ *                  Note: color option is ignored since category is used for color.
+ */
+export function pieChart(
+  data: DataRow[],
+  category: FieldRef,
+  value: FieldRef,
+  options?: ChartBuilderOptions,
+): ChartSpec {
+  const categoryChannel = resolveField(category, data);
+  const valueChannel = resolveField(value, data);
+
+  // Pie charts: value on y, category on color (no x-axis)
+  const encoding: Encoding = {
+    y: valueChannel,
+    color: categoryChannel,
+  };
+  if (options?.size && data) {
+    encoding.size = resolveField(options.size, data);
+  }
+
+  return buildChartSpec('pie', data, encoding, options);
+}
+
+/**
+ * Create an area chart spec.
+ *
+ * @param data - Array of data rows.
+ * @param x - X-axis field (typically temporal or ordinal).
+ * @param y - Y-axis field (typically quantitative).
+ * @param options - Optional color, size, chrome, annotations, theme, etc.
+ */
+export function areaChart(
+  data: DataRow[],
+  x: FieldRef,
+  y: FieldRef,
+  options?: ChartBuilderOptions,
+): ChartSpec {
+  const xChannel = resolveField(x, data);
+  const yChannel = resolveField(y, data);
+  const encoding = buildEncoding({ x: xChannel, y: yChannel }, options, data);
+  return buildChartSpec('area', data, encoding, options);
+}
+
+/**
+ * Create a donut chart spec.
+ *
+ * Convention: category maps to the color channel, value maps to y.
+ * Donut charts have no x-axis.
+ *
+ * @param data - Array of data rows.
+ * @param category - Category field (color channel, nominal).
+ * @param value - Value field (y channel, quantitative).
+ * @param options - Optional chrome, annotations, theme, etc.
+ *                  Note: color option is ignored since category is used for color.
+ */
+export function donutChart(
+  data: DataRow[],
+  category: FieldRef,
+  value: FieldRef,
+  options?: ChartBuilderOptions,
+): ChartSpec {
+  const categoryChannel = resolveField(category, data);
+  const valueChannel = resolveField(value, data);
+
+  const encoding: Encoding = {
+    y: valueChannel,
+    color: categoryChannel,
+  };
+  if (options?.size && data) {
+    encoding.size = resolveField(options.size, data);
+  }
+
+  return buildChartSpec('donut', data, encoding, options);
+}
+
+/**
+ * Create a dot chart spec (strip plot / dot plot).
+ *
+ * @param data - Array of data rows.
+ * @param x - X-axis field (quantitative or temporal).
+ * @param y - Y-axis field (nominal/categorical grouping).
+ * @param options - Optional color, size, chrome, annotations, theme, etc.
+ */
+export function dotChart(
+  data: DataRow[],
+  x: FieldRef,
+  y: FieldRef,
+  options?: ChartBuilderOptions,
+): ChartSpec {
+  const xChannel = resolveField(x, data);
+  const yChannel = resolveField(y, data);
+  const encoding = buildEncoding({ x: xChannel, y: yChannel }, options, data);
+  return buildChartSpec('dot', data, encoding, options);
+}
+
+/**
+ * Create a scatter chart spec.
+ *
+ * @param data - Array of data rows.
+ * @param x - X-axis field (quantitative).
+ * @param y - Y-axis field (quantitative).
+ * @param options - Optional color, size, chrome, annotations, theme, etc.
+ */
+export function scatterChart(
+  data: DataRow[],
+  x: FieldRef,
+  y: FieldRef,
+  options?: ChartBuilderOptions,
+): ChartSpec {
+  const xChannel = resolveField(x, data);
+  const yChannel = resolveField(y, data);
+  const encoding = buildEncoding({ x: xChannel, y: yChannel }, options, data);
+  return buildChartSpec('scatter', data, encoding, options);
+}
+
+/**
+ * Create a data table spec.
+ *
+ * If no columns are specified, auto-generates column configs from the
+ * keys of the first data row.
+ *
+ * @param data - Array of data rows.
+ * @param options - Column definitions, chrome, pagination, search, etc.
+ */
+export function dataTable(data: DataRow[], options?: TableBuilderOptions): TableSpec {
+  // Auto-generate columns from data keys if not provided
+  let columns = options?.columns;
+  if (!columns && data.length > 0) {
+    columns = Object.keys(data[0]).map((key): ColumnConfig => {
+      // Infer alignment from data type
+      const fieldType = inferFieldType(data, key);
+      const align = fieldType === 'quantitative' ? ('right' as const) : ('left' as const);
+
+      return {
+        key,
+        label: key,
+        align,
+      };
+    });
+  }
+
+  const spec: TableSpec = {
+    type: 'table',
+    data,
+    columns: columns ?? [],
+  };
+
+  if (options?.rowKey) spec.rowKey = options.rowKey;
+  if (options?.chrome) spec.chrome = options.chrome;
+  if (options?.theme) spec.theme = options.theme;
+  if (options?.darkMode) spec.darkMode = options.darkMode;
+  if (options?.search !== undefined) spec.search = options.search;
+  if (options?.pagination !== undefined) spec.pagination = options.pagination;
+  if (options?.stickyFirstColumn !== undefined) spec.stickyFirstColumn = options.stickyFirstColumn;
+  if (options?.compact !== undefined) spec.compact = options.compact;
+  if (options?.responsive !== undefined) spec.responsive = options.responsive;
+
+  return spec;
+}

package/src/index.ts

@@ -0,0 +1,129 @@
+/**
+ * @opendata-ai/openchart-core
+ *
+ * Core types, theme engine, color system, accessibility, and locale utilities
+ * for the openchart library.
+ *
+ * This package has no DOM dependencies and runs in any JavaScript environment.
+ */
+
+// ---------------------------------------------------------------------------
+// Type system (specs, layouts, marks, encoding, theme types)
+// ---------------------------------------------------------------------------
+
+export * from './types/index';
+
+// ---------------------------------------------------------------------------
+// Colors: palette collections, contrast utilities, color-blindness simulation
+//
+// Individual named palettes (SEQUENTIAL_BLUE, DIVERGING_RED_BLUE, etc.) are
+// available via SEQUENTIAL_PALETTES and DIVERGING_PALETTES or by direct import
+// from '@opendata-ai/openchart-core/src/colors/palettes'.
+// ---------------------------------------------------------------------------
+
+export type {
+  CategoricalPalette,
+  ColorBlindnessType,
+  DivergingPalette,
+  SequentialPalette,
+} from './colors/index';
+export {
+  CATEGORICAL_PALETTE,
+  checkPaletteDistinguishability,
+  contrastRatio,
+  DIVERGING_PALETTES,
+  findAccessibleColor,
+  meetsAA,
+  SEQUENTIAL_PALETTES,
+  simulateColorBlindness,
+} from './colors/index';
+
+// ---------------------------------------------------------------------------
+// Theme: defaults, resolution, dark-mode adaptation
+// ---------------------------------------------------------------------------
+
+export {
+  adaptColorForDarkMode,
+  adaptTheme,
+  DEFAULT_THEME,
+  resolveTheme,
+} from './theme/index';
+
+// ---------------------------------------------------------------------------
+// Layout: text measurement, chrome computation
+// ---------------------------------------------------------------------------
+
+export {
+  computeChrome,
+  estimateTextWidth,
+} from './layout/index';
+
+// ---------------------------------------------------------------------------
+// Responsive: breakpoints and layout strategies
+// ---------------------------------------------------------------------------
+
+export type {
+  AnnotationPosition,
+  AxisLabelDensity,
+  Breakpoint,
+  LabelMode,
+  LayoutStrategy,
+  LegendPosition,
+} from './responsive/index';
+export {
+  getBreakpoint,
+  getLayoutStrategy,
+} from './responsive/index';
+
+// ---------------------------------------------------------------------------
+// Labels: collision detection and resolution
+// ---------------------------------------------------------------------------
+
+export type {
+  LabelCandidate,
+  LabelPriority,
+} from './labels/index';
+export { resolveCollisions } from './labels/index';
+
+// ---------------------------------------------------------------------------
+// Locale: number and date formatting
+// ---------------------------------------------------------------------------
+
+export type { DateGranularity } from './locale/index';
+export {
+  abbreviateNumber,
+  formatDate,
+  formatNumber,
+} from './locale/index';
+
+// ---------------------------------------------------------------------------
+// Accessibility: alt text and ARIA label generation
+// ---------------------------------------------------------------------------
+
+export {
+  generateAltText,
+  generateAriaLabels,
+  generateDataTable,
+} from './accessibility/index';
+
+// ---------------------------------------------------------------------------
+// Helpers: spec construction builders
+// ---------------------------------------------------------------------------
+
+export type {
+  ChartBuilderOptions,
+  FieldRef,
+  TableBuilderOptions,
+} from './helpers/spec-builders';
+export {
+  areaChart,
+  barChart,
+  columnChart,
+  dataTable,
+  donutChart,
+  dotChart,
+  inferFieldType,
+  lineChart,
+  pieChart,
+  scatterChart,
+} from './helpers/spec-builders';