dataface 0.1.2__py3-none-any.whl

dataface/core/compile/models/face/compiled.py

@@ -0,0 +1,522 @@
+"""Compiled face types — output representation.
+
+Stage: COMPILE (Output) / EXECUTE and RENDER (Input)
+Purpose: Layout, Face, and resolved frozen dataclasses.
+"""
+
+from dataclasses import dataclass
+from typing import Any, Literal, TypeGuard
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from dataface.core.compile.models.chart.compiled import Chart
+from dataface.core.compile.models.face.authored import LayoutType
+from dataface.core.compile.models.query.compiled import AnyQuery
+from dataface.core.compile.models.style.authored import StylePatch
+from dataface.core.compile.models.style.merged import MergedStyle
+from dataface.core.compile.models.variable.authored import SingleRowBoolProbe, Variable
+
+# ============================================================================
+# TYPE ALIASES
+# ============================================================================
+
+
+# Resolved variable values (not Variable objects)
+# Used for Jinja template resolution - values can be any Python type
+VariableValues = dict[str, Any]
+
+
+# ============================================================================
+# UNIFIED LAYOUT
+# ============================================================================
+
+
+class LayoutItem(BaseModel):
+    """A single item in a layout.
+
+    Represents either a chart or a nested face in the layout.
+    The unified structure makes iteration simple:
+
+        for item in layout.items:
+            if item.type == "chart":
+                render_chart(item.chart)
+            else:
+                render_face(item.face)
+
+    Attributes:
+        type: Either "chart" or "face"
+        chart: Chart if type == "chart"
+        face: Face if type == "face"
+
+    Grid-specific (optional):
+        row, col: Grid position (0-based)
+        row_span, col_span: Grid span (in grid units)
+
+    Calculated dimensions (set by sizing module):
+        width_fraction: What fraction of parent width (0.0-1.0)
+        width: Pixel width
+        height: Pixel height
+        x: X position in pixels
+        y: Y position in pixels
+    """
+
+    type: Literal["chart", "face"] = Field(description="Item type: 'chart' or 'face'.")
+    chart: "Chart | None" = Field(
+        default=None, description="Compiled chart, present when type == 'chart'."
+    )
+    face: "Face | None" = Field(
+        default=None, description="Compiled face, present when type == 'face'."
+    )
+
+    # Grid positioning (optional) - 0-based, in grid units
+    row: int | None = Field(
+        default=None, description="Grid row position (0-based; grid layouts only)."
+    )
+    col: int | None = Field(
+        default=None, description="Grid column position (0-based; grid layouts only)."
+    )
+    row_span: int | None = Field(
+        default=None, description="Number of rows to span (grid layouts only)."
+    )
+    col_span: int | None = Field(
+        default=None, description="Number of columns to span (grid layouts only)."
+    )
+
+    # Authored dimensions (from YAML, e.g. "30%" or "200px").
+    # user_width: width fraction/px authored on a cols item.
+    # layout_height: slot height authored on a rows/wrapper item; resolved to
+    #   LayoutItem.height (float px) by the sizing pass.
+    user_width: str | None = Field(
+        default=None,
+        description="User-specified width from YAML (e.g., '30%' or '200px').",
+    )
+    layout_height: str | None = Field(
+        default=None,
+        description="Layout-wrapper height from YAML (e.g., '30%' or '200px'); "
+        "drives slot allocation in the sizing pass.",
+    )
+
+    # Calculated dimensions (set by sizing)
+    width_fraction: float = Field(
+        default=1.0, description="Fraction of parent width (0.0–1.0); set by sizing."
+    )
+    width: float = Field(default=0.0, description="Pixel width; set by sizing.")
+    height: float = Field(default=0.0, description="Pixel height; set by sizing.")
+    x: float = Field(default=0.0, description="X position in pixels; set by sizing.")
+    y: float = Field(default=0.0, description="Y position in pixels; set by sizing.")
+
+    # Layout visibility — evaluated at render time; None means always visible.
+    # Accepts: bool (static), str (variable name or Jinja expression),
+    # or SingleRowBoolProbe (single-row boolean probe).
+    visible: bool | str | SingleRowBoolProbe | None = Field(
+        default=None,
+        description=(
+            "Visibility condition for this layout item. "
+            "None/True: always shown. False: always hidden. "
+            "str: variable name (truthy check) or Jinja boolean expression. "
+            "{query, column}: single-row boolean probe (same contract as variables.disabled)."
+        ),
+    )
+
+    # Details (collapsible section) metadata
+    details_variable: str | None = Field(
+        default=None,
+        description="Variable name controlling expanded state (collapsible sections).",
+    )
+    details_summary: str | None = Field(
+        default=None,
+        description="Summary text shown when collapsed (collapsible sections).",
+    )
+    details_expanded_summary: str | None = Field(
+        default=None,
+        description="Summary text shown when expanded (collapsible sections).",
+    )
+    description: str | None = Field(
+        default=None, description="Optional metadata for AI/context tooltips."
+    )
+
+    # Render-ready sizing (calculated during normalization/sizing)
+    calculated_width: float | None = Field(
+        default=None,
+        description="Calculated pixel width based on 1200px default; set by sizing.",
+    )
+    calculated_height: float | None = Field(
+        default=None, description="Calculated pixel height; set by sizing."
+    )
+    aspect_ratio: float | None = Field(
+        default=None,
+        description="Width/height ratio for responsive rendering; set by sizing.",
+    )
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class Layout(BaseModel):
+    """Unified layout structure.
+
+    Stage: COMPILE output
+
+    All layout types (rows, cols, grid, tabs) are represented with this
+    unified structure, making downstream processing simpler.
+
+    The type field indicates the original layout type for rendering
+    (e.g., rows render vertically, cols horizontally).
+
+    Attributes:
+        type: Layout type (rows, cols, grid, tabs)
+        items: List of LayoutItem (charts or nested boards)
+
+    Grid-specific:
+        columns: Number of columns in grid
+        gap: Gap between items
+
+    Tabs-specific:
+        tab_titles: Titles for each tab
+        default_tab: Index of default active tab
+
+    Calculated:
+        width, height: Total dimensions (set by sizing)
+        content_width, content_height: Inner dimensions after padding/margin
+
+    Example:
+        >>> layout = compiled_board.layout
+        >>> print(f"Layout type: {layout.type}")
+        >>> for item in layout.items:
+        ...     print(f"  - {item.type}: {item.chart.id if item.chart else item.face.id}")
+    """
+
+    type: LayoutType = Field(description="Layout type (rows, cols, grid, tabs).")
+    items: list[LayoutItem] = Field(
+        default_factory=list,
+        description="List of layout items (charts or nested faces).",
+    )
+
+    # Grid-specific
+    columns: int | None = Field(
+        default=None, description="Number of columns for grid layouts."
+    )
+    gap: str | None = Field(
+        default=None, description="Gap between items for grid layouts (CSS value)."
+    )
+    row_height: str | None = Field(
+        default=None, description="Default row height for grid layouts (CSS value)."
+    )
+
+    # Tabs-specific
+    tab_titles: list[str] | None = Field(
+        default=None, description="Titles for each tab (tabs layout only)."
+    )
+    tab_slugs: list[str] | None = Field(
+        default=None,
+        description="Slugified titles used as URL values (tabs layout only).",
+    )
+    tab_variable: str | None = Field(
+        default=None,
+        description="Variable name controlling the active tab (tabs layout only).",
+    )
+    default_tab: int | None = Field(
+        default=None, description="Index of the default active tab (tabs layout only)."
+    )
+    tab_position: Literal["top", "left"] | None = Field(
+        default=None,
+        description="Tab bar position: 'top' or 'left' (tabs layout only).",
+    )
+
+    # Calculated dimensions (outer dimensions including padding/margin)
+    width: float = Field(
+        default=0.0, description="Total calculated pixel width; set by sizing."
+    )
+    height: float = Field(
+        default=0.0, description="Total calculated pixel height; set by sizing."
+    )
+
+    # Calculated content dimensions (inner dimensions after padding/margin)
+    content_width: float = Field(
+        default=0.0,
+        description="Inner pixel width after padding/margin; set by sizing.",
+    )
+    content_height: float = Field(
+        default=0.0,
+        description="Inner pixel height after padding/margin; set by sizing.",
+    )
+
+    model_config = ConfigDict(extra="forbid")
+
+
+# ============================================================================
+# COMPILED FACE
+# ============================================================================
+
+
+class Face(BaseModel):
+    """Compiled face ready for execution and rendering.
+
+    Stage: COMPILE output / EXECUTE and RENDER input
+
+    This is the main output of compilation. It contains:
+    - Resolved definitions (variables, queries, charts)
+    - Unified layout structure
+    - Calculated dimensions
+    - Applied defaults and metadata
+
+    Guarantees:
+        - id: Always set
+        - title: Always set (empty string if not provided)
+        - layout: Always present (unified structure)
+        - All charts resolved to Chart objects
+        - All queries resolved to query objects
+
+    Attributes:
+        id: Unique identifier for this face
+        title: Display title
+        description: Description text
+        variables: Variable definitions (Dict[str, Variable])
+        queries: Compiled queries (Dict[str, AnyQuery])
+        charts: Compiled charts (Dict[str, Chart])
+        layout: Unified layout structure
+        variable_defaults: Resolved default values for variables
+        style: Face styling
+    Example:
+        >>> result = compile(yaml_content)
+        >>> face = result.face
+        >>> print(face.id)        # "sales-dataface"
+        >>> print(face.title)     # "Sales Dataface"
+        >>> print(face.layout.type)  # "rows"
+        >>> for item in face.layout.items:
+        ...     chart = item.chart
+        ...     print(f"Chart: {chart.id}, Query: {chart.query_name}")
+    """
+
+    id: str = Field(description="Unique identifier for this face.")
+    title: str = Field(
+        default="", description="Display title. Empty string if not provided."
+    )
+    description: str = Field(
+        default="", description="Description text. Empty string if not provided."
+    )
+    tags: list[str] = Field(
+        default_factory=list, description="Tags for categorization and search."
+    )
+    text: str = Field(
+        default="", description="Markdown text content for text-only faces."
+    )
+
+    # Definitions
+    variables: dict[str, Variable] = Field(
+        default_factory=dict,
+        description="Local variable definitions for UI controls.",
+    )
+    queries: dict[str, AnyQuery] = Field(
+        default_factory=dict,
+        description="Compiled query objects by name.",
+    )
+    charts: dict[str, Chart] = Field(
+        default_factory=dict,
+        description="Compiled chart objects by name.",
+    )
+
+    # Source configurations (for resolving named source references)
+    sources: dict[str, dict[str, Any]] = Field(
+        default_factory=dict,
+        description="Source configurations for resolving named source references (e.g., {'profiles': {'type': 'duckdb'}}).",
+    )
+
+    # Unified layout
+    layout: Layout = Field(
+        description="Unified layout structure containing all charts and nested faces.",
+    )
+
+    # Pre-computed variable defaults from variable_registry
+    variable_defaults: VariableValues = Field(
+        default_factory=dict,
+        description="Pre-computed default values for all variables; only set on root board.",
+    )
+
+    # Global variable registry (only set on root face, contains all variables from entire tree)
+    variable_registry: dict[str, Variable] | None = Field(
+        default=None,
+        description="All variables from the entire face tree; only set on root face.",
+    )
+
+    # Vega-Lite theme (e.g., "dark", "stark", "carbong100")
+    theme: str | None = Field(
+        default=None,
+        description="Theme name (e.g., 'editorial', 'cream', 'stark'). Inherited by nested faces.",
+    )
+    # Authored style patch — None when the face has no style: block.
+    authored_style: StylePatch | None = Field(
+        default=None,
+        description="Authored face style patch (background, padding, border, etc.).",
+    )
+    # Board-scoped resolved style — authoritative, produced at compile time.
+    resolved_style: MergedStyle = Field(
+        description="Board-scoped resolved style; produced at compile time. Render reads this instead of re-merging patches.",
+    )
+
+    @property
+    def visible_variables(self) -> "dict[str, Variable]":
+        """Return variables with visible=True (available for UI controls)."""
+        return {k: v for k, v in self.variables.items() if v.visible}
+
+    # Card gap toggle (from board YAML)
+    card_gap: bool = Field(
+        default=False,
+        description="When True, adds gap between cards and adjusts page margin.",
+    )
+
+    # Semantic heading level: count of titled ancestors (not structural nesting depth).
+    # A titled root face is level=1; a titled face nested under a bare wrapper is still
+    # level=2 (only one titled ancestor). Bare wrappers without a title do not advance
+    # the counter. Required — every Face is constructed by the normalizer (or by a
+    # call site that derives level from parent_level), so a missing value is a bug,
+    # not a default. Can be overridden via face.style.title.level.
+    level: int = Field(
+        description=(
+            "Heading level for this face's title (matches H{level}; root face = 1 when "
+            "titled, 0 when untitled). Computed from titled-ancestor count; can be "
+            "overridden via face.style.title.level."
+        ),
+    )
+
+    # Compilation metadata
+    meta: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Compilation metadata (warnings, diagnostics, source info) populated by the normalizer.",
+    )
+
+    model_config = ConfigDict(extra="forbid")
+
+
+# Resolve forward references (Chart and Face are now in scope)
+LayoutItem.model_rebuild()
+Layout.model_rebuild()
+Face.model_rebuild()
+
+
+# ============================================================================
+# RESOLVED TYPES (produced by resolve_face() — no lookups needed downstream)
+# ============================================================================
+
+
+@dataclass(frozen=True)
+class ResolvedLayoutItem:
+    """Layout item with static dimension estimates — no executor, no data access."""
+
+    type: str  # "chart" | "face" | "text" | "markdown" | ...
+    chart: Chart | None
+    # nested face is a forward reference — resolved recursively
+    face: "MergedFace | None"
+    x: float
+    y: float
+    width: float
+    height: float
+    # Carry-through optional fields from LayoutItem
+    details_variable: str | None = None
+    details_summary: str | None = None
+    details_expanded_summary: str | None = None
+    description: str | None = None
+    visible: "bool | str | SingleRowBoolProbe | None" = None
+
+
+@dataclass(frozen=True)
+class ResolvedLayout:
+    """Layout tree with static dimension estimates.
+
+    Dimensions come from compile-time static sizing.  The render phase applies
+    data-aware sizing (executor-driven row counts and Vega render-first heights)
+    on top of these estimates.
+    """
+
+    type: str  # "rows" | "cols" | "grid" | "tabs"
+    items: tuple["ResolvedLayoutItem", ...]
+    width: float
+    height: float
+    content_width: float
+    content_height: float
+    # Grid-specific
+    columns: int | None = None
+    gap: float = 0.0
+    # Tabs-specific
+    tab_titles: tuple[str, ...] = ()
+    tab_slugs: tuple[str, ...] = ()
+    tab_variable: str | None = None
+    default_tab: int = 0
+    tab_position: str | None = None
+
+
+@dataclass(frozen=True)
+class MergedFace:
+    """Pure resolved face — deterministic transform from Face + config.
+
+    Produced by resolve_face() — never constructed directly.
+    No executor, no data access, no render-phase artifacts.
+    The render layer performs data-aware sizing on top of these static estimates.
+
+    Board-level config fields (page_padding, card_padding, card_gap) are None
+    for nested faces — those values only apply to the root renderable face.
+    """
+
+    # Identity
+    id: str
+    title: str
+    description: str
+    tags: tuple[str, ...]
+    text: str
+    level: int  # Heading level (1 = root face, matches H{level})
+
+    # Style (theme + face overrides already merged).
+    style: MergedStyle
+
+    # Baked board config constants — None for nested faces (root only).
+    # config.style.board.margin / card_padding / card_gap
+    page_padding: float | None
+    card_padding: float | None
+    card_gap: float | None
+
+    # Static dimension estimates (from compile-time layout tree)
+    # Render phase applies data-aware sizing on top.
+    width: float
+    height: float
+
+    # Resolved Vega-Lite config (pure: theme name → compiled VL config dict)
+    vega_config: dict[str, Any]
+
+    # Layout tree with static item estimates
+    layout: ResolvedLayout
+
+    # Data (unchanged from Face)
+    charts: dict[str, Chart]
+    variables: dict[str, Variable]
+    queries: dict[str, AnyQuery]
+    variable_defaults: VariableValues
+
+    @property
+    def visible_variables(self) -> "dict[str, Variable]":
+        """Variables with visible=True — available for UI controls."""
+        return {k: v for k, v in self.variables.items() if v.visible}
+
+
+# ============================================================================
+# TYPE GUARD
+# ============================================================================
+
+
+def is_face(item: Any) -> TypeGuard[Face]:
+    """Type guard for Face.
+
+    After compilation, all faces are Face objects.
+    Use this for type narrowing in conditional blocks.
+
+    Args:
+        item: Item to check
+
+    Returns:
+        True if item is a Face
+
+    Example:
+        >>> for item in layout.items:
+        ...     if item.face and is_face(item.face):
+        ...         # Type checker knows item.face is Face
+        ...         print(item.face.layout.type)
+    """
+    return isinstance(item, Face)