dataface 0.1.2__py3-none-any.whl

dataface/core/render/chart/title_overflow.py

@@ -0,0 +1,157 @@
+"""Shared chart title overflow helpers."""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Literal
+
+from dataface.core.render.font_measurement import get_font_measurer
+from mdsvg.fonts import truncate_text_precise, wrap_text_precise
+
+TitleOverflowMode = Literal["clip", "truncate", "wrap-two", "wrap"]
+DEFAULT_TITLE_OVERFLOW: TitleOverflowMode = "wrap-two"
+
+# Match the outer Vega chart-group translate, e.g. translate(20,53)
+_MAIN_GROUP_X_RE = re.compile(
+    r'<g fill="none" stroke-miterlimit="10" transform="translate\(([0-9.]+),'
+)
+# Match the title inner-group translate, e.g. translate(-71.21,-48)
+_TITLE_GROUP_RE = re.compile(
+    r'(class="mark-group role-title"><g transform="translate\()(-?[0-9.]+)(,)'
+)
+
+
+def resolve_title_overflow(title_style: Any | None) -> TitleOverflowMode:
+    """Return the effective title overflow mode."""
+    raw = getattr(title_style, "overflow", None) if title_style is not None else None
+    if raw in {"clip", "truncate", "wrap-two", "wrap"}:
+        return raw
+    return DEFAULT_TITLE_OVERFLOW
+
+
+def compute_title_limit(width: Any, padding: Any) -> int | None:
+    """Return the usable title width after horizontal padding."""
+    if not isinstance(width, (int, float)) or width <= 0:
+        return None
+
+    left = right = 0.0
+    if isinstance(padding, dict):
+        left = float(padding.get("left", 0) or 0)
+        right = float(padding.get("right", 0) or 0)
+    elif isinstance(padding, (int, float)):
+        left = right = float(padding)
+
+    limit = int(width - left - right)
+    return max(limit, 1) if limit > 0 else None
+
+
+def prepare_title_text(
+    text: str,
+    *,
+    overflow: TitleOverflowMode,
+    limit: int | None,
+    font_size: float,
+    font_family: str | None = None,
+) -> str:
+    """Return title text with explicit line breaks/clipping applied."""
+    if not text or limit is None:
+        return text
+
+    measurer = get_font_measurer(font_family)
+    if overflow == "clip":
+        return truncate_text_precise(
+            text,
+            limit,
+            font_size,
+            measurer,
+            ellipsis=False,
+        )
+    if overflow == "truncate":
+        return truncate_text_precise(
+            text,
+            limit,
+            font_size,
+            measurer,
+            ellipsis=True,
+        )
+    if overflow == "wrap":
+        return "\n".join(
+            wrap_text_precise(
+                text,
+                limit,
+                font_size,
+                measurer,
+            )
+        )
+    return "\n".join(
+        wrap_text_precise(
+            text,
+            limit,
+            font_size,
+            measurer,
+            max_lines=2,
+            ellipsis=True,
+        )
+    )
+
+
+def apply_title_overflow_to_spec(
+    spec: dict[str, Any],
+    title_style: Any | None,
+    *,
+    title_font_size: float | None = None,
+    title_font_family: str | None = None,
+) -> None:
+    """Apply title overflow handling to a Vega-Lite spec in place."""
+    title_block = spec.get("title")
+    if not isinstance(title_block, dict):
+        return
+
+    limit = compute_title_limit(spec.get("width"), spec.get("padding"))
+    if limit is None:
+        return
+
+    title_block["limit"] = limit
+    text = title_block.get("text")
+    if isinstance(text, str) and text:
+        style_font_size = (
+            getattr(title_style, "font_size", None) if title_style is not None else None
+        )
+        effective_font_size = float(
+            style_font_size
+            or title_font_size
+            or spec.get("config", {}).get("title", {}).get("fontSize")
+            or 18
+        )
+        result = prepare_title_text(
+            text,
+            overflow=resolve_title_overflow(title_style),
+            limit=limit,
+            font_size=effective_font_size,
+            font_family=title_font_family,
+        )
+        lines = result.split("\n")
+        title_block["text"] = lines if len(lines) > 1 else result
+
+
+def fix_title_alignment(svg: str, padding_left: float) -> str:
+    """Move the Vega-rendered title right to ``padding_left`` when leftward drift occurs."""
+    main_match = _MAIN_GROUP_X_RE.search(svg)
+    if not main_match:
+        return svg
+
+    title_match = _TITLE_GROUP_RE.search(svg)
+    if not title_match:
+        return svg
+
+    main_x = float(main_match.group(1))
+    title_x = float(title_match.group(2))
+    title_svg_x = main_x + title_x
+
+    if title_svg_x >= padding_left:
+        return svg
+
+    new_title_x = padding_left - main_x
+    old = title_match.group(1) + title_match.group(2) + title_match.group(3)
+    new = title_match.group(1) + f"{new_title_x:.2f}" + title_match.group(3)
+    return svg.replace(old, new, 1)

