@opendata-ai/openchart-core 2.0.0

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@opendata-ai/openchart-core",
+  "version": "2.0.0",
+  "description": "Types, theme, colors, accessibility, and utilities for openchart",
+  "license": "Apache-2.0",
+  "author": "Riley Hilliard",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tryopendata/openchart.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/tryopendata/openchart#readme",
+  "bugs": "https://github.com/tryopendata/openchart/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./styles.css": "./dist/styles.css"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": [
+    "./dist/styles.css"
+  ],
+  "keywords": [
+    "chart",
+    "visualization",
+    "data-table",
+    "svg",
+    "typescript",
+    "d3",
+    "declarative"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "d3-color": "^3.1.0",
+    "d3-format": "^3.1.0",
+    "d3-time-format": "^4.1.0"
+  },
+  "devDependencies": {
+    "@types/d3-color": "^3.1.3",
+    "@types/d3-format": "^3.0.4",
+    "@types/d3-time-format": "^4.0.3"
+  }
+}

package/src/accessibility/__tests__/alt-text.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, it } from 'vitest';
+import type { ChartSpec } from '../../types/spec';
+import { generateAltText, generateDataTable } from '../alt-text';
+
+const lineSpec: ChartSpec = {
+  type: 'line',
+  data: [
+    { date: '2020-01-01', value: 10, country: 'US' },
+    { date: '2021-01-01', value: 20, country: 'US' },
+    { date: '2020-01-01', value: 15, country: 'UK' },
+    { date: '2021-01-01', value: 25, country: 'UK' },
+  ],
+  encoding: {
+    x: { field: 'date', type: 'temporal' },
+    y: { field: 'value', type: 'quantitative' },
+    color: { field: 'country', type: 'nominal' },
+  },
+  chrome: { title: 'GDP Growth Rate' },
+};
+
+const barSpec: ChartSpec = {
+  type: 'bar',
+  data: [
+    { category: 'A', value: 10 },
+    { category: 'B', value: 20 },
+    { category: 'C', value: 30 },
+  ],
+  encoding: {
+    x: { field: 'category', type: 'nominal' },
+    y: { field: 'value', type: 'quantitative' },
+  },
+};
+
+describe('generateAltText', () => {
+  it('includes chart type', () => {
+    const alt = generateAltText(lineSpec, lineSpec.data);
+    expect(alt).toContain('Line chart');
+  });
+
+  it('includes title when present', () => {
+    const alt = generateAltText(lineSpec, lineSpec.data);
+    expect(alt).toContain('GDP Growth Rate');
+  });
+
+  it('includes temporal range', () => {
+    const alt = generateAltText(lineSpec, lineSpec.data);
+    expect(alt).toContain('from 2020 to 2021');
+  });
+
+  it('includes series count and names', () => {
+    const alt = generateAltText(lineSpec, lineSpec.data);
+    expect(alt).toContain('2 series');
+    expect(alt).toContain('US');
+    expect(alt).toContain('UK');
+  });
+
+  it('includes data point count', () => {
+    const alt = generateAltText(lineSpec, lineSpec.data);
+    expect(alt).toContain('4 data points');
+  });
+
+  it('handles categorical x-axis', () => {
+    const alt = generateAltText(barSpec, barSpec.data);
+    expect(alt).toContain('Bar chart');
+    expect(alt).toContain('3 categories');
+  });
+
+  it('handles missing chrome gracefully', () => {
+    const alt = generateAltText(barSpec, barSpec.data);
+    expect(alt).toBeTruthy();
+    expect(alt).not.toContain('showing undefined');
+  });
+});
+
+describe('generateDataTable', () => {
+  it('includes headers as first row', () => {
+    const table = generateDataTable(lineSpec, lineSpec.data);
+    expect(table[0]).toEqual(['date', 'value', 'country']);
+  });
+
+  it('includes data rows', () => {
+    const table = generateDataTable(lineSpec, lineSpec.data);
+    expect(table).toHaveLength(5); // 1 header + 4 data rows
+    expect(table[1]).toEqual(['2020-01-01', 10, 'US']);
+  });
+
+  it('only includes encoded fields', () => {
+    const spec: ChartSpec = {
+      type: 'bar',
+      data: [{ category: 'A', value: 10, extra: 'ignored' }],
+      encoding: {
+        x: { field: 'category', type: 'nominal' },
+        y: { field: 'value', type: 'quantitative' },
+      },
+    };
+    const table = generateDataTable(spec, spec.data);
+    expect(table[0]).toEqual(['category', 'value']);
+    expect(table[1]).toEqual(['A', 10]);
+  });
+
+  it('returns empty for spec with no encoding fields', () => {
+    const spec: ChartSpec = {
+      type: 'pie',
+      data: [{ value: 10 }],
+      encoding: {},
+    };
+    const table = generateDataTable(spec, spec.data);
+    expect(table).toEqual([]);
+  });
+});

