@opendata-ai/openchart-core 6.28.5 → 7.0.0

package/src/types/spec.ts

@@ -147,10 +147,13 @@ export interface MarkDef {
    * Show point markers on line/area marks.
    * - true: filled circles at each data point
    * - 'transparent': invisible hover targets (legacy behavior)
-   * - 'endpoints': show only first and last point per series
+   * - 'endpoints': show only first and last point per series (hollow dots)
+   * - 'last' / 'first': show only the last (or first) point — filled dot,
+   *   no white halo. Useful for highlighting the latest reading on a line
+   *   chart and the default for sparkline mode.
    * - false: no point marks (default; uses voronoi overlay for tooltips)
    */
-  point?: boolean | 'transparent' | 'endpoints';
+  point?: boolean | 'transparent' | 'endpoints' | 'last' | 'first';
   /**
    * Curve interpolation for line/area marks.
    * Maps to d3-shape curve factories.
@@ -245,6 +248,14 @@ export interface AxisConfig {
   labelColor?: string;
   /** Secondary data field to display alongside each tick label. Renders in lighter weight/color. Only effective on categorical y-axis labels (horizontal bar charts). */
   labelField?: string;
+  /**
+   * Where tick labels render relative to the chart area. Editorial line/area
+   * y-axes default to `'inline'`: labels sit above their gridlines at the
+   * chart's left edge, with no left gutter, axis line, or tick marks. Other
+   * axis types default to `'gutter'` (the classic placement outside the chart
+   * area).
+   */
+  tickPosition?: 'inline' | 'gutter';
 }
 
 /** Scale configuration for an encoding channel. */
@@ -301,10 +312,21 @@ export type ScaleType =
  * Follows the Vega-Lite encoding model: field identifies the column,
  * type determines how the engine interprets values, aggregate applies
  * a transformation before encoding.
+ *
+ * @template TData - The shape of a data row. When `ChartSpec<TData>` is used
+ * with a typed data array, `field` is constrained to `keyof TData & string`,
+ * giving IDE autocomplete and compile-time typo detection. Defaults to `DataRow`
+ * which degrades to plain `string` (no constraint), keeping untyped specs working.
  */
