@opendata-ai/openchart-engine 7.6.1 → 7.7.0

package/src/annotations/thinning.ts

@@ -0,0 +1,116 @@
+/**
+ * Annotation auto-thinning: demotes text annotations that can't fit without
+ * overlap to numbered dot markers with footnote text below the chart.
+ *
+ * Single deterministic pass: run collision resolution once at the full chart
+ * area, then greedily place by priority. Annotations that overlap an
+ * already-placed one get demoted. No iterative layout convergence.
+ */
+
+import type {
+  Annotation,
+  AnnotationFootnote,
+  Rect,
+  ResolvedAnnotation,
+  TextAnnotation,
+} from '@opendata-ai/openchart-core';
+import { detectCollision } from '@opendata-ai/openchart-core';
+import { type AnnotationMeasureTextFn, estimateLabelBounds } from './geometry';
+
+export interface ThinningResult {
+  annotations: ResolvedAnnotation[];
+  footnotes: AnnotationFootnote[];
+}
+
+/**
+ * Apply auto-thinning to resolved annotations. Text annotations that still
+ * overlap after collision resolution are demoted to footnote markers.
+ *
+ * Priority ordering: annotations with lower `priority` values are kept in
+ * place first. When priority is equal (or omitted), spec order wins (earlier
+ * annotations are kept). Non-text annotations are never thinned.
+ *
+ * Explicit `responsive: false` on an annotation exempts it from thinning
+ * (it is always placed first and never demoted).
+ *
+ * @param annotations - Resolved annotations (text + range + refline, in spec order
+ *   minus any that were skipped by `computeAnnotations`).
+ * @param specs - The full spec annotations array, index-aligned with `annotations`.
+ *   Non-text specs are ignored; text specs provide `priority` and `responsive`.
+ */
+export function thinAnnotations(
+  annotations: ResolvedAnnotation[],
+  specs: Annotation[],
+  measure: AnnotationMeasureTextFn,
+): ThinningResult {
+  if (annotations.length <= 1) {
+    return { annotations, footnotes: [] };
+  }
+
+  // Build index pairs: (resolved, spec, original index).
+  // Only text specs carry priority/responsive; non-text specs are ignored.
+  const entries = annotations.map((a, i) => ({
+    resolved: a,
+    spec: i < specs.length && specs[i].type === 'text' ? (specs[i] as TextAnnotation) : undefined,
+    index: i,
+  }));
+
+  // Separate pinned (responsive: false) from candidates
+  const pinned: typeof entries = [];
+  const candidates: typeof entries = [];
+  for (const entry of entries) {
+    if (entry.resolved.type !== 'text' || !entry.resolved.label) {
+      pinned.push(entry);
+    } else if (entry.spec?.responsive === false) {
+      pinned.push(entry);
+    } else {
+      candidates.push(entry);
+    }
+  }
+
+  // Sort candidates by priority (lower first), then by spec order
+  candidates.sort((a, b) => {
+    const pa = a.spec?.priority ?? Number.MAX_SAFE_INTEGER;
+    const pb = b.spec?.priority ?? Number.MAX_SAFE_INTEGER;
+    if (pa !== pb) return pa - pb;
+    return a.index - b.index;
+  });
+
+  // Place pinned annotations first (they're always kept)
+  const placedBounds: Rect[] = [];
+  for (const entry of pinned) {
+    if (entry.resolved.type === 'text' && entry.resolved.label) {
+      const bounds = entry.resolved.bounds ?? estimateLabelBounds(entry.resolved.label, measure);
+      placedBounds.push(bounds);
+    }
+  }
+
+  // Greedily place candidates; demote overlapping ones to footnotes
+  const footnotes: AnnotationFootnote[] = [];
+
+  for (const entry of candidates) {
+    const bounds = entry.resolved.bounds ?? estimateLabelBounds(entry.resolved.label!, measure);
+
+    if (bounds.width <= 0 || bounds.height <= 0) {
+      placedBounds.push(bounds);
+      continue;
+    }
+
+    const overlaps = placedBounds.some(
+      (pb) => pb.width > 0 && pb.height > 0 && detectCollision(bounds, pb),
+    );
+
+    if (overlaps) {
+      const footnoteIndex = footnotes.length + 1;
+      footnotes.push({
+        index: footnoteIndex,
+        text: entry.resolved.label!.text,
+      });
+      entry.resolved.footnoteIndex = footnoteIndex;
+    } else {
+      placedBounds.push(bounds);
+    }
+  }
+
+  return { annotations, footnotes };
+}

package/src/barlist/compile-barlist.ts

@@ -258,6 +258,7 @@ export function compileBarList(spec: unknown, options: CompileOptions): BarListL
       fontWeight: VALUE_FONT_WEIGHT,
       fill: valueColor,
       lineHeight: 1.4,
