@opendata-ai/openchart-engine 7.10.0 → 8.0.0-rc.1

package/src/compiler/normalize.ts

@@ -20,6 +20,8 @@ import type {
   GraphSpec,
   LabelSpec,
   LayerSpec,
+  MapSpec,
+  MarkDef,
   SankeySpec,
   TableSpec,
   TileMapSpec,
@@ -30,6 +32,7 @@ import {
   isChartSpec,
   isGraphSpec,
   isLayerSpec,
+  isMapSpec,
   isSankeySpec,
   isTableSpec,
   isTileMapSpec,
@@ -37,6 +40,7 @@ import {
   resolveMarkType,
 } from '@opendata-ai/openchart-core';
 import type { NormalizedBarListSpec } from '../barlist/types';
+import type { NormalizedMapSpec } from '../geo/types';
 import type { NormalizedSankeySpec } from '../sankey/types';
 import { STATE_CODE_SET } from '../tilemap/layout';
 import type { NormalizedTileMapSpec } from '../tilemap/types';
@@ -138,6 +142,9 @@ function inferEncodingTypes(encoding: Encoding, data: DataRow[], warnings: strin
 
     // Skip conditional value definitions - they don't have field/type at the top level
     if ('condition' in spec) continue;
+    // Skip bare value defs (no field). The sugar expansion moves these to
+    // mark-level properties before normalize runs on the compile path.
+    if (!('field' in spec)) continue;
 
     if (!spec.type) {
       const inferred = inferFieldType(data, spec.field);
@@ -168,13 +175,20 @@ function inferEncodingTypes(encoding: Encoding, data: DataRow[], warnings: strin
 function normalizeAnnotations(annotations: Annotation[] | undefined): Annotation[] {
   if (!annotations || annotations.length === 0) return [];
 
+  // The spec-sugar pass rewrites the deprecated `type: 'rule'` annotation
+  // alias to `'refline'` (with a warning) before validation/normalization
+  // ever runs, so by this point every annotation is in canonical form.
   return annotations.map((ann) => {
     switch (ann.type) {
       case 'text':
+        // Deliberately does NOT default fontSize/fontWeight. The annotation
+        // layer owns those (DEFAULT_ANNOTATION_FONT_SIZE, and the lede rule
+        // that promotes a subtitle-bearing primary line to bold). Stamping
+        // them here makes `annotation.fontWeight` always defined, so
+        // `resolveLedeFontWeight` can never fire and the size default can
+        // never apply — both features become dead code.
         return {
           ...ann,
-          fontSize: ann.fontSize ?? 12,
-          fontWeight: ann.fontWeight ?? 400,
           opacity: ann.opacity ?? 1,
         };
       case 'range':
@@ -184,10 +198,8 @@ function normalizeAnnotations(annotations: Annotation[] | undefined): Annotation
           fill: ann.fill ?? '#000000',
         };
       case 'refline':
-      case 'rule':
         return {
           ...ann,
-          type: 'refline' as const,
           style: ann.style ?? 'dashed',
           strokeWidth: ann.strokeWidth ?? 1,
           stroke: ann.stroke ?? '#666666',
@@ -254,10 +266,104 @@ function normalizeHighlight(encoding: Encoding, data: DataRow[], warnings: strin
   return highlight;
 }
 
+// ---------------------------------------------------------------------------
+// Series search normalization
+// ---------------------------------------------------------------------------
+
+/**
+ * Normalize `seriesSearch` to a config object, or undefined when disabled.
+ * Search needs a categorical color encoding to enumerate series values;
+ * warns and disables when there isn't one.
+ */
+function normalizeSeriesSearch(
+  spec: ChartSpec,
+  encoding: Encoding,
+  warnings: string[],
+): import('@opendata-ai/openchart-core').SeriesSearchConfig | undefined {
+  if (!spec.seriesSearch) return undefined;
+  const color = encoding.color;
+  const hasCategoricalColor =
+    !!color &&
+    !('condition' in color) &&
+    'field' in color &&
+    !!color.field &&
+    color.type !== 'quantitative';
+  if (!hasCategoricalColor) {
+    warnings.push(
+      '[openchart] seriesSearch requires a categorical color encoding (encoding.color.field with a nominal/ordinal type); ignoring seriesSearch.',
+    );
+    return undefined;
+  }
+  return typeof spec.seriesSearch === 'object' ? { ...spec.seriesSearch } : {};
+}
+
+// ---------------------------------------------------------------------------
+// You draw it normalization
+// ---------------------------------------------------------------------------
+
+/**
+ * Normalize `youDrawIt` to a config object with defaults filled in, or
+ * undefined when disabled. Mark type, single-series, and `from` presence are
+ * enforced by validateSpec before normalize runs; this only fills defaults.
+ */
+function normalizeYouDrawIt(
+  spec: ChartSpec,
+): import('@opendata-ai/openchart-core').YouDrawItConfig | undefined {
+  if (!spec.youDrawIt) return undefined;
+  return {
+    prompt: 'Draw your guess',
+    revealLabel: 'Show me',
+    ...spec.youDrawIt,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Spec-level normalization
 // ---------------------------------------------------------------------------
 
+/**
+ * Beeswarm point budget. Past this count the dodge layout still resolves
+ * every collision, but the swarm piles into a solid band that reads no
+ * better than an overplotted strip, and layout cost keeps growing.
+ */
+const BEESWARM_POINT_BUDGET = 2000;
+
+/**
+ * Warn when a parliament `majorityLine.seats` override lands outside the chamber
+ * (below 1 or above the seat total). The mark falls back to a simple majority in
+ * that case, so this is a non-fatal warning routed through the shared warnings
+ * array (dedup + single emit boundary) rather than a raw console.warn in mark
+ * computation. Only the object form of majorityLine carries a seat count.
+ */
+function warnParliamentMajorityRange(
+  markDef: MarkDef,
+  encoding: Encoding,
+  data: DataRow[],
+  warnings: string[],
+): void {
+  const majorityLine = markDef.majorityLine;
+  if (!majorityLine || typeof majorityLine !== 'object') return;
+  const requested = majorityLine.seats;
+  if (requested === undefined) return;
+
+  const valueField = encoding.theta?.field ?? encoding.y?.field;
+  if (!valueField) return;
+
+  let totalSeats = 0;
+  for (const row of data) {
+    const v = Number(row[valueField]);
+    if (Number.isFinite(v)) totalSeats += v;
+  }
+  if (totalSeats <= 0) return;
+
+  if (!Number.isFinite(requested) || requested < 1 || requested > totalSeats) {
+    const fallback = Math.floor(totalSeats / 2) + 1;
+    warnings.push(
+      `[openchart] parliament mark.majorityLine.seats (${requested}) is outside the valid range 1..${totalSeats}; using the default majority threshold of ${fallback}.`,
+    );
+  }
+}
+
 function normalizeChartSpec(spec: ChartSpec, warnings: string[]): NormalizedChartSpec {
   const encoding = inferEncodingTypes(spec.encoding, spec.data, warnings);
   const markType = resolveMarkType(spec.mark);
@@ -276,6 +382,16 @@ function normalizeChartSpec(spec: ChartSpec, warnings: string[]): NormalizedChar
     );
   }
 
+  if (markType === 'beeswarm' && spec.data.length > BEESWARM_POINT_BUDGET) {
+    warnings.push(
+      `[openchart] beeswarm received ${spec.data.length} data points, past the ~${BEESWARM_POINT_BUDGET}-point budget where individual dots stop being readable and the swarm collapses into a solid band. Sample the data down, or summarize the distribution with mark: 'tick' (strip plot) or a binned histogram (bin transform + mark: 'bar').`,
+    );
+  }
+
+  if (markType === 'parliament') {
+    warnParliamentMajorityRange(markDef, encoding, spec.data, warnings);
+  }
+
   return {
     markType,
     markDef,
@@ -283,6 +399,8 @@ function normalizeChartSpec(spec: ChartSpec, warnings: string[]): NormalizedChar
     encoding,
     chrome: normalizeChrome(spec.chrome),
     metrics: spec.metrics,
+    seriesSearch: normalizeSeriesSearch(spec, encoding, warnings),
+    youDrawIt: normalizeYouDrawIt(spec),
     annotations: normalizeAnnotations(spec.annotations),
     labels: normalizeLabels(spec.labels),
     legend: spec.legend,
@@ -298,6 +416,7 @@ function normalizeChartSpec(spec: ChartSpec, warnings: string[]): NormalizedChar
     seriesStyles: spec.seriesStyles ?? {},
     watermark: spec.watermark ?? true,
     highlight: normalizeHighlight(encoding, spec.data, warnings),
+    a11y: spec.a11y,
     display,
     resolve: spec.resolve,
     // Default empty userExplicit; compileChart overwrites this with the real
@@ -358,7 +477,7 @@ function normalizeSankeySpec(spec: SankeySpec, _warnings: string[]): NormalizedS
   };
 }
 
-function normalizeGraphSpec(spec: GraphSpec, _warnings: string[]): NormalizedGraphSpec {
+function normalizeGraphSpec(spec: GraphSpec): NormalizedGraphSpec {
   // Default layout with chargeStrength and linkDistance
   const defaultLayout = {
     type: 'force' as const,
@@ -458,6 +577,27 @@ function normalizeTileMapSpec(spec: TileMapSpec, warnings: string[]): Normalized
   };
 }
 
+function normalizeMapSpec(spec: MapSpec, _warnings: string[]): NormalizedMapSpec {
+  return {
+    type: 'map',
+    geo: {
+      features: spec.geo.features,
+      idField: spec.geo.idField ?? 'id',
+      projection: spec.geo.projection ?? 'albersUsa',
+      focus: spec.geo.focus ?? null,
+    },
+    data: spec.data,
+    encoding: spec.encoding,
+    chrome: normalizeChrome(spec.chrome),
+    legend: spec.legend,
+    theme: spec.theme ?? {},
+    darkMode: spec.darkMode ?? 'off',
+    watermark: spec.watermark ?? true,
+    animation: spec.animation,
+    valueFormat: spec.valueFormat,
+  };
+}
+
 function normalizeBarListSpec(spec: BarListSpec, _warnings: string[]): NormalizedBarListSpec {
   return {
     type: 'barlist',
@@ -504,7 +644,7 @@ export function normalizeSpec(spec: VizSpec, warnings: string[] = []): Normalize
     return normalizeTableSpec(spec, warnings);
   }
   if (isGraphSpec(spec)) {
-    return normalizeGraphSpec(spec, warnings);
+    return normalizeGraphSpec(spec);
   }
   if (isSankeySpec(spec)) {
     return normalizeSankeySpec(spec, warnings);
@@ -512,12 +652,15 @@ export function normalizeSpec(spec: VizSpec, warnings: string[] = []): Normalize
   if (isTileMapSpec(spec)) {
     return normalizeTileMapSpec(spec, warnings);
   }
+  if (isMapSpec(spec)) {
+    return normalizeMapSpec(spec, warnings);
+  }
   if (isBarListSpec(spec)) {
     return normalizeBarListSpec(spec, warnings);
   }
   // Should never happen after validation
   throw new Error(
-    `Unknown spec shape. Expected mark (chart), layer, type: 'table', type: 'graph', type: 'sankey', type: 'tilemap', or type: 'barlist'.`,
+    `Unknown spec shape. Expected mark (chart), layer, type: 'table', type: 'graph', type: 'sankey', type: 'tilemap', type: 'map', or type: 'barlist'.`,
   );
 }
 

package/src/compiler/types.ts

@@ -30,6 +30,7 @@ import type {
   ThemeConfig,
 } from '@opendata-ai/openchart-core';
 import type { NormalizedBarListSpec } from '../barlist/types';
+import type { NormalizedMapSpec } from '../geo/types';
 import type { NormalizedSankeySpec } from '../sankey/types';
 import type { NormalizedTileMapSpec } from '../tilemap/types';
 
@@ -107,6 +108,13 @@ export interface NormalizedChartSpec {
   chrome: NormalizedChrome;
   /** Optional KPI metric cells, passed through unchanged. */
   metrics?: import('@opendata-ai/openchart-core').Metric[];
+  /**
+   * Searchable series highlight config. Present only when `seriesSearch` is
+   * enabled AND the spec has a categorical color encoding to search over.
+   */
+  seriesSearch?: import('@opendata-ai/openchart-core').SeriesSearchConfig;
+  /** Resolved "you draw it" config with defaults filled in. Present only when `youDrawIt` is enabled. */
+  youDrawIt?: import('@opendata-ai/openchart-core').YouDrawItConfig;
   annotations: Annotation[];
   /** Normalized label configuration with defaults applied. density, format, and prefix are always set; offsets and color stay optional. */
   labels: Required<Pick<LabelConfig, 'density' | 'format' | 'prefix'>> &
@@ -126,6 +134,8 @@ export interface NormalizedChartSpec {
   hiddenSeries: string[];
   /** Per-series visual style overrides. */
   seriesStyles: Record<string, import('@opendata-ai/openchart-core').SeriesStyle>;
+  /** Author accessibility overrides (alt-text description, aria-hidden opt-out). */
+  a11y?: import('@opendata-ai/openchart-core').A11yConfig;
   /** Display mode controlling chrome/axes/legend stripping. Defaults to `'full'`. */
   display: Display;
   /** Resolve configuration for independent/shared scales in faceted charts. */
@@ -184,6 +194,7 @@ export type NormalizedSpec =
   | NormalizedGraphSpec
   | NormalizedSankeySpec
   | NormalizedTileMapSpec
+  | NormalizedMapSpec
   | NormalizedBarListSpec;
 
 // ---------------------------------------------------------------------------