dataface 0.1.2__py3-none-any.whl

dataface/core/render/control_registry.py

@@ -0,0 +1,287 @@
+"""Control template discovery and loading.
+
+Stage: RENDER
+Purpose: Discover and render variable control templates.
+
+This module provides the ControlRegistry class that:
+1. Discovers control templates from built-in and project directories
+2. Supports flexible directory organization (flat, self-contained, categorized)
+3. Renders templates with Jinja2
+4. Collects CSS/JS assets for used controls
+"""
+
+import json
+import logging
+from pathlib import Path
+from typing import Any
+
+from jinja2 import Environment, FileSystemLoader, select_autoescape
+
+logger = logging.getLogger(__name__)
+
+
+class ControlRegistry:
+    """Registry for variable control templates.
+
+    Discovers and loads control templates from:
+    1. Project controls directory (user customizations) - checked first
+    2. Built-in controls (dataface defaults)
+
+    Supports flexible directory organization:
+    - controls/rating.html (flat)
+    - controls/rating/rating.html (self-contained)
+    - controls/pickers/color/color.html (categorized)
+
+    Example:
+        registry = ControlRegistry(project_root=Path("/my/project"))
+        html = registry.render_control("select", {
+            "name": "region",
+            "label": "Region",
+            "value": "US",
+            "options": [{"value": "US", "label": "United States", "selected": True}]
+        })
+    """
+
+    def __init__(self, project_root: Path | None = None):
+        """Initialize the control registry.
+
+        Args:
+            project_root: Optional project root for loading custom controls.
+                         If provided, looks for controls in {project_root}/controls/
+        """
+        self._project_root = project_root
+        self._builtin_dir = Path(__file__).parent / "templates" / "controls"
+        self._templates: dict[str, Path] = {}
+        self._css: dict[str, str] = {}
+        self._js: dict[str, str] = {}
+        self._jinja_env: Environment | None = None
+        self._used_controls: set[str] = set()
+        self._base_css: str | None = None
+
+        self._load_base_css()
+        self._load_builtins()
+        if project_root:
+            self._load_project_controls(project_root)
+
+    def _load_base_css(self) -> None:
+        """Load the base styles CSS file."""
+        emoji_partial = Path(__file__).parent / "fonts" / "_emoji_font_face.css"
+        base_css_path = self._builtin_dir / "_styles.css"
+        if base_css_path.exists():
+            self._base_css = emoji_partial.read_text() + base_css_path.read_text()
+
+    def _load_builtins(self) -> None:
+        """Load built-in control templates."""
+        if not self._builtin_dir.exists():
+            logger.warning(
+                f"Built-in controls directory not found: {self._builtin_dir}"
+            )
+            return
+
+        for template in self._builtin_dir.glob("*.html"):
+            if not template.name.startswith("_"):
+                self._register_control(template.stem, template)
+
+    def _load_project_controls(self, project_root: Path) -> None:
+        """Load controls from project directory with flexible organization.
+
+        Supports:
+        - controls/rating.html (flat)
+        - controls/rating/rating.html (self-contained directory)
+        - controls/pickers/color/color.html (categorized)
+
+        Files starting with _ are ignored (for shared partials/imports).
+        """
+        controls_dir = project_root / "controls"
+        if not controls_dir.exists():
+            return
+
+        # Find all HTML templates (excluding _prefixed files)
+        for template in controls_dir.rglob("*.html"):
+            rel_path = template.relative_to(controls_dir)
+
+            # Skip files/dirs starting with _ (check relative path only)
+            if any(part.startswith("_") for part in rel_path.parts):
+                continue
+
+            if template.stem == template.parent.name:
+                # Self-contained: controls/rating/rating.html -> "rating"
+                # Or nested: controls/pickers/color/color.html -> "pickers/color"
+                parent_rel = rel_path.parent
+                if parent_rel != Path("."):
+                    control_name = str(parent_rel).replace("\\", "/")
+                else:
+                    control_name = template.stem
+            else:
+                # Flat: controls/toggle.html -> "toggle"
+                # Or categorized flat: controls/pickers/icon.html -> "pickers/icon"
+                if rel_path.parent != Path("."):
+                    control_name = str(rel_path.parent / template.stem).replace(
+                        "\\", "/"
+                    )
+                else:
+                    control_name = template.stem
+
+            # Project controls override built-ins
+            self._register_control(control_name, template, override=True)
+            logger.debug(f"Loaded project control: {control_name} from {template}")
+
+    def _register_control(
+        self, name: str, template_path: Path, override: bool = False
+    ) -> None:
+        """Register a control and discover its companion assets (CSS, JS)."""
+        if name in self._templates and not override:
+            return
+
+        self._templates[name] = template_path
+
+        # Load companion CSS if exists
+        css_path = template_path.with_suffix(".css")
+        if css_path.exists():
+            self._css[name] = css_path.read_text()
+
+        # Load companion JS if exists
+        js_path = template_path.with_suffix(".js")
+        if js_path.exists():
+            self._js[name] = js_path.read_text()
+
+    def find_control(self, input_type: str) -> Path | None:
+        """Find control template by type name.
+
+        Supports:
+        - "rating" -> controls/rating.html or controls/rating/rating.html
+        - "pickers/color" -> controls/pickers/color/color.html
+
+        Args:
+            input_type: The control type (e.g., "select", "checkbox", "rating")
+
+        Returns:
+            Path to the template file, or None if not found
+        """
+        # Direct match
+        if input_type in self._templates:
+            return self._templates[input_type]
+
+        # Try without namespace prefix for built-ins
+        base_name = input_type.split("/")[-1]
+        if base_name in self._templates:
+            return self._templates[base_name]
+
+        return None
+
+    def has_control(self, input_type: str) -> bool:
+        """Check if a control type is available."""
+        return self.find_control(input_type) is not None
+
+    def render_control(
+        self,
+        input_type: str,
+        context: dict[str, Any],
+    ) -> str:
+        """Render a control template with the given context.
+
+        Args:
+            input_type: The control type (e.g., "select", "checkbox")
+            context: Template context dict containing:
+                - name: Variable name
+                - label: Display label
+                - value: Current value
+                - default: Default value
+                - options: List of {value, label, selected} for select controls
+                - min, max, step: For number/slider controls
+                - config: Full variable config (for advanced templates)
+                - depends_on: List of variable dependencies
+
+        Returns:
+            Rendered HTML string
+        """
+        template_path = self.find_control(input_type)
+
+        if not template_path:
+            logger.warning(f"Unknown control type '{input_type}', using readonly")
+            template_path = self.find_control("readonly")
+            if not template_path:
+                # Ultimate fallback if no readonly template
+                name = context.get("name", "unknown")
+                label = context.get("label", name)
+                value = context.get("value", "")
+                return f'<span class="dft-variable-readonly"><span class="dft-variable-label">{_html_escape(label)}:</span> <span class="dft-variable-readonly-value">{_html_escape(str(value))}</span></span>'
+
+        # Track which controls are used (for CSS/JS collection)
+        self._used_controls.add(input_type)
+
+        env = self._get_jinja_env()
+        # Load template content directly to support project overrides
+        template_content = template_path.read_text()
+        template = env.from_string(template_content)
+        return template.render(**context)
+
+    def get_base_css(self) -> str:
+        """Get the base CSS styles for all controls."""
+        return self._base_css or ""
+
+    def get_used_css(self) -> str:
+        """Get combined CSS for controls that were actually rendered.
+
+        Returns CSS only for controls that have been rendered via render_control(),
+        avoiding unnecessary CSS bloat.
+        """
+        css_parts = []
+        for control_name in self._used_controls:
+            if control_name in self._css:
+                css_parts.append(f"/* {control_name} */\n{self._css[control_name]}")
+        return "\n\n".join(css_parts)
+
+    def get_all_css(self) -> str:
+        """Get base CSS plus any control-specific CSS for used controls."""
+        parts = []
+        if self._base_css:
+            parts.append(self._base_css)
+        used_css = self.get_used_css()
+        if used_css:
+            parts.append(used_css)
+        return "\n\n".join(parts)
+
+    def reset_used_controls(self) -> None:
+        """Reset the set of used controls (call before rendering a new face)."""
+        self._used_controls.clear()
+
+    def _get_jinja_env(self) -> Environment:
+        """Get or create Jinja environment with all template directories."""
+        if self._jinja_env is None:
+            # Templates are loaded directly by path, not by name lookup
+            # So we just need any directory for the loader (it's not used for discovery)
+            template_dirs = [str(self._builtin_dir)]
+
+            self._jinja_env = Environment(
+                loader=FileSystemLoader(template_dirs),
+                autoescape=select_autoescape(["html", "xml"]),
+            )
+
+            # Add custom filters
+            self._jinja_env.filters["js_escape"] = _js_escape_filter
+            self._jinja_env.filters["tojson"] = _tojson_filter
+
+            # Add useful globals
+            self._jinja_env.globals["range"] = range
+
+        return self._jinja_env
+
+
+def _js_escape_filter(s: str) -> str:
+    """Escape string for JavaScript single-quoted string context."""
+    if s is None:
+        return ""
+    return json.dumps(str(s))[1:-1].replace("'", "\\'")
+
+
+def _tojson_filter(obj: Any) -> str:
+    """Convert object to JSON string."""
+    return json.dumps(obj)
+
+
+def _html_escape(s: str) -> str:
+    """HTML escape a string."""
+    import html
+
+    return html.escape(str(s))

