dataface 0.1.2__py3-none-any.whl

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

@@ -0,0 +1,481 @@
+"""Style authored models — all-Optional *Patch overlays for YAML authoring.
+
+Patch classes are either:
+  - hand-written (class XxxPatch(BaseModel): ...)
+  - generated mechanically (XxxPatch = build_patch_model(XxxStyle))
+
+Generated patches depend on their compiled counterparts imported from .compiled.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+from dataface.core.compile.models.factories import (
+    build_patch_model,
+    build_patch_model_ext,
+)
+
+# Fields with cartesian/aspect-ratio sizing semantics — excluded from chart types
+# that use a fixed sizing contract (kpi, table) to prevent silent no-ops.
+_CHART_STYLE_SIZING: frozenset[str] = frozenset(
+    {"aspect_ratio", "min_height", "max_height"}
+)
+from dataface.core.compile.models.primitives import (
+    StyleColorConfig as StyleColorConfig,
+)
+from dataface.core.compile.models.style.compiled import (
+    AreaChartStyle,
+    AreaMarkStyle,
+    AxisDomainStyle,
+    AxisElementStyle,
+    AxisGridStyle,
+    AxisStylePatch as AxisStylePatch,
+    AxisTicksStyle,
+    BarChartStyle,
+    BarMarkStyle,
+    CalloutChartStyle,
+    DataTableStylePatch as DataTableStylePatch,
+    EndpointLabelsConfig,
+    GeoshapeChartStyle,
+    GlobalMarksStyle,
+    HeatmapChartStyle,
+    InferenceStyle,
+    KpiChartStyle,
+    LegendStyle,
+    LineChartStyle,
+    LineMarkStyle,
+    PaddingStyle,
+    PieChartStyle,
+    PointMapChartStyle,
+    PointMarkStyle,
+    RangeStylePatch as RangeStylePatch,
+    ScaleStyle,
+    ScatterChartStyle,
+    SparkBarBarStyle,
+    SparkBarChartLabelStyle,
+    SparkBarChartStyle,
+    SparkBarCountStyle,
+    SparkStyle,
+    Style,
+    TableChartStylePatch,
+    TableColumnDefaultsConfig as TableColumnDefaultsConfig,
+    TitleStyle,
+    TooltipStyle,
+    TotalStyle,
+    _CartesianChartStyle,
+    _coerce_gap,
+)
+
+if TYPE_CHECKING:
+
+    class TitleStylePatch(TitleStyle):
+        pass
+
+else:
+    TitleStylePatch = build_patch_model(TitleStyle)
+
+# ScaleStyle is already all-Optional — auto-generated patch is identical and
+# ensures AxisStylePatch.scale and tests share the same class identity.
+# TYPE_CHECKING stub mirrors the DataTable/Table/AxisStylePatch pattern:
+# mypy sees a proper class; runtime uses the dynamically-created patch model.
+if TYPE_CHECKING:
+
+    class ScaleStylePatch(ScaleStyle):
+        pass
+
+else:
+    ScaleStylePatch = build_patch_model(ScaleStyle)
+
+
+_StylePatchBase = build_patch_model(Style)
+
+
+class StylePatch(_StylePatchBase):  # type: ignore[misc,valid-type]
+    """Authored overlay for Style — all fields optional. Adds CSS shorthand coercers."""
+
+    @field_validator("gap", mode="before")
+    @classmethod
+    def _coerce_gap_value(cls, v: Any) -> Any:
+        return _coerce_gap(v)
+
+
+AxisGridStylePatch = build_patch_model(AxisGridStyle)
+AxisDomainStylePatch = build_patch_model(AxisDomainStyle)
+AxisTicksStylePatch = build_patch_model(AxisTicksStyle)
+AxisElementStylePatch = build_patch_model(AxisElementStyle)
+if TYPE_CHECKING:
+
+    class PointMarkStylePatch(PointMarkStyle):
+        pass
+
+else:
+    PointMarkStylePatch = build_patch_model(PointMarkStyle)
+
+# Per-family chart style patches used as Pydantic field annotations in authored
+# *Chart classes. The TYPE_CHECKING stub gives mypy a proper class identity while
+# the runtime uses the dynamically-created patch model from build_patch_model().
+# Pattern mirrors ScaleStylePatch / LegendStylePatch / TableChartStylePatch.
+if TYPE_CHECKING:
+
+    class BarChartStylePatch(BarChartStyle):  # noqa: F811
+        pass
+
+    class LineChartStylePatch(LineChartStyle):  # noqa: F811
+        pass
+
+    class AreaChartStylePatch(AreaChartStyle):  # noqa: F811
+        pass
+
+    class ScatterChartStylePatch(ScatterChartStyle):  # noqa: F811
+        pass
+
+    class HeatmapChartStylePatch(HeatmapChartStyle):  # noqa: F811
+        pass
+
+    class GeoshapeChartStylePatch(GeoshapeChartStyle):  # noqa: F811
+        pass
+
+    class PointMapChartStylePatch(PointMapChartStyle):  # noqa: F811
+        pass
+
+    class PieChartStylePatch(PieChartStyle):  # noqa: F811
+        pass
+
+else:
+    BarChartStylePatch = build_patch_model(BarChartStyle)
+    LineChartStylePatch = build_patch_model(LineChartStyle)
+    AreaChartStylePatch = build_patch_model(AreaChartStyle)
+    ScatterChartStylePatch = build_patch_model(ScatterChartStyle)
+    HeatmapChartStylePatch = build_patch_model(HeatmapChartStyle)
+    GeoshapeChartStylePatch = build_patch_model(GeoshapeChartStyle)
+    PointMapChartStylePatch = build_patch_model(PointMapChartStyle)
+    PieChartStylePatch = build_patch_model(PieChartStyle)
+TotalStylePatch = build_patch_model(TotalStyle)
+GlobalMarksStylePatch = build_patch_model(GlobalMarksStyle)
+SparkBarBarStylePatch = build_patch_model(SparkBarBarStyle)
+SparkBarChartLabelStylePatch = build_patch_model(SparkBarChartLabelStyle)
+SparkBarCountStylePatch = build_patch_model(SparkBarCountStyle)
+
+if TYPE_CHECKING:
+
+    class KpiChartStylePatch(KpiChartStyle):  # noqa: F811
+        pass
+
+    class SparkBarChartStylePatch(SparkBarChartStyle):  # noqa: F811
+        pass
+
+else:
+    KpiChartStylePatch = build_patch_model_ext(
+        KpiChartStyle, exclude=_CHART_STYLE_SIZING
+    )
+    SparkBarChartStylePatch = build_patch_model(SparkBarChartStyle)
+SparkStylePatch = build_patch_model(SparkStyle)
+if TYPE_CHECKING:
+
+    class CalloutChartStylePatch(CalloutChartStyle):  # noqa: F811
+        pass
+
+else:
+    CalloutChartStylePatch = build_patch_model(CalloutChartStyle)
+# AxisStylePatch is generated earlier (after AxisStyle) so chart-type
+# styles can reference it as a sentinel field.
+if TYPE_CHECKING:
+
+    class InferenceStylePatch(InferenceStyle):
+        pass
+
+else:
+    InferenceStylePatch = build_patch_model(InferenceStyle)
+
+# TYPE_CHECKING stub mirrors the AxisStylePatch pattern — gives mypy a proper
+# class (with accurate field names from LegendStyle) while the runtime uses
+# the dynamically created patch model from build_patch_model().
+if TYPE_CHECKING:
+
+    class LegendStylePatch(LegendStyle):
+        pass
+
+else:
+    LegendStylePatch = build_patch_model(LegendStyle)
+
+# Individual mark-type patches used in LayeredMarksStyle and LayeredChartStyle.
+if TYPE_CHECKING:
+
+    class BarMarkStylePatch(BarMarkStyle):
+        pass
+
+    class LineMarkStylePatch(LineMarkStyle):
+        pass
+
+    class AreaMarkStylePatch(AreaMarkStyle):
+        pass
+
+    class TooltipStylePatch(TooltipStyle):
+        pass
+
+    class EndpointLabelsConfigPatch(EndpointLabelsConfig):
+        pass
+
+    class PaddingStylePatch(PaddingStyle):
+        pass
+
+else:
+    BarMarkStylePatch = build_patch_model(BarMarkStyle)
+    LineMarkStylePatch = build_patch_model(LineMarkStyle)
+    AreaMarkStylePatch = build_patch_model(AreaMarkStyle)
+    TooltipStylePatch = build_patch_model(TooltipStyle)
+    EndpointLabelsConfigPatch = build_patch_model(EndpointLabelsConfig)
+    PaddingStylePatch = build_patch_model(PaddingStyle)
+
+
+# =============================================================================
+# LAYEREDCHARTSTYLE — flat authored overlay for layered multi-mark charts
+# =============================================================================
+
+
+class LayeredMarksStyle(BaseModel):
+    """Per-mark-type style overrides for layered charts.
+
+    Keys match the VL mark types emitted by layered layers. All fields default
+    to None (inherit global marks defaults). ``point`` controls the dot marker
+    on line and area layers; ``bar``, ``line``, ``area`` control their
+    respective marks directly.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    bar: BarMarkStylePatch | None = Field(
+        default=None, description="Bar mark overrides for bar layers."
+    )
+    line: LineMarkStylePatch | None = Field(
+        default=None, description="Line mark overrides for line layers."
+    )
+    area: AreaMarkStylePatch | None = Field(
+        default=None, description="Area mark overrides for area layers."
+    )
+    point: PointMarkStylePatch | None = Field(
+        default=None,
+        description="Point/dot mark overrides shared across line and area layers.",
+    )
+
+
+class LayeredChartStyle(_CartesianChartStyle):
+    """Flat style patch for layered multi-mark charts.
+
+    Inherits all cartesian chart-level and shared axis/legend fields from
+    ``_CartesianChartStyle`` (which itself inherits ``_ChartStyleBaseAllOptional``).
+    Only adds layered-specific behavior fields and per-mark-type overrides.
+
+    Some nested compiled types from ``_ChartStyleBaseAllOptional`` are overridden
+    with their ``*Patch`` equivalents so that partial dicts (e.g.
+    ``legend: {disable: true}``) are accepted without requiring all required fields
+    of the compiled model.
+
+    ``ChartStylePatch.layered`` holds this type; the cascade reads shared fields
+    from it directly and distributes ``marks.*`` overrides to the bar/line/area
+    family slots in ``MergedChartsStyle``.
+    """
+
+    # Override compiled → patch types for nested models that have required fields.
+    # _CartesianChartStyle inherits these as their compiled (non-optional) variants;
+    # we narrow them back to their patch equivalents so partial dicts validate cleanly.
+    legend: LegendStylePatch | None = Field(  # type: ignore[assignment]
+        default=None, description="Chart legend style overrides."
+    )
+    tooltip: TooltipStylePatch | None = Field(  # type: ignore[assignment]
+        default=None, description="Chart tooltip style overrides."
+    )
+    padding: PaddingStylePatch | None = Field(  # type: ignore[assignment]
+        default=None, description="Chart inner padding overrides."
+    )
+    title: TitleStylePatch | None = Field(
+        default=None,
+        description="Chart-level title style override; None inherits the theme title style.",
+    )
+    inference: InferenceStylePatch | None = Field(  # type: ignore[assignment]
+        default=None, description="Engine inference behavior flags."
+    )
+
+    # Family behavior fields (bar/area share orientation/stack; all share endpoint labels).
+    orientation: Literal["horizontal", "vertical", "auto"] | None = Field(
+        default=None,
+        description="Preferred bar orientation; None uses the renderer default (vertical).",
+    )
+    stack: bool | Literal["zero", "normalize", "center"] | None = Field(
+        default=None,
+        description="Default stack mode for bar/area charts.",
+    )
+    stack_order: Literal["value", "data", "alphabetical"] | None = Field(
+        default=None,
+        description="Z-order of stacked segments.",
+    )
+    endpoint_labels: EndpointLabelsConfigPatch | None = Field(
+        default=None,
+        description="Endpoint label pane configuration.",
+    )
+
+    # Mark overrides — keyed by mark type rather than by chart family.
+    marks: LayeredMarksStyle | None = Field(
+        default=None,
+        description="Per-mark-type style overrides (bar/line/area/point).",
+    )
+
+
+# =============================================================================
+# CHARTSTYLEPATCH — chart-local authored overlay
+# =============================================================================
+
+
+class ChartStylePatch(BaseModel):
+    """Chart-local style patch — chart-level sizing fields plus per-family sub-patches.
+
+    Each family key (bar, line, area, …) holds the fully-typed patch for that
+    chart family. The render layer reads only the family that matches the chart
+    type; other families are ignored.
+
+    For layered charts that mix multiple mark families, multiple keys may be set.
+
+    ``aspect_ratio``, ``min_height``, and ``max_height`` live here (not in a
+    family sub-patch) so layered charts can author them at the top of their
+    ``style:`` block.  For single-family charts the equivalent fields are on the
+    per-family patch (e.g. ``BarChartStylePatch``); the normalizer promotes them
+    to ``Chart.aspect_ratio`` etc. before the compiled ``ChartStylePatch`` is
+    built, so these fields are always ``None`` in the final compiled model.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    # Chart-level sizing — valid on all chart types that support aspect-ratio
+    # sizing (i.e. not kpi / table / callout / spark_bar which use fixed sizing).
+    # Normalizer promotes these to Chart.aspect_ratio / min_height / max_height.
+    aspect_ratio: float | None = Field(
+        default=None,
+        description="Chart aspect ratio (width/height). Overrides the theme default for this chart.",
+    )
+    min_height: float | None = Field(
+        default=None,
+        description="Minimum chart height in pixels.",
+    )
+    max_height: float | None = Field(
+        default=None,
+        description="Maximum chart height in pixels.",
+    )
+
+    # Per-chart-type authored overlay patches.
+    bar: BarChartStylePatch | None = Field(
+        default=None, description="Bar chart-specific style overrides."
+    )
+    line: LineChartStylePatch | None = Field(
+        default=None, description="Line chart-specific style overrides."
+    )
+    area: AreaChartStylePatch | None = Field(
+        default=None, description="Area chart-specific style overrides."
+    )
+    scatter: ScatterChartStylePatch | None = Field(
+        default=None, description="Scatter chart-specific style overrides."
+    )
+    pie: PieChartStylePatch | None = Field(
+        default=None,
+        description="Pie/donut chart style overrides.",
+    )
+    kpi: KpiChartStylePatch | None = Field(
+        default=None, description="KPI chart-specific style overrides."
+    )
+    spark_bar: SparkBarChartStylePatch | None = Field(
+        default=None, description="Spark bar chart-specific style overrides."
+    )
+    spark: SparkStylePatch | None = Field(default=None, description="Spark line/area chart-specific style overrides.")  # type: ignore[valid-type]
+    heatmap: HeatmapChartStylePatch | None = Field(
+        default=None, description="Heatmap chart-specific style overrides."
+    )
+    geoshape: GeoshapeChartStylePatch | None = Field(
+        default=None, description="Geoshape/map chart-specific style overrides."
+    )
+    point_map: PointMapChartStylePatch | None = Field(
+        default=None, description="Point map chart-specific style overrides."
+    )
+    table: TableChartStylePatch | None = Field(
+        default=None, description="Table chart-specific style overrides."
+    )
+    callout: CalloutChartStylePatch | None = Field(
+        default=None, description="Callout chart-specific style overrides (tone)."
+    )
+    layered: LayeredChartStyle | None = Field(
+        default=None, description="Layered chart-specific style overrides."
+    )
+
+    @classmethod
+    def coerce_chart_style(cls, raw_style: Any) -> ChartStylePatch:
+        if isinstance(raw_style, cls):
+            return raw_style
+        if isinstance(raw_style, dict):
+            return cls.model_validate(raw_style)
+        return cls()
+
+    @model_validator(mode="before")
+    @classmethod
+    def _reject_stale_pie_keys(cls, data: Any) -> Any:
+        """Catch authors using removed flat pie keys, old arc key, or chart-root geometry in style."""
+        if not isinstance(data, dict):
+            return data
+        # height and width belong at chart root, not in style:.
+        for geo_key in ("height", "width"):
+            if geo_key in data:
+                raise ValueError(
+                    f"style.{geo_key} is not valid on a chart's style block. "
+                    f"Chart sizing fields live at the chart root, not in style:.\n\n"
+                    f"  charts:\n"
+                    f"    my_chart:\n"
+                    f"      type: bar\n"
+                    f"      {geo_key}: ...   # ← move here\n"
+                    f"      style:\n"
+                    f"        # paint only"
+                )
+        # For layered charts, sizing fields must be at the top of style:, not
+        # nested inside a family sub-patch (e.g. style.bar.aspect_ratio).
+        # The normalizer only promotes top-level style sizing; nested forms are
+        # silently ignored, so reject them here.
+        _SIZING_KEYS = {"aspect_ratio", "min_height", "max_height"}
+        _FAMILY_KEYS = {
+            "bar",
+            "line",
+            "area",
+            "scatter",
+            "heatmap",
+            "geoshape",
+            "point_map",
+            "pie",
+            "spark_bar",
+            "spark",
+        }
+        for family in _FAMILY_KEYS:
+            family_patch = data.get(family)
+            if isinstance(family_patch, dict):
+                for sizing_key in _SIZING_KEYS:
+                    if sizing_key in family_patch:
+                        raise ValueError(
+                            f"style.{family}.{sizing_key} is not valid. "
+                            f"Sizing fields must be at the top of the style: block, "
+                            f"not nested inside a family sub-patch:\n\n"
+                            f"  style:\n"
+                            f"    {sizing_key}: ...   # ← move here\n"
+                            f"    {family}:\n"
+                            f"      # mark paint only"
+                        )
+        stale: dict[str, str] = {
+            "arc": "style.pie.marks.slice",
+            "slice": "style.pie.marks.slice",
+            "inner_radius": "style.pie.inner_radius",
+            "total": "style.pie.total",
+        }
+        for key, new_path in stale.items():
+            if key in data:
+                raise ValueError(
+                    f"style.{key} has been removed. "
+                    f"Pie style is now under style.pie.*. "
+                    f"Move it to {new_path}."
+                )
+        return data