dataface 0.1.2__py3-none-any.whl

dataface/core/compile/models/theme.py

@@ -0,0 +1,362 @@
+"""Theme configuration types and canonical theme normalization.
+
+Stage: COMPILE
+Purpose: Define the Dataface-facing theme schema and map it to Vega-Lite config.
+
+The public authoring surface is a canonical Dataface theme model:
+- top-level shared tokens
+- `charts:` for chart defaults and chart-type overrides
+
+Vega-Lite remains an implementation detail. Raw Vega config still passes through as
+an escape hatch, but `to_vega_config()` is the boundary that maps canonical theme
+values into Vega-Lite config for rendering.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from copy import deepcopy
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, model_validator
+
+from dataface.core.compile.models.vega_lite.config import (
+    AxisConfig,
+    LegendConfig,
+    MarkConfig,
+    RangeConfig,
+    TitleConfig,
+    ViewConfig,
+)
+
+
+def _deep_merge(base: dict[str, Any], overlay: Mapping[str, Any]) -> dict[str, Any]:
+    merged = deepcopy(base)
+    for key, value in overlay.items():
+        if (
+            key in merged
+            and isinstance(merged[key], dict)
+            and isinstance(value, Mapping)
+        ):
+            merged[key] = _deep_merge(merged[key], dict(value))
+        else:
+            merged[key] = deepcopy(value)
+    return merged
+
+
+def _to_plain_vega_value(value: object) -> object:
+    """Recursively convert pydantic models and mapping-like values to plain Python."""
+    if isinstance(value, BaseModel):
+        data: dict[str, object] = {}
+
+        for key in type(value).model_fields:
+            field_value = getattr(value, key, None)
+            if field_value is not None:
+                data[key] = _to_plain_vega_value(field_value)
+
+        extra = getattr(value, "model_extra", None) or {}
+        for key, extra_value in extra.items():
+            if extra_value is not None:
+                data[key] = _to_plain_vega_value(extra_value)
+
+        return data
+
+    if isinstance(value, dict):
+        return {
+            key: _to_plain_vega_value(item)
+            for key, item in value.items()
+            if item is not None
+        }
+
+    if isinstance(value, list):
+        return [_to_plain_vega_value(item) for item in value]
+
+    return value
+
+
+class ThemeTokens(BaseModel):
+    """Canonical shared theme tokens."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    background: str | None = None
+    color: str | None = None
+    muted: str | None = None
+    border_color: str | None = None
+    accent_color: str | None = None
+    title_color: str | None = None
+
+
+class ThemeMarkConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    color: str | None = None
+
+
+class ThemeTableStripeConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    color: str | None = None
+
+
+class ThemeTableConfig(ThemeTokens):
+    header_background: str | None = None
+    header_color: str | None = None
+    stripe: ThemeTableStripeConfig | None = None
+
+
+class ThemeChartsConfig(ThemeTokens):
+    palette: list[str] | None = None
+    dashes: list[list[int]] | None = None
+    table: ThemeTableConfig | None = None
+    bar: ThemeMarkConfig | None = None
+    arc: ThemeMarkConfig | None = None
+    area: ThemeMarkConfig | None = None
+    line: ThemeMarkConfig | None = None
+    path: ThemeMarkConfig | None = None
+    point: ThemeMarkConfig | None = None
+    rect: ThemeMarkConfig | None = None
+    shape: ThemeMarkConfig | None = None
+    symbol: ThemeMarkConfig | None = None
+
+
+class ThemeConfig(ThemeTokens):
+    """Canonical Dataface theme plus optional raw Vega-Lite config overrides.
+
+    Typed fields (view, title, axis, legend, range, mark-type configs) cover the
+    most common VL config sections and validate their contents strictly.
+
+    top-level extra="allow" is a deliberate VL escape hatch: any Vega-Lite config
+    key not listed as a typed field passes through as-is to to_vega_config(). This
+    covers sections Dataface does not enumerate typed fields for — axisBand, axisX,
+    axisY, axisQuantitative, axisOrdinal, headerRow, headerColumn, projectionConfig,
+    scale, and others. Closing this surface would require enumerating every Vega-Lite
+    config section, which is out of scope and creates unnecessary churn as VL evolves.
+
+    Contrast with vega.config (VegaRuntimeConfig.config: VegaLiteConfig) — that path
+    is closed (extra="forbid") because it represents the Dataface-emitted style output,
+    not the user-authored theme surface.
+
+    Note: unknown keys in theme YAML are silently accepted (no typo detection). This
+    is the accepted trade-off for an escape hatch surface.
+    """
+
+    # VL theme escape hatch — intentional, not a migration shim. See class docstring.
+    model_config = ConfigDict(extra="allow")
+
+    charts: ThemeChartsConfig | None = None
+
+    # Raw Vega-Lite override surface / pass-through.
+    view: ViewConfig | None = None
+    title: TitleConfig | None = None
+    axis: AxisConfig | None = None
+    legend: LegendConfig | None = None
+    range: RangeConfig | None = None
+    bar: MarkConfig | None = None
+    arc: MarkConfig | None = None
+    line: MarkConfig | None = None
+    area: MarkConfig | None = None
+    rect: MarkConfig | None = None
+    symbol: MarkConfig | None = None
+    point: MarkConfig | None = None
+    shape: MarkConfig | None = None
+    path: MarkConfig | None = None
+
+    @model_validator(mode="before")
+    @classmethod
+    def _reject_legacy_dataface_keys(cls, value: object) -> object:
+        if not isinstance(value, Mapping):
+            return value
+
+        legacy_root_keys = {
+            "table",
+            "variable",
+            "variables",
+            "borderColor",
+            "accentColor",
+            "titleColor",
+        }
+        present_legacy_keys = sorted(key for key in legacy_root_keys if key in value)
+        if present_legacy_keys:
+            invalid_keys = ", ".join(present_legacy_keys)
+            raise ValueError(
+                "Theme config uses unsupported legacy Dataface keys: "
+                f"{invalid_keys}. Use snake_case canonical keys instead."
+            )
+
+        return value
+
+    def resolved_top_level(self) -> ThemeTokens:
+        return ThemeTokens.model_validate(
+            self.model_dump(include=set(ThemeTokens.model_fields))
+        )
+
+    def resolved_charts(self) -> ThemeChartsConfig:
+        base = self.resolved_top_level().model_dump(exclude_none=True)
+        overlay = (
+            self.charts.model_dump(exclude_none=True) if self.charts is not None else {}
+        )
+        return ThemeChartsConfig.model_validate(_deep_merge(base, overlay))
+
+    def resolved_table(self) -> ThemeTableConfig:
+        charts = self.resolved_charts()
+        base = charts.model_dump(
+            include=set(ThemeTokens.model_fields),
+            exclude_none=True,
+        )
+        overlay = (
+            charts.table.model_dump(exclude_none=True)
+            if charts.table is not None
+            else {}
+        )
+        return ThemeTableConfig.model_validate(_deep_merge(base, overlay))
+
+    def _generated_vega_config(self) -> dict[str, Any]:
+        charts = self.resolved_charts()
+        generated: dict[str, Any] = {}
+
+        if self.background is not None:
+            generated["background"] = self.background
+
+        title_color = charts.title_color
+        if title_color is not None:
+            generated["title"] = {"color": title_color}
+            generated["axis"] = {
+                "labelColor": charts.muted,
+                "titleColor": title_color,
+                "gridColor": charts.border_color,
+                "tickColor": charts.border_color,
+                "domainColor": charts.border_color,
+            }
+            generated["legend"] = {
+                "labelColor": charts.muted,
+                "titleColor": title_color,
+            }
+        elif charts.muted is not None or charts.border_color is not None:
+            generated["axis"] = {
+                "labelColor": charts.muted,
+                "gridColor": charts.border_color,
+                "tickColor": charts.border_color,
+                "domainColor": charts.border_color,
+            }
+            generated["legend"] = {"labelColor": charts.muted}
+
+        if charts.palette is not None:
+            generated["range"] = {"category": charts.palette}
+
+        default_mark_color = charts.accent_color
+        mark_map = {
+            "bar": ("fill", charts.bar.color if charts.bar else None),
+            "arc": ("fill", charts.arc.color if charts.arc else None),
+            "area": ("fill", charts.area.color if charts.area else None),
+            "line": ("stroke", charts.line.color if charts.line else None),
+            "path": ("stroke", charts.path.color if charts.path else None),
+            "point": ("fill", charts.point.color if charts.point else None),
+            "rect": ("fill", charts.rect.color if charts.rect else None),
+            "shape": ("stroke", charts.shape.color if charts.shape else None),
+            "symbol": ("fill", charts.symbol.color if charts.symbol else None),
+        }
+        for key, (field, value) in mark_map.items():
+            color = value or default_mark_color
+            if color is not None:
+                generated[key] = {field: color}
+
+        return _to_plain_vega_value(generated)  # type: ignore[return-value]
+
+    def to_vega_config(self) -> dict:
+        """Export theme as Vega-Lite config.
+
+        Canonical Dataface theme tokens synthesize the common Vega-Lite config.
+        Any explicit raw Vega-Lite keys on the theme override the generated values.
+        """
+        raw = _to_plain_vega_value(self)
+        if not isinstance(raw, dict):
+            raise TypeError("ThemeConfig must serialize to a dictionary")
+
+        # Strip Dataface-internal keys that must not appear in Vega-Lite config.
+        # "table", "variable", "variables" are rejected by the model validator so
+        # they cannot reach here; the remaining keys are valid model fields that
+        # must be excluded from Vega output.
+        for key in (
+            "color",
+            "muted",
+            "border_color",
+            "accent_color",
+            "title_color",
+            "charts",
+        ):
+            raw.pop(key, None)
+
+        generated = self._generated_vega_config()
+        if not isinstance(generated, dict):
+            raise TypeError("Generated theme config must serialize to a dictionary")
+        return _deep_merge(generated, raw)
+
+
+def normalize_raw_theme_config(raw: Mapping[str, Any]) -> dict[str, Any]:
+    """Normalize raw theme dictionaries into the canonical theme surface."""
+    data = deepcopy(dict(raw))
+
+    def _mapping(name: str) -> Mapping[str, Any]:
+        value = data.get(name)
+        return value if isinstance(value, Mapping) else {}
+
+    axis = _mapping("axis")
+    legend = _mapping("legend")
+    title = _mapping("title")
+    range_config = _mapping("range")
+    charts = _mapping("charts")
+    table_raw = charts.get("table")
+    table: Mapping[str, Any] = table_raw if isinstance(table_raw, Mapping) else {}
+
+    mark_sources = (
+        ("bar", "fill"),
+        ("arc", "fill"),
+        ("line", "stroke"),
+        ("area", "fill"),
+        ("rect", "fill"),
+        ("symbol", "fill"),
+        ("point", "fill"),
+        ("shape", "stroke"),
+        ("path", "stroke"),
+    )
+    accent = None
+    chart_marks: dict[str, Any] = {}
+    for mark, field in mark_sources:
+        mark_value = _mapping(mark)
+        color = mark_value.get(field)
+        if color and accent is None:
+            accent = color
+        if color:
+            chart_marks[mark] = {"color": color}
+    if accent is None and isinstance(range_config.get("category"), list):
+        accent = range_config["category"][0] if range_config["category"] else None
+
+    derived_tokens: dict[str, Any] = {
+        "background": data.get("background"),
+        "color": table.get("color") or title.get("color"),
+        "muted": axis.get("labelColor") or legend.get("labelColor"),
+        "border_color": axis.get("gridColor")
+        or axis.get("tickColor")
+        or axis.get("domainColor"),
+        "accent_color": accent,
+        "title_color": table.get("header_color")
+        or axis.get("titleColor")
+        or title.get("color")
+        or legend.get("titleColor"),
+    }
+
+    normalized = dict(data)
+    for key, value in derived_tokens.items():
+        if value is not None and key not in normalized:
+            normalized[key] = value
+
+    chart_overrides: dict[str, Any] = {}
+    if isinstance(range_config.get("category"), list):
+        chart_overrides["palette"] = list(range_config["category"])
+    if chart_marks:
+        chart_overrides.update(chart_marks)
+    if chart_overrides:
+        normalized["charts"] = _deep_merge(dict(charts), chart_overrides)
+
+    return normalized

