dataface 0.1.2__py3-none-any.whl

dataface/core/render/variable_controls.py

@@ -0,0 +1,946 @@
+"""Variable control rendering for SVG/HTML output.
+
+Stage: RENDER
+Purpose: Render interactive and read-only variable controls.
+
+This module provides functions for rendering variable controls in SVG:
+- Interactive controls using foreignObject for HTML form elements
+- Read-only labels for PNG/PDF export
+- JavaScript for variable interactivity
+"""
+
+from __future__ import annotations
+
+import datetime
+import html
+import json
+import logging
+from typing import TYPE_CHECKING, Any
+
+from dataface.core.compile.models.face.compiled import VariableValues
+from dataface.core.compile.models.style.merged import MergedStyle, resolve_cascaded_font
+
+if TYPE_CHECKING:
+    from dataface.core.compile.models.variable.authored import Variable
+
+from dataface.core.compile.jinja import resolve_jinja_template
+from dataface.core.compile.models.query.compiled import SqlQuery
+from dataface.core.compile.models.style.compiled import font_weight_as_css
+from dataface.core.compile.models.variable.authored import SingleRowBoolProbe
+from dataface.core.compile.sizing import compute_variable_controls_height
+from dataface.core.execute.executor import Executor
+from dataface.core.render.script_embedding import (
+    embed_svg_script,
+)
+from dataface.core.render.text.case import format_display_text
+from dataface.core.render.utils import is_valid_sql_identifier
+from dataface.core.render.variable_input_refinement import refine_input_type_from_data
+
+logger = logging.getLogger(__name__)
+
+_READ_ONLY_UNSET_SELECT = "All"
+_READ_ONLY_UNSET_DATERANGE = "All dates"
+
+
+def _read_only_unset_label(var_def: Variable, *, default: str) -> str:
+    if var_def.placeholder:
+        return var_def.placeholder
+    return default
+
+
+def _select_value_is_unset(value: Any) -> bool:
+    return value is None or value == ""
+
+
+def _daterange_is_unset(value: Any) -> bool:
+    if value is None:
+        return True
+    if not isinstance(value, (list, tuple)):
+        return False
+    if len(value) != 2:
+        return False
+    return value[0] in (None, "") or value[1] in (None, "")
+
+
+def format_variable_display_value(var_def: Variable, value: Any) -> str:
+    """Human-readable filter state for read-only variable strips (PNG/PDF/static SVG)."""
+    input_type = var_def.input
+
+    if input_type in ("select", "radio"):
+        if _select_value_is_unset(value):
+            return _read_only_unset_label(var_def, default=_READ_ONLY_UNSET_SELECT)
+        return str(value)
+
+    if input_type == "multiselect":
+        if value is None or value == []:
+            return _read_only_unset_label(var_def, default=_READ_ONLY_UNSET_SELECT)
+        if not isinstance(value, (list, tuple)):
+            raise ValueError(
+                f"multiselect variable expects a list, got {type(value).__name__}"
+            )
+        return ", ".join(str(v) for v in value)
+
+    if input_type == "daterange":
+        if _daterange_is_unset(value):
+            return _read_only_unset_label(var_def, default=_READ_ONLY_UNSET_DATERANGE)
+        if not isinstance(value, (list, tuple)):
+            raise ValueError(
+                f"daterange variable expects a 2-element list, got {type(value).__name__}"
+            )
+        if len(value) != 2:
+            raise ValueError(
+                f"daterange variable expects exactly 2 elements, got {len(value)}"
+            )
+        start, end = value[0], value[1]
+        if start in (None, "") or end in (None, ""):
+            return _read_only_unset_label(var_def, default=_READ_ONLY_UNSET_DATERANGE)
+        return _format_daterange_label(str(start), str(end))
+
+    if input_type == "checkbox":
+        if value is None:
+            return "No"
+        if isinstance(value, str):
+            return "Yes" if value.lower().strip() in ("true", "yes", "1") else "No"
+        return "Yes" if value else "No"
+
+    if input_type in (
+        "text",
+        "input",
+        "textarea",
+        "number",
+        "slider",
+        "range",
+        "date",
+        "datepicker",
+    ):
+        if value is None or value == "":
+            return var_def.placeholder or ""
+        return str(value)
+
+    if input_type == "auto":
+        raise ValueError(
+            "read-only variable display requires a resolved input type, not 'auto'"
+        )
+
+    raise ValueError(
+        f"unsupported variable input type for read-only display: {input_type!r}"
+    )
+
+
+def render_variables_svg(
+    variable_defs: dict[str, Any],
+    current_values: VariableValues,
+    width: float,
+    *,
+    resolved_style: MergedStyle,
+) -> tuple[str, float]:
+    """Render variables as read-only labels in SVG.
+
+    Used for PNG/PDF export where foreignObject is not supported.
+
+    Args:
+        variable_defs: Dictionary of variable definitions
+        current_values: Current variable values
+        width: Available width
+        resolved_style: MergedStyle for color and font resolution.
+
+    Returns:
+        Tuple of (SVG string, height used)
+    """
+    if not variable_defs:
+        return "", 0.0
+
+    variables_style = resolved_style.variables
+    _font_family = variables_style.label.font.family
+    assert (
+        _font_family is not None
+    ), "cascade should have populated variables.label.font.family"
+
+    _var_font_size = variables_style.font.size
+    assert _var_font_size is not None, "style.variables.font.size must be configured"
+    font_size = float(_var_font_size)
+    line_height = variables_style.line_height
+    padding = variables_style.padding
+    font_family = html.escape(str(_font_family))
+    items: list[str] = []
+    current_x = 0.0
+    current_y = font_size + padding
+
+    for var_name, var_def in variable_defs.items():
+        current_value = current_values.get(var_name, var_def.default)
+        display_value = format_variable_display_value(var_def, current_value)
+
+        label = var_def.label or format_display_text(
+            var_name,
+            from_slug=True,
+            font=resolve_cascaded_font(
+                variables_style.label.font, "variables.label.font"
+            ),
+        )
+        escaped_label = html.escape(label)
+        escaped_value = html.escape(display_value)
+
+        # Create label: value text
+        label_text = f"{escaped_label}:"
+        value_text = f" {escaped_value}"
+
+        # Estimate width (rough calculation)
+        label_width = len(label_text) * font_size * 0.6
+        value_width = len(value_text) * font_size * 0.55
+
+        # Check if we need to wrap to next line
+        if current_x + label_width + value_width > width and current_x > 0:
+            current_x = 0
+            current_y += line_height
+
+        label_weight_raw = variables_style.label.font.weight
+        assert (
+            label_weight_raw is not None
+        ), "cascade should have populated variables.label.font.weight"
+        label_weight = font_weight_as_css(label_weight_raw)
+        # Render the label and value with theme-appropriate colors
+        items.append(
+            f'<text x="{current_x}" y="{current_y}" font-size="{font_size}" fill="{resolved_style.variables.font.color}" '
+            f'font-family="{font_family}">'
+            f'<tspan font-weight="{label_weight}">{label_text}</tspan>'
+            f'<tspan fill="{resolved_style.font.color}">{value_text}</tspan>'
+            f"</text>"
+        )
+
+        current_x += label_width + value_width + variables_style.gap
+
+    if not items:
+        return "", 0.0
+
+    total_height = current_y + padding
+    svg_content = "\n".join(items)
+
+    # Wrap in a rect background with theme color
+    return (
+        f'<rect x="0" y="0" width="{width}" height="{total_height}" fill="{resolved_style.variables.input.background}" rx="{variables_style.border.radius}"/>'
+        f"{svg_content}",
+        total_height,
+    )
+
+
+def resolve_query_options_for_svg(
+    query_ref: str, executor: Executor, variables: dict[str, Any]
+) -> list[str]:
+    """Resolve options from a named query for SVG rendering.
+
+    Args:
+        query_ref: Query name reference (e.g., "queries.city_options" or "city_options")
+        executor: Executor for running queries
+        variables: Current variable values for query execution
+
+    Returns:
+        List of option values from the query
+    """
+    try:
+        # Strip "queries." prefix if present
+        query_name = query_ref.replace("queries.", "")
+
+        # Execute the query
+        result = executor.execute_query(query_name, variables)
+
+        if result and len(result) > 0:
+            # Look for 'value' column first, then 'label', then first column
+            first_row = result[0]
+            value_key = None
+            for key in ["value", "label", "name", "id"]:
+                if key in first_row:
+                    value_key = key
+                    break
+            if value_key is None:
+                value_key = list(first_row.keys())[0]
+
+            return [
+                str(row[value_key]) for row in result if row.get(value_key) is not None
+            ]
+
+        return []
+    except (ValueError, KeyError, TypeError, RuntimeError):
+        # Log as warning with context to make failures visible for debugging
+        # Don't raise to keep rendering, but make the failure actionable
+        logger.warning(
+            "Failed to resolve query options for SVG variable control",
+            exc_info=True,
+        )
+        return []
+
+
+def resolve_column_options_for_svg(column_ref: str, executor: Executor) -> list[str]:
+    """Resolve distinct values from a column for variable options in SVG.
+
+    For column binding to work, the table must be defined in sources or be
+    an actual database table. For CSV-based data loaded via read_csv(),
+    use options.query with a dedicated query instead.
+
+    Args:
+        column_ref: Column reference in format "table.column" or just "column"
+        executor: Executor for running queries
+
+    Returns:
+        List of distinct values from the column, or empty list if unavailable
+    """
+    try:
+        # Parse the column reference (table.column or just column)
+        if "." not in column_ref:
+            return []
+
+        table_name, column_name = column_ref.rsplit(".", 1)
+
+        # Validate identifiers to prevent SQL injection
+        if not is_valid_sql_identifier(table_name) or not is_valid_sql_identifier(
+            column_name
+        ):
+            logger.warning(f"Invalid SQL identifier in column reference: {column_ref}")
+            return []
+
+        # Build a query to get distinct values
+        sql = f"SELECT DISTINCT {column_name} FROM {table_name} ORDER BY {column_name}"
+
+        try:
+            result = executor.adapter_registry.execute(SqlQuery(sql=sql))
+            if result.is_success and result.data:
+                first_key = list(result.data[0].keys())[0]
+                if first_key:
+                    return [
+                        str(row[first_key])
+                        for row in result.data
+                        if row[first_key] is not None
+                    ]
+        except (ValueError, KeyError, TypeError, RuntimeError):
+            # Column binding requires the table to exist in the database
+            # For CSV-based data, use options.query instead
+            logger.warning(
+                f"Failed to bind column '{column_ref}' for variable options. "
+                "For CSV-based data, use options.query instead.",
+                exc_info=True,
+            )
+
+        return []
+    except (ValueError, KeyError, TypeError):
+        logger.warning(
+            "Failed to resolve column options for SVG variable control",
+            exc_info=True,
+        )
+        return []
+
+
+def render_interactive_variables_svg(
+    variable_defs: dict[str, Any],
+    current_values: VariableValues,
+    width: float,
+    executor: Executor | None = None,
+    *,
+    resolved_style: MergedStyle,
+) -> tuple[str, float]:
+    """Render interactive variable controls in SVG using foreignObject.
+
+    Uses real HTML form elements embedded via foreignObject for:
+    - Native keyboard/accessibility support
+    - Mobile-friendly controls
+    - Less custom code to maintain
+
+    Variables with visible=False are filtered out and not rendered.
+
+    Args:
+        variable_defs: Dictionary of variable definitions
+        current_values: Current variable values
+        width: Available width
+        executor: Executor for resolving query-based options
+        resolved_style: MergedStyle for color and font resolution.
+
+    Returns:
+        Tuple of (SVG string with foreignObject, height used)
+    """
+    if not variable_defs:
+        return "", 0.0
+
+    # Filter out non-visible variables — they can be used in queries but not rendered
+    visible_defs = {
+        name: var_def for name, var_def in variable_defs.items() if var_def.visible
+    }
+
+    if not visible_defs:
+        return "", 0.0
+
+    # Use filtered visible_defs for rendering
+    variable_defs = visible_defs
+
+    variables_style = resolved_style.variables
+    _font_family = variables_style.label.font.family
+    assert (
+        _font_family is not None
+    ), "cascade should have populated variables.label.font.family"
+
+    height = compute_variable_controls_height(
+        variable_defs, width, variables_style=resolved_style.variables
+    )
+    font_family = html.escape(str(_font_family))
+
+    # Build HTML controls.
+    # Shared icon symbols (e.g. calendar for daterange) are prepended once so
+    # multiple daterange controls on the same face don't duplicate the id.
+    controls_html: list[str] = []
+    icons_html = generate_svg_variable_icons(variable_defs)
+    if icons_html:
+        controls_html.append(icons_html)
+    for var_name, var_def in variable_defs.items():
+        control = render_html_control_for_svg(
+            var_name,
+            var_def,
+            current_values,
+            executor,
+            resolved_style=resolved_style,
+        )
+        controls_html.append(control)
+
+    label_font = variables_style.label.font
+    label_color = label_font.color
+    assert (
+        label_color is not None
+    ), "cascade should have populated variables.label.font.color"
+    label_weight_raw = label_font.weight
+    assert (
+        label_weight_raw is not None
+    ), "cascade should have populated variables.label.font.weight"
+    label_weight = font_weight_as_css(label_weight_raw)
+    label_size_raw = label_font.size
+    assert (
+        label_size_raw is not None
+    ), "cascade should have populated variables.label.font.size"
+    value_font = variables_style.value.font
+    value_weight_raw = value_font.weight
+    assert (
+        value_weight_raw is not None
+    ), "cascade should have populated variables.value.font.weight"
+    value_weight = font_weight_as_css(value_weight_raw)
+    value_color = value_font.color
+    assert (
+        value_color is not None
+    ), "cascade should have populated variables.value.font.color"
+    value_family_raw = value_font.family
+    assert (
+        value_family_raw is not None
+    ), "cascade should have populated variables.value.font.family"
+    value_family = html.escape(str(value_family_raw))
+    value_size_raw = value_font.size
+    assert (
+        value_size_raw is not None
+    ), "cascade should have populated variables.value.font.size"
+    value_numeric_variant = variables_style.value.numeric_variant
+    placeholder_color = variables_style.placeholder.font.color
+    assert (
+        placeholder_color is not None
+    ), "cascade should have populated variables.placeholder.font.color"
+    accent = resolved_style.accent
+    # Semi-transparent focus ring derived from accent color.
+    # Inline hex/rgb8 → rgba string so we don't pull in a color library.
+    focus_ring = f"color-mix(in srgb, {accent} 25%, transparent)"
+
+    # Wrap in foreignObject with proper namespace using theme colors.
+    # CSS custom properties on .dft-variables are consumed by controls/_styles.css
+    # (included in svg/styles.css) for hover, focus, disabled interaction states.
+    # overflow:visible on the foreignObject lets absolute-positioned popovers (daterange
+    # chip) escape the element's clipping rectangle in Chromium and Safari.
+    _vars = resolved_style.variables
+    # Title-inline packs controls against the right edge of the band so they
+    # sit flush with the board's right margin opposite the title. Other
+    # positions (top/bottom) leave them flex-start so they flow naturally from
+    # the leading edge of the content area.
+    _justify = (
+        "flex-end" if variables_style.position == "title-inline" else "flex-start"
+    )
+    svg = f"""<foreignObject x="0" y="0" width="{width}" height="{height}" style="overflow: visible;">
+  <div xmlns="http://www.w3.org/1999/xhtml" class="dft-variables"
+       style="display: flex; flex-wrap: wrap; justify-content: {_justify}; gap: {variables_style.gap}px; align-items: center;
+              background: {_vars.input.background}; padding: {variables_style.padding}px {variables_style.container_padding}px; border-radius: {variables_style.border.radius}px;
+              font-size: {variables_style.font.size}px; box-sizing: border-box; height: 100%;
+              overflow: visible;
+              --dft-font-family: {font_family};
+              --dft-label-color: {label_color};
+              --dft-label-weight: {label_weight};
+              --dft-label-size: {label_size_raw}px;
+              --dft-text-color: {resolved_style.font.color};
+              --dft-value-color: {value_color};
+              --dft-value-family: {value_family};
+              --dft-value-size: {value_size_raw}px;
+              --dft-value-weight: {value_weight};
+              --dft-value-numeric-variant: {value_numeric_variant};
+              --dft-placeholder-color: {placeholder_color};
+              --dft-input-bg: {_vars.input.background};
+              --dft-input-border: {_vars.border.color};
+              --dft-accent-color: {accent};
+              --dft-focus-ring: {focus_ring};
+              --dft-muted-color: {_vars.font.color};
+              --dft-popover-rail-bg: {_vars.popover_rail_background};">
+    {"".join(controls_html)}
+  </div>
+</foreignObject>"""
+    return svg, height
+
+
+def _resolve_option_values(
+    var_def: Variable,
+    executor: Executor | None,
+    current_values: dict[str, Any],
+) -> list[str]:
+    """Resolve option values from static list, query, or column binding."""
+    if var_def.options and var_def.options.static:
+        return [str(opt) for opt in var_def.options.static]
+    if var_def.options and var_def.options.query and executor:
+        return resolve_query_options_for_svg(
+            var_def.options.query, executor, current_values
+        )
+    if var_def.options and var_def.options.column and executor:
+        return resolve_column_options_for_svg(var_def.options.column, executor)
+    if var_def.column and executor:
+        return resolve_column_options_for_svg(var_def.column, executor)
+    return []
+
+
+def _coerce_bool(value: Any) -> bool:
+    """Coerce value to bool; raise ValueError for unrecognized inputs."""
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, (int, float)):
+        if value == 1:
+            return True
+        if value == 0:
+            return False
+    if isinstance(value, str):
+        lower = value.strip().lower()
+        if lower in ("true", "1", "yes"):
+            return True
+        if lower in ("false", "0", "no"):
+            return False
+    raise ValueError(f"Cannot coerce {value!r} to bool; expected true/false/1/0/yes/no")
+
+
+def _eval_bool_condition(
+    expr: bool | str | SingleRowBoolProbe | None,
+    *,
+    if_none: bool,
+    current_values: dict[str, Any],
+    executor: Executor | None,
+    context: str,
+) -> bool:
+    """Evaluate a bool/str/probe condition and return the result.
+
+    Shared core for Variable.disabled and LayoutItem.visible; callers pass
+    ``if_none`` to control the meaning of a missing (None) value.
+
+    - None: return ``if_none`` (disabled → False, visible → True).
+    - bool: return as-is.
+    - str: auto-wrap in ``{{ }}`` if needed, evaluate as Jinja, coerce to bool.
+    - SingleRowBoolProbe: execute the named query; expect exactly 1 row; coerce
+      the named column to bool.
+
+    Args:
+        expr: The condition value (from YAML or a compiled model field).
+        if_none: Value to return when expr is None.
+        current_values: Current variable values for Jinja resolution.
+        executor: Required when expr is a SingleRowBoolProbe.
+        context: Human-readable label for error messages (e.g. "Variable 'region' disabled").
+
+    Raises:
+        ValueError: Wrong row count, missing column, non-bool-coercible value, or
+            no executor for a query-backed condition.
+    """
+    if expr is None:
+        return if_none
+    if isinstance(expr, bool):
+        return expr
+    if isinstance(expr, str):
+        # Auto-wrap bare variable names / Jinja expressions (no {{ }} required).
+        jinja_expr = expr if "{{" in expr else f"{{{{ {expr} }}}}"
+        rendered = resolve_jinja_template(jinja_expr, variables=current_values)
+        return _coerce_bool(rendered)
+    if isinstance(expr, SingleRowBoolProbe):
+        if executor is None:
+            raise ValueError(
+                f"{context} query '{expr.query}' requires an executor but none was provided"
+            )
+        rows = executor.execute_query(expr.query, current_values)
+        if not rows:
+            raise ValueError(
+                f"{context} query '{expr.query}' returned no rows; expected exactly 1"
+            )
+        if len(rows) > 1:
+            raise ValueError(
+                f"{context} query '{expr.query}' returned {len(rows)} rows; expected exactly 1"
+            )
+        row = rows[0]
+        if expr.column not in row:
+            raise ValueError(
+                f"{context} query '{expr.query}' has no column '{expr.column}'; "
+                f"available: {list(row.keys())}"
+            )
+        return _coerce_bool(row[expr.column])
+    raise TypeError(f"unsupported visible/disabled value: {expr!r}")
+
+
+def _evaluate_disabled(
+    var_def: Variable,
+    current_values: dict[str, Any],
+    executor: Executor | None,
+) -> bool:
+    """Return True when the variable control should be disabled."""
+    return _eval_bool_condition(
+        var_def.disabled,
+        if_none=False,
+        current_values=current_values,
+        executor=executor,
+        context="Variable disabled",
+    )
+
+
+def evaluate_visible(
+    expr: bool | str | SingleRowBoolProbe | None,
+    current_values: dict[str, Any],
+    executor: Executor | None,
+    context: str = "layout item",
+) -> bool:
+    """Return True when the layout item should be rendered.
+
+    Args:
+        expr: The visible value from the layout item.
+        current_values: Current variable values for Jinja resolution.
+        executor: Required when expr is a SingleRowBoolProbe.
+        context: Human-readable label for error messages (e.g. "layout item 'kpi_a'").
+    """
+    return _eval_bool_condition(
+        expr,
+        if_none=True,
+        current_values=current_values,
+        executor=executor,
+        context=f"{context} visible",
+    )
+
+
+_MONTHS_SHORT = [
+    "Jan",
+    "Feb",
+    "Mar",
+    "Apr",
+    "May",
+    "Jun",
+    "Jul",
+    "Aug",
+    "Sep",
+    "Oct",
+    "Nov",
+    "Dec",
+]
+
+
+def _format_daterange_label(start_iso: str, end_iso: str) -> str:
+    """Human-readable chip label from ISO date strings.
+
+    Mirrors JS formatRange() so the server-rendered initial label matches
+    what the client renders post-interaction. Falls back to raw ISO on parse error.
+    """
+    try:
+        s = datetime.date.fromisoformat(start_iso)
+        e = datetime.date.fromisoformat(end_iso)
+    except ValueError:
+        return f"{start_iso} – {end_iso}"
+
+    def fmt(d: datetime.date) -> str:
+        return f"{d.day} {_MONTHS_SHORT[d.month - 1]} {d.year}"
+
+    def fmt_no_yr(d: datetime.date) -> str:
+        return f"{d.day} {_MONTHS_SHORT[d.month - 1]}"
+
+    if s == e:
+        return fmt(s)
+    if s.year == e.year and s.month == e.month:
+        return f"{s.day}–{e.day} {_MONTHS_SHORT[s.month - 1]} {s.year}"
+    if s.year == e.year:
+        return f"{fmt_no_yr(s)} – {fmt(e)}"
+    return f"{fmt(s)} – {fmt(e)}"
+
+
+def render_html_control_for_svg(
+    var_name: str,
+    var_def: Variable,
+    current_values: dict[str, Any],
+    executor: Executor | None = None,
+    *,
+    resolved_style: MergedStyle,
+) -> str:
+    """Render a single HTML form control for embedding in SVG foreignObject.
+
+    Colors come from CSS custom properties on the .dft-variables container
+    (set by render_interactive_variables_svg); per-instance widths/padding
+    are still inline.
+
+    Args:
+        var_name: Variable name
+        var_def: Variable definition object
+        current_values: Current variable values dict
+        executor: Executor for resolving query-based options
+        resolved_style: Resolved style for visual properties
+
+    Returns:
+        HTML string for the control
+    """
+    variables_style = resolved_style.variables
+
+    input_config = variables_style.input
+    control_gap = variables_style.control_gap
+    input_padding = input_config.padding
+    input_border_radius = input_config.border.radius
+
+    current = current_values.get(var_name, var_def.default)
+    label = var_def.label or format_display_text(
+        var_name,
+        from_slug=True,
+        font=resolve_cascaded_font(variables_style.label.font, "variables.label.font"),
+    )
+    escaped_label = html.escape(label)
+    description = var_def.description
+    description_attr = f' title="{html.escape(description)}"' if description else ""
+    # Use html.escape for HTML attribute context (name, data-variable)
+    escaped_name = html.escape(var_name)
+    # Use json.dumps for JavaScript string context, then escape single quotes
+    # since we use single-quoted JS strings in HTML attributes
+    js_safe_name = json.dumps(var_name)[1:-1].replace(
+        "'", "\\'"
+    )  # Escape for JS single-quoted strings
+
+    # Build data attribute for variable dependencies (for cascading dropdowns)
+    # This tells the UI which other variables this variable depends on
+    depends_on_attr = ""
+    if var_def.variable_dependencies:
+        deps_list = sorted(var_def.variable_dependencies)
+        deps_json = json.dumps(deps_list)
+        depends_on_attr = f' data-depends-on="{html.escape(deps_json)}"'
+
+    # Evaluate disabled state before building any HTML.
+    is_disabled = _evaluate_disabled(var_def, current_values, executor)
+    disabled_attr = " disabled" if is_disabled else ""
+    disabled_wrapper_attrs = (
+        ' aria-disabled="true" data-disabled="true"' if is_disabled else ""
+    )
+
+    input_type = var_def.input
+
+    # Slider bounds from data-aware refinement (set below, used in slider branch)
+    slider_min_override: int | float | None = None
+    slider_max_override: int | float | None = None
+    slider_step_override: int | float | None = None
+
+    # Resolve options for select/multiselect — needed for both rendering and
+    # data-aware type refinement
+    option_values: list[str] = []
+    if input_type in ("select", "multiselect"):
+        option_values = list(
+            dict.fromkeys(_resolve_option_values(var_def, executor, current_values))
+        )
+
+        # Data-aware refinement: inspect resolved options to pick a better widget
+        if var_def.input_auto_detected and option_values:
+            refined = refine_input_type_from_data(var_def, option_values)
+            input_type = refined.input_type
+            # Apply auto-computed slider bounds (without mutating the compiled var_def)
+            if refined.slider_min is not None:
+                slider_min_override = refined.slider_min
+                slider_max_override = refined.slider_max
+                slider_step_override = refined.slider_step
+
+    if input_type in ("select", "multiselect"):
+        options = ['<option value="">-- All --</option>']
+
+        is_placeholder = current is None or current == ""
+        for opt in option_values:
+            escaped_opt = html.escape(opt)
+            selected = " selected" if str(current) == opt else ""
+            options.append(
+                f'<option value="{escaped_opt}"{selected}>{escaped_opt}</option>'
+            )
+        placeholder_attr = ' data-placeholder="true"' if is_placeholder else ""
+
+        return f"""<div class="variable-control dft-variable" data-variable-id="{escaped_name}" data-variable-label="{escaped_label}"{depends_on_attr}{description_attr}{disabled_wrapper_attrs} style="display: flex; align-items: center; gap: {control_gap}px;">
+  <label class="dft-variable-label">{escaped_label}:</label>
+  <select name="{escaped_name}" class="dft-variable-input" data-variable="{escaped_name}" onchange="updateVariable('{js_safe_name}', this.value)"{disabled_attr}{placeholder_attr}
+          style="padding: {input_padding.top}px {input_padding.right}px; border-radius: {input_border_radius}px; font-size: {variables_style.font.size}px;">
+    {"".join(options)}
+  </select>
+</div>"""
+
+    elif input_type == "checkbox":
+        # Handle string booleans from data-aware refinement (select → checkbox)
+        if isinstance(current, str):
+            current = current.lower().strip() in ("true", "yes", "1")
+        checked = " checked" if current else ""
+        return f"""<div class="variable-control dft-variable" data-variable-id="{escaped_name}" data-variable-label="{escaped_label}"{depends_on_attr}{description_attr}{disabled_wrapper_attrs} style="display: flex; align-items: center; gap: {control_gap}px; cursor: pointer;">
+  <input type="checkbox" name="{escaped_name}" class="dft-variable-input" data-variable="{escaped_name}"
+         onchange="updateVariable('{js_safe_name}', this.checked)"{checked}{disabled_attr}
+         style="width: {input_config.widths.checkbox}px; height: {input_config.widths.checkbox}px;"/>
+  <span class="dft-variable-label">{escaped_label}</span>
+</div>"""
+
+    elif input_type in ("slider", "range"):
+        # Data-aware overrides (all-or-none from RefinedType) take precedence
+        if slider_min_override is not None:
+            min_val = slider_min_override
+            max_val = slider_max_override
+            step_val = slider_step_override
+        else:
+            min_val = (
+                var_def.min
+                if var_def.min is not None
+                else input_config.range.default_min
+            )
+            max_val = (
+                var_def.max
+                if var_def.max is not None
+                else input_config.range.default_max
+            )
+            step_val = (
+                var_def.step
+                if var_def.step is not None
+                else input_config.range.default_step
+            )
+        raw_value = current if current is not None else min_val
+        # Escape value for HTML attribute context to prevent XSS
+        escaped_value = html.escape(str(raw_value))
+        return f"""<div class="variable-control dft-variable" data-variable-id="{escaped_name}" data-variable-label="{escaped_label}"{depends_on_attr}{description_attr}{disabled_wrapper_attrs} style="display: flex; align-items: center; gap: {control_gap}px;">
+  <label class="dft-variable-label">{escaped_label}:</label>
+  <input type="range" name="{escaped_name}" class="dft-variable-input" data-variable="{escaped_name}"
+         min="{min_val}" max="{max_val}" step="{step_val}" value="{escaped_value}"
+         oninput="this.nextElementSibling.textContent = this.value"
+         onchange="updateVariable('{js_safe_name}', this.value)"{disabled_attr}
+         style="width: {input_config.widths.range}px;"/>
+  <span class="dft-variable-slider-value" style="min-width: {input_config.widths.slider_value_min}px;">{escaped_value}</span>
+</div>"""
+
+    elif input_type in ("text", "input"):
+        value = html.escape(str(current or ""))
+        placeholder_attr = (
+            ' data-placeholder="true"' if current is None or current == "" else ""
+        )
+        return f"""<div class="variable-control dft-variable" data-variable-id="{escaped_name}" data-variable-label="{escaped_label}"{depends_on_attr}{description_attr}{disabled_wrapper_attrs} style="display: flex; align-items: center; gap: {control_gap}px;">
+  <label class="dft-variable-label">{escaped_label}:</label>
+  <input type="text" name="{escaped_name}" class="dft-variable-input" data-variable="{escaped_name}" value="{value}"
+         onchange="updateVariable('{js_safe_name}', this.value)"{disabled_attr}{placeholder_attr}
+         style="padding: {input_padding.top}px {input_padding.right}px; border-radius: {input_border_radius}px; width: {input_config.widths.text}px;"/>
+</div>"""
+
+    elif input_type == "number":
+        # Escape value for HTML attribute context to prevent XSS
+        value = html.escape(str(current)) if current is not None else ""
+        placeholder_attr = ' data-placeholder="true"' if current is None else ""
+        min_attr = f' min="{var_def.min}"' if var_def.min is not None else ""
+        max_attr = f' max="{var_def.max}"' if var_def.max is not None else ""
+        step_attr = f' step="{var_def.step}"' if var_def.step is not None else ""
+        return f"""<div class="variable-control dft-variable" data-variable-id="{escaped_name}" data-variable-label="{escaped_label}"{depends_on_attr}{description_attr}{disabled_wrapper_attrs} style="display: flex; align-items: center; gap: {control_gap}px;">
+  <label class="dft-variable-label">{escaped_label}:</label>
+  <input type="number" name="{escaped_name}" class="dft-variable-input" data-variable="{escaped_name}" value="{value}"{min_attr}{max_attr}{step_attr}
+         onchange="updateVariable('{js_safe_name}', this.value)"{disabled_attr}{placeholder_attr}
+         style="padding: {input_padding.top}px {input_padding.right}px; border-radius: {input_border_radius}px; width: {input_config.widths.number}px;"/>
+</div>"""
+
+    elif input_type in ("date", "datepicker"):
+        # Escape value for HTML attribute context to prevent XSS
+        value = html.escape(str(current or ""))
+        placeholder_attr = (
+            ' data-placeholder="true"' if current is None or current == "" else ""
+        )
+        return f"""<div class="variable-control dft-variable" data-variable-id="{escaped_name}" data-variable-label="{escaped_label}"{depends_on_attr}{description_attr}{disabled_wrapper_attrs} style="display: flex; align-items: center; gap: {control_gap}px;">
+  <label class="dft-variable-label">{escaped_label}:</label>
+  <input type="date" name="{escaped_name}" class="dft-variable-input" data-variable="{escaped_name}" value="{value}"
+         onchange="updateVariable('{js_safe_name}', this.value)"{disabled_attr}{placeholder_attr}
+         style="padding: {input_padding.top}px {input_padding.right}px; border-radius: {input_border_radius}px;"/>
+</div>"""
+
+    elif input_type == "daterange":
+        # Resolve initial chip state from pre-loaded values.
+        start_value = ""
+        end_value = ""
+        if isinstance(current, list) and len(current) >= 2:
+            start_value = html.escape(str(current[0]))
+            end_value = html.escape(str(current[1]))
+        chip_active = bool(start_value and end_value)
+        chip_label = (
+            _format_daterange_label(start_value, end_value)
+            if chip_active
+            else _READ_ONLY_UNSET_DATERANGE
+        )
+        chip_state = 'data-active="true"' if chip_active else 'data-placeholder="true"'
+
+        return f"""<div class="variable-control dft-variable" data-variable-id="{escaped_name}" data-variable-label="{escaped_label}"{depends_on_attr}{description_attr}{disabled_wrapper_attrs} style="display: flex; align-items: center; gap: {control_gap}px;">
+  <label class="dft-variable-label">{escaped_label}:</label>
+  <div class="dft-chip-host">
+    <button type="button" class="dft-chip" data-variable="{escaped_name}" {chip_state} aria-haspopup="true" aria-expanded="false"{disabled_attr}>
+      <span class="dft-chip-icon" aria-hidden="true">
+        <svg width="16" height="16"><use href="#dft-icon-calendar"/></svg>
+      </span>
+      <span class="dft-chip-label">{chip_label}</span>
+    </button>
+    <button type="button" class="dft-chip-clear" title="Clear" aria-label="Clear date range"{disabled_attr}>×</button>
+    <div class="dft-popover" aria-hidden="true">
+      <div class="dft-preset-rail"></div>
+      <div class="dft-calendar-area" data-variable="{escaped_name}" data-start="{start_value}" data-end="{end_value}"></div>
+    </div>
+  </div>
+</div>"""
+
+    # Fallback: read-only display
+    return f"""<div class="variable-control dft-variable" data-variable-id="{escaped_name}" data-variable-label="{escaped_label}"{depends_on_attr}{description_attr}{disabled_wrapper_attrs} style="display: flex; align-items: center; gap: {control_gap}px;">
+  <span class="dft-variable-label">{escaped_label}:</span>
+  <span class="dft-variable-readonly-value">{html.escape(str(current or ""))}</span>
+</div>"""
+
+
+def generate_svg_variable_script() -> str:
+    """Generate JavaScript for SVG variable interactions.
+
+    This script is embedded in the SVG and handles:
+    - Variable change events (updateVariable function)
+    - URL parameter updates
+    - Chart loading states
+    - Parent frame communication (for playground/suite embedding)
+    - URL parameter initialization on load
+
+    Returns:
+        SVG script element with embedded JavaScript
+    """
+    from pathlib import Path
+
+    script_path = Path(__file__).parent / "templates/scripts/variables.js"
+    return embed_svg_script(script_path.read_text())
+
+
+# Calendar icon SVG symbol — emitted once per face via generate_svg_variable_icons().
+# Each daterange chip references it via <use href="#dft-icon-calendar">.
+_CALENDAR_ICON_SYMBOL = (
+    '<svg width="0" height="0" style="position:absolute;overflow:hidden" aria-hidden="true">'
+    '<symbol id="dft-icon-calendar" viewBox="0 0 24 24" fill="none"'
+    ' stroke="currentColor" stroke-linecap="round" stroke-linejoin="round">'
+    '<rect x="3.5" y="5.5" width="17" height="4.5" rx="1" fill="currentColor" opacity="0.13" stroke="none"/>'
+    '<rect x="3" y="5" width="18" height="16" rx="2" stroke-width="1.75"/>'
+    '<line x1="3" y1="10" x2="21" y2="10" stroke-width="1.75"/>'
+    '<line x1="8" y1="3" x2="8" y2="7" stroke-width="2.25"/>'
+    '<line x1="16" y1="3" x2="16" y2="7" stroke-width="2.25"/>'
+    "</symbol></svg>"
+)
+
+
+def generate_svg_variable_icons(variable_defs: dict[str, Any]) -> str:
+    """Generate shared SVG icon symbols for variable controls.
+
+    Emits the calendar symbol when at least one daterange control is present.
+    Emitting it once avoids duplicate id='dft-icon-calendar' when multiple
+    daterange variables appear on the same face.
+
+    Returns:
+        HTML string with hidden SVG symbol definitions, or empty string.
+    """
+    needs_calendar = any(
+        getattr(v, "input", None) == "daterange" for v in variable_defs.values()
+    )
+    return _CALENDAR_ICON_SYMBOL if needs_calendar else ""