dataface 0.1.2__py3-none-any.whl

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

@@ -0,0 +1,398 @@
+"""Compiled chart types: Chart, ChartDependencies, is_chart.
+
+Stage: COMPILE (Output)
+Purpose: Define the compiled Chart type (output of compilation, input to execute/render)
+and its dependency tracker.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, TypeGuard
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from dataface.core.compile.custom_chart_types import BUILTIN_CHART_TYPE_VALUES
+from dataface.core.compile.models.chart.authored import (
+    ChartDataTable,
+    ChartLabels,
+    ChartSort,
+    ChartTotal,
+    FieldConditionalFormatting,
+    FilterDef,
+    KpiSupportConfig,
+    Layer,
+)
+from dataface.core.compile.models.primitives import FormatConfig
+from dataface.core.compile.models.query.compiled import AnyQuery
+from dataface.core.compile.models.style.authored import ChartStylePatch
+from dataface.core.compile.models.vega_lite.contracts import Projection
+
+# ============================================================================
+# CHART TYPE SETS
+# ============================================================================
+
+# SVG-family chart types that use hand-crafted SVG renderers instead of Vega-Lite.
+# Used for renderer-family classification and to exclude these types from:
+#   - aspect-ratio-driven sizing (they don't use width/aspect_ratio for height)
+#   - Vega render-first sizing (not Vega charts)
+#   - cols height alignment re-renders (non-Vega, don't benefit from re-render)
+# Each renderer owns its own sizing contract — there is no shared fixed height for this group.
+NON_ASPECT_RATIO_TYPES = frozenset({"table", "kpi", "spark_bar", "callout"})
+SVG_LAYOUT_PADDED_TYPES = frozenset({"table", "kpi", "spark_bar"})
+
+# ============================================================================
+# DEPENDENCY TRACKING
+# ============================================================================
+
+
+@dataclass(frozen=True)
+class ChartDependencies:
+    """Dependencies required by a chart for rendering.
+
+    Tracks all sources, variables, and queries that a chart needs.
+    Used for extracting minimal preview faces.
+    """
+
+    sources: frozenset[str] = field(default_factory=frozenset)
+    variables: frozenset[str] = field(default_factory=frozenset)
+    queries: frozenset[str] = field(default_factory=frozenset)
+
+
+# ============================================================================
+# COMPILED CHART
+# ============================================================================
+
+
+class Chart(BaseModel):
+    """Compiled chart ready for execution and rendering.
+
+    All data-mapping, geo, interaction, and compiled-specific fields
+    declared directly on this model (no shared base with authored patches).
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    # --- Identity ---
+    id: str = Field(description="Unique identifier within the dashboard.")
+    query: AnyQuery | None = Field(
+        default=None,
+        description="Resolved query object (SqlQuery, CsvQuery, etc.). None for blank/placeholder charts.",
+    )
+    query_name: str | None = Field(
+        default=None,
+        description="String name for executor lookup. None for blank/placeholder charts.",
+    )
+    type: str = Field(description="Chart type (line, bar, table, kpi, etc.).")
+
+    @field_validator("type", mode="before")
+    @classmethod
+    def _validate_chart_type(cls, v: object) -> str:
+        from dataface.core.compile.custom_chart_types import (
+            _NAME_RE as _CHART_CUSTOM_NAME_RE,
+        )
+
+        if not isinstance(v, str):
+            raise ValueError(f"chart type must be a string, got {type(v).__name__}")
+        if v in BUILTIN_CHART_TYPE_VALUES:
+            return v
+        if _CHART_CUSTOM_NAME_RE.match(v):  # custom chart type name
+            return v
+        raise ValueError(
+            f"Unknown chart type {v!r}. Must be a known chart type or a valid "
+            f"custom type name (lowercase letters, digits, and underscores)."
+        )
+
+    title: str = Field(
+        default="", description="Display title. Empty string if not provided."
+    )
+    subtitle: str = Field(
+        default="", description="Secondary title line. Empty string if not provided."
+    )
+    description: str = Field(
+        default="", description="Description text. Empty string if not provided."
+    )
+    label: str = Field(
+        default="",
+        description="KPI label rendered above the headline value. Empty for non-KPI.",
+    )
+
+    # Styling — typed chart-local style patch
+    style: ChartStylePatch | None = Field(
+        default=None,
+        description="Chart-local style patch (orientation, columns, spark-bar overrides, etc.).",
+    )
+
+    # Variable dependencies - computed during normalization
+    variable_dependencies: set[str] = Field(
+        default_factory=set,
+        description="Variable names this chart depends on (from title, filters, query SQL).",
+    )
+
+    # Source location in YAML for edit-back support
+    source_path: str | None = Field(
+        default=None,
+        description="YAML path for edit-back support (e.g., 'charts.revenue', 'rows[0]').",
+    )
+
+    # Whether the query is inline (defined in chart) vs named (reference)
+    query_is_inline: bool = Field(
+        default=False,
+        description="True if query is defined inline in chart; False if it's a named reference.",
+    )
+
+    # --- Data mapping fields ---
+    x: str | None = Field(
+        default=None, description="X-axis field name from the query result."
+    )
+    y: str | list[str] | None = Field(
+        default=None,
+        description="Y-axis field name(s). Accepts a single field or list for multi-series charts.",
+    )
+    color: str | None = Field(
+        default=None, description="Color data channel: bare field name only."
+    )
+    size: str | None = Field(
+        default=None,
+        description="Field used to size-encode data points (quantitative).",
+    )
+    shape: str | None = Field(
+        default=None,
+        description="Field used to shape-encode data points (categorical).",
+    )
+    theta: str | None = Field(
+        default=None, description="Field for angular encoding in pie (arc) charts."
+    )
+    total: ChartTotal | None = Field(
+        default=None, description="Donut center total config."
+    )
+    labels: ChartLabels | None = Field(
+        default=None, description="Per-row text annotations near each data anchor."
+    )
+    x_label: str | None = Field(
+        default=None, description="Custom label for the X axis."
+    )
+    y_label: str | None = Field(
+        default=None, description="Custom label for the Y axis."
+    )
+    format: str | FormatConfig | None = Field(
+        default=None,
+        description="Number format: D3 format string, preset name, or FormatConfig object.",
+    )
+    message: str | None = Field(
+        default=None,
+        description="Static error message content for explicit error charts.",
+    )
+    geo: str | dict[str, Any] | None = Field(
+        default=None,
+        description="GeoJSON field name or inline GeoJSON spec for geoshape charts.",
+    )
+    geo_source: str | None = Field(
+        default=None,
+        description="Named geographic data source for loading GeoJSON boundaries.",
+    )
+    lookup: str | None = Field(
+        default=None,
+        description="Data field to join against the geographic data (map join key).",
+    )
+    value: str | None = Field(
+        default=None,
+        description="For map: data field mapped to the fill color. For KPI: column reference for the headline number/text.",
+    )
+    support: KpiSupportConfig | None = Field(
+        default=None, description="Optional support line beneath the KPI value."
+    )
+    projection: str | Projection | None = Field(
+        default=None, description="Map projection name or Vega-Lite projection config."
+    )
+    latitude: str | None = Field(
+        default=None,
+        description="Field containing latitude values for point/bubble maps.",
+    )
+    longitude: str | None = Field(
+        default=None,
+        description="Field containing longitude values for point/bubble maps.",
+    )
+    basemap: dict[str, Any] | None = Field(
+        default=None,
+        description="Tile-layer configuration for point_map / bubble_map charts.",
+    )
+    sort: ChartSort | None = Field(
+        default=None,
+        description="Sort configuration: field to sort by and direction (asc/desc).",
+    )
+    stack: bool | str | None = Field(
+        default=None, description="Stack mode for marks that stack by default."
+    )
+    link: str | None = Field(
+        default=None, description="Click-through URL template for drill-down links."
+    )
+    filters: dict[str, FilterDef] | None = Field(
+        default=None,
+        description="Declarative column filters applied to chart data after query execution.",
+    )
+    layers: list[Layer] | None = Field(
+        default=None, description="Layers for multi-mark charts (layered type)."
+    )
+    x_domain: str | None = Field(
+        default=None,
+        description="Controls how x-values from multiple layer queries are combined on the shared x-axis.",
+    )
+    conditional_formatting: dict[str, FieldConditionalFormatting] | None = Field(
+        default=None,
+        description="Discrete rule-driven style overrides indexed by column name.",
+    )
+    data_table: ChartDataTable | None = Field(
+        default=None, description="Optional mini data-grid attached to the chart."
+    )
+    # Box geometry — set at chart root in the authored surface for cartesian charts.
+    # aspect_ratio, min_height, max_height are promoted from per-chart style during normalization.
+    height: int | float | None = Field(
+        default=None,
+        description="Explicit chart height in pixels. None defers to aspect_ratio or theme.",
+    )
+    width: int | float | None = Field(
+        default=None,
+        description=(
+            "Chart width hint in pixels. Feeds the label-overlap heuristic. "
+            "None falls back to the chart rendering config default_width."
+        ),
+    )
+    aspect_ratio: float | None = Field(
+        default=None,
+        description="Chart aspect ratio (width / height). Used when height is not set. Promoted from per-chart style at compile time.",
+    )
+    min_height: float | None = Field(
+        default=None,
+        description=(
+            "Per-chart minimum height in pixels for aspect-ratio-derived sizing. "
+            "Overrides face/theme style.charts.min_height for this chart. "
+            "Has no effect when chart.height is set. Promoted from per-chart style at compile time."
+        ),
+    )
+    max_height: float | None = Field(
+        default=None,
+        description=(
+            "Per-chart maximum height in pixels for aspect-ratio-derived sizing. "
+            "Overrides face/theme style.charts.max_height for this chart. "
+            "Has no effect when chart.height is set. Promoted from per-chart style at compile time."
+        ),
+    )
+    warnings_ignore: list[str] = Field(
+        default_factory=list,
+        description="Codes of render warnings to suppress for this chart.",
+    )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert chart to YAML-compatible dict."""
+        from dataface.core.render.chart.presentation import to_plain_dict
+
+        result: dict[str, Any] = {}
+
+        if self.title:
+            result["title"] = self.title
+        if self.label:
+            result["label"] = self.label
+        if self.type:
+            result["type"] = self.type
+
+        if self.query:
+            query_dict: dict[str, Any] = {}
+            if hasattr(self.query, "sql") and self.query.sql:
+                query_dict["sql"] = self.query.sql
+            if (
+                hasattr(self.query, "source")
+                and self.query.source
+                and isinstance(self.query.source, str)
+            ):
+                query_dict["source"] = self.query.source
+            if hasattr(self.query, "file") and self.query.file:
+                query_dict["file"] = self.query.file
+            if query_dict:
+                result["query"] = query_dict
+
+        if self.x:
+            result["x"] = self.x
+        if self.y:
+            result["y"] = self.y
+        if self.color:
+            result["color"] = self.color
+        if self.size:
+            result["size"] = self.size
+        if self.shape:
+            result["shape"] = self.shape
+        if self.theta:
+            result["theta"] = self.theta
+        if self.format:
+            if hasattr(self.format, "model_dump"):
+                result["format"] = self.format.model_dump(exclude_none=True)
+            else:
+                result["format"] = self.format
+        if self.message:
+            result["message"] = self.message
+
+        if self.geo:
+            result["geo"] = self.geo
+        if self.geo_source:
+            result["geo_source"] = self.geo_source
+        if self.lookup:
+            result["lookup"] = self.lookup
+        if self.value is not None:
+            result["value"] = self.value
+        if self.support is not None:
+            result["support"] = self.support.model_dump(exclude_none=True)
+        if self.projection:
+            result["projection"] = (
+                self.projection
+                if isinstance(self.projection, str)
+                else to_plain_dict(self.projection)
+            )
+        if self.latitude:
+            result["latitude"] = self.latitude
+        if self.longitude:
+            result["longitude"] = self.longitude
+        if self.basemap:
+            result["basemap"] = self.basemap
+        if self.sort:
+            result["sort"] = self.sort.model_dump(exclude_none=True)
+
+        if self.style:
+            result["style"] = self.style.model_dump(exclude_none=True)
+
+        if self.link:
+            result["link"] = self.link
+
+        if self.filters:
+            result["filters"] = {
+                col: fd.to_yaml_form() for col, fd in self.filters.items()
+            }
+
+        return result
+
+    def get_dependencies(self) -> ChartDependencies:
+        """Get all dependencies required to render this chart."""
+        variables: set[str] = self.variable_dependencies.copy()
+        if self.query and hasattr(self.query, "variable_dependencies"):
+            variables |= self.query.variable_dependencies
+
+        sources: set[str] = set()
+        if self.query:
+            source = getattr(self.query, "source", None)
+            if isinstance(source, str):
+                sources.add(source)
+
+        return ChartDependencies(
+            sources=frozenset(sources),
+            variables=frozenset(variables),
+            queries=frozenset(),
+        )
+
+
+# ============================================================================
+# TYPE GUARD
+# ============================================================================
+
+
+def is_chart(item: Any) -> TypeGuard[Chart]:
+    """Type guard for Chart."""
+    return isinstance(item, Chart)