dataface 0.1.2__py3-none-any.whl

dataface/core/render/chart/__init__.py

@@ -0,0 +1,27 @@
+"""Chart rendering subpackage.
+
+Contains all chart-type-specific renderers (KPI, table, spark bar),
+Vega-Lite spec generation, chart orchestration, and auto-enrichment.
+"""
+
+from dataface.core.render.chart.decisions import enrich_chart
+from dataface.core.render.chart.kpi import render_kpi_svg
+from dataface.core.render.chart.rendering import render_chart_item, render_layout_item
+from dataface.core.render.chart.spark import render_spark
+from dataface.core.render.chart.spark_bar import render_spark_bar_svg
+from dataface.core.render.chart.table import render_table_svg
+from dataface.core.render.chart.vega_lite import generate_vega_lite_spec, render_chart
+from dataface.core.render.utils import slug_to_text
+
+__all__ = [
+    "enrich_chart",
+    "generate_vega_lite_spec",
+    "render_chart",
+    "render_chart_item",
+    "render_kpi_svg",
+    "render_layout_item",
+    "render_spark",
+    "render_spark_bar_svg",
+    "render_table_svg",
+    "slug_to_text",
+]

dataface/core/render/chart/arc_attached_table.py

@@ -0,0 +1,251 @@
+"""Donut/pie attached-table trigger + series extraction.
+
+When an arc chart is too small or too crowded to carry direct labels
+cleanly, the renderer swaps to a series-keyed mini-table beneath the
+donut. The trigger is data-and-width aware: at the tiny tier we always
+attach a table; otherwise we count the wedges that would actually carry
+a label (share above WEDGE_LABEL_MIN_SHARE) and compare against a
+per-tier maximum.
+
+Decision rule (single source of truth):
+
+    visible = sum(share > 0.08 for share in shares)
+
+    if tier == "tiny":          attach table
+    elif visible == 0:          attach table  (no labels would render)
+    elif visible > tier_max:    attach table  (too many to fit cleanly)
+    else:                       direct labels with small wedges suppressed
+
+Constants are inline here — promote to theme cascade if a future ask
+demands per-theme tuning. The current numbers were locked against visual
+spike evidence (5-series narrow renders cleanly, 8 equal-mass series at
+wide overflow).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from dataface.core.compile.models.chart.authored import TableColumnConfig
+from dataface.core.compile.typography import width_tier
+
+# Wedges with share at or below this value get no direct label — the
+# wedge still renders, hover tooltip carries the value. 8% is the
+# observed danger floor: 5-6% wedges next to each other vertically
+# stack their labels at near-cardinal angles; 8% gives an honest buffer.
+WEDGE_LABEL_MIN_SHARE: float = 0.08
+
+# Per-tier ceiling on how many direct-label callouts fit comfortably
+# around the disk. Tiny is absent because tiny always uses the table.
+_TIER_MAX_VISIBLE_CALLOUTS: dict[str, int] = {
+    "narrow": 3,
+    "medium": 4,
+    "wide": 5,
+}
+
+
+def should_attach_table(width: float, shares: list[float]) -> bool:
+    """Return True when the arc chart should render as donut + attached table.
+
+    Args:
+        width: Final card pixel width the donut will be rendered into.
+        shares: Per-wedge fractional shares (each in [0, 1], normally summing
+            to 1.0). Order doesn't matter — only the count of visible
+            callouts matters for the decision.
+
+    Returns:
+        True → render donut SVG with no direct labels, plus a swatch-keyed
+        table beneath it. False → render donut SVG with direct labels for
+        wedges whose share exceeds ``WEDGE_LABEL_MIN_SHARE``.
+
+    Empty ``shares`` (data is empty or all-zero) returns False — that's
+    the placeholder case, handled by the standard renderer's existing
+    empty-data path, not by attaching a table.
+    """
+    if not shares:
+        return False
+    tier = width_tier(width)
+    if tier == "tiny":
+        return True
+    visible = sum(1 for s in shares if s > WEDGE_LABEL_MIN_SHARE)
+    if visible == 0:
+        return True
+    return visible > _TIER_MAX_VISIBLE_CALLOUTS[tier]
+
+
+# Pixel gap between donut SVG and attached table SVG. Tuned visually;
+# theme-cascadable if any future caller needs to vary it.
+_DONUT_TABLE_GAP_PX: float = 12.0
+
+
+def compute_shares(theta_field: str, data: list[dict[str, Any]]) -> list[float]:
+    """Compute per-row fractional shares from theta field values.
+
+    Returns shares as floats in [0, 1]. Returns an empty list when data
+    is empty, total is zero, or any row's theta value can't be coerced
+    to a number — callers treat all three cases as "can't decide
+    direct-vs-table from data alone" and route to the standard renderer
+    (which has its own placeholder + type-coercion handling).
+
+    Mirrors ``_augment_arc_label_data``'s tolerance for the CSV adapter
+    string-numeric shapes ("1,234"): runs ``normalize_data_types`` so a
+    row that the standard renderer would accept doesn't crash the
+    dispatcher on `float(...)`.
+    """
+    if not data:
+        return []
+    from dataface.core.render.utils import normalize_data_types
+
+    normalized = normalize_data_types(data)
+    try:
+        values = [float(row.get(theta_field, 0) or 0) for row in normalized]
+    except (TypeError, ValueError):
+        return []
+    total = sum(values)
+    if total <= 0:
+        return []
+    return [v / total for v in values]
+
+
+def compose_attached_table_svg(
+    donut_svg: str,
+    table_svg: str,
+    donut_width: float,
+    donut_height: float,
+    table_width: float,
+    table_height: float,
+    gap: float = _DONUT_TABLE_GAP_PX,
+) -> tuple[str, float, float]:
+    """Stack a donut SVG above a table SVG into a single outer SVG.
+
+    Returns ``(outer_svg, outer_width, outer_height)``. Outer width is
+    ``max(donut_width, table_width)``; outer height = donut + gap + table.
+    The donut sits at top-left (y=0); the table is **horizontally
+    centered** beneath it. Centering is the right default for the
+    donut-attached use case — the table is meant to read as a legend
+    beneath the donut, not as a full-width data block.
+    """
+    outer_w = max(donut_width, table_width)
+    outer_h = donut_height + gap + table_height
+    table_y = donut_height + gap
+    table_x = (outer_w - table_width) / 2  # centered under the donut
+    donut_x = (outer_w - donut_width) / 2  # also center the donut if narrower
+    return (
+        f'<svg xmlns="http://www.w3.org/2000/svg" '
+        f'width="{outer_w}" height="{outer_h}" '
+        f'viewBox="0 0 {outer_w} {outer_h}">'
+        f'<g transform="translate({donut_x}, 0)">{donut_svg}</g>'
+        f'<g transform="translate({table_x}, {table_y})">{table_svg}</g>'
+        f"</svg>",
+        outer_w,
+        outer_h,
+    )
+
+
+def _format_value_for_width(value: Any, value_format: Any) -> str:
+    """Render a value to the string the table will display so we can
+    measure its pixel width.
+
+    ``value_format`` is whatever the caller pulled off the chart:
+    ``None``, a d3-format string, or a ``FormatConfig`` (which may carry
+    ``prefix`` / ``suffix`` on top of a ``spec``). Width measurement
+    only needs an upper-bound string; the table renderer formats the
+    actual emitted text. Returns the empty string for None / unparseable
+    values (zero contribution to column width).
+    """
+    from dataface.core.compile.models.primitives import FormatConfig
+
+    if value is None:
+        return ""
+    try:
+        v = float(value)
+    except (TypeError, ValueError):
+        return str(value)
+
+    spec: str | None
+    prefix = ""
+    suffix = ""
+    if isinstance(value_format, FormatConfig):
+        spec = value_format.spec
+        prefix = value_format.prefix or ""
+        suffix = value_format.suffix or ""
+    elif isinstance(value_format, str):
+        spec = value_format
+    else:
+        spec = None
+
+    # Mirror a few common d3 specs for width approximation. Unknown
+    # specs fall back to integer-with-commas; the actual rendered text
+    # is the table renderer's job.
+    if spec == "$,.0f":
+        body = f"${v:,.0f}"
+    elif spec == ",.0f" or spec is None:
+        body = f"{v:,.0f}"
+    elif spec == ".0%":
+        body = f"{int(round(v * 100))}%"
+    else:
+        body = f"{v:,.0f}"
+    return f"{prefix}{body}{suffix}"
+
+
+def build_attached_table_columns(
+    rows: list[dict[str, Any]],
+    *,
+    value_format: Any,
+    font_size: float,
+    font_family: str,
+    cell_pad: int = 6,
+) -> tuple[dict[str, TableColumnConfig], float]:
+    """Build per-column ``TableColumnConfig`` objects for the attached table
+    plus the total table width (sum of column widths).
+
+    Sizes each column via the same font measurer the table renderer
+    uses, threaded the same ``font_size`` and ``font_family`` the table
+    will paint with. Caller pulls both off the resolved table style
+    (``tc.font.size`` / ``tc.font.family``) so a theme that retunes
+    table type doesn't desync width-sizing from rendering.
+
+    ``value_format`` is the chart's format hint (``str``, ``FormatConfig``,
+    or ``None``); accepted as-is and passed through to
+    ``TableColumnConfig.format``.
+    """
+    from dataface.core.render.font_measurement import get_font_measurer
+
+    if not rows:
+        # Empty case shouldn't actually fire (caller's trigger gate
+        # rejects empty-shares before we get here) but return a sane
+        # default so misuse fails loudly rather than panics.
+        return ({}, 0.0)
+
+    measurer = get_font_measurer(font_family)
+
+    def _col_width(strings: list[str], floor: int) -> int:
+        widest = max(
+            (measurer.measure(s, font_size) for s in strings),
+            default=0,
+        )
+        # 3px buffer caps measurer rounding so a value that measures
+        # 25.6px doesn't end up in a 25px column that would clip it.
+        return max(floor, int(widest) + cell_pad * 2 + 3)
+
+    swatch_w = 24
+    share_strings = [str(r.get("share", "")) for r in rows]
+    share_w = _col_width(share_strings, floor=36)
+    name_strings = [str(r.get("name", "")) for r in rows]
+    name_w = _col_width(name_strings, floor=60)
+    value_strings = [
+        _format_value_for_width(r.get("value"), value_format) for r in rows
+    ]
+    value_w = _col_width(value_strings, floor=50)
+
+    columns = {
+        "swatch": TableColumnConfig(swatch=True, width=swatch_w),
+        "share": TableColumnConfig(align="right", width=share_w),
+        "name": TableColumnConfig(width=name_w),
+        "value": TableColumnConfig(
+            format=value_format,
+            align="right",
+            width=value_w,
+        ),
+    }
+    return columns, float(swatch_w + share_w + name_w + value_w)

dataface/core/render/chart/artifacts.py

@@ -0,0 +1,16 @@
+"""Render output types for the chart render pipeline."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal
+
+ArtifactKind = Literal["vega_spec", "svg", "json"]
+
+
+@dataclass(frozen=True)
+class RenderArtifact:
+    """Chart-domain render output before transport conversion."""
+
+    kind: ArtifactKind
+    payload: dict[str, Any] | str