package/src/accessibility/__tests__/aria.test.ts

@@ -0,0 +1,125 @@
+import { describe, expect, it } from 'vitest';
+import type { Mark, MarkAria } from '../../types/layout';
+import { generateAriaLabels } from '../aria';
+
+const defaultAria: MarkAria = { label: 'test' };
+
+describe('generateAriaLabels', () => {
+  it('generates labels for line marks', () => {
+    const marks: Mark[] = [
+      {
+        type: 'line',
+        points: [
+          { x: 0, y: 0 },
+          { x: 10, y: 10 },
+        ],
+        stroke: '#333',
+        strokeWidth: 2,
+        seriesKey: 'US',
+        data: [],
+        aria: defaultAria,
+      },
+    ];
+
+    const labels = generateAriaLabels(marks);
+    expect(labels.get('mark-0')).toContain('Line series: US');
+    expect(labels.get('mark-0')).toContain('2 points');
+  });
+
+  it('generates labels for rect marks', () => {
+    const marks: Mark[] = [
+      {
+        type: 'rect',
+        x: 0,
+        y: 0,
+        width: 50,
+        height: 100,
+        fill: '#1b7fa3',
+        data: { category: 'Tech', value: 42 },
+        aria: defaultAria,
+      },
+    ];
+
+    const labels = generateAriaLabels(marks);
+    expect(labels.get('mark-0')).toContain('Data point');
+    expect(labels.get('mark-0')).toContain('category: Tech');
+    expect(labels.get('mark-0')).toContain('value: 42');
+  });
+
+  it('generates labels for arc marks', () => {
+    const marks: Mark[] = [
+      {
+        type: 'arc',
+        path: 'M...',
+        centroid: { x: 50, y: 50 },
+        innerRadius: 0,
+        outerRadius: 100,
+        startAngle: 0,
+        endAngle: Math.PI,
+        fill: '#e15759',
+        stroke: '#fff',
+        strokeWidth: 1,
+        data: { sector: 'Healthcare', percent: 25 },
+        aria: defaultAria,
+      },
+    ];
+
+    const labels = generateAriaLabels(marks);
+    expect(labels.get('mark-0')).toContain('Slice');
+    expect(labels.get('mark-0')).toContain('Healthcare');
+  });
+
+  it('generates labels for point marks', () => {
+    const marks: Mark[] = [
+      {
+        type: 'point',
+        cx: 100,
+        cy: 200,
+        r: 5,
+        fill: '#333',
+        stroke: '#333',
+        strokeWidth: 1,
+        data: { x: 10, y: 20 },
+        aria: defaultAria,
+      },
+    ];
+
+    const labels = generateAriaLabels(marks);
+    expect(labels.get('mark-0')).toContain('Data point');
+    expect(labels.get('mark-0')).toContain('x: 10');
+  });
+
+  it('handles empty marks array', () => {
+    const labels = generateAriaLabels([]);
+    expect(labels.size).toBe(0);
+  });
+
+  it('handles multiple marks with sequential keys', () => {
+    const marks: Mark[] = [
+      {
+        type: 'rect',
+        x: 0,
+        y: 0,
+        width: 10,
+        height: 10,
+        fill: '#333',
+        data: { a: 1 },
+        aria: defaultAria,
+      },
+      {
+        type: 'rect',
+        x: 20,
+        y: 0,
+        width: 10,
+        height: 10,
+        fill: '#666',
+        data: { a: 2 },
+        aria: defaultAria,
+      },
+    ];
+
+    const labels = generateAriaLabels(marks);
+    expect(labels.has('mark-0')).toBe(true);
+    expect(labels.has('mark-1')).toBe(true);
+  });
+});