+      fontVariant: 'tabular-nums',
     };
 
     const rowMark: BarListRowMark = {

package/src/charts/bar/labels.ts

@@ -227,6 +227,7 @@ export function computeBarLabels(
         lineHeight: 1.2,
         textAnchor,
         dominantBaseline: 'central',
+        fontVariant: 'tabular-nums',
       },
     });
   }

package/src/charts/column/labels.ts

@@ -123,6 +123,7 @@ export function computeColumnLabels(
         fill: labelColor ?? getRepresentativeColor(mark.fill),
         lineHeight: 1.2,
         textAnchor: 'middle',
+        fontVariant: 'tabular-nums',
       },
     });
   }

package/src/charts/dot/labels.ts

@@ -99,6 +99,7 @@ export function computeDotLabels(
         lineHeight: 1.2,
         textAnchor: 'start',
         dominantBaseline: 'central',
+        fontVariant: 'tabular-nums',
       },
     });
   }

package/src/charts/line/area.ts

@@ -457,9 +457,23 @@ export function computeAreaMarks(
   const encoding = spec.encoding as Encoding;
   const yChannel = encoding.y;
 
+  let marks: AreaMark[];
   if (yChannel && isStacked(yChannel.stack)) {
-    return computeStackedArea(spec, scales, chartArea, darkMode);
+    marks = computeStackedArea(spec, scales, chartArea, darkMode);
+  } else {
+    marks = computeSingleArea(spec, scales, chartArea);
   }
 
-  return computeSingleArea(spec, scales, chartArea);
+  const highlight = spec.highlight ?? [];
+  if (highlight.length > 0) {
+    const highlightSet = new Set(highlight);
+    marks.sort((a, b) => {
+      const aMuted = a.seriesKey != null && !highlightSet.has(a.seriesKey);
+      const bMuted = b.seriesKey != null && !highlightSet.has(b.seriesKey);
+      if (aMuted === bMuted) return 0;
+      return aMuted ? -1 : 1;
+    });
+  }
+
+  return marks;
 }

package/src/charts/line/compute.ts

