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

package/src/compile.ts

@@ -14,35 +14,32 @@
 
 import type {
   AnimationSpec,
-  BinParams,
-  BinTransform,
   ChartLayout,
   ChartSpec,
   CompileOptions,
   CompileTableOptions,
   Encoding,
-  EncodingChannel,
   FacetChannel,
   FacetPanelLayout,
   LayerSpec,
   LayoutStrategy,
+  LegendLayout,
   Mark,
   ResolvedAnimation,
   ResolvedAnnotation,
   ResolvedTheme,
   TableLayout,
-  TimeUnit,
-  TimeUnitTransform,
-  Transform,
 } from '@opendata-ai/openchart-core';
 import {
   adaptTheme,
   computeLabelBounds,
+  footnoteBandHeight,
   generateAltText,
   generateDataTable,
   getBreakpoint,
   getHeightClass,
   getLayoutStrategy,
+  isAxislessMark,
   resolveTheme,
 } from '@opendata-ai/openchart-core';
 import { computeAnnotations } from './annotations/compute';
@@ -64,8 +61,12 @@ import { getChartRenderer } from './charts/registry';
 import { groupByField } from './charts/utils';
 import { applyColorScaleRange } from './compile/color-scale-range';
 import { filterClippedDomains } from './compile/data-clip';
+import { applyFillPatterns } from './compile/fill-patterns';
 import { compileLayer as compileLayerImpl } from './compile/layer';
+import { emitSpecWarnings, expandSpecSugar } from './compile/spec-sugar';
 import { computeWatermarkObstacle } from './compile/watermark-obstacle';