dataface/core/compile/models/variable/authored.py

@@ -0,0 +1,254 @@
+"""Authored variable models: Variable, VariableOptions, SingleRowBoolProbe, VariableInputType.
+
+Stage: COMPILE (Input)
+Purpose: Define variable types that map directly to the YAML schema.
+
+Variables provide dynamic values to queries and charts. They can be bound to
+user inputs (select, slider, etc.) or have static default values.
+"""
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+# ============================================================================
+# ENUMS & LITERALS
+# ============================================================================
+
+VariableInputType = Literal[
+    "auto",
+    "select",
+    "multiselect",
+    "input",
+    "text",
+    "number",
+    "textarea",
+    "slider",
+    "range",
+    "date",
+    "datepicker",
+    "daterange",
+    "checkbox",
+    "radio",
+]
+
+# ============================================================================
+# VARIABLE TYPES
+# ============================================================================
+
+
+class VariableOptions(BaseModel):
+    """Options configuration for variable inputs.
+
+    Defines where the options come from for select/multiselect inputs.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    static: list[str | int | float] | None = Field(
+        default=None, description="List of static option values (strings or numbers)."
+    )
+    query: str | None = Field(
+        default=None, description="Query name whose result rows provide option values."
+    )
+    column: str | None = Field(
+        default=None, description="Column in the query result to use as option values."
+    )
+    label_column: str | None = Field(
+        default=None,
+        description="Column in the query result to use as display labels (separate from values).",
+    )
+
+
+class SingleRowBoolProbe(BaseModel):
+    """Single-row boolean query probe.
+
+    Executes a named query and reads one boolean cell to decide a yes/no
+    condition. Used by ``Variable.disabled`` and ``LayoutItem.visible``.
+    The query must return exactly one row; the named column must hold a
+    boolean-coercible value (true/false/1/0/yes/no).
+
+    Example YAML (disabled)::
+
+        disabled:
+          query: seed_control_state
+          column: is_disabled
+
+    Example YAML (visible)::
+
+        visible:
+          query: layout_flags
+          column: show_panel
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    query: str = Field(description="Name of the query to execute.")
+    column: str = Field(
+        description="Column in the single result row holding the boolean value."
+    )
+
+
+class Variable(BaseModel):
+    """Variable definition from YAML.
+
+    Variables provide dynamic values to queries and charts.
+    They can be bound to user inputs (select, slider, etc.) or
+    have static default values.
+
+    Cascading Variables:
+        Variables can depend on other variables when their options query
+        uses Jinja templates referencing other variables. For example:
+
+        variables:
+          country:
+            input: select
+            options:
+              query: country_options
+
+          state:
+            input: select
+            options:
+              query: state_options  # SQL uses {{ filter('country', country) }}
+
+        When country changes, state's options are re-fetched with the new
+        country value, and state's current value is reset.
+
+    Invisible Variables:
+        Variables with visible=False are not rendered in the UI but can still
+        be used in queries. This is useful for:
+        - Server-side variables passed via URL query params
+        - Internal system values (theme, model name, connection strings)
+        - Variables that shouldn't be user-editable
+
+    Example YAML:
+        variables:
+          date_range:
+            input: daterange
+            label: "Date Range"
+            default: ["2024-01-01", "2024-12-31"]
+          category:
+            input: select
+            options:
+              static: ["All", "Electronics", "Clothing"]
+            default: "All"
+          model:
+            input: text
+            visible: false  # Set via URL param, not shown in UI
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    input: VariableInputType = Field(
+        default="auto",
+        description="UI control type (select, multiselect, slider, daterange, etc.). 'auto' detects from options.",
+    )
+    input_auto_detected: bool = Field(
+        default=False,
+        exclude=True,
+        description="Internal: True when input type was resolved from 'auto' to a concrete type.",
+    )
+    label: str | None = Field(
+        default=None, description="Display label shown above the input control."
+    )
+    description: str | None = Field(
+        default=None, description="Help text shown below the input control."
+    )
+    default: Any | None = Field(
+        default=None, description="Default value used when no URL param is set."
+    )
+    placeholder: str | None = Field(
+        default=None, description="Placeholder text shown in the input when empty."
+    )
+    required: bool | None = Field(
+        default=False,
+        description="When True, a value must be provided before queries execute.",
+    )
+    allow_null: bool | None = Field(
+        default=False,
+        description="When True, 'null' is a valid selection (useful for optional filters).",
+    )
+    visible: bool = Field(
+        default=True,
+        description="When False, the variable is not rendered in the UI but can still be set via URL params.",
+    )
+    disabled: bool | str | SingleRowBoolProbe | None = Field(
+        default=None,
+        description=(
+            "Disable this control. Accepts: static bool; a variable name or Jinja "
+            "boolean expression string (no {{ }} required — bare names auto-wrap); "
+            "or a {query, column} form that reads a single boolean cell from a named "
+            "query. Absent variable in a string expression raises (use a default)."
+        ),
+    )
+
+    # Source binding (one of these for data-driven options)
+    column: str | None = Field(
+        default=None,
+        description="Column name in the query result to use as option values.",
+    )
+    query: str | dict[str, Any] | None = Field(
+        default=None,
+        description="Query name or inline query definition for populating options.",
+    )
+    dimension: str | None = Field(
+        default=None, description="MetricFlow dimension name for populating options."
+    )
+    measure: str | None = Field(
+        default=None, description="MetricFlow measure name for populating options."
+    )
+    model: str | None = Field(
+        default=None, description="dbt model name for populating options."
+    )
+
+    # Options
+    options: VariableOptions | None = Field(
+        default=None, description="Static or query-driven option list configuration."
+    )
+
+    # Migration metadata
+    data_type: str | None = Field(
+        default=None,
+        description=(
+            "Upstream data-type hint preserved through migrations (e.g. 'string', "
+            "'number'). Informational; not currently consumed at compile time."
+        ),
+    )
+
+    # Slider-specific
+    min: int | float | None = Field(
+        default=None, description="Minimum value for slider/range inputs."
+    )
+    max: int | float | None = Field(
+        default=None, description="Maximum value for slider/range inputs."
+    )
+    step: int | float | None = Field(
+        default=None, description="Step size for slider/range inputs."
+    )
+
+    # Operator for filter generation
+    operator: str | None = Field(
+        default=None,
+        description="SQL operator used when generating filter expressions (e.g., '=', 'IN', 'LIKE').",
+    )
+
+    # Computed during compilation — not an authored field.
+    variable_dependencies: set[str] = Field(
+        default_factory=set,
+        exclude=True,
+        description="Other variable names this variable's options query depends on (computed during compilation).",
+    )
+
+    def get_option_query(self) -> str | None:
+        """Get the query name used for populating options.
+
+        Returns:
+            Query name if options are populated from a query, None otherwise
+        """
+        # Check options.query first (structured options)
+        if self.options and self.options.query:
+            return self.options.query
+        # Check direct query binding
+        if isinstance(self.query, str):
+            return self.query
+        return None