dataface 0.1.2__py3-none-any.whl

dataface/core/render/chart/kpi.py

@@ -0,0 +1,916 @@
+"""Custom SVG renderer for KPI quantitative-text-object charts.
+
+KPI is rendered as a left-aligned three-element typographic object — no
+default card chrome:
+
+    1. Value     (large primary line, optionally prefixed by a glyph)
+    2. Label     (Inter 14, dark, may wrap to two lines)
+    3. Support   (optional: glyph + value + neutral trailing explainer)
+
+Layout uses fixed internal slots so that labels wrapping to two lines do
+not push neighbouring KPIs' value baselines out of alignment when several
+KPIs sit side-by-side in a row.
+"""
+
+from __future__ import annotations
+
+import html
+from dataclasses import dataclass
+from typing import Any
+
+from dataface.core.compile.colors import sanitize_color
+from dataface.core.compile.config import get_chart_rendering
+from dataface.core.compile.models.chart.authored import (
+    KpiSupportConfig,
+    coerce_numeric,
+    match_predicate,
+)
+from dataface.core.compile.models.primitives import FormatConfig
+from dataface.core.compile.models.style.compiled import (
+    VALID_FONT_WEIGHTS,
+    font_weight_as_css,
+)
+from dataface.core.compile.models.style.merged import MergedChartsStyle, MergedStyle
+from dataface.core.render.board_links import get_link_context, resolve_href
+from dataface.core.render.chart.table_support import (
+    compute_scale_domain,
+    interpolate_scale_color,
+    resolve_hinge,
+    resolve_palette_stops,
+)
+from dataface.core.render.chart.title_overflow import (
+    compute_title_limit,
+    prepare_title_text,
+    resolve_title_overflow,
+)
+from dataface.core.render.errors import ChartDataError
+from dataface.core.render.format_utils import format_kpi_parts, resolve_format
+
+_VALID_TONES = ("positive", "negative", "warning")
+
+# Typographic ratios for KPI geometry. Tuned by eye against the playground
+# specimen.
+#
+#   _CAP_HEIGHT_RATIO     — fraction of font-size occupied by lining figures.
+#                           Used for top-padding (visible whitespace from
+#                           card edge to ink) and value→label gap math.
+#   _DESCENDER_RATIO      — fraction of font-size occupied below baseline.
+#                           Used to size the support row's bottom gutter so
+#                           visible bottom padding equals ``pad.bottom``.
+#   _AFFIX_ELEVATION      — fraction of (value_font − affix_font) that the
+#                           prefix/glyph baseline rides above the value
+#                           baseline. Single coefficient; affix and glyph
+#                           pick up different absolute elevations because
+#                           their size deltas differ. The 0.37 value is
+#                           empirical (eyeballed against the specimen);
+#                           it does not correspond to a typographic
+#                           landmark like cap-top or midpoint.
+_CAP_HEIGHT_RATIO = 0.7
+_DESCENDER_RATIO = 0.2
+_AFFIX_ELEVATION = 0.37
+
+
+def _tone_color(tone: str | None, tones: Any) -> str | None:
+    """Resolve a semantic tone name to the theme-provided color.
+
+    ``tones`` is the ``KpiTonesStyle`` from ``resolved_style.kpi.tones``
+    — the renderer reads tone hexes from theme YAML rather than hardcoding
+    them so themes can rebrand the semantic vocabulary.
+    """
+    if tone is None:
+        return None
+    if tone not in _VALID_TONES:
+        raise ValueError(
+            f"KPI: unknown tone {tone!r}. Expected one of {list(_VALID_TONES)}."
+        )
+    return getattr(tones, tone)
+
+
+def _rule_output_for_channel(rule: Any, channel_name: str) -> Any:
+    """Extract the style value from a ConditionalRule for a given KPI channel."""
+    if channel_name == "background":
+        return rule.background
+    if channel_name == "color":
+        return rule.font.color if rule.font is not None else None
+    return None
+
+
+def _evaluate_channel_for_row(
+    resolved_channels: dict[str, Any],
+    channel_name: str,
+    row: dict[str, Any],
+    fallback: str | None = None,
+    col_format: str | None = None,
+) -> str | None:
+    """Evaluate a style channel against a single data row."""
+    ch = resolved_channels.get(channel_name)
+    if ch is None:
+        return fallback
+
+    if ch.mode == "literal":
+        return ch.literal_value
+
+    if ch.mode == "conditional":
+        cell_value = row.get(ch.data_field)
+        matched: Any = fallback
+        matched_any = False
+        default_rule: Any = None
+        for rule in ch.rules:
+            if rule.default is True:
+                default_rule = rule
+                continue
+            if match_predicate(rule, cell_value):
+                output = _rule_output_for_channel(rule, channel_name)
+                if output is not None:
+                    matched = output
+                matched_any = True
+        if not matched_any and default_rule is not None:
+            output = _rule_output_for_channel(default_rule, channel_name)
+            if output is not None:
+                matched = output
+        # When no threshold rule matched and a fallback gradient scale is present,
+        # evaluate the gradient — this is the "scale shows through otherwise"
+        # behaviour that mirrors Looker's threshold-over-scale priority.
+        if matched is fallback and ch.fallback_scale is not None:
+            numeric = coerce_numeric(cell_value)
+            if numeric is None:
+                return ch.fallback_scale.null_color or fallback
+            lo, hi = compute_scale_domain([row], ch.data_field, ch.fallback_scale)
+            hinge = resolve_hinge(ch.fallback_scale, lo, hi, col_format)
+            return interpolate_scale_color(
+                numeric,
+                lo,
+                hi,
+                resolve_palette_stops(ch.fallback_scale.palette),
+                hinge=hinge,
+                arm_mode=ch.fallback_scale.arm_mode,
+            )
+        return matched
+
+    if ch.mode == "gradient":
+        scale = ch.scale
+        if scale is None:
+            return fallback
+        numeric = coerce_numeric(row.get(ch.data_field))
+        if numeric is None:
+            return scale.null_color or fallback
+        lo, hi = compute_scale_domain([row], ch.data_field, scale)
+        hinge = resolve_hinge(scale, lo, hi, col_format)
+        return interpolate_scale_color(
+            numeric,
+            lo,
+            hi,
+            resolve_palette_stops(scale.palette),
+            hinge=hinge,
+            arm_mode=scale.arm_mode,
+        )
+
+    return fallback
+
+
+def _resolve_value(raw: str, row: dict[str, Any], chart_id: str) -> tuple[Any, str]:
+    """Return ``(cell_value, column_name)`` for a KPI/support block.
+
+    ``raw`` must be a column reference. Raises ``ChartDataError`` when the
+    column is not present in the query result row.
+    """
+    if raw in row:
+        return row[raw], raw
+    raise ChartDataError(
+        f"KPI value column '{raw}' not found in query result.\n"
+        "Channels are always column references; constant values come from the query.\n"
+        "For a string status value:\n"
+        f"  query:\n"
+        f"    rows:\n"
+        f'      - status: "{raw}"\n'
+        f"  value: status\n"
+        "For a numeric literal:\n"
+        "  query:\n"
+        "    rows:\n"
+        "      - count: <value>\n"
+        "  value: count",
+        chart_id=chart_id,
+    )
+
+
+def _coerce_numeric_value(cell: Any) -> float | None:
+    """Coerce ``cell`` to a float or return None if it should be rendered as a string.
+
+    ``bool`` is treated as a string-class value even though it is technically
+    an ``int`` subclass — rendering ``True`` through the narrative-notation
+    pipeline as ``1.0`` would be magic behavior the author did not ask for.
+    """
+    if cell is None or isinstance(cell, bool):
+        return None
+    if isinstance(cell, (int, float)):
+        return float(cell)
+    try:
+        return float(cell)
+    except (ValueError, TypeError):
+        # String literals like "At risk" stay as strings.
+        return None
+
+
+def _narrative_format_default(
+    format_input: str | FormatConfig | dict[str, Any] | None,
+) -> str | FormatConfig | dict[str, Any] | None:
+    """Apply KPI's narrative defaults when the author did not pick them.
+
+    KPI is a hero number that the reader pauses on, so it defaults to the
+    narrative notation register (``1.5mn``) instead of the analytic register
+    (``1.5 M``) used on axis ticks and table cells. When neither spec nor
+    notation is authored, we also default to compact SI form (``".2s"``)
+    so narrative notation actually shows up — notation alone is a no-op
+    against a non-SI spec.
+    """
+    if format_input is None:
+        return FormatConfig(spec=".2s", notation="narrative")
+    if isinstance(format_input, FormatConfig):
+        spec = format_input.spec
+        notation = format_input.notation
+        updates: dict[str, Any] = {}
+        if notation is None:
+            updates["notation"] = "narrative"
+        if spec is None and (notation is None or notation in ("narrative", "analytic")):
+            updates["spec"] = ".2s"
+        return format_input.model_copy(update=updates) if updates else format_input
+    if isinstance(format_input, dict):
+        spec = format_input.get("spec")
+        notation = format_input.get("notation")
+        updated = dict(format_input)
+        if notation is None:
+            updated["notation"] = "narrative"
+        if spec is None and (notation is None or notation in ("narrative", "analytic")):
+            updated["spec"] = ".2s"
+        return updated
+    # Plain string spec (e.g. ",.0f"): respect the author's spec; just add
+    # narrative notation so any SI-form spec they used renders narratively.
+    return FormatConfig(spec=str(format_input), notation="narrative")
+
+
+def _format_value_parts(
+    cell: Any,
+    format_input: str | FormatConfig | dict[str, Any] | None,
+    formats: dict[str, Any] | None = None,
+) -> tuple[str, str, str, bool]:
+    """Format a KPI cell into ``(prefix, number_str, suffix, is_numeric)``.
+
+    Non-numeric cells are returned as a string in ``number_str`` with empty
+    affixes — used for status-style KPIs like ``"At risk"``.
+    """
+    numeric = _coerce_numeric_value(cell)
+    if numeric is None:
+        text = "" if cell is None else str(cell)
+        return "", text, "", False
+    prefix, number_str, suffix = format_kpi_parts(numeric, format_input, formats)
+    return prefix, number_str, suffix, True
+
+
+def _resolved_charts_style_value(
+    chart: Any, fallback_style: MergedChartsStyle, key: str
+) -> Any:
+    """Read a top-level chart-style field from the merged MergedChartsStyle.
+
+    Chart-local Patch fields (background, color, title) are pre-merged into
+    ``chart.resolved_style`` by build_resolved_style. In the rare test path
+    where ``chart`` is a Mock without ``resolved_style``, fall back to the
+    ``fallback_style`` already passed to render_kpi_svg for the chart-level
+    merged style.
+    """
+    rs = getattr(chart, "resolved_style", None) or fallback_style
+    return getattr(rs, key)
+
+
+def _explicit_color_override(value: Any) -> str | None:
+    if value in (None, ""):
+        return None
+    return sanitize_color(str(value), None)
+
+
+def _resolve_value_color(
+    tone: str | None,
+    channel_color: str | None,
+    style_color: str | None,
+    tones: Any,
+    fallback: str,
+) -> str:
+    """Resolve KPI value color with deterministic precedence.
+
+    Highest → lowest:
+
+    1. ``channel_color`` — data-driven color from ``conditional_formatting``
+    2. ``tone`` — semantic shorthand (``positive`` → green, etc.)
+    3. ``style.color`` or ``style.kpi.value.font.color`` — chart-local style color
+    4. theme ``kpi.value.font.color`` — last-resort ink
+    """
+    if channel_color is not None:
+        return channel_color
+    tone_color = _tone_color(tone, tones)
+    if tone_color is not None:
+        return tone_color
+    if style_color:
+        return sanitize_color(style_color, fallback)
+    return fallback
+
+
+def _resolve_glyph_color(
+    tone: str | None,
+    tones: Any,
+    fallback: str,
+) -> str:
+    """Glyph color: tone > fallback (matches table behaviour)."""
+    tone_color = _tone_color(tone, tones)
+    if tone_color is not None:
+        return tone_color
+    return fallback
+
+
+@dataclass(frozen=True)
+class _KpiLayout:
+    """Vertical slot dimensions for the value / label / support layout."""
+
+    width: float
+    height: float
+    content_x: float
+    value_baseline: float
+    value_font: float
+    affix_font: float
+    glyph_font: float
+    value_weight: str
+    # Vertical baselines for affixes within the value line.
+    # Prefix ($ etc.) rides at cap height of the value (top-aligned).
+    # Glyph (▲▼●) sits at vertical midpoint. Suffix stays on the value baseline.
+    prefix_baseline: float
+    glyph_baseline: float
+    label_baseline_first: float
+    label_font_size: float
+    label_font_family: str
+    label_weight: str
+    label_line_height: float
+    label_lines: tuple[str, ...]
+    label_original: str
+    label_truncated: bool  # True when rendered label differs from original
+    support_baseline: float
+    support_font_size: float
+    # None = inherit body weight (browser/document default). Set explicitly
+    # (e.g. "500") to override — wired from ``kpi.font.weight``.
+    support_weight: str | None
+
+
+@dataclass(frozen=True)
+class _KpiColors:
+    """Resolved fill colors for the value / glyph / label / card surfaces."""
+
+    value_fill: str
+    glyph_fill: str
+    label_fill: str
+    card_fill: str | None
+    border_color: str | None
+    muted: str
+
+
+@dataclass(frozen=True)
+class _SupportRow:
+    """Resolved support-row content + colors. ``None`` means no row to emit."""
+
+    glyph: str
+    value_str: str
+    explainer: str
+    value_fill: str
+    glyph_fill: str
+
+
+def _resolve_value_font_spec(kpi_config: Any) -> tuple[float, str, float, float]:
+    """Return ``(value_font, value_weight, affix_font, glyph_font)``.
+
+    Font sizes come from authored theme YAML (kpi.value.font.size, etc.).
+    No clamping — theme sets the exact size.
+    """
+    assert (
+        kpi_config.value.font.size is not None
+    ), "theme must supply kpi.value.font.size"
+    value_font = float(kpi_config.value.font.size)
+
+    weight_input = kpi_config.value.font.weight
+    value_weight = (
+        font_weight_as_css(weight_input)
+        if weight_input is not None
+        and font_weight_as_css(weight_input) in VALID_FONT_WEIGHTS
+        else "500"
+    )
+
+    assert (
+        kpi_config.affix.font.size is not None
+    ), "theme must supply kpi.affix.font.size"
+    affix_font = float(kpi_config.affix.font.size)
+    assert (
+        kpi_config.glyph.font.size is not None
+    ), "theme must supply kpi.glyph.font.size"
+    glyph_font = float(kpi_config.glyph.font.size)
+    return value_font, value_weight, affix_font, glyph_font
+
+
+def _wrap_label_lines(
+    label_text: str,
+    requested_width: float,
+    pad: Any,
+    label_font_size: float,
+    label_font_family: str,
+    title_style: Any,
+) -> tuple[tuple[str, ...], bool]:
+    """Run the title-overflow wrap and report ``(lines, truncated)``.
+
+    Direct comparison of rendered vs original catches every overflow mode
+    (clip, truncate, wrap-two); the "…" sniff misses clip mode which
+    shortens without ellipsis. Empty label short-circuits — the slot is
+    reserved by the layout but no `<text>` is emitted (see _emit_kpi_svg).
+    """
+    if not label_text:
+        return (), False
+    rendered_label = prepare_title_text(
+        label_text,
+        overflow=resolve_title_overflow(title_style),
+        limit=compute_title_limit(
+            requested_width,
+            {"left": pad.left, "right": pad.right},
+        ),
+        font_size=label_font_size,
+        font_family=label_font_family,
+    )
+    label_lines = tuple((rendered_label.splitlines() or [label_text])[:2])
+    return label_lines, rendered_label != label_text
+
+
+def _resolve_kpi_layout(
+    label_text: str,
+    requested_width: float,
+    requested_height: float,
+    resolved_style: MergedChartsStyle,
+) -> _KpiLayout:
+    kpi_config = resolved_style.kpi
+    kpi_rendering = get_chart_rendering().kpi
+
+    # Label slot reads from kpi.label.font (cascade fills from kpi.font).
+    # Sizes and family are guaranteed non-None after resolve_style(); asserts
+    # confirm the cascade contract. Weight falls back to "500" for non-CSS values
+    # (e.g. theme supplies 701 which isn't a valid CSS weight keyword).
+    _label_size = kpi_config.label.font.size
+    _support_size = kpi_config.font.size
+    assert (
+        _label_size is not None
+    ), "kpi.label.font.size unresolved — call resolve_style() first"
+    assert (
+        _support_size is not None
+    ), "kpi.font.size unresolved — call resolve_style() first"
+    label_font_size = float(_label_size)
+    _lw = kpi_config.label.font.weight
+    label_weight: str = (
+        font_weight_as_css(_lw)
+        if _lw is not None and font_weight_as_css(_lw) in VALID_FONT_WEIGHTS
+        else "500"
+    )
+    _label_family = kpi_config.label.font.family
+    assert (
+        _label_family is not None
+    ), "kpi.label.font.family unresolved — call resolve_style() first"
+    label_font_family = _label_family
+    support_font_size = float(_support_size)
+    pad = kpi_config.content_padding
+
+    value_font, value_weight, affix_font, glyph_font = _resolve_value_font_spec(
+        kpi_config
+    )
+    # Support weight: when ``kpi.font.weight`` is set, emit it explicitly on
+    # the support <text>; otherwise leave it implicit (inherits body weight).
+    support_weight_input = kpi_config.font.weight
+    support_weight: str | None = (
+        font_weight_as_css(support_weight_input)
+        if support_weight_input is not None
+        and font_weight_as_css(support_weight_input) in VALID_FONT_WEIGHTS
+        else None
+    )
+
+    label_line_height = label_font_size + 4.0
+    label_top_padding = float(kpi_rendering.minimum_title_value_gap)
+
+    # Inner edge padding (per side) reads from ``kpi.content_padding``.
+    # Cap-height + descender awareness make ``pad.top`` / ``pad.bottom``
+    # mean *visible whitespace from card edge to ink* (not baseline-to-edge),
+    # so 18 vs 5 top/bottom asymmetry is gone.
+    cap_height = value_font * _CAP_HEIGHT_RATIO
+
+    # Value + label + support is a fixed 3-line text block at one consistent
+    # rhythm:
+    #   line 1: label
+    #   line 2: label continuation, or blank
+    #   line 3: support, riding the third label baseline regardless of its
+    #           own font size.
+    value_baseline = pad.top + cap_height
+    prefix_baseline = value_baseline - (value_font - affix_font) * _AFFIX_ELEVATION
+    glyph_baseline = value_baseline - (value_font - glyph_font) * _AFFIX_ELEVATION
+    # Cap-height-aware on the label side too: ``label_top_padding`` reads
+    # as visible whitespace from the value's bottom (digits sit on the
+    # baseline; lining figures don't descend) to the label's cap top.
+    # Adding ``label_font_size`` here would inflate the visible gap by
+    # ~30% — the formula now gives the config token its literal meaning.
+    label_cap_height = label_font_size * _CAP_HEIGHT_RATIO
+    label_baseline_first = value_baseline + label_top_padding + label_cap_height
+    # When title.overflow forces single-line rendering, no label can wrap to
+    # two lines, so the second reserved line is wasted vertical. Row-baseline
+    # alignment is preserved because the overflow mode is theme-wide — every
+    # KPI in the face shifts by the same amount.
+    overflow_mode = resolve_title_overflow(resolved_style.title)
+    label_slot_lines = 1 if overflow_mode in {"clip", "truncate"} else 2
+    support_baseline = label_baseline_first + label_slot_lines * label_line_height
+
+    # Visible bottom padding = pad.bottom from support text descender
+    # to card edge (matches the visible top padding above).
+    support_descender = support_font_size * _DESCENDER_RATIO
+    minimum_card_h = support_baseline + support_descender + pad.bottom
+    height = max(requested_height, minimum_card_h)
+
+    label_lines, label_truncated = _wrap_label_lines(
+        label_text,
+        requested_width,
+        pad,
+        label_font_size,
+        label_font_family,
+        resolved_style.title,
+    )
+
+    return _KpiLayout(
+        width=requested_width,
+        height=height,
+        content_x=pad.left,
+        value_baseline=value_baseline,
+        value_font=value_font,
+        affix_font=affix_font,
+        glyph_font=glyph_font,
+        value_weight=value_weight,
+        prefix_baseline=prefix_baseline,
+        glyph_baseline=glyph_baseline,
+        label_baseline_first=label_baseline_first,
+        label_font_size=label_font_size,
+        label_font_family=label_font_family,
+        label_weight=label_weight,
+        label_line_height=label_line_height,
+        label_lines=label_lines,
+        label_original=label_text,
+        label_truncated=label_truncated,
+        support_baseline=support_baseline,
+        support_font_size=support_font_size,
+        support_weight=support_weight,
+    )
+
+
+def _resolve_kpi_colors(
+    chart: Any,
+    row: dict[str, Any],
+    main_format: Any,
+    resolved_style: MergedChartsStyle,
+    formats: dict[str, str] | None = None,
+    *,
+    board_style: MergedStyle,
+) -> _KpiColors:
+    """Resolve the four surface fills (value/glyph/title/card) and border."""
+    kpi_config = resolved_style.kpi
+    _ms = board_style
+
+    resolved_channels = chart.resolved_channels
+    kpi_format = resolve_format(main_format, formats) or None
+    channel_bg = _evaluate_channel_for_row(
+        resolved_channels, "background", row, col_format=kpi_format
+    )
+    channel_color = _evaluate_channel_for_row(
+        resolved_channels, "color", row, col_format=kpi_format
+    )
+    card_fill = (
+        channel_bg
+        if channel_bg is not None
+        else _explicit_color_override(
+            _resolved_charts_style_value(chart, resolved_style, "background")
+        )
+    )
+
+    tones = kpi_config.tones
+    style_color = _resolved_charts_style_value(chart, resolved_style, "color")
+    tone = resolved_style.kpi.tone
+    value_fill = _resolve_value_color(
+        tone=tone,
+        channel_color=channel_color,
+        style_color=style_color if isinstance(style_color, str) else None,
+        tones=tones,
+        fallback=_ms.font.color,
+    )
+    glyph_fill = _resolve_glyph_color(tone, tones, fallback=value_fill)
+
+    # Label color: use the body text color directly. The legacy "label
+    # picks up style.title.font.color" coupling tied two distinct slots
+    # together (chart-section title and KPI label) and only worked by
+    # reading the authored Patch — i.e. by discriminating "did the chart
+    # author override style.title.font.color." After the cascade rename,
+    # resolved_style.title.font.color is always populated by the theme
+    # default, so the legacy fallthrough to body color silently flipped
+    # to a different theme value. Drop the coupling: the KPI label uses
+    # body text color (theme charts.color / sanitized fallback), and a
+    # future task can add a typed ``style.label.font.color`` slot if a
+    # KPI label override is genuinely needed.
+    label_fill = sanitize_color(None, _ms.font.color)
+
+    rs = getattr(chart, "resolved_style", None) or resolved_style
+    _bc = rs.border.color
+    border_color = (
+        _explicit_color_override(_bc)
+        if _bc.lower() not in {"transparent", "none", ""}
+        else None
+    )
+
+    return _KpiColors(
+        value_fill=value_fill,
+        glyph_fill=glyph_fill,
+        label_fill=label_fill,
+        card_fill=card_fill,
+        border_color=border_color,
+        muted=_ms.variables.font.color or "",
+    )
+
+
+def _resolve_support_row(
+    support: KpiSupportConfig | None,
+    row: dict[str, Any],
+    tones: Any,
+    muted: str,
+    chart_id: str,
+    formats: dict[str, str] | None = None,
+) -> _SupportRow | None:
+    """Resolve the support row's text and colors. Returns None when the row
+    is absent or carries no content to emit."""
+    if support is None:
+        return None
+    s_cell = None
+    if support.value is not None:
+        s_cell, _ = _resolve_value(support.value, row, chart_id)
+    # Support keeps the BI default register — its dense numeric form
+    # belongs alongside axis ticks and table cells, not the hero number
+    # above it.
+    s_prefix, s_number_str, s_suffix, _ = _format_value_parts(
+        s_cell, support.format, formats
+    )
+    if s_prefix or s_suffix:
+        value_str = f"{s_prefix}{s_number_str}{s_suffix}"
+    else:
+        value_str = s_number_str
+
+    glyph = support.glyph or ""
+    explainer = support.label or ""
+    if not (value_str or explainer or glyph):
+        return None
+
+    tone_color = _tone_color(support.tone, tones)
+    value_fill = tone_color if tone_color is not None else muted
+    glyph_fill = tone_color if tone_color is not None else value_fill
+
+    return _SupportRow(
+        glyph=glyph,
+        value_str=value_str,
+        explainer=explainer,
+        value_fill=value_fill,
+        glyph_fill=glyph_fill,
+    )
+
+
+def render_kpi_svg(
+    chart: Any,
+    data: list[dict[str, Any]],
+    width: float | None = None,
+    height: float | None = None,
+    is_placeholder: bool = False,
+    *,
+    resolved_style: MergedChartsStyle,
+    face_level: int = 1,
+    board_style: MergedStyle,
+) -> str:
+    """Render a KPI as a left-aligned three-slot quantitative text object."""
+    _ = face_level  # KPI charts have no title; level unused at this renderer tier
+    kpi_config = resolved_style.kpi
+
+    chart_id = getattr(chart, "id", "unknown")
+    requested_w: float = width or kpi_config.default_width
+    requested_h: float = height or kpi_config.default_height
+
+    if not data:
+        raise ChartDataError(
+            f"KPI chart '{chart_id}' has no data — query returned 0 rows",
+            chart_id=chart_id,
+        )
+    if len(data) > 1:
+        from dataface.core.errors import DF_RENDER_KPI_MULTIROW
+
+        raise ChartDataError.from_code(
+            DF_RENDER_KPI_MULTIROW,
+            chart_id=chart_id,
+            row_count=len(data),
+        )
+
+    raw_value = chart.value
+    if raw_value is None:
+        raise ChartDataError(
+            f"KPI chart '{chart_id}' requires a 'value' field (column reference).",
+            chart_id=chart_id,
+        )
+
+    row = data[0]
+    cell, value_column = _resolve_value(raw_value, row, chart_id)
+    # Apply narrative-notation default to the top-level KPI block only —
+    # support-block format defaults to analytic (its register matches dense
+    # axis/table use rather than the hero number above it).
+    main_format = _narrative_format_default(chart.format)
+    formats = resolved_style.formats
+    prefix, number_str, suffix, value_is_numeric = _format_value_parts(
+        cell, main_format, formats
+    )
+    # Empty string honored as "no label" — renderer skips emission while
+    # keeping the slot reserved (so multi-up KPI rows stay aligned).
+    label_text = chart.label or ""
+    if label_text:
+        from dataface.core.render.text.case import apply_case
+
+        _label_case = kpi_config.label.font.case
+        if _label_case is not None and _label_case != "none":
+            label_text = apply_case(label_text, _label_case)
+
+    layout = _resolve_kpi_layout(label_text, requested_w, requested_h, resolved_style)
+    palette = _resolve_kpi_colors(
+        chart, row, main_format, resolved_style, formats, board_style=board_style
+    )
+    support_row = _resolve_support_row(
+        chart.support, row, kpi_config.tones, palette.muted, chart_id, formats
+    )
+
+    # Family resolution for KPI text. The cascade fills ``kpi.font.family``
+    # from root ``style.font.family`` and ``kpi.value.font.family`` from
+    # ``kpi.font.family``. Read the resolved values directly. If a caller
+    # bypasses the cascade and leaves either field None, the theme/contract
+    # is broken — raise loudly rather than emit ``font-family="None"``.
+    body_font_family = kpi_config.font.family
+    value_font_family = kpi_config.value.font.family
+    if body_font_family is None or value_font_family is None:
+        raise ValueError(
+            "KPI font family is unresolved — call resolve_style() so the "
+            "cascade fills kpi.font.family from style.font.family and "
+            "kpi.value.font.family from kpi.font.family before rendering."
+        )
+
+    return _emit_kpi_svg(
+        chart=chart,
+        layout=layout,
+        palette=palette,
+        support_row=support_row,
+        prefix=prefix,
+        number_str=number_str,
+        suffix=suffix,
+        value_is_numeric=value_is_numeric,
+        value_font_family=value_font_family,
+        body_font_family=body_font_family,
+        kpi_config=kpi_config,
+    )
+
+
+def _emit_kpi_svg(
+    chart: Any,
+    layout: _KpiLayout,
+    palette: _KpiColors,
+    support_row: _SupportRow | None,
+    prefix: str,
+    number_str: str,
+    suffix: str,
+    value_is_numeric: bool,
+    value_font_family: str,
+    body_font_family: str,
+    kpi_config: Any,
+) -> str:
+    """Mechanical SVG assembly given pre-resolved layout/palette/support."""
+    parts: list[str] = []
+
+    if palette.card_fill is not None or palette.border_color is not None:
+        rect = (
+            f'<rect x="0" y="0" width="{layout.width}" height="{layout.height}" '
+            f'rx="{kpi_config.border.radius:g}" '
+            f'fill="{palette.card_fill or "none"}"'
+        )
+        if palette.border_color:
+            rect += f' stroke="{palette.border_color}" stroke-width="1"'
+        rect += "/>"
+        parts.append(rect)
+
+    # Value row — glyph (optional) + prefix + number + suffix. Per-tspan
+    # ``y=`` anchors each affix to its own baseline so prefix floats to the
+    # top of the line and glyph rides the middle, while value+suffix sit on
+    # the value baseline.
+    glyph_char = kpi_config.glyph.character
+    value_tspans: list[str] = []
+    if glyph_char:
+        value_tspans.append(
+            f'<tspan y="{layout.glyph_baseline}" '
+            f'font-size="{layout.glyph_font}" '
+            f'fill="{palette.glyph_fill}">{html.escape(glyph_char)} </tspan>'
+        )
+    if value_is_numeric and prefix:
+        value_tspans.append(
+            f'<tspan y="{layout.prefix_baseline}" '
+            f'font-size="{layout.affix_font}" '
+            f'fill="{palette.value_fill}">{html.escape(prefix)}</tspan>'
+        )
+    value_tspans.append(
+        f'<tspan y="{layout.value_baseline}" '
+        f'font-size="{layout.value_font}" '
+        f'fill="{palette.value_fill}">{html.escape(number_str)}</tspan>'
+    )
+    if value_is_numeric and suffix:
+        value_tspans.append(
+            f'<tspan y="{layout.value_baseline}" '
+            f'font-size="{layout.affix_font}" '
+            f'fill="{palette.value_fill}" dx="2">{html.escape(suffix)}</tspan>'
+        )
+    # font-weight on the parent <text> so glyph/prefix/value/suffix all inherit
+    # the same weight. The cascade resolves it from ``kpi.value.font.weight``.
+    _link_ctx = get_link_context()
+    kpi_link = (
+        resolve_href(chart.link, _link_ctx) if chart.link and _link_ctx else chart.link
+    )
+    if kpi_link:
+        escaped_href = html.escape(kpi_link, quote=True)
+        parts.append(f'<a href="{escaped_href}">')
+    parts.append(
+        f'<text x="{layout.content_x}" y="{layout.value_baseline}" '
+        f'text-anchor="start" font-family="{value_font_family}" '
+        f'font-weight="{layout.value_weight}">'
+        f'{"".join(value_tspans)}</text>'
+    )
+    if kpi_link:
+        parts.append("</a>")
+
+    # Label — fixed two-line slot, top-aligned within it. The slot is always
+    # reserved (so support baselines align across a row of mixed-length
+    # labels) even when the author set ``label: ""`` — only the <text> is
+    # skipped in that case.
+    if layout.label_original:
+        # Emit inner <title> when the rendered text differs from the
+        # original — catches all overflow modes (clip, truncate, wrap-two).
+        inner_title = (
+            f"<title>{html.escape(layout.label_original)}</title>"
+            if layout.label_truncated
+            else ""
+        )
+        parts.append(
+            f'<text x="{layout.content_x}" y="{layout.label_baseline_first}" '
+            f'text-anchor="start" font-family="{layout.label_font_family}" '
+            f'font-size="{layout.label_font_size}" fill="{palette.label_fill}" '
+            f'font-weight="{layout.label_weight}">'
+            f"{inner_title}"
+        )
+        for line_index, line in enumerate(layout.label_lines):
+            line_y = layout.label_baseline_first + line_index * layout.label_line_height
+            parts.append(
+                f'<tspan x="{layout.content_x}" y="{line_y}">{html.escape(line)}</tspan>'
+            )
+        parts.append("</text>")
+
+    # Support row — glyph + value + neutral explainer.
+    if support_row is not None:
+        s_tspans: list[str] = []
+        if support_row.glyph:
+            s_tspans.append(
+                f'<tspan fill="{support_row.glyph_fill}">'
+                f"{html.escape(support_row.glyph)} </tspan>"
+            )
+        if support_row.value_str:
+            s_tspans.append(
+                f'<tspan fill="{support_row.value_fill}">'
+                f"{html.escape(support_row.value_str)}</tspan>"
+            )
+        if support_row.explainer:
+            spacer = " " if support_row.value_str or support_row.glyph else ""
+            s_tspans.append(
+                f'<tspan fill="{palette.muted}">'
+                f"{html.escape(spacer + support_row.explainer)}</tspan>"
+            )
+        # Support always uses the body sans, never the value family — keeps
+        # editorial KPIs (serif value) reading right (sans support).
+        weight_attr = (
+            f' font-weight="{layout.support_weight}"' if layout.support_weight else ""
+        )
+        parts.append(
+            f'<text x="{layout.content_x}" y="{layout.support_baseline}" '
+            f'text-anchor="start" font-family="{body_font_family}" '
+            f'font-size="{layout.support_font_size}"{weight_attr}>'
+            f'{"".join(s_tspans)}</text>'
+        )
+
+    inner = "\n".join(parts)
+    return (
+        f'<svg xmlns="http://www.w3.org/2000/svg" '
+        f'width="{layout.width}" height="{layout.height}" '
+        f'viewBox="0 0 {layout.width} {layout.height}">'
+        f"{inner}</svg>"
+    )