+import { resolveYouDrawIt } from './compile/you-draw-it';
+import { collectContrastWarnings } from './compiler/a11y-warnings';
 import { resolveAnimation } from './compiler/animation';
 import { compile as compileSpec } from './compiler/index';
 import {
@@ -75,15 +76,17 @@ import {
   trendColor,
 } from './compiler/sparkline-defaults';
 import type { NormalizedChartSpec, NormalizedTableSpec } from './compiler/types';
+import { compileMap as compileMapImpl } from './geo/compile-map';
 import { compileGraph as compileGraphImpl } from './graphs/compile-graph';
 import type { GraphCompilation } from './graphs/types';
 import { computeAxes } from './layout/axes';
 import { computeDimensions } from './layout/dimensions';
-import { computeFacetGrid } from './layout/facet';
+import { computeFacetGrid, facetMinHeight, MIN_PANEL_HEIGHT } from './layout/facet';
 import { computeGridlines } from './layout/gridlines';
 import { createMeasureFn, resolveLayoutPlan } from './layout/plan';
 import { computeScales } from './layout/scales';
 import { placeLegend } from './legend/compute';
+import { placeSizeLegend } from './legend/size';
 import { compileSankey as compileSankeyImpl } from './sankey/compile-sankey';
 import { compileTableLayout } from './tables/compile-table';
 import { compileTileMap as compileTileMapImpl } from './tilemap/compile-tilemap';
@@ -91,76 +94,26 @@ import { computeTooltipDescriptors } from './tooltips/compute';
 import { runTransforms } from './transforms';
 
 // ---------------------------------------------------------------------------
-// Encoding sugar expansion (bin, timeUnit on encoding channels)
+// Spec sugar expansion (VL idioms, bin/timeUnit, deprecation warnings)
 // ---------------------------------------------------------------------------
 
+// Implementation lives in ./compile/spec-sugar; re-exported here so existing
+// deep imports (`import { expandEncodingSugar } from '.../compile'`) keep working.
+export { expandEncodingSugar, expandSpecSugar } from './compile/spec-sugar';
+
 /**
- * Expand encoding-level `bin` and `timeUnit` shorthand into explicit transforms.
- *
- * Vega-Lite allows `encoding.x.bin: true` as sugar for a BinTransform.
- * This function detects those shorthands, generates the corresponding transforms,
- * updates encoding field references to the output field names, and prepends the
- * transforms to the spec's transform array.
- *
- * Mutates nothing; returns a new spec object (shallow copy).
+ * Apply top-level spec `width`/`height` (VL fixed-size sugar) as overrides on
+ * the compile options. Returns the options untouched when the spec carries no
+ * size.
  */
-export function expandEncodingSugar(spec: Record<string, unknown>): Record<string, unknown> {
-  const encoding = spec.encoding as Record<string, EncodingChannel | undefined> | undefined;
-  if (!encoding) return spec;
-
-  const generatedTransforms: Transform[] = [];
-  const updatedEncoding = { ...encoding };
-  let changed = false;
-
-  for (const channel of Object.keys(encoding)) {
-    const ch = encoding[channel];
-    if (!ch || !ch.field) continue;
-
-    // Expand bin shorthand
-    if (ch.bin != null && ch.bin !== false) {
-      const field = ch.field;
-      const outputField = `bin_${field}`;
-      const binTransform: BinTransform = {
-        bin: ch.bin === true ? true : (ch.bin as BinParams),
-        field,
-        as: outputField,
-      };
-      generatedTransforms.push(binTransform);
-
-      // Update encoding to reference binned output field, remove bin property
-      const { bin: _bin, ...rest } = ch;
-      updatedEncoding[channel] = { ...rest, field: outputField } as EncodingChannel;
-      changed = true;
-    }
-
-    // Expand timeUnit shorthand (read from updated encoding in case bin already ran)
-    const current = updatedEncoding[channel] ?? ch;
-    if (current.timeUnit) {
-      const field = current.field;
-      const unit = current.timeUnit as TimeUnit;
-      const outputField = `${unit}_${field}`;
-      const timeUnitTransform: TimeUnitTransform = {
-        timeUnit: unit,
-        field,
-        as: outputField,
-      };
-      generatedTransforms.push(timeUnitTransform);
-
-      // Update encoding to reference timeUnit output field, remove timeUnit property
-      const { timeUnit: _tu, ...rest } = current;
-      updatedEncoding[channel] = { ...rest, field: outputField } as EncodingChannel;
-      changed = true;
-    }
-  }
-
-  if (!changed) return spec;
-
-  // Prepend generated transforms before any user-defined transforms
-  const existingTransforms = (spec.transform as Transform[] | undefined) ?? [];
+function applySpecSize(spec: unknown, options: CompileOptions): CompileOptions {
+  if (!spec || typeof spec !== 'object') return options;
+  const sized = spec as Record<string, unknown>;
+  if (typeof sized.width !== 'number' && typeof sized.height !== 'number') return options;
   return {
-    ...spec,
-    encoding: updatedEncoding,
-    transform: [...generatedTransforms, ...existingTransforms],
+    ...options,
+    width: typeof sized.width === 'number' ? sized.width : options.width,
+    height: typeof sized.height === 'number' ? sized.height : options.height,
   };
 }
 
@@ -168,6 +121,15 @@ export function expandEncodingSugar(spec: Record<string, unknown>): Record<strin
 // Chart compilation
 // ---------------------------------------------------------------------------
 
+/**
+ * Cap on footnote-reserve convergence passes in compileChart. Reserving space
+ * for the footnote list shrinks the plot, which can demote one more label and
+ * grow the list; the count only ever grows and is bounded by the annotation
+ * count, so this terminates on its own. The cap is a guard against a
+ * measurement quirk oscillating, not the normal exit condition.
+ */
+const MAX_FOOTNOTE_PASSES = 3;
+
 /**
  * Inject sparkline-mode visual defaults that depend on the resolved theme.
  *
@@ -233,20 +195,32 @@ function applySparklineDefaults(
  * ChartLayout with positions, colors, and marks ready for rendering.
  *
  * @param spec - Raw chart spec (validated and normalized internally).
- * @param options - Compile options (width, height, theme, darkMode).
+ * @param optionsInput - Compile options (width, height, theme, darkMode).
+ *   Top-level spec width/height, when present, override the option values.
  * @returns ChartLayout with all computed positions.
  * @throws Error if spec is invalid or not a chart type.
  */
-export function compileChart(spec: unknown, options: CompileOptions): ChartLayout {
-  // Expand encoding-level bin/timeUnit sugar before validation + normalization.
-  // This converts shorthand (e.g. encoding.x.bin: true) into explicit transforms.
+export function compileChart(spec: unknown, optionsInput: CompileOptions): ChartLayout {
+  // Expand VL-idiom and encoding-level sugar (data {values}, top-level title,
+  // sort-by-value, value defs, scheme names, theta, bin/timeUnit, ...) before
+  // validation + normalization, surfacing any deprecation warnings.
+  const sugarWarnings: string[] = [];
   const expandedSpec =
     spec && typeof spec === 'object' && !Array.isArray(spec)
-      ? expandEncodingSugar(spec as Record<string, unknown>)
+      ? expandSpecSugar(spec as Record<string, unknown>, sugarWarnings)
       : spec;
 
-  // Validate + normalize
-  const { spec: normalized } = compileSpec(expandedSpec);
+  // Top-level width/height are fixed-size overrides (VL alignment): the
+  // authored size wins over the container-derived compile options.
+  const options = applySpecSize(expandedSpec, optionsInput);
+
+  // Validate + normalize. Normalize-stage warnings (type mismatches,
+  // beeswarm point budget, sparkline mark advice) surface through the same
+  // console channel as the sugar warnings. Emit both together in one call so
+  // dedup spans the whole compile: a message produced by both a sugar pass and
+  // a normalize pass prints once, not once per stage.
+  const { spec: normalized, warnings: normalizeWarnings } = compileSpec(expandedSpec);
+  emitSpecWarnings([...sugarWarnings, ...normalizeWarnings], options.onWarn);
 
   if ('type' in normalized && (normalized as unknown as Record<string, unknown>).type === 'table') {
     throw new Error('compileChart received a table spec. Use compileTable instead.');
@@ -260,6 +234,9 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   ) {
     throw new Error('compileChart received a sankey spec. Use compileSankey instead.');
   }
+  if ('type' in normalized && (normalized as unknown as Record<string, unknown>).type === 'map') {
+    throw new Error('compileChart received a map spec. Use compileMap instead.');
+  }
 
   let chartSpec = normalized as NormalizedChartSpec;
 
@@ -607,6 +584,8 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
       watermark,
       resolvedAnimation,
       crosshair,
+      spec,
+      optionsInput,
     );
   }
 
@@ -640,14 +619,26 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   const chartArea = options.frozenChartArea ?? dims.chartArea;
 
   // Place legend in its final position relative to the computed chart area.
+  // effectiveAxisGap lifts a top legend above the inline-tick overhang zone
+  // the margin stack reserved below it.
   const finalLegend = placeLegend(
     plan.legendContent,
     chartArea,
     options.width,
     theme,
     plan.xAxisExtent,
+    dims.effectiveAxisGap,
   );
 
+  // Every legend on the chart. The color legend is primary (and stays in the
+  // singular `legend` slot); a size legend joins it when a quantitative `size`
+  // channel is encoded. Consumers that reserve space or hit-test must iterate
+  // this rather than read `legend` -- see ChartLayout.legends.
+  const sizeLegend = plan.sizeLegendContent
+    ? placeSizeLegend(plan.sizeLegendContent, chartArea, theme, finalLegend)
+    : null;
+  const allLegends: LegendLayout[] = [finalLegend, ...(sizeLegend ? [sizeLegend] : [])];
+
   // Inline y-axis labels: inset the x-scale range start by the widest tick
   // label width so data marks start to the right of the labels. The plan
   // already measured the real tick labels.
@@ -674,8 +665,16 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   scales.defaultColor =
     chartSpec.markDef.fill ?? chartSpec.markDef.stroke ?? theme.colors.categorical[0];
 
-  // Arc charts (pie/donut) don't use axes or gridlines
-  const isRadial = chartSpec.markType === 'arc';
+  // Dev-mode WCAG contrast diagnostics. Host-gated via options.dev (never an
+  // env sniff; the engine is isomorphic). Advisory console.warn only.
+  if (options.dev) {
+    emitSpecWarnings(collectContrastWarnings(scales, chartSpec.markType, theme), options.onWarn);
+  }
+
+  // Axisless marks (arc, waffle, calendar, parliament) don't use axes or
+  // gridlines: arcs and parliament hemicycles are radial, waffles and calendars
+  // compute their own grid geometry.
+  const isRadial = isAxislessMark(chartSpec.markType);
 
   // Compute axes (skip for radial charts).
   // Sparkline mode skips axes by default unless the user explicitly opted into
@@ -715,6 +714,18 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
     ? renderer(renderSpec, scales, chartArea, strategy, theme, options.width)
     : [];
 
+  // Opt-in per-series fill patterns (mark.fillPattern: 'auto'). Mutates
+  // filled marks in place; assignment is deterministic and theme-aware.
+  applyFillPatterns(marks, chartSpec.markDef, theme);
+
+  // Resolve "you draw it" geometry (pixel fromX, x-sample positions, target
+  // line color/key). Reads marks so it must run after they're computed.
+  const xFieldForYdi =
+    chartSpec.encoding.x && 'field' in chartSpec.encoding.x
+      ? (chartSpec.encoding.x.field as string | undefined)
+      : undefined;
+  const youDrawIt = resolveYouDrawIt(chartSpec.youDrawIt, marks, scales, chartArea, xFieldForYdi);
+
   // Compute the right-side endpoint labels column for multi-series line/area
   // charts. Reads `mark.dataPoints` so it must run AFTER marks are computed.
   // dimensions.ts already reserved the right margin via predictEndpointLabelsWidth.
@@ -762,6 +773,7 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
     obstacles,
     svg: { width: dims.total.width, height: dims.total.height },
     measure: annotationMeasure,
+    fontFamily: theme.fonts.family,
     autoThin: chartSpec.autoThin,
   });
 
