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

package/src/types/spec.ts

@@ -32,6 +32,10 @@ import type { SeriesStrategy, TokenValue } from './theme';
  * - 'rule': reference lines as data marks
  * - 'tick': strip/rug plot marks
  * - 'rect': heatmaps and 2D binned plots
+ * - 'range': dumbbell / arrow / range-bar plots spanning two values per category
+ * - 'waffle': unit grids ("x of 100") for part-to-whole counts
+ * - 'calendar': GitHub-style calendar heatmap (weeks x weekdays, daily dates)
+ * - 'parliament': hemicycle seat-dot chart for election/legislature results
  */
 export type MarkType =
   | 'bar'
@@ -44,10 +48,12 @@ export type MarkType =
   | 'rule'
   | 'tick'
   | 'rect'
-  | 'lollipop';
-
-/** @deprecated Use MarkType instead. Kept for internal migration references. */
-export type ChartType = MarkType;
+  | 'lollipop'
+  | 'beeswarm'
+  | 'range'
+  | 'waffle'
+  | 'calendar'
+  | 'parliament';
 
 // ---------------------------------------------------------------------------
 // Gradient definitions (Vega-aligned)
@@ -174,6 +180,19 @@ export interface MarkDef {
   innerRadius?: number;
   /** Outer radius for arc marks. */
   outerRadius?: number;
+  /**
+   * Start angle in radians for arc marks. Defaults to 0 (full pie/donut).
+   * Combined with `endAngle`, restricts the pie/donut to a partial sweep,
+   * e.g. `startAngle: -Math.PI / 2, endAngle: Math.PI / 2` for a half-donut
+   * (election-style results donut). Angles follow d3's convention: 0 is
+   * straight up, increasing clockwise. Only meaningful when `type` is `'arc'`.
+   */
+  startAngle?: number;
+  /**
+   * End angle in radians for arc marks. Defaults to 2*Math.PI (full pie/donut).
+   * See `startAngle`. Only meaningful when `type` is `'arc'`.
+   */
+  endAngle?: number;
   /** Corner radius for rect/bar marks. 'pill' sets rx to half the bar thickness. */
   cornerRadius?: number | 'pill';
   /** Fixed bar thickness in pixels for bar/column marks. When set, bars are this height (horizontal) or width (vertical), centered within the band. */
@@ -200,6 +219,99 @@ export interface MarkDef {
    * two competing diagonals.
    */
   trendline?: boolean;
+  /**
+   * Horizontal pixel offset from the data anchor. Only meaningful when `type`
+   * is `'text'`. Use it to lift a label clear of the mark it annotates instead
+   * of shifting the underlying data value.
+   */
+  dx?: number;
+  /**
+   * Vertical pixel offset from the data anchor (negative = up). Only meaningful
+   * when `type` is `'text'`. `{ type: 'text', dy: -10 }` floats each label ten
+   * pixels above its point.
+   */
+  dy?: number;
+  /** Horizontal alignment of text marks relative to their anchor. Defaults to `'center'`. */
+  align?: 'left' | 'center' | 'right';
+  /** Vertical alignment of text marks relative to their anchor. Defaults to `'middle'`. */
+  baseline?: 'top' | 'middle' | 'bottom';
+  /**
+   * Font size in pixels for text marks. Ignored when the `size` encoding channel
+   * is present (which scales font size from a data field). `size` is already
+   * taken by bar thickness, hence the distinct name.
+   */
+  fontSize?: number;
+  /**
+   * Pattern-fill reinforcement for filled marks (bar, area, arc).
+   *
+   * - `'auto'`: assign a per-series SVG pattern (diagonal hatch, dots,
+   *   crosshatch, vertical lines) layered over each series color so series
+   *   remain distinguishable without color vision. Marks too small to show
+   *   a legible pattern keep their solid fill.
+   * - `'none'` (default): solid fills only.
+   */
+  fillPattern?: 'auto' | 'none';
+  /**
+   * Visual style for range marks. Only meaningful when `type` is `'range'`.
+   * - 'dumbbell' (default): a dot at each end joined by a connector line.
+   *   The start dot is muted, the end dot carries the accent color.
+   * - 'arrow': a line with an arrowhead at the x2/y2 end, the strongest
+   *   "change between two points in time" form.
+   * - 'bar': a plain floating range bar spanning start to end.
+   */
+  style?: 'dumbbell' | 'arrow' | 'bar';
+  /**
+   * Color range marks by direction of change. Only meaningful when `type` is
+   * `'range'`. When true, increases (x2 > x, or y2 > y) use the theme's
+   * `positive` semantic color and decreases use `negative`. A field-based
+   * `encoding.color` takes precedence over direction coloring.
+   */
+  colorByDirection?: boolean;
+  /**
+   * Total number of cells in a waffle grid. Only meaningful when `type` is
+   * `'waffle'`. Category values normalize to this many cells via
+   * largest-remainder rounding so the grid always sums exactly. Default 100.
+   */
+  units?: number;
+  /**
+   * Number of columns in a waffle grid. Only meaningful when `type` is
+   * `'waffle'`. Rows derive from `units / columns`. Default 10.
+   */
+  columns?: number;
+  /**
+   * First day of the week for calendar marks. Only meaningful when `type` is
+   * `'calendar'`. Controls which weekday occupies the top row of each band.
+   * Defaults to 'monday' (ISO week convention).
+   */
+  weekStart?: 'monday' | 'sunday';
+  /**
+   * Corner radius in pixels for calendar day cells. Only meaningful when
+   * `type` is `'calendar'`. Defaults to 1.
+   */
+  cellRadius?: number;
+  /**
+   * Seat layout shape for parliament marks. Only meaningful when `type` is
+   * `'parliament'`. `'hemicycle'` (default, and currently the only shape)
+   * packs seats into concentric semicircular arcs, party-grouped left to
+   * right.
+   */
+  shape?: 'hemicycle';
+  /**
+   * Seat dot radius in pixels for parliament marks. `'auto'` (default) sizes
+   * dots to fill the available hemicycle rings for the given seat count.
+   * Only meaningful when `type` is `'parliament'`.
+   */
+  seatRadius?: number | 'auto';
+  /**
+   * The majority-threshold line and "N to win" label on parliament marks. Only
+   * meaningful when `type` is `'parliament'`. `true` (default) draws the line at
+   * a simple majority (half the seats plus one); `false` hides it. The object
+   * form overrides the threshold and label: `{ seats }` sets a custom seat count
+   * (e.g. a two-thirds supermajority) and `{ label }` overrides the default
+   * "N to win" text. A `seats` value outside `1..totalSeats` warns and falls
+   * back to the simple-majority default.
+   */
+  majorityLine?: boolean | { seats?: number; label?: string };
 }
 
 // ---------------------------------------------------------------------------
@@ -227,7 +339,11 @@ export type AggregateOp =
 export interface AxisConfig {
   /** Axis title text. If omitted, the field name is used. */
   title?: string;
-  /** Number format string (d3-format). e.g. ",.0f" for comma-separated integers. */
+  /**
+   * Number format: d3-format string (e.g. ",.0f"), or semantic keyword
+   * `'percent'` / `'currency'`. When omitted, compact notation (1k, 2.5M)
+   * is applied automatically.
+   */
   format?: string;
   /** Override tick count. Engine picks a sensible default if omitted. */
   tickCount?: number;
@@ -271,8 +387,12 @@ export interface AxisConfig {
 
 /** Scale configuration for an encoding channel. */
 export interface ScaleConfig {
-  /** Explicit domain override. Auto-derived from data if omitted. */
-  domain?: [number, number] | string[];
+  /**
+   * Explicit domain override. Auto-derived from data if omitted.
+   * Continuous scales take `[min, max]`; threshold scales take the full
+   * list of class break values; categorical scales take the value list.
+   */
+  domain?: number[] | string[];
   /** Scale type override. Usually inferred from field type. */
   type?: ScaleType;
   /** Whether to nice-ify the domain for clean tick values. Defaults to true. */
@@ -283,6 +403,15 @@ export interface ScaleConfig {
   clip?: boolean;
   /** Explicit range override. */
   range?: unknown[];
+  /**
+   * Named color scheme (Vega-Lite aligned). Resolved against the core palette
+   * registry (sequential: blue, green, orange, purple, teal; diverging:
+   * redBlue, brownTeal; categorical) during the pre-validation sugar
+   * expansion; common VL names (blues, greens, category10, ...) are accepted
+   * as aliases. Unknown names fail validation with the supported list.
+   * An explicit `range` wins over `scheme`.
+   */
+  scheme?: string;
   /** Reverse the range direction. */
   reverse?: boolean;
   /** Clamp output to the range. */
@@ -317,6 +446,30 @@ export type ScaleType =
   | 'quantize'
   | 'threshold';
 
+/**
+ * Sort a categorical domain by the aggregated values of another field
+ * (Vega-Lite EncodingSortField).
+ */
+export interface SortByField {
+  /** Data field whose values determine the category order. */
+  field: string;
+  /** Aggregate applied per category before comparing. Defaults to 'sum'. */
+  op?: AggregateOp;
+  /** Sort direction. Defaults to 'ascending'. */
+  order?: 'ascending' | 'descending';
+}
+
+/**
+ * A constant value definition for an encoding channel (Vega-Lite aligned).
+ * The VL idiom for a fixed visual property, e.g. `color: { value: '#1b7fa3' }`.
+ * Expanded to the matching mark-level property (fill/stroke, size, opacity)
+ * during the pre-validation sugar expansion.
+ */
+export interface ValueDef {
+  /** The constant value: CSS color string, size number, opacity (0-1), or gradient. */
+  value: string | number | boolean | null | GradientDef;
+}
+
 /**
  * A single encoding channel mapping a data field to a visual property.
  *
@@ -348,8 +501,11 @@ export interface EncodingChannel<TData extends DataRow = DataRow> {
   type: FieldType;
   /** Optional aggregate to apply before encoding. */
   aggregate?: AggregateOp;
-  /** Axis configuration. Set to `false` to suppress axis entirely (no space reserved). */
-  axis?: AxisConfig | false;
+  /**
+   * Axis configuration. Set to `false` to suppress axis entirely (no space
+   * reserved). `null` is accepted as a VL-aligned alias for `false`.
+   */
+  axis?: AxisConfig | false | null;
   /** Scale configuration. */
   scale?: ScaleConfig;
   /**
@@ -361,26 +517,28 @@ export interface EncodingChannel<TData extends DataRow = DataRow> {
    * The string forms are still the canonical input — the boolean shorthand is
    * normalized to the matching string before reaching layout.
    *
-   * - undefined: chart-type default (see below)
+   * - undefined: chart-type default (see below) -- stacked for bar/column/area
    * - true | 'zero': stack from zero baseline
    * - 'normalize': stack and normalize to fraction of total (0-1 per category)
    * - 'center': center stacks around zero (streamgraph style)
-   * - null | false: no stacking -- renders overlap (area) or grouped/dodged (bar)
+   * - null | false: no stacking -- renders grouped/dodged (bar) or overlap (area)
    *
    * **Defaults differ by chart type:**
-   * - **Bar/Column**: defaults to grouped (side-by-side). Use `stack: 'zero'` (or `true`) for stacked bars.
-   * - **Area**: defaults to overlap (v6 breaking change). Use `stack: 'zero'` (or `true`)
-   *   to opt into stacked areas. Each overlapping series renders as a translucent
-   *   gradient band anchored at the y-domain baseline.
+   * - **Bar/Column**: defaults to stacked (`'zero'`), Vega-Lite aligned. Use
+   *   `stack: null` (or `false`) for grouped/side-by-side bars.
+   * - **Area**: defaults to stacked (`'zero'`), Vega-Lite aligned. Use
+   *   `stack: null` (or `false`) to opt into overlap rendering, where each
+   *   series renders as a translucent gradient band anchored at the
+   *   y-domain baseline.
    * - **Line**: stacking is not applied (lines always overlap).
    *
    * @example
-   * // Stacked horizontal bars (opt-in; default is grouped):
-   * "x": { "field": "revenue", "type": "quantitative", "stack": "zero" }
+   * // Grouped horizontal bars (opt-out; default is stacked):
+   * "x": { "field": "revenue", "type": "quantitative", "stack": null }
    *
    * @example
-   * // Stacked area (opt-in; default is overlap):
-   * "y": { "field": "value", "type": "quantitative", "stack": "zero" }
+   * // Overlap area (opt-out; default is stacked):
+   * "y": { "field": "value", "type": "quantitative", "stack": null }
    */
   stack?: boolean | 'zero' | 'normalize' | 'center' | null;
   /**
@@ -403,8 +561,22 @@ export interface EncodingChannel<TData extends DataRow = DataRow> {
    * - 'descending': sort domain values descending
    * - null: use data order (no sorting)
    * - undefined: ascending (VL default)
+   * - 'x' | '-x' | 'y' | '-y': sort by another channel's values ('-' prefix
+   *   for descending). The VL ranked-bar idiom: `sort: '-y'` orders categories
+   *   by value, largest first. Resolved into an explicit domain during the
+   *   pre-validation sugar expansion.
+   * - string[]: explicit value order. Listed values come first (in the given
+   *   order); unlisted data values follow in data order.
+   * - SortByField: sort by the aggregated values of another field.
    */
-  sort?: 'ascending' | 'descending' | null;
+  sort?: 'ascending' | 'descending' | null | 'x' | '-x' | 'y' | '-y' | string[] | SortByField;
+  /**
+   * Legend configuration for this channel (Vega-Lite aligned).
+   * Only meaningful on the `color` channel. `null` hides the legend (the VL
+   * idiom for `legend.show = false`); a config object merges into the
+   * top-level `legend` (top-level keys win on conflict).
+   */
+  legend?: LegendConfig | null;
   /**
    * Display title override (Vega-Lite aligned).
    * Used as the label in tooltips instead of the raw field name.
@@ -413,7 +585,8 @@ export interface EncodingChannel<TData extends DataRow = DataRow> {
   title?: string;
   /**
    * Format string for values (Vega-Lite aligned).
-   * For quantitative fields: d3-format string (e.g. ",.0f", "$,.2f").
+   * For quantitative fields: d3-format string (e.g. ",.0f", "$,.2f"),
+   * or semantic keyword `'percent'` / `'currency'`.
    * For temporal fields: d3-time-format string (e.g. "%Y", "%b %d").
    * Used in tooltips; `axis.format` takes precedence for axis tick labels.
    */
@@ -475,14 +648,16 @@ export interface Encoding<TData extends DataRow = DataRow> {
   /**
    * Color channel. Required for arc marks (determines pie/donut slice coloring).
    * Optional for all other marks -- used for series differentiation on multi-series charts,
-   * or heatmap intensity. Accepts a conditional definition to apply colors based on data predicates.
+   * or heatmap intensity. Accepts a conditional definition to apply colors based on data predicates,
+   * or a bare `{ value }` constant (VL aligned; expanded to the mark-level fill/stroke).
    */
-  color?: EncodingChannel<TData> | ConditionalValueDef<TData>;
+  color?: EncodingChannel<TData> | ConditionalValueDef<TData> | ValueDef;
   /**
    * Size channel. Used by point/bubble charts to scale dot area by a quantitative field.
-   * Accepts a conditional definition to vary size based on data predicates.
+   * Accepts a conditional definition to vary size based on data predicates,
+   * or a bare `{ value }` constant (VL aligned; expanded to `mark.size`).
    */
-  size?: EncodingChannel<TData> | ConditionalValueDef<TData>;
+  size?: EncodingChannel<TData> | ConditionalValueDef<TData> | ValueDef;
   /**
    * Detail channel. Groups data into multiple series without mapping to a visual property.
    * Useful when you want separate lines per category but don't need the color to differ.
@@ -506,17 +681,14 @@ export interface Encoding<TData extends DataRow = DataRow> {
   y2?: EncodingChannel<TData>;
   /**
    * Data-driven opacity (0-1 range). Accepts a conditional definition to vary opacity
-   * based on data predicates (e.g., highlight selected points).
-   */
-  opacity?: EncodingChannel<TData> | ConditionalValueDef<TData>;
-  /**
-   * Point shape encoding. Valid values: 'circle', 'square', 'diamond', 'triangle-up',
-   * 'triangle-down', 'cross'. Used on point/scatter marks to differentiate series by shape.
+   * based on data predicates (e.g., highlight selected points), or a bare `{ value }`
+   * constant (VL aligned; expanded to `mark.opacity`).
    */
-  shape?: EncodingChannel<TData>;
+  opacity?: EncodingChannel<TData> | ConditionalValueDef<TData> | ValueDef;
   /**
-   * Stroke dash pattern encoding. Maps a nominal field to different dash patterns
-   * on line marks. Useful when color alone doesn't distinguish series well.
+   * Stroke dash pattern encoding. Maps a nominal/ordinal field to different
+   * dash patterns on line and rule marks. Useful when color alone doesn't
+   * distinguish series well.
    */
   strokeDash?: EncodingChannel<TData>;
   /** Rotation angle encoding for point marks. Maps a quantitative field to 0-360 degrees. */
@@ -531,25 +703,15 @@ export interface Encoding<TData extends DataRow = DataRow> {
    * multi-field tooltips. Independent of the x/y/color encoding.
    */
   tooltip?: EncodingChannel<TData> | EncodingChannel<TData>[];
-  /** Hyperlink encoding. Maps a field containing URLs to clickable marks. */
-  href?: EncodingChannel<TData>;
   /**
-   * Drawing order. Controls z-order and stacking sort order for bar/area marks.
-   * Lower values are drawn first (behind higher values).
-   */
-  order?: EncodingChannel<TData>;
-  /**
-   * Angular position for arc marks (pie/donut).
-   * Optional -- defaults to the `y` channel value when omitted.
-   * Not used by any other mark type.
+   * Angular position (slice value) for arc marks (pie/donut), the canonical
+   * value channel in v8. Waffle and parliament marks accept it too (the same
+   * part-to-whole value channel). `y` is still accepted on these marks as a
+   * deprecated alias for backward compatibility (a compile warning is emitted
+   * and `y` is populated from `theta` internally). Not used by any other mark
+   * type.
    */
   theta?: EncodingChannel<TData>;
-  /**
-   * Radial distance from center for arc marks.
-   * Optional -- only meaningful on donut charts (controls inner radius boundary).
-   * Not used by any other mark type.
-   */
-  radius?: EncodingChannel<TData>;
   /**
    * Facet channel: partitions data into a grid of small-multiple panels.
    * Each unique value of the facet field produces one panel. Panels share
@@ -682,15 +844,26 @@ export interface AnnotationOffset {
 /** Anchor direction for annotation label placement relative to the data point. */
 export type AnnotationAnchor = 'top' | 'bottom' | 'left' | 'right' | 'auto';
 
-/** Style overrides for the dot marker drawn at the connector's data-point endpoint. */
+/** Connector type for annotation labels. */
+export type ConnectorType = 'straight' | 'curve' | 'drop-line';
+
+/** Object form of the connector config, allowing arrow control. */
+export interface ConnectorConfig {
+  /** Connector style. */
+  type: ConnectorType;
+  /** Whether to draw an arrowhead at the data-point end. Default: true for curve, false for straight. Drop-line never takes a head. */
+  arrow?: boolean;
+}
+
+/** Style overrides for the dot marker drawn at the data point. */
 export interface AnnotationDot {
-  /** Circle radius in pixels. Default 5. */
+  /** Circle radius in pixels. Default 4. */
   radius?: number;
   /** Fill color. Defaults to theme background for an "open ring" look. */
   fill?: string;
-  /** Stroke color. Defaults to theme text color. */
+  /** Stroke color. Defaults to the connector's resolved stroke, so marker and leader read as one system. */
   stroke?: string;
-  /** Stroke width in pixels. Default 2. */
+  /** Stroke width in pixels. Default 1.5. */
   strokeWidth?: number;
 }
 
@@ -722,7 +895,13 @@ export interface TextAnnotation extends AnnotationBase {
   x: string | number;
   /** Y-axis data value or position. */
   y: string | number;
-  /** The annotation text. Required for text annotations. */
+  /**
+   * The annotation text. Required for text annotations.
+   *
+   * Supports inline `**bold**` spans, so emphasis lands on the key phrase rather
+   * than the whole block: `'Inflation peaked at **8.5%**'`. Unmatched `**` (and
+   * empty `****`) render literally. `\n` starts a new line.
+   */
   text: string;
   /** Thinning priority (lower = kept longer at narrow widths). When omitted, spec order is used. */
   priority?: number;
@@ -730,12 +909,23 @@ export interface TextAnnotation extends AnnotationBase {
    * Optional muted second-tone text rendered below the primary `text`.
    * Used for supporting context (e.g. methodology, source). Newlines in
    * `text` still produce multi-line primary; subtitle is a separate block.
+   *
+   * Supports the same inline `**bold**` spans as `text`. When a subtitle is
+   * present and no `fontWeight` is set, the primary `text` resolves to weight
+   * 700 — the lede + context stack.
    */
   subtitle?: string;
   /**
-   * Optional dot marker drawn at the connector's data-point endpoint.
-   * `true` enables the default open-ring style. Pass an object to override
-   * radius, fill, stroke, or strokeWidth.
+   * Open-ring marker drawn on the data point itself (not on the pulled-back
+   * connector tip).
+   *
+   * Left unset, a default marker appears whenever a connector is enabled and
+   * carries no arrowhead — the leader points, the ring lands. An arrowed
+   * connector gets no marker unless you ask for one: the head already marks the
+   * spot. `dot: false` is always bare; an explicit `dot` always wins.
+   *
+   * `true` uses the default style; pass an object to override radius, fill,
+   * stroke, or strokeWidth.
    */
   dot?: boolean | AnnotationDot;
   /** Font size override. */
@@ -748,13 +938,19 @@ export interface TextAnnotation extends AnnotationBase {
   anchor?: AnnotationAnchor;
   /**
    * Connector from label to anchor point.
-   * - `true` (default): straight line
-   * - `'straight'`: straight line (alias of `true`)
+   * - `true` (default): straight line, no arrow
+   * - `'straight'`: straight line, no arrow
    * - `'curve'`: curved arrow with arrowhead
-   * - `'drop-line'`: vertical line through the data point's x; label sits beside the line and auto-flips to the opposite side if it would overflow the chart area
+   * - `'drop-line'`: vertical line through the data point's x
+   * - `{ type, arrow? }`: object form for explicit arrow control
    * - `false`: no connector
+   *
+   * The connector leaves the text block on the side facing the data point, with
+   * a small standoff gap. A leader shorter than 8px is dropped as noise (the
+   * marker alone reads better), as is a connector whose target sits inside the
+   * text block. Widen `offset` if you want the line back.
    */
-  connector?: boolean | 'straight' | 'curve' | 'drop-line';
+  connector?: boolean | ConnectorType | ConnectorConfig;
   /** Per-endpoint offsets for the connector line. Allows fine-tuning where the connector starts and ends. */
   connectorOffset?: {
     /** Offset for the label-end of the connector. */
@@ -762,8 +958,14 @@ export interface TextAnnotation extends AnnotationBase {
     /** Offset for the data-point-end of the connector. */
     to?: AnnotationOffset;
   };
-  /** Background color behind the text. Useful for readability over chart lines. */
-  background?: string;
+  /**
+   * Background plate behind the text, for readability over chart lines.
+   *
+   * `true` uses the theme surface, so the plate follows light/dark mode. A
+   * color string sets it explicitly. Prefer `true`: a hardcoded '#ffffff' stays
+   * white in dark mode and the text turns light-gray-on-white.
+   */
+  background?: string | true;
   /** Whether to show the paint-order stroke halo behind text. Default true. Set false for white text on colored backgrounds. */
   halo?: boolean;
 }
@@ -807,7 +1009,14 @@ export interface RangeAnnotation extends AnnotationBase {
  * Useful for baselines (zero), targets, or thresholds.
  */
 export interface RefLineAnnotation extends AnnotationBase {
-  type: 'refline' | 'rule';
+  /**
+   * Discriminant. `'refline'` is canonical and the only value in the type.
+   * `'rule'` (it collides with the `rule` mark type) is still accepted at
+   * runtime for backward compatibility -- the spec-sugar pass rewrites it to
+   * `'refline'` with a deprecation warning before validation -- but it is not
+   * part of this type. Use `'refline'`.
+   */
+  type: 'refline';
   /** X-axis value for a vertical reference line. */
   x?: string | number;
   /** Y-axis value for a horizontal reference line. */
@@ -1007,7 +1216,11 @@ export interface LabelConfig {
   suffix?: string;
   /** Fixed CSS color for all labels. Overrides the default fill-derived color. */
   color?: string;
-  /** Per-series pixel offsets for fine-tuning label positions, keyed by series name. */
+  /**
+   * Per-series pixel offsets for fine-tuning label positions, keyed by series name.
+   * @deprecated Per-series pixel offsets are a workaround for collision bugs
+   * now fixed by the layout engine. Will be removed in a future version.
+   */
   offsets?: Record<string, AnnotationOffset>;
   /** Font size in pixels for bar/column value labels. */
   fontSize?: number;
@@ -1038,6 +1251,46 @@ export interface LegendConfig {
   exclude?: string[];
 }
 
+/**
+ * Configuration for the searchable series highlight input (`seriesSearch`).
+ * The boolean form (`seriesSearch: true`) uses the defaults.
+ */
+export interface SeriesSearchConfig {
+  /** Placeholder text for the search input. Defaults to "Find a series". */
+  placeholder?: string;
+}
+
+/**
+ * Configuration for the "you draw it" interactive engagement format
+ * (`youDrawIt`). The reader draws their guess of the trend from `from` to the
+ * right edge before the real line reveals. Line marks only, single-series only.
+ */
+export interface YouDrawItConfig {
+  /**
+   * The x value (matching `encoding.x`'s domain) where drawing starts. Data
+   * before this point renders normally; data at or after it is hidden behind
+   * a hatched "draw here" region until reveal.
+   */
+  from: string | number;
+  /** Prompt text shown in the hatched drawing region. Defaults to "Draw your guess". */
+  prompt?: string;
+  /** Label for the skip-to-reveal button. Defaults to "Show me". */
+  revealLabel?: string;
+  /**
+   * Optional extra comparison line (e.g. "what everyone else guessed"),
+   * supplied by the host app. Rendered in a third, visually distinct style
+   * alongside the reader's guess and the real line after reveal.
+   */
+  comparisonLine?: Array<{ x: string | number; y: number }>;
+}
+
+/**
+ * Content composition for an endpoint-label entry: the series name, the
+ * formatted value, or both joined on one line. See
+ * {@link EndpointLabelsConfig.content}.
+ */
+export type EndpointLabelContent = 'label' | 'value' | 'label value';
+
 /**
  * Configuration for the endpoint labels column rendered at the chart's right edge
  * for multi-series line/area charts. Each entry pairs the series name with its
@@ -1075,6 +1328,20 @@ export interface EndpointLabelsConfig {
    * - `'both'`: labels on both left (leading) and right (trailing) edges.
    */
   ends?: 'end' | 'both';
+  /**
+   * What each entry renders.
+   * - `'label'`: series name only.
+   * - `'value'`: formatted value only.
+   * - `'label value'`: series name and value joined on one line.
+   *
+   * When omitted, entries render the series name with the formatted value on
+   * a second line (the classic endpoint column). Pass an object to set the
+   * leading and trailing columns independently, e.g. the classic slope-chart
+   * look is `{ leading: 'label value', trailing: 'value' }`.
+   */
+  content?:
+    | EndpointLabelContent
+    | { leading?: EndpointLabelContent; trailing?: EndpointLabelContent };
   /** Field to read the displayed value from. Defaults to `encoding.y.field`. */
   valueField?: string;
   /** d3-format string for the value. Defaults to `encoding.y.axis.format`. */
@@ -1250,14 +1517,14 @@ export interface Metric {
 
 /**
  * Encoding for arc marks (pie/donut charts).
- * - `y`: required (quantitative — the slice value)
+ * - `theta`: required (quantitative — the canonical slice value channel)
  * - `color`: required (nominal/ordinal — the category)
- * - `theta`: optional (defaults to `y` channel)
- * - `radius`: optional (donut inner radius)
+ * - `y`: deprecated alias for `theta`, accepted for backward compatibility
  */
 export interface ArcEncoding<TData extends DataRow = DataRow> extends Encoding<TData> {
-  y: EncodingChannel<TData>;
-  color: EncodingChannel<TData>;
+  /** Canonical value channel for arc marks (quantitative — the slice value). */
+  theta: EncodingChannel<TData>;
+  color: EncodingChannel<TData> | ConditionalValueDef<TData>;
 }
 
 /**
@@ -1320,6 +1587,67 @@ export interface LollipopEncoding<TData extends DataRow = DataRow> extends Encod
   y: EncodingChannel<TData>;
 }
 
+/**
+ * Encoding for beeswarm marks (dodged distribution dots).
+ * - Exactly one positional channel is quantitative: the value axis
+ *   (x = horizontal swarm, y = vertical swarm).
+ * - The other positional channel is optional (nominal/ordinal): grouped
+ *   swarms, one lane per category. The cross axis has no scale; the dodge
+ *   layout computes pixel offsets around each lane center.
+ */
+export interface BeeswarmEncoding<TData extends DataRow = DataRow> extends Encoding<TData> {
+  x?: EncodingChannel<TData>;
+  y?: EncodingChannel<TData>;
+}
+
+/**
+ * Encoding for range marks (dumbbell / arrow / range-bar plots).
+ * - Horizontal (the common editorial form): `y` nominal/ordinal category,
+ *   `x` quantitative start, `x2` quantitative end.
+ * - Vertical: `x` nominal/ordinal category, `y` quantitative start,
+ *   `y2` quantitative end.
+ */
+export interface RangeEncoding<TData extends DataRow = DataRow> extends Encoding<TData> {
+  x: EncodingChannel<TData>;
+  y: EncodingChannel<TData>;
+}
+
+/**
+ * Encoding for waffle marks (unit grids for part-to-whole counts).
+ * - `color`: required (nominal/ordinal, the category)
+ * - `theta`: the canonical quantitative share, the same part-to-whole value
+ *   channel arc marks use. `y` is a deprecated alias, accepted for backward
+ *   compatibility.
+ */
+export interface WaffleEncoding<TData extends DataRow = DataRow> extends Encoding<TData> {
+  color: EncodingChannel<TData> | ConditionalValueDef<TData>;
+}
+
+/**
+ * Encoding for parliament marks (hemicycle seat-dot charts).
+ * - `color`: required (nominal/ordinal, the party)
+ * - `theta`: the canonical quantitative seat count, the same part-to-whole
+ *   value channel arc/waffle marks use. `y` is a deprecated alias, accepted
+ *   for backward compatibility.
+ */
+export interface ParliamentEncoding<TData extends DataRow = DataRow> extends Encoding<TData> {
+  color: EncodingChannel<TData> | ConditionalValueDef<TData>;
+}
+
+/**
+ * Encoding for calendar marks (GitHub-style calendar heatmaps).
+ * - `x`: required (temporal, daily dates, one row per day)
+ * - `color`: required (quantitative, the per-day value)
+ *
+ * The calendar computes its own weeks-x-weekdays geometry: no positional
+ * scales or axes. Multi-year data partitions into one stacked band per year,
+ * all bands sharing a single color scale and legend.
+ */
+export interface CalendarEncoding<TData extends DataRow = DataRow> extends Encoding<TData> {
+  x: EncodingChannel<TData>;
+  color: EncodingChannel<TData>;
+}
+
 /**
  * Encoding for text marks (data-positioned labels).
  * - `text`: required (the field to render as text)
@@ -1349,6 +1677,33 @@ export interface RectEncoding<TData extends DataRow = DataRow> extends Encoding<
   y: EncodingChannel<TData>;
 }
 
+// ---------------------------------------------------------------------------
+// Accessibility configuration
+// ---------------------------------------------------------------------------
+
+/**
+ * Author-facing accessibility overrides.
+ *
+ * Everything here is optional; when omitted, openchart auto-generates alt
+ * text, ARIA labels, and a screen-reader data table from the spec and data.
+ */
+export interface A11yConfig {
+  /**
+   * Alt text announced by screen readers for the chart as a whole. Replaces
+   * the auto-generated description. Also settable via the top-level
+   * `description` field (Vega-Lite convention); this field wins when both
+   * are present.
+   */
+  description?: string;
+  /**
+   * Hide the chart from assistive technology entirely (`aria-hidden`).
+   * Use only when the chart is decorative or the surrounding content
+   * already conveys the same information. Also suppresses the hidden
+   * screen-reader data table and keyboard mark navigation.
+   */
+  hidden?: boolean;
+}
+
 // ---------------------------------------------------------------------------
 // Shared (non-mark-specific) ChartSpec properties
 // ---------------------------------------------------------------------------
@@ -1360,12 +1715,44 @@ export interface RectEncoding<TData extends DataRow = DataRow> extends Encoding<
  * @internal
  */
 interface BaseChartSpec<TData extends DataRow = DataRow> {
-  /** Data array: each element is a row with field values. */
+  /**
+   * Data array: each element is a row with field values.
+   * The Vega-Lite object form `{ values: [...] }` is also accepted at runtime
+   * and unwrapped during the pre-validation sugar expansion. `{ url }` is not
+   * supported (openchart does not fetch data).
+   */
   data: TData[];
   /** Data transforms applied in order before encoding (filter, bin, calculate, timeUnit). */
   transform?: Transform[];
   /** Editorial chrome (title, subtitle, source, etc.). */
   chrome?: Chrome;
+  /**
+   * Top-level title sugar (Vega-Lite aligned). Expanded into `chrome.title`
+   * (and `chrome.subtitle` for the object form). `chrome.title` wins when
+   * both are set.
+   */
+  title?: string | { text: string; subtitle?: string };
+  /** Top-level subtitle sugar. Expanded into `chrome.subtitle`; `chrome.subtitle` wins. */
+  subtitle?: string;
+  /**
+   * Alt text for the rendered chart (Vega-Lite aligned). Sugar for
+   * `a11y.description`; `a11y.description` wins when both are set.
+   * When absent, alt text is auto-generated from the spec and data.
+   */
+  description?: string;
+  /** Accessibility overrides. See {@link A11yConfig}. */
+  a11y?: A11yConfig;
+  /**
+   * Fixed render width in pixels (Vega-Lite aligned). Overrides the
+   * container-derived width. When both `width` and `height` are set,
+   * `responsive: false` is implied unless `responsive` is set explicitly.
+   * Omit for the default container-driven sizing.
+   */
+  width?: number;
+  /** Fixed render height in pixels (Vega-Lite aligned). See `width`. */
+  height?: number;
+  /** Accepted for Vega-Lite compatibility and ignored (with a compile warning). */
+  $schema?: string;
   /**
    * KPI/metric cells rendered as a horizontal row between subtitle and chart
    * area. Each cell shows a label/value pair with optional delta and secondary
@@ -1426,6 +1813,22 @@ interface BaseChartSpec<TData extends DataRow = DataRow> {
    * explicitly set.
    */
   crosshair?: boolean;
+  /**
+   * Searchable series highlight ("find your country"). Renders a compact
+   * search input above the chart with typeahead over the color channel's
+   * distinct values. Selecting a value adds it to the highlight set
+   * (multi-select chips, removable); clearing restores the authored
+   * `encoding.color.highlight` baseline. Requires a categorical color
+   * encoding. Mutually exclusive with edit mode (search wins).
+   */
+  seriesSearch?: boolean | SeriesSearchConfig;
+  /**
+   * "You draw it" interactive engagement format: the reader draws their
+   * guess of the trend before the real line reveals. Line marks only,
+   * single-series only. Mutually exclusive with edit mode (validation
+   * warning if both are enabled; youDrawIt is disabled).
+   */
+  youDrawIt?: YouDrawItConfig;
   /**
    * Display mode controlling how much chart chrome is rendered.
    *
@@ -1521,6 +1924,18 @@ export type ChartSpec<TData extends DataRow = DataRow> =
       mark: 'lollipop' | (MarkDef & { type: 'lollipop' });
       encoding: LollipopEncoding<TData>;
     })
+  | (BaseChartSpec<TData> & {
+      mark: 'beeswarm' | (MarkDef & { type: 'beeswarm' });
+      encoding: BeeswarmEncoding<TData>;
+    })
+  | (BaseChartSpec<TData> & {
+      mark: 'range' | (MarkDef & { type: 'range' });
+      encoding: RangeEncoding<TData>;
+    })
+  | (BaseChartSpec<TData> & {
+      mark: 'waffle' | (MarkDef & { type: 'waffle' });
+      encoding: WaffleEncoding<TData>;
+    })
   | (BaseChartSpec<TData> & {
       mark: 'text' | (MarkDef & { type: 'text' });
       encoding: TextEncoding<TData>;
@@ -1536,6 +1951,14 @@ export type ChartSpec<TData extends DataRow = DataRow> =
   | (BaseChartSpec<TData> & {
       mark: 'rule' | (MarkDef & { type: 'rule' });
       encoding: Encoding<TData>;
+    })
+  | (BaseChartSpec<TData> & {
+      mark: 'calendar' | (MarkDef & { type: 'calendar' });
+      encoding: CalendarEncoding<TData>;
+    })
+  | (BaseChartSpec<TData> & {
+      mark: 'parliament' | (MarkDef & { type: 'parliament' });
+      encoding: ParliamentEncoding<TData>;
     });
 
 /**
@@ -1676,6 +2099,16 @@ export interface LayerSpec<TData extends DataRow = DataRow> {
   transform?: Transform[];
   /** Editorial chrome (title, subtitle, source, etc.). */
   chrome?: Chrome;
+  /** Top-level title sugar (VL aligned). Expanded into `chrome.title`; `chrome.title` wins. */
+  title?: string | { text: string; subtitle?: string };
+  /** Top-level subtitle sugar. Expanded into `chrome.subtitle`; `chrome.subtitle` wins. */
+  subtitle?: string;
+  /** Fixed render width in pixels (VL aligned). Overrides the container-derived width. */
+  width?: number;
+  /** Fixed render height in pixels (VL aligned). Overrides the container-derived height. */
+  height?: number;
+  /** Accepted for Vega-Lite compatibility and ignored (with a compile warning). */
+  $schema?: string;
   /** Annotations on the layered view. */
   annotations?: Annotation[];
   /** Label display configuration. `false` disables all labels, `true` uses defaults. */
@@ -1774,6 +2207,8 @@ export interface SankeySpec {
    * number (data value 28 renders as "28%"). For currency: "$,.0f" or "$~s".
    * For SI suffixes: "~s" (renders 1000 as "1k"). When not set, values use
    * the default number formatter.
+   * @deprecated Use the encoding channel's `format` field instead. This
+   * property is expanded into the encoding during compilation.
    */
   valueFormat?: string;
 }
@@ -1840,6 +2275,72 @@ export interface TileMapSpec {
   /**
    * d3-format string applied to tile values, legend labels, and tooltips.
    * Examples: ".1f" for one decimal, "$,.0f" for currency, "~s" for SI.
+   * @deprecated Use the encoding channel's `format` field instead. This
+   * property is expanded into the encoding during compilation.
+   */
+  valueFormat?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Map spec (choropleth / symbol maps)
+// ---------------------------------------------------------------------------
+
+/** Supported map projections. */
+export type MapProjection = 'albersUsa' | 'mercator' | 'equalEarth' | 'identity';
+
+/** Focus target for map camera: feature id(s) to zoom/pan to. */
+export type MapFocus =
+  | string
+  | number
+  | Array<string | number>
+  | { features: string | number | Array<string | number>; padding?: number };
+
+/** Geo configuration for map specs. */
+export interface MapGeo {
+  /** TopoJSON topology object. User imports this from us-atlas, world-atlas, or their own source. */
+  features: unknown;
+  /** Field in the TopoJSON feature properties to use as the join key. Defaults to 'id'. */
+  idField?: string;
+  /** Map projection. Defaults to 'albersUsa'. */
+  projection?: MapProjection;
+  /** Focus on specific feature(s). null clears focus from a prior story step. */
+  focus?: MapFocus | null;
+}
+
+/** Encoding channels specific to map visualizations. */
+export interface MapEncoding {
+  /** Join key field in the data (required). Maps data rows to geo features via geo.idField. */
+  key: EncodingChannel;
+  /** Color encoding (required, quantitative or nominal). Drives fill color of features. */
+  color: EncodingChannel;
+  /** Tooltip encoding (optional). */
+  tooltip?: EncodingChannel | EncodingChannel[];
+}
+
+export interface MapSpec {
+  /** Discriminant: always "map". */
+  type: 'map';
+  /** Geo configuration: TopoJSON features, join key, and projection. */
+  geo: MapGeo;
+  /** Tabular data to join to geo features. */
+  data: DataRow[];
+  /** Encoding channels mapping data fields to visual properties. */
+  encoding: MapEncoding;
+  /** Editorial chrome (title, subtitle, source, byline, footer). */
+  chrome?: Chrome;
+  /** Legend display configuration. */
+  legend?: LegendConfig;
+  /** Theme configuration overrides. */
+  theme?: ThemeConfig;
+  /** Dark mode behavior. Defaults to "off". */
+  darkMode?: DarkMode;
+  /** Whether to show the tryOpenData.ai watermark. Defaults to true. */
+  watermark?: boolean;
+  /** Animation configuration for entrance animations. */
+  animation?: AnimationSpec;
+  /**
+   * d3-format string applied to color values in tooltips and legend.
+   * @deprecated Use the encoding channel's `format` field instead.
    */
   valueFormat?: string;
 }
@@ -1877,6 +2378,8 @@ export interface BarListSpec {
   /**
    * d3-format string applied to bar values and tooltips.
    * Examples: ".1f" for one decimal, "$,.0f" for currency, "~s" for SI.
+   * @deprecated Use the encoding channel's `format` field instead. This
+   * property is expanded into the encoding during compilation.
    */
   valueFormat?: string;
 }
@@ -1904,7 +2407,15 @@ export interface BarListEncoding {
  * - GraphSpec: has `type: 'graph'`
  * - SankeySpec: has `type: 'sankey'`
  * - TileMapSpec: has `type: 'tilemap'`
+ * - MapSpec: has `type: 'map'`
  * - BarListSpec: has `type: 'barlist'`
+ *
+ * Election parliament (hemicycle) charts are `ChartSpec` with `mark:
+ * 'parliament'`, not a separate top-level type: seat data (party + seats)
+ * maps naturally onto encoding.color/y like arc and waffle, and riding the
+ * existing chart pipeline gets scales, legend, tooltips, a11y, and dark mode
+ * for free instead of a second bespoke compile path (see
+ * `packages/engine/src/charts/parliament/`).
  */
 export type VizSpec =
   | ChartSpec
@@ -1913,6 +2424,7 @@ export type VizSpec =
   | GraphSpec
   | SankeySpec
   | TileMapSpec
+  | MapSpec
   | BarListSpec;
 
 /**
@@ -1928,6 +2440,8 @@ export type GraphSpecWithoutData = Omit<GraphSpec, 'nodes' | 'edges'>;
 export type SankeySpecWithoutData = Omit<SankeySpec, 'data'>;
 /** TileMap spec without runtime data, for persistence/storage. */
 export type TileMapSpecWithoutData = Omit<TileMapSpec, 'data'>;
+/** Map spec without runtime data, for persistence/storage. */
+export type MapSpecWithoutData = Omit<MapSpec, 'data'>;
 /** BarList spec without runtime data, for persistence/storage. */
 export type BarListSpecWithoutData = Omit<BarListSpec, 'data'>;
 /** Union of data-stripped spec types for persistence/storage. */
@@ -1937,6 +2451,7 @@ export type StoredVizSpec =
   | GraphSpecWithoutData
   | SankeySpecWithoutData
   | TileMapSpecWithoutData
+  | MapSpecWithoutData
   | BarListSpecWithoutData;
 
 // ---------------------------------------------------------------------------
@@ -2144,9 +2659,10 @@ export interface Condition<TData extends DataRow = DataRow> {
   test: FilterPredicate;
   /**
    * Static value to use when the condition is true.
-   * Accepted values: CSS color string, opacity (0-1), size number, or boolean flag.
+   * Accepted values: CSS color string, opacity (0-1), size number, boolean flag,
+   * or a gradient definition for color channels.
    */
-  value?: string | number | boolean | null;
+  value?: string | number | boolean | null | GradientDef;
   /**
    * Data field to use when the condition is true.
    * Constrained to column names of `TData` when using `ChartSpec<TData>`.
@@ -2167,18 +2683,19 @@ export interface ConditionalValueDef<TData extends DataRow = DataRow> {
   condition: Condition<TData> | Condition<TData>[];
   /**
    * Default value when no condition matches.
-   * Accepted values: CSS color string, opacity (0-1), size number, or boolean flag.
+   * Accepted values: CSS color string, opacity (0-1), size number, boolean flag,
+   * or a gradient definition for color channels.
    */
-  value?: string | number | boolean | null;
+  value?: string | number | boolean | null | GradientDef;
 }
 
 /**
  * Check if a channel definition is a regular EncodingChannel (has 'field' at top level).
- * Use this to narrow `EncodingChannel | ConditionalValueDef` in encoding channels
- * that support conditional encoding (color, size, opacity).
+ * Use this to narrow `EncodingChannel | ConditionalValueDef | ValueDef` in encoding
+ * channels that support conditional encoding (color, size, opacity).
  */
 export function isEncodingChannel<TData extends DataRow = DataRow>(
-  def: EncodingChannel<TData> | ConditionalValueDef<TData> | undefined,
+  def: EncodingChannel<TData> | ConditionalValueDef<TData> | ValueDef | undefined,
 ): def is EncodingChannel<TData> {
   if (!def) return false;
   return 'field' in def && !('condition' in def);
@@ -2188,12 +2705,24 @@ export function isEncodingChannel<TData extends DataRow = DataRow>(
  * Check if a channel definition is a ConditionalValueDef.
  */
 export function isConditionalDef<TData extends DataRow = DataRow>(
-  def: EncodingChannel<TData> | ConditionalValueDef<TData> | undefined,
+  def: EncodingChannel<TData> | ConditionalValueDef<TData> | ValueDef | undefined,
 ): def is ConditionalValueDef<TData> {
   if (!def) return false;
   return 'condition' in def;
 }
 
+/**
+ * Check if a channel definition is a bare ValueDef (constant value, no field
+ * or condition). These are expanded to mark-level properties during the
+ * pre-validation sugar expansion.
+ */
+export function isValueDef<TData extends DataRow = DataRow>(
+  def: EncodingChannel<TData> | ConditionalValueDef<TData> | ValueDef | undefined,
+): def is ValueDef {
+  if (!def) return false;
+  return 'value' in def && !('condition' in def) && !('field' in def);
+}
+
 // ---------------------------------------------------------------------------
 // Mark type helpers
 // ---------------------------------------------------------------------------
@@ -2211,10 +2740,25 @@ export const MARK_TYPES: ReadonlySet<string> = new Set<MarkType>([
   'tick',
   'rect',
   'lollipop',
+  'beeswarm',
+  'range',
+  'waffle',
+  'calendar',
+  'parliament',
 ]);
 
-/** @deprecated Use MARK_TYPES instead. */
-export const CHART_TYPES = MARK_TYPES;
+/**
+ * Mark types that lay out inside the chart area without positional axes
+ * (no axis or gridline computation; margins shrink to padding).
+ */
+export function isAxislessMark(markType: MarkType): boolean {
+  return (
+    markType === 'arc' ||
+    markType === 'waffle' ||
+    markType === 'calendar' ||
+    markType === 'parliament'
+  );
+}
 
 /**
  * Extract the mark type string from a mark field (string or MarkDef).
@@ -2269,6 +2813,11 @@ export function isBarListSpec(spec: VizSpec | Record<string, unknown>): spec is
   return 'type' in spec && (spec as Record<string, unknown>).type === 'barlist';
 }
 
+/** Check if a spec is a MapSpec. */
+export function isMapSpec(spec: VizSpec | Record<string, unknown>): spec is MapSpec {
+  return 'type' in spec && (spec as Record<string, unknown>).type === 'map';
+}
+
 // ---------------------------------------------------------------------------
 // Annotation type guards
 // ---------------------------------------------------------------------------
@@ -2283,9 +2832,14 @@ export function isRangeAnnotation(annotation: Annotation): annotation is RangeAn
   return annotation.type === 'range';
 }
 
-/** Check if an annotation is a RefLineAnnotation. */
+/**
+ * Check if an annotation is a RefLineAnnotation. Also accepts the deprecated
+ * `'rule'` type at runtime (pre-sugar-expansion input), since `annotation.type`
+ * may not yet be narrowed to the canonical `'refline'` form.
+ */
 export function isRefLineAnnotation(annotation: Annotation): annotation is RefLineAnnotation {
-  return annotation.type === 'refline' || annotation.type === 'rule';
+  const type: string = annotation.type;
+  return type === 'refline' || type === 'rule';
 }
 
 // ---------------------------------------------------------------------------
@@ -2305,4 +2859,9 @@ export const MARK_DISPLAY_NAMES: Record<MarkType, string> = {
   tick: 'Tick plot',
   rect: 'Heatmap',
   lollipop: 'Lollipop chart',
+  beeswarm: 'Beeswarm chart',
+  range: 'Range plot',
+  waffle: 'Waffle chart',
+  calendar: 'Calendar heatmap',
+  parliament: 'Parliament chart',
 };