dataface/core/render/chart/type_inference.py

@@ -0,0 +1,122 @@
+"""Shared helpers for Vega-Lite type inference from query result data."""
+
+from __future__ import annotations
+
+import datetime as dt
+import re
+from typing import Any
+
+DATE_LIKE_PATTERNS = [
+    r"^\d{4}-Q[1-4]$",
+    r"^Q[1-4]\s*\d{4}$",
+    r"^\d{4}Q[1-4]$",
+    r"^\d{4}-\d{2}$",
+    r"^(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\s+\d{4}$",
+    r"^FY\d{4}$",
+    r"^H[12]\s*\d{4}$",
+    r"^\d{4}-H[12]$",
+    r"^W(?:eek\s*)?\d{1,2}\s*\d{4}$",
+    r"^\d{4}-W\d{2}$",  # ISO 8601 week: 2024-W01
+    r"^\d{2}/\d{4}$",  # MM/YYYY: 01/2024
+    r"^\d{2}/\d{2}/\d{4}$",  # MM/DD/YYYY: 01/15/2024
+    r"^(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\s+\d{1,2},?\s+\d{4}$",  # Mon DD, YYYY
+    r"^\d{4}-\d{2}-\d{2}$",  # YYYY-MM-DD: 2024-01-15
+    r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?$",  # ISO 8601 naive timestamp: 2024-01-15T13:30:00
+]
+DATE_LIKE_REGEXES = [
+    re.compile(pattern, re.IGNORECASE) for pattern in DATE_LIKE_PATTERNS
+]
+
+
+def is_date_like_string(value: str) -> bool:
+    """Return True when a string looks like an ordered date bucket."""
+    return any(pattern.match(value) for pattern in DATE_LIKE_REGEXES)
+
+
+# Year-leading patterns whose lexicographic ascending order equals chronological
+# order. Safe to use as a window-sort field for x-cell sampling.
+# Patterns NOT listed here (e.g. "Jan 2024", "01/2024", "Q1 2024") sort
+# lex-incorrectly and must NOT trigger sampling — wrong cells would be selected.
+# Every entry must also appear in DATE_LIKE_PATTERNS (the module-level assert
+# below enforces this so the two lists cannot silently drift).
+_LEX_SORTABLE_DATE_LIKE_PATTERNS = [
+    r"^\d{4}-Q[1-4]$",  # 2024-Q1 lex == chron
+    r"^\d{4}Q[1-4]$",  # 2024Q1 lex == chron
+    r"^\d{4}-\d{2}$",  # 2024-01 lex == chron
+    r"^FY\d{4}$",  # FY2024 lex == chron
+    r"^\d{4}-H[12]$",  # 2024-H1 lex == chron
+    r"^\d{4}-W\d{2}$",  # 2024-W01 lex == chron (ISO 8601 week)
+    r"^\d{4}-\d{2}-\d{2}$",  # 2024-01-15 lex == chron
+    r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?$",  # naive ISO timestamp lex == chron (no tz suffix)
+]
+# Guard against drift: every lex-sortable pattern must be a subset of the
+# full date-like list so a future edit to DATE_LIKE_PATTERNS can't leave
+# is_lex_sortable_date_like silently matching patterns that were tightened.
+# Use RuntimeError (not assert) so the guard survives python -O.
+if not set(_LEX_SORTABLE_DATE_LIKE_PATTERNS) <= set(DATE_LIKE_PATTERNS):
+    raise RuntimeError(
+        "_LEX_SORTABLE_DATE_LIKE_PATTERNS contains patterns not in DATE_LIKE_PATTERNS; "
+        "update or remove the stale entries"
+    )
+_LEX_SORTABLE_DATE_LIKE_REGEXES = [
+    re.compile(p, re.IGNORECASE) for p in _LEX_SORTABLE_DATE_LIKE_PATTERNS
+]
+
+
+def is_lex_sortable_date_like(value: str) -> bool:
+    """Return True when the string is a date-like bucket whose lex sort is chronological.
+
+    Only year-leading ISO-prefix patterns qualify. Month-name, MM/YYYY, and
+    quarter-first patterns sort incorrectly under string comparison and must
+    not be used to drive the sampling window's ascending sort.
+    """
+    return any(p.match(value) for p in _LEX_SORTABLE_DATE_LIKE_REGEXES)
+
+
+def infer_vega_type_from_data(data: list[dict[str, Any]], field: str) -> str:
+    """Infer the most appropriate Vega-Lite type for a field."""
+    if not data or field not in data[0]:
+        return "nominal"
+
+    sample_values = [
+        row.get(field) for row in data[: min(10, len(data))] if field in row
+    ]
+    if not sample_values:
+        return "nominal"
+
+    all_numeric = True
+    all_temporal = True
+    all_date_like = True
+
+    for value in sample_values:
+        if value is None:
+            continue
+        if not isinstance(value, (int, float)):
+            all_numeric = False
+        if isinstance(value, (dt.date, dt.datetime)):
+            # date/datetime objects are always temporal; date_like too
+            pass
+        elif isinstance(value, str):
+            # Require an actual date-like structure: YYYY-MM-DD, YYYY/MM/DD,
+            # MM/DD/YYYY, or ISO timestamps. The old check (`count("-") >= 2`)
+            # was too broad and misidentified strings like "claude-opus-4-7"
+            # (3 hyphens, no digits in date positions) as temporal.
+            is_standard_date = bool(
+                re.match(r"^\d{4}[-/]\d{2}[-/]\d{2}(T[\d:.].*)?$", value)
+                or re.match(r"^\d{2}/\d{2}/\d{4}$", value)
+            )
+            if not is_standard_date:
+                all_temporal = False
+            if not is_standard_date and not is_date_like_string(value):
+                all_date_like = False
+        else:
+            all_temporal = False
+            all_date_like = False
+
+    if all_numeric:
+        return "quantitative"
+    if all_temporal:
+        return "temporal"
+    if all_date_like:
+        return "ordinal"
+    return "nominal"