@@ -770,26 +782,67 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
   // alignment with the resolved array is preserved.
   let footnotes: import('@opendata-ai/openchart-core').AnnotationFootnote[] | undefined;
   if (chartSpec.autoThin && annotations.length > 1) {
-    const result = thinAnnotations(annotations, chartSpec.annotations, annotationMeasure);
+    const result = thinAnnotations(
+      annotations,
+      chartSpec.annotations,
+      annotationMeasure,
+      chartArea,
+      { x: 0, y: 0, width: dims.total.width, height: dims.total.height },
+    );
     annotations = result.annotations;
     if (result.footnotes.length > 0) {
       footnotes = result.footnotes;
+
+      // The footnote list renders below the plot, but nothing reserved space for
+      // it — thinning only just now discovered how many lines there are. Recompile
+      // with that band carved out of the bottom margin so the list can't overrun
+      // the source row and the brand watermark.
+      //
+      // Reserving shrinks the plot, which can push a further label out of bounds
+      // and grow the list by one, so re-reserve until the count settles. The
+      // count only ever grows (a smaller plot never keeps more labels inline) and
+      // is bounded by the annotation count, so this terminates; the explicit cap
+      // is a belt-and-braces guard against a measurement quirk oscillating.
+      //
+      // A frozen area short-circuits all of this. `compileLayer` pins every
+      // leaf to the primary layout's coordinate space, and `chartArea` above
+      // takes `frozenChartArea` over anything `computeDimensions` produces --
+      // so a grown bottom margin is computed and then thrown away. The
+      // recursion would re-run the whole compile up to MAX_FOOTNOTE_PASSES
+      // times and return the identical layout. Skip it rather than pay for it.
+      const reserve = footnoteBandHeight(footnotes.length, theme);
+      const currentReserve = options.footnoteReserve ?? 0;
+      if (
+        !options.frozenChartArea &&
+        reserve > currentReserve &&
+        (options.footnotePass ?? 0) < MAX_FOOTNOTE_PASSES
+      ) {
+        return compileChart(spec, {
+          ...optionsInput,
+          footnoteReserve: reserve,
+          footnotePass: (options.footnotePass ?? 0) + 1,
+        });
+      }
     }
   }
 
   // Compute tooltip descriptors from marks and encoding
   const tooltipDescriptors = computeTooltipDescriptors(chartSpec, marks);
 