dataface/core/render/converters/__init__.py

@@ -0,0 +1,24 @@
+"""Format conversion functions for rendered output.
+
+Stage: RENDER
+Purpose: Convert SVG output to other formats (HTML, PNG, PDF).
+
+This package provides format converters:
+- html.py: SVG to HTML conversion (with wrapper page)
+- png.py: SVG to PNG conversion (using svglib)
+- pdf.py: SVG to PDF conversion (using svglib)
+
+Dependencies:
+    - svglib (optional, for PNG/PDF export)
+    - reportlab (optional, for PNG/PDF export)
+"""
+
+from dataface.core.render.converters.html import to_html
+from dataface.core.render.converters.pdf import to_pdf
+from dataface.core.render.converters.png import to_png
+
+__all__ = [
+    "to_html",
+    "to_png",
+    "to_pdf",
+]

dataface/core/render/converters/chart.py

@@ -0,0 +1,276 @@
+"""Chart output conversion helpers."""
+
+from __future__ import annotations
+
+import base64
+import json
+import re
+from collections.abc import Iterable
+from typing import TYPE_CHECKING, Any
+
+from dataface.core.compile.sizing import DEFAULT_CHART_HEIGHT
+from dataface.core.render.board_links import get_link_context, resolve_href
+from dataface.core.render.chart.artifacts import RenderArtifact
+
+if TYPE_CHECKING:
+    from dataface.core.compile.models.style.merged import MergedStyle
+from dataface.core.render.chart.title_overflow import fix_title_alignment
+from dataface.core.render.converters.pdf import to_pdf
+from dataface.core.render.converters.png import to_png
+from dataface.core.render.errors import ChartDataError, FormatError
+from dataface.core.render.font_support import register_vl_convert_fonts
+
+# Strip sentinel prefix from vl_convert-rendered chart href <a> elements.
+# vl_convert uses xlink:href and mangles relative URLs, so we embed a sentinel
+# prefix that we can detect and strip here. See standard_renderer._HREF_SENTINEL.
+_SENTINEL_HREF_RE = re.compile(r'<a xlink:href="http://dft\.invalid([^"]*)"')
+
+
+def _fix_chart_click_hrefs(svg: str) -> str:
+    """Convert sentinel xlink:href to plain href in SVG <a> elements.
+
+    Converts ``<a xlink:href="http://dft.invalid/path?q=v">``
+    to ``<a href="/path?q=v">`` so variables.js can intercept variable-update
+    clicks and the browser can follow navigation clicks directly.
+
+    When a link context is active (board resolver), board-root paths are
+    rewritten for the current runtime (serve vs Cloud). Query-string-only
+    links (?var=value) pass through unchanged — they are in-page variable
+    updates intercepted by variables.js, not cross-board navigation.
+    """
+    ctx = get_link_context()
+
+    def _replace(m: re.Match[str]) -> str:
+        url = m.group(1)
+        if ctx is not None:
+            url = resolve_href(url, ctx)
+        return f'<a href="{url}"'
+
+    return _SENTINEL_HREF_RE.sub(_replace, svg)
+
+
+# Inject stroke-linecap="round" on legend-symbol <path> elements emitted by
+# vl_convert. Vega-Lite has no spec-level surface for this (probed
+# legend.symbolStrokeCap, config.legend.symbolStrokeCap, config.style.symbol.
+# strokeCap, config.mark.strokeCap — all silently dropped), so the legend's
+# dash segments render with butt caps while the chart lines use round caps
+# (LineStyle theme default). The mismatch is most visible when the dash
+# palette contains a dotted entry: round caps render 0-length dashes as
+# circular dots, butt caps render them as nothing. Match the chart's cap by
+# stamping round onto the legend paths during post-processing — but only on
+# charts that actually use the strokeDash encoding (gated by the caller),
+# so that charts with no dashes keep producing byte-identical SVG output.
+_LEGEND_SYMBOL_LINECAP_RE = re.compile(
+    r'(class="[^"]*role-legend-symbol[^"]*"[^>]*><path)(?![^/]*stroke-linecap)([^/]*?)(/>)'
+)
+
+
+def _fix_legend_symbol_linecap(svg: str) -> str:
+    """Stamp ``stroke-linecap="round"`` onto legend-symbol paths."""
+    return _LEGEND_SYMBOL_LINECAP_RE.sub(r'\1 stroke-linecap="round"\2\3', svg)
+
+
+def _spec_has_encoding(spec: dict[str, Any], channels: Iterable[str]) -> bool:
+    """True when ``spec`` carries any of ``channels`` in an encoding.
+
+    Recurses through ``spec["encoding"]``, ``spec["layer"]``, ``spec["hconcat"]``,
+    and ``spec["vconcat"]`` at every depth — deep enough to catch the
+    endpoint-label-rail wrapper that wraps a layered line chart inside
+    ``hconcat[0]``, and any future nested composition.  Cheap gate used before
+    SVG post-processors so charts that don't use the channel keep producing
+    byte-identical SVG.
+    """
+    channel_set = frozenset(channels)
+
+    def _has(node: dict[str, Any]) -> bool:
+        if channel_set & node.get("encoding", {}).keys():
+            return True
+        for child in node.get("layer", []):
+            if isinstance(child, dict) and _has(child):
+                return True
+        for child in node.get("hconcat", []):
+            if isinstance(child, dict) and _has(child):
+                return True
+        for child in node.get("vconcat", []):
+            if isinstance(child, dict) and _has(child):
+                return True
+        return False
+
+    return _has(spec)
+
+
+def _correct_concat_overshoot(
+    spec: dict[str, Any],
+    target_width: float | None,
+    target_height: float | None,
+    vlc: Any,
+) -> None:
+    """Two-pass width/height correction for hconcat/vconcat endpoint-label specs.
+
+    vl-convert ignores ``autosize: fit`` on concat children, so the first
+    render measures the actual SVG dimensions; the overshoot is subtracted from
+    the resizable pane(s) before the real render.
+
+    Width: hconcat shrinks pane[0] only (label pane is fixed-width). vconcat
+    shrinks both panes — they share the x scale and must resize together so rail
+    labels stay centered.
+
+    Height: hconcat shrinks both panes equally so neither governs a taller total.
+    vconcat height is handled upfront in _wrap_horizontal_top_row_rail, so
+    target_height is not expected on vconcat wrappers.
+    """
+    if target_width is None and target_height is None:
+        return
+    is_hconcat = "hconcat" in spec and spec["hconcat"]
+    is_vconcat = "vconcat" in spec and spec["vconcat"]
+    if not is_hconcat and not is_vconcat:
+        return
+    try:
+        probe_svg = vlc.vegalite_to_svg(spec)
+    except Exception:  # noqa: BLE001, S110 — vl-convert throws untyped JS errors
+        return
+    if target_width is not None:
+        m = re.search(r"<svg[^>]*\bwidth=\"([0-9.]+)\"", probe_svg)
+        if m:
+            overshoot = float(m.group(1)) - float(target_width)
+            if overshoot > 0:
+                width_panes = (
+                    [spec["hconcat"][0]] if is_hconcat else list(spec["vconcat"])
+                )
+                for pane in width_panes:
+                    orig_w = float(pane.get("width", target_width))
+                    new_w = orig_w - overshoot
+                    if new_w > 0:
+                        pane["width"] = new_w
+    if target_height is not None and is_hconcat:
+        m = re.search(r"<svg[^>]*\bheight=\"([0-9.]+)\"", probe_svg)
+        if m:
+            overshoot = float(m.group(1)) - float(target_height)
+            if overshoot > 0:
+                for pane in spec["hconcat"]:
+                    orig_h = float(pane.get("height", target_height))
+                    new_h = orig_h - overshoot
+                    if new_h > 0:
+                        pane["height"] = new_h
+
+
+def render_svg_content(svg_content: str, format: str, *, scale: float = 1.0) -> str:
+    """Convert SVG content to the requested encoded output."""
+    if format == "svg":
+        return svg_content
+    if format == "png":
+        return base64.b64encode(to_png(svg_content, scale=scale)).decode("utf-8")
+    if format == "pdf":
+        return base64.b64encode(to_pdf(svg_content)).decode("utf-8")
+    raise ValueError(f"Unsupported SVG format: {format}")
+
+
+def render_vega_spec(
+    spec: dict[str, Any],
+    format: str,
+    width: float | None,
+    height: float | None,
+    is_placeholder: bool,
+    resolved_style: MergedStyle | None = None,
+) -> str:
+    """Render a Vega-Lite spec into SVG, PNG, or PDF."""
+    try:
+        import vl_convert as vlc
+    except ImportError:
+        raise FormatError(
+            f"vl-convert-python is required for {format} rendering. "
+            "Install with: pip install vl-convert-python",
+        ) from None
+
+    register_vl_convert_fonts(vlc)
+
+    # Two-pass width/height correction for hconcat endpoint-label specs.
+    # vl-convert ignores autosize:fit on concat children, so the first render
+    # measures the actual SVG dimensions; the overshoots are subtracted from
+    # the resizable pane(s) before the real render. Both sentinels are stamped
+    # by _maybe_wrap_endpoint_label_pane and must be popped before rendering.
+    target_width = spec.pop("$df_target_width", None)
+    target_height = spec.pop("$df_target_height", None)
+    if target_width is not None or target_height is not None:
+        _correct_concat_overshoot(spec, target_width, target_height, vlc)
+
+    try:
+        svg_result = vlc.vegalite_to_svg(spec)
+    except Exception as exc:
+        # vl-convert JS errors (e.g. Vega scene-graph TypeErrors on unsupported
+        # layered specs) escape as Python exceptions.  Re-raise as ChartDataError
+        # so render_chart_item records a per-tile error card instead of aborting
+        # the entire dashboard render process.
+        raise ChartDataError(str(exc)) from exc
+    svg_result = _fix_chart_click_hrefs(svg_result)
+    if _spec_has_encoding(spec, ["strokeDash"]):
+        svg_result = _fix_legend_symbol_linecap(svg_result)
+
+    # For hconcat specs (endpoint-label wrapper), padding lives on pane[0], not
+    # the wrapper root — the wrapper has no padding so spec.get("padding") returns
+    # nothing and fix_title_alignment would never run without this lookup.
+    padding = (
+        spec["hconcat"][0].get("padding")
+        if "hconcat" in spec and spec["hconcat"]
+        else spec.get("padding")
+    ) or {}
+    if isinstance(padding, dict):
+        padding_left = float(padding.get("left", 0) or 0)
+    elif isinstance(padding, (int, float)):
+        padding_left = float(padding)
+    else:
+        padding_left = 0.0
+    if padding_left > 0:
+        svg_result = fix_title_alignment(svg_result, padding_left)
+
+    if is_placeholder:
+        from dataface.core.compile.models.primitives import FontStyle
+        from dataface.core.render.placeholder import (
+            add_placeholder_overlay,
+            apply_placeholder_opacity,
+        )
+
+        assert resolved_style is not None
+        chart_width = width or 400
+        chart_height = height or DEFAULT_CHART_HEIGHT
+        svg_result = apply_placeholder_opacity(svg_result)
+        svg_result = add_placeholder_overlay(
+            svg_result,
+            chart_width,
+            chart_height,
+            font=FontStyle(family=resolved_style.font.family),
+        )
+
+    return render_svg_content(svg_result, format, scale=1.0)
+
+
+def render_chart_artifact(
+    artifact: RenderArtifact,
+    format: str,
+    width: float | None,
+    height: float | None,
+    is_placeholder: bool = False,
+    resolved_style: MergedStyle | None = None,
+) -> str:
+    """Render a chart-domain artifact into the requested output format."""
+    if artifact.kind == "json":
+        if format != "json":
+            raise ValueError(f"JSON artifact cannot render as {format}")
+        return json.dumps(artifact.payload, indent=2)
+
+    if artifact.kind == "svg":
+        return render_svg_content(str(artifact.payload), format)
+
+    if artifact.kind == "vega_spec":
+        if not isinstance(artifact.payload, dict):
+            raise ValueError("Vega spec artifact payload must be a dictionary")
+        return render_vega_spec(
+            artifact.payload,
+            format,
+            width,
+            height,
+            is_placeholder=is_placeholder,
+            resolved_style=resolved_style,
+        )
+
+    raise ValueError(f"Unsupported artifact kind: {artifact.kind}")

