dataface 0.1.2__py3-none-any.whl

dataface/core/render/chart/pipeline.py

@@ -0,0 +1,818 @@
+"""Chart enrichment and resolution pipeline."""
+
+from __future__ import annotations
+
+import copy
+import dataclasses
+import math
+from typing import Any, Literal
+
+from dataface.core.compile.channel import (
+    ResolvedStyleChannel,
+    normalize_chart_channels,
+    parse_style_channel,
+)
+from dataface.core.compile.chart_resolved import (
+    ChartLayer,
+    ResolvedChart,
+)
+from dataface.core.compile.chart_type_detection import detect_chart_type_full
+from dataface.core.compile.config import get_chart_rendering
+from dataface.core.compile.models.chart.authored import (
+    ColumnScaleConfig,
+    FieldConditionalFormatting,
+    Layer,
+    TableColumnConfig,
+)
+from dataface.core.compile.models.chart.compiled import Chart
+from dataface.core.compile.models.style.authored import (
+    ChartStylePatch,
+)
+from dataface.core.compile.models.style.compiled import InferenceStyle
+from dataface.core.compile.models.style.merged import (
+    MergedChartsStyle,
+    MergedStyle,
+)
+from dataface.core.compile.style_cascade import build_resolved_style
+from dataface.core.render.chart.decisions import enrich_chart as enrich_chart_semantics
+from dataface.core.render.chart.type_inference import infer_vega_type_from_data
+from dataface.core.render.font_measurement import get_font_measurer
+
+# Fraction of the chart's discrete-x width usable for axis label text. The
+# remainder accounts for the other-axis label band, chart-area inset, and
+# inter-bar gutters. Deliberately crude — catches the common long-vs-short
+# cases cleanly. Used by `_pick_tilt_angle` to decide which tilt increment
+# clears the per-band budget on a vertical bar's x-axis.
+_USABLE_LABEL_AXIS_RATIO = 0.8
+
+
+def _pick_tilt_angle(
+    x_field: str | None,
+    data: list[dict[str, Any]],
+    resolved_charts: MergedChartsStyle,
+    chart_width: float,
+) -> tuple[float, bool]:
+    """Walk axis_x.label.tilt_increments and pick the first angle that fits.
+
+    Returns ``(angle, fits)``. ``fits=False`` means every entry was too dense;
+    the caller should downgrade overlap to ``"parity"``.
+    """
+    increments = resolved_charts.axis_x.label.tilt_increments
+    # min_length=1 in the schema guarantees a non-empty list when the field is set.
+    # The fallback here covers the never-resolved sentinel case (e.g. axis_y).
+    if not increments:
+        return 0.0, True
+    if not x_field or not data:
+        return 0.0, True
+    labels = list({str(row.get(x_field, "")) for row in data[:100]})
+    labels = [label for label in labels if label]
+    n_labels = len(labels)
+    if n_labels == 0:
+        return 0.0, True
+    font = resolved_charts.axis_x.label.font
+    measurer = get_font_measurer(font.family)
+    max_width = max(measurer.measure(label, font.size) for label in labels)
+    usable_width = chart_width * _USABLE_LABEL_AXIS_RATIO
+    band = usable_width / n_labels
+    # Line height is per the rendered font; VL paints a single-line axis label.
+    line_height = font.size
+    for angle in increments:
+        radians = math.radians(abs(angle))
+        # Horizontal footprint of one label at this tilt: the label width
+        # projected onto x by cos(theta), plus the line-height projected by
+        # sin(theta) (a tilted label still bleeds half a line-height sideways).
+        footprint = max_width * math.cos(radians) + line_height * math.sin(radians)
+        if footprint <= band:
+            return angle, True
+    return increments[-1], False
+
+
+def _is_discrete_axis(
+    x_field: str | None,
+    data: list[dict[str, Any]],
+    time_unit: str | None = None,
+) -> bool:
+    """True iff the x-axis field renders as discrete categorical bands.
+
+    Any non-None ``time_unit`` forces continuous — cyclical units (monthofyear,
+    dayofweek, weekofyear, hourofday) emit nominal-looking labels but ride a
+    temporal scale where parity-drop is the right reduction strategy.
+
+    Without a time_unit, classification falls back to the data:
+      * temporal (ISO dates), quantitative (numbers), ordinal (date-like
+        strings like "Q1 2024") → continuous
+      * nominal string categories → discrete
+    """
+    if time_unit is not None:
+        return False
+    if not x_field or not data or x_field not in data[0]:
+        return False
+    return infer_vega_type_from_data(data, x_field) == "nominal"
+
+
+def _resolve_overlap_smart_x(
+    resolved_charts: MergedChartsStyle,
+    x_field: str | None,
+    data: list[dict[str, Any]],
+    chart_width: float,
+    time_unit: str | None = None,
+    authored_angle: float | None = None,
+    is_horizontal_bar: bool = False,
+) -> MergedChartsStyle:
+    """Resolve overlap='smart' on the x-axis cascade into a concrete value.
+
+    Dataface ``axis_x`` is always the categorical cascade. On horizontal bars
+    bar-flip routes axis_x to VL ``encoding["y"]``; on every other chart shape
+    it stays on VL ``encoding["x"]``.
+
+    Smart overlap contract:
+      * horizontal bar, no authored angle → ``angle=0`` + ``overlap='allow'``.
+        Horizontal bars carry category labels on VL y where tilt is wrong;
+        never parity-drop (every band must keep its label). Renderer grows
+        height from category count when the layout slot is too short.
+      * continuous x-axis, no authored angle → ``angle=0`` + ``overlap='parity'``.
+        Pins VL's adaptive daily-grain tilt and forces reliable parity-drop on
+        bucketed temporals.
+      * discrete vertical x-axis, no authored angle → walk ``tilt_increments``,
+        pick the first angle that fits, emit ``overlap='allow'``. If no angle
+        fits, fall through to the last increment + ``overlap='parity'``.
+      * authored angle (theme cascade or chart-local) → respect it, emit
+        ``overlap='allow'``. The author chose a tilt to avoid overlap.
+      * non-smart overlap values pass through unchanged.
+
+    ``authored_angle`` carries the chart-local angle if any; the theme-cascaded
+    angle lives on ``resolved_charts.axis_x.label.angle``. Either short-circuits
+    the picker so user-authored tilts are never overwritten.
+    """
+    label = resolved_charts.axis_x.label
+    if label.overlap != "smart":
+        return resolved_charts
+
+    effective_angle = authored_angle if authored_angle is not None else label.angle
+
+    if effective_angle is not None:
+        new_label = dataclasses.replace(label, overlap="allow")
+    elif is_horizontal_bar:
+        new_label = dataclasses.replace(label, overlap="allow", angle=0.0)
+    elif not _is_discrete_axis(x_field, data, time_unit=time_unit):
+        new_label = dataclasses.replace(label, overlap="parity", angle=0.0)
+    else:
+        angle, fits = _pick_tilt_angle(x_field, data, resolved_charts, chart_width)
+        new_label = dataclasses.replace(
+            label,
+            overlap="allow" if fits else "parity",
+            angle=float(angle),
+        )
+
+    new_axis_x = dataclasses.replace(resolved_charts.axis_x, label=new_label)
+    return dataclasses.replace(resolved_charts, axis_x=new_axis_x)
+
+
+# Title block + view padding above/below the plot when sizing horizontal bars.
+_HORIZONTAL_BAR_LAYOUT_CHROME_PX = 72.0
+
+
+def count_horizontal_bar_categories(
+    category_field: str | None,
+    data: list[dict[str, Any]],
+) -> int:
+    """Distinct category values on the authored ``x`` field (VL y after flip)."""
+    if not category_field or not data:
+        return 0
+    return len(
+        {
+            str(row[category_field])
+            for row in data
+            if category_field in row and row[category_field] is not None
+        }
+    )
+
+
+def min_height_for_horizontal_bar_categories(
+    n_categories: int,
+    resolved_charts: MergedChartsStyle,
+) -> float:
+    """Minimum chart height so every categorical band can show a flat y label."""
+    if n_categories <= 0:
+        return 0.0
+    label = resolved_charts.axis_x.label
+    bar_mark = resolved_charts.marks.bar
+    font_size = label.font.size
+    separation = label.separation
+    padding = label.padding
+    bar_size = bar_mark.size
+    assert (
+        font_size is not None
+    ), "axis_x.label.font.size unset — theme cascade must populate it"
+    assert (
+        separation is not None
+    ), "axis_x.label.separation unset — theme cascade must populate it"
+    assert (
+        padding is not None
+    ), "axis_x.label.padding unset — theme cascade must populate it"
+    assert bar_size is not None, "marks.bar.size unset — theme cascade must populate it"
+    label_line = font_size + 2 * padding
+    band_step = max(bar_size, label_line) + separation
+    return _HORIZONTAL_BAR_LAYOUT_CHROME_PX + n_categories * band_step
+
+
+def _family_patch_for(style: ChartStylePatch | Any, chart_type: str) -> Any:
+    """Return the family sub-patch for chart_type, or None.
+
+    Uses the same chart-type → family-key mapping as _normalize_chart so
+    pipeline reads are consistent with how the patch was written.
+    """
+    from dataface.core.compile.normalize_charts import (
+        _AUTHORED_FAMILY_TO_MONOLITHIC_KEY,
+    )
+    from dataface.core.compile.style_cascade import _get_primary_patch
+
+    if not isinstance(style, ChartStylePatch):
+        return None
+    key = _AUTHORED_FAMILY_TO_MONOLITHIC_KEY.get(chart_type)
+    if key is not None:
+        return getattr(style, key, None)
+    # For types not in the mapping (layered, auto, …) fall back to the first
+    # non-null family patch.
+    return _get_primary_patch(style)
+
+
+def _read_authored_format(chart: Chart | Any) -> Any:
+    """Extract authored y-axis format from chart.format or style.axis_y.format."""
+    if chart.format:
+        return chart.format
+    style = getattr(chart, "style", None)
+    patch = _family_patch_for(style, getattr(chart, "type", ""))
+    axis_y = getattr(patch, "axis_y", None) if patch is not None else None
+    return axis_y.format if axis_y is not None else None
+
+
+def _read_authored_zero(chart: Chart | Any) -> Any:
+    """Extract authored scale zero from style.scale.zero."""
+    style = getattr(chart, "style", None)
+    patch = _family_patch_for(style, getattr(chart, "type", ""))
+    scale = getattr(patch, "scale", None) if patch is not None else None
+    return scale.zero if scale is not None else None
+
+
+def _read_authored_stack(chart: Chart | Any) -> Any:
+    """Cascade stack: top-level chart.stack wins; fall back to style.stack."""
+    top = getattr(chart, "stack", None)
+    if top is not None:
+        return top
+    style = getattr(chart, "style", None)
+    patch = _family_patch_for(style, getattr(chart, "type", ""))
+    return getattr(patch, "stack", None) if patch is not None else None
+
+
+def _convert_layers(
+    raw_layers: list[Layer] | None,
+) -> tuple[ChartLayer, ...]:
+    """Convert authored Layer objects to frozen ChartLayer tuples.
+
+    By the time this runs, Pydantic has already coerced dicts to Layer
+    (Chart.layers is ``list[Layer] | None``).
+    """
+    if not raw_layers:
+        return ()
+    return tuple(
+        ChartLayer(
+            chart_type=layer.type,
+            query_name=layer.query,
+            x=layer.x,
+            y=layer.y,
+            label=layer.label,
+            color=layer.color,
+            fill=layer.fill,
+            size=layer.size,
+            shape=layer.shape,
+            axis_y=(
+                layer.axis_y.model_dump(exclude_none=True)
+                if layer.axis_y is not None
+                else None
+            ),
+        )
+        for layer in raw_layers
+    )
+
+
+def _authored_color_field(chart: Chart | Any) -> str | None:
+    """Return the authored color data field using the canonical parser."""
+    color = getattr(chart, "color", None)
+    if color is None:
+        return None
+    ch = parse_style_channel(color, "color")
+    return ch.data_field or None
+
+
+def _chart_for_decisions(
+    chart: Chart | Any,
+    resolved_type: str,
+) -> Chart | Any:
+    """Return chart with resolved type for the decisions enrichment helper."""
+    if resolved_type == getattr(chart, "type", None):
+        return chart
+    if isinstance(chart, Chart):
+        return chart.model_copy(update={"type": resolved_type})
+    chart_copy = copy.copy(chart)
+    chart_copy.type = resolved_type
+    return chart_copy
+
+
+def compute_enrichments(
+    chart: Chart | Any,
+    data: list[dict[str, Any]],
+    column_descriptions: dict[str, tuple] | None = None,
+    *,
+    inference: InferenceStyle,
+) -> dict[str, Any]:
+    """Compute data-driven field inferences. Returns sparse dict of inferred values only."""
+    if not data:
+        return {}
+
+    authored_zero = _read_authored_zero(chart)
+    infer_zero = inference.infer_zero_when_missing and authored_zero is None
+
+    chart_type = getattr(chart, "type", None) or "auto"
+    needs_type = chart_type == "auto"
+    needs_fields = (
+        any(getattr(chart, f, None) is None for f in ("x", "y", "theta"))
+        or getattr(chart, "color", None) is None
+    )
+
+    if not (needs_type or needs_fields or infer_zero):
+        return {}
+
+    inferred: dict[str, Any] = {}
+    has_authored_color = getattr(chart, "color", None) is not None
+    authored_color_field = _authored_color_field(chart)
+    value = getattr(chart, "value", None)
+    value_for_inference = value if isinstance(value, str) else None
+
+    if inference.infer_type_when_auto and needs_type:
+        y = getattr(chart, "y", None)
+        result = detect_chart_type_full(
+            data,
+            x_field=getattr(chart, "x", None),
+            y_field=(y[0] if isinstance(y, list) else y),
+            color_field=authored_color_field,
+            value_field=value_for_inference,
+            column_descriptions=column_descriptions,
+        )
+        inferred["chart_type"] = result.chart_type
+        if value_for_inference is None and result.value:
+            inferred["value"] = result.value
+        if getattr(chart, "theta", None) is None and result.theta:
+            inferred["theta"] = result.theta
+        if getattr(chart, "x", None) is None and result.x:
+            inferred["x"] = result.x
+        if getattr(chart, "y", None) is None and result.y:
+            inferred["y"] = result.y
+        if not has_authored_color and result.color:
+            inferred["color"] = result.color
+
+    resolved_type = inferred.get("chart_type", chart_type)
+    enriched = enrich_chart_semantics(
+        _chart_for_decisions(chart, resolved_type), data, column_descriptions
+    )
+
+    if inference.infer_fields_when_missing:
+        if getattr(chart, "x", None) is None and getattr(enriched, "x", None):
+            inferred.setdefault("x", enriched.x)
+        if getattr(chart, "y", None) is None and getattr(enriched, "y", None):
+            inferred.setdefault("y", enriched.y)
+        if not has_authored_color and getattr(enriched, "color", None):
+            inferred.setdefault("color", enriched.color)
+        enriched_value = getattr(enriched, "value", None)
+        if value_for_inference is None and isinstance(enriched_value, str):
+            inferred.setdefault("value", enriched_value)
+        if getattr(chart, "theta", None) is None and getattr(enriched, "theta", None):
+            inferred.setdefault("theta", enriched.theta)
+
+    if infer_zero:
+        enriched_style = getattr(enriched, "style", None)
+        if isinstance(enriched_style, ChartStylePatch):
+            enriched_patch = _family_patch_for(enriched_style, chart_type)
+            _ep_scale = (
+                getattr(enriched_patch, "scale", None)
+                if enriched_patch is not None
+                else None
+            )
+            if _ep_scale is not None and _ep_scale.zero is not None:
+                inferred["zero"] = _ep_scale.zero
+
+    return inferred
+
+
+_TABLE_COLOR_CHANNELS = frozenset({"color", "background"})
+_TABLE_LOWERABLE_MODES = frozenset({"gradient"})
+
+
+def _build_col_map(
+    existing_cols: dict[str, Any],
+    lowerable: dict[str, Any],
+) -> dict[str, TableColumnConfig]:
+    """Build column→TableColumnConfig map from existing columns, updated with
+    per-channel gradients.
+    """
+    col_map: dict[str, TableColumnConfig] = {}
+    for field_name, col_cfg in existing_cols.items():
+        if isinstance(col_cfg, TableColumnConfig):
+            col_map[field_name] = col_cfg
+        elif isinstance(col_cfg, dict):
+            col_map[field_name] = TableColumnConfig.model_validate(col_cfg)
+
+    # Lower per-channel gradients (color.scale, background.scale) onto the
+    # target column's ColumnScaleConfig.
+    for ch_name, ch in lowerable.items():
+        field_name = ch.data_field
+        existing_cfg = col_map.get(field_name) or TableColumnConfig()
+        existing_scale = existing_cfg.scale or ColumnScaleConfig()
+        new_scale = existing_scale.model_copy(update={ch_name: ch.scale})
+        col_map[field_name] = existing_cfg.model_copy(update={"scale": new_scale})
+
+    return col_map
+
+
+def _apply_col_map(
+    existing_cols: dict[str, Any],
+    col_map: dict[str, TableColumnConfig],
+) -> dict[str, TableColumnConfig]:
+    """Merge col_map back into the columns dict, preserving authoring order and appending new columns."""
+    result: dict[str, TableColumnConfig] = {}
+    for field_name, col_cfg in existing_cols.items():
+        if field_name in col_map:
+            result[field_name] = col_map[field_name]
+        elif isinstance(col_cfg, TableColumnConfig):
+            result[field_name] = col_cfg
+        elif isinstance(col_cfg, dict):
+            result[field_name] = TableColumnConfig.model_validate(col_cfg)
+        else:
+            result[field_name] = TableColumnConfig()
+    for field_name, cfg in col_map.items():
+        if field_name not in result:
+            result[field_name] = cfg
+    return result
+
+
+def _lower_channels_to_table(
+    resolved: ResolvedChart,
+    resolved_channels: dict[str, Any],
+) -> tuple[ResolvedChart, dict[str, Any]]:
+    """Lower chart-level gradient channels onto ``style.columns[*].scale``.
+
+    Channels in gradient mode lower onto ``TableColumnConfig.scale`` so the
+    table renderer can interpolate a per-cell color from the column value.
+    Threshold rules (``conditional_formatting``) are read directly by the
+    table renderer from the chart-level block — no lowering required.
+    """
+    unsupported = [ch for ch in resolved_channels if ch not in _TABLE_COLOR_CHANNELS]
+    if unsupported:
+        raise ValueError(
+            f"Table charts do not support channel(s): {sorted(unsupported)}. "
+            "Meaningful table channels: color, background."
+        )
+
+    lowerable: dict[str, Any] = {}
+    for ch_name, ch in resolved_channels.items():
+        if ch_name not in _TABLE_COLOR_CHANNELS:
+            continue
+        if ch.mode not in _TABLE_LOWERABLE_MODES:
+            raise ValueError(
+                f"Table chart does not support chart.{ch_name} in '{ch.mode}' mode. "
+                f"Tables render one cell per row — use "
+                f"chart.conditional_formatting.<column>.when for threshold coloring or "
+                f"chart.{ch_name}: {{column: X, scale: {{palette: [...]}}}} "
+                "for gradient coloring."
+            )
+        lowerable[ch_name] = ch
+
+    if not lowerable:
+        return resolved, resolved_channels
+
+    existing_cols: dict[str, Any] = dict(resolved.columns or {})
+    col_map = _build_col_map(existing_cols, lowerable)
+    new_columns = _apply_col_map(existing_cols, col_map)
+    remaining = {k: v for k, v in resolved_channels.items() if k not in lowerable}
+    return dataclasses.replace(resolved, columns=new_columns), remaining
+
+
+# Chart types where the `color` channel paints the mark (so rule.background
+# lowers into a mark-fill VL condition). Other VL types (arc/pie/rect/etc.)
+# also use color for the mark fill; this set is the intersection that the
+# current migrator + tests exercise.
+_MARK_FILL_CHART_TYPES: frozenset[str] = frozenset({"bar", "line", "area", "scatter"})
+
+
+def _project_conditional_formatting(
+    chart: Any,
+    available_columns: set[str],
+) -> dict[str, ResolvedStyleChannel]:
+    """Project ``chart.conditional_formatting`` into per-channel conditional channels.
+
+    Projection rules:
+      * bar/line/area/scatter: rules with ``background`` lower into the
+        ``color`` channel (mark fill) as a VL condition list. Font-only rules
+        are ignored — marks have no text.
+      * kpi: rules with ``background`` lower into the ``background`` channel
+        (card fill). Rules with ``font.color`` lower into the ``color``
+        channel (number text).
+
+    Multi-column support is deferred; tests today exercise one metric column
+    per chart. Raises ValueError on unknown columns or multi-column usage.
+    """
+    cf: dict[str, FieldConditionalFormatting] | None = getattr(
+        chart, "conditional_formatting", None
+    )
+    if not cf:
+        return {}
+
+    chart_type = getattr(chart, "type", None)
+    for column_name in cf:
+        if available_columns and column_name not in available_columns:
+            raise ValueError(
+                f"conditional_formatting targets column '{column_name}' which is "
+                f"not in the query result. Available: {sorted(available_columns)}"
+            )
+
+    if chart_type in _MARK_FILL_CHART_TYPES:
+        outputs = {"color": lambda r: r.background}
+    elif chart_type == "kpi":
+        outputs = {
+            "background": lambda r: r.background,
+            "color": lambda r: r.font.color if r.font is not None else None,
+        }
+    else:
+        return {}
+
+    projected: dict[str, ResolvedStyleChannel] = {}
+    for channel_name, extractor in outputs.items():
+        per_column = [
+            (column, tuple(r for r in entry.when if extractor(r) is not None))
+            for column, entry in cf.items()
+        ]
+        per_column = [(c, rs) for c, rs in per_column if rs]
+        if not per_column:
+            continue
+        if len(per_column) > 1:
+            raise ValueError(
+                f"conditional_formatting on channel '{channel_name}' supports "
+                "one column's rules per chart in v1 — got rules for: "
+                f"{sorted(c for c, _ in per_column)}."
+            )
+        column, rules = per_column[0]
+        projected[channel_name] = ResolvedStyleChannel(
+            channel=channel_name,
+            mode="conditional",
+            data_field=column,
+            rules=rules,
+        )
+    return projected
+
+
+def _available_columns_for_validation(
+    chart: Chart | Any,
+    data: list[dict[str, Any]],
+) -> set[str]:
+    """Return columns visible to chart-level validation.
+
+    Query-level pivot keeps SQL long-form but table rendering sees generated
+    wide columns named from the pivot column values. Validation must recognize
+    those generated columns or table conditional formatting cannot target them.
+    """
+    if not data:
+        return set()
+
+    columns = set(data[0].keys())
+    chart_pivot = getattr(getattr(chart, "query", None), "pivot", None)
+    if (
+        getattr(chart, "type", None) == "table"
+        and chart_pivot is not None
+        and chart_pivot.column in columns
+        and chart_pivot.value in columns
+    ):
+        pivot_columns = {str(row[chart_pivot.column]) for row in data}
+        return (columns - {chart_pivot.column, chart_pivot.value}) | pivot_columns
+
+    return columns
+
+
+def resolve_chart(
+    chart: Chart | Any,
+    data: list[dict[str, Any]],
+    column_descriptions: dict[str, tuple] | None = None,
+    *,
+    # Intentionally optional: resolve_chart serves both visual rendering (where
+    # callers thread the face's MergedStyle) and non-visual resolution (type
+    # inference, axis analysis, label routing) where no board style is needed.
+    # Renderer callers that require visual fidelity must pass board_style;
+    # SvgRenderer and the geo branches of render_standard_vega_spec raise if
+    # resolved_style is absent rather than synthesising a silent default.
+    board_style: MergedStyle | None = None,
+) -> ResolvedChart:
+    """Resolve a chart into render-ready semantics."""
+    chart_style = getattr(chart, "style", None)
+    _authored_type = getattr(chart, "type", None) or "auto"
+    # Pass the authored chart type so build_resolved_style can apply per-family
+    # theme patches (e.g. editorial bar.legend.disable: false). Skip when type is
+    # "auto" — the concrete type isn't known until after compute_enrichments.
+    _build_chart_type = _authored_type if _authored_type != "auto" else None
+    resolved_style = build_resolved_style(
+        board_style, chart_style, chart_type=_build_chart_type
+    )
+    inference = resolved_style.inference
+
+    authored_format = _read_authored_format(chart)
+    authored_zero = _read_authored_zero(chart)
+    inferred = compute_enrichments(
+        chart, data, column_descriptions, inference=inference
+    )
+
+    chart_type = _authored_type
+    resolved_type = (
+        inferred.get("chart_type", chart_type) if chart_type == "auto" else chart_type
+    )
+
+    # When ``type: auto`` resolves to ``kpi`` at render time, the normalizer
+    # routed the chart-id slug into ``title`` (because chart_type was ``auto``
+    # at normalize time, not ``kpi``). Carry that auto-derived text into
+    # ``label`` so the KPI renderer reads the intended display string instead
+    # of falling through to the value-column name.
+    chart_label = getattr(chart, "label", "") or ""
+    chart_title = getattr(chart, "title", "") or ""
+    if resolved_type == "kpi" and not chart_label and chart_title:
+        resolved_label = chart_title
+        resolved_title = ""
+    else:
+        resolved_label = chart_label
+        resolved_title = chart_title
+
+    # Active family sub-patch for shared-field reads (axis_x, orientation, etc.)
+    family_patch = _family_patch_for(chart_style, chart_type)
+
+    x_field_for_overlap = getattr(chart, "x", None) or inferred.get("x")
+    chart_width_for_overlap = (
+        getattr(chart, "width", None) or get_chart_rendering().default_width
+    )
+    _fp_axis_x = (
+        getattr(family_patch, "axis_x", None) if family_patch is not None else None
+    )
+    chart_time_unit = _fp_axis_x.time_unit if _fp_axis_x is not None else None
+
+    # Bar orientation is type-driven. Discrete x (nominal categories)
+    # reads naturally horizontal; continuous x (temporal, quantitative,
+    # date-like ordinal, time_unit-bucketed) reads naturally vertical. Same
+    # `_is_discrete_axis` helper that drives the smart-tilt resolver.
+    authored_orientation = (
+        getattr(family_patch, "orientation", None) if family_patch is not None else None
+    )
+    if authored_orientation in ("horizontal", "vertical"):
+        orientation: Literal["horizontal", "vertical"] = authored_orientation
+    elif resolved_type == "bar" and _is_discrete_axis(
+        x_field_for_overlap, data, time_unit=chart_time_unit
+    ):
+        orientation = "horizontal"
+    else:
+        orientation = "vertical"
+    # Chart-local style.axis_x.label.angle lives on the chart Patch, not on the
+    # theme-cascaded resolved_style.axis_x — build_resolved_style routes it to
+    # axis_overrides_x for emit-time merging. Surface it here so the dispatcher
+    # can short-circuit the picker when an author specified a tilt directly.
+    _fp_axis_x_label = (
+        getattr(_fp_axis_x, "label", None) if _fp_axis_x is not None else None
+    )
+    chart_authored_angle = (
+        _fp_axis_x_label.angle if _fp_axis_x_label is not None else None
+    )
+    resolved_style = _resolve_overlap_smart_x(
+        resolved_style,
+        x_field_for_overlap,
+        data,
+        chart_width_for_overlap,
+        time_unit=chart_time_unit,
+        authored_angle=chart_authored_angle,
+        is_horizontal_bar=(resolved_type == "bar" and orientation == "horizontal"),
+    )
+
+    # Table-specific fields live on the table family sub-patch.
+    table_patch = (
+        getattr(chart_style, "table", None) if chart_style is not None else None
+    )
+    style_columns = table_patch.columns if table_patch is not None else None
+    header_overflow = table_patch.header_overflow if table_patch is not None else None
+    column_defaults = table_patch.column_defaults if table_patch is not None else None
+
+    resolved = ResolvedChart(
+        source_chart=chart,
+        id=getattr(chart, "id", "unknown"),
+        chart_type=resolved_type,
+        title=resolved_title,
+        subtitle=getattr(chart, "subtitle", "") or "",
+        description=getattr(chart, "description", "") or "",
+        label=resolved_label,
+        x=(
+            getattr(chart, "x", None)
+            if getattr(chart, "x", None) is not None
+            else inferred.get("x")
+        ),
+        y=(
+            getattr(chart, "y", None)
+            if getattr(chart, "y", None) is not None
+            else inferred.get("y")
+        ),
+        size=getattr(chart, "size", None),
+        shape=getattr(chart, "shape", None),
+        theta=(
+            getattr(chart, "theta", None)
+            if getattr(chart, "theta", None) is not None
+            else inferred.get("theta")
+        ),
+        total=getattr(chart, "total", None),
+        labels=getattr(chart, "labels", None),
+        format=authored_format,
+        message=getattr(chart, "message", None),
+        zero=authored_zero if authored_zero is not None else inferred.get("zero"),
+        x_label=getattr(chart, "x_label", None),
+        y_label=getattr(chart, "y_label", None),
+        geo=getattr(chart, "geo", None),
+        geo_source=getattr(chart, "geo_source", None),
+        lookup=getattr(chart, "lookup", None),
+        value=(
+            getattr(chart, "value", None)
+            if getattr(chart, "value", None) is not None
+            else inferred.get("value")
+        ),
+        support=getattr(chart, "support", None),
+        projection=getattr(chart, "projection", None),
+        latitude=getattr(chart, "latitude", None),
+        longitude=getattr(chart, "longitude", None),
+        basemap=getattr(chart, "basemap", None),
+        sort=getattr(chart, "sort", None),
+        stack=_read_authored_stack(chart),
+        orientation=orientation,
+        link=getattr(chart, "link", None),
+        query_name=getattr(chart, "query_name", None),
+        variable_dependencies=set(getattr(chart, "variable_dependencies", set())),
+        resolved_style=resolved_style,
+        columns=style_columns,
+        header_overflow=header_overflow,
+        column_defaults=column_defaults,
+        layers=_convert_layers(getattr(chart, "layers", None)),
+        x_domain=getattr(chart, "x_domain", None),
+    )
+
+    available_cols = _available_columns_for_validation(chart, data)
+    style_color = (
+        getattr(family_patch, "color", None) if family_patch is not None else None
+    )
+    resolved_channels = normalize_chart_channels(
+        chart, available_cols, style_color=style_color
+    )
+
+    # Project the chart-level conditional_formatting block into synthetic
+    # per-channel conditional channels for VL mark-fill chart types and KPI.
+    # Tables read the block directly at render time; projection is a no-op
+    # there but the unknown-column validation still runs.
+    projected = _project_conditional_formatting(chart, available_cols)
+    for channel_name, projected_ch in projected.items():
+        if channel_name in resolved_channels:
+            existing = resolved_channels[channel_name]
+            # Gradient + conditional on the same channel: compose them so
+            # threshold rules take priority and the gradient shows through when
+            # no rule matches.  This mirrors Looker's "scale with rule override"
+            # behaviour and is the only safe composition — all other conflicts
+            # (e.g. two gradients, literal + conditional) remain an error.
+            if existing.mode == "gradient" and projected_ch.mode == "conditional":
+                projected_ch = dataclasses.replace(
+                    projected_ch, fallback_scale=existing.scale
+                )
+            else:
+                raise ValueError(
+                    f"chart.{channel_name} conflicts with conditional_formatting "
+                    f"rules on column '{projected_ch.data_field}'. Use one surface: "
+                    "per-channel encoding (scale/value/column) OR rule-driven "
+                    "conditional_formatting."
+                )
+        resolved_channels[channel_name] = projected_ch
+
+    # Add enrichment-inferred color channel when the user did not author one.
+    # Must happen before table lowering so the injected channel passes through
+    # the same lowering gate as authored channels.
+    inferred_color = inferred.get("color")
+    if inferred_color and "color" not in resolved_channels:
+        resolved_channels = {
+            **resolved_channels,
+            "color": ResolvedStyleChannel(
+                channel="color", mode="series", data_field=str(inferred_color)
+            ),
+        }
+
+    if resolved.chart_type == "table" and resolved_channels:
+        resolved, resolved_channels = _lower_channels_to_table(
+            resolved, resolved_channels
+        )
+
+    return dataclasses.replace(
+        resolved,
+        resolved_channels=resolved_channels,
+    )