dataface 0.1.2__py3-none-any.whl

dataface/core/compile/normalize_layout.py

@@ -0,0 +1,1000 @@
+"""Layout resolution and unified layout construction."""
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pydantic import ValidationError as PydanticValidationError
+
+from dataface.core.compile.errors import CompilationError, ReferenceError
+from dataface.core.compile.models.chart.authored import (
+    _SharedChartFields,
+)
+from dataface.core.compile.models.chart.compiled import (
+    Chart,
+)
+from dataface.core.compile.models.face.authored import (
+    AuthoredFace,
+    ForeachConfig,
+    ForeachItem,
+    ForeachQuery,
+    GridLayout,
+    LayoutType,
+    TabLayout,
+)
+from dataface.core.compile.models.face.compiled import Face, Layout, LayoutItem
+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.normalize_charts import (
+    _generate_inline_chart_id,
+    _normalize_chart,
+)
+
+
+def _validate_style_patch(style_dict: dict[str, Any]) -> StylePatch:
+    """Validate a raw style dict and return a StylePatch.
+
+    Re-raises PydanticValidationError with ``style.`` prepended to each loc
+    so errors from nested-face style blocks say ``style.bad_key`` rather than
+    the bare ``bad_key`` that a standalone StylePatch.model_validate raises.
+    """
+    try:
+        return StylePatch.model_validate(style_dict)
+    except PydanticValidationError as exc:
+        raise PydanticValidationError.from_exception_data(
+            title=exc.title,
+            input_type="python",
+            line_errors=[
+                {
+                    "type": err["type"],
+                    "loc": ("style",) + err["loc"],
+                    "input": err["input"],
+                    "ctx": err.get("ctx", {}),
+                }
+                for err in exc.errors()
+            ],
+        ) from exc
+
+
+def _validate_dimension(value: Any, name: str) -> None:
+    """Reject zero/negative dimension values at compile time.
+
+    Uses ``parse_dimension`` from the sizing module so the validator and
+    the sizing engine agree on what constitutes a valid dimension.
+    ``total=1.0`` makes percentages yield their numeric fraction (e.g.
+    ``"50%"`` → 0.5) so the sign check works uniformly.
+    """
+    if value is None:
+        return
+    from dataface.core.compile.sizing import parse_dimension
+
+    parsed = parse_dimension(str(value), 1.0)
+    if parsed is None:
+        raise CompilationError(
+            f"'{name}: {value}' is not a valid dimension"
+            " (use e.g. '200', '200px', or '50%')"
+        )
+    if parsed <= 0:
+        raise CompilationError(f"'{name}: {value}' must be positive (got {parsed})")
+
+
+def build_unified_layout(
+    face: AuthoredFace,
+    charts: dict[str, Chart],
+    query_registry: dict[str, AnyQuery],
+    face_id: str,
+    depth: int,
+    base_path: Path | None = None,
+    default_source: str | None = None,
+    chart_registry: dict[str, Any] | None = None,
+    theme: str | None = None,
+    parent_variables: dict[str, Any] | None = None,
+    *,
+    _resolve_jinja: bool = False,
+    resolved_style: MergedStyle,
+    parent_level: int = 0,
+) -> Layout:
+    """Build a unified Layout from face layout fields.
+
+    Converts rows/cols/grid/tabs to unified Layout structure.
+
+    Args:
+        face: AuthoredFace with layout fields
+        charts: Available charts for resolution
+        query_registry: Query registry for inline charts
+        face_id: Parent face ID
+        depth: Nesting depth
+        base_path: Base path for resolving external file references
+        default_source: Default source for inline queries
+        theme: Vega-Lite theme to inherit to nested faces
+        parent_variables: Variables from parent scope for template resolution
+        parent_level: Semantic heading level of the enclosing face. Passed
+            through to nested normalize_face calls so children compute their
+            own level as parent_level + (1 if they have a title else 0).
+
+    Returns:
+        Unified Layout structure
+    """
+    from dataface.core.compile.normalizer import slugify
+
+    # Track used chart IDs across all layout items to avoid duplicates
+    used_chart_ids = set(charts.keys())
+
+    if face.rows:
+        items = _resolve_layout_items(
+            face.rows,
+            charts,
+            query_registry,
+            face_id,
+            depth,
+            "row",
+            base_path,
+            default_source,
+            chart_registry,
+            theme,
+            used_chart_ids,
+            parent_variables,
+            _resolve_jinja=_resolve_jinja,
+            parent_level=parent_level,
+        )
+        return Layout(type=LayoutType.ROWS, items=items)
+
+    elif face.cols:
+        items = _resolve_layout_items(
+            face.cols,
+            charts,
+            query_registry,
+            face_id,
+            depth,
+            "col",
+            base_path,
+            default_source,
+            chart_registry,
+            theme,
+            used_chart_ids,
+            parent_variables,
+            _resolve_jinja=_resolve_jinja,
+            parent_level=parent_level,
+        )
+        return Layout(type=LayoutType.COLS, items=items)
+
+    elif face.grid:
+        grid_obj = face.grid
+        items = _resolve_grid_items(
+            grid_obj,
+            charts,
+            query_registry,
+            face_id,
+            depth,
+            base_path,
+            default_source,
+            chart_registry,
+            theme,
+            used_chart_ids,
+            parent_variables,
+            _resolve_jinja=_resolve_jinja,
+            parent_level=parent_level,
+        )
+        return Layout(
+            type=LayoutType.GRID,
+            items=items,
+            columns=grid_obj.columns,
+            gap=grid_obj.gap,
+            row_height=grid_obj.row_height,
+        )
+
+    elif face.tabs:
+        tabs_obj = face.tabs
+        items, tab_titles = _resolve_tab_items(
+            tabs_obj,
+            query_registry,
+            face_id,
+            depth,
+            base_path,
+            default_source,
+            chart_registry,
+            theme,
+            _resolve_jinja=_resolve_jinja,
+            resolved_style=resolved_style,
+            parent_level=parent_level,
+        )
+
+        # Compute tab slugs and variable name
+        tab_slugs = [slugify(title) for title in tab_titles]
+        # Validate slugs
+        for i, slug in enumerate(tab_slugs):
+            if not slug:
+                raise CompilationError(
+                    f"Tab title '{tab_titles[i]}' produces an empty slug. "
+                    "Tab titles must contain at least one alphanumeric character."
+                )
+        # Check for slug collisions
+        if len(set(tab_slugs)) != len(tab_slugs):
+            seen: set[str] = set()
+            for slug in tab_slugs:
+                if slug in seen:
+                    raise CompilationError(
+                        f"Duplicate tab slug '{slug}'. Tab titles must produce "
+                        "unique slugs (after lowercasing and replacing spaces with _)."
+                    )
+                seen.add(slug)
+
+        # Use explicit id, or generate a unique name from face_id
+        # (avoids collisions when multiple tabs layouts exist in nested faces)
+        tab_variable = tabs_obj.id or f"_tab_{face_id}"
+
+        # Resolve default tab from slug
+        default_slug = slugify(tabs_obj.default) if tabs_obj.default else tab_slugs[0]
+        default_tab = tab_slugs.index(default_slug) if default_slug in tab_slugs else 0
+
+        return Layout(
+            type=LayoutType.TABS,
+            items=items,
+            tab_titles=tab_titles,
+            tab_slugs=tab_slugs,
+            tab_variable=tab_variable,
+            default_tab=default_tab,
+            tab_position=tabs_obj.position,
+        )
+
+    # Content-only face. Orphan-chart detection lives post-compile so
+    # cross-face references work — see _collect_orphan_charts in compiler.py.
+    return Layout(type=LayoutType.ROWS, items=[])
+
+
+def _resolve_layout_items(
+    items: list[Any],
+    charts: dict[str, Chart],
+    query_registry: dict[str, AnyQuery],
+    face_id: str,
+    depth: int,
+    prefix: str,
+    base_path: Path | None = None,
+    default_source: str | None = None,
+    chart_registry: dict[str, Any] | None = None,
+    theme: str | None = None,
+    used_chart_ids: set | None = None,
+    parent_variables: dict[str, Any] | None = None,
+    _resolve_jinja: bool = False,
+    parent_level: int = 0,
+) -> list[LayoutItem]:
+    """Resolve layout items to LayoutItem objects.
+
+    Args:
+        items: List of layout items (strings, dicts, charts)
+        charts: Available charts
+        query_registry: Query registry
+        face_id: Parent face ID
+        depth: Nesting depth
+        prefix: Item prefix for ID generation
+        base_path: Base path for resolving external file references
+        default_source: Default source for inline queries
+        theme: Vega-Lite theme to inherit to nested faces
+        chart_registry: Raw chart definitions for nested face normalization
+        used_chart_ids: Set of already-used chart IDs for uniqueness
+        parent_variables: Variables from parent scope for template resolution
+
+    Returns:
+        List of resolved LayoutItem objects
+    """
+    resolved: list[LayoutItem] = []
+
+    # Initialize used_chart_ids with existing chart names if not provided
+    if used_chart_ids is None:
+        used_chart_ids = set(charts.keys())
+
+    for idx, item in enumerate(items):
+        # Handle foreach construct
+        if isinstance(item, ForeachItem):
+            foreach_items = _resolve_foreach_item(
+                item.foreach,
+                charts,
+                query_registry,
+                face_id,
+                depth,
+                f"{prefix}{idx}",
+                base_path,
+                default_source,
+                chart_registry,
+                theme,
+                used_chart_ids,
+                parent_variables,
+                parent_level=parent_level,
+            )
+            resolved.extend(foreach_items)
+        else:
+            layout_item = _resolve_single_item(
+                item,
+                charts,
+                query_registry,
+                face_id,
+                depth,
+                f"{prefix}{idx}",
+                base_path,
+                default_source,
+                chart_registry,
+                theme,
+                used_chart_ids,
+                parent_variables,
+                _resolve_jinja=_resolve_jinja,
+                parent_level=parent_level,
+            )
+            resolved.append(layout_item)
+
+    return resolved
+
+
+def _resolve_single_item(
+    item: Any,
+    charts: dict[str, Chart],
+    query_registry: dict[str, AnyQuery],
+    face_id: str,
+    depth: int,
+    item_id: str,
+    base_path: Path | None = None,
+    default_source: str | None = None,
+    chart_registry: dict[str, Any] | None = None,
+    theme: str | None = None,
+    used_chart_ids: set | None = None,
+    parent_variables: dict[str, Any] | None = None,
+    _resolve_jinja: bool = False,
+    parent_level: int = 0,
+) -> LayoutItem:
+    """Resolve a single layout item.
+
+    Args:
+        item: Layout item to resolve
+        charts: Available charts
+        query_registry: Query registry
+        theme: Vega-Lite theme to inherit to nested faces
+        face_id: Parent face ID
+        depth: Nesting depth
+        item_id: ID for this item (fallback for inline charts)
+        base_path: Base path for resolving external file references
+        default_source: Default source for inline queries
+        chart_registry: Raw chart definitions for nested face normalization
+        used_chart_ids: Set of already-used chart IDs for uniqueness
+        parent_variables: Variables from parent scope for template resolution
+
+    Returns:
+        Resolved LayoutItem
+    """
+    # String reference to chart OR board file import
+    if isinstance(item, str):
+        # Check for board file import (ends with .yml or .yaml)
+        if item.endswith(".yml") or item.endswith(".yaml"):
+            return _resolve_board_file_import(
+                item,
+                query_registry,
+                face_id,
+                depth,
+                item_id,
+                base_path,
+                default_source,
+                chart_registry,
+                theme,
+                parent_variables,
+                _resolve_jinja=_resolve_jinja,
+                parent_level=parent_level,
+            )
+        elif item in charts:
+            return LayoutItem(type="chart", chart=charts[item])
+        else:
+            raise ReferenceError(item, "layout item")
+
+    # Already a Chart
+    if isinstance(item, Chart):
+        return LayoutItem(type="chart", chart=item)
+
+    # dict[str, AuthoredChart]: {"my_chart": AuthoredChart(...)}
+    if isinstance(item, dict):
+        if len(item) != 1:
+            raise CompilationError(
+                f"Named chart dict must have exactly one key, got: {list(item.keys())}"
+            )
+        _chart_name, chart_def = next(iter(item.items()))
+        chart_dict = chart_def.model_dump(exclude_none=True)
+        if used_chart_ids is None:
+            used_chart_ids = set(charts.keys())
+        inline_id = _generate_inline_chart_id(chart_dict, item_id, used_chart_ids)
+        source_path = f"{item_id.replace('row', 'rows[').replace('col', 'cols[')}]"
+        chart = _normalize_chart(
+            inline_id,
+            chart_dict,
+            query_registry,
+            base_path,
+            default_source,
+            source_path=source_path,
+        )
+        return LayoutItem(type="chart", chart=chart)
+
+    # Pre-validated AuthoredFace (typed inline nested face from rows/cols)
+    if isinstance(item, AuthoredFace):
+        from dataface.core.compile.normalizer import normalize_face
+
+        # In foreach context, resolve Jinja templates baked into the typed face.
+        # Pydantic parsed templates as literal strings; dump to dict, resolve, re-validate.
+        if _resolve_jinja and parent_variables:
+            face_dict = item.model_dump(exclude_none=True, by_alias=False)
+            face_dict = _resolve_dict_templates(face_dict, parent_variables)
+            item = AuthoredFace.model_validate(face_dict)
+
+        details = item.details
+        user_width = str(item.width) if item.width is not None else None
+        layout_height = str(item.height) if item.height is not None else None
+        _validate_dimension(user_width, "width")
+        _validate_dimension(layout_height, "height")
+
+        compiled_nested = normalize_face(
+            item,
+            face_id=f"{face_id}_{item_id}",
+            parent_context={
+                "parent_id": face_id,
+                "base_path": base_path,
+                "default_source": default_source,
+                "theme": theme,
+                "variables": parent_variables,
+                "_resolve_jinja": _resolve_jinja,
+            },
+            query_registry=query_registry,
+            chart_registry=chart_registry,
+            depth=depth + 1,
+            base_path=base_path,
+            parent_level=parent_level,
+        )
+
+        details_kwargs: dict[str, Any] = {}
+        if details:
+            details_id = item.id or f"_details_{item_id}"
+            details_kwargs = {
+                "details_variable": details_id,
+                "details_summary": details.summary,
+                "details_expanded_summary": details.expanded_title or details.summary,
+            }
+            compiled_nested.meta["details_expanded_default"] = details.expanded
+
+        return LayoutItem(
+            type="face",
+            face=compiled_nested,
+            user_width=user_width,
+            layout_height=layout_height,
+            description=item.description,
+            visible=item.visible,
+            **details_kwargs,
+        )
+
+    # Pre-validated chart patch (typed inline chart from rows/cols)
+    if isinstance(item, _SharedChartFields):
+        if used_chart_ids is None:
+            used_chart_ids = set(charts.keys())
+        # exclude_none=True: None-defaulted fields must be absent so _normalize_chart's
+        # auto-derive guards ("title" not in chart_dict) fire correctly.
+        # visible is excluded=True on AuthoredChart so it won't appear in chart_dict.
+        chart_dict = item.model_dump(exclude_none=True)
+        inline_id = _generate_inline_chart_id(chart_dict, item_id, used_chart_ids)
+        source_path = f"{item_id.replace('row', 'rows[').replace('col', 'cols[')}]"
+        chart = _normalize_chart(
+            inline_id,
+            chart_dict,
+            query_registry,
+            base_path,
+            default_source,
+            source_path=source_path,
+        )
+        return LayoutItem(type="chart", chart=chart, visible=item.visible)
+
+    raise CompilationError(f"Invalid layout item type: {type(item)}")
+
+
+# Layout keys that should not have templates resolved (processed by layout resolution)
+_LAYOUT_KEYS = frozenset({"rows", "cols", "grid", "tabs"})
+
+
+def _resolve_dict_templates(
+    data: dict[str, Any],
+    variables: dict[str, Any],
+) -> dict[str, Any]:
+    """Resolve Jinja templates recursively in dict values.
+
+    Used to resolve loop variables and inherited variables in nested face
+    definitions created by foreach (compile-time static expansion).
+
+    Args:
+        data: Dict with potentially templated string values
+        variables: Variables for Jinja resolution
+
+    Returns:
+        Dict with resolved string values
+    """
+    from dataface.core.compile.jinja import resolve_jinja_template
+
+    result: dict[str, Any] = {}
+    for key, value in data.items():
+        if isinstance(value, str):
+            # Resolve Jinja templates in strings
+            result[key] = resolve_jinja_template(value, variables, strict=False)
+        elif isinstance(value, dict):
+            # Recurse into nested dicts
+            result[key] = _resolve_dict_templates(value, variables)
+        elif isinstance(value, list):
+            # Don't recurse into layout items - those are processed by _resolve_layout_items
+            if key in _LAYOUT_KEYS:
+                result[key] = value
+            else:
+                result[key] = [
+                    (
+                        _resolve_dict_templates(v, variables)
+                        if isinstance(v, dict)
+                        else (
+                            resolve_jinja_template(v, variables, strict=False)
+                            if isinstance(v, str)
+                            else v
+                        )
+                    )
+                    for v in value
+                ]
+        else:
+            result[key] = value
+    return result
+
+
+def _resolve_board_file_import(
+    file_path: str,
+    query_registry: dict[str, AnyQuery],
+    face_id: str,
+    depth: int,
+    item_id: str,
+    base_path: Path | None = None,
+    default_source: str | None = None,
+    chart_registry: dict[str, Any] | None = None,
+    theme: str | None = None,
+    parent_variables: dict[str, Any] | None = None,
+    _resolve_jinja: bool = False,
+    parent_level: int = 0,
+) -> LayoutItem:
+    """Load and resolve a board file import.
+
+    Board file imports allow including external YAML face files in layouts.
+    The imported face inherits variables from the parent context.
+
+    Args:
+        file_path: Path to the YAML file (relative to base_path or absolute)
+        charts: Available charts
+        query_registry: Query registry
+        face_id: Parent face ID
+        depth: Nesting depth
+        item_id: ID for this item
+        base_path: Base path for resolving relative file paths
+        default_source: Default source for inline queries
+        chart_registry: Raw chart definitions for nested face normalization
+        theme: Vega-Lite theme to inherit
+        used_chart_ids: Set of already-used chart IDs for uniqueness
+        parent_variables: Variables from parent scope for template resolution
+        _resolve_jinja: If True, resolve Jinja templates in the YAML content
+                     (foreach creates static faces; all templates baked at compile time).
+                     If False, skip YAML content resolution so interactive variables
+                     remain as templates and are resolved at render time.
+
+    Returns:
+        LayoutItem containing the compiled nested face
+
+    Raises:
+        CompilationError: If file not found or invalid
+    """
+    from dataface.core.compile.jinja import resolve_jinja_template
+    from dataface.core.compile.normalizer import normalize_face
+
+    # Resolve the file path (might contain Jinja templates for parameterised imports
+    # like `partials/{{ chart_type }}.yml`). This always uses parent_variables so
+    # file paths with interactive variable defaults still resolve at compile time.
+    parent_variables = parent_variables or {}
+    resolved_path = resolve_jinja_template(file_path, parent_variables, strict=False)
+
+    # Resolve relative to base_path
+    full_path = base_path / resolved_path if base_path else Path(resolved_path)
+
+    if not full_path.exists():
+        raise CompilationError(
+            f"Board file not found: '{resolved_path}' "
+            f"(resolved from '{file_path}', base_path={base_path})"
+        )
+
+    # Load and parse the YAML file
+    try:
+        yaml_content = full_path.read_text()
+        # Only resolve Jinja templates in the YAML content when inside a foreach.
+        # Foreach creates static compile-time faces, so all templates (loop vars +
+        # interactive defaults) must be baked in. For regular imports, leave
+        # templates intact so they are resolved dynamically at render time.
+        if _resolve_jinja:
+            yaml_content = resolve_jinja_template(
+                yaml_content, parent_variables, strict=False
+            )
+        face_data = yaml.safe_load(yaml_content)
+    except yaml.YAMLError as e:
+        raise CompilationError(
+            f"Failed to parse board file '{resolved_path}': {e}"
+        ) from e
+    except OSError as e:
+        raise CompilationError(
+            f"Failed to read board file '{resolved_path}': {e}"
+        ) from e
+
+    if not isinstance(face_data, dict):
+        raise CompilationError(
+            f"Board file '{resolved_path}' must contain a YAML dictionary"
+        )
+
+    # Convert raw YAML dict to AuthoredFace; model_validate handles all nested models.
+    nested_face = AuthoredFace.model_validate(face_data)
+
+    # Build parent context with variables from parent scope
+    parent_context = {
+        "parent_id": face_id,
+        "base_path": full_path.parent,  # Use imported file's directory as base
+        "default_source": default_source,
+        "theme": theme,
+        "variables": parent_variables,  # Pass variables to child
+        "_resolve_jinja": _resolve_jinja,  # Propagate foreach context to children
+    }
+
+    # Compile the nested face
+    compiled_nested = normalize_face(
+        nested_face,
+        face_id=f"{face_id}_{item_id}",
+        parent_context=parent_context,
+        query_registry=query_registry,
+        chart_registry=chart_registry,
+        depth=depth + 1,
+        base_path=full_path.parent,
+        parent_level=parent_level,
+    )
+
+    return LayoutItem(type="face", face=compiled_nested)
+
+
+def _resolve_foreach_item(
+    foreach_config: ForeachConfig,
+    charts: dict[str, Chart],
+    query_registry: dict[str, AnyQuery],
+    face_id: str,
+    depth: int,
+    item_id: str,
+    base_path: Path | None = None,
+    default_source: str | None = None,
+    chart_registry: dict[str, Any] | None = None,
+    theme: str | None = None,
+    used_chart_ids: set | None = None,
+    parent_variables: dict[str, Any] | None = None,
+    parent_level: int = 0,
+) -> list[LayoutItem]:
+    """Resolve a foreach construct that iterates over inline data.
+
+    foreach allows dynamically generating layout items at compile time.
+    Each row from the inline data becomes available as a loop variable,
+    accessible via dot notation (e.g., {{ col.name }}).
+
+    Example YAML:
+        rows:
+          - foreach:
+              query:
+                data:
+                  - name: "revenue"
+                    type: "numeric"
+                  - name: "date"
+                    type: "date"
+              as: col
+              items:
+                - 'partials/{{ col.type }}.yml'
+
+    Note: At compile time, foreach only works with inline data (query.data).
+    Query references are not executed during compilation.
+
+    Args:
+        foreach_config: Validated ForeachConfig with query, as_, and items.
+        charts: Available charts
+        query_registry: Query registry
+        face_id: Parent face ID
+        depth: Nesting depth
+        item_id: ID prefix for generated items
+        base_path: Base path for resolving external file references
+        default_source: Default source for inline queries
+        chart_registry: Raw chart definitions for nested face normalization
+        theme: Vega-Lite theme to inherit
+        used_chart_ids: Set of already-used chart IDs for uniqueness
+        parent_variables: Variables from parent scope
+
+    Returns:
+        List of LayoutItems generated from the foreach iteration
+    """
+    query_config = foreach_config.query
+    loop_var = foreach_config.as_
+    item_templates = foreach_config.items
+    parent_variables = parent_variables or {}
+
+    # Extract inline data from query config
+    # At compile time, foreach only works with inline data
+    static_data = _get_foreach_data(query_config)
+    if not static_data:
+        return []
+
+    # Generate layout items for each row
+    resolved_items: list[LayoutItem] = []
+    for idx, row in enumerate(static_data):
+        loop_context = _build_loop_context(row, loop_var, parent_variables)
+
+        for template_idx, template_item in enumerate(item_templates):
+            layout_item = _resolve_single_item(
+                template_item,
+                charts,
+                query_registry,
+                face_id,
+                depth,
+                f"{item_id}_foreach{idx}_{template_idx}",
+                base_path,
+                default_source,
+                chart_registry,
+                theme,
+                used_chart_ids,
+                loop_context,
+                _resolve_jinja=True,
+                parent_level=parent_level,
+            )
+            resolved_items.append(layout_item)
+
+    return resolved_items
+
+
+def _get_foreach_data(query_config: ForeachQuery) -> list[dict[str, Any]] | None:
+    """Extract data for foreach iteration from a ForeachQuery.
+
+    Args:
+        query_config: Validated ForeachQuery with optional data or static_data.
+
+    Returns:
+        List of row dicts for iteration, or None if no data.
+    """
+    data = query_config.data or query_config.static_data
+    if isinstance(data, list):
+        return data
+    return None
+
+
+def _build_loop_context(
+    row: Any,
+    loop_var: str,
+    parent_variables: dict[str, Any],
+) -> dict[str, Any]:
+    """Build the variable context for a foreach iteration.
+
+    The loop variable is accessible via dot notation: {{ col.field }}
+    This keeps variable scoping explicit and avoids shadowing parent variables.
+
+    Args:
+        row: Current row data (dict or scalar)
+        loop_var: Name of the loop variable
+        parent_variables: Variables inherited from parent scope
+
+    Returns:
+        Combined context dict for Jinja resolution
+    """
+    loop_context = dict(parent_variables)
+
+    if isinstance(row, dict):
+        # Row is a dict - accessible as {{ loop_var.field }}
+        loop_context[loop_var] = row
+    else:
+        # Scalar value - wrap in dict with 'value' key
+        loop_context[loop_var] = {"value": row}
+
+    return loop_context
+
+
+def _resolve_grid_items(
+    grid: GridLayout,
+    charts: dict[str, Chart],
+    query_registry: dict[str, AnyQuery],
+    face_id: str,
+    depth: int,
+    base_path: Path | None = None,
+    default_source: str | None = None,
+    chart_registry: dict[str, Any] | None = None,
+    theme: str | None = None,
+    used_chart_ids: set | None = None,
+    parent_variables: dict[str, Any] | None = None,
+    _resolve_jinja: bool = False,
+    parent_level: int = 0,
+) -> list[LayoutItem]:
+    """Resolve grid layout items.
+
+    Auto-calculates col/row positions for items without explicit positioning.
+    Items flow left-to-right, wrapping to the next row when they exceed
+    the column count.
+
+    Args:
+        grid: GridLayout definition
+        charts: Available charts
+        query_registry: Query registry
+        face_id: Parent face ID
+        depth: Nesting depth
+        base_path: Base path for resolving external file references
+        default_source: Default source for inline queries
+        chart_registry: Raw chart definitions for nested face normalization
+        theme: Vega-Lite theme to inherit to nested faces
+        parent_variables: Variables from parent scope for template resolution
+
+    Returns:
+        List of LayoutItem with grid positioning
+    """
+    resolved: list[LayoutItem] = []
+    columns = grid.columns
+
+    # Track grid occupancy for auto-positioning
+    # For items without explicit position, place left-to-right, top-to-bottom
+    current_col = 0
+    current_row = 0
+
+    for idx, grid_item in enumerate(grid.items):
+        item = grid_item.item
+        layout_item = _resolve_single_item(
+            item,
+            charts,
+            query_registry,
+            face_id,
+            depth,
+            f"grid{idx}",
+            base_path,
+            default_source,
+            chart_registry,
+            theme,
+            used_chart_ids,
+            parent_variables,
+            _resolve_jinja=_resolve_jinja,
+            parent_level=parent_level,
+        )
+
+        # Get span values (default to 1)
+        # Support 'width' as alias for 'col_span' and 'height' as alias for 'row_span'
+        # This is more intuitive for users (width: 6 means span 6 columns)
+        col_span = grid_item.col_span or grid_item.width or 1
+        row_span = grid_item.row_span or grid_item.height or 1
+
+        # Use explicit position if provided, otherwise auto-calculate
+        if grid_item.col is not None:
+            item_col = grid_item.col
+        else:
+            # Auto-position: check if item fits in current row
+            if current_col + col_span > columns:
+                # Wrap to next row
+                current_col = 0
+                current_row += 1
+            item_col = current_col
+            # Advance position for next item
+            current_col += col_span
+
+        item_row = grid_item.row if grid_item.row is not None else current_row
+
+        # Set grid positioning
+        layout_item.col = item_col
+        layout_item.row = item_row
+        layout_item.col_span = col_span
+        layout_item.row_span = row_span
+        if grid_item.description and not layout_item.description:
+            layout_item.description = grid_item.description
+        resolved.append(layout_item)
+
+    return resolved
+
+
+def _resolve_tab_items(
+    tabs: TabLayout,
+    query_registry: dict[str, AnyQuery],
+    face_id: str,
+    depth: int,
+    base_path: Path | None = None,
+    default_source: str | None = None,
+    chart_registry: dict[str, Any] | None = None,
+    theme: str | None = None,
+    *,
+    _resolve_jinja: bool = False,
+    resolved_style: MergedStyle,
+    parent_level: int = 0,
+) -> tuple[list[LayoutItem], list[str]]:
+    """Resolve tab layout items.
+
+    Args:
+        tabs: TabLayout definition
+        charts: Available charts
+        query_registry: Query registry
+        face_id: Parent face ID
+        theme: Vega-Lite theme to inherit to nested faces
+        depth: Nesting depth
+        base_path: Base path for resolving external file references
+        default_source: Default source for inline queries
+        parent_variables: Variables from parent scope for template resolution
+        chart_registry: Raw chart definitions for nested face normalization
+
+    Returns:
+        Tuple of (items, tab_titles)
+    """
+    from dataface.core.compile.normalizer import normalize_face
+
+    resolved: list[LayoutItem] = []
+    titles: list[str] = []
+
+    for idx, tab_item in enumerate(tabs.items):
+        titles.append(tab_item.title)
+
+        # Tab items can have nested layouts
+        tab_dict = tab_item.model_dump(exclude_none=True)
+
+        if any(k in tab_dict for k in ["rows", "cols", "grid", "tabs"]):
+            # Tab is a nested face. Pop TabItem-only fields not on AuthoredFace,
+            # then model_validate so style errors include the "style." loc prefix.
+            tab_dict.pop("icon", None)
+            nested_face = AuthoredFace.model_validate(tab_dict)
+            compiled_nested = normalize_face(
+                nested_face,
+                face_id=f"{face_id}_tab{idx}",
+                parent_context={
+                    "parent_id": face_id,
+                    "base_path": base_path,
+                    "default_source": default_source,
+                    "theme": theme,
+                    "_resolve_jinja": _resolve_jinja,
+                },
+                query_registry=query_registry,
+                chart_registry=chart_registry,
+                depth=depth + 1,
+                base_path=base_path,
+                parent_level=parent_level,
+            )
+            resolved.append(
+                LayoutItem(
+                    type="face",
+                    face=compiled_nested,
+                    description=tab_item.description,
+                )
+            )
+
+        elif tab_item.text:
+            # Content-only tab
+            content_face = Face(
+                id=f"{face_id}_tab{idx}",
+                title=tab_item.title,
+                description=tab_item.description or "",
+                text=tab_item.text,
+                layout=Layout(type=LayoutType.ROWS, items=[]),
+                theme=theme,
+                resolved_style=resolved_style,
+                level=parent_level + 1,
+            )
+            resolved.append(
+                LayoutItem(
+                    type="face",
+                    face=content_face,
+                    description=tab_item.description,
+                )
+            )
+
+        else:
+            # Empty tab
+            empty_face = Face(
+                id=f"{face_id}_tab{idx}",
+                title=tab_item.title,
+                description=tab_item.description or "",
+                layout=Layout(type=LayoutType.ROWS, items=[]),
+                theme=theme,
+                resolved_style=resolved_style,
+                level=parent_level + 1,
+            )
+            resolved.append(
+                LayoutItem(
+                    type="face",
+                    face=empty_face,
+                    description=tab_item.description,
+                )
+            )
+
+    return resolved, titles