dataface 0.1.2__py3-none-any.whl

dataface/core/render/chart/vega_lite_types.py

@@ -0,0 +1,268 @@
+"""Standard chart type Vega-Lite spec generators.
+
+Each generator receives a ``MappedChart`` from ``profile.py`` and performs
+mechanical Vega-Lite spec assembly — dimensions, title, tooltips.  No
+Dataface/VL encoding divergence logic lives here; that belongs in profile.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from dataface.core.compile.chart_resolved import ResolvedChart
+from dataface.core.render.chart.profile import MappedChart
+from dataface.core.render.chart.spec_builders import (
+    new_chart_spec,
+    set_chart_dimensions,
+    set_chart_title,
+    tooltip_entry,
+)
+from dataface.core.render.format_utils import resolve_format
+from dataface.core.render.text.case import format_display_text
+from dataface.core.render.utils import normalize_data_types
+
+
+def _generate_layered_spec(
+    mapped: MappedChart,
+    chart: ResolvedChart,
+    data: list[dict[str, Any]],
+    width: float | None = None,
+    height: float | None = None,
+    min_height: float | None = None,
+) -> dict[str, Any]:
+    """Assemble layered chart spec from the profile-mapped layered contract."""
+    if mapped.data_override is not None:
+        data = mapped.data_override
+    data = normalize_data_types(data)
+    tooltip_number_format = resolve_format(
+        chart.resolved_style.tooltip.format, chart.resolved_style.formats
+    )
+
+    has_datasets = mapped.datasets is not None
+
+    # Collect y fields: from chart.y (multi-metric) or from layers (type: layered)
+    y_fields = chart.y or []
+    if not isinstance(y_fields, list):
+        y_fields = [y_fields]
+    if not y_fields and chart.layers:
+        y_fields = [layer.y for layer in chart.layers if layer.y]
+
+    # When layers use different datasets, there's no shared x field for
+    # a combined tooltip.  Fall back to per-layer tooltips.
+    x_field = mapped.encoding.get("x", {}).get("field") if not has_datasets else None
+
+    # Build tooltip showing all metrics at once (only for shared-data layers)
+    tooltip_fields: list[dict[str, Any]] = []
+    if x_field:
+        tooltip_fields.append(
+            tooltip_entry(
+                x_field,
+                mapped.encoding.get("x", {}).get("type", "nominal"),
+                title=format_display_text(
+                    x_field, from_slug=True, font=chart.resolved_style.axis_x.title.font
+                ),
+            ),
+        )
+    if not has_datasets:
+        for metric in y_fields:
+            tooltip_fields.append(
+                tooltip_entry(
+                    metric,
+                    "quantitative",
+                    title=format_display_text(
+                        metric,
+                        from_slug=True,
+                        font=chart.resolved_style.axis_y.title.font,
+                    ),
+                    format=tooltip_number_format,
+                ),
+            )
+
+    # Normalize datasets values when present
+    normalized_datasets = None
+    if mapped.datasets:
+        normalized_datasets = {
+            name: normalize_data_types(rows) for name, rows in mapped.datasets.items()
+        }
+
+    spec = new_chart_spec(data, layer=True, datasets=normalized_datasets)
+    set_chart_dimensions(spec, width, height, min_height=min_height)
+
+    if mapped.encoding:
+        spec["encoding"] = dict(mapped.encoding)
+
+    # Prevents future-date rows in secondary layers from stretching the axis
+    # beyond the primary query's range (Looker merged-result visual match).
+    first_dataset_name: str | None = None
+    first_layer_x_field: str | None = None
+    if chart.x_domain == "primary" and mapped.layers:
+        if not has_datasets:
+            raise ValueError(
+                f"Chart '{chart.id}': x_domain: primary requires per-layer datasets "
+                "but no datasets were resolved. Ensure each layer specifies its own query."
+            )
+        first_layer = mapped.layers[0]
+        first_dataset_name = first_layer.data_name
+        if first_dataset_name is None:
+            raise ValueError(
+                f"Chart '{chart.id}': x_domain: primary requires the first layer's "
+                "dataset to be present, but the first layer has no data_name. "
+                "Ensure the first layer's query name appears in the datasets dict."
+            )
+        first_layer_x_field = first_layer.encoding.get("x", {}).get("field")
+        if first_layer_x_field is None:
+            raise ValueError(
+                f"Chart '{chart.id}': x_domain: primary requires an x field on "
+                "the first layer's encoding, but none was resolved. "
+                "Add `x:` to the first layer or the chart level."
+            )
+
+    for layer_idx, layer in enumerate(mapped.layers):
+        layer_encoding = dict(layer.encoding)
+
+        # Combined tooltip shows all metrics at the shared x position.
+        # Only used when all layers share the same dataset.
+        use_combined = (
+            not has_datasets
+            and chart.chart_type in ("line", "area", "layered")
+            and x_field
+            and tooltip_fields
+        )
+        if use_combined:
+            layer_encoding["tooltip"] = tooltip_fields
+
+        # Inject scale.domain override on layer-0's x-encoding when x_domain is
+        # "primary". VL resolves the shared x-scale from the first mark's domain,
+        # so placing the override here anchors the axis to the primary dataset's
+        # x-values and clips secondary layers rather than extending the axis.
+        if layer_idx == 0 and first_dataset_name is not None:
+            x_enc = dict(layer_encoding.get("x", {}))
+            scale = dict(x_enc.get("scale", {}))
+            scale["domain"] = {"data": first_dataset_name, "field": first_layer_x_field}
+            x_enc["scale"] = scale
+            layer_encoding["x"] = x_enc
+
+        layer_spec: dict[str, Any] = {
+            "mark": dict(layer.mark),
+            "encoding": layer_encoding,
+        }
+
+        if layer.transform:
+            layer_spec["transform"] = [dict(t) for t in layer.transform]
+
+        # Per-layer data reference for multi-query layered charts. Inline
+        # ``layer.data`` (used by the zero/top-rule layers to halt parent
+        # data iteration) takes precedence — a layer that ships its own
+        # values shouldn't also pull from a named dataset.
+        if layer.data is not None:
+            layer_spec["data"] = dict(layer.data)
+        elif layer.data_name is not None:
+            layer_spec["data"] = {"name": layer.data_name}
+
+        spec["layer"].append(layer_spec)
+
+    if mapped.derived_resolve:
+        spec["resolve"] = mapped.derived_resolve
+
+    set_chart_title(spec, chart.title, chart.subtitle, style=chart.resolved_style)
+
+    return spec
+
+
+def _generate_histogram_spec(
+    mapped: MappedChart,
+    chart: ResolvedChart,
+    data: list[dict[str, Any]],
+    width: float | None = None,
+    height: float | None = None,
+) -> dict[str, Any]:
+    """Assemble histogram spec from profile-mapped mark and encoding."""
+    data = normalize_data_types(data)
+
+    spec = new_chart_spec(data, mark=mapped.mark)
+    set_chart_dimensions(spec, width, height, min_height=100)
+    spec["encoding"] = dict(mapped.encoding)
+
+    set_chart_title(spec, chart.title, chart.subtitle, style=chart.resolved_style)
+    return spec
+
+
+def _generate_arc_spec(
+    mapped: MappedChart,
+    chart: ResolvedChart,
+    data: list[dict[str, Any]],
+    width: float | None = None,
+    height: float | None = None,
+) -> dict[str, Any]:
+    """Assemble arc/pie spec from profile-mapped mark and encoding."""
+    if mapped.layers:
+        # Donut center total (and future per-slice labels) emit arc + text
+        # layers; defer to the shared layered assembler. ``min_height=100``
+        # matches the non-layered arc path's contract (small donuts otherwise
+        # collapse into unreadable blobs).
+        return _generate_layered_spec(
+            mapped, chart, data, width, height, min_height=100
+        )
+
+    data = normalize_data_types(data)
+
+    spec = new_chart_spec(data, mark=mapped.mark)
+    set_chart_dimensions(spec, width, height, min_height=100)
+    spec["encoding"] = dict(mapped.encoding)
+
+    set_chart_title(spec, chart.title, chart.subtitle, style=chart.resolved_style)
+    return spec
+
+
+def _generate_rect_spec(
+    mapped: MappedChart,
+    chart: ResolvedChart,
+    data: list[dict[str, Any]],
+    width: float | None = None,
+    height: float | None = None,
+) -> dict[str, Any]:
+    """Assemble rect/square/heatmap spec from profile-mapped mark and encoding."""
+    data = normalize_data_types(data)
+
+    spec = new_chart_spec(data, mark=mapped.mark)
+    set_chart_dimensions(spec, width, height, min_width=150, min_height=100)
+    spec["encoding"] = dict(mapped.encoding)
+
+    set_chart_title(spec, chart.title, chart.subtitle, style=chart.resolved_style)
+    return spec
+
+
+def _generate_boxplot_spec(
+    mapped: MappedChart,
+    chart: ResolvedChart,
+    data: list[dict[str, Any]],
+    width: float | None = None,
+    height: float | None = None,
+) -> dict[str, Any]:
+    """Assemble boxplot spec from profile-mapped mark and encoding."""
+    data = normalize_data_types(data)
+
+    spec = new_chart_spec(data, mark=mapped.mark)
+    set_chart_dimensions(spec, width, height)
+    spec["encoding"] = dict(mapped.encoding)
+
+    set_chart_title(spec, chart.title, chart.subtitle, style=chart.resolved_style)
+    return spec
+
+
+def _generate_error_spec(
+    mapped: MappedChart,
+    chart: ResolvedChart,
+    data: list[dict[str, Any]],
+    width: float | None = None,
+    height: float | None = None,
+) -> dict[str, Any]:
+    """Assemble errorbar/errorband spec from profile-mapped mark and encoding."""
+    data = normalize_data_types(data)
+
+    spec = new_chart_spec(data, mark=mapped.mark)
+    set_chart_dimensions(spec, width, height)
+    spec["encoding"] = dict(mapped.encoding)
+
+    set_chart_title(spec, chart.title, chart.subtitle, style=chart.resolved_style)
+    return spec

dataface/core/render/chart/vl_field_maps.py

@@ -0,0 +1,346 @@
+"""Vega-Lite field name maps and helper for snake_case → camelCase mapping."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel
+
+SCALE_FIELD_MAP: dict[str, str] = {
+    # ``paddingInner`` / ``paddingOuter`` are the encoding-level VL field names
+    # for band-scale gutter and edge padding. The ``bandPaddingInner`` /
+    # ``bandPaddingOuter`` variants only work at the global config level
+    # (``config.scale.bandPaddingInner``) — they are silently ignored when
+    # placed on ``encoding.{x,y}.scale``.
+    "band_padding_inner": "paddingInner",
+    "band_padding_outer": "paddingOuter",
+    "point_padding": "pointPadding",
+    "rect_band_padding_inner": "rectBandPaddingInner",
+    "round": "round",
+    "zero": "zero",
+    "clamp": "clamp",
+    "continuous_padding": "continuousPadding",
+    "quantile_count": "quantileCount",
+    "quantize_count": "quantizeCount",
+    "use_unaggregated_domain": "useUnaggregatedDomain",
+    "x_reverse": "xReverse",
+    "type": "type",
+}
+
+# Encoding-level-only scale fields applied to encoding.x.scale / encoding.y.scale.
+SCALE_ENCODING_FIELD_MAP: dict[str, str] = {
+    "domain": "domain",
+    "nice": "nice",
+    # Unified shorthand. VL dispatches based on scale type (bandPaddingOuter,
+    # pointPadding, continuousPadding). Encoding-level only.
+    "padding": "padding",
+}
+
+VIEW_FIELD_MAP: dict[str, str] = {
+    "fill": "fill",
+    "stroke": "stroke",
+    "stroke_width": "strokeWidth",
+    "continuous_width": "continuousWidth",
+    "continuous_height": "continuousHeight",
+    "corner_radius": "cornerRadius",
+}
+
+
+from typing import Any
+
+
+def _n(obj: Any, *path: str) -> Any:
+    """Get nested attribute, returning None if any level is None or missing."""
+    for attr in path:
+        if obj is None:
+            return None
+        obj = getattr(obj, attr, None)
+    return obj
+
+
+def _dasharray_to_vl(dasharray: str) -> list[float]:
+    """Convert SVG stroke-dasharray string (e.g. '4 2') to VL strokeDash number array."""
+    return [float(x) for x in dasharray.split()]
+
+
+def _stroke_to_vl(stroke: Any) -> dict[str, Any]:
+    """Map a StrokeStyle → VL stroke properties (non-None fields only).
+
+    Single canonical primitive shared by all per-mark mappers and halo
+    path builders so new StrokeStyle fields automatically flow everywhere.
+    """
+    d: dict[str, Any] = {}
+    if (v := _n(stroke, "color")) is not None:
+        d["stroke"] = v
+    if (v := _n(stroke, "width")) is not None:
+        d["strokeWidth"] = v
+    if (v := _n(stroke, "cap")) is not None:
+        d["strokeCap"] = v
+    if (v := _n(stroke, "join")) is not None:
+        d["strokeJoin"] = v
+    if (v := _n(stroke, "dasharray")) is not None:
+        d["strokeDash"] = _dasharray_to_vl(v)
+    return d
+
+
+def axis_to_vl(axis: Any) -> dict[str, Any]:
+    """Map any axis style object → VL axis config dict (non-None fields only).
+
+    Works for AxisStyle (all fields concrete, always emitted) and
+    AxisStylePatch (skip None). Single canonical mapper for all axis
+    variants — theme global/channel/type-conditional and chart-local patches.
+    """
+    if axis is None:
+        return {}
+    d: dict[str, Any] = {}
+
+    # Label font (nested via label.font)
+    if (v := _n(axis, "label", "font", "color")) is not None:
+        d["labelColor"] = v
+    if (v := _n(axis, "label", "font", "family")) is not None:
+        d["labelFont"] = v
+    if (v := _n(axis, "label", "font", "size")) is not None:
+        d["labelFontSize"] = v
+    if (v := _n(axis, "label", "font", "weight")) is not None:
+        d["labelFontWeight"] = v
+    if (v := _n(axis, "label", "padding")) is not None:
+        d["labelPadding"] = v
+    if (v := _n(axis, "label", "max_width")) is not None:
+        d["labelLimit"] = v
+    if (v := _n(axis, "label", "angle")) is not None:
+        d["labelAngle"] = v
+    if (v := _n(axis, "label", "align")) is not None:
+        d["labelAlign"] = v
+    if (v := _n(axis, "label", "baseline")) is not None:
+        d["labelBaseline"] = v
+    # "smart" → omit labelOverlap (VL applies per-scale adaptive default).
+    # "allow" → false (no reduction; labels may overlap).
+    # "parity" / "greedy" → pass through as-is.
+    _overlap = _n(axis, "label", "overlap")
+    if _overlap == "allow":
+        d["labelOverlap"] = False
+    elif _overlap in ("parity", "greedy"):
+        d["labelOverlap"] = _overlap
+    if (v := _n(axis, "label", "separation")) is not None:
+        d["labelSeparation"] = v
+    if (v := _n(axis, "label", "visible")) is not None:
+        d["labels"] = v
+    if (v := _n(axis, "label", "expr")) is not None:
+        d["labelExpr"] = v
+    if (v := _n(axis, "label", "bound")) is not None:
+        d["labelBound"] = v
+    if (v := _n(axis, "label", "flush")) is not None:
+        d["labelFlush"] = v
+    if (v := _n(axis, "label", "offset")) is not None:
+        d["labelOffset"] = v
+    if (v := _n(axis, "label", "line_height")) is not None:
+        d["labelLineHeight"] = v
+    if (v := _n(axis, "label", "anchor")) is not None:
+        d["labelAnchor"] = v
+
+    # Title font
+    if (v := _n(axis, "title", "font", "color")) is not None:
+        d["titleColor"] = v
+    if (v := _n(axis, "title", "font", "family")) is not None:
+        d["titleFont"] = v
+    if (v := _n(axis, "title", "font", "size")) is not None:
+        d["titleFontSize"] = v
+    if (v := _n(axis, "title", "font", "weight")) is not None:
+        d["titleFontWeight"] = v
+    if (v := _n(axis, "title", "padding")) is not None:
+        d["titlePadding"] = v
+
+    # Grid
+    if (v := _n(axis, "grid", "visible")) is not None:
+        d["grid"] = v
+    if (v := _n(axis, "grid", "opacity")) is not None:
+        d["gridOpacity"] = v
+    if (v := _n(axis, "grid", "width")) is not None:
+        d["gridWidth"] = v
+    if (v := _n(axis, "grid", "color")) is not None:
+        d["gridColor"] = v
+    if (v := _n(axis, "grid", "dash")) is not None:
+        d["gridDash"] = v
+
+    # Domain
+    if (v := _n(axis, "domain", "visible")) is not None:
+        d["domain"] = v
+    if (v := _n(axis, "domain", "width")) is not None:
+        d["domainWidth"] = v
+    if (v := _n(axis, "domain", "color")) is not None:
+        d["domainColor"] = v
+
+    # Ticks
+    if (v := _n(axis, "ticks", "visible")) is not None:
+        d["ticks"] = v
+    if (v := _n(axis, "ticks", "color")) is not None:
+        d["tickColor"] = v
+    if (v := _n(axis, "ticks", "size")) is not None:
+        d["tickSize"] = v
+    if (v := _n(axis, "ticks", "width")) is not None:
+        d["tickWidth"] = v
+
+    # Flat fields
+    if (v := _n(axis, "orient")) is not None:
+        d["orient"] = v
+    if (v := _n(axis, "offset")) is not None:
+        d["offset"] = v
+    if (v := _n(axis, "band_position")) is not None:
+        d["bandPosition"] = v
+    if (v := _n(axis, "format")) is not None:
+        d["format"] = v
+    if (v := _n(axis, "values")) is not None:
+        d["values"] = v
+
+    return d
+
+
+def legend_to_vl(legend: Any) -> dict[str, Any] | None:
+    """Map any legend style object → VL legend config dict (non-None fields only).
+
+    Returns None when disable=True (VL legend: null disables the legend entirely).
+    Works for LegendStyle and LegendStylePatch.
+    """
+    if legend is None:
+        return {}
+    if _n(legend, "disable") is True:
+        return None  # VL: encoding.color.legend = null
+
+    d: dict[str, Any] = {}
+    if (v := _n(legend, "orient")) is not None:
+        d["orient"] = v
+    if (v := _n(legend, "direction")) is not None:
+        d["direction"] = v
+    if (v := _n(legend, "label", "font", "color")) is not None:
+        d["labelColor"] = v
+    if (v := _n(legend, "label", "font", "family")) is not None:
+        d["labelFont"] = v
+    if (v := _n(legend, "label", "font", "size")) is not None:
+        d["labelFontSize"] = v
+    if (v := _n(legend, "label", "font", "weight")) is not None:
+        d["labelFontWeight"] = v
+    if (v := _n(legend, "title", "font", "color")) is not None:
+        d["titleColor"] = v
+    if (v := _n(legend, "title", "font", "family")) is not None:
+        d["titleFont"] = v
+    if (v := _n(legend, "title", "font", "size")) is not None:
+        d["titleFontSize"] = v
+    if (v := _n(legend, "title", "font", "weight")) is not None:
+        d["titleFontWeight"] = v
+    return d
+
+
+# Per-type mark mappers are intentionally separate: each chart type exposes a different
+# subset of mark properties with different VL field names (e.g. bar uses
+# continuousBandSize, line uses interpolate, scatter uses size). A single generic mapper
+# would need to union all fields and conditionally skip inapplicable ones — more complex
+# with no benefit since callers always know the chart type.
+def bar_mark_to_vl(
+    bar: Any, orientation: Literal["vertical", "horizontal"]
+) -> dict[str, Any]:
+    """Map BarStyle/Patch → VL extended mark dict (non-None only).
+
+    ``orientation`` controls which dimension receives the band fraction:
+    - ``"vertical"``: ``mark.width = {"band": band_width}``  — x categorical band.
+    - ``"horizontal"``: ``mark.height = {"band": band_width}``  — y categorical band.
+    """
+    if bar is None:
+        return {}
+    d: dict[str, Any] = {}
+    if (v := _n(bar, "border", "radius")) is not None:
+        # Round only the value-end corners (top for vertical bars, right for
+        # horizontal). Rounding all four corners carves wedges out of the
+        # baseline-meeting edge that expose chart background through the bold
+        # zero rule.
+        d["cornerRadiusEnd"] = v
+    if (v := _n(bar, "border", "color")) is not None:
+        d["stroke"] = v
+    if (v := _n(bar, "border", "width")) is not None:
+        d["strokeWidth"] = v
+    if (v := _n(bar, "size")) is not None:
+        d["continuousBandSize"] = v
+    if (v := _n(bar, "band_width")) is not None:
+        if orientation == "horizontal":
+            d["height"] = {"band": v}
+        else:
+            d["width"] = {"band": v}
+    return d
+
+
+def _emit_point_mark(point: Any) -> dict[str, Any]:
+    """Build a VL point mark config dict from a MarkPointStyle/Patch (non-None fields only)."""
+    d: dict[str, Any] = {}
+    if (v := _n(point, "size")) is not None:
+        d["size"] = v
+    if (v := _n(point, "color")) is not None:
+        d["color"] = v
+    if (v := _n(point, "shape")) is not None:
+        d["shape"] = v
+    if (v := _n(point, "opacity")) is not None:
+        d["opacity"] = v
+    filled = _n(point, "filled")
+    if filled is not None:
+        d["filled"] = filled
+    # fill only applies when filled=false; encoding.color owns the fill channel otherwise.
+    if filled is False and (v := _n(point, "fill")) is not None:
+        d["fill"] = v
+    return d
+
+
+def line_mark_to_vl(line: Any, point: Any = None) -> dict[str, Any]:
+    """Map LineMarkStyle → VL extended mark dict (non-None only).
+
+    ``point`` is an optional PointMarkStyle; when provided and point.size > 0,
+    emits a VL point overlay on the line.
+    """
+    if line is None:
+        return {}
+    d: dict[str, Any] = _stroke_to_vl(_n(line, "stroke"))
+    if (v := _n(line, "curve")) is not None:
+        d["interpolate"] = v
+    if point is not None:
+        pt_size = _n(point, "size")
+        if pt_size is not None and pt_size > 0:
+            d["point"] = _emit_point_mark(point)
+    return d
+
+
+def area_mark_to_vl(area: Any) -> dict[str, Any]:
+    """Map AreaStyle/Patch → VL extended mark dict (non-None only)."""
+    if area is None:
+        return {}
+    d: dict[str, Any] = {}
+    if (v := _n(area, "opacity")) is not None:
+        d["opacity"] = v
+    d.update(_stroke_to_vl(_n(area, "stroke")))
+    return d
+
+
+def scatter_mark_to_vl(point: Any) -> dict[str, Any]:
+    """Map PointMarkStyle → VL extended mark dict (non-None only)."""
+    if point is None:
+        return {}
+    return _emit_point_mark(point)
+
+
+def slice_mark_to_vl(arc: Any) -> dict[str, Any]:
+    """Map SliceStyle/Patch → VL extended mark dict (non-None only)."""
+    if arc is None:
+        return {}
+    d: dict[str, Any] = {}
+    if (v := _n(arc, "gap")) is not None:
+        d["padAngle"] = v
+    if (v := _n(arc, "corner_radius")) is not None:
+        d["cornerRadius"] = v
+    d.update(_stroke_to_vl(_n(arc, "stroke")))
+    return d
+
+
+def map_fields(source: BaseModel, field_map: dict[str, str]) -> dict[str, object]:
+    """Extract non-None fields from source, mapping snake_case to camelCase."""
+    result: dict[str, object] = {}
+    for src_name, dst_name in field_map.items():
+        value = getattr(source, src_name, None)
+        if value is not None:
+            result[dst_name] = value
+    return result

dataface/core/render/chart_interactivity.py

@@ -0,0 +1,24 @@
+"""Core-owned chart hover interactivity runtime."""
+
+import json
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from dataface.core.render.script_embedding import embed_svg_script
+
+if TYPE_CHECKING:
+    from dataface.core.compile.models.style.merged import MergedStyle
+
+
+def generate_svg_chart_interactivity_script(
+    resolved_style: "MergedStyle",
+) -> str:
+    """Embed the chart hover runtime into SVG output."""
+    assert resolved_style is not None
+    font_family = str(resolved_style.font.family)
+    script_path = (
+        Path(__file__).parent / "templates" / "scripts" / "chart_interactivity.js"
+    )
+    script = script_path.read_text()
+    script = script.replace('"__DATAFACE_FONT_FAMILY__"', json.dumps(font_family))
+    return embed_svg_script(script)