dataface 0.1.2__py3-none-any.whl

dataface/core/render/layouts.py

@@ -0,0 +1,541 @@
+"""Layout rendering functions for SVG and HTML.
+
+Stage: RENDER
+Purpose: Render different layout types (rows, cols, grid, tabs) to SVG and HTML.
+
+This module provides functions to render layouts based on their type:
+- Rows: Vertical stacking
+- Cols: Horizontal distribution
+- Grid: Positioned grid cells
+- Tabs: Tabbed container (active tab only for SVG)
+
+Dependencies:
+    - compile.models.face.compiled (Layout, LayoutItem, Face)
+    - compile.models.chart.compiled (Chart)
+    - .renderer (for rendering charts and nested faces)
+
+OPTIMIZATION OPPORTUNITY: Batch Vega-Lite Rendering
+---------------------------------------------------
+Currently, each chart in a layout is rendered individually via separate
+vl-convert calls. This could be optimized by:
+
+1. Collecting all Vega-Lite charts in the layout
+2. Combining them into a single vconcat/hconcat spec
+3. Making ONE vl-convert call for all charts
+4. Extracting individual SVGs from the combined result
+
+Expected improvement: ~30% faster rendering for datafaces with 4+ charts.
+See: plans/archive/VEGA_SVG_BATCH_CONVERSION_ANALYSIS.md
+"""
+
+import html
+from typing import Any
+
+from dataface.core.compile.models.face.compiled import (
+    Face,
+    LayoutItem,
+    ResolvedLayoutItem,
+    VariableValues,
+)
+from dataface.core.compile.models.style.merged import MergedStyle
+from dataface.core.errors import StructuredError
+from dataface.core.execute.executor import Executor
+from dataface.core.render.chart.rendering import render_layout_item
+from dataface.core.render.svg_utils import _px
+
+__all__ = [
+    "is_details_expanded",
+    "render_rows_layout",
+    "render_cols_layout",
+    "render_grid_layout",
+    "render_tabs_layout",
+    "render_details_summary",
+]
+
+
+def _bg_rect(
+    width: float,
+    height: float,
+    fill: str,
+    rx: float = 4,
+    x: float = 0,
+    y: float = 0,
+    stroke: str | None = None,
+    stroke_width: float = 1,
+) -> str:
+    """Return a background rect SVG element."""
+    stroke_attr = (
+        f' stroke="{html.escape(stroke)}" stroke-width="{stroke_width}"'
+        if stroke
+        else ""
+    )
+    return f'<rect x="{x}" y="{y}" width="{width}" height="{height}" fill="{html.escape(fill)}"{stroke_attr} rx="{rx}"/>'
+
+
+def render_rows_layout(
+    items: list[LayoutItem] | tuple[ResolvedLayoutItem, ...],
+    executor: Executor,
+    variables: VariableValues,
+    available_width: float,
+    available_height: float,
+    card_gap: float,
+    gap: float,
+    background: str | None = None,
+    resolved_style: MergedStyle | None = None,
+    interactive: bool = True,
+    render_cache: dict[tuple[str, float, float], tuple[str, float]] | None = None,
+    *,
+    error_collector: list[StructuredError] | None = None,
+    face_level: int = 1,
+    vega_config: dict[str, Any] | None = None,
+) -> tuple[str, float]:
+    """Render items in vertical stack.
+
+    In a rows layout, items stack vertically. Heights are determined by:
+    1. Pre-calculated dimensions from sizing module (preferred)
+    2. Content-aware fallback if not pre-calculated
+
+    Args:
+        items: Layout items to render
+        executor: Executor for query execution
+        variables: Variable values for queries
+        available_width: Available container width
+        available_height: Available container height
+        gap: Gap between items
+        background: Optional background color
+
+    Returns:
+        (svg_elements_string, total_actual_height) — no <svg> wrapper.
+    """
+    if not items:
+        return "", 0.0
+
+    rendered_items: list[str] = []
+    current_y = 0.0
+    actual_total_height = 0.0
+
+    for item in items:
+        # Use pre-calculated item dimensions for the render call.
+        # Actual rendered height is read back from the item SVG.
+        item_height = item.height if item.height > 0 else available_height
+        item_width = item.width if item.width > 0 else available_width
+
+        item_svg, actual_item_height = render_layout_item(
+            item,
+            executor,
+            variables,
+            card_gap=card_gap,
+            available_width=item_width,
+            available_height=item_height,
+            gap=gap,
+            resolved_style=resolved_style,
+            interactive=interactive,
+            render_cache=render_cache,
+            error_collector=error_collector,
+            face_level=face_level,
+            vega_config=vega_config,
+        )
+
+        if item_svg:
+            rendered_items.append(
+                f'<g transform="translate(0, {_px(current_y)})">{item_svg}</g>'
+            )
+            actual_total_height = current_y + actual_item_height
+            current_y += actual_item_height + gap + card_gap
+
+    bg_rect = ""
+    if background:
+        bg_rect = _bg_rect(available_width, actual_total_height, background)
+
+    return f"{bg_rect}\n{''.join(rendered_items)}", actual_total_height
+
+
+def render_cols_layout(
+    items: list[LayoutItem] | tuple[ResolvedLayoutItem, ...],
+    executor: Executor,
+    variables: VariableValues,
+    available_width: float,
+    available_height: float,
+    card_gap: float,
+    gap: float,
+    background: str | None = None,
+    resolved_style: MergedStyle | None = None,
+    interactive: bool = True,
+    render_cache: dict[tuple[str, float, float], tuple[str, float]] | None = None,
+    *,
+    error_collector: list[StructuredError] | None = None,
+    face_level: int = 1,
+    vega_config: dict[str, Any] | None = None,
+) -> tuple[str, float]:
+    """Render items in horizontal distribution.
+
+    Trusts the normalizer for all sizing. Uses pre-calculated item.x, item.width,
+    and item.height values.
+
+    Args:
+        items: Layout items to render (with pre-calculated dimensions from normalizer)
+        executor: Executor for query execution
+        variables: Variable values for queries
+        available_width: Available container width
+        available_height: Available container height (upper bound)
+        gap: Gap between items (unused - normalizer already applied it)
+        background: Optional background color
+
+    Returns:
+        (svg_elements_string, max_actual_item_height) — no <svg> wrapper.
+    """
+    if not items:
+        return "", 0.0
+
+    # Render items using pre-calculated positions from normalizer
+    rendered_items: list[str] = []
+    max_actual_height = 0.0
+
+    for item in items:
+        # Trust normalizer for dimensions
+        item_w = item.width if item.width > 0 else available_width
+        item_h = item.height if item.height > 0 else available_height
+        x_pos = item.x  # Use pre-calculated x position from normalizer
+
+        item_svg, actual_item_height = render_layout_item(
+            item,
+            executor,
+            variables,
+            card_gap=card_gap,
+            available_width=item_w,
+            available_height=item_h,
+            gap=gap,
+            resolved_style=resolved_style,
+            interactive=interactive,
+            render_cache=render_cache,
+            error_collector=error_collector,
+            face_level=face_level,
+            vega_config=vega_config,
+        )
+
+        if item_svg:
+            rendered_items.append(
+                f'<g transform="translate({_px(x_pos)}, 0)">{item_svg}</g>'
+            )
+            max_actual_height = max(max_actual_height, actual_item_height)
+
+    bg_rect = ""
+    if background:
+        bg_rect = _bg_rect(available_width, max_actual_height, background)
+
+    return f"{bg_rect}\n{''.join(rendered_items)}", max_actual_height
+
+
+def render_grid_layout(
+    items: list[LayoutItem] | tuple[ResolvedLayoutItem, ...],
+    executor: Executor,
+    variables: VariableValues,
+    available_width: float,
+    available_height: float,
+    columns: int,
+    card_gap: float,
+    gap: float,
+    background: str | None = None,
+    resolved_style: MergedStyle | None = None,
+    interactive: bool = True,
+    render_cache: dict[tuple[str, float, float], tuple[str, float]] | None = None,
+    *,
+    error_collector: list[StructuredError] | None = None,
+    face_level: int = 1,
+    vega_config: dict[str, Any] | None = None,
+) -> tuple[str, float]:
+    """Render items in positioned grid.
+
+    Grid items have explicit x, y positions and width, height spans.
+    Each item's dimensions are calculated based on the grid columns/rows.
+
+    Args:
+        items: Layout items with grid positions (x, y, width, height)
+        executor: Executor for query execution
+        variables: Variable values for queries
+        available_width: Available container width
+        available_height: Available container height
+        columns: Number of grid columns
+        gap: Gap between grid cells
+        background: Optional background color
+
+    Returns:
+        (svg_elements_string, max_actual_bottom_edge) — no <svg> wrapper.
+    """
+    if not items:
+        return "", 0.0
+
+    # Trust the normalizer - sizing.py calculates all grid positions and dimensions
+    rendered_items: list[str] = []
+    max_bottom_edge = 0.0
+
+    for item in items:
+        # Use pre-calculated pixel positions and dimensions from sizing.py
+        pixel_x = item.x
+        pixel_y = item.y
+        item_w = item.width if item.width > 0 else available_width
+        item_h = item.height if item.height > 0 else available_height
+
+        item_svg, actual_item_height = render_layout_item(
+            item,
+            executor,
+            variables,
+            card_gap=card_gap,
+            available_width=item_w,
+            available_height=item_h,
+            gap=gap,
+            resolved_style=resolved_style,
+            interactive=interactive,
+            render_cache=render_cache,
+            error_collector=error_collector,
+            face_level=face_level,
+            vega_config=vega_config,
+        )
+
+        if item_svg:
+            rendered_items.append(
+                f'<g transform="translate({_px(pixel_x)}, {_px(pixel_y)})">{item_svg}</g>'
+            )
+            max_bottom_edge = max(max_bottom_edge, pixel_y + actual_item_height)
+
+    bg_rect = ""
+    if background:
+        bg_rect = _bg_rect(available_width, max_bottom_edge, background)
+
+    return f"{bg_rect}\n{''.join(rendered_items)}", max_bottom_edge
+
+
+def _build_toggle_url(
+    variables: VariableValues, param_name: str, new_value: str
+) -> str:
+    """Build URL that changes one param while preserving all others.
+
+    Only includes non-default variable values to keep URLs clean.
+    """
+    from urllib.parse import urlencode
+
+    params = {k: str(v) for k, v in variables.items() if v is not None}
+    params[param_name] = new_value
+    return "?" + urlencode(params)
+
+
+def render_tabs_layout(
+    items: list[LayoutItem] | tuple[ResolvedLayoutItem, ...],
+    executor: Executor,
+    variables: VariableValues,
+    available_width: float,
+    available_height: float,
+    card_gap: float = 0.0,
+    tab_titles: list[str] | None = None,
+    tab_slugs: list[str] | None = None,
+    tab_variable: str | None = None,
+    active_tab: int = 0,
+    tab_position: str = "top",
+    background: str | None = None,
+    *,
+    resolved_style: MergedStyle,
+    interactive: bool = True,
+    render_cache: dict[tuple[str, float, float], tuple[str, float]] | None = None,
+    error_collector: list[StructuredError] | None = None,
+    face_level: int = 1,
+    vega_config: dict[str, Any] | None = None,
+) -> tuple[str, float]:
+    """Render tabbed container (active tab only).
+
+    In a tabs layout, each tab gets the full container size minus the tab bar.
+    Only the active tab is rendered in SVG output. The tab bar is rendered as
+    clickable SVG <a href> links that update URL params for server re-rendering.
+
+    Args:
+        items: Layout items (one per tab)
+        executor: Executor for query execution
+        variables: Variable values for queries
+        available_width: Available container width
+        available_height: Available container height
+        tab_titles: Display titles for tabs
+        tab_slugs: URL-safe slugs for tabs (used in URL params)
+        tab_variable: Variable name for tab selection (URL param name)
+        active_tab: Index of active tab (0-based)
+        tab_position: Position of tabs ("top" or "left")
+        background: Optional background color
+
+    Returns:
+        (svg_elements_string, actual_height) — no <svg> wrapper.
+    """
+    if not items:
+        return "", 0.0
+
+    # Resolve active tab from variable value (URL param overrides default)
+    if tab_variable and tab_slugs:
+        var_value = variables.get(tab_variable)
+        if var_value and str(var_value) in tab_slugs:
+            active_tab = tab_slugs.index(str(var_value))
+
+    tabs_config = resolved_style.layout.tabs
+    tab_bar_height = tabs_config.bar_height
+
+    # Render only active tab
+    content_height = (
+        available_height - tab_bar_height if tab_position == "top" else available_height
+    )
+    content_y = tab_bar_height if tab_position == "top" else 0.0
+
+    active_item = items[min(active_tab, len(items) - 1)]
+    item_svg, actual_item_height = render_layout_item(
+        active_item,
+        executor,
+        variables,
+        card_gap=0.0,
+        available_width=available_width,
+        available_height=content_height,
+        resolved_style=resolved_style,
+        interactive=interactive,
+        render_cache=render_cache,
+        error_collector=error_collector,
+        face_level=face_level,
+        vega_config=vega_config,
+    )
+
+    # Compute tab titles once - use provided titles or generate defaults
+    titles = (
+        tab_titles
+        if tab_titles and len(tab_titles) == len(items)
+        else [f"Tab {idx + 1}" for idx in range(len(items))]
+    )
+    slugs = tab_slugs or [f"tab_{idx}" for idx in range(len(items))]
+
+    # Render tab bar as clickable SVG links
+    tab_width = available_width / len(titles)
+    tab_bar_parts: list[str] = []
+    # header_background / row_stripe are optional in the universal default
+    # ("header rule only"). When the theme doesn't define them, fall back
+    # to the page background so the tab chrome still reads as a flat band
+    # rather than emitting fill="" (which browsers treat as invalid →
+    # initial value = black). Mirrors the same fallback in geo.py.
+    _active_fill = (
+        resolved_style.charts.table.header.background or resolved_style.background
+    )
+    _inactive_fill = (
+        resolved_style.charts.table.row.stripe.color
+        if resolved_style.charts.table.row.stripe
+        else None
+    ) or resolved_style.background
+    for idx, (title, slug) in enumerate(zip(titles, slugs, strict=True)):
+        is_active = idx == active_tab
+        x = idx * tab_width
+        weight = tabs_config.active_weight if is_active else tabs_config.inactive_weight
+
+        tab_svg = (
+            f'<rect x="{x}" y="0" width="{tab_width}" height="{tab_bar_height}" '
+            f'fill="{_active_fill if is_active else _inactive_fill}" '
+            f'stroke="{resolved_style.border.color}" stroke-width="{tabs_config.border.width}"/>'
+            f'<text x="{x + tab_width / 2}" y="{tab_bar_height / 2 + tabs_config.title_baseline_offset}" '
+            f'text-anchor="middle" font-size="{tabs_config.font.size}" fill="{resolved_style.title.font.color if is_active else resolved_style.variables.font.color}" '
+            f'font-weight="{weight}">{html.escape(title)}</text>'
+        )
+
+        if tab_variable and not is_active:
+            href = _build_toggle_url(variables, tab_variable, slug)
+            tab_bar_parts.append(f'<a href="{html.escape(href)}">{tab_svg}</a>')
+        else:
+            tab_bar_parts.append(tab_svg)
+
+    tab_bar_svg = "\n".join(tab_bar_parts)
+
+    content_svg = ""
+    if item_svg:
+        content_svg = f'<g transform="translate(0, {_px(content_y)})">{item_svg}</g>'
+
+    actual_height = content_y + actual_item_height
+    bg_rect = ""
+    if background:
+        bg_rect = _bg_rect(available_width, actual_height, background)
+
+    return f"{bg_rect}\n{tab_bar_svg}\n{content_svg}", actual_height
+
+
+def is_details_expanded(
+    item: LayoutItem | ResolvedLayoutItem, variables: VariableValues
+) -> bool:
+    """Check if a details section is expanded based on its variable value.
+
+    Resolution order:
+      1. Live variable value (user has toggled the section, URL overrides).
+      2. `face.meta["details_expanded_default"]` when the item still carries
+         a `Face` (compile-time path used by the primary SVG
+         renderer).
+
+    NOTE: `MergedFace` does not carry `meta`, so a resolved layout item
+    with `details_expanded_default: true` that has not been lifted into a
+    variable default will render collapsed here. In practice the
+    variable-normalization pass (`normalize_variables`) should seed the
+    details variable default from meta so the first branch covers it; if
+    a future call site exercises this with Resolved items and finds details
+    stuck collapsed, wire `details_expanded_default` into
+    `ResolvedLayoutItem` instead of adding a second meta dict.
+    """
+    if item.details_variable in variables:
+        return str(variables[item.details_variable]).lower() == "true"
+    face = item.face
+    if isinstance(face, Face) and face.meta:
+        return bool(face.meta.get("details_expanded_default", False))
+    return False
+
+
+def render_details_summary(
+    item: LayoutItem | ResolvedLayoutItem,
+    variables: VariableValues,
+    available_width: float,
+    expanded: bool | None = None,
+    *,
+    resolved_style: MergedStyle,
+) -> str:
+    """Render a collapsible section's summary bar as clickable SVG.
+
+    The summary bar shows a disclosure triangle (▶/▼) and text.
+    Clicking navigates to a URL that toggles the expanded state.
+
+    Args:
+        item: LayoutItem with details metadata
+        variables: Current variable values (for building toggle URL)
+        available_width: Width of the summary bar
+        expanded: Pre-computed expanded state (avoids recomputing)
+
+    Returns:
+        SVG string for the summary bar
+    """
+    var_name = item.details_variable
+    is_expanded = (
+        expanded if expanded is not None else is_details_expanded(item, variables)
+    )
+    arrow = "▼" if is_expanded else "▶"
+    label = item.details_expanded_summary if is_expanded else item.details_summary
+    new_value = "false" if is_expanded else "true"
+    if not var_name:
+        raise ValueError(
+            "Details summary rendering requires item.details_variable to be set"
+        )
+    href = _build_toggle_url(variables, var_name, new_value)
+
+    # Fall back to page background when the theme doesn't set header fill /
+    # row stripe — see the comment in render_tabs_layout above.
+    _expanded_fill = (
+        resolved_style.charts.table.header.background or resolved_style.background
+    )
+    _collapsed_fill = (
+        resolved_style.charts.table.row.stripe.color
+        if resolved_style.charts.table.row.stripe
+        else None
+    ) or resolved_style.background
+    details_config = resolved_style.layout.details
+    summary_height = float(details_config.summary_height)
+    return (
+        f'<a href="{html.escape(href)}">'
+        f'<rect x="0" y="0" width="{available_width}" height="{summary_height}" '
+        f'fill="{_expanded_fill if is_expanded else _collapsed_fill}" '
+        f'stroke="{resolved_style.border.color}" stroke-width="{details_config.border.width}" rx="{details_config.border.radius}" style="cursor: pointer;"/>'
+        f'<text x="{details_config.arrow.x}" y="{summary_height / 2 + details_config.text_baseline_offset}" font-size="{details_config.arrow.font.size}" fill="{resolved_style.title.font.color}">{arrow}</text>'
+        f'<text x="{details_config.label_x}" y="{summary_height / 2 + details_config.text_baseline_offset}" font-size="{details_config.font.size}" '
+        f'fill="{resolved_style.title.font.color}" font-weight="500">{html.escape(label or "")}</text>'
+        f"</a>"
+    )