dataface/core/render/chart/validation.py

@@ -0,0 +1,99 @@
+"""Chart data validation helpers.
+
+Keeps data-shape policy separate from mechanical spec assembly.
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+from typing import Any
+
+from dataface.core.compile.chart_resolved import ResolvedChart, effective_color_field
+from dataface.core.errors.codes_render import DF_RENDER_BAR_DUPLICATE_ROWS
+from dataface.core.render.chart.type_inference import infer_vega_type_from_data
+from dataface.core.render.errors import ChartDataError
+
+
+def _format_duplicate_key(fields: list[str], key: tuple[Any, ...]) -> str:
+    parts = [f"{field}={value!r}" for field, value in zip(fields, key, strict=False)]
+    return ", ".join(parts)
+
+
+def _plot_key_fields(chart: ResolvedChart, data: list[dict[str, Any]]) -> list[str]:
+    chart_type = chart.chart_type
+    color = effective_color_field(chart)
+
+    if chart_type == "bar":
+        x_field = chart.x
+        y_field = chart.y if isinstance(chart.y, str) else None
+        if not x_field or not y_field:
+            return []
+
+        x_type = infer_vega_type_from_data(data, x_field)
+        y_type = infer_vega_type_from_data(data, y_field)
+        if x_type in {"nominal", "ordinal"} and y_type == "quantitative":
+            fields = [x_field]
+        elif y_type in {"nominal", "ordinal"} and x_type == "quantitative":
+            fields = [y_field]
+        else:
+            return []
+
+        if color:
+            fields.append(color)
+        return fields
+
+    if chart_type in {"line", "area"}:
+        x_field = chart.x
+        y_field = chart.y if isinstance(chart.y, str) else None
+        if not x_field or not y_field:
+            return []
+        if infer_vega_type_from_data(data, y_field) != "quantitative":
+            return []
+
+        fields = [x_field]
+        for series_field in (color, chart.shape):
+            if series_field:
+                fields.append(series_field)
+        return fields
+
+    if chart_type in {"arc", "pie"}:
+        return [color] if color else []
+
+    if chart_type in {"rect", "square", "heatmap"}:
+        x_field = chart.x
+        y_field = chart.y if isinstance(chart.y, str) else None
+        if x_field and y_field:
+            return [x_field, y_field]
+
+    return []
+
+
+def validate_preaggregated_data(
+    chart: ResolvedChart,
+    data: list[dict[str, Any]],
+) -> None:
+    """Reject raw detail rows when a chart expects one value per plotted key."""
+    if not data:
+        return
+
+    key_fields = _plot_key_fields(chart, data)
+    if not key_fields:
+        return
+
+    counts = Counter(tuple(row.get(field) for field in key_fields) for row in data)
+    duplicate_keys = [key for key, count in counts.items() if count > 1]
+    if not duplicate_keys:
+        return
+
+    duplicate_preview = "; ".join(
+        _format_duplicate_key(key_fields, key) for key in duplicate_keys[:3]
+    )
+    chart_id = chart.id or "unknown"
+    field_list = ", ".join(key_fields)
+    raise ChartDataError.from_code(
+        DF_RENDER_BAR_DUPLICATE_ROWS,
+        chart_type=chart.chart_type.title(),
+        chart_id=chart_id,
+        field_list=field_list,
+        duplicate_preview=duplicate_preview,
+    )

dataface/core/render/chart/vega_lite.py

@@ -0,0 +1,125 @@
+"""Public chart rendering entrypoints."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from dataface.core.compile.models.style.merged import MergedStyle
+
+from dataface.core.compile.chart_resolved import ResolvedChart
+from dataface.core.compile.models.chart.compiled import (
+    Chart,
+)
+from dataface.core.render.chart.pipeline import resolve_chart
+from dataface.core.render.chart.renderers import RendererRegistry, build_chart_json
+from dataface.core.render.chart.standard_renderer import render_standard_vega_spec
+from dataface.core.render.converters.chart import render_chart_artifact
+
+renderer_registry = RendererRegistry()
+
+
+def generate_vega_lite_spec(
+    chart: Chart | ResolvedChart | Any,
+    data: list[dict[str, Any]],
+    width: float | None = None,
+    height: float | None = None,
+    theme: str | None = None,
+    resolved_style: MergedStyle | None = None,
+) -> dict[str, Any]:
+    """Generate a Vega-Lite spec for charts that render as Vega-Lite."""
+    # Synthesise a default at the public-API boundary so callers that don't
+    # have a face-level MergedStyle (tests, CLI tools) still get a valid spec.
+    # Geo/map chart types require a concrete board_style for stroke/projection
+    # reads; this resolves to the compiled default when the caller omits it.
+    if resolved_style is None:
+        from dataface.core.compile.config import get_config
+        from dataface.core.compile.models.style.merged import resolve_style as _resolve
+
+        resolved_style = _resolve(get_config().style)
+    resolved_chart = (
+        chart
+        if isinstance(chart, ResolvedChart)
+        else resolve_chart(chart, data, board_style=resolved_style)
+    )
+    if resolved_chart.chart_type == "table":
+        return {"data": {"values": data}}
+    if resolved_chart.renderer_family == "svg":
+        # KPI / table / spark_bar / error are custom-SVG; they have no
+        # Vega-Lite spec equivalent. Callers asking for a VL spec on these
+        # types are almost always confused — fail loudly instead of returning
+        # a partial spec.
+        raise ValueError(
+            f"Chart type '{resolved_chart.chart_type}' does not render to a Vega-Lite spec"
+        )
+    return render_standard_vega_spec(
+        resolved_chart,
+        data,
+        width=width,
+        height=height,
+        theme=theme,
+        resolved_style=resolved_style,
+    )
+
+
+def render_chart(
+    chart: Chart | ResolvedChart | Any,
+    data: list[dict[str, Any]],
+    format: str = "json",
+    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,
+) -> str:
+    """Render a chart to JSON, SVG, PNG, or PDF."""
+    resolved_chart = (
+        chart
+        if isinstance(chart, ResolvedChart)
+        else resolve_chart(chart, data, board_style=resolved_style)
+    )
+
+    if format == "json":
+        artifact = build_chart_json(resolved_chart, data, width=width, height=height)
+        return render_chart_artifact(
+            artifact,
+            format,
+            width=width,
+            height=height,
+            is_placeholder=is_placeholder,
+            resolved_style=resolved_style,
+        )
+
+    render_data = data
+    if is_placeholder and not data:
+        from dataface.core.render.placeholder import generate_placeholder_data
+
+        render_data = generate_placeholder_data(
+            resolved_chart.chart_type, resolved_chart
+        )
+
+    artifact = renderer_registry.render(
+        resolved_chart,
+        render_data,
+        width=width,
+        height=height,
+        is_placeholder=is_placeholder,
+        datasets=datasets,
+        variables=variables,
+        padding=padding,
+        resolved_style=resolved_style,
+        face_level=face_level,
+        effective_vega_config=effective_vega_config,
+    )
+    return render_chart_artifact(
+        artifact,
+        format,
+        width=width,
+        height=height,
+        is_placeholder=is_placeholder,
+        resolved_style=resolved_style,
+    )