dataface 0.1.2__py3-none-any.whl

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

@@ -0,0 +1,659 @@
+"""Authored face types — YAML input representation.
+
+Stage: COMPILE (Input)
+Purpose: Types that map directly to the YAML face schema.
+
+Contains the top-level AuthoredFace and its layout sub-shapes, plus
+LayoutType for face layout variants.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Annotated, Any, Literal
+
+from pydantic import (
+    BaseModel,
+    BeforeValidator,
+    ConfigDict,
+    Discriminator,
+    Field,
+    Tag,
+    model_validator,
+)
+
+from dataface.core.compile.models.chart.authored import AuthoredChart
+from dataface.core.compile.models.markers import Cascade
+from dataface.core.compile.models.query.authored import AuthoredQuery
+from dataface.core.compile.models.refs import (
+    ChartRef,
+    QueryRef,
+    VariableRef,
+    normalize_query_value,
+)
+from dataface.core.compile.models.source import SourceConfig
+from dataface.core.compile.models.style.authored import StylePatch
+from dataface.core.compile.models.variable.authored import SingleRowBoolProbe, Variable
+
+
+def _ref_or_inline(v: object, ref_cls: type) -> str:
+    """Classify a union value as '@ref' or '@inline'.
+
+    Returns '@ref' when v is already a typed ref instance, a bare cross-file ref
+    string, or a dict that contains a 'ref' key. Returns '@inline' otherwise.
+
+    Tag names start with '@' to prevent collision with user-chosen YAML keys
+    ('ref', 'inline') in Pydantic error locs.
+
+    Routing any dict with a 'ref' key to the ref branch produces a clean
+    'extra inputs not permitted' error from the ref model (extra="forbid")
+    rather than an opaque 'extra inputs' error on the inline model.
+    """
+    if isinstance(v, ref_cls):
+        return "@ref"
+    if isinstance(v, str):
+        return "@ref"
+    if isinstance(v, dict) and "ref" in v:
+        return "@ref"
+    return "@inline"
+
+
+def _var_discriminator(v: object) -> str:
+    return _ref_or_inline(v, VariableRef)
+
+
+def _query_discriminator(v: object) -> str:
+    return _ref_or_inline(v, QueryRef)
+
+
+def _chart_discriminator(v: object) -> str:
+    return _ref_or_inline(v, ChartRef)
+
+
+VariableOrRef = Annotated[
+    Annotated[Variable, Tag("@inline")] | Annotated[VariableRef, Tag("@ref")],
+    Discriminator(_var_discriminator),
+]
+QueryOrRef = Annotated[
+    Annotated[AuthoredQuery, Tag("@inline")] | Annotated[QueryRef, Tag("@ref")],
+    Discriminator(_query_discriminator),
+]
+ChartOrRef = Annotated[
+    Annotated[AuthoredChart, Tag("@inline")] | Annotated[ChartRef, Tag("@ref")],
+    Discriminator(_chart_discriminator),
+]
+
+# ============================================================================
+# LAYOUT SUB-SHAPES
+# ============================================================================
+
+_CHARTREF_KEYS = frozenset({"chart", "width", "height", "description", "visible"})
+_CHARTREF_MSG = (
+    "Layout item uses removed `chart:` reference form. "
+    "Use a bare chart name (`- chart_name`) or a nested face wrapper:\n"
+    "  - height: 600\n"
+    "    rows:\n"
+    "      - chart_name"
+)
+
+
+def _reject_chartref_dict(v: Any) -> Any:
+    if (
+        isinstance(v, dict)
+        and isinstance(v.get("chart"), str)
+        and v.keys() <= _CHARTREF_KEYS
+    ):
+        raise ValueError(_CHARTREF_MSG)
+    return v
+
+
+def _check_layout_list(v: Any) -> Any:
+    if not isinstance(v, list):
+        return v
+    for item in v:
+        _reject_chartref_dict(item)
+    return v
+
+
+def _check_layout_item(v: Any) -> Any:
+    return _reject_chartref_dict(v)
+
+
+class ForeachQuery(BaseModel):
+    """Inline data source for compile-time foreach loops."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    data: list[dict[str, Any]] | None = Field(
+        default=None,
+        description="Inline row data for compile-time iteration.",
+    )
+    static_data: list[dict[str, Any]] | None = Field(
+        default=None,
+        description="Alias for data; inline row data for compile-time iteration.",
+    )
+
+
+class ForeachConfig(BaseModel):
+    """foreach loop configuration.
+
+    `as` is a Python keyword so the field is declared as `as_` with an alias.
+    """
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    query: ForeachQuery = Field(
+        description="Inline data source providing the rows to iterate over."
+    )
+    as_: str = Field(
+        alias="as",
+        description="Variable name bound to each row (accessible as {{ as.field }}).",
+    )
+    items: Annotated[
+        list[
+            str | AuthoredFace | AuthoredChart | ForeachItem | dict[str, AuthoredChart]
+        ],
+        BeforeValidator(_check_layout_list),
+    ] = Field(description="Layout item templates resolved once per data row.")
+
+
+class ForeachItem(BaseModel):
+    """Top-level foreach construct in a layout list."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    foreach: ForeachConfig = Field(
+        description="foreach loop configuration with query, as, and items."
+    )
+
+
+class GridItem(BaseModel):
+    """Grid layout item with position and span.
+
+    Uses grid terminology (not pixels):
+        col: Column position (0-indexed)
+        row: Row position (0-indexed)
+        col_span: Number of columns to span (default 1)
+        row_span: Number of rows to span (default 1)
+        width: Alias for col_span (more intuitive)
+        height: Alias for row_span (more intuitive)
+
+    Example:
+        - item: my_chart
+          col: 0
+          row: 0
+          width: 12      # Takes half of 24-column grid (alias for col_span)
+          height: 2      # Spans 2 rows (alias for row_span)
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    item: Annotated[
+        str | AuthoredFace | AuthoredChart | ForeachItem | dict[str, AuthoredChart],
+        BeforeValidator(_check_layout_item),
+    ] = Field(
+        description="Chart name or inline chart/face definition to place in this grid cell."
+    )
+    col: int | None = Field(
+        default=None, description="Column position (0-indexed). Auto-placed if omitted."
+    )
+    row: int | None = Field(
+        default=None, description="Row position (0-indexed). Auto-placed if omitted."
+    )
+    col_span: int | None = Field(
+        default=None, description="Number of columns to span (width in grid units)."
+    )
+    row_span: int | None = Field(
+        default=None, description="Number of rows to span (height in grid units)."
+    )
+    width: int | None = Field(
+        default=None, description="Alias for col_span (more intuitive name)."
+    )
+    height: int | None = Field(
+        default=None, description="Alias for row_span (more intuitive name)."
+    )
+    description: str | None = Field(
+        default=None,
+        description="Optional metadata for AI search and context tooltips.",
+    )
+
+
+class GridLayout(BaseModel):
+    """Grid layout configuration."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    columns: int = Field(
+        default=24, description="Number of grid columns (default: 24)."
+    )
+    row_height: str | None = Field(
+        default=None, description="Default row height as a CSS value (e.g., '200px')."
+    )
+    gap: Literal["sm", "md", "lg", "xl"] | None = Field(
+        default=None, description="Gap between grid cells (sm, md, lg, xl)."
+    )
+    default_width: int | None = Field(
+        default=None,
+        description="Default column span for items that don't specify width.",
+    )
+    default_height: int | None = Field(
+        default=None,
+        description="Default row span for items that don't specify height.",
+    )
+    items: list[GridItem] = Field(
+        description="List of grid items with position and span configuration."
+    )
+
+
+class TabItem(BaseModel):
+    """Tab layout item."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    title: str = Field(description="Tab label displayed in the tab bar.")
+    icon: str | None = Field(
+        default=None,
+        description="Optional icon shown in the tab (e.g., emoji or icon name).",
+    )
+    description: str | None = Field(
+        default=None,
+        description="Optional metadata for AI search and context tooltips.",
+    )
+    text: str | None = Field(
+        default=None, description="Markdown text content shown in this tab."
+    )
+    style: StylePatch | None = Field(
+        default=None, description="Style patch for this tab's content area."
+    )
+
+    # Layout fields (tab can contain nested layouts)
+    rows: Annotated[
+        list[
+            str | AuthoredFace | AuthoredChart | ForeachItem | dict[str, AuthoredChart]
+        ]
+        | None,
+        BeforeValidator(_check_layout_list),
+    ] = Field(default=None, description="Vertical stack layout for this tab's content.")
+    cols: Annotated[
+        list[
+            str | AuthoredFace | AuthoredChart | ForeachItem | dict[str, AuthoredChart]
+        ]
+        | None,
+        BeforeValidator(_check_layout_list),
+    ] = Field(default=None, description="Horizontal layout for this tab's content.")
+    grid: GridLayout | None = Field(
+        default=None, description="CSS-grid layout for this tab's content."
+    )
+    tabs: TabLayout | None = Field(
+        default=None, description="Nested tab layout (tabs within tabs)."
+    )
+
+
+class TabLayout(BaseModel):
+    """Tab layout configuration.
+
+    The `id` field controls the variable name and URL param for tab selection.
+    If not provided, auto-generates as 'tab', 'tab_1', etc.
+
+    Example YAML:
+        tabs:
+          id: view              # → URL param ?view=overview
+          default: overview
+          items:
+            - title: Overview
+              rows: [kpi_row]
+            - title: Details
+              rows: [detail_table]
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    id: str | None = Field(
+        default=None,
+        description="Variable name and URL param base for tab selection (auto-generated if omitted).",
+    )
+    position: Literal["top", "left"] = Field(
+        default="top", description="Tab bar position (top or left)."
+    )
+    default: str | None = Field(
+        default=None, description="Default tab title to activate on load."
+    )
+    items: list[TabItem] = Field(description="List of tab items.")
+
+
+# ============================================================================
+# FACE (TOP-LEVEL)
+# ============================================================================
+
+
+class FaceDetails(BaseModel):
+    """Collapsible section metadata for a face.
+
+    Authored as a block or string shorthand:
+
+        details: "Show more"                        # str shorthand
+        details:
+          summary: "Show more"
+          expanded_title: "Hide"
+          expanded: false
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    summary: str = Field(description="Label shown when the section is collapsed.")
+    expanded_title: str | None = Field(
+        default=None,
+        description="Label shown when the section is expanded. Defaults to summary.",
+    )
+    expanded: bool = Field(
+        default=False, description="Whether the section is open by default."
+    )
+
+
+def _coerce_details(v: Any) -> Any:
+    """Coerce str → FaceDetails dict for the BeforeValidator on AuthoredFace.details."""
+    if isinstance(v, str):
+        return {"summary": v}
+    return v
+
+
+class SourcesSection(BaseModel):
+    """Sources section for faces.
+
+    Contains a default source and optionally inline source definitions.
+    Extra keys are validated as SourceConfig (inline source definitions).
+
+    Example YAML:
+        sources:
+          default: my_postgres  # Default source for all queries
+          local_csv:            # Inline source definition
+            type: csv
+            file: data/local.csv
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    __pydantic_extra__: dict[str, SourceConfig]
+
+    default: str | None = Field(
+        default=None,
+        description="Default source name used for all queries that don't specify a source.",
+    )
+
+
+class AuthoredFace(BaseModel):
+    """AuthoredFace (dataface) definition from YAML.
+
+    This is the top-level input type representing a complete dataface.
+    A face contains definitions (variables, queries, charts) and a layout.
+
+    Example YAML:
+        title: Sales Dataface
+        description: Overview of sales metrics
+
+        sources:
+          default: my_postgres  # Default source for all queries
+
+        variables:
+          date_range:
+            input: daterange
+            default: ["2024-01-01", "2024-12-31"]
+
+        queries:
+          sales: SELECT * FROM sales WHERE date BETWEEN ...
+
+        charts:
+          revenue:
+            query: sales
+            type: line
+            x: date
+            y: amount
+
+        rows:
+          - revenue
+
+    Layout:
+        Exactly one layout type should be present (rows, cols, grid, or tabs).
+        Layout items can be:
+        - Chart name (string reference)
+        - Inline chart definition (dict with query and type)
+        - Nested face (dict with layout keys)
+
+    Sources:
+        Optional sources section with:
+        - default: Default source name for all queries in this face
+        - Inline source definitions (source_name: {...config...})
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    @model_validator(mode="before")
+    @classmethod
+    def _normalize_queries(cls, data: object) -> object:
+        """Normalize string query values before Pydantic sees them.
+
+        Called for all faces (top-level and nested) via the model_validator.
+        Top-level faces are also processed by parser._normalize_query_definitions
+        before reaching this validator; nested faces embedded in rows/cols/tabs/grid
+        bypass the parser and rely solely on this validator.
+
+        Delegates to normalize_query_value from models.refs (the single shared
+        normalization helper used by parser and this validator).
+        """
+        if not isinstance(data, dict):
+            return data
+        raw_queries = data.get("queries")
+        if not isinstance(raw_queries, dict):
+            return data
+        return {
+            **data,
+            "queries": {
+                name: normalize_query_value(q) for name, q in raw_queries.items()
+            },
+        }
+
+    title: str | None = Field(
+        default=None, description="Dashboard title displayed at the top."
+    )
+    description: str | None = Field(
+        default=None, description="Description text for the dashboard."
+    )
+    tags: list[str] | None = Field(
+        default=None, description="Tags for categorization and search."
+    )
+    docs: str | None = Field(
+        default=None,
+        description=(
+            "Relative path under the docs site for the canonical doc page that "
+            "explains this face. Surfaced as a 'Docs →' link in the playground "
+            "gallery when DFT_DOCS_URL is set."
+        ),
+    )
+    text: str | None = Field(
+        default=None, description="Markdown text content for text-only sections."
+    )
+
+    # Source configuration
+    sources: Annotated[
+        SourcesSection | None,
+        Cascade(key="default_source", via="get_default_source"),
+    ] = Field(
+        default=None,
+        description="Database source configuration. Use 'default:' to set the default source for all queries.",
+    )
+    # Single source shorthand (alternative to sources.default)
+    source: Annotated[
+        str | None, Cascade(key="default_source", via="get_default_source")
+    ] = Field(
+        default=None,
+        description="Default source name shorthand (equivalent to sources.default). Sets the connection for all queries.",
+    )
+
+    # Scoped definitions
+    variables: dict[str, VariableOrRef] | None = Field(
+        default_factory=dict,
+        description="Variable definitions for dynamic filtering and UI controls.",
+    )
+    queries: dict[str, QueryOrRef] | None = Field(
+        default_factory=dict,
+        description="Named query definitions (SQL, CSV, MetricFlow, HTTP, etc.).",
+    )
+    charts: dict[str, ChartOrRef] | None = Field(
+        default_factory=dict,
+        description="Named chart definitions referenced in the layout.",
+    )
+
+    # Layout (exactly one should be present)
+    rows: Annotated[
+        list[
+            str | AuthoredFace | AuthoredChart | ForeachItem | dict[str, AuthoredChart]
+        ]
+        | None,
+        BeforeValidator(_check_layout_list),
+    ] = Field(
+        default=None,
+        description="Vertical stack layout: list of chart names or inline chart/face definitions.",
+    )
+    cols: Annotated[
+        list[
+            str | AuthoredFace | AuthoredChart | ForeachItem | dict[str, AuthoredChart]
+        ]
+        | None,
+        BeforeValidator(_check_layout_list),
+    ] = Field(
+        default=None,
+        description="Horizontal layout: list of chart names or inline chart/face definitions.",
+    )
+    grid: GridLayout | None = Field(
+        default=None,
+        description="CSS-grid style layout with explicit row/column placement.",
+    )
+    tabs: TabLayout | None = Field(
+        default=None,
+        description="Tabbed navigation layout where each tab contains its own layout.",
+    )
+
+    # Card gap toggle: when true, adds gap between cards.
+    card_gap: bool = Field(
+        default=False,
+        description="When True, adds gap between cards. Default: cards are edge-to-edge (0 gap).",
+    )
+
+    # Focus mode
+    chart_focus: str | None = Field(
+        default=None,
+        description="Render only this named chart with its dependent variables (useful for embedding or SVG export).",
+    )
+
+    # Collapsible section (details)
+    details: Annotated[FaceDetails | None, BeforeValidator(_coerce_details)] = Field(
+        default=None,
+        description=(
+            "Collapsible section metadata. "
+            "String shorthand: details: 'text' → FaceDetails(summary='text'). "
+            "Block form: details: {summary: ..., expanded_title: ..., expanded: false}."
+        ),
+    )
+
+    # Styling & dimensions (when nested)
+    id: str | None = Field(
+        default=None,
+        description="Explicit ID for this face. Auto-generated from filename if omitted.",
+    )
+    style: Annotated[StylePatch | None, Cascade()] = Field(
+        default=None,
+        description="Style patch (background, padding, border, etc.). Background and semantic color tokens (accent, muted) cascade to nested child faces.",
+    )
+    width: str | int | None = Field(
+        default=None,
+        description="Width when nested (e.g., '50%', '400px', or an integer in pixels).",
+    )
+    height: str | int | None = Field(
+        default=None,
+        description="Height when nested (e.g., '300px' or an integer in pixels).",
+    )
+    visible: bool | str | SingleRowBoolProbe | None = Field(
+        default=None,
+        description=(
+            "Controls whether this layout item is rendered. "
+            "Accepts a bool, variable name, Jinja expression, "
+            "or {query, column} probe."
+        ),
+    )
+
+    # Vega-Lite theme
+    theme: Annotated[str | None, Cascade()] = Field(
+        default=None,
+        description="Theme name (e.g., 'editorial', 'cream', 'stark').",
+    )
+
+    @model_validator(mode="before")
+    @classmethod
+    def reject_face_key(cls, data: Any) -> Any:
+        """Reject 'face' as a top-level key."""
+        if isinstance(data, dict) and "face" in data:
+            raise ValueError(
+                "'face:' is not valid. Face properties (title, rows, queries, etc.) "
+                "should be at the top level of the YAML file, not nested under 'face:'."
+            )
+        return data
+
+    @model_validator(mode="after")
+    def validate_layout(self) -> AuthoredFace:
+        """Ensure at least one layout type or content is defined."""
+        layouts = [self.rows, self.cols, self.grid, self.tabs]
+        defined = [layout for layout in layouts if layout is not None]
+        if len(defined) > 1:
+            raise ValueError(
+                "Face can only have one layout type (rows, cols, grid, or tabs)"
+            )
+        if (
+            len(defined) == 0
+            and self.text is None
+            and not self.title
+            and not self.description
+        ):
+            raise ValueError(
+                "Face must have at least one layout type, text, title, or description"
+            )
+        return self
+
+    def get_default_source(self) -> str | None:
+        """Return the default source name, or None.
+
+        source: shorthand takes precedence over sources.default.
+        """
+        if self.source:
+            return self.source
+        if self.sources is None:
+            return None
+        return self.sources.default
+
+
+# Resolve forward references (ForeachConfig.items references ForeachItem and
+# AuthoredFace; GridItem.item and TabItem.rows/cols also reference types defined
+# later in the file — rebuild after all classes are in scope)
+ForeachConfig.model_rebuild()
+GridItem.model_rebuild()
+TabItem.model_rebuild()
+AuthoredFace.model_rebuild()
+
+
+# ============================================================================
+# LAYOUT TYPE
+# ============================================================================
+
+
+class LayoutType(str, Enum):
+    """Layout types for organizing charts.
+
+    - rows: Vertical stack of items
+    - cols: Horizontal arrangement of items
+    - grid: CSS-grid style layout with columns
+    - tabs: Tabbed navigation between views
+    """
+
+    ROWS = "rows"
+    COLS = "cols"
+    GRID = "grid"
+    TABS = "tabs"