package/src/accessibility/alt-text.ts

@@ -0,0 +1,120 @@
+/**
+ * Automatic alt text generation for chart accessibility.
+ *
+ * Produces human-readable descriptions of chart content for screen readers
+ * and a tabular fallback for data access.
+ */
+
+import type { ChartSpec, DataRow } from '../types/spec';
+
+// ---------------------------------------------------------------------------
+// Alt text generation
+// ---------------------------------------------------------------------------
+
+/** Friendly display names for chart types. */
+const CHART_TYPE_NAMES: Record<string, string> = {
+  line: 'Line chart',
+  area: 'Area chart',
+  bar: 'Bar chart',
+  column: 'Column chart',
+  pie: 'Pie chart',
+  donut: 'Donut chart',
+  dot: 'Dot plot',
+  scatter: 'Scatter plot',
+};
+
+/**
+ * Generate alt text describing a chart's content.
+ *
+ * Produces a description like:
+ * "Line chart showing GDP Growth Rate from 2020 to 2024 with 2 series (US, UK)"
+ *
+ * @param spec - The chart spec.
+ * @param data - The data array.
+ */
+export function generateAltText(spec: ChartSpec, data: DataRow[]): string {
+  const chartName = CHART_TYPE_NAMES[spec.type] ?? `${spec.type} chart`;
+  const parts: string[] = [chartName];
+
+  // Add title context if present
+  const title = spec.chrome?.title;
+  if (title) {
+    const titleText = typeof title === 'string' ? title : title.text;
+    parts.push(`showing ${titleText}`);
+  }
+
+  // Describe the data range
+  if (spec.encoding.x && data.length > 0) {
+    const field = spec.encoding.x.field;
+    const values = data.map((d) => d[field]).filter((v) => v != null);
+
+    if (values.length > 0) {
+      if (spec.encoding.x.type === 'temporal') {
+        const dates = values.map((v) => (v instanceof Date ? v : new Date(String(v))));
+        const validDates = dates.filter((d) => !Number.isNaN(d.getTime()));
+        if (validDates.length >= 2) {
+          validDates.sort((a, b) => a.getTime() - b.getTime());
+          const first = validDates[0].getUTCFullYear();
+          const last = validDates[validDates.length - 1].getUTCFullYear();
+          if (first !== last) {
+            parts.push(`from ${first} to ${last}`);
+          }
+        }
+      } else if (spec.encoding.x.type === 'nominal' || spec.encoding.x.type === 'ordinal') {
+        const uniqueValues = [...new Set(values.map(String))];
+        parts.push(`across ${uniqueValues.length} categories`);
+      }
+    }
+  }
+
+  // Describe series if color encoding is present
+  if (spec.encoding.color && data.length > 0) {
+    const colorField = spec.encoding.color.field;
+    const uniqueSeries = [...new Set(data.map((d) => String(d[colorField])).filter(Boolean))];
+    if (uniqueSeries.length > 0) {
+      parts.push(`with ${uniqueSeries.length} series (${uniqueSeries.join(', ')})`);
+    }
+  }
+
+  // Add data point count
+  parts.push(`(${data.length} data points)`);
+
+  return parts.join(' ');
+}
+
+// ---------------------------------------------------------------------------
+// Data table fallback
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate a tabular data fallback for screen readers.
+ *
+ * Returns a 2D array where the first row is headers and subsequent
+ * rows are data values. Only includes fields referenced in the encoding.
+ *
+ * @param spec - The chart spec.
+ * @param data - The data array.
+ */
+export function generateDataTable(spec: ChartSpec, data: DataRow[]): unknown[][] {
+  // Collect fields from encoding
+  const fields: string[] = [];
+  const encoding = spec.encoding;
+
+  if (encoding.x) fields.push(encoding.x.field);
+  if (encoding.y) fields.push(encoding.y.field);
+  if (encoding.color) fields.push(encoding.color.field);
+  if (encoding.size) fields.push(encoding.size.field);
+
+  // Deduplicate
+  const uniqueFields = [...new Set(fields)];
+
+  if (uniqueFields.length === 0) return [];
+
+  // Header row
+  const headers = uniqueFields;
+
+  // Data rows
+  const rows = data.map((row) => uniqueFields.map((field) => row[field] ?? ''));
+
+  return [headers, ...rows];
+}

