dataface 0.1.2__py3-none-any.whl

dataface/core/render/layout_sizing.py

@@ -0,0 +1,865 @@
+"""Data-aware layout sizing for the render pipeline.
+
+Stage: RENDER
+Purpose: Calculate layout dimensions using actual query data and rendered chart heights.
+
+This module owns all data-aware sizing logic that requires an executor or vl-convert:
+- Render-first Vega sizing (render charts to get true heights, cache SVGs)
+- Table sizing from actual row counts
+- Cols height alignment (re-render shorter Vega items at max height)
+
+It injects a HeightProvider callback into the pure layout algorithms in
+compile/sizing.py, keeping the compile module free of render/execute imports.
+
+Entry Point:
+    - calculate_data_aware_layout(face, executor, variables, render_first)
+      Called from renderer.py after query pre-execution.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from dataface.core.compile.models.chart.compiled import (
+    NON_ASPECT_RATIO_TYPES,
+    Chart,
+)
+from dataface.core.compile.models.face.compiled import Face, Layout, LayoutItem
+from dataface.core.compile.sizing import (
+    HeightProvider,
+    calculate_layout_height,
+    calculate_layout_items,
+    get_chart_content_height,
+    get_face_gap,
+    get_item_content_height,
+    get_title_height,
+)
+from dataface.core.execute.errors import ExecutionError
+from dataface.core.render.chart.render_single import RenderCache
+from dataface.core.render.chart.spec_builders import additive_padding
+from dataface.core.render.errors import ChartDataError
+
+if TYPE_CHECKING:
+    from dataface.core.compile.models.style.merged import MergedStyle
+    from dataface.core.execute.executor import Executor
+
+_log = logging.getLogger(__name__)
+_FIXED_ASPECT_PIE_TYPES = frozenset({"pie", "arc"})
+
+
+@dataclass
+class SizingRenderCtx:
+    """Render context threaded through data-aware sizing.
+
+    When present, the data-aware height provider renders Vega-Lite charts via
+    vl-convert instead of using aspect-ratio estimates. Results are cached
+    in render_cache for reuse by the render pass.
+    """
+
+    resolved_style: MergedStyle
+    render_cache: RenderCache = field(default_factory=dict)
+    vega_config: dict[str, Any] | None = None
+    executor: Executor | None = None
+    variables: dict[str, Any] | None = None
+    # Heading level of the face containing the charts being sized (root=1, nested=2, …).
+    # Chart title uses face_level + 1; sizer and renderer must agree.
+    face_level: int = 1
+    # Maps chart_id → corrected spec.width for data_table charts.
+    # autosize:pad makes outer SVG wider than spec.width by a constant overhead;
+    # the render-first pass measures this and stores the shrunk spec.width here so
+    # _align_cols_heights can reuse it instead of item.width (which would re-overflow).
+    data_table_corrected_widths: dict[str, float] = field(default_factory=dict)
+    # Maps (chart_id, slot_width) → natural rendered height.
+    # Populated during the sizing pass; used to deduplicate renders of the same
+    # chart at the same width and to drive the close-enough skip in _align_cols_heights.
+    natural_heights: dict[tuple[str, float], float] = field(default_factory=dict)
+
+
+def _nested_render_ctx(
+    render_ctx: SizingRenderCtx,
+    nested_face: Face,
+) -> SizingRenderCtx:
+    """Build a SizingRenderCtx for a nested face, inheriting the shared cache."""
+    from dataface.core.compile.vega_config import compile_effective_vega_config
+
+    return SizingRenderCtx(
+        render_cache=render_ctx.render_cache,
+        natural_heights=render_ctx.natural_heights,
+        vega_config=compile_effective_vega_config(nested_face.theme),
+        resolved_style=nested_face.resolved_style,
+        executor=render_ctx.executor,
+        variables=render_ctx.variables,
+        face_level=nested_face.level,
+        data_table_corrected_widths=render_ctx.data_table_corrected_widths,
+    )
+
+
+def _get_table_height_from_data(
+    chart: Chart,
+    executor: Executor,
+    variables: dict[str, Any] | None,
+    resolved_style: MergedStyle,
+    width: float | None = None,
+    face_level: int = 1,
+) -> float:
+    """Calculate table height from actual row count.
+
+    ``resolved_style`` is the face's resolved style (the same value the renderer
+    receives via ``board_style``). Face-level and chart-local overrides are merged
+    via ``build_resolved_style`` so sizer and renderer agree on row heights,
+    padding, and header dimensions.
+
+    ``width`` drives the title font size (via ``chart_title_spec``) and must
+    match what the renderer will see at layout time. When ``None``, falls back
+    to the renderer's own ``TABLE_DEFAULT_WIDTH`` so both stay in lockstep.
+
+    If the query fails, sizes for an error message display.
+    """
+    from dataface.core.compile.style_cascade import build_resolved_style
+    from dataface.core.render.chart.table import (
+        TABLE_DEFAULT_WIDTH,
+        compute_table_title_block_layout,
+    )
+
+    effective_charts = build_resolved_style(resolved_style, chart.style)
+    tc = effective_charts.table  # TableChartStyle — face-merged, all with defaults
+
+    row_height = int(tc.row.height)
+    # When the header row is hidden, it contributes no vertical extent —
+    # matches the renderer's `if not tc.header.visible: header_height = 0` branch.
+    header_height = int(tc.header.height) if tc.header.visible else 0
+    padding_y = int(tc.outer_padding)
+    title_height = compute_table_title_block_layout(
+        chart_title=chart.title,
+        chart_subtitle=chart.subtitle,
+        table_width=width if width is not None else TABLE_DEFAULT_WIDTH,
+        tc=tc,
+        padding=padding_y,
+        title_style=effective_charts.title,
+        resolved_chart_style=effective_charts,
+        face_level=face_level,
+    ).height
+    bottom_padding = int(tc.bottom_padding)
+
+    # Chart-local pagination is pre-merged into effective_charts.pagination by
+    # build_resolved_style — read the resolved page_size off the merged value.
+    pagination = effective_charts.pagination
+    resolved_page_size = (
+        pagination.page_size if pagination is not None and pagination.enabled else None
+    )
+
+    # Header-body gap also vanishes when header is hidden — the renderer
+    # uses the same zero-out so sizer + renderer agree on total height.
+    header_body_gap = int(row_height * 0.25) if tc.header.visible else 0
+
+    try:
+        data = executor.execute_chart(chart, variables)
+        row_count = len(data)
+    except ExecutionError as exc:
+        # Migrate-or-fail: only the query-failed signal warrants a static height
+        # fallback. ValueError/OSError/RuntimeError/LookupError are bug-class —
+        # let them surface loudly so the underlying bug is fixed, not masked.
+        _log.warning("Table height estimation failed for chart %r: %s", chart.id, exc)
+        return (
+            title_height
+            + header_height
+            + header_body_gap
+            + row_height
+            + padding_y
+            + bottom_padding
+        )
+
+    multi_page = resolved_page_size is not None and row_count > resolved_page_size
+    if resolved_page_size is not None:
+        row_count = min(row_count, resolved_page_size)
+    height = (
+        title_height
+        + header_height
+        + header_body_gap
+        + (row_count * row_height)
+        + padding_y
+        + bottom_padding
+    )
+    if multi_page:
+        from dataface.core.render.chart.table import _PAGINATION_CONTROL_HEIGHT
+
+        height += _PAGINATION_CONTROL_HEIGHT
+    return height
+
+
+def _make_data_aware_height_provider(
+    render_ctx: SizingRenderCtx,
+    executor: Executor,
+    variables: dict[str, Any] | None,
+    card_padding: float,
+) -> HeightProvider:
+    """Create a HeightProvider that uses render-first sizing for Vega charts.
+
+    For Vega-Lite charts: renders via vl-convert, caches SVG, returns actual height.
+    For tables: uses actual row counts from executor.
+    For everything else: delegates to the static compile-time calculator.
+
+    Render-first Vega sizing (vl-convert renders) only fires when
+    render_ctx.executor is not None. When render_ctx.executor is None
+    (render_first=False), the provider falls back to static aspect-ratio
+    estimates for Vega charts while still sizing tables from row counts.
+    """
+    from dataface.core.render.chart.render_single import render_chart_to_svg
+
+    def provider(
+        item: LayoutItem,
+        card_gap: float,
+        gap: float,
+        width: float,
+        variable_defaults: dict[str, Any] | None,
+    ) -> float:
+        if item.type == "chart" and item.chart:
+            card_pad = card_padding
+
+            # Table: use actual row counts
+            if item.chart.type == "table":
+                return (
+                    _get_table_height_from_data(
+                        item.chart,
+                        executor,
+                        variables,
+                        resolved_style=render_ctx.resolved_style,
+                        width=width,
+                        face_level=render_ctx.face_level,
+                    )
+                    + 2 * card_pad
+                )
+
+            if item.chart.type == "callout":
+                _chart_svg, _, actual_height = render_chart_to_svg(
+                    item.chart,
+                    executor,
+                    variables or {},
+                    width,
+                    height=None,
+                    vega_config=render_ctx.vega_config,
+                    resolved_style=render_ctx.resolved_style,
+                    face_level=render_ctx.face_level,
+                )
+                render_ctx.render_cache[(item.chart.id, width, actual_height)] = (
+                    _chart_svg,
+                    actual_height,
+                )
+                render_ctx.natural_heights[(item.chart.id, width)] = actual_height
+                return actual_height
+
+            # spark_bar: natural-height SVG renderer — renders content-first.
+            # Returns natural_height + 2*card_pad to match SVG_LAYOUT_PADDED_TYPES behavior
+            # (card_pad inset applied via translate in render_chart_item).
+            # Not cached: rendering.py skips render_cache for SVG_LAYOUT_PADDED_TYPES,
+            # so the final render pass re-renders regardless.
+            if item.chart.type == "spark_bar":
+                _chart_svg, _, actual_height = render_chart_to_svg(
+                    item.chart,
+                    executor,
+                    variables or {},
+                    width,
+                    height=None,
+                    vega_config=render_ctx.vega_config,
+                    resolved_style=render_ctx.resolved_style,
+                    face_level=render_ctx.face_level,
+                )
+                return actual_height + 2 * card_pad
+
+            # Render-first Vega sizing.
+            # Vega charts now render at full item width with card_pad as internal
+            # Vega padding, so the returned SVG height already includes the inset.
+            # Do NOT add 2*card_pad here — it would double-count the padding.
+            if (
+                render_ctx.executor is not None
+                and item.chart.type not in NON_ASPECT_RATIO_TYPES
+            ):
+                render_inner_width = width
+                chart_padding = render_ctx.resolved_style.charts.padding
+                # static_estimate approximates Vega output height: marks + Vega padding
+                static_estimate = (
+                    get_chart_content_height(
+                        item.chart,
+                        width=render_inner_width,
+                        resolved_style=render_ctx.resolved_style,
+                    )
+                    + 2 * card_pad
+                )
+                # Use item.height when it has been pre-set (future: cols alignment
+                # pre-pass). In the normal sizing flow item.height is 0 here because
+                # _calculate_rows_dimensions fires the provider in its first pass before
+                # the second pass sets item.height.  _fix_slot_heights_in_tree runs after
+                # calculate_layout_items to re-render at the final slot height when the
+                # two values diverge (e.g. a 600px wrapper around an 800px estimate).
+                render_height = item.height if item.height > 0 else static_estimate
+
+                # Use cached result if already rendered at this width
+                if (item.chart.id, render_inner_width) in render_ctx.natural_heights:
+                    cached_height = render_ctx.natural_heights[
+                        (item.chart.id, render_inner_width)
+                    ]
+                    return max(cached_height, static_estimate)
+
+                try:
+                    chart_svg, actual_width, actual_height = render_chart_to_svg(
+                        item.chart,
+                        render_ctx.executor,
+                        render_ctx.variables or {},
+                        render_inner_width,
+                        height=render_height,
+                        vega_config=render_ctx.vega_config,
+                        resolved_style=render_ctx.resolved_style,
+                        padding=additive_padding(card_pad, chart_padding),
+                        face_level=render_ctx.face_level,
+                    )
+                except (ExecutionError, ChartDataError) as exc:
+                    # Migrate-or-fail: only ExecutionError (query failed) and
+                    # ChartDataError (vega-lite spec rejected) are expected
+                    # data-side failures we estimate around. KeyError/ValueError/
+                    # OSError/RuntimeError/LookupError are bug-class exceptions
+                    # — let them surface loudly, do not silently render an
+                    # aspect-ratio fallback that masks the bug.
+                    _log.warning(
+                        "Render-first sizing failed for chart %r "
+                        "(will use aspect-ratio estimate): %s",
+                        item.chart.id,
+                        exc,
+                    )
+                else:
+                    # Clamp: tiny overshoot (≤2px above static_estimate) → static_estimate.
+                    # Two-pass height correction (endpoint-label hconcat) can return
+                    # actual_height = static_estimate + ε due to fractional-pixel rounding.
+                    # Without the clamp, natural_heights differs by ε between endpoint_labels
+                    # ON and OFF, causing row_height drift. Undershoots are also snapped up.
+                    if actual_height - static_estimate <= 2.0:
+                        actual_height = static_estimate
+
+                    # autosize:pad (set by attach_data_table) makes the outer
+                    # SVG wider than render_inner_width by the y-axis label +
+                    # padding + legend overhead. Measure the first render's
+                    # actual outer width, compute the overhead, and re-render
+                    # with spec.width pre-shrunk so the second render's outer
+                    # SVG fits the allocated slot.
+                    # Pass height=static_estimate (not actual_height) to the
+                    # re-render: under autosize:pad, spec.height is the *inner*
+                    # plot rect, so Vega adds strip/axis on top — using
+                    # actual_height as spec.height would inflate the output by
+                    # ~strip_height on every re-render.
+                    # Store the shrunk width in data_table_corrected_widths so
+                    # _align_cols_heights can reuse it instead of item.width,
+                    # preventing the overhead from being re-applied on alignment.
+                    if item.chart.data_table is not None:
+                        overhead = actual_width - render_inner_width
+                        if overhead > 0:
+                            shrunk_width = max(render_inner_width - overhead, 1.0)
+                            try:
+                                chart_svg, _, rerender_height = render_chart_to_svg(
+                                    item.chart,
+                                    render_ctx.executor,
+                                    render_ctx.variables or {},
+                                    shrunk_width,
+                                    height=render_height,
+                                    vega_config=render_ctx.vega_config,
+                                    resolved_style=render_ctx.resolved_style,
+                                    padding=additive_padding(card_pad, chart_padding),
+                                    face_level=render_ctx.face_level,
+                                )
+                            except (ExecutionError, ChartDataError) as exc:
+                                _log.warning(
+                                    "Width-correction re-render failed for chart %r "
+                                    "(keeping first render): %s",
+                                    item.chart.id,
+                                    exc,
+                                )
+                            else:
+                                actual_height = max(rerender_height, static_estimate)
+                                render_ctx.data_table_corrected_widths[
+                                    item.chart.id
+                                ] = shrunk_width
+
+                    render_ctx.render_cache[
+                        (item.chart.id, render_inner_width, actual_height)
+                    ] = (chart_svg, actual_height)
+                    render_ctx.natural_heights[(item.chart.id, render_inner_width)] = (
+                        actual_height
+                    )
+                    return actual_height
+
+            # Fallback: static aspect-ratio estimate (marks + Vega padding)
+            return (
+                get_chart_content_height(
+                    item.chart,
+                    width=width,
+                    resolved_style=render_ctx.resolved_style,
+                )
+                + 2 * card_pad
+            )
+
+        if item.type == "face" and item.face:
+            data_aware = get_item_content_height(
+                item,
+                card_gap,
+                gap,
+                width,
+                variable_defaults,
+                height_provider=provider,
+                resolved_style=render_ctx.resolved_style,
+            )
+            return max(data_aware, item.height)
+
+        # Fallback for any other item types
+        return get_item_content_height(
+            item,
+            card_gap,
+            gap,
+            width,
+            variable_defaults,
+            height_provider=provider,
+            resolved_style=render_ctx.resolved_style,
+        )
+
+    return provider
+
+
+def _col_chart_body_target(
+    items: list[LayoutItem], render_ctx: SizingRenderCtx
+) -> float:
+    """Max natural chart body height across all items in a cols row.
+
+    For direct chart items uses the natural height from natural_heights.
+    For face items the logic depends on the face's inner layout:
+      - All-Vega rows face (every sub-item is a Vega chart): contribute
+        item.height (= sum of sub-chart heights + gaps, set by the sizing pass).
+        An adjacent direct chart must fill the same cell height.
+      - Any other face layout (mixed content, cols sub-layout, single chart):
+        contribute max(sub-chart natural heights) — the non-chart overhead must
+        not inflate adjacent chart bodies.
+    Non-aspect-ratio types (table, kpi, spark_bar) are excluded.
+    Returns 0.0 if no Vega charts are found.
+    """
+    max_h = 0.0
+    for item in items:
+        if item.chart is not None and item.chart.type not in NON_ASPECT_RATIO_TYPES:
+            h = render_ctx.natural_heights.get((item.chart.id, item.width))
+            if h is not None:
+                max_h = max(max_h, h)
+        elif item.face is not None:
+            sub_items = item.face.layout.items
+            is_all_vega_rows = (
+                item.face.layout.type == "rows"
+                and len(sub_items) > 1
+                and all(
+                    s.chart is not None and s.chart.type not in NON_ASPECT_RATIO_TYPES
+                    for s in sub_items
+                )
+            )
+            if is_all_vega_rows and item.height > 0:
+                # face item.height = sum(sub-chart heights) + inter-item gaps,
+                # computed by the sizing pass. Use it as-is so the adjacent
+                # direct chart fills the same cell.
+                max_h = max(max_h, item.height)
+            else:
+                for sub in sub_items:
+                    if (
+                        sub.chart is not None
+                        and sub.chart.type not in NON_ASPECT_RATIO_TYPES
+                    ):
+                        h = render_ctx.natural_heights.get((sub.chart.id, sub.width))
+                        if h is not None:
+                            max_h = max(max_h, h)
+    return max_h
+
+
+def _effective_alignment_target_for_chart(
+    chart: Chart,
+    width: float,
+    target_height: float,
+    render_ctx: SizingRenderCtx,
+) -> float:
+    """Return the per-chart alignment target, capping pie/arc growth."""
+    natural_h = render_ctx.natural_heights.get((chart.id, width))
+    if (
+        chart.type in _FIXED_ASPECT_PIE_TYPES
+        and natural_h is not None
+        and target_height > natural_h
+    ):
+        return natural_h
+    return target_height
+
+
+def _align_face_charts(
+    face_item: LayoutItem, target_height: float, render_ctx: SizingRenderCtx
+) -> None:
+    """Expand Vega charts inside a face item toward target_height.
+
+    The face bounds the expansion: charts can grow at most to face.layout.content_height
+    minus the space taken by non-chart siblings (rows layout only — stacked items share
+    vertical space). For cols layouts, items are side-by-side so non-chart siblings do
+    not reduce the Vega chart's available height.
+
+    Updates each chart's item.height so the render layer uses the correct cache key,
+    then delegates the actual re-render to _align_cols_heights.
+    """
+    assert face_item.face is not None, "_align_face_charts requires a face LayoutItem"
+    face = face_item.face
+    vega_count = sum(
+        1
+        for sub in face.layout.items
+        if sub.chart is not None and sub.chart.type not in NON_ASPECT_RATIO_TYPES
+    )
+    # cols layout: all side-by-side charts need equalization.
+    # non-cols with exactly 1 Vega chart (e.g. chart + text caption): safe to expand.
+    # non-cols with multiple Vega charts: stacked rows — equalizing would overflow the face.
+    if face.layout.type != "cols" and vega_count != 1:
+        return
+    content_h: float = face.layout.content_height
+    if content_h <= 0:
+        return
+
+    if face.layout.type == "cols":
+        # cols: items are side-by-side — non-chart siblings don't consume Vega height.
+        face_chart_max = content_h
+    else:
+        # rows with 1 Vega chart: stacked non-chart items (captions, KPIs) do consume height.
+        non_chart_h = sum(
+            sub.height
+            for sub in face.layout.items
+            if sub.chart is None or sub.chart.type in NON_ASPECT_RATIO_TYPES
+        )
+        face_chart_max = max(content_h - non_chart_h, 0.0)
+    effective = min(target_height, face_chart_max)
+
+    for sub in face.layout.items:
+        if sub.chart is not None and sub.chart.type not in NON_ASPECT_RATIO_TYPES:
+            sub.height = _effective_alignment_target_for_chart(
+                sub.chart,
+                sub.width,
+                effective,
+                render_ctx,
+            )
+
+    _align_cols_heights(face.layout.items, effective, render_ctx)
+
+
+def _align_cols_heights(
+    items: list[LayoutItem], target_height: float, render_ctx: SizingRenderCtx
+) -> None:
+    """Re-render shorter Vega cols items at target_height; update their cache entries.
+
+    Handles both direct chart items and face items (delegating to
+    _align_face_charts for the latter).  Non-Vega items (table, KPI) are not
+    re-rendered — their container gets the max height but their content stays
+    at its natural height.
+    """
+    from dataface.core.render.chart.render_single import render_chart_to_svg
+
+    card_pad = float(render_ctx.resolved_style.board.card_padding)
+    chart_padding = render_ctx.resolved_style.charts.padding
+
+    if render_ctx.executor is None:
+        return
+
+    executor = render_ctx.executor
+    variables = render_ctx.variables or {}
+
+    for item in items:
+        if item.face is not None:
+            _align_face_charts(item, target_height, render_ctx)
+            continue
+        if item.chart is None or item.chart.type in NON_ASPECT_RATIO_TYPES:
+            continue
+        chart_id = item.chart.id
+        natural_h = render_ctx.natural_heights.get((chart_id, item.width))
+        effective_target = _effective_alignment_target_for_chart(
+            item.chart,
+            item.width,
+            target_height,
+            render_ctx,
+        )
+        if natural_h is None or abs(natural_h - effective_target) < 1.0:
+            continue
+
+        # Vega-family: render at item width (or the corrected shrunk width for
+        # data_table charts). autosize:pad (activated by attach_data_table) makes
+        # the outer SVG wider than spec.width by a constant overhead; using item.width
+        # as spec.width would re-apply that overhead and overflow the allocated slot.
+        render_width = render_ctx.data_table_corrected_widths.get(chart_id, item.width)
+        try:
+            chart_svg, _, actual_height = render_chart_to_svg(
+                item.chart,
+                executor,
+                variables,
+                render_width,
+                height=effective_target,
+                vega_config=render_ctx.vega_config,
+                resolved_style=render_ctx.resolved_style,
+                padding=additive_padding(card_pad, chart_padding),
+                face_level=render_ctx.face_level,
+            )
+        except ChartDataError as exc:
+            # Migrate-or-fail: only ChartDataError (vega-lite rejected the spec)
+            # is an expected per-chart failure we keep going through. Other
+            # exception types are bug-class — let them surface loudly.
+            _log.warning(
+                "Cols alignment re-render failed for chart %r; "
+                "keeping original height: %s",
+                chart_id,
+                exc,
+            )
+            continue
+
+        # autosize:pad (set by attach_data_table) makes the outer SVG taller than
+        # spec.height by the strip + axis overhead. If inflation detected, compute
+        # the overhead and re-render with spec.height pre-shrunk so the outer SVG
+        # fits within target_height.
+        if item.chart.data_table is not None:
+            overhead = actual_height - effective_target
+            if overhead > 0:
+                corrected_height = max(effective_target - overhead, 1.0)
+                try:
+                    chart_svg, _, actual_height = render_chart_to_svg(
+                        item.chart,
+                        executor,
+                        variables,
+                        render_width,
+                        height=corrected_height,
+                        vega_config=render_ctx.vega_config,
+                        resolved_style=render_ctx.resolved_style,
+                        padding=additive_padding(card_pad, chart_padding),
+                        face_level=render_ctx.face_level,
+                    )
+                except ChartDataError as exc:
+                    _log.warning(
+                        "Height-correction re-render failed for chart %r "
+                        "(keeping first alignment render): %s",
+                        chart_id,
+                        exc,
+                    )
+
+        render_ctx.render_cache[(chart_id, item.width, effective_target)] = (
+            chart_svg,
+            actual_height,
+        )
+
+
+def _align_grid_rows(items: list[LayoutItem], render_ctx: SizingRenderCtx) -> None:
+    """Align Vega chart heights within each row of a grid layout.
+
+    Groups items by (row, height). Items with the same row and row_span share
+    the same height and form one visual row band to align.
+    """
+    row_groups: dict[tuple[int, float], list[LayoutItem]] = {}
+    for item in items:
+        key = (item.row or 0, item.height)
+        if key not in row_groups:
+            row_groups[key] = []
+        row_groups[key].append(item)
+    for (_, row_height), row_items in row_groups.items():
+        if len(row_items) > 1:
+            _align_cols_heights(row_items, row_height, render_ctx)
+
+
+def _fix_slot_heights_in_tree(layout: Layout, render_ctx: SizingRenderCtx) -> None:
+    """Re-render Vega charts whose slot height differs from the cached render height.
+
+    Called after calculate_layout_items has set all item.height values.
+    When a layout wrapper declares an explicit height (e.g. height: 600 on a
+    rows wrapper), the sizing provider may have rendered at the aspect-ratio
+    estimate (because item.height was 0 at provider call time). If the layout
+    algorithm then scaled the item.height down to the slot, the cache entry
+    (chart_id, width, estimate) won't match the renderer's lookup key
+    (chart_id, width, item.height). This pass re-renders at item.height and
+    updates the cache so the render pass hits without a fresh vl-convert call.
+
+    Only fires when item.height differs from the natural height by more than 1px
+    (avoids redundant re-renders for sub-pixel rounding differences).
+    """
+    from dataface.core.render.chart.render_single import render_chart_to_svg
+
+    if render_ctx.executor is None:
+        return
+
+    card_pad = float(render_ctx.resolved_style.board.card_padding)
+    chart_padding = render_ctx.resolved_style.charts.padding
+
+    for item in layout.items:
+        if item.face is not None:
+            nested_ctx = _nested_render_ctx(render_ctx, item.face)
+            _fix_slot_heights_in_tree(item.face.layout, nested_ctx)
+            continue
+
+        if item.chart is None or item.chart.type in NON_ASPECT_RATIO_TYPES:
+            continue
+        if item.height <= 0:
+            continue
+
+        chart_id = item.chart.id
+        natural_h = render_ctx.natural_heights.get((chart_id, item.width))
+        if natural_h is None or abs(natural_h - item.height) < 1.0:
+            continue
+
+        # Slot height differs from the rendered height — re-render at item.height.
+        render_width = render_ctx.data_table_corrected_widths.get(chart_id, item.width)
+        try:
+            chart_svg, _, actual_height = render_chart_to_svg(
+                item.chart,
+                render_ctx.executor,
+                render_ctx.variables or {},
+                render_width,
+                height=item.height,
+                vega_config=render_ctx.vega_config,
+                resolved_style=render_ctx.resolved_style,
+                padding=additive_padding(card_pad, chart_padding),
+                face_level=render_ctx.face_level,
+            )
+        except (ExecutionError, ChartDataError) as exc:
+            _log.warning(
+                "Slot-height re-render failed for chart %r "
+                "(keeping aspect-ratio render): %s",
+                chart_id,
+                exc,
+            )
+            continue
+
+        render_ctx.render_cache[(chart_id, item.width, item.height)] = (
+            chart_svg,
+            actual_height,
+        )
+        render_ctx.natural_heights[(chart_id, item.width)] = actual_height
+
+
+def _align_all_cols_in_tree(layout: Layout, render_ctx: SizingRenderCtx) -> None:
+    """Walk the layout tree depth-first and align cols/grid heights where needed."""
+    if render_ctx.render_cache and layout.items:
+        if layout.type == "cols":
+            chart_target = _col_chart_body_target(layout.items, render_ctx)
+            if chart_target > 0:
+                for item in layout.items:
+                    if (
+                        item.chart is not None
+                        and item.chart.type not in NON_ASPECT_RATIO_TYPES
+                    ):
+                        item.height = _effective_alignment_target_for_chart(
+                            item.chart,
+                            item.width,
+                            chart_target,
+                            render_ctx,
+                        )
+                _align_cols_heights(layout.items, chart_target, render_ctx)
+        elif layout.type == "grid":
+            _align_grid_rows(layout.items, render_ctx)
+
+    # Nested layouts are always modeled as nested faces in the Face tree;
+    # face-only recursion is correct and complete.
+    for item in layout.items:
+        if item.face is not None and item.face.layout.items:
+            nested_ctx = _nested_render_ctx(render_ctx, item.face)
+            _align_all_cols_in_tree(item.face.layout, nested_ctx)
+
+
+def calculate_data_aware_layout(
+    face: Face,
+    executor: Executor,
+    variables: dict[str, Any] | None = None,
+    render_first: bool = True,
+) -> tuple[Face, RenderCache]:
+    """Calculate layout dimensions using actual query data for table sizing.
+
+    Like calculate_layout(), but uses the executor to get actual row counts
+    for table charts and renders Vega-Lite charts to get true heights.
+
+    Must be called after execute_face_batch() so query results are cached.
+
+    Args:
+        face: Face with layout structure
+        executor: Executor with cached query results
+        variables: Variable values for query execution
+        render_first: When True, Vega-Lite charts are rendered during sizing to
+            get actual heights (render-first sizing). Set False for non-SVG
+            formats (yaml/json/text) to avoid unnecessary chart rendering.
+
+    Returns:
+        (Face with calculated dimensions, render_cache mapping chart_id
+        to (svg_string, actual_height) for Vega charts rendered during sizing)
+    """
+    board = face.resolved_style.board
+
+    container_width = float(board.width)
+    content_width = max(container_width - 2 * float(board.margin), 0.0)
+    min_height = float(board.min_height)
+    card_padding = float(board.card_padding)
+
+    card_gap = float(board.card_gap) if face.card_gap else 0.0
+    gap = get_face_gap(face)
+
+    variable_defaults = face.variable_defaults
+
+    # Create render context; executor=None disables render-first Vega sizing.
+    from dataface.core.compile.vega_config import compile_effective_vega_config
+
+    render_ctx = SizingRenderCtx(
+        resolved_style=face.resolved_style,
+        vega_config=compile_effective_vega_config(face.theme),
+        executor=executor if render_first else None,
+        variables=variables,
+        face_level=face.level,
+    )
+
+    # Build a data-aware height provider
+    height_provider = _make_data_aware_height_provider(
+        render_ctx,
+        executor,
+        variables,
+        card_padding=card_padding,
+    )
+
+    # Calculate layout height using compile sizing algorithms + data-aware provider
+    container_height = calculate_layout_height(
+        face.layout,
+        card_gap,
+        gap,
+        min_height,
+        available_width=content_width,
+        variable_defaults=variable_defaults,
+        height_provider=height_provider,
+        resolved_style=face.resolved_style,
+    )
+
+    if face.title:
+        title_measure_width = max(content_width - 2 * card_padding, 0.0)
+        title_height = get_title_height(
+            face.title, title_measure_width, variable_defaults
+        )
+        container_height += title_height + gap + card_gap
+
+    face.layout.width = container_width
+    face.layout.height = container_height
+    face.layout.content_width = content_width
+    face.layout.content_height = container_height
+
+    # Assign dimensions using compile sizing + data-aware provider
+    calculate_layout_items(
+        face.layout,
+        content_width,
+        container_height,
+        card_gap,
+        gap,
+        variable_defaults,
+        height_provider,
+        resolved_style=face.resolved_style,
+    )
+
+    # Slot-height fix: re-render charts whose cached SVG was sized by the
+    # aspect-ratio estimate but whose assigned slot height differs.  This handles
+    # layout wrappers with an explicit height (rows: [- height: 600, rows: [chart]])
+    # where the sizing provider ran before item.height was set.
+    if render_ctx.render_cache:
+        _fix_slot_heights_in_tree(face.layout, render_ctx)
+
+    # Cols alignment: walk tree, re-render shorter Vega items at aligned height
+    if render_ctx.render_cache:
+        _align_all_cols_in_tree(face.layout, render_ctx)
+
+    return face, render_ctx.render_cache