-  // Compute accessibility
-  const altText = generateAltText(
-    {
-      mark: chartSpec.markType,
-      data: chartSpec.data,
-      encoding: chartSpec.encoding,
-      chrome: chartSpec.chrome,
-    } as ChartSpec,
-    chartSpec.data,
-  );
+  // Compute accessibility. An author-provided description (a11y.description,
+  // or top-level `description` folded in by the sugar expansion) replaces the
+  // auto-generated alt text; auto-generation stays the fallback.
+  const altText =
+    chartSpec.a11y?.description ??
+    generateAltText(
+      {
+        mark: chartSpec.markType,
+        data: chartSpec.data,
+        encoding: chartSpec.encoding,
+        chrome: chartSpec.chrome,
+      } as ChartSpec,
+      chartSpec.data,
+    );
   const dataTableFallback = generateDataTable(
     {
       mark: chartSpec.markType,
@@ -808,6 +861,8 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
     area: chartArea,
     chrome,
     metrics: dims.metrics,
+    ...(dims.seriesSearch ? { seriesSearch: dims.seriesSearch } : {}),
+    ...(youDrawIt ? { youDrawIt } : {}),
     axes: {
       x: axes.x,
       y: axes.y,
@@ -815,6 +870,7 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
     marks,
     annotations,
     legend: finalLegend,
+    legends: allLegends,
     ...(endpointLabels.entries.length > 0 ? { endpointLabels } : {}),
     tooltipDescriptors,
     a11y: {
@@ -822,6 +878,7 @@ export function compileChart(spec: unknown, options: CompileOptions): ChartLayou
       dataTableFallback,
       role: 'img',
       keyboardNavigable: marks.length > 0,
+      ...(chartSpec.a11y?.hidden ? { hidden: true } : {}),
     },
     theme,
     dimensions: {
@@ -850,6 +907,8 @@ function compileFaceted(
   watermark: boolean,
   resolvedAnimation: ResolvedAnimation | undefined,
   crosshair: boolean,
+  rawSpec: unknown,
+  optionsInput: CompileOptions,
 ): ChartLayout {
   const measure = createMeasureFn(options.measureText);
 
@@ -898,12 +957,14 @@ function compileFaceted(
   );
   const chartArea = dims.chartArea;
 
+  // Same effectiveAxisGap threading as the regular (non-faceted) path.
   const finalLegend = placeLegend(
     plan.legendContent,
     chartArea,
     options.width,
     theme,
     plan.xAxisExtent,
+    dims.effectiveAxisGap,
   );
 
   // Estimate y-axis gutter width (used as left reservation for outer axes)
@@ -917,6 +978,23 @@ function compileFaceted(
     bottom: bottomReservation,
   });
 
+  // If panels are too short, grow the compile height and restart (once).
+  if (
+    !optionsInput.facetHeightGrown &&
+    grid.panels.length > 0 &&
+    grid.panels[0].area.height < MIN_PANEL_HEIGHT
+  ) {
+    const neededChartHeight = facetMinHeight(facetValues.length, grid.columns);
+    const heightGrowth = neededChartHeight - chartArea.height;
+    if (heightGrowth > 0) {
+      return compileChart(rawSpec, {
+        ...optionsInput,
+        height: options.height + heightGrowth,
+        facetHeightGrown: true,
+      });
+    }
+  }
+
   // Resolve scale for determining if we use 'independent' or 'shared'
   const resolveConfig = chartSpec.resolve;
   const yResolve = resolveConfig?.scale?.y ?? 'shared';
@@ -929,7 +1007,7 @@ function compileFaceted(
   const sharedYDomain =
     yResolve === 'shared' && fullScales.y ? fullScales.y.scale.domain() : undefined;
 
-  const isRadial = chartSpec.markType === 'arc';
+  const isRadial = isAxislessMark(chartSpec.markType);
   const rendererKey = resolveRendererKey(
     renderSpec.markType,
     panelEncoding as Encoding,
@@ -939,6 +1017,11 @@ function compileFaceted(
 
   const allMarks: Mark[] = [];
   const panelLayouts: FacetPanelLayout[] = [];
+  // Footnotes pool across panels into one figure-level list (the renderer draws
+  // a single list below the grid from `chrome.footnotes`), so the numbering is
+  // continuous and each panel's markers index into it.
+  const allFootnotes: import('@opendata-ai/openchart-core').AnnotationFootnote[] = [];
+  const footnoteNumberBySpecIndex = new Map<number, number>();
 
   for (const gridPanel of grid.panels) {
     const panelData = groups.get(gridPanel.key) ?? [];
@@ -971,18 +1054,22 @@ function compileFaceted(
     panelScales.defaultColor =
       chartSpec.markDef.fill ?? chartSpec.markDef.stroke ?? theme.colors.categorical[0];
 
-    // Outer-axis economy: only leftmost column gets y ticks, only bottom row gets x ticks.
-    // Exception: when scales are independent, every panel needs its own axis ticks.
+    // Dev-mode contrast diagnostics: panels share one palette resolution, so
+    // checking the first panel covers the figure without repeating warnings.
+    if (options.dev && panelLayouts.length === 0) {
+      emitSpecWarnings(
+        collectContrastWarnings(panelScales, chartSpec.markType, theme),
+        options.onWarn,
+      );
+    }
+
     const isLeftCol = gridPanel.col === 0;
-    const isBottomRow = gridPanel.row === grid.rows - 1;
 
     const panelAxes = isRadial
       ? { x: undefined, y: undefined }
       : computeAxes(panelScales, gridPanel.area, strategy, theme, options.measureText, {
           data: panelData,
           encoding: panelSpecWithDomains.encoding as Encoding,
-          skipX: xResolve === 'shared' ? !isBottomRow : false,
-          skipY: yResolve === 'shared' ? !isLeftCol : false,
           markType: chartSpec.markType,
           totalWidth: gridPanel.area.width,
         });
@@ -991,6 +1078,18 @@ function compileFaceted(
       computeGridlines(panelAxes, gridPanel.area);
     }
 
+    // Strip y-axis tick labels from non-leftmost panels (gridlines stay).
+    // X-axis labels show on every panel for readability.
+    if (yResolve === 'shared' && !isLeftCol && panelAxes.y) {
+      panelAxes.y = {
+        ...panelAxes.y,
+        ticks: [],
+        label: undefined,
+        domainLine: false,
+        tickMarks: false,
+      };
+    }
+
     // Compute marks for this panel
     const panelMarks: Mark[] = renderer
       ? renderer(
@@ -1007,7 +1106,7 @@ function compileFaceted(
     const annotationMeasure: AnnotationMeasureTextFn = options.measureText
       ? (text, font) => options.measureText!(text, font.fontSize, font.fontWeight).width
       : heuristicMeasure;
-    const panelAnnotations = computeAnnotations(panelSpecWithDomains, {
+    let panelAnnotations = computeAnnotations(panelSpecWithDomains, {
       scales: panelScales,
       chartArea: gridPanel.area,
       strategy,
@@ -1015,9 +1114,55 @@ function compileFaceted(
       obstacles: [],
       svg: { width: options.width, height: options.height },
       measure: annotationMeasure,
+      fontFamily: theme.fonts.family,
       autoThin: panelSpecWithDomains.autoThin,
     });
 
+    // Auto-thinning, per panel. A panel is its own little chart: the box a label
+    // must stay inside is the panel, not the figure. Thinning against the whole
+    // SVG (what the single-chart path passes) would let a label from the left
+    // column sprawl across its neighbour and still count as "fits".
+    //
+    // The spec's annotations resolve into *every* panel, so the same annotation
+    // can demote in more than one. The footnote list is figure-level and its text
+    // is per-spec-annotation, so number by spec index and reuse that number in
+    // every panel that demoted it -- otherwise the list repeats itself once per
+    // panel.
+    if (chartSpec.autoThin && panelAnnotations.length > 1) {
+      const thinned = thinAnnotations(
+        panelAnnotations,
+        chartSpec.annotations,
+        annotationMeasure,
+        gridPanel.area,
+        gridPanel.area,
+      );
+      panelAnnotations = thinned.annotations;
+      // `thinAnnotations` numbers footnotes 1..n *within the panel it was given*,
+      // so restamp each demoted annotation with its figure-level number. Take the
+      // text from `thinned.footnotes` (the 1-based panel-local index it just
+      // assigned) rather than re-reading `label.text`: thinning owns that string,
+      // and re-deriving it here would be a second producer to drift out of sync.
+      //
+      // Key on `specIndex`, NOT on position: with `resolve.scale.x: 'independent'`
+      // each panel derives its own domain, so an annotation can resolve in one
+      // panel and be dropped in another. Position i then means a different spec
+      // annotation in each panel, and the markers point at other panels' text.
+      for (const a of panelAnnotations) {
+        const panelIndex = a.footnoteIndex;
+        if (panelIndex == null || a.specIndex === undefined) continue;
+        let num = footnoteNumberBySpecIndex.get(a.specIndex);
+        if (num === undefined) {
+          num = allFootnotes.length + 1;
+          footnoteNumberBySpecIndex.set(a.specIndex, num);
+          allFootnotes.push({
+            index: num,
+            text: thinned.footnotes[panelIndex - 1]?.text ?? '',
+          });
+        }
+        a.footnoteIndex = num;
+      }
+    }
+
     allMarks.push(...panelMarks);
 
     panelLayouts.push({
@@ -1036,10 +1181,37 @@ function compileFaceted(
     });
   }
 
+  // The footnote list renders below the grid, but nothing reserved space for it
+  // -- thinning only just now discovered how many lines there are. Recompile with
+  // that band carved out of the bottom margin, same contract as the single-chart
+  // path (see the matching block in compileChart). computeDimensions applies
+  // options.footnoteReserve generically, so the facet grid shrinks with it.
+  //
+  // A frozen area short-circuits this, same as the single-chart path: compileLayer
+  // pins every leaf to the primary layout's coordinate space, so the grown bottom
+  // margin is computed and then thrown away. Recursing would re-run the whole
+  // compile up to MAX_FOOTNOTE_PASSES times for an identical layout.
+  if (allFootnotes.length > 0 && !options.frozenChartArea) {
+    const reserve = footnoteBandHeight(allFootnotes.length, theme);
+    const currentReserve = options.footnoteReserve ?? 0;
+    if (reserve > currentReserve && (options.footnotePass ?? 0) < MAX_FOOTNOTE_PASSES) {
+      return compileChart(rawSpec, {
+        ...optionsInput,
+        footnoteReserve: reserve,
+        footnotePass: (options.footnotePass ?? 0) + 1,
+      });
+    }
+  }
+
   // Compute tooltip descriptors from all marks across panels
   const tooltipDescriptors = computeTooltipDescriptors(panelChartSpec, allMarks);
 
-  // A11y: mention faceting in alt text
+  // Opt-in per-series fill patterns across all panels at once so a series
+  // gets the same pattern in every panel.
+  applyFillPatterns(allMarks, chartSpec.markDef, theme);
+
+  // A11y: mention faceting in alt text. An author description is used
+  // verbatim (the author already describes the whole figure).
   const panelCount = facetValues.length;
   const baseAltText = generateAltText(
     {
@@ -1050,7 +1222,9 @@ function compileFaceted(
     } as ChartSpec,
     chartSpec.data,
   );
-  const altText = `${baseAltText} Faceted into ${panelCount} panels by ${facetChannel.field}.`;
+  const altText =
+    chartSpec.a11y?.description ??
+    `${baseAltText} Faceted into ${panelCount} panels by ${facetChannel.field}.`;
 
   const dataTableFallback = generateDataTable(
     {
@@ -1068,18 +1242,23 @@ function compileFaceted(
   // Figure-level marks are the union of all panel marks (for tooltip/keyboard nav)
   return {
     area: chartArea,
-    chrome: dims.chrome,
+    chrome: allFootnotes.length > 0 ? { ...dims.chrome, footnotes: allFootnotes } : dims.chrome,
     metrics: dims.metrics,
+    ...(dims.seriesSearch ? { seriesSearch: dims.seriesSearch } : {}),
     axes: { x: undefined, y: undefined },
     marks: allMarks,
     annotations: [],
     legend: finalLegend,
+    // Facets share one color legend across the grid; the size channel isn't
+    // supported in facet specs, so there is no second legend to carry.
+    legends: [finalLegend],
     tooltipDescriptors,
     a11y: {
       altText,
       dataTableFallback,
       role: 'img',
       keyboardNavigable: allMarks.length > 0,
+      ...(chartSpec.a11y?.hidden ? { hidden: true } : {}),
     },
     theme,
     dimensions: { width: options.width, height: options.height },
@@ -1102,7 +1281,17 @@ function compileFaceted(
 // ---------------------------------------------------------------------------
 
 export function compileLayer(spec: LayerSpec, options: CompileOptions): ChartLayout {
-  return compileLayerImpl(spec, options, compileChart);
+  // Expand VL-idiom sugar on the layer spec and every child up front. Leaf
+  // compiles re-run the (idempotent) expansion after encoding inheritance;
+  // warning triggers are stripped or stamped here so each warns exactly once.
+  const sugarWarnings: string[] = [];
+  const expanded = expandSpecSugar(
+    spec as unknown as Record<string, unknown>,
+    sugarWarnings,
+  ) as unknown as LayerSpec;
+  emitSpecWarnings(sugarWarnings, options.onWarn);
+  const resolvedOptions = applySpecSize(expanded, options);
+  return compileLayerImpl(expanded, resolvedOptions, compileChart);
 }
 
 // ---------------------------------------------------------------------------
@@ -1214,6 +1403,29 @@ export function compileTileMap(
   return compileTileMapImpl(spec, options);
 }
 
+// ---------------------------------------------------------------------------
+// Map compilation
+// ---------------------------------------------------------------------------
+
+/**
+ * Compile a map spec into a MapLayout.
+ *
+ * Takes a raw map spec, validates, normalizes, resolves theme and chrome,
+ * projects geo features, joins data, builds feature marks with color fills,
+ * and returns a MapLayout ready for rendering.
+ *
+ * @param spec - Raw map spec (validated and normalized internally).
+ * @param options - Compile options (width, height, theme, darkMode).
+ * @returns MapLayout with computed positions and visual properties.
+ * @throws Error if spec is invalid or not a map type.
+ */
+export function compileMap(
+  spec: unknown,
+  options: CompileOptions,
+): import('@opendata-ai/openchart-core').MapLayout {
+  return compileMapImpl(spec, options);
+}
+
 // ---------------------------------------------------------------------------
 // BarList compilation
 // ---------------------------------------------------------------------------