package/src/accessibility/aria.ts

@@ -0,0 +1,73 @@
+/**
+ * ARIA label generation for individual marks.
+ *
+ * Produces per-mark labels for screen reader navigation, enabling
+ * users to explore data points individually.
+ */
+
+import type { Mark } from '../types/layout';
+
+/**
+ * Generate ARIA labels for a set of marks.
+ *
+ * Returns a Map keyed by a mark identifier (index-based) with
+ * descriptive labels like "Data point: US GDP 42 in 2020-01".
+ *
+ * @param marks - Array of mark objects from the compiled chart layout.
+ */
+export function generateAriaLabels(marks: Mark[]): Map<string, string> {
+  const labels = new Map<string, string>();
+
+  for (let i = 0; i < marks.length; i++) {
+    const mark = marks[i];
+    const key = `mark-${i}`;
+
+    switch (mark.type) {
+      case 'line': {
+        const series = mark.seriesKey ?? 'Series';
+        const pointCount = mark.points.length;
+        labels.set(key, `Line series: ${series} with ${pointCount} points`);
+        break;
+      }
+
+      case 'area': {
+        const series = mark.seriesKey ?? 'Area';
+        labels.set(key, `Area series: ${series}`);
+        break;
+      }
+
+      case 'rect': {
+        const dataEntries = Object.entries(mark.data).filter(([k]) => !k.startsWith('_'));
+        const description = dataEntries.map(([k, v]) => `${k}: ${formatValue(v)}`).join(', ');
+        labels.set(key, `Data point: ${description}`);
+        break;
+      }
+
+      case 'arc': {
+        const dataEntries = Object.entries(mark.data).filter(([k]) => !k.startsWith('_'));
+        const description = dataEntries.map(([k, v]) => `${k}: ${formatValue(v)}`).join(', ');
+        labels.set(key, `Slice: ${description}`);
+        break;
+      }
+
+      case 'point': {
+        const dataEntries = Object.entries(mark.data).filter(([k]) => !k.startsWith('_'));
+        const description = dataEntries.map(([k, v]) => `${k}: ${formatValue(v)}`).join(', ');
+        labels.set(key, `Data point: ${description}`);
+        break;
+      }
+    }
+  }
+
+  return labels;
+}
+
+/** Format a data value for use in an ARIA label. */
+function formatValue(value: unknown): string {
+  if (value == null) return 'N/A';
+  if (value instanceof Date) return value.toISOString().slice(0, 10);
+  if (typeof value === 'number') {
+    return Number.isInteger(value) ? String(value) : value.toFixed(2);
+  }
+  return String(value);
+}

package/src/accessibility/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Accessibility module barrel export.
+ */
+
+export { generateAltText, generateDataTable } from './alt-text';
+export { generateAriaLabels } from './aria';