dataface/core/render/chart/callout.py

@@ -0,0 +1,225 @@
+"""Wrapped SVG renderer for callout charts (type: callout)."""
+
+from __future__ import annotations
+
+import html
+
+from dataface.core.compile.chart_resolved import ResolvedChart
+from dataface.core.compile.config import get_config
+from dataface.core.compile.models.style.merged import (
+    MergedStyle,
+    resolve_style,
+)
+from dataface.core.compile.palette import color as resolve_palette_color
+from dataface.core.render.font_measurement import get_font_measurer
+from mdsvg.fonts import wrap_text_precise
+
+_MIN_HEIGHT = 60.0
+_LINE_HEIGHT_RATIO = 1.35
+# Keep cards readable without letting a long stack trace consume the full board.
+_MAX_MESSAGE_LINES = 12
+
+
+def render_callout_svg(
+    *,
+    chart_id: str,
+    message: str,
+    width: float,
+    height: float | None = None,
+    title: str | None = None,
+    resolved_style: MergedStyle | None = None,
+    code: str | None = None,
+    hint: str | None = None,
+    doc_url: str | None = None,
+    tone: str = "negative",
+) -> str:
+    """Render a wrapped inline callout card as SVG.
+
+    Colors are resolved from ``{tone}.*`` palette roles (bg, border, solid,
+    text) at render time so each tone gets the correct theme-defined semantic
+    color without storing per-tone style copies.
+    """
+    style = resolved_style or resolve_style(get_config().style)
+    inline = style.charts.callout
+    padding = inline.padding
+    section_gap = inline.section_gap
+
+    background = resolve_palette_color(f"{tone}.bg")
+    border_color = resolve_palette_color(f"{tone}.border")
+    title_color = resolve_palette_color(f"{tone}.solid")
+    message_color = resolve_palette_color(f"{tone}.text")
+
+    w = max(width, 120.0)
+    content_width = max(w - (2 * padding), 40.0)
+
+    title_rf = inline.title.font  # MergedFontStyle — all fields concrete
+    message_rf = inline.message.font
+    title_text = title or f"Callout: {chart_id}"
+
+    title_measurer = get_font_measurer(title_rf.family)
+    message_measurer = get_font_measurer(message_rf.family)
+    title_lines = wrap_text_precise(
+        title_text,
+        content_width,
+        title_rf.size,
+        title_measurer,
+        max_lines=3,
+        ellipsis=True,
+    ) or [title_text]
+    message_lines = wrap_text_precise(
+        message,
+        content_width,
+        message_rf.size,
+        message_measurer,
+        max_lines=_MAX_MESSAGE_LINES,
+        ellipsis=True,
+    ) or [message]
+
+    # Optional extra lines: hint and doc_url
+    hint_lines: list[str] = []
+    if hint:
+        hint_lines = wrap_text_precise(
+            hint,
+            content_width,
+            message_rf.size,
+            message_measurer,
+            max_lines=3,
+            ellipsis=True,
+        ) or [hint]
+
+    doc_url_lines: list[str] = []
+    if doc_url:
+        doc_url_lines = wrap_text_precise(
+            doc_url,
+            content_width,
+            message_rf.size * 0.85,
+            message_measurer,
+            max_lines=4,
+            ellipsis=True,
+        ) or [doc_url]
+
+    title_line_height = title_rf.size * _LINE_HEIGHT_RATIO
+    message_line_height = message_rf.size * _LINE_HEIGHT_RATIO
+    doc_url_line_height = message_rf.size * 0.85 * _LINE_HEIGHT_RATIO
+
+    # Code badge height (small monospace text above title)
+    code_badge_height = (title_rf.size * 0.75 * _LINE_HEIGHT_RATIO) if code else 0.0
+    title_block_height = len(title_lines) * title_line_height
+    message_block_height = len(message_lines) * message_line_height
+    hint_block_height = len(hint_lines) * message_line_height if hint_lines else 0.0
+    doc_url_block_height = (
+        len(doc_url_lines) * doc_url_line_height if doc_url_lines else 0.0
+    )
+
+    natural_height = (
+        (2 * padding)
+        + code_badge_height
+        + (section_gap if code else 0.0)
+        + title_block_height
+        + section_gap
+        + message_block_height
+        + (section_gap + hint_block_height if hint_lines else 0.0)
+        + (section_gap + doc_url_block_height if doc_url_lines else 0.0)
+    )
+    h = max(_MIN_HEIGHT, height or 0.0, natural_height)
+
+    current_y = padding
+
+    # Code badge
+    code_svg = ""
+    if code:
+        code_font_size = title_rf.size * 0.75
+        code_y = current_y + code_font_size
+        code_svg = (
+            f'<text x="{padding}" y="{code_y}" '
+            f'font-size="{code_font_size}" font-weight="normal" '
+            f'font-family="monospace" '
+            f'fill="{message_color}">{html.escape(code)}</text>'
+        )
+        current_y += code_badge_height + section_gap
+
+    title_start_y = current_y + title_rf.size + inline.title.y_offset
+    current_y = (
+        title_start_y
+        + title_block_height
+        - title_rf.size
+        + section_gap
+        + inline.message.y_offset
+    )
+    message_start_y = current_y
+
+    title_lines_svg = "".join(
+        f'<text x="{padding}" y="{title_start_y + (index * title_line_height)}" '
+        f'font-size="{title_rf.size}" font-weight="{title_rf.weight}" '
+        f'font-family="{html.escape(title_rf.family)}" '
+        f'fill="{title_color}">{html.escape(line)}</text>'
+        for index, line in enumerate(title_lines)
+    )
+    message_lines_svg = "".join(
+        f'<text x="{padding}" y="{message_start_y + (index * message_line_height)}" '
+        f'font-size="{message_rf.size}" font-weight="{message_rf.weight}" '
+        f'font-family="{html.escape(message_rf.family)}" '
+        f'fill="{message_color}">{html.escape(line)}</text>'
+        for index, line in enumerate(message_lines)
+    )
+
+    hint_svg = ""
+    if hint_lines:
+        hint_start_y = message_start_y + message_block_height + section_gap
+        hint_svg = "".join(
+            f'<text x="{padding}" y="{hint_start_y + (i * message_line_height)}" '
+            f'font-size="{message_rf.size}" font-weight="normal" font-style="italic" '
+            f'font-family="{html.escape(message_rf.family)}" '
+            f'fill="{message_color}">{html.escape(line)}</text>'
+            for i, line in enumerate(hint_lines)
+        )
+
+    doc_svg = ""
+    if doc_url_lines:
+        doc_url_font_size = message_rf.size * 0.85
+        prev_height = message_block_height + (
+            section_gap + hint_block_height if hint_lines else 0.0
+        )
+        doc_start_y = message_start_y + prev_height + section_gap
+        doc_svg = "".join(
+            f'<text x="{padding}" y="{doc_start_y + (i * doc_url_line_height)}" '
+            f'font-size="{doc_url_font_size}" font-weight="normal" '
+            f'font-family="{html.escape(message_rf.family)}" '
+            f'fill="{message_color}">{html.escape(line)}</text>'
+            for i, line in enumerate(doc_url_lines)
+        )
+
+    return (
+        f'<svg xmlns="http://www.w3.org/2000/svg" class="dft-chart-callout" width="{w}" height="{h}" viewBox="0 0 {w} {h}">'
+        f'<rect x="0" y="0" width="{w}" height="{h}" '
+        f'fill="{background}" stroke="{border_color}" '
+        f'stroke-width="{inline.border.width}" rx="{inline.border.radius}"/>'
+        f"{code_svg}{title_lines_svg}{message_lines_svg}{hint_svg}{doc_svg}</svg>"
+    )
+
+
+def render_callout_chart_svg(
+    chart: ResolvedChart,
+    data: list[dict[str, object]],
+    width: float | None = None,
+    height: float | None = None,
+    is_placeholder: bool = False,
+    *,
+    resolved_style: MergedStyle | None = None,
+    face_level: int = 1,
+) -> str:
+    """Render an authored ``type: callout`` chart."""
+    _ = data, is_placeholder, face_level
+    chart_id = chart.id
+    tone = chart.resolved_style.callout.tone or "negative"
+    title = chart.title or f"Callout: {chart_id}"
+    assert chart.message, "callout charts require a message"
+    return render_callout_svg(
+        chart_id=chart_id,
+        message=chart.message,
+        width=width or 320.0,
+        height=height,
+        title=title,
+        resolved_style=resolved_style,
+        tone=tone,
+    )