dataface 0.1.2__py3-none-any.whl

dataface/core/render/chart/rendering.py

@@ -0,0 +1,565 @@
+"""Chart and layout-item rendering entrypoints.
+
+This module owns:
+- executing a chart query
+- resolving the chart into render-ready semantics
+- dispatching to chart vs nested-face rendering
+
+UI chrome such as menus is handled outside core rendering.
+"""
+
+from __future__ import annotations
+
+import html
+from typing import TYPE_CHECKING, Any
+
+from dataface.core.compile.config import get_config
+from dataface.core.compile.errors import DatafaceError
+from dataface.core.compile.models.chart.compiled import (
+    SVG_LAYOUT_PADDED_TYPES,
+    Chart,
+)
+from dataface.core.compile.models.face.compiled import (
+    Face,
+    LayoutItem,
+    MergedFace,
+    ResolvedLayoutItem,
+    VariableValues,
+)
+from dataface.core.compile.models.style.merged import MergedStyle
+from dataface.core.errors import DF_RENDER_INTERNAL, StructuredError
+from dataface.core.execute.executor import Executor
+from dataface.core.render.chart.spec_builders import additive_padding
+
+if TYPE_CHECKING:
+    from dataface.core.execute.adapters.base import SchemaStatus
+from dataface.core.render.svg_utils import (
+    _px,
+    extract_svg_dimensions,
+    extract_svg_inner_content,
+)
+from dataface.core.render.variable_controls import evaluate_visible
+
+__all__ = [
+    "render_layout_item",
+    "render_chart_item",
+]
+
+
+def _uses_svg_family_layout_padding(chart_type: str) -> bool:
+    """Return whether the chart should be inset by layout card padding."""
+    return chart_type in SVG_LAYOUT_PADDED_TYPES
+
+
+def _ensure_resolved_face(face: Face | MergedFace) -> MergedFace:
+    """Return the face as a MergedFace, resolving it if it's a Face."""
+    if isinstance(face, MergedFace):
+        return face
+    from dataface.core.resolve_face import resolve_nested_face
+
+    return resolve_nested_face(face)
+
+
+def _coerce_border_radius(value: object) -> float:
+    """Return a numeric border radius from numeric or CSS-ish values."""
+    if value is None:
+        return 0.0
+    if isinstance(value, (int, float)):
+        return float(value)
+
+    text = str(value).strip()
+    if not text:
+        return 0.0
+    if text.endswith("px"):
+        text = text[:-2].strip()
+
+    try:
+        return float(text)
+    except ValueError as exc:
+        raise ValueError(f"Invalid border_radius value: {value!r}") from exc
+
+
+def render_layout_item(
+    item: LayoutItem | ResolvedLayoutItem,
+    executor: Executor,
+    variables: VariableValues,
+    card_gap: float,
+    available_width: float,
+    available_height: float = 300.0,
+    gap: float = 0.0,
+    resolved_style: MergedStyle | None = None,
+    interactive: bool = True,
+    render_cache: dict[tuple[str, float, float], tuple[str, float]] | None = None,
+    error_collector: list[StructuredError] | None = None,
+    face_level: int = 1,
+    vega_config: dict[str, Any] | None = None,
+) -> tuple[str, float]:
+    """Render a single layout item (chart, nested face, or details section).
+
+    If the item has details metadata, renders a collapsible section:
+    - Summary bar (always rendered, clickable)
+    - Content (only rendered when the details variable is true)
+
+    Args:
+        item: Layout item to render
+        executor: Executor for query execution
+        variables: Variable values for queries
+        available_width: Width in pixels for the item
+        available_height: Height in pixels for the item
+        resolved_style: Board-scoped MergedStyle for effective chart style.
+        interactive: Whether to render interactive variable controls (foreignObject).
+        face_level: Heading level of the parent face (root=1, nested=2, …).
+
+    Returns:
+        (svg_string, actual_height) — actual_height is the true rendered height.
+    """
+    # Evaluate visible expression before doing any work — hidden items cost nothing.
+    if not evaluate_visible(item.visible, variables, executor):
+        return "", 0.0
+
+    # Use calculated dimensions if available, otherwise use passed dimensions
+    width = item.width if item.width > 0 else available_width
+    height = item.height if item.height > 0 else available_height
+
+    # Details (collapsible section): render summary bar + conditionally render content
+    if item.details_variable and item.details_summary:
+        from dataface.core.compile.models.style.merged import resolve_style
+        from dataface.core.render.layouts import (
+            is_details_expanded,
+            render_details_summary,
+        )
+
+        resolved_style = resolved_style or resolve_style(get_config().style)
+        details_config = resolved_style.layout.details
+        summary_height = float(details_config.summary_height)
+
+        expanded = is_details_expanded(item, variables)
+        summary_svg = render_details_summary(
+            item,
+            variables,
+            width,
+            expanded=expanded,
+            resolved_style=resolved_style,  # keyword-only, required
+        )
+
+        if expanded and item.face:
+            from dataface.core.compile.sizing import details_chrome_height
+            from dataface.core.render.faces import render_nested_face
+
+            content_height = height - details_chrome_height(
+                item, gap=gap, card_gap=card_gap
+            )
+            content_svg, face_actual_height = render_nested_face(
+                _ensure_resolved_face(item.face),
+                executor,
+                variables,
+                width,
+                content_height,
+                card_gap,
+                interactive,
+                render_cache,
+                error_collector=error_collector,
+            )
+            actual_height = float(
+                _px(summary_height + details_config.content_y_offset)
+                + face_actual_height
+            )
+            section_border = (
+                f'<rect x="0" y="0" width="{width}" height="{actual_height}" '
+                f'fill="none" stroke="{resolved_style.border.color}" stroke-width="{details_config.border.width}" rx="{details_config.border.radius}"/>'
+            )
+            rendered = (
+                f"{section_border}"
+                f"{summary_svg}"
+                f'<g transform="translate(0, {_px(summary_height + details_config.content_y_offset)})">'
+                f"{content_svg}</g>"
+            )
+        else:
+            rendered = summary_svg
+            actual_height = summary_height
+    else:
+        rendered = ""
+        actual_height = height
+        if item.type == "chart" and item.chart:
+            # Card padding strategy differs by renderer family:
+            # - SVG-family (table/kpi/spark_bar): render at reduced size, wrap in
+            #   SVG translate so content is inset by card_padding on all sides.
+            # - Vega-family: render at full item size, forward card_padding as
+            #   Vega's internal padding dict so Vega handles the inset itself.
+            #   This aligns Vega content (marks, axis) with face titles which are
+            #   also positioned at x_offset + card_padding.
+            from dataface.core.compile.models.style.merged import resolve_style
+
+            resolved_style = resolved_style or resolve_style(get_config().style)
+            card_padding = float(resolved_style.board.card_padding)
+            is_svg_family = _uses_svg_family_layout_padding(item.chart.type)
+
+            if is_svg_family:
+                chart_svg, chart_actual_height = render_chart_item(
+                    item.chart,
+                    executor,
+                    variables,
+                    width,
+                    height,
+                    resolved_style=resolved_style,
+                    render_cache=render_cache,
+                    svg_layout_padding=card_padding,
+                    error_collector=error_collector,
+                    face_level=face_level,
+                    vega_config=vega_config,
+                )
+                if chart_svg:
+                    rendered = chart_svg
+                    actual_height = chart_actual_height
+            else:
+                # Vega-family: full item dimensions, padding forwarded to Vega spec.
+                chart_svg, chart_actual_height = render_chart_item(
+                    item.chart,
+                    executor,
+                    variables,
+                    width,
+                    height,
+                    resolved_style=resolved_style,
+                    render_cache=render_cache,
+                    padding=additive_padding(
+                        card_padding, resolved_style.charts.padding
+                    ),
+                    error_collector=error_collector,
+                    face_level=face_level,
+                    vega_config=vega_config,
+                )
+                if chart_svg:
+                    rendered = chart_svg
+                    actual_height = chart_actual_height
+        elif item.type == "face" and item.face:
+            # Import here to avoid circular imports
+            from dataface.core.render.faces import render_nested_face
+
+            rendered, actual_height = render_nested_face(
+                _ensure_resolved_face(item.face),
+                executor,
+                variables,
+                width,
+                available_height=height,
+                card_gap=card_gap,
+                interactive=interactive,
+                render_cache=render_cache,
+                error_collector=error_collector,
+            )
+
+    if rendered and item.description:
+        escaped_description = html.escape(item.description)
+        return (
+            f'<g class="dft-layout-item" data-layout-description="{escaped_description}"'
+            f' aria-label="{escaped_description}">'
+            f"{rendered}</g>",
+            actual_height,
+        )
+    return rendered, actual_height
+
+
+def _render_callout_block(
+    exc: DatafaceError,
+    chart: Chart,
+    executor: Executor,
+    variables: VariableValues,
+    available_width: float,
+    available_height: float,
+    resolved_style: MergedStyle | None,
+    error_collector: list[StructuredError] | None,
+) -> tuple[str, float]:
+    """Build an inline error SVG block and optionally collect the StructuredError.
+
+    Single call site for chart-error materialisation — the streaming task can
+    wrap this as a yield point without hunting across multiple files.
+    """
+    from dataface.core.render.chart.callout import render_callout_svg
+
+    # Stamp chart_id on fields so to_structured() carries it.
+    exc.fields["chart_id"] = chart.id
+    structured = exc.to_structured()
+
+    if error_collector is not None:
+        error_collector.append(structured)
+
+    chart_svg = render_callout_svg(
+        chart_id=chart.id,
+        message=structured.message,
+        width=available_width,
+        height=available_height,
+        title=f"Chart Error: {chart.id}",
+        resolved_style=resolved_style,
+        code=structured.code,
+        hint=structured.hint,
+        doc_url=structured.doc_url,
+        tone="negative",
+    )
+    svg, actual_height = _wrap_rendered_chart_svg(
+        chart,
+        chart_svg,
+        available_width=available_width,
+        executor=executor,
+        resolved_title=chart.id,
+        extra_classes=("dft-chart-callout",),
+        is_error_fallback=True,
+    )
+    return svg, actual_height
+
+
+def render_chart_item(
+    chart: Chart,
+    executor: Executor,
+    variables: VariableValues,
+    available_width: float,
+    available_height: float = 300.0,
+    *,
+    resolved_style: MergedStyle | None = None,
+    render_cache: dict[tuple[str, float, float], tuple[str, float]] | None = None,
+    padding: dict[str, Any] | None = None,
+    svg_layout_padding: float = 0.0,
+    error_collector: list[StructuredError] | None = None,
+    face_level: int = 1,
+    vega_config: dict[str, Any] | None = None,
+) -> tuple[str, float]:
+    """Render a chart item with explicit dimensions.
+
+    Args:
+        chart: Chart to render
+        executor: Executor for query execution
+        variables: Variable values for queries
+        available_width: Width in pixels for the chart
+        available_height: Height in pixels for the chart
+        resolved_style: Board-scoped MergedStyle for effective chart style.
+        render_cache: Optional cache of pre-rendered SVGs from sizing pass.
+        padding: Vega-Lite padding dict forwarded from layout (Vega-family only).
+        error_collector: When provided, per-chart StructuredErrors are appended here.
+
+    Returns:
+        (svg_string, actual_height) — actual_height is the true rendered height.
+    """
+    from dataface.core.execute.errors import ExecutionError
+    from dataface.core.render.errors import RenderError
+
+    try:
+        render_width = available_width
+        render_height = available_height
+        if _uses_svg_family_layout_padding(chart.type):
+            render_width = max(available_width - 2 * svg_layout_padding, 0.0)
+            render_height = max(available_height - 2 * svg_layout_padding, 0.0)
+
+        svg, actual_height = _render_chart_item_inner(
+            chart,
+            executor,
+            variables,
+            render_width,
+            render_height,
+            resolved_style=resolved_style,
+            render_cache=render_cache,
+            padding=padding,
+            face_level=face_level,
+            vega_config=vega_config,
+        )
+        if svg_layout_padding and _uses_svg_family_layout_padding(chart.type):
+            padding_px = _px(svg_layout_padding)
+            svg = f'<g transform="translate({padding_px}, {padding_px})">' f"{svg}</g>"
+            actual_height += 2 * padding_px
+        return svg, actual_height
+    except (RenderError, ExecutionError, DatafaceError) as e:
+        # RenderError subsumes ChartDataError — existing KPI multirow path preserved.
+        # DatafaceError subsumes JinjaError and other compile-stage errors that
+        # escape into render (e.g. jinja in a chart title evaluated at render time).
+        return _render_callout_block(
+            e,
+            chart,
+            executor,
+            variables,
+            available_width,
+            available_height,
+            resolved_style,
+            error_collector,
+        )
+    except Exception as e:  # noqa: BLE001
+        wrapped = RenderError.from_code(DF_RENDER_INTERNAL, inner_message=str(e))
+        return _render_callout_block(
+            wrapped,
+            chart,
+            executor,
+            variables,
+            available_width,
+            available_height,
+            resolved_style,
+            error_collector,
+        )
+
+
+def _render_chart_item_inner(
+    chart: Chart,
+    executor: Executor,
+    variables: VariableValues,
+    available_width: float,
+    available_height: float = 300.0,
+    resolved_style: MergedStyle | None = None,
+    render_cache: dict[tuple[str, float, float], tuple[str, float]] | None = None,
+    padding: dict[str, Any] | None = None,
+    face_level: int = 1,
+    vega_config: dict[str, Any] | None = None,
+) -> tuple[str, float]:
+    """Internal chart rendering — raises on error.
+
+    Delegates chart-resolution and vl-convert rendering to render_chart_to_svg()
+    so the pipeline (query-execute → resolve → render) lives in one place.
+    SVG-family charts (table/kpi/spark_bar) use an explicit height; Vega-family
+    charts auto-size vertically (height=None). Cache is only used for Vega-family.
+    """
+    from dataface.core.compile.jinja import resolve_jinja_template
+    from dataface.core.render.chart.render_single import render_chart_to_svg
+
+    # SVG-family charts own their height; Vega-family auto-sizes vertically.
+    # Cache is only valid for Vega-family (SVG-family always re-renders).
+    is_svg_family = chart.type in SVG_LAYOUT_PADDED_TYPES
+    height_arg: float | None = available_height if is_svg_family else None
+
+    cache_key = (chart.id, available_width, available_height)
+    if render_cache is not None and not is_svg_family and cache_key in render_cache:
+        chart_svg, _ = render_cache[cache_key]
+    else:
+        # render_chart_to_svg owns the full pipeline: execute → resolve → vl-convert.
+        # Note: Renders individually; batch rendering could improve performance.
+        # See: plans/archive/VEGA_SVG_BATCH_CONVERSION_ANALYSIS.md
+        chart_svg, _, _ = render_chart_to_svg(
+            chart,
+            executor,
+            variables,
+            available_width,
+            height=height_arg,
+            resolved_style=resolved_style,
+            padding=padding,
+            face_level=face_level,
+            vega_config=vega_config,
+        )
+
+    # Resolve chart title for data attributes (Jinja only — no full resolve needed).
+    # KPI charts carry their authored text in ``label``; every other chart type
+    # uses ``title``. The wire-level ``data-chart-title`` attribute stays under
+    # one name regardless (it is an accessibility/identification handle, not
+    # tied to the YAML field name).
+    chart_title_source = chart.label if chart.type == "kpi" else chart.title
+    chart_title = (
+        resolve_jinja_template(chart_title_source, variables, strict=False)
+        if chart_title_source
+        else ""
+    ) or chart.id
+
+    # Apply chart-local background wrapper. ``style.background`` is a
+    # chart-local-only field — read it directly off the authored ``chart.style``.
+    # ``style.border`` is now eagerly merged into ``resolved_style.charts.border``
+    # by the cascade, so border.radius comes from there.
+    chart_style = getattr(chart, "style", None)
+    bg_color = getattr(chart_style, "background", None) if chart_style else None
+    if bg_color:
+        inner_content = extract_svg_inner_content(chart_svg)
+        dims = extract_svg_dimensions(chart_svg)
+        assert resolved_style is not None
+        chart_border_radius = _coerce_border_radius(resolved_style.charts.border.radius)
+        bg_rect = f'<rect x="0" y="0" width="{dims.width}" height="{dims.height}" fill="{bg_color}" rx="{chart_border_radius}"/>'
+        chart_svg = f'<svg xmlns="http://www.w3.org/2000/svg" width="{dims.width}" height="{dims.height}" viewBox="0 0 {dims.width} {dims.height}">{bg_rect}{inner_content}</svg>'
+
+    return _wrap_rendered_chart_svg(
+        chart,
+        chart_svg,
+        available_width=available_width,
+        executor=executor,
+        resolved_title=chart_title,
+    )
+
+
+def _wrap_rendered_chart_svg(
+    chart: Chart,
+    chart_svg: str,
+    available_width: float,
+    executor: Executor,
+    resolved_title: str | None = None,
+    extra_classes: tuple[str, ...] = (),
+    is_error_fallback: bool = False,
+) -> tuple[str, float]:
+    dims = extract_svg_dimensions(chart_svg)
+    chart_height_actual = dims.height
+    # Internal SVG-family renderers embed directly in the chart wrapper <g>;
+    # extract their inner content to avoid a redundant nested <svg> viewport.
+    # is_error_fallback marks the ChartDataError path, where the payload is a
+    # render_callout_svg card on top of any chart.type (including Vega).
+    # Vega/Vega-Lite output otherwise remains as a standalone nested <svg>.
+    is_internal_svg = (
+        chart.type in SVG_LAYOUT_PADDED_TYPES
+        or chart.type == "callout"
+        or is_error_fallback
+    )
+    if is_internal_svg:
+        chart_content = extract_svg_inner_content(chart_svg)
+    else:
+        chart_content = chart_svg
+
+    var_deps = chart.variable_dependencies or set()
+    var_attrs = (
+        " ".join(f'data-var-{html.escape(v)}="true"' for v in sorted(var_deps))
+        if var_deps
+        else ""
+    )
+
+    chart_title = (resolved_title or chart.id) or chart.id
+    escaped_title = html.escape(chart_title)
+    escaped_id = html.escape(chart.id)
+    escaped_description = html.escape(chart.description) if chart.description else ""
+    accessible_label = chart_title
+    if chart.description:
+        accessible_label = f"{chart_title} — {chart.description}"
+    escaped_accessible_label = html.escape(accessible_label)
+
+    schema_status = _resolve_schema_status(executor, chart.query_name)
+
+    classes = ["dft-chart", *extra_classes]
+    if chart.type == "callout" and "dft-chart-callout" not in classes:
+        classes.append("dft-chart-callout")
+    if schema_status:
+        classes.append(f"dft-schema-{schema_status}")
+    class_attr = " ".join(classes)
+    attrs_parts = [
+        f'class="{class_attr}"',
+        f'id="chart-{escaped_id}"',
+        f'data-chart-id="{escaped_id}"',
+        f'data-chart-title="{escaped_title}"',
+        f'data-chart-width="{available_width}"',
+        f'data-chart-height="{chart_height_actual}"',
+        f'aria-label="{escaped_accessible_label}"',
+    ]
+    if schema_status:
+        attrs_parts.append(f'data-schema-status="{schema_status}"')
+    if escaped_description:
+        attrs_parts.append(f'data-chart-description="{escaped_description}"')
+    if var_attrs:
+        attrs_parts.append(var_attrs)
+
+    attrs_str = " " + " ".join(attrs_parts)
+    return f"<g{attrs_str}>{chart_content}</g>", chart_height_actual
+
+
+def _resolve_schema_status(
+    executor: Executor, query_name: str | None
+) -> SchemaStatus | None:
+    """Derive aggregate schema status for a chart from its query's provenance.
+
+    Returns "changed" if any relation used a dev/branch schema,
+    "unchanged" if all relations matched prod, "unknown" if provenance
+    exists but classification is uncertain, or None if no provenance.
+    """
+    if not query_name:
+        return None
+    relations = executor.get_query_provenance(query_name)
+    if not relations:
+        return None
+    statuses = {r.status for r in relations}
+    if "changed" in statuses:
+        return "changed"
+    if "unknown" in statuses:
+        return "unknown"
+    return "unchanged"

