dataface 0.1.2__py3-none-any.whl

dataface/core/render/chart/spark_bar.py

@@ -0,0 +1,370 @@
+"""Compact horizontal spark bar chart SVG rendering."""
+
+from __future__ import annotations
+
+import html as html_module
+from typing import Any
+
+from dataface.core.compile.config import get_chart_rendering
+from dataface.core.compile.models.primitives import FontStyle
+from dataface.core.compile.models.style.merged import (
+    MergedChartsStyle,
+    MergedStyle,
+)
+from dataface.core.compile.typography import chart_title_spec
+from dataface.core.render.utils import normalize_data_types
+
+_DEFAULT_WIDTH = 200.0
+_MIN_WIDTH = 150.0
+
+
+def _auto_detect_spark_bar_fields(
+    data: list[dict[str, Any]],
+    x_field: str | None,
+    y_field: str | None,
+) -> tuple[str | None, str | None]:
+    """Auto-detect x (frequency) and y (category) fields for spark bar charts.
+
+    Args:
+        data: List of data rows
+        x_field: Explicitly specified x field (frequency)
+        y_field: Explicitly specified y field (category)
+
+    Returns:
+        Tuple of (x_field, y_field) with auto-detected values if not specified
+
+    """
+    if not data:
+        return x_field, y_field
+
+    # Auto-detect y field (category)
+    if not y_field:
+        for key in data[0]:
+            if key.lower() in ("value", "label", "category", "name"):
+                y_field = key
+                break
+        if not y_field:
+            # Use first string column as y
+            for key, val in data[0].items():
+                if isinstance(val, str):
+                    y_field = key
+                    break
+
+    # Auto-detect x field (frequency)
+    if not x_field:
+        for key in data[0]:
+            if key.lower() in ("frequency", "count", "freq", "n", "total"):
+                x_field = key
+                break
+        if not x_field:
+            # Use first numeric column as x
+            for key, val in data[0].items():
+                if isinstance(val, (int, float)) and not isinstance(val, bool):
+                    x_field = key
+                    break
+
+    return x_field, y_field
+
+
+def _render_spark_bar_row(
+    row: dict[str, Any],
+    row_index: int,
+    row_y: float,
+    x_field: str | None,
+    y_field: str | None,
+    bar_height: int,
+    bar_area_width: float,
+    max_value: float,
+    left_padding: int,
+    chart_width: float,
+    text_color: str,
+    bar_color: str,
+    bar_background: str,
+    labels_visible: bool,
+    counts_visible: bool,
+    spark_config: Any,
+    spark_rendering: Any,
+    font: FontStyle,
+) -> list[str]:
+    """Render a single bar row for spark bar chart.
+
+    Args:
+        row: Data row dict
+        row_index: Index of this row (0-based)
+        row_y: Y position for this row
+        x_field: Field name for frequency/count values
+        y_field: Field name for category labels
+        bar_height: Height of each bar (may be overridden from default)
+        bar_area_width: Width of the bar area
+        max_value: Maximum value for scaling bars
+        left_padding: Left padding before bar starts
+        chart_width: Total chart width
+        text_color: Color for text labels
+        bar_color: Fill color for bars (may be overridden from default)
+        bar_background: Background color for bar track
+        labels_visible: Whether to show category labels
+        counts_visible: Whether to show count labels
+        spark_config: Config object for non-overridable values (border_radius, font sizes, label.width)
+        font: FontStyle for text elements (reads .family)
+
+    Returns:
+        List of SVG element strings for this row
+
+    """
+    svg_parts: list[str] = []
+
+    # Get values
+    label_value = str(row.get(y_field, "")) if y_field else f"Item {row_index + 1}"
+    count_value = row.get(x_field, 0) if x_field else 0
+    if not isinstance(count_value, (int, float)):
+        count_value = 0
+
+    # Calculate bar width
+    bar_width = (float(count_value) / max_value) * bar_area_width
+
+    # Truncate label if too long (use config for label.width)
+    max_label_chars = int(spark_config.label.width / spark_rendering.avg_char_width_px)
+    display_label = label_value
+    if len(display_label) > max_label_chars:
+        display_label = display_label[: max_label_chars - 2] + "..."
+    escaped_label = html_module.escape(display_label)
+
+    # Format count
+    if isinstance(count_value, float) and count_value == int(count_value):
+        display_count = str(int(count_value))
+    elif isinstance(count_value, float):
+        display_count = f"{count_value:,.1f}"
+    else:
+        display_count = f"{count_value:,}"
+
+    # Render label
+    if labels_visible:
+        label_y = row_y + (bar_height / 2) + spark_rendering.text_baseline_offset
+        svg_parts.append(
+            f'<text x="0" y="{label_y:.1f}" '
+            f'font-size="{spark_config.font.size}" fill="{text_color}" '
+            f'font-family="{font.family}">'
+            f"{escaped_label}</text>",
+        )
+
+    # Render bar background
+    bar_x = left_padding
+    svg_parts.append(
+        f'<rect x="{bar_x}" y="{row_y:.1f}" '
+        f'width="{bar_area_width}" height="{bar_height}" '
+        f'fill="{bar_background}" rx="{spark_config.border.radius}"/>',
+    )
+
+    # Render bar fill
+    if bar_width > 0:
+        svg_parts.append(
+            f'<rect x="{bar_x}" y="{row_y:.1f}" '
+            f'width="{bar_width:.1f}" height="{bar_height}" '
+            f'fill="{bar_color}" rx="{spark_config.border.radius}"/>',
+        )
+
+    # Render count
+    if counts_visible:
+        count_x = chart_width - spark_rendering.side_padding
+        count_y = row_y + (bar_height / 2) + spark_rendering.text_baseline_offset
+        svg_parts.append(
+            f'<text x="{count_x:.1f}" y="{count_y:.1f}" '
+            f'font-size="{spark_config.font.size}" fill="{text_color}" text-anchor="end" '
+            f'font-family="{font.family}" '
+            f'style="font-variant-numeric: tabular-nums lining-nums;">'
+            f"{display_count}</text>",
+        )
+
+    return svg_parts
+
+
+def render_spark_bar_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 spark bar chart as SVG.
+
+    Creates a compact horizontal bar chart for profiler column cards with:
+    - Category labels on the left
+    - Horizontal bars showing frequency/count
+    - Optional count labels on the right
+    - Truncated labels for long text
+
+    Args:
+        chart: Chart definition with x (frequency), y (category) fields
+        data: List of dicts containing bar data
+        width: Optional explicit width in pixels
+        height: Optional explicit height in pixels
+        is_placeholder: If True, render with placeholder styling
+        face_level: Heading level of the parent face (root=1, nested=2, …).
+            Chart title uses face_level + 1.
+        board_style: Board-level MergedStyle for theme color reads.
+
+    Returns:
+        SVG string representing the spark bar chart
+
+    """
+    data = normalize_data_types(data)
+
+    # spark_config comes from resolved_style, which is already merged with any
+    # chart-local ChartStylePatch.spark_bar overlay by _build_resolved_style.
+    spark_config = resolved_style.spark_bar
+    spark_rendering = (
+        get_chart_rendering().spark_bar
+    )  # designer-tunable layout constants
+
+    assert spark_config.font.family is not None, "style.font.family must be configured"
+    text_color = board_style.font.color
+    secondary_color = board_style.variables.font.color
+    subtitle_text = chart.subtitle or ""
+
+    # Extract overridable values (post-patch)
+    bar_height = spark_config.bar.height
+    max_bars = spark_config.max_bars
+    labels_visible = spark_config.label.visible
+    counts_visible = spark_config.count.visible
+    bar_color = spark_config.bar.color
+    assert (
+        bar_color is not None
+    ), "spark_bar.bar.color requires resolved style (pass resolved_style)"
+    # board_style.variables.input.background carries the active board theme's
+    # track color — always use it.
+    bar_background = board_style.variables.input.background
+
+    # Get field names from chart, auto-detecting if not specified
+    x_field, y_field = _auto_detect_spark_bar_fields(data, chart.x, chart.y)
+
+    # Limit data to max_bars
+    visible_data = data[:max_bars] if data else []
+
+    # Calculate dimensions
+    num_bars = len(visible_data)
+    row_height = bar_height + spark_config.bar.padding
+    chart_width = width or _DEFAULT_WIDTH
+    chart_width = max(chart_width, _MIN_WIDTH)
+    # Width-aware title spec: size, weight, family based on card width
+    chart_title_size, chart_title_weight, chart_title_family = chart_title_spec(
+        chart_width, level=face_level + 1, resolved_chart_style=resolved_style
+    )
+    title_height = spark_rendering.title_height if chart.title else 0
+    if chart.title and subtitle_text:
+        title_height += chart_title_size
+    chart_height = height or (
+        title_height + (num_bars * row_height) + spark_config.bar.padding
+    )
+
+    # Calculate bar area dimensions
+    left_padding = (
+        spark_config.label.width if labels_visible else spark_rendering.side_padding
+    )
+    right_padding = (
+        spark_config.count.width if counts_visible else spark_rendering.side_padding
+    )
+    bar_area_width = max(chart_width - left_padding - right_padding, 20)
+
+    # Find max value for scaling
+    max_value = 0.0
+    if visible_data and x_field:
+        for row in visible_data:
+            val = row.get(x_field, 0)
+            if isinstance(val, (int, float)):
+                max_value = max(max_value, float(val))
+    if max_value == 0:
+        max_value = 1.0  # Prevent division by zero
+
+    # Build SVG elements
+    svg_parts: list[str] = []
+    current_y = 0.0
+
+    # Title
+    if chart.title:
+        escaped_title = html_module.escape(str(chart.title))
+        svg_parts.append(
+            f'<text x="0" y="{spark_rendering.title_baseline_y}" '
+            f'font-size="{chart_title_size}" font-weight="{chart_title_weight}" fill="{text_color}" '
+            f'font-family="{chart_title_family}">'
+            f"{escaped_title}</text>",
+        )
+        if subtitle_text:
+            escaped_subtitle = html_module.escape(subtitle_text)
+            assert (
+                spark_config.subtitle.font.size is not None
+            ), "theme must supply spark_bar.subtitle.font.size"
+            subtitle_font_size = float(spark_config.subtitle.font.size)
+            svg_parts.append(
+                f'<text x="0" y="{spark_rendering.title_baseline_y + chart_title_size}" '
+                f'font-size="{subtitle_font_size}" fill="{secondary_color}" '
+                f'font-family="{spark_config.font.family}">'
+                f"{escaped_subtitle}</text>",
+            )
+        current_y = title_height
+
+    # Render bars
+    for i, row in enumerate(visible_data):
+        row_y = current_y + (i * row_height)
+        svg_parts.extend(
+            _render_spark_bar_row(
+                row=row,
+                row_index=i,
+                row_y=row_y,
+                x_field=x_field,
+                y_field=y_field,
+                bar_height=int(bar_height),
+                bar_area_width=bar_area_width,
+                max_value=max_value,
+                left_padding=int(left_padding),
+                chart_width=chart_width,
+                text_color=text_color,
+                bar_color=bar_color,
+                bar_background=bar_background,
+                labels_visible=labels_visible,
+                counts_visible=counts_visible,
+                spark_config=spark_config,
+                spark_rendering=spark_rendering,
+                font=spark_config.font,
+            ),
+        )
+
+    # Show "more" indicator if data was truncated
+    if len(data) > len(visible_data):
+        more_count = len(data) - len(visible_data)
+        more_y = (
+            current_y + (num_bars * row_height) + spark_rendering.more_rows_offset_y
+        )
+        svg_parts.append(
+            f'<text x="{chart_width / 2}" y="{more_y:.1f}" '
+            f'font-size="{spark_rendering.more_rows_font_size}" fill="{secondary_color}" text-anchor="middle" font-style="italic" '
+            f'font-family="{spark_config.font.family}" '
+            f'style="font-variant-numeric: tabular-nums lining-nums;">'
+            f"+ {more_count} more</text>",
+        )
+        chart_height = more_y + spark_rendering.more_rows_bottom_padding
+
+    # Wrap in SVG
+    svg_result = f"""<svg xmlns="http://www.w3.org/2000/svg" width="{chart_width}" height="{chart_height}" viewBox="0 0 {chart_width} {chart_height}">
+{"".join(svg_parts)}
+</svg>"""
+
+    # Apply placeholder styling if needed
+    if is_placeholder:
+        from dataface.core.render.placeholder import (
+            add_placeholder_overlay,
+            apply_placeholder_opacity,
+        )
+
+        svg_result = apply_placeholder_opacity(svg_result)
+        svg_result = add_placeholder_overlay(
+            svg_result,
+            chart_width,
+            chart_height,
+            font=spark_config.font,
+        )
+
+    return svg_result

dataface/core/render/chart/spec_builders.py

@@ -0,0 +1,154 @@
+"""Shared Vega-Lite spec builder helpers."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from dataface.core.compile.config import get_vega_config
+from dataface.core.render.text.case import apply_case
+
+if TYPE_CHECKING:
+    from dataface.core.compile.models.style.compiled import PaddingStyle
+    from dataface.core.compile.models.style.merged import MergedChartsStyle
+
+
+def new_chart_spec(
+    data: list[dict[str, Any]],
+    *,
+    mark: dict[str, Any] | None = None,
+    layer: bool = False,
+    datasets: dict[str, list[dict[str, Any]]] | None = None,
+) -> dict[str, Any]:
+    """Build the common base for Vega-Lite chart specs.
+
+    When ``datasets`` is provided (per-layer queries), the spec uses
+    top-level ``"datasets"`` instead of ``"data": {"values": ...}``.
+    Each layer then references its dataset via ``"data": {"name": ...}``.
+    """
+    spec: dict[str, Any] = {
+        "$schema": get_vega_config().schema,
+        "background": None,
+        "autosize": {"type": "fit", "contains": "padding"},
+        # Zero-padding initial state. The board layer replaces this via padding=
+        # additive_padding(card_pad, charts.padding). On direct-render paths (no board
+        # layer), bump_padding_bottom() can safely increment the bottom field.
+        "padding": {"left": 0, "right": 0, "top": 0, "bottom": 0},
+    }
+    if datasets is not None:
+        spec["datasets"] = datasets
+    else:
+        spec["data"] = {"values": data}
+    if mark is not None:
+        spec["mark"] = mark
+    if layer:
+        spec["layer"] = []
+    else:
+        spec["encoding"] = {}
+    return spec
+
+
+def uniform_padding(value: float) -> dict[str, float]:
+    """Return a Vega-Lite padding dict with equal inset on all sides."""
+    return {"left": value, "right": value, "top": value, "bottom": value}
+
+
+def additive_padding(card_pad: float, chart_padding: PaddingStyle) -> dict[str, float]:
+    """Add card_padding to per-chart padding on each side independently.
+
+    Per-chart padding (style.charts.padding) stacks ON TOP of card_padding so
+    author-specified insets compose with the global card layout rather than
+    replacing it. The theme default is {0,0,0,0}, making this a no-op for
+    boards that don't override per-chart padding.
+    """
+    return {
+        "left": card_pad + chart_padding.left,
+        "right": card_pad + chart_padding.right,
+        "top": card_pad + chart_padding.top,
+        "bottom": card_pad + chart_padding.bottom,
+    }
+
+
+def bump_padding_bottom(spec: dict[str, Any], add_px: float) -> None:
+    """Increase spec-level `padding.bottom` by add_px in place.
+
+    Assumes the spec already carries a 4-key padding dict, which is the
+    invariant ``new_chart_spec`` (the only Dataface entry point that
+    builds chart-body specs) sets. Other sides are left alone.
+    """
+    padding = dict(spec["padding"])
+    padding["bottom"] = float(padding.get("bottom", 0)) + add_px
+    spec["padding"] = padding
+
+
+def bump_padding_top(spec: dict[str, Any], add_px: float) -> None:
+    """Increase spec-level `padding.top` by add_px in place.
+
+    Symmetric counterpart to ``bump_padding_bottom`` — used when a strip
+    is attached above the plot (``style.data_table.position: top``).
+    """
+    padding = dict(spec["padding"])
+    padding["top"] = float(padding.get("top", 0)) + add_px
+    spec["padding"] = padding
+
+
+def set_chart_title(
+    spec: dict[str, Any],
+    title: str | None,
+    subtitle: str | None = None,
+    *,
+    style: MergedChartsStyle | None = None,
+) -> None:
+    """Apply a standard title block when a title is present.
+
+    When *style* is provided, ``style.title.font.case`` is applied to the
+    title text. Subtitle is not yet case-transformed here — chart subtitles
+    have always been emitted raw.
+    """
+    if title and style is not None:
+        case = style.title.font.case
+        if case is not None and case != "none":
+            title = apply_case(title, case)
+    if title or subtitle:
+        title_block: dict[str, Any] = {"text": title or ""}
+        if subtitle:
+            title_block["subtitle"] = subtitle
+        spec["title"] = title_block
+
+
+def set_chart_dimensions(
+    spec: dict[str, Any],
+    width: float | None = None,
+    height: float | None = None,
+    *,
+    width_offset: float = 0,
+    min_width: float | None = None,
+    height_offset: float = 0,
+    min_height: float | None = None,
+) -> None:
+    """Apply width and height with optional offsets and minimums."""
+    if width is not None and width > 0:
+        computed_width = width - width_offset
+        spec["width"] = max(computed_width, min_width) if min_width else computed_width
+    if height is not None and height > 0:
+        computed_height = height - height_offset
+        spec["height"] = (
+            max(computed_height, min_height) if min_height else computed_height
+        )
+
+
+def tooltip_entry(
+    field: str,
+    field_type: str,
+    *,
+    title: str | None = None,
+    format: str | None = None,
+    **extra: Any,
+) -> dict[str, Any]:
+    """Build a tooltip field definition."""
+    entry: dict[str, Any] = {"field": field, "type": field_type}
+    if title is not None:
+        entry["title"] = title
+    if format is not None:
+        entry["format"] = format
+    entry.update(extra)
+    return entry