package/src/colors/__tests__/colorblind.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'vitest';
+import { checkPaletteDistinguishability, simulateColorBlindness } from '../colorblind';
+
+describe('simulateColorBlindness', () => {
+  it('returns a valid hex color for protanopia', () => {
+    const result = simulateColorBlindness('#e15759', 'protanopia');
+    expect(result).toMatch(/^#[0-9a-f]{6}$/i);
+  });
+
+  it('returns a valid hex color for deuteranopia', () => {
+    const result = simulateColorBlindness('#59a14f', 'deuteranopia');
+    expect(result).toMatch(/^#[0-9a-f]{6}$/i);
+  });
+
+  it('returns a valid hex color for tritanopia', () => {
+    const result = simulateColorBlindness('#1b7fa3', 'tritanopia');
+    expect(result).toMatch(/^#[0-9a-f]{6}$/i);
+  });
+
+  it('pure grey remains close to grey under all types', () => {
+    const grey = '#808080';
+    for (const type of ['protanopia', 'deuteranopia', 'tritanopia'] as const) {
+      const sim = simulateColorBlindness(grey, type);
+      // Simulated grey should still be roughly grey (all channels similar)
+      const match = sim.match(/^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i);
+      expect(match).not.toBeNull();
+      if (match) {
+        const [r, g, b] = [parseInt(match[1], 16), parseInt(match[2], 16), parseInt(match[3], 16)];
+        // All channels should be within ~40 of each other
+        const max = Math.max(r, g, b);
+        const min = Math.min(r, g, b);
+        expect(max - min).toBeLessThan(40);
+      }
+    }
+  });
+
+  it('red and green become similar under protanopia', () => {
+    const simRed = simulateColorBlindness('#ff0000', 'protanopia');
+    const simGreen = simulateColorBlindness('#00ff00', 'protanopia');
+    // They should be more similar than the originals
+    // (we just verify they're both valid, the matrix math handles the rest)
+    expect(simRed).toMatch(/^#[0-9a-f]{6}$/i);
+    expect(simGreen).toMatch(/^#[0-9a-f]{6}$/i);
+  });
+});
+
+describe('checkPaletteDistinguishability', () => {
+  it('returns true for very different colors', () => {
+    expect(checkPaletteDistinguishability(['#ff0000', '#0000ff', '#ffffff'], 'protanopia')).toBe(
+      true,
+    );
+  });
+
+  it('returns false for near-identical colors', () => {
+    expect(
+      checkPaletteDistinguishability(['#ff0000', '#ff0200', '#ff0100'], 'protanopia', 30),
+    ).toBe(false);
+  });
+
+  it('handles single-color palettes (vacuously true)', () => {
+    expect(checkPaletteDistinguishability(['#ff0000'], 'deuteranopia')).toBe(true);
+  });
+});

package/src/colors/__tests__/contrast.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from 'vitest';
+import { contrastRatio, findAccessibleColor, meetsAA } from '../contrast';
+
+describe('contrastRatio', () => {
+  it('returns 21 for black on white', () => {
+    const ratio = contrastRatio('#000000', '#ffffff');
+    expect(ratio).toBeCloseTo(21, 0);
+  });
+
+  it('returns 1 for identical colors', () => {
+    const ratio = contrastRatio('#336699', '#336699');
+    expect(ratio).toBeCloseTo(1, 1);
+  });
+
+  it('is commutative (order does not matter)', () => {
+    const a = contrastRatio('#1b7fa3', '#ffffff');
+    const b = contrastRatio('#ffffff', '#1b7fa3');
+    expect(a).toBeCloseTo(b, 5);
+  });
+
+  it('computes known contrast ratios within tolerance', () => {
+    // White text on dark blue: should be high contrast
+    const ratio = contrastRatio('#ffffff', '#003366');
+    expect(ratio).toBeGreaterThan(8);
+  });
+});
+
+describe('meetsAA', () => {
+  it('black on white meets AA for normal text', () => {
+    expect(meetsAA('#000000', '#ffffff')).toBe(true);
+  });
+
+  it('light grey on white fails AA for normal text', () => {
+    expect(meetsAA('#cccccc', '#ffffff')).toBe(false);
+  });
+
+  it('uses 3:1 threshold for large text', () => {
+    // Find a color that has ratio between 3 and 4.5
+    // Medium grey on white has ~3.9:1 ratio
+    const ratio = contrastRatio('#767676', '#ffffff');
+    expect(ratio).toBeGreaterThanOrEqual(3);
+    expect(ratio).toBeLessThan(5);
+    // Should fail normal text but pass large text
+    expect(meetsAA('#767676', '#ffffff', true)).toBe(true);
+  });
+});
+
+describe('findAccessibleColor', () => {
+  it('returns the original color if already accessible', () => {
+    const result = findAccessibleColor('#000000', '#ffffff');
+    expect(result).toBe('#000000');
+  });
+
+  it('darkens a light color to meet contrast on white', () => {
+    const result = findAccessibleColor('#cccccc', '#ffffff');
+    const ratio = contrastRatio(result, '#ffffff');
+    expect(ratio).toBeGreaterThanOrEqual(4.5);
+  });
+
+  it('lightens a dark color to meet contrast on dark background', () => {
+    const result = findAccessibleColor('#333333', '#1a1a2e');
+    const ratio = contrastRatio(result, '#1a1a2e');
+    expect(ratio).toBeGreaterThanOrEqual(4.5);
+  });
+
+  it('respects custom target ratio', () => {
+    const result = findAccessibleColor('#aaaaaa', '#ffffff', 7);
+    const ratio = contrastRatio(result, '#ffffff');
+    expect(ratio).toBeGreaterThanOrEqual(7);
+  });
+});

package/src/colors/__tests__/palettes.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'vitest';
+import {
+  CATEGORICAL_PALETTE,
+  DIVERGING_PALETTES,
+  DIVERGING_RED_BLUE,
+  SEQUENTIAL_BLUE,
+  SEQUENTIAL_PALETTES,
+} from '../palettes';
+
+describe('palettes', () => {
+  it('categorical palette has 10 colors', () => {
+    expect(CATEGORICAL_PALETTE).toHaveLength(10);
+  });
+
+  it('categorical palette colors are valid hex', () => {
+    for (const color of CATEGORICAL_PALETTE) {
+      expect(color).toMatch(/^#[0-9a-f]{6}$/i);
+    }
+  });
+
+  it('sequential palettes have expected keys', () => {
+    expect(Object.keys(SEQUENTIAL_PALETTES)).toEqual(
+      expect.arrayContaining(['blue', 'green', 'orange', 'purple']),
+    );
+  });
+
+  it('sequential palettes have 6 stops each', () => {
+    for (const [_name, stops] of Object.entries(SEQUENTIAL_PALETTES)) {
+      expect(stops.length).toBeGreaterThanOrEqual(5);
+      expect(stops.length).toBeLessThanOrEqual(7);
+      // Verify all stops are hex
+      for (const stop of stops) {
+        expect(stop).toMatch(/^#[0-9a-f]{6}$/i);
+      }
+    }
+  });
+
+  it('diverging palettes have expected keys', () => {
+    expect(Object.keys(DIVERGING_PALETTES)).toEqual(
+      expect.arrayContaining(['redBlue', 'brownTeal']),
+    );
+  });
+
+  it('diverging palettes have 7 stops (neutral midpoint)', () => {
+    for (const stops of Object.values(DIVERGING_PALETTES)) {
+      expect(stops).toHaveLength(7);
+    }
+  });
+
+  it('named palette objects have matching names', () => {
+    expect(SEQUENTIAL_BLUE.name).toBe('blue');
+    expect(DIVERGING_RED_BLUE.name).toBe('redBlue');
+  });
+});