dataface 0.1.2__py3-none-any.whl

dataface/core/compile/style_cascade.py

@@ -0,0 +1,471 @@
+"""Per-chart style cascade — merges chart-local ChartStylePatch into MergedChartsStyle.
+
+Stage: COMPILE (pure — no render imports)
+Purpose: Given a board MergedStyle and a chart-local ChartStylePatch, produce
+the fully-merged MergedChartsStyle that the render layer consumes.
+
+Architectural directive: render code reads only resolved_style.* — it never sees
+the chart-local Patch. After build_resolved_style runs, every authored override
+(axis, legend, scale, mark, palette, title, …) is baked into the resolved
+fields. The renderer reads `resolved_style.axis_x.label.padding` and gets the
+final value with no authored-vs-cascaded discrimination.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from typing import Any, Literal
+
+from dataface.core.compile.config import get_config
+from dataface.core.compile.models.style.authored import (
+    AreaChartStylePatch,
+    BarChartStylePatch,
+    ChartStylePatch,
+    LayeredChartStyle,
+    LegendStylePatch,
+    LineChartStylePatch,
+)
+from dataface.core.compile.models.style.compiled import (
+    AxisStyle,
+    AxisStylePatch,
+    InferenceStyle,
+)
+
+# Family sub-patch keys in author-precedence order.  The cascade reads global
+# fields (palette, background, inference, …) from the FIRST non-null sub-patch.
+# For non-layered charts exactly one key is set; for layered charts the first
+# non-null entry wins for shared fields.
+_ALL_FAMILY_KEYS: tuple[str, ...] = (
+    "bar",
+    "line",
+    "area",
+    "scatter",
+    "pie",
+    "kpi",
+    "spark_bar",
+    "spark",
+    "table",
+    "heatmap",
+    "geoshape",
+    "point_map",
+)
+from dataface.core.compile.models.style.merged import (
+    MergedChartsStyle,
+    MergedLegendStyle,
+    MergedStyle,
+    _resolve_color_tokens,
+    deep_merge,
+    resolve_style,
+)
+
+
+def _get_primary_patch(chart_style: ChartStylePatch) -> Any:
+    """Return the first non-null family sub-patch, or None.
+
+    For non-layered charts exactly one family slot is set; that patch carries
+    both the shared fields (palette, background, inference, …) and any
+    family-specific overrides.  For layered charts ``layered`` is checked first;
+    it carries all shared cartesian fields directly on the flat surface.
+    """
+    layered = getattr(chart_style, "layered", None)
+    if layered is not None:
+        return layered
+    for key in _ALL_FAMILY_KEYS:
+        patch = getattr(chart_style, key, None)
+        if patch is not None:
+            return patch
+    return None
+
+
+def _chart_style_has_overrides(style: ChartStylePatch | None) -> bool:
+    if style is None:
+        return False
+    return any(v is not None for v in style.model_dump().values())
+
+
+def _has_family_legend_patch(
+    base_charts: MergedChartsStyle, chart_type: str | None
+) -> bool:
+    """Return True if chart_type has a non-None legend patch in the theme family style.
+
+    Used to bypass the fast path when a per-family legend override exists in the theme
+    but no chart-local style override is authored.
+    """
+    if not chart_type:
+        return False
+    family = getattr(base_charts, chart_type, None)
+    if family is None:
+        return False
+    return getattr(family, "legend", None) is not None
+
+
+def _merge_legend(
+    base: MergedLegendStyle, patch: LegendStylePatch | None
+) -> MergedLegendStyle:
+    """Merge a LegendStylePatch onto a MergedLegendStyle.
+
+    Patch is a typed all-Optional model — direct attribute access; no
+    ``getattr`` defensiveness. Non-None patch fields win; None preserves base.
+    """
+    if patch is None:
+        return base
+    updates: dict[str, Any] = {}
+    if patch.orient is not None:
+        updates["orient"] = patch.orient
+    if patch.direction is not None:
+        updates["direction"] = patch.direction
+    if patch.disable is not None:
+        updates["disable"] = patch.disable
+    for sub_name in ("label", "title"):
+        sub_patch = getattr(patch, sub_name)
+        if sub_patch is None:
+            continue
+        sub_base = getattr(base, sub_name)
+        sub_updates: dict[str, Any] = {}
+        if sub_patch.padding is not None:
+            sub_updates["padding"] = sub_patch.padding
+        if sub_patch.font is not None:
+            font_updates = {
+                f: v
+                for f in ("family", "color", "size", "weight")
+                if (v := getattr(sub_patch.font, f)) is not None
+            }
+            if font_updates:
+                sub_updates["font"] = dataclasses.replace(sub_base.font, **font_updates)
+        if sub_updates:
+            updates[sub_name] = dataclasses.replace(sub_base, **sub_updates)
+    return dataclasses.replace(base, **updates) if updates else base
+
+
+def build_resolved_style(
+    board_resolved: MergedStyle | None,
+    chart_style: Any,
+    chart_type: str | None = None,
+) -> MergedChartsStyle:
+    """Build the fully-merged MergedChartsStyle for a single chart.
+
+    Fast path: chart has no local style overrides and no per-family theme patches
+    for chart_type → return board.charts unchanged.
+
+    Merge path: apply chart_style on top of board.charts. Every chart-local
+    override (axis_x/axis_y/axis/axis_quantitative/axis_band, legend, scale,
+    palette, range, inference, table, data_table, background, title, x_temporal_mode,
+    bar/line/area/scatter/arc/kpi/spark/spark_bar) is applied here so the renderer
+    reads a single, fully-resolved value without ever touching the Patch.
+
+    chart_type: the chart family name ("bar", "line", etc.) used to apply per-family
+    theme patches (e.g. editorial bar.legend.disable: false). When given, per-family
+    theme legend patches override the global resolved legend before face-local patches.
+    """
+    base_resolved = board_resolved or resolve_style(get_config().style)
+    base_charts = base_resolved.charts
+
+    # Coerce dict / unknown shape (MockChart in tests) to a typed patch.
+    if (
+        isinstance(chart_style, dict)
+        or chart_style is not None
+        and not isinstance(chart_style, ChartStylePatch)
+    ):
+        # LayeredChartStyle passed directly: wrap it in the monolithic container.
+        if isinstance(chart_style, LayeredChartStyle):
+            chart_style = ChartStylePatch(layered=chart_style)
+        else:
+            # Auto-wrap table-specific style fields in the table sub-patch if needed
+            if isinstance(chart_style, dict):
+                table_fields = {
+                    "columns",
+                    "pagination",
+                    "column_defaults",
+                    "row",
+                    "header",
+                    "row_numbers",
+                    "wrap",
+                    "background",
+                    "color",
+                    "rule",
+                    "outer_padding",
+                    "bottom_padding",
+                    "title",
+                    "border",
+                    "header_overflow",
+                    "column_layout",
+                }
+                has_table_fields = any(k in chart_style for k in table_fields)
+                if has_table_fields and "table" not in chart_style:
+                    # Wrap table fields in table={...}
+                    table_style = {}
+                    other_style = {}
+                    for k, v in chart_style.items():
+                        if k in table_fields:
+                            table_style[k] = v
+                        else:
+                            other_style[k] = v
+                    if table_style:
+                        other_style["table"] = table_style
+                    chart_style = other_style
+            chart_style = ChartStylePatch.model_validate(chart_style)
+
+    # Resolve palette tokens (e.g. "dft-creams.cream-50" → "#918878") across
+    # all color-bearing fields of the chart-local style patch — before any field
+    # is stored as a sentinel or merged into the resolved tree.  Raises
+    # UnknownColorError on unknown tokens, matching validate-and-error-fast.
+    if chart_style is not None:
+        chart_style = _resolve_color_tokens(chart_style)
+
+    if not _chart_style_has_overrides(chart_style) and not _has_family_legend_patch(
+        base_charts, chart_type
+    ):
+        return base_charts
+    assert chart_style is not None or chart_type is not None
+
+    overrides: dict[str, Any] = {}
+
+    # Primary family sub-patch: the single non-null family for non-layered charts,
+    # or the first non-null for layered charts.  Shared global fields (palette,
+    # background, inference, axis overrides, …) are read from this patch.
+    primary = _get_primary_patch(chart_style)
+
+    # --- Palette / range ---
+    # Named palette (e.g. ``style.palette: dft-seq-rust``) resolves through
+    # the palette resolver into the stops list that MergedChartsStyle.palette
+    # holds. Explicit ``style.range.category`` (a list of CSS color strings)
+    # wins over the named form when both are authored.
+    _palette = getattr(primary, "palette", None)
+    if _palette is not None:
+        from dataface.core.compile.palette import palette as resolve_palette
+
+        # Patch models accept both string names and resolved lists; compiled
+        # models always materialise as list[str] via the field_validator.
+        overrides["palette"] = (
+            resolve_palette(_palette) if isinstance(_palette, str) else _palette
+        )
+    _range = getattr(primary, "range", None)
+    if _range is not None and _range.category is not None:
+        overrides["palette"] = _range.category
+
+    # --- Inference ---
+    _inference = getattr(primary, "inference", None)
+    if _inference is not None:
+        board_inf = base_charts.inference
+        merged_inf = {
+            f: (
+                pv
+                if (pv := getattr(_inference, f)) is not None
+                else getattr(board_inf, f)
+            )
+            for f in InferenceStyle.model_fields
+        }
+        overrides["inference"] = InferenceStyle(**merged_inf)
+
+    # --- data_table (cartesian families only via _CartesianChartStyle) ---
+    _data_table = getattr(primary, "data_table", None)
+    if _data_table is not None:
+        overrides["data_table"] = deep_merge(base_charts.data_table, _data_table)
+
+    # --- Per-chart-type overlays ---
+    # deep_merge handles every family-specific field including orientation, stack,
+    # color_scheme (geoshape), column_layout/columns/column_defaults (table), etc.
+    for ct in _ALL_FAMILY_KEYS:
+        patch = getattr(chart_style, ct, None)
+        if patch is not None:
+            overrides[ct] = deep_merge(getattr(base_charts, ct), patch)
+
+    # --- Layered mark distribution ---
+    # LayeredChartStyle.marks distributes per-mark-type overrides to the bar/line/area
+    # family slots that the renderer reads (eff.bar.marks.bar, eff.line.marks.line, etc.).
+    _layered = getattr(chart_style, "layered", None)
+    if _layered is not None and _layered.marks is not None:
+        _lm = _layered.marks
+        if _lm.bar is not None:
+            overrides["bar"] = deep_merge(
+                overrides.get("bar", base_charts.bar),
+                BarChartStylePatch.model_validate(
+                    {"marks": {"bar": _lm.bar.model_dump(exclude_none=True)}}
+                ),
+            )
+        if _lm.line is not None or _lm.point is not None:
+            _line_marks: dict[str, Any] = {}
+            if _lm.line is not None:
+                _line_marks["line"] = _lm.line.model_dump(exclude_none=True)
+            if _lm.point is not None:
+                _line_marks["point"] = _lm.point.model_dump(exclude_none=True)
+            overrides["line"] = deep_merge(
+                overrides.get("line", base_charts.line),
+                LineChartStylePatch.model_validate({"marks": _line_marks}),
+            )
+        if _lm.area is not None or _lm.point is not None:
+            # Point marks are distributed to both line and area families because
+            # area+line combos can render overlaid point marks via either family slot.
+            _area_marks: dict[str, Any] = {}
+            if _lm.area is not None:
+                _area_marks["area"] = _lm.area.model_dump(exclude_none=True)
+            if _lm.point is not None:
+                _area_marks["point"] = _lm.point.model_dump(exclude_none=True)
+            overrides["area"] = deep_merge(
+                overrides.get("area", base_charts.area),
+                AreaChartStylePatch.model_validate({"marks": _area_marks}),
+            )
+
+    # --- Callout tone override ---
+    # MergedCalloutChartStyle is a frozen dataclass (not a BaseModel), so it
+    # cannot use the deep_merge loop above.  Only tone is chart-locally authored.
+    _callout_patch = getattr(chart_style, "callout", None)
+    if _callout_patch is not None and _callout_patch.tone is not None:
+        overrides["callout"] = dataclasses.replace(
+            base_charts.callout, tone=_callout_patch.tone
+        )
+
+    # --- Top-level Vega-facing ---
+    _background = getattr(primary, "background", None)
+    if _background is not None:
+        overrides["background"] = _background
+    _color = getattr(primary, "color", None)
+    if isinstance(_color, str):
+        # Only string (static paint) flows to MergedChartsStyle.color.
+        # StyleColorConfig (gradient scale) is consumed by normalize_chart_channels
+        # and never stored in the style cascade.
+        overrides["color"] = _color
+    _title = getattr(primary, "title", None)
+    if _title is not None:
+        overrides["title"] = deep_merge(base_charts.title, _title)
+
+    # --- Chart-local axis overrides ---
+    # Stored as typed AxisStylePatch sentinels on resolved_chart_style
+    # so the renderer's resolved_axis_style helper can apply Layers 4/5/6 in
+    # the canonical cascade order (after Layer 3 axis_quantitative and Layer
+    # 3.5 chart-type axis). Baking them into base.axis_x/y here would invert
+    # the precedence relative to axis_quantitative — the renderer must keep
+    # control of the layering.
+    _axis = getattr(primary, "axis", None)
+    if _axis is not None:
+        overrides["axis_overrides_global"] = _axis
+    _axis_x = getattr(primary, "axis_x", None)
+    if _axis_x is not None:
+        overrides["axis_overrides_x"] = _axis_x
+    _axis_y = getattr(primary, "axis_y", None)
+    if _axis_y is not None:
+        overrides["axis_overrides_y"] = _axis_y
+    _axis_quantitative = getattr(primary, "axis_quantitative", None)
+    if _axis_quantitative is not None:
+        overrides["axis_overrides_quantitative"] = _axis_quantitative
+    _axis_band = getattr(primary, "axis_band", None)
+    if _axis_band is not None:
+        overrides["axis_overrides_band"] = _axis_band
+
+    # --- Legend ---
+    # Apply per-family theme patch first (e.g. editorial bar.legend.disable: false),
+    # then face-local patch on top. Merge order: global → family theme → face-local.
+    _effective_legend = base_charts.legend
+    if chart_type is not None:
+        family_style = getattr(base_charts, chart_type, None)
+        family_legend_patch = (
+            getattr(family_style, "legend", None) if family_style is not None else None
+        )
+        if family_legend_patch is not None:
+            _effective_legend = _merge_legend(base_charts.legend, family_legend_patch)
+    _legend = getattr(primary, "legend", None) if primary is not None else None
+    if _legend is not None:
+        _effective_legend = _merge_legend(_effective_legend, _legend)
+    if _effective_legend is not base_charts.legend:
+        overrides["legend"] = _effective_legend
+
+    # --- Scale (chart-level global; per-axis already lands on axis_*.scale above) ---
+    _scale = getattr(primary, "scale", None)
+    if _scale is not None:
+        overrides["scale"] = _scale
+
+    # --- Pagination (table charts expose this via TableChartStyle.pagination) ---
+    # Chart-local pagination layers on top of the face default. ``enabled``
+    # is required on the authored Patch so it always sets; ``page_size`` is
+    # optional — when unset the cascade falls back to the face-level
+    # page_size so the renderer reads a single resolved value off
+    # ``effective.pagination`` without re-running the merge.
+    _pagination = getattr(primary, "pagination", None)
+    if _pagination is not None:
+        face = base_charts.pagination
+        merged_pagination = _pagination
+        if (
+            merged_pagination.page_size is None
+            and face is not None
+            and face.page_size is not None
+        ):
+            merged_pagination = merged_pagination.model_copy(
+                update={"page_size": face.page_size}
+            )
+        overrides["pagination"] = merged_pagination
+
+    if not overrides:
+        return base_charts
+
+    return dataclasses.replace(base_charts, **overrides)
+
+
+# ── Axis-cascade emit helper ──────────────────────────────────────────
+
+
+def _chart_type_axis_patch(
+    effective: MergedChartsStyle,
+    chart_type: str,
+    axis_name: Literal["axis_x", "axis_y"],
+) -> AxisStylePatch | None:
+    """Return the chart-type-specific axis patch (Layer 3.5 of the cascade).
+
+    Pie charts have no cartesian axes, so this always returns None for them.
+    """
+    chart_type_style = getattr(effective, chart_type, None)
+    return (
+        getattr(chart_type_style, axis_name, None)
+        if chart_type_style is not None
+        else None
+    )
+
+
+def resolved_axis_style(
+    effective: MergedChartsStyle,
+    axis_name: Literal["axis_x", "axis_y"],
+    channel_type: str,
+    chart_type_axis_patch: AxisStylePatch | None = None,
+) -> AxisStyle:
+    """Walk the 7-layer axis cascade and return a merged AxisStyle.
+
+    Single source of truth for axis state at emit time. The renderer reads
+    every axis field (ticks, grid, domain, orient, offset, ...) from this
+    return value — never from ``effective.axis_x`` / ``axis_y`` directly,
+    since those reflect only Layers 1+2 and silently miss type-conditional,
+    chart-type, and chart-local overrides.
+
+    Layer order (each overrides the previous):
+      1+2. theme global + channel-specific  (effective.axis_{x,y})
+      3.   theme type-conditional           (effective.axis_quantitative / band)
+      3.5. theme chart-type-specific        (chart_type_axis_patch)
+      4.   chart-local global               (effective.axis_overrides_global)
+      5.   chart-local type-conditional     (effective.axis_overrides_quantitative / _band)
+      6.   chart-local channel-specific     (effective.axis_overrides_{x,y}) — wins
+
+    Chart-local layers come from typed Patch sentinels stored on
+    ``effective`` by ``build_resolved_style`` — the chart's ChartStylePatch
+    is consumed by the cascade and never reaches the renderer.
+    """
+    base = AxisStyle.model_validate(dataclasses.asdict(getattr(effective, axis_name)))
+
+    if channel_type == "quantitative":
+        base = deep_merge(  # type: ignore[assignment]
+            base,
+            AxisStyle.model_validate(dataclasses.asdict(effective.axis_quantitative)),
+        )
+    # axis_band has no theme-resolved representation; only chart-local applies.
+
+    base = deep_merge(base, chart_type_axis_patch)  # type: ignore[assignment]
+
+    base = deep_merge(base, effective.axis_overrides_global)  # type: ignore[assignment]
+    if channel_type == "quantitative":
+        base = deep_merge(  # type: ignore[assignment]
+            base, effective.axis_overrides_quantitative
+        )
+    elif channel_type in ("ordinal", "nominal"):
+        base = deep_merge(base, effective.axis_overrides_band)  # type: ignore[assignment]
+    base = deep_merge(  # type: ignore[assignment]
+        base, getattr(effective, f"axis_overrides_{axis_name[-1]}")
+    )
+
+    return base