dataface 0.1.2__py3-none-any.whl

dataface/core/compile/models/chart/authored.py

@@ -0,0 +1,2137 @@
+"""Authored chart models: per-family discriminated union for AuthoredChart.
+
+Stage: COMPILE (Input)
+Purpose: Define all chart-specific authored types that map directly to the YAML schema.
+Families: BarChart, LineChart, AreaChart, ScatterChart, HeatmapChart, PieChart, KpiChart,
+    TableChart, PointMapChart, GeoshapeChart, LayeredChart, CalloutChart, SparkBarChart.
+    AuthoredChart is a type alias over a discriminated union. type: is mandatory — missing
+    or unknown type raises a ValidationError at the authored-model level.
+"""
+
+from __future__ import annotations
+
+import math
+from enum import Enum
+from typing import Annotated, Any, Literal
+
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Discriminator,
+    Field,
+    StrictBool,
+    Tag,
+    field_validator,
+    model_validator,
+)
+
+from dataface.core.compile.models.primitives import (
+    FontStyle,
+    FormatConfig,
+    ScaleTargetConfig,
+)
+from dataface.core.compile.models.style.authored import (
+    AreaChartStylePatch,
+    BarChartStylePatch,
+    CalloutChartStylePatch,
+    GeoshapeChartStylePatch,
+    HeatmapChartStylePatch,
+    KpiChartStylePatch,
+    LayeredChartStyle,
+    LineChartStylePatch,
+    PieChartStylePatch,
+    PointMapChartStylePatch,
+    ScatterChartStylePatch,
+    SparkBarChartStylePatch,
+)
+from dataface.core.compile.models.style.compiled import (
+    VALID_FONT_WEIGHTS,
+    TableChartStylePatch,
+    _normalize_overflow_value,
+    font_weight_as_css,
+)
+from dataface.core.compile.models.variable.authored import SingleRowBoolProbe
+from dataface.core.compile.models.vega_lite.contracts import (
+    Projection,
+)
+from dataface.core.compile.vega_lite.validation import (
+    validate_projection_definition,
+)
+
+# ============================================================================
+# KPI: SEMANTIC TONE + SUPPORT BLOCK
+# ============================================================================
+
+ToneLiteral = Literal["positive", "negative", "warning"]
+"""Semantic styling hint shared by KPI value/glyph and (future) table emphasis.
+
+v1: three tones only — positive, negative, warning.
+neutral removed; KPIs without tone use default chrome colors.
+"""
+
+
+class KpiSupportConfig(BaseModel):
+    """Support-line block authored alongside a KPI's main value."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    value: str | None = Field(
+        default=None,
+        description="Column reference (string column name) for the support number/text.",
+    )
+    label: str | None = Field(
+        default=None,
+        description="Trailing explainer text rendered beside the support value.",
+    )
+    format: str | FormatConfig | None = Field(
+        default=None,
+        description="Number format (D3 spec, preset, or FormatConfig).",
+    )
+    glyph: str | None = Field(
+        default=None,
+        description="Optional prefix glyph (e.g. '▲', '▼', '●').",
+    )
+    tone: ToneLiteral | None = Field(
+        default=None,
+        description="Semantic styling for the support value/glyph.",
+    )
+
+    @model_validator(mode="before")
+    @classmethod
+    def _reject_removed_color_shortcuts(cls, data: Any) -> Any:
+        if isinstance(data, dict):
+            if "value_color" in data:
+                raise ValueError(
+                    "value_color no longer accepted on support. "
+                    "Use style.kpi.value.font.color instead."
+                )
+            if "glyph_color" in data:
+                raise ValueError(
+                    "glyph_color no longer accepted on support. "
+                    "Use style.kpi.glyph.font.color instead."
+                )
+        return data
+
+    @model_validator(mode="before")
+    @classmethod
+    def reject_literal_support_value(cls, data: Any) -> Any:
+        if isinstance(data, dict) and not isinstance(data.get("value"), bool):
+            v = data.get("value")
+            if isinstance(v, (int, float)):
+                raise ValueError(
+                    f"support.value must be a column reference (string column name).\n"
+                    f"Got numeric literal: {v}.\n"
+                    "Channels are always column references; data values come from the query.\n"
+                    "Update to:\n"
+                    f'  query: {{ sql: "select revenue, {v} as delta_pct from revenue_q" }}\n'
+                    "  value: revenue\n"
+                    "  support:\n"
+                    "    value: delta_pct"
+                )
+        return data
+
+    @model_validator(mode="after")
+    def _require_non_empty(self) -> KpiSupportConfig:
+        if self.value is None and self.label is None and self.glyph is None:
+            raise ValueError(
+                "Empty `support:` block. Set at least one of `value`, "
+                "`label`, or `glyph`, or omit the block entirely."
+            )
+        return self
+
+
+# ============================================================================
+# ENUMS & LITERALS
+# ============================================================================
+
+
+class ChartType(str, Enum):
+    """Supported chart types."""
+
+    # Basic Vega-Lite marks
+    BAR = "bar"
+    LINE = "line"
+    AREA = "area"
+    CIRCLE = "circle"
+    SQUARE = "square"
+    TICK = "tick"
+    RULE = "rule"
+    TRAIL = "trail"
+    RECT = "rect"
+    ARC = "arc"
+
+    # Composite marks
+    BOXPLOT = "boxplot"
+    ERRORBAR = "errorbar"
+    ERRORBAND = "errorband"
+
+    # Special marks
+    GEOSHAPE = "geoshape"
+    IMAGE = "image"
+
+    # Dataface-specific
+    TABLE = "table"
+    KPI = "kpi"
+    CALLOUT = "callout"
+
+    # Aliases (map to underlying marks)
+    SCATTER = "scatter"  # VL mark: point
+    HEATMAP = "heatmap"  # -> rect
+    PIE = "pie"  # -> arc
+    DONUT = "donut"  # -> pie with style.inner_radius=0.6 (normalized alias)
+    HISTOGRAM = "histogram"  # -> bar + binning
+    MAP = "map"  # -> geoshape (generic map)
+    POINT_MAP = "point_map"  # -> circle marks with lat/lng
+    BUBBLE_MAP = "bubble_map"  # -> circle marks with size encoding
+
+    # Spark charts (compact inline charts)
+    SPARK_BAR = "spark_bar"  # -> compact horizontal bars for profiler cards
+
+    # Composition
+    LAYERED = "layered"  # explicit multi-mark layered chart
+
+    # Internal/auto-detection (not shown in UI dropdowns)
+    AUTO = "auto"  # auto-detect chart type from data
+
+
+# Display metadata for UI dropdowns
+CHART_TYPE_DISPLAY: dict[ChartType, dict[str, str]] = {
+    # Basic Vega-Lite marks
+    ChartType.LINE: {"label": "Line", "icon": "📈"},
+    ChartType.BAR: {"label": "Bar", "icon": "📊"},
+    ChartType.AREA: {"label": "Area", "icon": "📉"},
+    ChartType.CIRCLE: {"label": "Circle", "icon": "⭕"},
+    ChartType.SQUARE: {"label": "Square", "icon": "⬜"},
+    ChartType.TICK: {"label": "Tick", "icon": "➖"},
+    ChartType.RULE: {"label": "Rule", "icon": "📏"},
+    ChartType.TRAIL: {"label": "Trail", "icon": "〰️"},
+    ChartType.RECT: {"label": "Rect", "icon": "⬛"},
+    ChartType.ARC: {"label": "Arc", "icon": "🌙"},
+    # Composite marks
+    ChartType.BOXPLOT: {"label": "Boxplot", "icon": "📦"},
+    ChartType.ERRORBAR: {"label": "Error Bar", "icon": "📊"},
+    ChartType.ERRORBAND: {"label": "Error Band", "icon": "📊"},
+    # Special marks
+    ChartType.GEOSHAPE: {"label": "Geoshape", "icon": "🗺️"},
+    ChartType.IMAGE: {"label": "Image", "icon": "🖼️"},
+    # Dataface-specific
+    ChartType.TABLE: {"label": "Table", "icon": "📋"},
+    ChartType.KPI: {"label": "KPI", "icon": "#️⃣"},
+    ChartType.CALLOUT: {"label": "Callout", "icon": "🚨"},
+    # Aliases
+    ChartType.SCATTER: {"label": "Scatter", "icon": "⬡"},
+    ChartType.HEATMAP: {"label": "Heatmap", "icon": "🟧"},
+    ChartType.PIE: {"label": "Pie", "icon": "🥧"},
+    ChartType.DONUT: {"label": "Donut", "icon": "🍩"},
+    ChartType.HISTOGRAM: {"label": "Histogram", "icon": "📊"},
+    # Maps
+    ChartType.MAP: {"label": "Map", "icon": "🗺️"},
+    ChartType.POINT_MAP: {"label": "Point Map", "icon": "📍"},
+    ChartType.BUBBLE_MAP: {"label": "Bubble Map", "icon": "🫧"},
+    # Spark charts
+    ChartType.SPARK_BAR: {"label": "Spark Bar", "icon": "📊"},
+    # Composition
+    ChartType.LAYERED: {"label": "Layered", "icon": "📊"},
+    # Internal
+    ChartType.AUTO: {"label": "Auto", "icon": "🔮"},
+}
+
+# Internal chart types that should not be shown in UI dropdowns by default
+_INTERNAL_CHART_TYPES: set[ChartType] = {ChartType.AUTO, ChartType.DONUT}
+
+
+def get_chart_type_options(include_internal: bool = False) -> list[dict]:
+    """Get chart types for UI dropdowns. Single source of truth.
+
+    Args:
+        include_internal: Whether to include internal types like AUTO
+
+    Returns:
+        List of dicts with name, label, icon for each chart type
+    """
+    return [
+        {
+            "name": ct.value,
+            **CHART_TYPE_DISPLAY.get(
+                ct, {"label": ct.value.replace("_", " ").title(), "icon": "📊"}
+            ),
+        }
+        for ct in ChartType
+        if include_internal or ct not in _INTERNAL_CHART_TYPES
+    ]
+
+
+# ============================================================================
+# SPARK CHARTS (SPARKLINES)
+# ============================================================================
+
+SparkTypeLiteral = Literal[
+    "line",
+    "area",
+    "bar",
+    "bar-normalize",
+    "columns",
+]
+
+SPARK_SUPPORTED_TYPES: frozenset[str] = frozenset(
+    {"line", "area", "bar", "bar-normalize", "columns"}
+)
+
+# Renamed-away variant names → guidance for authors hitting the old vocab.
+# Pre-launch repo — no aliases, no silent fallback. The validator below
+# surfaces the rename as a clear ValueError instead of a generic Literal
+# mismatch.
+_SPARK_RENAMED_AWAY: dict[str, str] = {
+    "progress": (
+        "spark.type 'progress' renamed to 'bar' (no max, no track) or "
+        "'bar-normalize' (with max, with background track)"
+    ),
+    "bars": "spark.type 'bars' renamed to 'columns' (multi-value vertical bars)",
+    "histogram": (
+        "spark.type 'histogram' renamed to 'columns' — pre-bin in SQL "
+        "(width_bucket / histogram_continuous) and render as columns"
+    ),
+}
+
+
+class SparkConfig(BaseModel):
+    """Configuration for spark charts (inline sparklines) in table columns."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: SparkTypeLiteral = Field(
+        default="line",
+        description="Spark chart type (line, area, bar, bar-normalize, columns).",
+    )
+    color: str | None = Field(default=None, description="Color for the spark mark.")
+    height: int | None = Field(
+        default=None, description="Spark chart height in pixels."
+    )
+    width: int | None = Field(default=None, description="Spark chart width in pixels.")
+
+    # Line/area specific
+    last_visible: bool | None = Field(
+        default=None,
+        description="Highlight the last data point (line/area spark charts).",
+    )
+    min_max_visible: bool | None = Field(
+        default=None,
+        description="Annotate the min and max data points (line/area spark charts).",
+    )
+    fill_opacity: float | None = Field(
+        default=None, description="Fill opacity for area spark charts (0–1)."
+    )
+
+    # Bar / bar-normalize specific
+    max: float | None = Field(
+        default=None, description="Maximum value for bar-normalize range scaling."
+    )
+    thresholds: dict[int | float, str] | None = Field(
+        default=None,
+        description="Color thresholds for bar / bar-normalize: {value: CSS color string}.",
+    )
+    background: str | None = Field(
+        default=None, description="Background track color for bar-normalize chart."
+    )
+    border_radius: float | None = Field(
+        default=None, description="Border radius for bar-normalize track in pixels."
+    )
+    value_visible: bool | None = Field(
+        default=None, description="Show numeric value label alongside the bar."
+    )
+    value_suffix: str | None = Field(
+        default=None,
+        description="Suffix appended to the displayed value label (e.g., '%').",
+    )
+
+    @field_validator("type", mode="before")
+    @classmethod
+    def _reject_renamed_away_type(cls, value: Any) -> Any:
+        if isinstance(value, str) and value in _SPARK_RENAMED_AWAY:
+            raise ValueError(_SPARK_RENAMED_AWAY[value])
+        return value
+
+
+# ============================================================================
+# CONDITIONAL FORMATTING
+# ============================================================================
+
+_PREDICATE_OPS: tuple[str, ...] = (
+    "eq",
+    "ne",
+    "lt",
+    "lte",
+    "gt",
+    "gte",
+    "between",
+    "in_",
+    "is_null",
+    "default",
+)
+
+
+def _validate_exactly_one_predicate(obj: Any) -> None:
+    """Raise ValueError if obj does not have exactly one condition operator set."""
+    ops = [f for f in _PREDICATE_OPS if getattr(obj, f) is not None]
+    if len(ops) == 0:
+        raise ValueError(
+            f"{type(obj).__name__} requires exactly one condition operator"
+        )
+    if len(ops) > 1:
+        raise ValueError(
+            f"{type(obj).__name__} requires exactly one condition operator, got: {ops}"
+        )
+
+
+class _PredicateBase(BaseModel):
+    """Shared predicate fields and helpers for conditional rules."""
+
+    # extra="forbid": rejects unknown fields like all authored models.
+    # populate_by_name=True: 'in' is a Python keyword, so the field is `in_`
+    # in Python; YAML authors write `in:` and the alias bridges the two.
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    eq: Any = Field(
+        default=None, description="Match rows where the column value equals this value."
+    )
+    ne: Any = Field(
+        default=None,
+        description="Match rows where the column value does not equal this value.",
+    )
+    lt: int | float | None = Field(
+        default=None,
+        description="Match rows where the column value is less than this number.",
+    )
+    lte: int | float | None = Field(
+        default=None,
+        description="Match rows where the column value is less than or equal to this number.",
+    )
+    gt: int | float | None = Field(
+        default=None,
+        description="Match rows where the column value is greater than this number.",
+    )
+    gte: int | float | None = Field(
+        default=None,
+        description="Match rows where the column value is greater than or equal to this number.",
+    )
+    between: list[int | float] | None = Field(
+        default=None,
+        description="Match rows where the column value falls in [low, high] (inclusive).",
+    )
+    in_: list[Any] | None = Field(
+        default=None,
+        alias="in",
+        description="Match rows where the column value is in this list.",
+    )
+    is_null: StrictBool | None = Field(
+        default=None, description="Match null rows (true) or non-null rows (false)."
+    )
+    default: Literal[True] | None = Field(
+        default=None,
+        description="Catch-all rule that matches any row not matched by earlier rules. Must be the last entry.",
+    )
+
+    @field_validator("between")
+    @classmethod
+    def _validate_between(cls, v: list[int | float] | None) -> list[int | float] | None:
+        if v is None:
+            return v
+        if len(v) != 2:
+            raise ValueError(
+                f"between expects exactly 2 values [low, high], got {len(v)}"
+            )
+        low, high = v
+        if low > high:
+            raise ValueError(f"between requires low <= high, got [{low}, {high}]")
+        return v
+
+    @field_validator("in_")
+    @classmethod
+    def _validate_in(cls, v: list[Any] | None) -> list[Any] | None:
+        if v is None:
+            return v
+        if len(v) == 0:
+            raise ValueError("in must be a non-empty list")
+        return v
+
+    def active_predicate(self) -> tuple[str, Any]:
+        """Return the (op, value) pair for the single active predicate."""
+        for op in _PREDICATE_OPS:
+            val = getattr(self, op)
+            if val is not None:
+                return op, val
+        raise AssertionError("No active predicate — should be caught by validator")
+
+
+def coerce_numeric(v: Any) -> float | None:
+    """Return float(v) for finite numeric-compatible values; None otherwise."""
+    if v is None or isinstance(v, bool):
+        return None
+    if isinstance(v, (int, float)):
+        result = float(v)
+        return result if math.isfinite(result) else None
+    if isinstance(v, str):
+        try:
+            result = float(v)
+            return result if math.isfinite(result) else None
+        except (ValueError, TypeError):
+            return None
+    return None
+
+
+def _in_value_matches(candidate: Any, value: Any) -> bool:
+    """Equality check for a single ``in`` candidate, with the bool/int guard."""
+    if isinstance(value, bool) != isinstance(candidate, bool):
+        return False
+    return value == candidate
+
+
+def match_predicate(rule: _PredicateBase, value: Any) -> bool:
+    """Return True if the rule's single predicate matches value."""
+    if rule.default is True:
+        return True
+    if rule.is_null is not None:
+        return (value is None) == rule.is_null
+    if rule.eq is not None:
+        if isinstance(value, bool) != isinstance(rule.eq, bool):
+            return False
+        return value == rule.eq
+    if rule.ne is not None:
+        if isinstance(value, bool) != isinstance(rule.ne, bool):
+            return True
+        return value != rule.ne
+    if rule.in_ is not None:
+        return any(_in_value_matches(candidate, value) for candidate in rule.in_)
+    v_coerced = coerce_numeric(value)
+    if v_coerced is None:
+        return False
+    v = v_coerced
+    if rule.lt is not None:
+        return v < float(rule.lt)
+    if rule.lte is not None:
+        return v <= float(rule.lte)
+    if rule.gt is not None:
+        return v > float(rule.gt)
+    if rule.gte is not None:
+        return v >= float(rule.gte)
+    if rule.between is not None:
+        low, high = rule.between
+        return float(low) <= v <= float(high)
+    return False
+
+
+def _validate_glyph_pair(
+    glyph: str | None, glyph_color: str | None, label: str
+) -> None:
+    """Shared check for the (glyph, glyph_color) authoring contract."""
+    if glyph is not None and not glyph.strip():
+        raise ValueError(f"{label} glyph must be a non-empty string")
+    if glyph_color is not None and glyph is None:
+        raise ValueError(f"{label} glyph_color requires glyph to be set")
+
+
+class ConditionalRule(_PredicateBase):
+    """A single conditional formatting rule."""
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    # Style overrides — at least one must be set
+    background: str | None = Field(
+        default=None, description="Cell background color applied when the rule matches."
+    )
+    font: FontStyle | None = Field(
+        default=None,
+        description="Font style overrides (color, weight, style, decoration) applied when the rule matches.",
+    )
+    glyph: str | None = Field(
+        default=None,
+        description="Glyph character prepended to the cell value when the rule matches.",
+    )
+    glyph_color: str | None = Field(
+        default=None,
+        description="Color for the glyph when the rule matches. Requires glyph to be set.",
+    )
+
+    @model_validator(mode="after")
+    def _validate_rule(self) -> ConditionalRule:
+        _validate_exactly_one_predicate(self)
+        _font_effective = self.font is not None and (
+            self.font.color is not None
+            or self.font.weight is not None
+            or self.font.style is not None
+            or self.font.decoration is not None
+        )
+        _validate_glyph_pair(self.glyph, self.glyph_color, label="ConditionalRule")
+        if self.background is None and not _font_effective and self.glyph is None:
+            raise ValueError(
+                "ConditionalRule requires at least one style override "
+                "(background, font.color, font.weight, font.style, "
+                "font.decoration, or glyph)"
+            )
+        if self.font is not None and self.font.weight is not None:
+            if font_weight_as_css(self.font.weight) not in VALID_FONT_WEIGHTS:
+                raise ValueError(
+                    f"ConditionalRule font.weight {self.font.weight!r} is not a valid "
+                    "CSS font-weight; use a numeric string (e.g. '700') or 'normal'/'bold'."
+                )
+        return self
+
+
+class FieldConditionalFormatting(BaseModel):
+    """Conditional formatting rules scoped to a single column."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    when: list[ConditionalRule] = Field(
+        description="Ordered list of conditional rules. The first matching rule applies; a 'default: true' rule must be last."
+    )
+
+    @model_validator(mode="after")
+    def _validate_default_position(self) -> FieldConditionalFormatting:
+        for i, rule in enumerate(self.when):
+            if rule.default is True and i != len(self.when) - 1:
+                raise ValueError(
+                    "ConditionalRule with default: true must be the last entry "
+                    f"in a when list (found at position {i} of {len(self.when)})"
+                )
+        return self
+
+
+# ============================================================================
+# CHART.DATA_TABLE — attached mini-table primitive
+# ============================================================================
+
+ChartDataTableAggregateOp = Literal[
+    "sum", "avg", "min", "max", "median", "count", "count_distinct"
+]
+
+
+class ChartDataTableSource(BaseModel):
+    """A data_table row that reads a column's raw per-x value."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    source: str = Field(
+        description="Query column the row reads from (per-x raw value)."
+    )
+    format: str | None = Field(
+        default=None,
+        description="D3-style format string (Vega-Lite format parity). Optional.",
+    )
+    label: str | None = Field(
+        default=None,
+        description="Left-stub row label. Optional.",
+    )
+
+
+class ChartDataTableAggregate(BaseModel):
+    """A data_table row that reads an aggregate of a column grouped by x."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    aggregate: ChartDataTableAggregateOp = Field(
+        description=(
+            "Aggregate operation applied per x-group. One of: "
+            "sum, avg, min, max, median, count, count_distinct. "
+            "Exact names only — no aliases (spec G4)."
+        ),
+    )
+    source: str = Field(
+        description=(
+            "Query column being aggregated. Always required alongside "
+            "`aggregate:` (spec G2)."
+        ),
+    )
+    format: str | None = Field(
+        default=None, description="D3-style format string for the aggregated value."
+    )
+    label: str | None = Field(
+        default=None, description="Column header label override for this row."
+    )
+
+
+class ChartDataTablePerSeries(BaseModel):
+    """A data_table entry that expands into one row per color: series.
+
+    When ``by_measure=True`` the entry expands into a single row reading the
+    named y-field directly, without a color: channel.  This is the expansion
+    mode for multi-y charts (``y: [revenue, margin]``) where each measure is
+    its own y-axis series rather than a color-encoded pivot.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    per_series: str = Field(
+        description="Query column the row reads from (per-x, per-series value)."
+    )
+    by_measure: bool = Field(
+        default=False,
+        description=(
+            "When True, expand one row reading the named measure field directly "
+            "(no color: groupby). Required for multi-y charts where each measure "
+            "is its own y-field rather than a color-encoded series."
+        ),
+    )
+    label: str | None = Field(
+        default=None,
+        description=(
+            "Row label displayed in the strip's label gutter. "
+            "When None and by_measure=True, the per_series field name is used. "
+            "Has no effect when by_measure=False (series name is the label)."
+        ),
+    )
+    format: str | None = Field(
+        default=None,
+        description="D3-style format string (Vega-Lite format parity). Optional.",
+    )
+
+
+def _discriminate_entry(entry: Any) -> str | None:
+    """Tag-selector for the ChartDataTableEntry tagged union."""
+    if isinstance(entry, ChartDataTableAggregate):
+        return "aggregate"
+    if isinstance(entry, ChartDataTablePerSeries):
+        return "per_series"
+    if isinstance(entry, ChartDataTableSource):
+        return "source"
+    if isinstance(entry, dict):
+        if "aggregate" in entry:
+            return "aggregate"
+        if "per_series" in entry:
+            return "per_series"
+        return "source"
+    return None
+
+
+ChartDataTableEntry = Annotated[
+    Annotated[ChartDataTableSource, Tag("source")]
+    | Annotated[ChartDataTableAggregate, Tag("aggregate")]
+    | Annotated[ChartDataTablePerSeries, Tag("per_series")],
+    Discriminator(_discriminate_entry),
+]
+
+CHART_DATA_TABLE_MAX_X_TICKS = 40
+
+
+class ChartDataTable(BaseModel):
+    """Container for a chart's data_table block."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    entries: list[ChartDataTableEntry] = Field(
+        min_length=1,
+        description="List of data-table entries (source, aggregate, or per-series rows).",
+    )
+
+    @model_validator(mode="before")
+    @classmethod
+    def _accept_bare_list(cls, data: Any) -> Any:
+        if isinstance(data, list):
+            return {"entries": data}
+        return data
+
+
+CHART_DATA_TABLE_SUPPORTED_TYPES: frozenset[str] = frozenset(
+    {"bar", "line", "area", "layered"}
+)
+
+
+def validate_data_table_shape(entries: list[ChartDataTableEntry]) -> None:
+    """Data-free validation of a data_table entry list (spec §3.2)."""
+    seen: set[tuple[str, str | None, bool]] = set()
+    for entry in entries:
+        if isinstance(entry, ChartDataTablePerSeries):
+            key: tuple[str, str | None, bool] = (entry.per_series, None, True)
+            if key in seen:
+                raise ValueError(
+                    f"chart.data_table has duplicate per_series entries for "
+                    f"{{per_series: {entry.per_series!r}}}. "
+                    "Remove the duplicate."
+                )
+            seen.add(key)
+            continue
+        agg = entry.aggregate if isinstance(entry, ChartDataTableAggregate) else None
+        source = entry.source
+        normal_key: tuple[str, str | None, bool] = (source, agg, False)
+        if normal_key in seen:
+            label = (
+                f"{{aggregate: {agg}, source: {source}}}"
+                if agg is not None
+                else f"{{source: {source}}}"
+            )
+            raise ValueError(
+                f"chart.data_table has duplicate entries for {label}. "
+                "Remove the duplicate or differentiate by aggregate operation."
+            )
+        seen.add(normal_key)
+
+
+# ============================================================================
+# TABLE COLUMN CONFIG
+# ============================================================================
+
+
+class ColumnScaleConfig(BaseModel):
+    """Scale-based continuous color mapping for a table column."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    background: ScaleTargetConfig | None = Field(
+        default=None, description="Continuous background color mapping for this column."
+    )
+    color: ScaleTargetConfig | None = Field(
+        default=None, description="Continuous text color mapping for this column."
+    )
+
+    @model_validator(mode="after")
+    def _validate_color_palettes(self) -> ColumnScaleConfig:
+        for key, target in (("background", self.background), ("color", self.color)):
+            if target is not None and not all(
+                isinstance(c, str) for c in target.palette
+            ):
+                raise ValueError(
+                    f"ColumnScaleConfig.{key}.palette must be CSS color strings, not numbers."
+                )
+        return self
+
+
+class TableColumnConfig(BaseModel):
+    """Configuration for a single table column."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    label: str | None = Field(
+        default=None, description="Display header label (defaults to column name)."
+    )
+    format: str | FormatConfig | None = Field(
+        default=None,
+        description="Number format (D3 string, preset name, or FormatConfig).",
+    )
+    spark: SparkConfig | SparkTypeLiteral | None = Field(
+        default=None, description="Inline spark chart config or spark type name."
+    )
+    swatch: bool | None = Field(
+        default=None,
+        description=(
+            "When True, render this column's cells as small rounded color squares "
+            "instead of text. Cell value must be a CSS color string (e.g. '#3164a3'). "
+            "Useful for series-keyed tables — e.g. a 'Series' column where each row "
+            "is identified by its color in the parent chart's palette."
+        ),
+    )
+    width: int | str | None = Field(
+        default=None,
+        description="Column width (integer pixels or CSS string like '10%').",
+    )
+    max_width: int | str | None = Field(
+        default=None,
+        description=(
+            "Maximum column width for auto-sized text columns "
+            "(integer pixels or CSS string like '30%'). "
+            "Cannot be set together with width:."
+        ),
+    )
+    align: Literal["left", "center", "right"] | None = Field(
+        default=None, description="Text alignment in cells (left, center, right)."
+    )
+    header_overflow: Literal["clip", "truncate", "wrap-two", "wrap"] | None = Field(
+        default=None,
+        description="Header text overflow mode (clip, truncate, wrap-two, wrap).",
+    )
+    header_link: str | None = Field(
+        default=None, description="URL template for the column header link."
+    )
+    link: str | None = Field(
+        default=None,
+        description="URL template for cell values (Jinja template with row fields available).",
+    )
+    background: str | None = Field(
+        default=None, description="Cell background color (CSS color string)."
+    )
+    font: FontStyle | None = Field(
+        default=None, description="Cell font style overrides."
+    )
+    scale: ColumnScaleConfig | None = Field(
+        default=None,
+        description="Continuous color mapping configuration for this column.",
+    )
+    glyph: str | None = Field(
+        default=None, description="Glyph character prepended to cell values."
+    )
+    glyph_color: str | None = Field(
+        default=None, description="Color for the glyph. Requires glyph to be set."
+    )
+
+    @field_validator("header_overflow", mode="before")
+    @classmethod
+    def _normalize_header_overflow(cls, value: Any) -> Any:
+        return _normalize_overflow_value(value)
+
+    @field_validator("spark", mode="before")
+    @classmethod
+    def _reject_renamed_away_spark_shorthand(cls, value: Any) -> Any:
+        if isinstance(value, str) and value in _SPARK_RENAMED_AWAY:
+            raise ValueError(_SPARK_RENAMED_AWAY[value])
+        return value
+
+    @model_validator(mode="after")
+    def _validate_glyph(self) -> TableColumnConfig:
+        _validate_glyph_pair(self.glyph, self.glyph_color, label="TableColumnConfig")
+        return self
+
+    @model_validator(mode="after")
+    def _validate_width_max_width_exclusive(self) -> TableColumnConfig:
+        if self.width is not None and self.max_width is not None:
+            raise ValueError(
+                "TableColumnConfig: 'width' and 'max_width' are mutually exclusive. "
+                "Use 'width' for a hard pin, or 'max_width' to cap auto-sizing."
+            )
+        return self
+
+
+# ============================================================================
+# CHART SORT
+# ============================================================================
+
+
+class ChartSort(BaseModel):
+    """Chart-level sort configuration for categorical axes."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    by: str = Field(description="Field name to sort by.")
+    order: Literal["asc", "desc"] = Field(
+        default="asc", description="Sort direction (asc or desc)."
+    )
+
+
+# ============================================================================
+# CHART SURFACE VALIDATION
+# ============================================================================
+
+_KPI_ONLY_FIELDS: dict[str, str] = {
+    "support": "structured support row beneath the headline value",
+    "label": "text rendered above the headline value",
+}
+
+# ============================================================================
+# LAYER PATCH — PER-LAYER AUTHORED INPUT
+# ============================================================================
+
+VALID_LAYER_TYPES: frozenset[str] = frozenset(
+    {
+        "bar",
+        "line",
+        "area",
+        "circle",
+        "square",
+        "tick",
+        "rule",
+        "trail",
+        "rect",
+        "image",
+        "scatter",
+    }
+)
+
+
+class ChartTotal(BaseModel):
+    """Donut center total — opt-in summary at the center of a pie chart."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    label: str | None = Field(
+        default=None, description="Caption text displayed below the center total value."
+    )
+    format: str | FormatConfig | None = Field(
+        default=None, description="Number format (D3 spec, preset, or FormatConfig)."
+    )
+
+
+class ChartLabels(BaseModel):
+    """Per-row text annotations rendered near each data anchor."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    template: str = Field(
+        description="Jinja2 template for the label text. Row fields are available as variables."
+    )
+    where: str | None = Field(
+        default=None,
+        description="Jinja2 boolean filter expression. Labels only render on rows where this is truthy.",
+    )
+
+    @field_validator("template")
+    @classmethod
+    def _validate_template(cls, value: str | None) -> str | None:
+        from dataface.core.compile.labels_env import label_jinja_env
+
+        if value is None:
+            return value
+        try:
+            label_jinja_env().parse(value)
+        except Exception as exc:
+            raise ValueError(f"Invalid Jinja template: {exc}") from exc
+        return value
+
+    @field_validator("where")
+    @classmethod
+    def _validate_where(cls, value: str | None) -> str | None:
+        from dataface.core.compile.labels_env import (
+            label_jinja_env,
+            strip_jinja_braces,
+        )
+
+        if value is None:
+            return value
+        try:
+            label_jinja_env().compile_expression(strip_jinja_braces(value))
+        except Exception as exc:
+            raise ValueError(f"Invalid Jinja expression: {exc}") from exc
+        return value
+
+
+class LayerAxisYStyle(BaseModel):
+    """Per-layer y-axis settings on a layered chart."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    orient: Literal["left", "right"] | None = Field(
+        default=None, description="Y-axis side for this layer (left or right)."
+    )
+    title: str | None = Field(
+        default=None, description="Y-axis title override for this layer."
+    )
+
+
+class Layer(BaseModel):
+    """A single layer in a layered chart authored YAML."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: str = Field(
+        description="Mark type for this layer (bar, line, area, circle, square, tick, rule, trail, rect, image, scatter)."
+    )
+    query: str | None = Field(
+        default=None,
+        description="Query name for this layer's data (overrides chart-level query).",
+    )
+    x: str | None = Field(default=None, description="X-axis field name for this layer.")
+    y: str | None = Field(default=None, description="Y-axis field name for this layer.")
+    label: str | None = Field(
+        default=None, description="Label field name for this layer."
+    )
+    color: str | None = Field(
+        default=None,
+        description="Color data channel for this layer: bare field name only.",
+    )
+    fill: str | None = Field(
+        default=None,
+        description="Static fill color for this layer (hex string). Use for fixed-color marks; `color` is for data channels.",
+    )
+    size: str | None = Field(
+        default=None, description="Size channel field name for this layer."
+    )
+    shape: str | None = Field(
+        default=None, description="Shape channel field name for this layer."
+    )
+    axis_y: LayerAxisYStyle | None = Field(
+        default=None, description="Y-axis settings for this layer (orientation, title)."
+    )
+
+    @field_validator("color", mode="before")
+    @classmethod
+    def _reject_non_column_color(cls, v: Any) -> Any:
+        if isinstance(v, str) and v.startswith("#"):
+            raise ValueError(
+                f"literal color '{v}' belongs in style:\n"
+                "  style:\n"
+                "    color: '#...'\n"
+                "Layer.color is a data channel (bare field name only)."
+            )
+        if isinstance(v, dict):
+            raise ValueError(
+                "Layer.color only accepts a bare field name (string). "
+                "Dicts (value, scale, when forms) are not supported on layers."
+            )
+        return v
+
+    @model_validator(mode="before")
+    @classmethod
+    def reject_vl_passthrough_fields(cls, data: Any) -> Any:
+        if isinstance(data, dict) and "encoding" in data:
+            raise ValueError(
+                "`encoding` is not part of the authored Dataface layer surface. "
+                "Use typed layer channels (`color`, `size`, `shape`) instead."
+            )
+        return data
+
+
+# ============================================================================
+# FILTER BINDING
+# ============================================================================
+
+# Canonical set of recognized filter operator keys.
+# filter_injection._OP_MAP holds the sqlglot-class mapping for SQL injection;
+# this set is the authoritative list for compile-time validation.
+FILTER_OPS: frozenset[str] = frozenset(
+    {"eq", "neq", "gt", "gte", "lt", "lte", "like", "ilike", "in", "not_in", "between"}
+)
+
+
+class FilterDef(BaseModel):
+    """One column→variable binding in chart.filters.
+
+    Authored in YAML as a plain variable name (implicit eq), a Jinja template
+    (implicit eq, resolved at execute time), or a single-key operator dict:
+
+        filters:
+          region: selected_region          → FilterDef(op="eq", var="selected_region")
+          region: "{{ selected_region }}"  → FilterDef(op="eq", template="{{ selected_region }}")
+          revenue:
+            gte: min_revenue               → FilterDef(op="gte", var="min_revenue")
+
+    Exactly one of ``var`` or ``template`` must be set. Operator dicts require
+    plain variable names; Jinja templates are not accepted in operator-dict values.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    op: Literal[
+        "eq",
+        "neq",
+        "gt",
+        "gte",
+        "lt",
+        "lte",
+        "like",
+        "ilike",
+        "in",
+        "not_in",
+        "between",
+    ] = Field(default="eq", description="Comparison operator. Defaults to 'eq'.")
+    var: str | None = Field(
+        default=None,
+        description="Plain variable name (no Jinja). Set when the filter value is a dashboard variable reference.",
+    )
+    template: str | None = Field(
+        default=None,
+        description="Jinja template resolved at execute time. Only valid with op='eq'. Set when conditional-disable or complex expressions are needed.",
+    )
+
+    @model_validator(mode="before")
+    @classmethod
+    def _from_yaml(cls, v: Any) -> dict[str, Any]:
+        """Coerce authored YAML shapes into normalized dict form.
+
+        Accepts four input forms:
+          - plain variable name:  "region_var"             → {op: "eq", var: "region_var"}
+          - Jinja template:       "{{ region_var }}"       → {op: "eq", template: "{{ region_var }}"}
+          - single-key op dict:   {"gte": "min_rev"}       → {op: "gte", var: "min_rev"}
+          - already-normalized:   {"op": X, "var": Y}      — passed through as-is
+                                  {"op": X, "template": Y} — passed through as-is
+        """
+        if isinstance(v, str):
+            if not v:
+                raise ValueError("filter value must be a non-empty string")
+            if "{{" in v or "}}" in v:
+                return {"op": "eq", "template": v}
+            return {"op": "eq", "var": v}
+        if isinstance(v, dict):
+            # Already-normalized form from programmatic construction — pass through.
+            if set(v.keys()) <= {"op", "var", "template"}:
+                return v
+            # YAML authored shape: single-key {operator: var_name} — plain var only.
+            if len(v) != 1:
+                raise ValueError(
+                    f"operator dict must have exactly one key, got {sorted(v.keys())!r}"
+                )
+            op, var = next(iter(v.items()))
+            if op not in FILTER_OPS:
+                raise ValueError(
+                    f"unknown operator {op!r}; must be one of {sorted(FILTER_OPS)}"
+                )
+            if not isinstance(var, str) or not var:
+                raise ValueError(
+                    f"filters.{op}: variable name must be a non-empty string"
+                )
+            if "{{" in var or "}}" in var:
+                raise ValueError(
+                    f"filters.{op}: Jinja templates are not allowed in operator-dict "
+                    f"filter values; use a plain variable name instead of {var!r}"
+                )
+            return {"op": op, "var": var}
+        raise ValueError(
+            f"filter binding must be a variable name string or single-key operator dict, "
+            f"got {type(v).__name__}"
+        )
+
+    @model_validator(mode="after")
+    def _exactly_one(self) -> FilterDef:
+        """Exactly one of var or template must be set; template requires op='eq'."""
+        if (self.var is None) == (self.template is None):
+            raise ValueError(
+                "FilterDef must set exactly one of var or template, "
+                f"got var={self.var!r}, template={self.template!r}"
+            )
+        if self.template is not None and self.op != "eq":
+            raise ValueError(
+                f"FilterDef.template is only valid with op='eq', got op={self.op!r}"
+            )
+        return self
+
+    def to_yaml_form(self) -> str | dict[str, str]:
+        """Return the canonical YAML-authored representation.
+
+        Template bindings and implicit-eq bindings round-trip as a plain string;
+        all other operators round-trip as a single-key operator dict.
+        """
+        if self.template is not None:
+            return self.template
+        assert self.var is not None  # enforced by _exactly_one
+        if self.op == "eq":
+            return self.var
+        return {self.op: self.var}
+
+
+# ============================================================================
+# CHART FIELD BASES
+# ============================================================================
+
+
+def _reject_color_dict(v: Any) -> Any:
+    """Shared validator: reject non-string chart.color values."""
+    if isinstance(v, str) and v.startswith("#"):
+        raise ValueError(
+            f"literal color '{v}' belongs in style:\n"
+            "  style:\n"
+            "    color: '#...'\n"
+            "chart.color is a data channel (bare field name only)."
+        )
+    if isinstance(v, dict):
+        if "value" in v:
+            raise ValueError(
+                "color: {value: ...} no longer accepted at chart root. "
+                "Move literal colors to style:\n"
+                "  style:\n    color: '#...'"
+            )
+        if "scale" in v:
+            raise ValueError(
+                "Inline scale config no longer accepted at chart.color. "
+                "Use style:\n"
+                "  style:\n    color: {scale: {palette: [...]}}"
+            )
+        if "when" in v:
+            raise ValueError(
+                "Inline conditional no longer accepted at chart.color. "
+                "Use conditional_formatting: for per-cell rules."
+            )
+        raise ValueError(
+            "chart.color only accepts a bare field name (string). "
+            "Use style.color for static paint or gradient scale."
+        )
+    return v
+
+
+class _SharedChartFields(BaseModel):
+    """Private base shared by ALL chart families (authored patches).
+
+    Contains only fields that every chart type meaningfully uses.
+    Per-family fields (x/y, theta, value, layers, message) are declared
+    on the family-specific *Patch classes, not here.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    # None = auto-generated chart id from YAML key when omitted.
+    id: Annotated[
+        str | None,
+        Field(
+            default=None,
+            description="Explicit chart ID (auto-generated from the chart's YAML key if omitted).",
+        ),
+    ]
+    # None = no chart title (KPI charts use label: on KpiChart, not title:).
+    title: Annotated[
+        str | None,
+        Field(
+            default=None,
+            description="Chart title displayed above the chart (not used on type: kpi).",
+        ),
+    ]
+    # None = no subtitle.
+    subtitle: Annotated[
+        str | None,
+        Field(default=None, description="Chart subtitle displayed below the title."),
+    ]
+    description: Annotated[
+        str | None,
+        Field(
+            default=None,
+            description="Human-readable description used by AI search and context tooltips.",
+        ),
+    ]
+    # None = author omitted query; normalizer supplies or errors at compile.
+    query: Annotated[
+        str | dict[str, Any] | None,
+        Field(
+            default=None,
+            description="Named query reference, inline AuthoredQuery, or SQL string shorthand.",
+        ),
+    ]
+    link: Annotated[
+        str | None,
+        Field(
+            default=None, description="Click-through URL template for drill-down links."
+        ),
+    ]
+
+    @model_validator(mode="before")
+    @classmethod
+    def _reject_href(cls, data: Any) -> Any:
+        if isinstance(data, dict) and "href" in data:
+            raise ValueError(
+                "'href:' was renamed to 'link:'. Use `link:` for click-through URLs."
+            )
+        return data
+
+    filters: Annotated[
+        dict[str, FilterDef] | None,
+        Field(
+            default=None,
+            description="Declarative column filters applied to chart data after query execution.",
+        ),
+    ]
+    conditional_formatting: Annotated[
+        dict[str, FieldConditionalFormatting] | None,
+        Field(
+            default=None,
+            description="Discrete rule-driven style overrides indexed by column name.",
+        ),
+    ]
+    # Excluded from compiled dict — layout hint only when patch is inline in rows/cols.
+    visible: Annotated[
+        bool | str | SingleRowBoolProbe | None,
+        Field(
+            default=None,
+            exclude=True,
+            description="Controls whether this layout item is rendered.",
+        ),
+    ]
+    # Widest base declaration; concrete subclasses narrow via Literal.
+    # Required — missing or unknown type raises a discriminator ValidationError.
+    type: str
+    warnings_ignore: Annotated[
+        list[str] | None,
+        Field(
+            default=None,
+            description="Codes of render warnings to suppress for this chart.",
+        ),
+    ]
+
+
+class _CartesianChartFields(_SharedChartFields):
+    """Private base for cartesian chart families (bar, line, area, scatter, heatmap).
+
+    Holds channel fields that only make sense on charts with x/y axes.
+    """
+
+    # None = field not encoded.
+    x: Annotated[
+        str | None,
+        Field(default=None, description="X-axis field name from the query result."),
+    ]
+    y: Annotated[
+        str | list[str] | None,
+        Field(
+            default=None,
+            description="Y-axis field name(s). Accepts a single field or list for multi-series charts.",
+        ),
+    ]
+    x_label: Annotated[
+        str | None, Field(default=None, description="Custom label for the X axis.")
+    ]
+    y_label: Annotated[
+        str | None, Field(default=None, description="Custom label for the Y axis.")
+    ]
+    # None = no color encoding (solid fill from theme).
+    color: Annotated[
+        str | None,
+        Field(default=None, description="Color data channel: bare field name only."),
+    ]
+    sort: Annotated[
+        ChartSort | None,
+        Field(
+            default=None,
+            description="Sort configuration: field to sort by and direction (asc/desc).",
+        ),
+    ]
+    labels: Annotated[
+        ChartLabels | None,
+        Field(
+            default=None, description="Per-row text annotations near each data anchor."
+        ),
+    ]
+    data_table: Annotated[
+        ChartDataTable | None,
+        Field(
+            default=None,
+            description="Optional mini data-grid attached below/above the chart.",
+        ),
+    ]
+    # None = no format override; axis/tooltip format falls back to theme.
+    format: Annotated[
+        str | FormatConfig | None,
+        Field(
+            default=None,
+            description="Number format: D3 format string, preset name, or FormatConfig object.",
+        ),
+    ]
+    # Box geometry — height and width at chart root, not in style:.
+    # aspect_ratio, min_height, max_height belong in style: (promoted to compiled Chart root).
+    # Renderer-owned types (kpi, table, callout, spark_bar) reject these via model_validator.
+    height: Annotated[
+        int | float | None,
+        Field(
+            default=None,
+            gt=0,
+            description=(
+                "Explicit chart height in pixels. Positive number only. When set, "
+                "overrides aspect_ratio and theme cascade. Not valid on kpi, table, "
+                "callout, or spark_bar \u2014 those renderers own their own sizing contracts."
+            ),
+        ),
+    ]
+    width: Annotated[
+        int | float | None,
+        Field(
+            default=None,
+            gt=0,
+            description=(
+                "Chart width hint in pixels. Positive number only. Used by the "
+                "label-overlap heuristic to determine whether x-axis labels need "
+                "tilting. Does not override the layout slot width — the chart "
+                "still fills its allocated container. Not valid on kpi, table, "
+                "callout, or spark_bar \u2014 those renderers own their own sizing contracts."
+            ),
+        ),
+    ]
+
+    @field_validator("color", mode="before")
+    @classmethod
+    def _reject_non_column_color(cls, v: Any) -> Any:
+        """Color is a data channel — only bare field names accepted at chart root."""
+        return _reject_color_dict(v)
+
+    @model_validator(mode="after")
+    def _validate_data_table(self) -> _CartesianChartFields:
+        if self.data_table is None:
+            return self
+        if self.type not in CHART_DATA_TABLE_SUPPORTED_TYPES:
+            supported = ", ".join(sorted(CHART_DATA_TABLE_SUPPORTED_TYPES))
+            raise ValueError(
+                f"chart.data_table is not supported for chart type "
+                f"{self.type!r} in v1. Supported chart types: {supported}."
+            )
+        if isinstance(self.y, list) and len(self.y) > 1:
+            all_by_measure = all(
+                isinstance(e, ChartDataTablePerSeries) and e.by_measure
+                for e in self.data_table.entries
+            )
+            if not all_by_measure:
+                raise ValueError(
+                    "chart.data_table is not supported on charts with a "
+                    "multi-field `y:` list unless every entry is a "
+                    "`per_series:` entry with `by_measure: true`. "
+                    "Collapse `y:` to one field, or use "
+                    "`{per_series: <alias>, by_measure: true}` entries."
+                )
+        has_per_series_needing_color = any(
+            isinstance(e, ChartDataTablePerSeries) and not e.by_measure
+            for e in self.data_table.entries
+        )
+        if has_per_series_needing_color:
+            color = self.color
+            has_color = color is not None and color != ""
+            if not has_color:
+                raise ValueError(
+                    "chart.data_table per_series: entries require the chart to have "
+                    "a color: channel. Add `color: <field>` to the chart."
+                )
+        validate_data_table_shape(self.data_table.entries)
+        return self
+
+
+class BasemapConfig(BaseModel):
+    """Tile-layer configuration for point_map and bubble_map charts.
+
+    extra="allow" so authors can pass arbitrary provider-specific keys;
+    typed fields here are the Dataface-documented surface.
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    type: str | None = Field(
+        default=None, description="Tile provider type (e.g. 'mapbox', 'raster')."
+    )
+    style: str | None = Field(
+        default=None, description="Tile style URL (e.g. Mapbox style URI)."
+    )
+    source: str | None = Field(
+        default=None,
+        description="Named geographic boundary source (e.g. 'us-states') for overlay rendering.",
+    )
+    attribution: str | None = Field(
+        default=None, description="Attribution text for the tile provider."
+    )
+    fill: str | None = Field(
+        default=None, description="Fill color for geographic boundary overlay."
+    )
+    stroke: str | None = Field(
+        default=None, description="Stroke color for geographic boundary overlay."
+    )
+
+
+class _GeoChartFields(_SharedChartFields):
+    """Private base for geographic chart families (map/geoshape, point_map/bubble_map)."""
+
+    # None = no projection specified; renderer uses default.
+    projection: Annotated[
+        str | Projection | None,
+        Field(
+            default=None,
+            description="Map projection name or Vega-Lite projection config.",
+        ),
+    ]
+    # None = no color encoding.
+    color: Annotated[
+        str | None,
+        Field(default=None, description="Color data channel: bare field name only."),
+    ]
+    geo: Annotated[
+        str | dict[str, Any] | None,
+        Field(
+            default=None,
+            description="GeoJSON field name or inline GeoJSON spec for geoshape charts.",
+        ),
+    ]
+    geo_source: Annotated[
+        str | None,
+        Field(
+            default=None,
+            description="Named geographic data source for loading GeoJSON boundaries.",
+        ),
+    ]
+    lookup: Annotated[
+        str | None,
+        Field(
+            default=None,
+            description="Data field to join against geographic data (map join key).",
+        ),
+    ]
+    # None = no value encoding (fill uses static color).
+    value: Annotated[
+        str | None,
+        Field(default=None, description="Data field mapped to the fill color."),
+    ]
+    # None = lat/lon not specified.
+    latitude: Annotated[
+        str | None,
+        Field(
+            default=None,
+            description="Field containing latitude values for point/bubble maps.",
+        ),
+    ]
+    longitude: Annotated[
+        str | None,
+        Field(
+            default=None,
+            description="Field containing longitude values for point/bubble maps.",
+        ),
+    ]
+
+    @field_validator("color", mode="before")
+    @classmethod
+    def _reject_non_column_color(cls, v: Any) -> Any:
+        if isinstance(v, str) and v.startswith("#"):
+            raise ValueError(
+                f"literal color '{v}' belongs in style:\n"
+                "  style:\n"
+                "    color: '#...'\n"
+                "chart.color is a data channel (bare field name only)."
+            )
+        if isinstance(v, dict):
+            raise ValueError("chart.color only accepts a bare field name (string).")
+        return v
+
+    @field_validator("projection", mode="before")
+    @classmethod
+    def _validate_projection(cls, value: Any) -> str | Projection | None:
+        return validate_projection_definition(value)
+
+
+class _RadialChartFields(_SharedChartFields):
+    """Private base for radial/arc chart families (pie, donut).
+
+    Holds channel fields that only make sense on arc charts with angular encoding.
+    """
+
+    theta: Annotated[
+        str, Field(description="Field for angular encoding in pie (arc) charts.")
+    ]
+    # None = no color encoding.
+    color: Annotated[
+        str | None,
+        Field(default=None, description="Color data channel: bare field name only."),
+    ]
+    total: Annotated[
+        ChartTotal | None, Field(default=None, description="Donut center total.")
+    ]
+    labels: Annotated[
+        ChartLabels | None,
+        Field(
+            default=None, description="Per-row text annotations near each data anchor."
+        ),
+    ]
+
+    @field_validator("color", mode="before")
+    @classmethod
+    def _reject_non_column_color(cls, v: Any) -> Any:
+        if isinstance(v, str) and v.startswith("#"):
+            raise ValueError(
+                f"literal color '{v}' belongs in style. chart.color is a data channel."
+            )
+        return v
+
+
+# ============================================================================
+# PER-FAMILY AUTHORED PATCHES
+# ============================================================================
+
+# --- Cartesian family ---
+
+
+class BarChart(_CartesianChartFields):
+    """Authored patch for bar and histogram charts."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: Annotated[
+        Literal["bar", "histogram"], Field(description="Bar or histogram chart type.")
+    ]
+    size: Annotated[
+        str | None,
+        Field(
+            default=None,
+            description="Field used to size-encode data points (quantitative).",
+        ),
+    ]
+    shape: Annotated[
+        str | None,
+        Field(
+            default=None,
+            description="Field used to shape-encode data points (categorical).",
+        ),
+    ]
+    style: Annotated[
+        BarChartStylePatch | None,
+        Field(default=None, description="Chart-local style overrides."),
+    ]
+
+
+class LineChart(_CartesianChartFields):
+    """Authored patch for line charts.
+
+    Intentionally excludes size, and shape — these channels are structurally
+    impossible on line charts. An attempt to set them raises extra_forbidden.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: Annotated[Literal["line"], Field(description="Line chart type.")]
+    style: Annotated[
+        LineChartStylePatch | None,
+        Field(default=None, description="Chart-local style overrides."),
+    ]
+
+
+class AreaChart(_CartesianChartFields):
+    """Authored patch for area charts."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: Annotated[Literal["area"], Field(description="Area chart type.")]
+    size: Annotated[
+        str | None,
+        Field(
+            default=None,
+            description="Field used to size-encode data points (quantitative).",
+        ),
+    ]
+    shape: Annotated[
+        str | None,
+        Field(
+            default=None,
+            description="Field used to shape-encode data points (categorical).",
+        ),
+    ]
+    style: Annotated[
+        AreaChartStylePatch | None,
+        Field(default=None, description="Chart-local style overrides."),
+    ]
+
+
+class ScatterChart(_CartesianChartFields):
+    """Authored patch for scatter charts."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: Annotated[Literal["scatter"], Field(description="Scatter chart type.")]
+    size: Annotated[
+        str | None,
+        Field(
+            default=None,
+            description="Field used to size-encode data points (quantitative).",
+        ),
+    ]
+    shape: Annotated[
+        str | None,
+        Field(
+            default=None,
+            description="Field used to shape-encode data points (categorical).",
+        ),
+    ]
+    style: Annotated[
+        ScatterChartStylePatch | None,
+        Field(default=None, description="Chart-local style overrides."),
+    ]
+
+
+class HeatmapChart(_CartesianChartFields):
+    """Authored patch for heatmap charts."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: Annotated[Literal["heatmap"], Field(description="Heatmap chart type.")]
+    size: Annotated[
+        str | None,
+        Field(
+            default=None,
+            description="Field used to size-encode data points (quantitative).",
+        ),
+    ]
+    shape: Annotated[
+        str | None,
+        Field(
+            default=None,
+            description="Field used to shape-encode data points (categorical).",
+        ),
+    ]
+    style: Annotated[
+        HeatmapChartStylePatch | None,
+        Field(default=None, description="Chart-local style overrides."),
+    ]
+
+
+# --- Arc family ---
+
+
+class PieChart(_RadialChartFields):
+    """Authored patch for pie and donut charts.
+
+    Pie charts use theta (angular) and color (segment) channels.
+    x/y/format/sort and other cartesian fields are not valid here.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: Annotated[
+        Literal["pie", "donut"], Field(description="Pie or donut chart type.")
+    ]
+    style: Annotated[
+        PieChartStylePatch | None,
+        Field(default=None, description="Chart-local style overrides."),
+    ]
+
+
+# --- KPI family ---
+
+
+class KpiChart(_SharedChartFields):
+    """Authored patch for KPI (key performance indicator) charts.
+
+    KPI charts do not use title: (use label: instead) and require value:.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: Annotated[Literal["kpi"], Field(description="KPI chart type.")]
+    value: Annotated[
+        str,
+        Field(
+            description="Column reference (string column name) for the headline number/text."
+        ),
+    ]
+    # None = no label above the headline value (slug auto-generated).
+    label: Annotated[
+        str | None,
+        Field(default=None, description="KPI label rendered above the headline value."),
+    ]
+    # None = no format override; value is rendered as-is.
+    format: Annotated[
+        str | FormatConfig | None,
+        Field(
+            default=None,
+            description="Number format applied to the headline value: D3 format string, preset name, or FormatConfig object.",
+        ),
+    ]
+    support: Annotated[
+        KpiSupportConfig | None,
+        Field(default=None, description="Optional support line beneath the KPI value."),
+    ]
+    style: Annotated[
+        KpiChartStylePatch | None,
+        Field(default=None, description="Chart-local style overrides."),
+    ]
+
+    @field_validator("value", mode="before")
+    @classmethod
+    def _reject_literal_value(cls, v: Any) -> Any:
+        if not isinstance(v, bool) and isinstance(v, (int, float)):
+            raise ValueError(
+                "value at chart root must be a column reference (string column name).\n"
+                f"Got numeric literal: {v}.\n"
+                "Channels are always column references; data values come from the query.\n"
+                "Update to:\n"
+                f"  query:\n    rows:\n      - count: {v}\n"
+                "  value: count\n"
+                "or write a SQL query:\n"
+                f'  query: "select {v} as count"\n'
+                "  value: count"
+            )
+        return v
+
+    @model_validator(mode="before")
+    @classmethod
+    def _reject_kpi_title_and_subtitle(cls, data: Any) -> Any:
+        if isinstance(data, dict):
+            if data.get("title"):
+                raise ValueError(
+                    "`title:` is not used on `type: kpi`. Use `label:` instead."
+                )
+            if data.get("subtitle"):
+                from dataface.core.compile.normalize_charts import (  # noqa: PLC0415
+                    _kpi_subtitle_error,
+                )
+
+                raise ValueError(_kpi_subtitle_error(data.get("id")))
+        return data
+
+    @model_validator(mode="before")
+    @classmethod
+    def _reject_glyph_and_tone_at_chart_root(cls, data: Any) -> Any:
+        if isinstance(data, dict):
+            if "glyph" in data:
+                raise ValueError(
+                    "'glyph:' has moved from the KPI chart root into the style namespace.\n"
+                    "Use style.glyph.character instead:\n\n"
+                    "  style:\n"
+                    "    glyph:\n"
+                    "      character: '▲'\n"
+                )
+            if "tone" in data:
+                raise ValueError(
+                    "'tone:' has moved from the KPI chart root into the style namespace.\n"
+                    "Use style.tone instead:\n\n"
+                    "  style:\n"
+                    "    tone: positive\n"
+                )
+        return data
+
+
+# --- Table family ---
+
+
+class TableChart(_SharedChartFields):
+    """Authored patch for table charts."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: Annotated[Literal["table"], Field(description="Table chart type.")]
+    style: Annotated[
+        TableChartStylePatch | None,
+        Field(default=None, description="Chart-local style overrides."),
+    ]
+
+
+# --- Geo family ---
+
+
+class PointMapChart(_GeoChartFields):
+    """Authored patch for point_map and bubble_map charts."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: Annotated[
+        Literal["point_map", "bubble_map"],
+        Field(description="Point map or bubble map chart type."),
+    ]
+    # None = no size encoding; bubbles use a fixed radius.
+    size: Annotated[
+        str | None,
+        Field(
+            default=None,
+            description="Data field used to scale bubble radius (quantitative). Only meaningful on bubble_map.",
+        ),
+    ]
+    basemap: Annotated[
+        BasemapConfig | None,
+        Field(
+            default=None, description="Tile-layer configuration for the map background."
+        ),
+    ]
+    style: Annotated[
+        PointMapChartStylePatch | None,
+        Field(default=None, description="Chart-local style overrides."),
+    ]
+
+
+class GeoshapeChart(_GeoChartFields):
+    """Authored patch for map and geoshape charts."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: Annotated[
+        Literal["map", "geoshape"], Field(description="Map or geoshape chart type.")
+    ]
+    style: Annotated[
+        GeoshapeChartStylePatch | None,
+        Field(default=None, description="Chart-local style overrides."),
+    ]
+
+
+# --- Layered family ---
+
+
+class LayeredChart(_SharedChartFields):
+    """Authored patch for layered multi-mark charts."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: Annotated[Literal["layered"], Field(description="Layered chart type.")]
+    layers: Annotated[
+        list[Layer],
+        Field(
+            min_length=1,
+            description="Layers for multi-mark charts. Each layer is a chart definition.",
+        ),
+    ]
+    x: Annotated[
+        str | None,
+        Field(default=None, description="Shared X-axis field name for all layers."),
+    ]
+    # None = no sort; layers render in query order.
+    sort: Annotated[
+        ChartSort | None,
+        Field(default=None, description="Sort configuration for the shared X axis."),
+    ]
+    x_domain: Annotated[
+        Literal["union", "primary"] | None,
+        Field(
+            default=None,
+            description="Controls how x-values from multiple layer queries are combined.",
+        ),
+    ]
+    data_table: Annotated[
+        ChartDataTable | None,
+        Field(
+            default=None, description="Optional mini data-grid attached to the chart."
+        ),
+    ]
+    # None = no format override.
+    format: Annotated[
+        str | FormatConfig | None,
+        Field(default=None, description="Number format override."),
+    ]
+    # Layered uses a flat bespoke style surface (LayeredChartStyle).
+    style: Annotated[
+        LayeredChartStyle | None,
+        Field(default=None, description="Chart-local style overrides."),
+    ]
+
+    @model_validator(mode="after")
+    def _validate_layered_constraints(self) -> LayeredChart:
+        if self.x_domain is not None:
+            if self.layers and self.layers[0].query is None:
+                raise ValueError(
+                    "x_domain requires the first layer to specify its own `query:`. "
+                    "The x-domain anchor is applied to the first layer's dataset; "
+                    "a first layer without a per-layer query has no dataset to anchor to."
+                )
+        if self.data_table is not None:
+            for i, layer in enumerate(self.layers):
+                if layer.query is not None:
+                    raise ValueError(
+                        f"chart.data_table is not supported on layered "
+                        f"charts with per-layer `query:` (layer {i} sets "
+                        f"query={layer.query!r})."
+                    )
+                if layer.x is not None and layer.x != self.x:
+                    if self.x is None:
+                        raise ValueError(
+                            f"chart.data_table requires a chart-level `x:` "
+                            f"on layered charts (layer {i} sets x={layer.x!r} "
+                            f"but the chart itself has no x)."
+                        )
+                    raise ValueError(
+                        f"chart.data_table is not supported on layered "
+                        f"charts with per-layer `x:` that differs from the "
+                        f"chart-level x (layer {i} sets x={layer.x!r}, "
+                        f"chart.x={self.x!r})."
+                    )
+            validate_data_table_shape(self.data_table.entries)
+        return self
+
+
+# --- Callout family ---
+
+
+class CalloutChart(BaseModel):
+    """Static callout/message chart. Minimal — no chrome, no styling, no query."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: Annotated[Literal["callout"], Field(description="Callout chart type.")]
+    message: Annotated[str, Field(description="Static message content.")]
+    title: Annotated[
+        str | None,
+        Field(
+            default=None, description="Optional chart title shown above the message."
+        ),
+    ] = None
+    style: Annotated[
+        CalloutChartStylePatch | None,
+        Field(default=None, description="Chart-local style overrides (tone)."),
+    ] = None
+    warnings_ignore: Annotated[
+        list[str] | None,
+        Field(
+            default=None,
+            description="Codes of render warnings to suppress for this chart.",
+        ),
+    ] = None
+
+    @model_validator(mode="before")
+    @classmethod
+    def _reject_tone_at_chart_root(cls, data: Any) -> Any:
+        if isinstance(data, dict) and "tone" in data:
+            raise ValueError(
+                "'tone:' has moved from the callout chart root into the style namespace.\n"
+                "Use style.tone instead:\n\n"
+                "  style:\n"
+                "    tone: negative\n"
+            )
+        return data
+
+
+# --- SparkBar family ---
+
+
+class SparkBarChart(_SharedChartFields):
+    """Authored patch for spark_bar charts (compact horizontal bars)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: Annotated[Literal["spark_bar"], Field(description="SparkBar chart type.")]
+    # None = auto-detected from query columns.
+    x: Annotated[
+        str | None, Field(default=None, description="X-axis (label) field name.")
+    ]
+    y: Annotated[
+        str | list[str] | None,
+        Field(default=None, description="Y-axis (value) field name(s)."),
+    ]
+    style: Annotated[
+        SparkBarChartStylePatch | None,
+        Field(default=None, description="Chart-local style overrides."),
+    ]
+
+
+# ============================================================================
+# AuthoredChart DISCRIMINATED UNION ALIAS
+# ============================================================================
+
+# Set of type values that have a dedicated family patch class.
+_DISCRIMINATED_AUTHORED_TYPES: frozenset[str] = frozenset(
+    {
+        "bar",
+        "histogram",
+        "line",
+        "area",
+        "scatter",
+        "heatmap",
+        "pie",
+        "donut",
+        "kpi",
+        "table",
+        "point_map",
+        "bubble_map",
+        "map",
+        "geoshape",
+        "layered",
+        "callout",
+        "spark_bar",
+    }
+)
+
+
+def _discriminate_authored_chart(v: Any) -> str | None:
+    """Custom discriminator: return type tag for the AuthoredChart union.
+
+    Returns None for unknown or missing type, which triggers Pydantic's
+    union_tag_not_found ValidationError — explicit and loud.
+    """
+    if isinstance(v, dict):
+        t = v.get("type")
+    elif isinstance(v, _SharedChartFields):
+        t = v.type
+    else:
+        return None
+    return t if isinstance(t, str) and t in _DISCRIMINATED_AUTHORED_TYPES else None
+
+
+AuthoredChart = Annotated[
+    Annotated[BarChart, Tag("bar")]
+    | Annotated[BarChart, Tag("histogram")]
+    | Annotated[LineChart, Tag("line")]
+    | Annotated[AreaChart, Tag("area")]
+    | Annotated[ScatterChart, Tag("scatter")]
+    | Annotated[HeatmapChart, Tag("heatmap")]
+    | Annotated[PieChart, Tag("pie")]
+    | Annotated[PieChart, Tag("donut")]
+    | Annotated[KpiChart, Tag("kpi")]
+    | Annotated[TableChart, Tag("table")]
+    | Annotated[PointMapChart, Tag("point_map")]
+    | Annotated[PointMapChart, Tag("bubble_map")]
+    | Annotated[GeoshapeChart, Tag("map")]
+    | Annotated[GeoshapeChart, Tag("geoshape")]
+    | Annotated[LayeredChart, Tag("layered")]
+    | Annotated[CalloutChart, Tag("callout")]
+    | Annotated[SparkBarChart, Tag("spark_bar")],
+    Discriminator(_discriminate_authored_chart),
+]
+"""Discriminated union of per-family authored chart patches.
+
+AuthoredChart is a type alias, not a BaseModel. Use TypeAdapter(AuthoredChart) for
+validation. Use isinstance(item, _SharedChartFields) to check if an object
+is any kind of chart patch. type: is mandatory; missing or unknown type raises
+a union_tag_not_found ValidationError.
+"""
+
+# ============================================================================
+# GEO CHART TYPES
+# ============================================================================
+
+GEO_CHART_TYPES: frozenset[str] = frozenset(
+    {"map", "geoshape", "point_map", "bubble_map"}
+)