dataface/core/render/chart/serialization.py

@@ -0,0 +1,90 @@
+"""Serialization helpers for chart rendering outputs."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from dataface.core.compile.models.chart.compiled import (
+    Chart,
+)
+from dataface.core.render.utils import normalize_data_types
+
+
+def build_dataface_json(
+    chart: Chart | Any,
+    data: list[dict[str, Any]],
+    width: float | None = None,
+    height: float | None = None,
+) -> dict[str, Any]:
+    """Build the normalized Dataface JSON representation for a chart."""
+    normalized_data = normalize_data_types(data)
+    result: dict[str, Any] = {"type": chart.type}
+
+    if chart.title:
+        result["title"] = chart.title
+    if getattr(chart, "label", None):
+        result["label"] = chart.label
+    if chart.subtitle:
+        result["subtitle"] = chart.subtitle
+    if chart.description:
+        result["description"] = chart.description
+
+    for field in ["x", "y", "color", "size", "shape"]:
+        value = getattr(chart, field, None)
+        if value is not None:
+            result[field] = value
+
+    for field in ["x_label", "y_label"]:
+        value = getattr(chart, field, None)
+        if value is not None:
+            result[field] = value
+
+    if chart.format is not None:
+        result["format"] = (
+            chart.format.model_dump(exclude_none=True)
+            if hasattr(chart.format, "model_dump")
+            else chart.format
+        )
+
+    # KPI quantitative-text-object fields. `support` is a Pydantic model so it
+    # needs ``model_dump`` to be JSON-serializable.
+    support = getattr(chart, "support", None)
+    if support is not None:
+        result["support"] = support.model_dump(exclude_none=True)
+
+    for field in [
+        "geo",
+        "geo_source",
+        "lookup",
+        "value",
+        "projection",
+        "latitude",
+        "longitude",
+        "background",
+    ]:
+        value = getattr(chart, field, None)
+        if value is not None:
+            result[field] = value
+
+    if chart.filters is not None:
+        result["filters"] = {
+            col: fd.to_yaml_form() for col, fd in chart.filters.items()
+        }
+
+    if chart.style:
+        result["style"] = chart.style.model_dump(exclude_none=True)
+
+    link = getattr(chart, "link", None)
+    if link:
+        result["link"] = link
+
+    if chart.type == "table":
+        result["columns"] = list(normalized_data[0].keys()) if normalized_data else []
+
+    result["data"] = normalized_data
+    if width is not None:
+        result["width"] = width
+    if height is not None:
+        result["height"] = height
+
+    return result