@opendata-ai/openchart-core 7.11.0 → 8.0.0-rc.2

package/src/accessibility/alt-text.ts

@@ -40,8 +40,46 @@ export function generateAltText(spec: ChartSpec, data: DataRow[]): string {
     parts.push(`showing ${titleText}`);
   }
 
+  // Waffle: name the unit framing. Per-category "x of N units" phrasing
+  // lives on the mark aria labels; the chart-level text carries the total.
+  if (markType === 'waffle') {
+    const units = markDef.units ?? 100;
+    parts.push(`dividing ${units} units`);
+  }
+
+  // Parliament: name the total seat count and the majority threshold, the two
+  // numbers a reader most wants. Per-party seat counts live on the seat marks'
+  // aria labels; this carries the overall framing.
+  if (markType === 'parliament') {
+    const valueField = spec.encoding.theta?.field ?? spec.encoding.y?.field;
+    if (valueField) {
+      const totalSeats = data.reduce((sum, d) => {
+        const v = Number(d[valueField]);
+        return sum + (Number.isFinite(v) && v > 0 ? v : 0);
+      }, 0);
+      if (totalSeats > 0) {
+        const majority = Math.floor(totalSeats / 2) + 1;
+        parts.push(`with ${totalSeats} seats, ${majority} needed for a majority`);
+      }
+    }
+  }
+
+  // Beeswarm: name the distribution fields (value axis + optional lane).
+  // Skips the generic x-axis description below, which would either say
+  // nothing (quantitative value axis) or repeat the lane count.
+  if (markType === 'beeswarm') {
+    const xIsValue = spec.encoding.x?.type === 'quantitative';
+    const valueField = xIsValue ? spec.encoding.x?.field : spec.encoding.y?.field;
+    const laneField = xIsValue ? spec.encoding.y?.field : spec.encoding.x?.field;
+    if (valueField) {
+      parts.push(
+        `plotting the distribution of ${valueField}${laneField ? ` by ${laneField}` : ''}`,
+      );
+    }
+  }
+
   // Describe the data range
-  if (spec.encoding.x && data.length > 0) {
+  if (spec.encoding.x && markType !== 'beeswarm' && data.length > 0) {
     const field = spec.encoding.x.field;
     const values = data.map((d) => d[field]).filter((v) => v != null);
 

package/src/accessibility/aria.ts

@@ -5,6 +5,7 @@
  * users to explore data points individually.
  */
 
+import { defaultNumberFormatter } from '../locale/format';
 import type { Mark } from '../types/layout';
 
 /**
@@ -62,12 +63,13 @@ export function generateAriaLabels(marks: Mark[]): Map<string, string> {
   return labels;
 }
 
-/** Format a data value for use in an ARIA label. */
+const ariaNumberFormatter = defaultNumberFormatter();
+
 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 ariaNumberFormatter(value);
   }
   return String(value);
 }

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