dataface/core/render/converters/html.py

@@ -0,0 +1,98 @@
+"""HTML format conversion.
+
+Stage: RENDER
+Purpose: Convert SVG output to HTML page with minimal wrapper.
+"""
+
+import html as html_module
+from pathlib import Path
+from typing import Any
+
+from dataface.core.compile.models.face.compiled import Face, VariableValues
+from dataface.core.execute.executor import Executor
+
+_EMOJI_FONT_FACE_PATH = Path(__file__).parent.parent / "fonts" / "_emoji_font_face.css"
+
+
+def to_html(
+    face: Face,
+    svg_content: str,
+    background: str | None,
+    executor: Executor,
+    variables: VariableValues,
+    **options: Any,
+) -> str:
+    """Convert SVG to HTML page with minimal wrapper.
+
+    SVG-First Migration: HTML format now simply wraps SVG output in an HTML
+    document. The SVG already contains:
+    - Interactive variable controls (via foreignObject)
+    - JavaScript for variable interactivity (via <script> tags)
+    - All chart rendering and layout
+
+    This approach:
+    - Eliminates duplicate HTML-specific rendering code paths
+    - Ensures consistent output between SVG and HTML formats
+    - Simplifies maintenance by having a single rendering path
+
+    Args:
+        face: Face being rendered
+        svg_content: The SVG content to wrap
+        background: Background color for the page
+        executor: Executor instance (unused, for API compatibility)
+        variables: Variable values (for title resolution)
+    Returns:
+        Complete HTML document as string
+
+    """
+    from dataface.core.compile.jinja import resolve_jinja_template
+
+    # Resolve title for <title> tag
+    page_title = face.title or "Dataface"
+    page_title = resolve_jinja_template(page_title, variables, strict=False)
+    escaped_title = html_module.escape(page_title)
+
+    font_family = face.resolved_style.font.family
+    emoji_font_face = _EMOJI_FONT_FACE_PATH.read_text()
+
+    page_bg = face.resolved_style.page.background
+    bg_style = f"background-color: {page_bg};" if page_bg else ""
+
+    return f"""<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{escaped_title}</title>
+    <style>
+        {emoji_font_face}
+        * {{
+            box-sizing: border-box;
+        }}
+        body {{
+            margin: 0;
+            padding: 0;
+            font-family: {font_family};
+            {bg_style}
+        }}
+        .dataface-wrapper {{
+            width: 100%;
+            margin: 0 auto;
+        }}
+        .dataface-svg-container {{
+            width: 100%;
+        }}
+        .dataface-svg-container svg {{
+            max-width: 100%;
+            height: auto;
+        }}
+    </style>
+</head>
+<body>
+    <div class="dataface-wrapper">
+        <div class="dataface-svg-container">
+            {svg_content}
+        </div>
+    </div>
+</body>
+</html>"""