-export interface EncodingChannel {
-  /** Data field name (column in the data array). */
-  field: string;
+export interface EncodingChannel<TData extends DataRow = DataRow> {
+  /**
+   * Data field name (column in the data array).
+   *
+   * When using `ChartSpec<TData>` with a typed data array, this is constrained
+   * to the actual column names of `TData`. Typos fail at compile time and IDEs
+   * autocomplete your column names.
+   */
+  field: keyof TData & string;
   /**
    * How to interpret the field values.
    * - quantitative: continuous numbers (scale: linear)
@@ -321,18 +343,33 @@ export interface EncodingChannel {
   scale?: ScaleConfig;
   /**
    * Stacking behavior for quantitative channels (Vega-Lite aligned).
-   * - undefined | true | 'zero': stack from zero baseline (default)
+   *
+   * Vega-Lite accepts `'zero' | 'normalize' | 'center' | null`. OpenChart adds
+   * `true` (sugar for `'zero'`) and `false` (sugar for `null`) so callers can
+   * write `stack: true` / `stack: false` without learning the string forms.
+   * 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)
+   * - 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 grouped (side-by-side) bars instead
+   * - null | false: no stacking -- renders overlap (area) or grouped/dodged (bar)
    *
-   * Use `stack: null` to get grouped/dodged bars. This is the idiomatic way to
-   * compare values across categories side-by-side rather than stacked on top of
-   * each other. Without it, multi-series bar data stacks by default.
+   * **Defaults differ by chart type:**
+   * - **Bar**: defaults to stacked. Use `stack: null` for grouped (side-by-side) 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.
+   * - **Line**: stacking is not applied (lines always overlap).
    *
    * @example
    * // Side-by-side grouped bars (comparing 2018 vs 2022 wages by firm size):
    * "x": { "field": "pay", "type": "quantitative", "stack": null }
+   *
+   * @example
+   * // Stacked area (opt-in; default is overlap):
+   * "y": { "field": "value", "type": "quantitative", "stack": "zero" }
    */
   stack?: boolean | 'zero' | 'normalize' | 'center' | null;
   /**
@@ -374,44 +411,97 @@ export interface EncodingChannel {
 
 /**
  * Encoding object mapping visual channels to data fields.
- * Which channels are required depends on the mark type.
- * See MARK_ENCODING_RULES in encoding.ts for per-type requirements.
+ * Which channels are required depends on the mark type — see the per-mark
+ * encoding interfaces (ArcEncoding, LineEncoding, etc.) and MARK_ENCODING_RULES
+ * in encoding.ts for the full requirements table.
+ *
+ * @template TData - Propagated from ChartSpec<TData>. Constrains `field` in
+ * every channel to `keyof TData & string` when a typed data row is provided.
  */
-export interface Encoding {
-  /** Horizontal position channel. */
-  x?: EncodingChannel;
-  /** Vertical position channel. */
-  y?: EncodingChannel;
-  /** Color channel (series differentiation or heatmap). Accepts conditional definitions. */
-  color?: EncodingChannel | ConditionalValueDef;
-  /** Size channel (bubble charts, dot plots). Accepts conditional definitions. */
-  size?: EncodingChannel | ConditionalValueDef;
-  /** Detail channel (group without encoding to a visual property). */
-  detail?: EncodingChannel;
-  /** Secondary x position (for ranges, error bars). */
-  x2?: EncodingChannel;
-  /** Secondary y position (for ranges, error bars). */
-  y2?: EncodingChannel;
-  /** Data-driven opacity (0-1). Accepts conditional definitions. */
-  opacity?: EncodingChannel | ConditionalValueDef;
-  /** Point shape encoding (circle, square, diamond, triangle-up, etc.). */
-  shape?: EncodingChannel;
-  /** Data-driven stroke dash patterns. */
-  strokeDash?: EncodingChannel;
-  /** Rotation angle encoding. */
-  angle?: EncodingChannel;
-  /** Text content for text marks. */
-  text?: EncodingChannel;
-  /** Tooltip field(s). Can be a single channel or array. */
-  tooltip?: EncodingChannel | EncodingChannel[];
-  /** Hyperlink encoding. */
-  href?: EncodingChannel;
-  /** Stacking/drawing order. */
-  order?: EncodingChannel;
-  /** Angular position for arc marks. */
-  theta?: EncodingChannel;
-  /** Radial position for arc marks. */
-  radius?: EncodingChannel;
+export interface Encoding<TData extends DataRow = DataRow> {
+  /**
+   * Horizontal position channel. Required for: bar, line, area, point, tick, rect, lollipop.
+   * Maps a field to the x-axis. Use `type: 'temporal'` for dates, `'nominal'` for categories,
+   * `'quantitative'` for numbers.
+   */
+  x?: EncodingChannel<TData>;
+  /**
+   * Vertical position channel. Required for: bar, line, area, point, tick, rect, arc, lollipop.
+   * For arc marks, this is the value field (slice size). For all others it's the y-axis position.
+   */
+  y?: EncodingChannel<TData>;
+  /**
+   * 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.
+   */
+  color?: EncodingChannel<TData> | ConditionalValueDef<TData>;
+  /**
+   * 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.
+   */
+  size?: EncodingChannel<TData> | ConditionalValueDef<TData>;
+  /**
+   * 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.
+   */
+  detail?: EncodingChannel<TData>;
+  /**
+   * Secondary x position. Used with `x` to define a horizontal span (rect marks, error bars).
+   * Both `x` and `x2` must be quantitative.
+   */
+  x2?: EncodingChannel<TData>;
+  /**
+   * Secondary y position. Used with `y` to define a vertical span (rect marks, error bands).
+   * Both `y` and `y2` must be quantitative.
+   */
+  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.
+   */
+  shape?: EncodingChannel<TData>;
+  /**
+   * Stroke dash pattern encoding. Maps a nominal field to different dash patterns
+   * on line 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. */
+  angle?: EncodingChannel<TData>;
+  /**
+   * Text content for `text` marks. Required when mark is `'text'`.
+   * Not meaningful for other mark types.
+   */
+  text?: EncodingChannel<TData>;
+  /**
+   * Tooltip field(s). Shown on hover. Can be a single channel or an array for
+   * 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.
+   */
+  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>;
 }
 
 // ---------------------------------------------------------------------------
@@ -492,11 +582,18 @@ export interface ChromeText {
 }
 
 /**
- * Editorial chrome elements: title, subtitle, source attribution, byline, footer.
+ * Editorial chrome elements: eyebrow, title, subtitle, source attribution, byline, footer.
  * These are first-class structural elements, not string-only afterthoughts.
  * Each element can be a simple string or a ChromeText object with style overrides.
  */
 export interface Chrome {
+  /**
+   * Editorial kicker/category label rendered above the title. Typically
+   * uppercase, tracked, and tinted with the accent color (e.g.
+   * "Equities · Single Ticker"). Term follows IBM Carbon and Atlassian
+   * Design System conventions; not part of Vega-Lite's title model.
+   */
+  eyebrow?: string | ChromeText;
   /** Main title displayed above the visualization. */
   title?: string | ChromeText;
   /** Subtitle displayed below the title, typically providing context. */
@@ -507,6 +604,12 @@ export interface Chrome {
   byline?: string | ChromeText;
   /** Footer text, displayed at the very bottom. */
   footer?: string | ChromeText;
+  /**
+   * Right-anchored brand block on the footer row, paired with a small accent
+   * dot to its left. Visually balances the source/byline left-anchored text.
+   * When set, suppresses the default `tryOpenData.ai` watermark for this chart.
+   */
+  brand?: string | ChromeText;
 }
 
 // ---------------------------------------------------------------------------
@@ -524,6 +627,18 @@ 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. */
+export interface AnnotationDot {
+  /** Circle radius in pixels. Default 5. */
+  radius?: number;
+  /** Fill color. Defaults to theme background for an "open ring" look. */
+  fill?: string;
+  /** Stroke color. Defaults to theme text color. */
+  stroke?: string;
+  /** Stroke width in pixels. Default 2. */
+  strokeWidth?: number;
+}
+
 /** Base properties shared by all annotation types. */
 interface AnnotationBase {
   /** Stable identifier for selection and edit callbacks. When provided, edit events include this ID for reliable element matching. */
@@ -554,6 +669,18 @@ export interface TextAnnotation extends AnnotationBase {
   y: string | number;
   /** The annotation text. Required for text annotations. */
   text: string;
+  /**
+   * 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.
+   */
+  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.
+   */
+  dot?: boolean | AnnotationDot;
   /** Font size override. */
   fontSize?: number;
   /** Font weight override. */
@@ -565,10 +692,12 @@ export interface TextAnnotation extends AnnotationBase {
   /**
    * Connector from label to anchor point.
    * - `true` (default): straight line
+   * - `'straight'`: straight line (alias of `true`)
    * - `'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
    * - `false`: no connector
    */
-  connector?: boolean | 'curve';
+  connector?: boolean | 'straight' | 'curve' | 'drop-line';
   /** 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. */
@@ -745,6 +874,60 @@ export interface LegendConfig {
   exclude?: string[];
 }
 
+/**
+ * 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
+ * last formatted value, optionally anchored to the line by an open-circle marker.
+ *
+ * The column is independent of the traditional `legend` and the legacy
+ * end-of-line labels. Together with `legend.show`, the three suppression toggles
+ * follow this truth table for ≥2-series line/area charts:
+ *
+ * | `legend.show` | `endpointLabels` | Traditional legend | Endpoint column | End-of-line labels |
+ * |--|--|--|--|--|
+ * | unset | unset | hidden (auto-suppressed) | shown (default) | hidden |
+ * | true  | unset | shown                    | shown           | hidden |
+ * | unset | false | shown (auto-suppress revoked) | hidden     | hidden |
+ * | false | false | hidden                   | hidden          | shown (last-resort) |
+ * | true  | false | shown                    | hidden          | hidden |
+ * | false | true  | hidden                   | shown           | hidden |
+ * | true  | true  | shown                    | shown           | hidden |
+ *
+ * Single-series charts: column is hidden by default (nothing to identify).
+ *
+ * The implementation is in `packages/engine/src/legend/suppression.ts` —
+ * `resolveSuppression` is the single source of truth. The table above is
+ * a user-facing mirror; if the two ever diverge, the engine wins. Tests
+ * in `legend/__tests__/suppression.test.ts` enforce every cell.
+ */
+export interface EndpointLabelsConfig {
+  /** Explicit on/off. When undefined, the chart auto-decides based on series count. */
+  show?: boolean;
+  /** 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`. */
+  format?: string;
+  /** Max wrap width in pixels for long series names. Default 96. */
+  width?: number;
+  /** Render an open-circle marker on the line at the right edge. Default true. */
+  showMarker?: boolean;
+  /** Override the marker style. */
+  markerStyle?: {
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    radius?: number;
+  };
+  /**
+   * Render a thin leader line from the swatch row back to the line endpoint
+   * when collision-sweep displaces a label off its data point. Default false:
+   * the marker on the line plus the swatch in the column already pair label
+   * to data; the connector tends to add visual noise for small displacements.
+   * Opt in when labels collide hard and you need the explicit tie-back.
+   */
+  showLeader?: boolean;
+}
+
 // ---------------------------------------------------------------------------
 // Spec types (the top-level discriminated union)
 // ---------------------------------------------------------------------------
@@ -858,33 +1041,174 @@ export interface ChartSpecOverride {
 }
 
 /**
- * Chart specification: the primary input for standard chart types.
+ * A KPI/metric cell rendered above the chart in a horizontal row.
  *
- * Uses the Vega-Lite `mark` property instead of `type` to specify
- * the visualization mark. The mark can be a string shorthand or an
- * object with additional properties (interpolation, point markers, etc.).
+ * Used for editorial dashboards (e.g. "CLOSE $186.10 +1.4%") where the chart
+ * is paired with summary statistics. Cells lay out evenly across the chart
+ * width. Hidden in sparkline mode; auto-stripped when the container can't
+ * fit the laid-out values.
  */
-export interface ChartSpec {
-  /**
-   * The mark type to render.
-   * String shorthand: `mark: 'bar'`
-   * Object with properties: `mark: { type: 'line', interpolate: 'step' }`
-   */
-  mark: MarkType | MarkDef;
+export interface Metric {
+  /** Uppercase eyebrow label, e.g. "CLOSE". */
+  label: string;
+  /** Primary numeric value, e.g. "$186.10". */
+  value: string;
+  /** Optional change indicator, e.g. "+1.4%". Rendered next to the value. */
+  delta?: string;
+  /** Tone for the delta. 'up' = positive (green), 'down' = negative (red). Default 'up'. */
+  deltaTone?: 'up' | 'down';
+  /** Optional secondary value (e.g. multiplier "10.3×"). Rendered after the delta. */
+  secondary?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Per-mark encoding interfaces (Task 2)
+// Required channels derived directly from MARK_ENCODING_RULES in encoding.ts.
+// TypeScript types must stay in sync with those runtime rules.
+// ---------------------------------------------------------------------------
+
+/**
+ * Encoding for arc marks (pie/donut charts).
+ * - `y`: required (quantitative — the slice value)
+ * - `color`: required (nominal/ordinal — the category)
+ * - `theta`: optional (defaults to `y` channel)
+ * - `radius`: optional (donut inner radius)
+ */
+export interface ArcEncoding<TData extends DataRow = DataRow> extends Encoding<TData> {
+  y: EncodingChannel<TData>;
+  color: EncodingChannel<TData>;
+}
+
+/**
+ * Encoding for line marks.
+ * - `x`: required (temporal or ordinal — the time/category axis)
+ * - `y`: required (quantitative — the value axis)
+ */
+export interface LineEncoding<TData extends DataRow = DataRow> extends Encoding<TData> {
+  x: EncodingChannel<TData>;
+  y: EncodingChannel<TData>;
+}
+
+/**
+ * Encoding for bar marks (vertical columns and horizontal bars).
+ * - `x`: required
+ * - `y`: required
+ */
+export interface BarEncoding<TData extends DataRow = DataRow> extends Encoding<TData> {
+  x: EncodingChannel<TData>;
+  y: EncodingChannel<TData>;
+}
+
+/**
+ * Encoding for area marks.
+ * - `x`: required (temporal or ordinal)
+ * - `y`: required (quantitative)
+ */
+export interface AreaEncoding<TData extends DataRow = DataRow> extends Encoding<TData> {
+  x: EncodingChannel<TData>;
+  y: EncodingChannel<TData>;
+}
+
+/**
+ * Encoding for point marks (scatter plots).
+ * - `x`: required
+ * - `y`: required
+ */
+export interface PointEncoding<TData extends DataRow = DataRow> extends Encoding<TData> {
+  x: EncodingChannel<TData>;
+  y: EncodingChannel<TData>;
+}
+
+/**
+ * Encoding for circle marks (dot plots).
+ * - `x`: required (quantitative)
+ * - `y`: required (nominal/ordinal — the category axis)
+ */
+export interface CircleEncoding<TData extends DataRow = DataRow> extends Encoding<TData> {
+  x: EncodingChannel<TData>;
+  y: EncodingChannel<TData>;
+}
+
+/**
+ * Encoding for lollipop marks.
+ * - `x`: required (quantitative)
+ * - `y`: required (nominal/ordinal)
+ */
+export interface LollipopEncoding<TData extends DataRow = DataRow> extends Encoding<TData> {
+  x: EncodingChannel<TData>;
+  y: EncodingChannel<TData>;
+}
+
+/**
+ * Encoding for text marks (data-positioned labels).
+ * - `text`: required (the field to render as text)
+ * - `x`, `y`: optional positioning
+ */
+export interface TextEncoding<TData extends DataRow = DataRow> extends Encoding<TData> {
+  text: EncodingChannel<TData>;
+}
+
+/**
+ * Encoding for tick marks (strip/rug plots).
+ * - `x`: required
+ * - `y`: required
+ */
+export interface TickEncoding<TData extends DataRow = DataRow> extends Encoding<TData> {
+  x: EncodingChannel<TData>;
+  y: EncodingChannel<TData>;
+}
+
+/**
+ * Encoding for rect marks (heatmaps, 2D binned plots).
+ * - `x`: required
+ * - `y`: required
+ */
+export interface RectEncoding<TData extends DataRow = DataRow> extends Encoding<TData> {
+  x: EncodingChannel<TData>;
+  y: EncodingChannel<TData>;
+}
+
+// ---------------------------------------------------------------------------
+// Shared (non-mark-specific) ChartSpec properties
+// ---------------------------------------------------------------------------
+
+/**
+ * Properties shared across all ChartSpec mark variants.
+ * Extracted to avoid repeating them in every union member.
+ *
+ * @internal
+ */
+interface BaseChartSpec<TData extends DataRow = DataRow> {
   /** Data array: each element is a row with field values. */
-  data: DataRow[];
+  data: TData[];
   /** Data transforms applied in order before encoding (filter, bin, calculate, timeUnit). */
   transform?: Transform[];
-  /** Encoding mapping data fields to visual channels. */
-  encoding: Encoding;
   /** Editorial chrome (title, subtitle, source, etc.). */
   chrome?: Chrome;
+  /**
+   * 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
+   * value. Hidden in sparkline mode and auto-stripped when the container is
+   * too narrow or short, or when value text would overflow its cell.
+   */
+  metrics?: Metric[];
   /** Data annotations (text callouts, highlighted ranges, reference lines). */
   annotations?: Annotation[];
   /** Label display configuration. `false` disables all labels, `true` uses defaults. */
   labels?: LabelSpec;
   /** Legend display configuration (position override). */
   legend?: LegendConfig;
+  /**
+   * Right-side endpoint labels column for multi-series line/area charts.
+   *
+   * - `true` or `EndpointLabelsConfig`: render the column.
+   * - `false`: hide the column.
+   * - omitted: auto-enable for multi-series line/area charts, hide otherwise.
+   *
+   * See {@link EndpointLabelsConfig} for the full suppression truth table that
+   * relates this flag to `legend.show` and the legacy end-of-line labels.
+   */
+  endpointLabels?: boolean | EndpointLabelsConfig;
   /** Whether the chart adapts to container width. Defaults to true. */
   responsive?: boolean;
   /** Theme configuration overrides. */
@@ -941,6 +1265,87 @@ export interface ChartSpec {
   zIndex?: number;
 }
 
+/**
+ * Chart specification: the primary input for standard chart types.
+ *
+ * Uses the Vega-Lite `mark` property instead of `type` to specify
+ * the visualization mark. The mark can be a string shorthand or an
+ * object with additional properties (interpolation, point markers, etc.).
+ *
+ * This is a discriminated union — the `mark` value determines which encoding
+ * channels are required. TypeScript enforces required channels at compile time,
+ * matching the runtime rules in `MARK_ENCODING_RULES`.
+ *
+ * @template TData - The shape of a single data row. When provided, `encoding.*.field`
+ * values are constrained to `keyof TData` and IDEs autocomplete your column names.
+ * Defaults to `DataRow` (no constraint) — existing untyped specs work unchanged.
+ *
+ * @example
+ * // Typed: field autocomplete + typo detection
+ * type SalesRow = { date: string; revenue: number; region: string };
+ * const spec: ChartSpec<SalesRow> = {
+ *   mark: 'line',
+ *   data: rows,
+ *   encoding: {
+ *     x: { field: 'date', type: 'temporal' },      // autocompletes
+ *     y: { field: 'revenue', type: 'quantitative' }, // typos fail at compile time
+ *   }
+ * };
+ *
+ * @example
+ * // Untyped: works exactly as before (no migration needed)
+ * const spec: ChartSpec = {
+ *   mark: 'bar',
+ *   data: myData,
+ *   encoding: { x: { field: 'category', type: 'nominal' }, y: { field: 'value', type: 'quantitative' } }
+ * };
+ */
+export type ChartSpec<TData extends DataRow = DataRow> =
+  | (BaseChartSpec<TData> & {
+      mark: 'arc' | (MarkDef & { type: 'arc' });
+      encoding: ArcEncoding<TData>;
+    })
+  | (BaseChartSpec<TData> & {
+      mark: 'line' | (MarkDef & { type: 'line' });
+      encoding: LineEncoding<TData>;
+    })
+  | (BaseChartSpec<TData> & {
+      mark: 'bar' | (MarkDef & { type: 'bar' });
+      encoding: BarEncoding<TData>;
+    })
+  | (BaseChartSpec<TData> & {
+      mark: 'area' | (MarkDef & { type: 'area' });
+      encoding: AreaEncoding<TData>;
+    })
+  | (BaseChartSpec<TData> & {
+      mark: 'point' | (MarkDef & { type: 'point' });
+      encoding: PointEncoding<TData>;
+    })
+  | (BaseChartSpec<TData> & {
+      mark: 'circle' | (MarkDef & { type: 'circle' });
+      encoding: CircleEncoding<TData>;
+    })
+  | (BaseChartSpec<TData> & {
+      mark: 'lollipop' | (MarkDef & { type: 'lollipop' });
+      encoding: LollipopEncoding<TData>;
+    })
+  | (BaseChartSpec<TData> & {
+      mark: 'text' | (MarkDef & { type: 'text' });
+      encoding: TextEncoding<TData>;
+    })
+  | (BaseChartSpec<TData> & {
+      mark: 'tick' | (MarkDef & { type: 'tick' });
+      encoding: TickEncoding<TData>;
+    })
+  | (BaseChartSpec<TData> & {
+      mark: 'rect' | (MarkDef & { type: 'rect' });
+      encoding: RectEncoding<TData>;
+    })
+  | (BaseChartSpec<TData> & {
+      mark: 'rule' | (MarkDef & { type: 'rule' });
+      encoding: Encoding<TData>;
+    });
+
 /**
  * Table specification: input for data table visualizations.
  *
@@ -1062,14 +1467,19 @@ export interface ResolveConfig {
  * Each element in `layer` is either a ChartSpec or another LayerSpec (nested).
  * Shared data, encoding, and transforms at the LayerSpec level are inherited
  * by children that don't define their own.
+ *
+ * @template TData - The shape of a single data row. When all layers share the
+ * same data shape, pass it here to get field autocomplete across the layer.
+ * For layers with different data shapes per child, omit TData (defaults to
+ * `DataRow`) — children can be independently typed.
  */
-export interface LayerSpec {
+export interface LayerSpec<TData extends DataRow = DataRow> {
   /** Array of child layers (ChartSpec or nested LayerSpec). */
-  layer: (ChartSpec | LayerSpec)[];
+  layer: (ChartSpec<TData> | LayerSpec<TData>)[];
   /** Shared data inherited by children without their own data. */
-  data?: DataRow[];
+  data?: TData[];
   /** Shared encoding inherited by children (overridden per-channel by child). */
-  encoding?: Encoding;
+  encoding?: Encoding<TData>;
   /** Shared transforms. Parent transforms run before child transforms. */
   transform?: Transform[];
   /** Editorial chrome (title, subtitle, source, etc.). */
@@ -1297,8 +1707,11 @@ export type VizSpec =
   | TileMapSpec
   | BarListSpec;
 
-/** Chart spec without runtime data, for persistence/storage. */
-export type ChartSpecWithoutData = Omit<ChartSpec, 'data'>;
+/**
+ * Chart spec without runtime data, for persistence/storage.
+ * Generic: `ChartSpecWithoutData<MyRow>` constrains encoding field names.
+ */
+export type ChartSpecWithoutData<TData extends DataRow = DataRow> = Omit<ChartSpec<TData>, 'data'>;
 /** Table spec without runtime data and columns, for persistence/storage. Columns can be auto-generated via dataTable(). */
 export type TableSpecWithoutData = Omit<TableSpec, 'data' | 'columns'>;
 /** Graph spec without runtime data, for persistence/storage. */
@@ -1346,7 +1759,12 @@ export interface RelativeTimeRef {
 
 /** A predicate that tests a field value against a condition. */
 export interface FieldPredicate {
-  /** Data field to test. */
+  /**
+   * Data field to test.
+   * Note: FieldPredicate is used in transforms (FilterTransform) which operate
+   * on the raw DataRow type — field is typed as string here since transforms
+   * can reference computed/derived fields not present in the original TData.
+   */
   field: string;
   /** Equals comparison. */
   equal?: unknown;
@@ -1509,14 +1927,23 @@ export type Transform =
 /**
  * A single condition with a test predicate and resulting value/field.
  * When the test passes for a datum, the condition's value/field is used.
+ *
+ * @template TData - Propagated from ChartSpec<TData>. Constrains `field` to
+ * `keyof TData & string` when a typed data row is provided.
  */
-export interface Condition {
+export interface Condition<TData extends DataRow = DataRow> {
   /** Predicate to test against each datum. */
   test: FilterPredicate;
-  /** Static value to use when the condition is true. */
-  value?: unknown;
-  /** Data field to use when the condition is true. */
-  field?: string;
+  /**
+   * Static value to use when the condition is true.
+   * Accepted values: CSS color string, opacity (0-1), size number, or boolean flag.
+   */
+  value?: string | number | boolean | null;
+  /**
+   * Data field to use when the condition is true.
+   * Constrained to column names of `TData` when using `ChartSpec<TData>`.
+   */
+  field?: keyof TData & string;
   /** Field type for the conditional field. */
   type?: FieldType;
 }
@@ -1524,12 +1951,17 @@ export interface Condition {
 /**
  * A conditional value definition for an encoding channel.
  * Evaluates conditions in order, falling back to the default value.
+ *
+ * @template TData - Propagated from ChartSpec<TData>.
  */
-export interface ConditionalValueDef {
+export interface ConditionalValueDef<TData extends DataRow = DataRow> {
   /** One or more conditions to evaluate. */
-  condition: Condition | Condition[];
-  /** Default value when no condition matches. */
-  value?: unknown;
+  condition: Condition<TData> | Condition<TData>[];
+  /**
+   * Default value when no condition matches.
+   * Accepted values: CSS color string, opacity (0-1), size number, or boolean flag.
+   */
+  value?: string | number | boolean | null;
 }
 
 /**
@@ -1537,9 +1969,9 @@ export interface ConditionalValueDef {
  * Use this to narrow `EncodingChannel | ConditionalValueDef` in encoding channels
  * that support conditional encoding (color, size, opacity).
  */
-export function isEncodingChannel(
-  def: EncodingChannel | ConditionalValueDef | undefined,
-): def is EncodingChannel {
+export function isEncodingChannel<TData extends DataRow = DataRow>(
+  def: EncodingChannel<TData> | ConditionalValueDef<TData> | undefined,
+): def is EncodingChannel<TData> {
   if (!def) return false;
   return 'field' in def && !('condition' in def);
 }
@@ -1547,9 +1979,9 @@ export function isEncodingChannel(
 /**
  * Check if a channel definition is a ConditionalValueDef.
  */
-export function isConditionalDef(
-  def: EncodingChannel | ConditionalValueDef | undefined,
-): def is ConditionalValueDef {
+export function isConditionalDef<TData extends DataRow = DataRow>(
+  def: EncodingChannel<TData> | ConditionalValueDef<TData> | undefined,
+): def is ConditionalValueDef<TData> {
   if (!def) return false;
   return 'condition' in def;
 }