dataface 0.1.2__py3-none-any.whl

dataface/core/render/chart/render_single.py

@@ -0,0 +1,347 @@
+"""Single-chart render utility shared by sizing pass and render pass."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from dataface.core.compile.models.chart.compiled import (
+    Chart,
+)
+from dataface.core.compile.models.face.compiled import VariableValues
+from dataface.core.render.svg_utils import extract_svg_dimensions
+
+if TYPE_CHECKING:
+    from dataface.core.compile.chart_resolved import ResolvedChart
+    from dataface.core.compile.models.style.merged import MergedStyle
+    from dataface.core.execute.executor import Executor
+
+# Type alias for the SVG render cache used across sizing and render passes.
+# Maps (chart_id, slot_width, slot_height) → (svg_string, actual_height_px).
+RenderCache = dict[tuple[str, float, float], tuple[str, float]]
+
+
+def render_chart_to_svg(
+    chart: Chart,
+    executor: Executor,
+    variables: VariableValues,
+    width: float,
+    height: float | None = None,
+    resolved_style: MergedStyle | None = None,
+    padding: dict[str, Any] | None = None,
+    face_level: int = 1,
+    vega_config: dict[str, Any] | None = None,
+) -> tuple[str, float, float]:
+    """Render a Vega-Lite chart and return (svg_string, actual_width, actual_height).
+
+    Executes the query, resolves the chart, and calls vl-convert.
+    When height=None, Vega auto-sizes vertically (used for initial sizing pass).
+    When height is given, the chart is constrained to that height (used for
+    cols alignment re-renders).
+
+    Shared by both Vega-family and SVG-family chart render paths.
+    Does NOT wrap the SVG in data-attribute groups — that stays in rendering.py.
+
+    ``face_level`` is the heading level of the parent face (root=1, nested=2, …).
+    Chart title uses face_level + 1.
+    """
+    from dataface.core.compile.jinja import resolve_jinja_template
+    from dataface.core.render.chart.pipeline import resolve_chart
+    from dataface.core.render.chart.vega_lite import render_chart as vega_render
+    from dataface.core.render.placeholder import is_placeholder_needed
+    from dataface.core.render.utils import resolve_field_names
+
+    data = [] if chart.type == "callout" else executor.execute_chart(chart, variables)
+
+    # Per-layer datasets for layered charts
+    datasets: dict[str, list[dict[str, Any]]] | None = None
+    if chart.type == "layered" and chart.layers:
+        layer_query_names: set[str] = set()
+        for layer in chart.layers:
+            q = layer.query
+            if isinstance(q, str):
+                layer_query_names.add(q)
+        if layer_query_names:
+            datasets = {}
+            if chart.query_name:
+                datasets[chart.query_name] = data
+            for qn in layer_query_names:
+                if qn not in datasets:
+                    datasets[qn] = executor.execute_query(qn, variables)
+
+    use_placeholder = is_placeholder_needed(chart, data)
+
+    updates: dict[str, str] = {}
+    if chart.title:
+        updates["title"] = resolve_jinja_template(chart.title, variables, strict=False)
+    if chart.label:
+        updates["label"] = resolve_jinja_template(chart.label, variables, strict=False)
+    if chart.subtitle:
+        updates["subtitle"] = resolve_jinja_template(
+            chart.subtitle, variables, strict=False
+        )
+    if chart.message:
+        updates["message"] = resolve_jinja_template(
+            chart.message, variables, strict=False
+        )
+    # KPI link is a static URL template resolved against variables (e.g.
+    # "/region/{{ region }}"). Vega-family charts resolve link per datum at
+    # render time via _build_href_calc_expr — do not pre-resolve those.
+    if chart.type == "kpi" and chart.link:
+        updates["link"] = resolve_jinja_template(chart.link, variables, strict=False)
+    resolved_chart = chart.model_copy(update=updates) if updates else chart
+    resolved_chart = resolve_field_names(resolved_chart, data)
+
+    detect_data = data
+    if use_placeholder and not data:
+        from dataface.core.render.placeholder import generate_placeholder_data
+
+        detect_data = generate_placeholder_data("bar", resolved_chart)
+
+    col_descs = (
+        executor.get_column_descriptions(chart.query_name) if chart.query_name else None
+    )
+    presentation_chart = resolve_chart(
+        resolved_chart, detect_data, col_descs, board_style=resolved_style
+    )
+
+    # Attached-table dispatch — arc charts (only "pie" survives the
+    # normalizer; "donut" → "pie + style.inner_radius") at a tier ×
+    # cardinality where direct labels can't fit cleanly render as donut
+    # SVG + swatch-keyed table SVG composed into one outer <svg>. See
+    # arc_attached_table.py for the trigger rule.
+    if resolved_style is not None and chart.type == "pie" and data:
+        from dataface.core.render.chart.arc_attached_table import (
+            compute_shares,
+            should_attach_table,
+        )
+
+        shares = compute_shares(chart.theta or "", data)
+        if should_attach_table(width, shares):
+            return _render_arc_with_attached_table(
+                presentation_chart=presentation_chart,
+                chart=chart,
+                data=data,
+                shares=shares,
+                width=width,
+                height=height,
+                is_placeholder=use_placeholder,
+                datasets=datasets,
+                variables=variables,
+                padding=padding,
+                resolved_style=resolved_style,
+                face_level=face_level,
+                vega_config=vega_config,
+            )
+
+    # height=None → Vega auto-sizes vertically; actual height read back from SVG.
+    # height=<value> → fixed height constraint (used for cols alignment re-renders).
+    chart_svg = vega_render(
+        presentation_chart,
+        data,
+        format="svg",
+        width=width,
+        height=height,
+        is_placeholder=use_placeholder,
+        datasets=datasets,
+        variables=variables,
+        padding=padding,
+        resolved_style=resolved_style,
+        face_level=face_level,
+        effective_vega_config=vega_config,
+    )
+
+    dims = extract_svg_dimensions(chart_svg)
+    return chart_svg, dims.width, dims.height
+
+
+def _render_arc_with_attached_table(
+    presentation_chart: ResolvedChart,
+    chart: Chart,
+    data: list[dict[str, Any]],
+    shares: list[float],
+    width: float,
+    height: float | None,
+    is_placeholder: bool,
+    datasets: dict[str, list[dict[str, Any]]] | None,
+    variables: VariableValues,
+    padding: dict[str, Any] | None,
+    resolved_style: MergedStyle,
+    face_level: int,
+    vega_config: dict[str, Any] | None,
+) -> tuple[str, float, float]:
+    """Render donut + attached-table composition.
+
+    Donut renders without direct labels (table carries them). Table uses
+    the swatch column + header-hidden config from the β-1 foundation.
+    Palette is read from ``presentation_chart.resolved_style.palette``
+    (chart-local merged style) so any per-chart palette override survives
+    into the swatches — same source the arc layer paints from.
+
+    The ``height`` parameter is intentionally ignored — the composed
+    SVG's natural height (donut + gap + table) flows back through the
+    data-aware sizer so the surrounding layout grows the card to fit.
+    A cols-alignment re-render that tried to constrain height here
+    would clip the table.
+    """
+    import dataclasses
+    from types import SimpleNamespace
+
+    from dataface.core.compile.models.style.authored import (
+        ChartStylePatch,
+        TableChartStylePatch,
+    )
+    from dataface.core.compile.style_cascade import build_resolved_style
+    from dataface.core.render.chart.arc_attached_table import (
+        build_attached_table_columns,
+        compose_attached_table_svg,
+    )
+    from dataface.core.render.chart.table import render_table_svg
+    from dataface.core.render.chart.vega_lite import render_chart as vega_render
+
+    # Donut: replace labels with None so the labels layer doesn't emit.
+    # The arc `order` encoding still fires (data_override + order are
+    # hoisted out of the labels branch in profile.py) so wedge order
+    # stays pinned to data insertion.
+    donut_chart = dataclasses.replace(presentation_chart, labels=None)
+    donut_svg = vega_render(
+        donut_chart,
+        data,
+        format="svg",
+        width=width,
+        height=width,  # donut renders square at the slot width
+        is_placeholder=is_placeholder,
+        datasets=datasets,
+        variables=variables,
+        padding=padding,
+        resolved_style=resolved_style,
+        face_level=face_level,
+        effective_vega_config=vega_config,
+    )
+    donut_dims = extract_svg_dimensions(donut_svg)
+
+    # Series rows for the table — palette from chart-local resolved
+    # style (same source the arc layer paints from), pre-computed shares
+    # from the trigger gate (no duplicate arithmetic).
+    series_rows = _extract_arc_rows_for_table(presentation_chart, data, shares)
+    # Pre-format share as "42%" string — sidesteps the three-lane
+    # numeric layout's %-suffix-drop bug (filed as follow-up).
+    table_data = [
+        {
+            "swatch": r["swatch"],
+            "share": f"{round(r['share'] * 100)}%",
+            "name": r["name"],
+            "value": r["value"],
+        }
+        for r in series_rows
+    ]
+    # Value format — read directly from the chart's format hint
+    # (``str | FormatConfig | None``). ``TableColumnConfig.format``
+    # accepts all three shapes; passing the raw value through preserves
+    # any authored prefix/suffix on a FormatConfig.
+    value_format = presentation_chart.format
+
+    # Width-sizing uses the same font the table will render with —
+    # threaded from the resolved table style (theme-cascaded) so a
+    # theme that retunes table type doesn't desync measurement.
+    table_style = resolved_style.charts.table
+    table_font_size = (
+        float(table_style.font.size) if table_style.font.size is not None else 11.0
+    )
+    table_font_family = table_style.font.family or "Inter Variable"
+    columns, table_target_width = build_attached_table_columns(
+        table_data,
+        value_format=value_format,
+        font_size=table_font_size,
+        font_family=table_font_family,
+    )
+    table_patch = ChartStylePatch(
+        table=TableChartStylePatch.model_validate(
+            {
+                "header": {"visible": False},
+                "pagination": {"enabled": False},
+                "columns": columns,
+            }
+        )
+    )
+    # SimpleNamespace stand-in — render_table_svg reads chart attributes
+    # by attribute access. Stdlib ad-hoc carrier; no mock framework in
+    # production code. ``chart.id`` is guaranteed on a normalized Chart
+    # so we read it directly.
+    table_chart = SimpleNamespace(
+        id=f"{chart.id}__attached_table",
+        title=None,
+        subtitle=None,
+        style=table_patch,
+        columns=None,
+        column_defaults=None,
+        link=None,
+    )
+
+    table_resolved = build_resolved_style(resolved_style, table_patch)
+    table_render_width = min(table_target_width, float(width))
+    table_svg = render_table_svg(
+        table_chart,
+        table_data,
+        width=table_render_width,
+        resolved_style=table_resolved,
+        board_style=resolved_style,
+    )
+    table_dims = extract_svg_dimensions(table_svg)
+
+    composed, w, h = compose_attached_table_svg(
+        donut_svg=donut_svg,
+        table_svg=table_svg,
+        donut_width=donut_dims.width,
+        donut_height=donut_dims.height,
+        table_width=table_dims.width,
+        table_height=table_dims.height,
+    )
+    return composed, w, h
+
+
+def _extract_arc_rows_for_table(
+    presentation_chart: ResolvedChart,
+    data: list[dict[str, Any]],
+    shares: list[float],
+) -> list[dict[str, Any]]:
+    """Build per-wedge rows for the attached table.
+
+    Palette source is the **chart-local** merged style
+    (``presentation_chart.resolved_style.palette``) — same source the
+    arc layer paints wedges from. Reading the board-level palette
+    instead would silently desync swatches from wedges whenever a chart
+    overrides ``style.palette`` or ``style.range.category``.
+
+    Shares are passed in (already computed at the trigger gate) rather
+    than recomputed here. ``data`` and ``shares`` are expected to have
+    the same length (``compute_shares`` returns one share per data row);
+    ``zip(..., strict=True)`` enforces that invariant.
+    """
+    from dataface.core.render.errors import ChartDataError
+
+    theta_field = presentation_chart.theta or ""
+    color_ch = presentation_chart.resolved_channels.get("color")
+    color_field = (
+        color_ch.data_field
+        if color_ch is not None and color_ch.data_field is not None
+        else None
+    )
+    palette = list(presentation_chart.resolved_style.palette)
+    if not palette:
+        raise ChartDataError(
+            f"Arc chart {presentation_chart.id!r} attached-table render "
+            "needs a resolved palette, but the chart-local style produced "
+            "an empty list.",
+            chart_id=presentation_chart.id,
+        )
+    rows: list[dict[str, Any]] = []
+    for idx, (row, share) in enumerate(zip(data, shares, strict=True)):
+        rows.append(
+            {
+                "swatch": palette[idx % len(palette)],
+                "share": share,
+                "name": row.get(color_field) if color_field else None,
+                "value": row.get(theta_field, 0) or 0,
+            }
+        )
+    return rows

dataface/core/render/chart/renderers.py

@@ -0,0 +1,193 @@
+"""Renderer registry for resolved charts."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Protocol
+
+if TYPE_CHECKING:
+    from dataface.core.compile.models.style.merged import MergedStyle
+
+from dataface.core.compile.chart_resolved import ResolvedChart
+from dataface.core.render.chart.artifacts import RenderArtifact
+from dataface.core.render.chart.callout import render_callout_chart_svg
+from dataface.core.render.chart.kpi import render_kpi_svg
+from dataface.core.render.chart.serialization import build_dataface_json
+from dataface.core.render.chart.spark_bar import render_spark_bar_svg
+from dataface.core.render.chart.standard_renderer import render_standard_vega_spec
+from dataface.core.render.chart.table import render_table_svg
+
+SVG_RENDERERS: dict[str, Callable[..., str]] = {
+    "table": render_table_svg,
+    "spark_bar": render_spark_bar_svg,
+    "kpi": render_kpi_svg,
+    "callout": render_callout_chart_svg,
+}
+
+# SVG chart types that consume `variables` for pagination state.
+_VARIABLE_AWARE_SVG_TYPES = {"table"}
+
+
+class ChartRenderer(Protocol):
+    def render(
+        self,
+        chart: ResolvedChart,
+        data: list[dict[str, Any]],
+        width: float | None = None,
+        height: float | None = None,
+        is_placeholder: bool = False,
+        datasets: dict[str, list[dict[str, Any]]] | None = None,
+        variables: dict[str, Any] | None = None,
+        padding: dict[str, Any] | None = None,
+        face_level: int = 1,
+    ) -> RenderArtifact: ...
+
+
+@dataclass
+class StandardVegaLiteRenderer:
+    def render(
+        self,
+        chart: ResolvedChart,
+        data: list[dict[str, Any]],
+        width: float | None = None,
+        height: float | None = None,
+        is_placeholder: bool = False,
+        datasets: dict[str, list[dict[str, Any]]] | None = None,
+        variables: dict[str, Any] | None = None,
+        padding: dict[str, Any] | None = None,
+        face_level: int = 1,
+        resolved_style: MergedStyle | None = None,
+        effective_vega_config: dict[str, Any] | None = None,
+    ) -> RenderArtifact:
+        return RenderArtifact(
+            kind="vega_spec",
+            payload=render_standard_vega_spec(
+                chart,
+                data,
+                width,
+                height,
+                datasets=datasets,
+                padding=padding,
+                resolved_style=resolved_style,
+                face_level=face_level,
+                effective_vega_config=effective_vega_config,
+            ),
+        )
+
+
+@dataclass
+class SvgRenderer:
+    def render(
+        self,
+        chart: ResolvedChart,
+        data: list[dict[str, Any]],
+        width: float | None = None,
+        height: float | None = None,
+        is_placeholder: bool = False,
+        datasets: dict[str, list[dict[str, Any]]] | None = None,
+        variables: dict[str, Any] | None = None,
+        padding: (
+            dict[str, Any] | None
+        ) = None,  # intentionally unused: SVG-family uses SVG translate
+        face_level: int = 1,
+        resolved_style: MergedStyle | None = None,
+    ) -> RenderArtifact:
+        # KPI/spark/spark_bar/table take chart-level MergedChartsStyle as
+        # ``resolved_style``; callout takes the board-level MergedStyle for
+        # callout card styling. The two surfaces don't overlap on a single
+        # call, so a per-type swap is enough — no separate "chart_style" kwarg.
+        kwargs: dict[str, Any] = {
+            "width": width,
+            "height": height,
+            "is_placeholder": is_placeholder,
+            "face_level": face_level,
+        }
+        if chart.chart_type == "callout":
+            assert (
+                resolved_style is not None
+            ), f"{chart.chart_type} renderer requires resolved_style"
+            kwargs["resolved_style"] = resolved_style
+        else:
+            if resolved_style is None:
+                raise ValueError(
+                    f"SvgRenderer.render requires resolved_style (board-level MergedStyle) "
+                    f"for chart type '{chart.chart_type}'. "
+                    "Thread the face's MergedStyle from the render pipeline."
+                )
+            kwargs["resolved_style"] = chart.resolved_style
+            kwargs["board_style"] = resolved_style
+        if chart.chart_type in _VARIABLE_AWARE_SVG_TYPES:
+            kwargs["variables"] = variables
+        svg = SVG_RENDERERS[chart.chart_type](chart, data, **kwargs)
+        return RenderArtifact(kind="svg", payload=svg)
+
+
+@dataclass
+class RendererRegistry:
+    standard_renderer: ChartRenderer = field(default_factory=StandardVegaLiteRenderer)
+    geo_renderer: ChartRenderer = field(default_factory=StandardVegaLiteRenderer)
+    svg_renderer: ChartRenderer = field(default_factory=SvgRenderer)
+
+    def select(self, chart: ResolvedChart) -> ChartRenderer:
+        if chart.renderer_family == "svg":
+            return self.svg_renderer
+        if chart.renderer_family == "geo":
+            return self.geo_renderer
+        return self.standard_renderer
+
+    def render(
+        self,
+        chart: ResolvedChart,
+        data: list[dict[str, Any]],
+        width: float | None = None,
+        height: float | None = None,
+        is_placeholder: bool = False,
+        datasets: dict[str, list[dict[str, Any]]] | None = None,
+        variables: dict[str, Any] | None = None,
+        padding: dict[str, Any] | None = None,
+        resolved_style: MergedStyle | None = None,
+        face_level: int = 1,
+        effective_vega_config: dict[str, Any] | None = None,
+    ) -> RenderArtifact:
+        renderer = self.select(chart)
+        # SVG-family always needs resolved_style; VL/geo families take it
+        # too so the chart's halo/knockout/spec background match the face's
+        # *actual* resolved background rather than re-deriving from theme name
+        # (which can mismatch when the face has chart-local style overrides).
+        extra: dict[str, Any] = (
+            {"resolved_style": resolved_style}
+            if chart.renderer_family in ("svg", "vega", "geo")
+            else {}
+        )
+        if (
+            chart.renderer_family in ("vega", "geo")
+            and effective_vega_config is not None
+        ):
+            extra["effective_vega_config"] = effective_vega_config
+        return renderer.render(
+            chart,
+            data,
+            width,
+            height,
+            is_placeholder,
+            datasets=datasets,
+            variables=variables,
+            padding=padding,
+            face_level=face_level,
+            **extra,
+        )
+
+
+def build_chart_json(
+    chart: ResolvedChart,
+    data: list[dict[str, Any]],
+    width: float | None = None,
+    height: float | None = None,
+) -> RenderArtifact:
+    return RenderArtifact(
+        kind="json",
+        payload=build_dataface_json(
+            chart.source_chart, data, width=width, height=height
+        ),
+    )