@@ -42,6 +42,18 @@ describe('simulateColorBlindness', () => {
     expect(simRed).toMatch(/^#[0-9a-f]{6}$/i);
     expect(simGreen).toMatch(/^#[0-9a-f]{6}$/i);
   });
+
+  it('achromatopsia collapses every color to a grey', () => {
+    for (const color of ['#e15759', '#59a14f', '#1b7fa3']) {
+      const sim = simulateColorBlindness(color, 'achromatopsia');
+      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)];
+        expect(Math.max(r, g, b) - Math.min(r, g, b)).toBeLessThanOrEqual(1);
+      }
+    }
+  });
 });
 
 describe('checkPaletteDistinguishability', () => {

package/src/colors/colorblind.ts

@@ -14,8 +14,8 @@ import { rgb } from 'd3-color';
 // Types
 // ---------------------------------------------------------------------------
 
-/** The three common types of color vision deficiency. */
-export type ColorBlindnessType = 'protanopia' | 'deuteranopia' | 'tritanopia';
+/** The four common types of color vision deficiency. */
+export type ColorBlindnessType = 'protanopia' | 'deuteranopia' | 'tritanopia' | 'achromatopsia';
 
 // ---------------------------------------------------------------------------
 // Simulation matrices
@@ -49,10 +49,19 @@ const TRITAN_MATRIX: Matrix3x3 = [
   [0.0, 0.475, 0.525],
 ];
 
+// Total color blindness: every channel collapses to Rec. 709 relative
+// luminance, computed in linear RGB like the other matrices.
+const ACHROMAT_MATRIX: Matrix3x3 = [
+  [0.2126, 0.7152, 0.0722],
+  [0.2126, 0.7152, 0.0722],
+  [0.2126, 0.7152, 0.0722],
+];
+
 const MATRICES: Record<ColorBlindnessType, Matrix3x3> = {
   protanopia: PROTAN_MATRIX,
   deuteranopia: DEUTAN_MATRIX,
   tritanopia: TRITAN_MATRIX,
+  achromatopsia: ACHROMAT_MATRIX,
 };
 
 // ---------------------------------------------------------------------------

package/src/colors/contrast.ts

@@ -28,6 +28,17 @@ export function relativeLuminance(color: string): number {
 // Public API
 // ---------------------------------------------------------------------------
 
+/**
+ * Check whether a color string parses to a fully opaque color.
+ * Contrast ratios are only meaningful against opaque backgrounds; the
+ * default chart background ('transparent') defers to the host page and
+ * can't be checked at compile time.
+ */
+export function isOpaqueColor(color: string): boolean {
+  const c = rgb(color);
+  return c != null && !Number.isNaN(c.r) && c.opacity === 1;
+}
+
 /**
  * Compute the WCAG contrast ratio between two colors.
  * Returns a value between 1 (identical) and 21 (black on white).

package/src/colors/index.ts

@@ -8,7 +8,13 @@ export {
   simulateColorBlindness,
 } from './colorblind';
 
-export { contrastRatio, findAccessibleColor, meetsAA, pickLabelColor } from './contrast';
+export {
+  contrastRatio,
+  findAccessibleColor,
+  isOpaqueColor,
+  meetsAA,
+  pickLabelColor,
+} from './contrast';
 export type {
   CategoricalPalette,
   DivergingPalette,
@@ -20,9 +26,11 @@ export {
   DIVERGING_BROWN_TEAL,
   DIVERGING_PALETTES,
   DIVERGING_RED_BLUE,
+  resolveSchemeName,
   SEQUENTIAL_BLUE,
   SEQUENTIAL_GREEN,
   SEQUENTIAL_ORANGE,
   SEQUENTIAL_PALETTES,
   SEQUENTIAL_PURPLE,
+  SUPPORTED_SCHEME_NAMES,
 } from './palettes';

package/src/colors/palettes.ts

@@ -157,3 +157,50 @@ export const DIVERGING_PALETTES: Record<string, string[]> = {
   redBlue: [...DIVERGING_RED_BLUE.stops],
   brownTeal: [...DIVERGING_BROWN_TEAL.stops],
 };
+
+// ---------------------------------------------------------------------------
+// Scheme name resolution (spec-level `scale: { scheme }` support)
+// ---------------------------------------------------------------------------
+
+/**
+ * Vega-Lite scheme-name aliases mapped onto the openchart palettes.
+ * Keys are lowercase. Only schemes with a faithful local equivalent are
+ * aliased; unknown names fail validation with the supported list rather
+ * than silently substituting an unrelated ramp.
+ */
+const VL_SCHEME_ALIASES: Record<string, string> = {
+  blues: 'blue',
+  greens: 'green',
+  oranges: 'orange',
+  purples: 'purple',
+  teals: 'teal',
+  redblue: 'redBlue',
+  brownteal: 'brownTeal',
+  // ColorBrewer BrBG, which brownTeal mirrors
+  brownbluegreen: 'brownTeal',
+  category10: 'categorical',
+  tableau10: 'categorical',
+};
+
+/**
+ * Resolve a scheme name to its palette stops. Accepts openchart palette names
+ * (blue, green, orange, purple, teal, redBlue, brownTeal, categorical) and
+ * common Vega-Lite aliases (blues, greens, ..., redblue, category10).
+ * Case-insensitive. Returns undefined for unknown names.
+ */
+export function resolveSchemeName(name: string): string[] | undefined {
+  const canonical =
+    SEQUENTIAL_PALETTES[name] || DIVERGING_PALETTES[name]
+      ? name
+      : (VL_SCHEME_ALIASES[name.toLowerCase()] ?? name.toLowerCase());
+  if (canonical === 'categorical') return [...CATEGORICAL_PALETTE];
+  return SEQUENTIAL_PALETTES[canonical] ?? DIVERGING_PALETTES[canonical];
+}
+
+/** Scheme names accepted by `scale: { scheme }`, for validation messages. */
+export const SUPPORTED_SCHEME_NAMES: readonly string[] = [
+  ...Object.keys(SEQUENTIAL_PALETTES),
+  ...Object.keys(DIVERGING_PALETTES),
+  'categorical',
+  ...Object.keys(VL_SCHEME_ALIASES),
+];

package/src/helpers/__tests__/deep-merge.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'vitest';
+import { deepMergeSpec } from '../deep-merge';
+
+describe('deepMergeSpec', () => {
+  it('merges nested plain objects key by key', () => {
+    const base = { encoding: { x: { field: 'a' }, y: { field: 'b' } }, chrome: { title: 'X' } };
+    const patch = { encoding: { y: { field: 'c' } } };
+    expect(deepMergeSpec(base, patch)).toEqual({
+      encoding: { x: { field: 'a' }, y: { field: 'c' } },
+      chrome: { title: 'X' },
+    });
+  });
+
+  it('replaces arrays wholesale rather than merging by index', () => {
+    const base = { annotations: [{ type: 'text', text: 'old' }] };
+    const patch = { annotations: [{ type: 'refline', y: 5 }] };
+    expect(deepMergeSpec(base, patch)).toEqual({
+      annotations: [{ type: 'refline', y: 5 }],
+    });
+  });
+
+  it('leaves target untouched when patch value is undefined', () => {
+    const base = { chrome: { title: 'X' } };
+    expect(deepMergeSpec(base, { chrome: { title: undefined } })).toEqual({
+      chrome: { title: 'X' },
+    });
+  });
+
+  it('overwrites with null explicitly', () => {
+    const base = { encoding: { color: { field: 'a' } } };
+    expect(deepMergeSpec(base, { encoding: { color: null } })).toEqual({
+      encoding: { color: null },
+    });
+  });
+
+  it('does not mutate the source objects', () => {
+    const base = { encoding: { x: { field: 'a' } } };
+    const patch = { encoding: { x: { field: 'b' } } };
+    const result = deepMergeSpec(base, patch);
+    expect(result).not.toBe(base);
+    expect(base.encoding.x.field).toBe('a');
+  });
+
+  it('cumulative patches compose left to right', () => {
+    let spec: Record<string, unknown> = { mark: 'line', encoding: { y: { field: 'a' } } };
+    const patches = [{ chrome: { title: 'Step 1' } }, { encoding: { y: { field: 'b' } } }];
+    for (const p of patches) spec = deepMergeSpec(spec, p);
+    expect(spec).toEqual({
+      mark: 'line',
+      encoding: { y: { field: 'b' } },
+      chrome: { title: 'Step 1' },
+    });
+  });
+});

package/src/helpers/__tests__/spec-builders.test.ts

@@ -203,12 +203,12 @@ describe('columnChart', () => {
 // ---------------------------------------------------------------------------
 
 describe('pieChart', () => {
-  it('maps category to color channel and value to y', () => {
+  it('maps category to color channel and value to theta', () => {
     const spec = pieChart(categoricalData, 'name', 'count');
 
     expect(spec.mark).toBe('arc');
-    // Arc (pie) convention: value on y, category on color, no x
-    expect(spec.encoding.y).toEqual({ field: 'count', type: 'quantitative' });
+    // Arc (pie) convention: value on theta (canonical), category on color, no x
+    expect(spec.encoding.theta).toEqual({ field: 'count', type: 'quantitative' });
     expect(spec.encoding.color).toEqual({ field: 'name', type: 'nominal' });
     expect(spec.encoding.x).toBeUndefined();
   });

package/src/helpers/deep-merge.ts

@@ -0,0 +1,29 @@
+/**
+ * Deep merge for applying partial patches onto a spec-shaped object.
+ *
+ * Used by the scrollytelling story layer (`vanilla/story`) to apply
+ * cumulative deep-partial spec patches onto a base spec. Arrays REPLACE
+ * rather than merge element-by-element: predictable behavior for things
+ * like `annotations` or `data`, where index-wise merging would silently
+ * produce nonsense. Plain objects merge key-by-key, recursively.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: recursive object merge requires dynamic typing
+export function deepMergeSpec(target: any, source: any): any {
+  if (source === undefined) return target;
+  if (source === null) return source;
+  if (
+    typeof source !== 'object' ||
+    Array.isArray(source) ||
+    typeof target !== 'object' ||
+    target === null ||
+    Array.isArray(target)
+  ) {
+    return source;
+  }
+
+  const result = { ...target };
+  for (const key of Object.keys(source)) {
+    result[key] = deepMergeSpec(target[key], source[key]);
+  }
+  return result;
+}

package/src/helpers/spec-builders.ts

@@ -250,12 +250,12 @@ export function columnChart(
 /**
  * Create a pie chart spec.
  *
- * Convention: category maps to the color channel, value maps to y.
+ * Convention: category maps to the color channel, value maps to theta.
  * 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 value - Value field (theta channel, quantitative).
  * @param options - Optional chrome, annotations, theme, etc.
  *                  Note: color option is ignored since category is used for color.
  */
@@ -268,9 +268,9 @@ export function pieChart(
   const categoryChannel = resolveField(category, data);
   const valueChannel = resolveField(value, data);
 
-  // Pie charts: value on y, category on color (no x-axis)
+  // Pie charts: value on theta (canonical in v8), category on color (no x-axis)
   const encoding: Encoding = {
-    y: valueChannel,
+    theta: valueChannel,
     color: categoryChannel,
   };
   if (options?.size && data) {
@@ -303,12 +303,12 @@ export function areaChart(
 /**
  * Create a donut chart spec.
  *
- * Convention: category maps to the color channel, value maps to y.
+ * Convention: category maps to the color channel, value maps to theta.
  * 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 value - Value field (theta channel, quantitative).
  * @param options - Optional chrome, annotations, theme, etc.
  *                  Note: color option is ignored since category is used for color.
  */
@@ -322,7 +322,7 @@ export function donutChart(
   const valueChannel = resolveField(value, data);
 
   const encoding: Encoding = {
-    y: valueChannel,
+    theta: valueChannel,
     color: categoryChannel,
   };
   if (options?.size && data) {

package/src/index.ts

@@ -33,9 +33,12 @@ export {
   contrastRatio,
   DIVERGING_PALETTES,
   findAccessibleColor,
+  isOpaqueColor,
   meetsAA,
   pickLabelColor,
+  resolveSchemeName,
   SEQUENTIAL_PALETTES,
+  SUPPORTED_SCHEME_NAMES,
   simulateColorBlindness,
 } from './colors/index';
 
@@ -65,6 +68,8 @@ export {
   COMPACT_WIDTH,
   computeChrome,
   estimateTextWidth,
+  FOOTNOTE_LINE_HEIGHT,
+  footnoteBandHeight,
   heuristicMeasure,
   resolveMeasurer,
   textAscent,
@@ -110,11 +115,13 @@ export {
   MAX_LEFT_LABEL_FRACTION_DEFAULT,
   MAX_LEFT_LABEL_FRACTION_MEDIUM,
   MAX_LEFT_LABEL_FRACTION_MEDIUM_MAX,
+  maxRotatedLabelWidth,
   NARROW_VIEWPORT_MAX,
   TICK_LABEL_OFFSET,
   TICK_LINE_HEIGHT_FACTOR,
   TOP_PAD_EXTRA_NARROW,
   TOP_PAD_NARROW_MAX,
+  truncateRotatedLabel,
   X_AXIS_BAND_HEIGHT,
   X_AXIS_ROTATED_EXTENT_CAP,
   X_AXIS_TITLE_BAND,
@@ -143,13 +150,21 @@ export {
 // Locale: number and date formatting
 // ---------------------------------------------------------------------------
 
-export type { DateGranularity } from './locale/index';
+export type { DateGranularity, FieldFormatContext, NumberFormatter } from './locale/index';
 export {
   abbreviateNumber,
+  buildCompactStepFormatter,
   buildD3Formatter,
   buildTemporalFormatter,
+  computeFieldFormatContext,
+  defaultNumberFormatter,
+  formatCurrency,
   formatDate,
   formatNumber,
+  formatOrdinal,
+  formatPercent,
+  isYearContext,
+  resolveNumberFormatter,
 } from './locale/index';
 
 // ---------------------------------------------------------------------------
@@ -185,3 +200,16 @@ export {
   scatterChart,
   tileMap,
 } from './helpers/spec-builders';
+
+// ---------------------------------------------------------------------------
+// Helpers: deep-merge for spec patches (used by vanilla/story)
+// ---------------------------------------------------------------------------
+
+export { deepMergeSpec } from './helpers/deep-merge';
+
+// ---------------------------------------------------------------------------
+// CSS token definitions (single source of truth for tokens.css / dark.css)
+// ---------------------------------------------------------------------------
+
+export type { CssTokenDef } from './styles/token-definitions';
+export { CSS_TOKEN_ROOT_SELECTORS, CSS_TOKENS, cssTokenDefault } from './styles/token-definitions';

package/src/labels/collision.ts

@@ -183,6 +183,7 @@ export function resolveCollisions(
               to: { x: label.anchorX, y: label.anchorY },
               stroke: label.style.fill,
               style: 'straight' as const,
+              arrow: false,
             }
           : undefined,
       });

package/src/layout/chrome.ts

@@ -156,6 +156,30 @@ function estimateLineCount(
 // Public API
 // ---------------------------------------------------------------------------
 
+/**
+ * Line-height multiplier for the auto-thinning footnote list.
+ *
+ * Exported because the chrome renderer steps each footnote line down by it
+ * while the band height below is computed from it -- the two have to agree, or
+ * the last line drifts outside the band that was reserved for it.
+ */
+export const FOOTNOTE_LINE_HEIGHT = 1.3;
+/** Gap below the footnote list, separating it from the source row. */
+const FOOTNOTE_BAND_GAP = 4;
+
+/**
+ * Vertical space a footnote list of `count` lines occupies below the plot.
+ *
+ * Single source of truth, deliberately: the engine reserves this band in the
+ * bottom margin, the chrome renderer shifts the source row down by it, and the
+ * brand watermark shifts by it too. When those three disagree the footnotes
+ * land on top of the watermark, which is exactly the bug this centralizes away.
+ */
+export function footnoteBandHeight(count: number, theme: ResolvedTheme): number {
+  if (count <= 0) return 0;
+  return count * theme.fonts.sizes.small * FOOTNOTE_LINE_HEIGHT + FOOTNOTE_BAND_GAP;
+}
+
 /**
  * Compute resolved chrome layout from a Chrome spec and resolved theme.
  *

package/src/layout/index.ts

@@ -2,7 +2,7 @@
  * Layout module barrel export.
  */
 
-export { computeChrome } from './chrome';
+export { computeChrome, FOOTNOTE_LINE_HEIGHT, footnoteBandHeight } from './chrome';
 export {
   BRAND_FONT_SIZE,
   BRAND_MIN_WIDTH,