@@ -67,7 +67,10 @@ export function computeLineMarks(
   const colorField = isSequentialColor ? undefined : colorEnc?.field;
   const sequentialColorField = isSequentialColor ? colorEnc.field : undefined;
   const groups = groupByField(spec.data, colorField);
-  const marks: (LineMark | PointMark)[] = [];
+  const mutedMarks: (LineMark | PointMark)[] = [];
+  const highlightedMarks: (LineMark | PointMark)[] = [];
+  const highlight = spec.highlight ?? [];
+  const highlightActive = highlight.length > 0;
 
   for (const [seriesKey, rows] of groups) {
     // For sequential color, use a mid-range color for the line stroke
@@ -165,6 +168,13 @@ export function computeLineMarks(
     const seriesStyleKey = seriesKey === '__default__' ? undefined : seriesKey;
     const styleOverride = seriesStyleKey ? spec.seriesStyles?.[seriesStyleKey] : undefined;
 
+    const isMuted = highlightActive && !highlight.includes(seriesKey);
+    let resolvedStrokeWidth =
+      styleOverride?.strokeWidth ?? spec.markDef.strokeWidth ?? DEFAULT_STROKE_WIDTH;
+    if (isMuted) {
+      resolvedStrokeWidth = Math.max(1, resolvedStrokeWidth * 0.75);
+    }
+
     // Map lineStyle to SVG strokeDasharray
     let strokeDasharray: string | undefined;
     if (styleOverride?.lineStyle === 'dashed') strokeDasharray = '6 4';
@@ -178,7 +188,7 @@ export function computeLineMarks(
       points: allPoints,
       path: combinedPath,
       stroke: strokeColor,
-      strokeWidth: styleOverride?.strokeWidth ?? spec.markDef.strokeWidth ?? DEFAULT_STROKE_WIDTH,
+      strokeWidth: resolvedStrokeWidth,
       strokeDasharray,
       opacity: styleOverride?.opacity,
       seriesKey: seriesStyleKey,
@@ -187,7 +197,8 @@ export function computeLineMarks(
       aria,
     };
 
-    marks.push(lineMark);
+    const bucket = isMuted ? mutedMarks : highlightedMarks;
+    bucket.push(lineMark);
 
     // Emit PointMark objects when markDef.point is truthy, or when sequential
     // color is active (points carry the gradient since SVG paths are single-color).
@@ -232,20 +243,16 @@ export function computeLineMarks(
         // data point already exists on the line and gets described by the a11y
         // data table; the dot is purely visual.
         if (isSingleEndpoint) {
-          marks.push({
+          bucket.push({
             type: 'point',
             cx: p.x,
             cy: p.y,
-            // 3.5 reads as a deliberate terminator against the 2px sparkline
-            // line — smaller dots blur into the stroke at typical card sizes.
             r: 3.5,
             fill: strokeColor,
             stroke: 'transparent',
             strokeWidth: 0,
             fillOpacity: 1,
             data: p.row,
-            // No label: decorative marks render with aria-hidden="true" and
-            // don't participate in the accessible data table.
             aria: { decorative: true },
           });
           continue;
@@ -264,12 +271,12 @@ export function computeLineMarks(
             label: `Data point: ${xChannel.field}=${String(p.row[xChannel.field])}, ${yChannel.field}=${String(p.row[yChannel.field])}`,
           },
         };
-        marks.push(pointMark);
+        bucket.push(pointMark);
       }
     }
   }
 
-  return marks;
+  return [...mutedMarks, ...highlightedMarks];
 }
 
 // ---------------------------------------------------------------------------

package/src/charts/pie/labels.ts

@@ -99,6 +99,7 @@ export function computePieLabels(
         lineHeight: 1.2,
         textAnchor: isRight ? 'start' : 'end',
         dominantBaseline: 'central',
+        fontVariant: 'tabular-nums',
       },
     });
 

package/src/compile/__tests__/color-scale-range.test.ts

@@ -1,11 +1,13 @@
 import type { Encoding, ResolvedTheme } from '@opendata-ai/openchart-core';
-import { resolveTheme } from '@opendata-ai/openchart-core';
+import { ACHROMATIC_RAMP, adaptTheme, resolveTheme } from '@opendata-ai/openchart-core';
 import { scaleLinear, scaleOrdinal } from 'd3-scale';
 import { describe, expect, it } from 'vitest';
 import type { ResolvedScales } from '../../layout/scales';
 import { applyColorScaleRange } from '../color-scale-range';
 
 const theme: ResolvedTheme = resolveTheme();
+const accentNeutralTheme: ResolvedTheme = resolveTheme({ seriesStrategy: 'accent-neutral' });
+const darkAccentNeutralTheme: ResolvedTheme = adaptTheme(accentNeutralTheme);
 
 describe('applyColorScaleRange', () => {
   it('is a no-op when no color scale is present', () => {
@@ -77,3 +79,80 @@ describe('applyColorScaleRange', () => {
     expect(linear.range()).toEqual([firstSeq[0], firstSeq[firstSeq.length - 1]]);
   });
 });
+
+// ---------------------------------------------------------------------------
+// seriesStrategy
+// ---------------------------------------------------------------------------
+
+describe('applyColorScaleRange seriesStrategy', () => {
+  function makeOrdinalScales(domain: string[]): {
+    scales: ResolvedScales;
+    ordinal: ReturnType<typeof scaleOrdinal<string, string>>;
+  } {
+    const ordinal = scaleOrdinal<string, string>().domain(domain);
+    const scales: ResolvedScales = {
+      color: { scale: ordinal, type: 'ordinal', channel: 'color' },
+    };
+    return { scales, ordinal };
+  }
+
+  const encoding: Encoding = {
+    x: { field: 'x', type: 'nominal' },
+    y: { field: 'y', type: 'quantitative' },
+    color: { field: 'c', type: 'nominal' },
+  };
+
+  it('palette strategy assigns full categorical palette', () => {
+    const { scales, ordinal } = makeOrdinalScales(['a', 'b', 'c']);
+    applyColorScaleRange(scales, encoding, theme);
+    expect(ordinal.range()).toEqual(theme.colors.categorical);
+  });
+
+  it('accent-neutral: single series gets accent only', () => {
+    const { scales, ordinal } = makeOrdinalScales(['solo']);
+    applyColorScaleRange(scales, encoding, accentNeutralTheme);
+    expect(ordinal.range()).toEqual([accentNeutralTheme.colors.categorical[0]]);
+  });
+
+  it('accent-neutral: 3 series gets accent + neutral grays (darkest first on light surface)', () => {
+    const { scales, ordinal } = makeOrdinalScales(['a', 'b', 'c']);
+    applyColorScaleRange(scales, encoding, accentNeutralTheme);
+    const range = ordinal.range();
+    expect(range[0]).toBe(accentNeutralTheme.colors.categorical[0]);
+    expect(range[1]).toBe(ACHROMATIC_RAMP.fgFaint);
+    expect(range[2]).toBe(ACHROMATIC_RAMP.fgSubtle);
+  });
+
+  it('accent-neutral: dark surface reverses neutral prominence (brightest first)', () => {
+    const { scales, ordinal } = makeOrdinalScales(['a', 'b', 'c']);
+    applyColorScaleRange(scales, encoding, darkAccentNeutralTheme);
+    const range = ordinal.range();
+    expect(range[0]).toBe(darkAccentNeutralTheme.colors.categorical[0]);
+    expect(range[1]).toBe(ACHROMATIC_RAMP.fgMuted);
+    expect(range[2]).toBe(ACHROMATIC_RAMP.fgSubtle);
+  });
+
+  it('accent-neutral: 4 series is the last accent-neutral count', () => {
+    const { scales, ordinal } = makeOrdinalScales(['a', 'b', 'c', 'd']);
+    applyColorScaleRange(scales, encoding, accentNeutralTheme);
+    const range = ordinal.range();
+    expect(range[0]).toBe(accentNeutralTheme.colors.categorical[0]);
+    expect(range.slice(1)).toEqual([
+      ACHROMATIC_RAMP.fgFaint,
+      ACHROMATIC_RAMP.fgSubtle,
+      ACHROMATIC_RAMP.fgMuted,
+    ]);
+  });
+
+  it('accent-neutral: 5 series falls back to full palette', () => {
+    const { scales, ordinal } = makeOrdinalScales(['a', 'b', 'c', 'd', 'e']);
+    applyColorScaleRange(scales, encoding, accentNeutralTheme);
+    expect(ordinal.range()).toEqual(accentNeutralTheme.colors.categorical);
+  });
+
+  it('accent-neutral: 6 series falls back to full palette', () => {
+    const { scales, ordinal } = makeOrdinalScales(['a', 'b', 'c', 'd', 'e', 'f']);
+    applyColorScaleRange(scales, encoding, accentNeutralTheme);
+    expect(ordinal.range()).toEqual(accentNeutralTheme.colors.categorical);
+  });
+});

package/src/compile/color-scale-range.ts

@@ -5,17 +5,27 @@
  * (or the categorical endpoints as a fallback). Categorical scales get the
  * full categorical palette. A user-provided `encoding.color.scale.range`
  * always wins.
+ *
+ * When `highlight` is non-empty, highlighted series get sequential palette
+ * colors and muted series get a neutral gray.
+ *
+ * When `theme.seriesStrategy` is `'accent-neutral'`, low-cardinality
+ * charts use accent + neutral grays instead of the full palette.
  */
 
-import type { Encoding, ResolvedTheme } from '@opendata-ai/openchart-core';
+import { ACHROMATIC_RAMP, type Encoding, type ResolvedTheme } from '@opendata-ai/openchart-core';
 import type { ScaleLinear, ScaleOrdinal } from 'd3-scale';
 import type { ResolvedScales } from '../layout/scales';
 
+/** Neutral gray applied to muted (non-highlighted) series. */
+const MUTED_COLOR = '#bfc3c8';
+
 /** Mutates `scales.color.scale.range` in place when no explicit palette was set. */
 export function applyColorScaleRange(
   scales: ResolvedScales,
   encoding: Encoding,
   theme: ResolvedTheme,
+  highlight?: string[],
 ): void {
   if (!scales.color) return;
 
@@ -33,6 +43,38 @@ export function applyColorScaleRange(
       seqStops[seqStops.length - 1],
     ]);
   } else {
-    (scales.color.scale as ScaleOrdinal<string, string>).range(theme.colors.categorical);
+    const ordinalScale = scales.color.scale as ScaleOrdinal<string, string>;
+    const palette = theme.colors.categorical;
+    const domain = ordinalScale.domain();
+
+    if (highlight && highlight.length > 0) {
+      const highlightSet = new Set(highlight);
+      const colors = domain.map((v, i) =>
+        highlightSet.has(v) ? palette[i % palette.length] : MUTED_COLOR,
+      );
+      ordinalScale.range(colors);
+    } else {
+      const strategy = theme.seriesStrategy ?? 'palette';
+      if (strategy !== 'accent-neutral') {
+        ordinalScale.range(palette);
+      } else {
+        const count = domain.length;
+        if (count <= 1) {
+          ordinalScale.range([palette[0]]);
+        } else if (count <= 4) {
+          // Prominence tracks contrast against the surface: on dark canvases
+          // the brightest gray reads strongest, on light canvases the darkest.
+          const neutrals = theme.isDark
+            ? [ACHROMATIC_RAMP.fgMuted, ACHROMATIC_RAMP.fgSubtle, ACHROMATIC_RAMP.fgFaint]
+            : [ACHROMATIC_RAMP.fgFaint, ACHROMATIC_RAMP.fgSubtle, ACHROMATIC_RAMP.fgMuted];
+          const colors = domain.map((_, i) =>
+            i === 0 ? palette[0] : neutrals[(i - 1) % neutrals.length],
+          );
+          ordinalScale.range(colors);
+        } else {
+          ordinalScale.range(palette);
+        }
+      }
+    }
   }
 }