dataface 0.1.2__py3-none-any.whl

dataface/core/compile/chart_focus.py

@@ -0,0 +1,101 @@
+"""Chart focus utilities.
+
+This module provides the `focus_on_chart()` function for rendering a single
+chart from a dataface. It transforms a compiled face to show only one chart
+with its dependent variables.
+
+There are two ways to focus on a chart:
+
+1. **YAML field** (recommended for users):
+   Add `chart_focus: chart_id` to your dataface YAML.
+   The compiler will automatically apply the focus during normalization.
+
+   ```yaml
+   title: Sales Dataface
+   chart_focus: revenue_chart  # Render only this chart
+   charts:
+     revenue_chart:
+       query: sales
+       type: bar
+   rows:
+     - revenue_chart
+   ```
+
+2. **Python API** (for programmatic use):
+   ```python
+   from dataface.core.compile import compile, focus_on_chart
+
+   result = compile(yaml_content)
+   focused = focus_on_chart(result.face, "revenue_chart")
+   render(focused, executor, format="svg")
+   ```
+
+Use cases:
+- Chart editing (focus on one chart while editing)
+- Export single chart (SVG/PNG/PDF)
+- Embed a single chart in another page
+"""
+
+from dataface.core.compile.models.face.authored import LayoutType
+from dataface.core.compile.models.face.compiled import Face, Layout, LayoutItem
+
+
+def focus_on_chart(face: Face, chart_id: str) -> Face:
+    """Transform a compiled face to focus on a single chart.
+
+    Creates a new face with:
+    - Only the specified chart in the layout
+    - Only the variables that chart depends on
+    - All sources and queries unchanged (they're lazy-loaded anyway)
+
+    This is called automatically when `chart_focus` is set in the YAML.
+    It can also be called directly for programmatic chart focusing.
+
+    Args:
+        face: The compiled face containing the chart
+        chart_id: The ID of the chart to focus on
+
+    Returns:
+        A new Face with simplified layout and filtered variables
+
+    Raises:
+        ValueError: If the chart is not found
+
+    Example:
+        >>> result = compile(yaml_content)
+        >>> focused = focus_on_chart(result.face, "revenue_chart")
+        >>> render(focused, executor, format="svg")
+    """
+    # Find the chart - all charts (including inline) are now in face.charts
+    chart = face.charts.get(chart_id)
+    if chart is None:
+        available_charts = (
+            ", ".join(sorted(face.charts.keys())) if face.charts else "none"
+        )
+        raise ValueError(
+            f"Chart '{chart_id}' not found in face. Available charts: {available_charts}"
+        )
+
+    # Get the chart's variable dependencies
+    deps = chart.get_dependencies()
+
+    # Filter variables to only those the chart needs
+    focused_variables = {
+        name: var for name, var in face.variables.items() if name in deps.variables
+    }
+
+    # Create a simple layout with just this chart
+    chart_item = LayoutItem(type="chart", chart=chart)
+    simple_layout = Layout(type=LayoutType.ROWS, items=[chart_item])
+
+    # Create new face with focused content
+    # No title - this is a focused view, not a dataface
+    focused_face = face.model_copy(
+        update={
+            "variables": focused_variables,
+            "layout": simple_layout,
+            "title": "",
+        }
+    )
+
+    return focused_face

dataface/core/compile/chart_resolved.py