dataface/core/render/markdown_defaults.yml

@@ -0,0 +1,16 @@
+markdown:
+  light:
+    text_color: "#1a1a1a"
+    heading_color: "#111111"
+    link_color: "#2563eb"
+    code_color: "#be185d"
+    code_background: "#f3f4f6"
+    blockquote_color: "#6b7280"
+
+  dark:
+    text_color: "#e5e7eb"
+    link_color: "#6eb5ff"
+    code_color: "#f472b6"
+    code_background: "#2a2a3e"
+    blockquote_color: "#aaaaaa"
+    heading_color: "#ffffff"

dataface/core/render/missing_vars_prompt.py

@@ -0,0 +1,79 @@
+"""HTML rendering for the blocking required-variables prompt.
+
+Shared by dft serve (standalone page) and Cloud face viewer (JSON fragment).
+Both surfaces call `render_missing_variables_prompt` to produce the prompt card
+HTML; each surface wraps it in its own chrome and supplies the appropriate
+form action / persistence mechanism.
+"""
+
+from html import escape as _esc
+
+from dataface.core.render.errors import MissingVariable
+
+
+def render_missing_variables_prompt(
+    missing: list[MissingVariable],
+    *,
+    form_action: str,
+    form_method: str = "get",
+) -> str:
+    """Return the blocking prompt card HTML for a list of missing required variables.
+
+    Args:
+        missing: Variables that were absent at render time.
+        form_action: Form action URL. For dft serve this is the face URL (GET).
+            For Cloud the JS overrides submission, so any stable identifier works.
+        form_method: HTML form method ("get" or "post").
+
+    Returns:
+        HTML string for the prompt card (not a full page).
+    """
+    inputs_html = "".join(_variable_input(mv) for mv in missing)
+    return f"""\
+<div class="missing-variables-prompt">
+  <div class="missing-variables-card">
+    <h2>This dashboard requires configuration</h2>
+    <p>The following variable{' is' if len(missing) == 1 else 's are'} required before the dashboard can render.</p>
+    <form class="missing-variables-form" action="{_esc(form_action, quote=True)}" method="{_esc(form_method)}">
+{inputs_html}\
+      <button type="submit" class="missing-variables-submit">Apply</button>
+    </form>
+  </div>
+</div>"""
+
+
+def _variable_input(mv: MissingVariable) -> str:
+    key = _esc(mv.key, quote=True)
+    label = _esc(mv.label or mv.key)
+    description = (
+        f'<p class="missing-var-description">{_esc(mv.description)}</p>'
+        if mv.description
+        else ""
+    )
+    input_type = mv.input_type or "text"
+    # text/number/date map to native HTML primitives that don't need an options
+    # list. Other authored types (select, multiselect, slider, daterange, ...)
+    # need richer MissingVariable metadata that the engine doesn't carry yet —
+    # fall back to a text input AND surface an inline note so the choice is
+    # loud, not silent. Raising would 500 the very surface this prompt exists
+    # to keep alive.
+    if input_type in ("text", "number", "date"):
+        html_type = input_type
+        fallback_note = ""
+    else:
+        html_type = "text"
+        fallback_note = (
+            '<p class="missing-var-description">'
+            f"Variable type {_esc(input_type)} not yet wired through; "
+            "enter the value as plain text."
+            "</p>"
+        )
+    control = f'<input type="{_esc(html_type)}" name="{key}" id="var-{key}" class="missing-var-input" placeholder="{label}" required>'
+    return f"""\
+      <div class="missing-var-field">
+        <label for="var-{key}">{label}</label>
+        {description}
+        {fallback_note}
+        {control}
+      </div>
+"""