@@ -0,0 +1,169 @@
+"""Compile-time domain models for resolved chart semantics.
+
+Stage: COMPILE
+Purpose: Define resolved chart contracts that cross the compile→render boundary.
+
+ResolvedChart is the canonical representation of a chart after compile-time
+resolution — it is what render functions consume.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from dataface.core.compile.channel import ResolvedStyleChannel
+from dataface.core.compile.config import get_config
+from dataface.core.compile.models.chart.authored import (
+    GEO_CHART_TYPES,
+    ChartLabels,
+    ChartTotal,
+    KpiSupportConfig,
+)
+from dataface.core.compile.models.chart.compiled import (
+    NON_ASPECT_RATIO_TYPES,
+    Chart,
+)
+from dataface.core.compile.models.primitives import FormatConfig
+from dataface.core.compile.models.style.compiled import TableColumnDefaultsConfig
+from dataface.core.compile.models.style.merged import (
+    MergedChartsStyle,
+    resolve_style,
+)
+from dataface.core.compile.models.vega_lite.contracts import Projection
+
+FormatState = str | FormatConfig | None
+ZeroState = bool | None
+
+GEO_RENDERER_TYPES = GEO_CHART_TYPES
+
+
+def _renderer_family_for(chart_type: str) -> str:
+    """Classify a resolved chart type into the renderer family that owns it."""
+    if chart_type in NON_ASPECT_RATIO_TYPES:
+        return "svg"
+    if chart_type in GEO_RENDERER_TYPES:
+        return "geo"
+    return "vega"
+
+
+def effective_color_field(chart: ResolvedChart) -> str | None:
+    """Return the color data field from resolved_channels, or None."""
+    color_ch = chart.resolved_channels.get("color")
+    if color_ch is None or color_ch.mode == "literal":
+        return None
+    return color_ch.data_field or None
+
+
+def is_grouped_bar(chart: ResolvedChart) -> bool:
+    """True when a bar chart defaults to grouped (side-by-side) columns.
+
+    A bar with stack=None and a color data field renders as grouped columns
+    (xOffset/yOffset) rather than VL's stacked default.
+    """
+    return (
+        chart.chart_type == "bar"
+        and chart.stack is None
+        and effective_color_field(chart) is not None
+    )
+
+
+@dataclass(frozen=True)
+class ChartLayer:
+    """A single resolved layer in a layered chart.
+
+    ``axis_y`` carries the typed per-layer dual-axis settings (``orient``,
+    ``title``) parsed from authored YAML, normalized to a plain dict.
+    None means "no per-layer override."
+    """
+
+    chart_type: str
+    query_name: str | None = None
+    x: str | None = None
+    y: str | None = None
+    label: str | None = None
+    color: str | None = None
+    fill: str | None = None
+    size: str | None = None
+    shape: str | None = None
+    axis_y: dict[str, Any] | None = None
+
+
+@dataclass(frozen=True, kw_only=True)
+class ResolvedChart:
+    """Render-ready chart semantics with the chart-local style cascade pre-applied.
+
+    The renderer reads ``resolved_style`` for ALL style state — chart-local
+    overrides (axis, legend, scale, mark, palette, …) are baked in by
+    ``build_resolved_style`` during compile. The renderer never sees the
+    original ChartStylePatch, so it cannot discriminate authored vs cascaded
+    values — and does not need to.
+
+    ``orientation`` is promoted to a first-class field (was on ChartStylePatch).
+    """
+
+    source_chart: Chart | Any
+    id: str
+    chart_type: str
+    title: str = ""
+    subtitle: str = ""
+    description: str = ""
+    # KPI-only — text rendered above the headline value. Empty for non-KPI.
+    label: str = ""
+    x: str | None = None
+    y: str | list[str] | None = None
+    size: str | None = None
+    shape: str | None = None
+    theta: str | None = None
+    total: ChartTotal | None = None
+    labels: ChartLabels | None = None
+    format: FormatState = None
+    message: str | None = None
+    zero: ZeroState = None
+    x_label: str | None = None
+    y_label: str | None = None
+    geo: str | dict[str, Any] | None = None
+    geo_source: str | None = None
+    lookup: str | None = None
+    value: str | None = None
+    support: KpiSupportConfig | None = None
+    projection: str | Projection | None = None
+    latitude: str | None = None
+    longitude: str | None = None
+    # For point_map / bubble_map: tile-layer config dict.
+    basemap: dict[str, Any] | None = None
+    sort: Any = None
+    # stack accepts bool | Literal["zero","normalize","center"] | None
+    stack: Any = None
+    orientation: Literal["vertical", "horizontal"] = "vertical"
+    link: str | None = None
+    query_name: str | None = None
+    variable_dependencies: set[str] = field(default_factory=set)
+    resolved_style: MergedChartsStyle = field(
+        default_factory=lambda: resolve_style(get_config().style).charts
+    )
+    # Chart-local table-column configs — preserved for table rendering and
+    # gradient lowering. ChartStylePatch.columns is the authored shape; the
+    # renderer reads from here, not from source_chart.style.
+    columns: dict[str, Any] | None = None
+    # Promoted from ChartStylePatch.header_overflow so the table renderer
+    # reads it from a typed first-class field instead of reaching back into
+    # source_chart.style at emit time.
+    header_overflow: Literal["clip", "truncate", "wrap-two", "wrap"] | None = None
+    # Promoted from ChartStylePatch.column_defaults so the table renderer
+    # applies inherited defaults to query-inferred columns without reaching
+    # back into source_chart.style.
+    column_defaults: TableColumnDefaultsConfig | None = None
+    layers: tuple[ChartLayer, ...] = ()
+    resolved_channels: dict[str, ResolvedStyleChannel] = field(default_factory=dict)
+    # Only meaningful on layered charts with per-layer datasets.
+    x_domain: Literal["union", "primary"] | None = None
+
+    @property
+    def renderer_family(self) -> str:
+        return _renderer_family_for(self.chart_type)
+
+    @property
+    def query(self) -> Any:
+        """Delegate to source_chart.query so callers need not unwrap source_chart."""
+        return getattr(self.source_chart, "query", None)