dataface 0.3.2.dev22__py3-none-any.whl → 0.3.2.dev111__py3-none-any.whl

dataface/core/connections.py

@@ -14,9 +14,12 @@ looking for, so routing through an adapter would mean inventing a sentinel
 dataset just to construct one. The BigQuery client needs no dataset at all.
 """
 
-from typing import Any
+from __future__ import annotations
 
-from dataface.core.compile.models.source import BigQuerySourceConfig, SourceConfig
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from dataface.core.compile.models.source import BigQuerySourceConfig, SourceConfig
 
 
 def _import_bigquery(module_name: str) -> Any:
@@ -78,6 +81,8 @@ def list_datasets(source_config: SourceConfig) -> list[str]:
     this is what the connection form calls before the user can know which
     datasets exist.
     """
+    from dataface.core.compile.models.source import BigQuerySourceConfig
+
     if not isinstance(source_config, BigQuerySourceConfig):
         raise ValueError(
             f"list_datasets is BigQuery-only, got {source_config.type!r}. "
@@ -97,6 +102,8 @@ def dataset_location(source_config: SourceConfig) -> str:
     resources without a location, so filling it for every listed dataset would
     be an N+1 across potentially hundreds of them.
     """
+    from dataface.core.compile.models.source import BigQuerySourceConfig
+
     if not isinstance(source_config, BigQuerySourceConfig):
         raise ValueError(
             f"dataset_location is BigQuery-only, got {source_config.type!r}."
@@ -133,7 +140,7 @@ def test_connection(source_config: SourceConfig) -> tuple[bool, str]:
     try:
         adapter = build_adapter(creds)
         with adapter.connection_named("test"):
-            adapter.execute("SELECT 1", auto_begin=True, fetch=True)
+            adapter.execute("SELECT 1", auto_begin=False, fetch=True)
         return True, "Connection successful"
     except (
         Exception  # noqa: BLE001

dataface/core/dashboard.py

@@ -21,6 +21,7 @@ from __future__ import annotations
 import importlib.util as _importlib_util
 import logging
 import time
+from datetime import datetime
 from pathlib import PurePosixPath
 from typing import Any, Literal, get_args
 
@@ -81,10 +82,7 @@ from dataface.core.render import RenderError, render
 from dataface.core.render.board_links import LinkContext
 from dataface.core.render.dir_context import lazy_dir_context
 from dataface.core.render.face_to_dict import NO_ROW_CAP
-
-RenderFormat = Literal[
-    "svg", "html", "png", "pdf", "terminal", "json", "text", "yaml", "data"
-]
+from dataface.core.render_format import RenderFormat
 
 # "failed" — no output produced (face_error, or validation_errors from a failed
 #   compile).
@@ -120,9 +118,9 @@ class RenderedDashboard(BaseModel):
     # concept of. Cloud resolves agent-facing dashboard URLs through its own
     # router instead (`search_dashboards`).
     url: str | None = None
-    # Resolved per-query cache policies — populated only on success, consumed by
-    # Cloud's snapshot writer to compute expires_at without recompiling the board.
-    board_cache_policies: dict[str, CachePolicy] = {}
+    # Per-query (name, data_as_of, policy) records populated on success. Consumed
+    # by Cloud's snapshot writer to compute expires_at anchored on actual data age.
+    board_query_data_ages: list[tuple[str, datetime, CachePolicy]] = []
 
 
 def raise_on_dashboard_failure(result: RenderedDashboard) -> None:
@@ -394,19 +392,29 @@ def render_dashboard(
         # the compile-time source map here: render never re-parses the
         # authored text, it reuses the map compile already built.
         stamp_diagnostics(
-            render_result.chart_errors, result.source_map, result.sql_blocks
+            render_result.chart_errors,
+            result.source_map,
+            result.sql_blocks,
+            result.container_paths,
+        )
+        stamp_diagnostics(
+            render_result.warnings,
+            result.source_map,
+            result.sql_blocks,
+            result.container_paths,
         )
-        stamp_diagnostics(render_result.warnings, result.source_map, result.sql_blocks)
         stamp_diagnostics(
             render_result.suppressed_warnings,
             result.source_map,
             result.sql_blocks,
+            result.container_paths,
         )
         if render_result.face_error is not None:
             stamp_diagnostics(
                 [render_result.face_error],
                 result.source_map,
                 result.sql_blocks,
+                result.container_paths,
             )
         _logger.debug(
             "render_dashboard %s compile=%.0fms execute+render=%.0fms total=%.0fms cache=%s",
@@ -472,7 +480,12 @@ def render_dashboard(
         fatal_diagnostic = e.to_diagnostic(
             file=file_path.relpath if file_path is not None else None
         )
-        stamp_diagnostics([fatal_diagnostic], result.source_map, result.sql_blocks)
+        stamp_diagnostics(
+            [fatal_diagnostic],
+            result.source_map,
+            result.sql_blocks,
+            result.container_paths,
+        )
         return RenderedDashboard(
             status="failed",
             face_error=fatal_diagnostic,
@@ -495,12 +508,5 @@ def render_dashboard(
             *render_result.suppressed_warnings,
         ],
         url=url,
-        # The registry, not `face.queries`: inline chart/layer queries and
-        # `#`-anchored refs are normalized straight into the registry and never
-        # get a `queries:` entry, so keying off the named section hands Cloud a
-        # short map — or an empty one for a board authored entirely inline,
-        # which its `min(..., default=inf)` reads as "nothing expires".
-        board_cache_policies={
-            name: q.cache for name, q in result.query_registry.items()
-        },
+        board_query_data_ages=executor.query_data_ages,
     )

dataface/core/defaults/themes/_base.yaml

@@ -145,27 +145,25 @@ style:
       radius: 0.0
 
     axis:
-      domain:
+      line:
         visible: false
         width: 1
       ticks:
         visible: false
-        size: 6  # default tick size cascades to all axes; matches VL's geometric idiom
+        length: 6  # default tick length cascades to all axes; matches VL's geometric idiom
       grid:
         visible: true
         opacity: 1
         width: 1.5
-        zero:
-          width: 2
-      label:
+      labels:
         font:
           size:     &size_label 11
         padding: 6
         overlap:                         # default: all strategies enabled; the ONE home for this setting
           tilt: true
           skip: true
-        separation: 16       # 16px minimum gap between adjacent labels
-        # bound, flush, offset, line_height, anchor intentionally absent — VL per-axis defaults apply.
+        min_gap: 16       # 16px minimum gap between adjacent labels
+        # bound, flush, offset intentionally absent — VL per-axis defaults apply.
       title:
         visible: false
         font:
@@ -173,13 +171,6 @@ style:
           weight: &weight_bold 600
           case: title
         padding: 10
-      # fill is semantically only active on axis_x (ordinal bucketed-time);
-      # required on all AxisStyle instances since the model enforces it.
-      fill: "null"
-      # fiscal_year_start_month: same story as fill — only meaningful on
-      # axis_x (year/yearquarter bucketing), required everywhere the model
-      # enforces it. 1 = January = calendar-quarter convention.
-      fiscal_year_start_month: 1
 
     axis_x:
       # Only intentional differences from `axis` — everything else cascades.
@@ -188,7 +179,8 @@ style:
       ticks:
         visible: true
         width: 1
-      label:
+        offset: 1
+      labels:
         # Tilt angle candidates for the "tilt" step in the label overlap
         # strategy walk. Picker chooses the first angle where labels fit.
         # When no angle fits, the strategy walk continues to the next step
@@ -196,7 +188,6 @@ style:
         tilt_increments: [0, -30, -45, -60, -90]
       scale:
         padding: 0  # band/point padding around categorical x-axis values
-      offset: 1
       # Engine fills missing time buckets on ordinal bucketed-time x-axes.
       # Bar/line/area inherit this global default. Scatter pins null under
       # style.charts.scatter.axis_x (layer 3.5) — scatter should never zero-fill or interpolate.
@@ -205,23 +196,28 @@ style:
 
     axis_y:
       # Y-specific tweaks only — orientation and tick width. Empty
-      # grid/domain/label/title cascade from the canonical `axis`
+      # grid/line/labels/title cascade from the canonical `axis`
       # block via the InheritSlot graph at resolve time, so face-level patches on
       # `style.axis.*` reach axis_y through the same path.
       # "auto" → "right" by default; flips to "left" when endpoint labels are
       # on the right edge (line charts with style.line.endpoint_labels.visible).
+      # Also serves the categorical-orient role for horizontal bar's swapped
+      # categorical axis (categorical_orient was deleted 2026-08 trim).
       position: auto
-      categorical_orient: left
       ticks:
         width: 1.5
-      fill: "null"
-      fiscal_year_start_month: 1
+      grid:
+        # zero-baseline gridline — measure axis only. Moved from axis.grid.zero
+        # (BaseAxisGridStyle has no zero; only MeasureGridStyle does).
+        zero:
+          width: 2
       scale:
-        # Measure-axis domain stays pinned to the chart query's full unfiltered
-        # extent across filter-variable changes (editorial default — a filter
-        # changes data, not axes). "auto" opts a chart back into rescaling the
-        # domain to the current filtered subset on every variable change.
-        domain_strategy: stable
+        continuous:
+          # Measure-axis domain stays pinned to the chart query's full unfiltered
+          # extent across filter-variable changes (editorial default — a filter
+          # changes data, not axes). "auto" opts a chart back into rescaling the
+          # domain to the current filtered subset on every variable change.
+          domain_strategy: stable
         # Editorial default (settled 2026-07-16): data marks sit ~8% from
         # the visible axis edges. Zero-anchored: domain_max = data_max * 1.08.
         # Zoomed axes: both edges expand by 8% of the visible span, symmetric.
@@ -234,16 +230,14 @@ style:
       # tick width matching axis_y. Colors cascade from `axis` via the inherit graph.
       ticks:
         width: 1.5
-      label:
+      labels:
         font: {}
-      fill: "null"
-      fiscal_year_start_month: 1
-      # References the shared number_default alias (.3~s) so quantitative axes
-      # AND the value labels that inherit this format read a bounded 3-sig-fig
-      # SI number (9.18, 21.5M) — not the unbounded 6-sig-fig 9.18039 a bare ~s
-      # gives on real data. Axis ticks are round, so the bound is invisible there.
-      # Authors override per-chart via chart.format or style.axis_y.format.
-      format: "number_default"
+        # References the shared number_default alias (.3~s) so quantitative axes
+        # AND the value labels that inherit this format read a bounded 3-sig-fig
+        # SI number (9.18, 21.5M) — not the unbounded 6-sig-fig 9.18039 a bare ~s
+        # gives on real data. Axis ticks are round, so the bound is invisible there.
+        # Authors override per-chart via chart.format or style.axis_y.labels.format.
+        format: "number_default"
 
     tooltip:
       format: ",.2~f"
@@ -563,7 +557,8 @@ style:
       # "auto" runs the Dataface smart-zero heuristic at render time.
       # Set to true/false to pin the zero-baseline for all bar charts.
       scale:
-        zero: auto
+        continuous:
+          zero: auto
       endpoint_labels:
         visible: false
         label_offset: 6.0
@@ -573,12 +568,13 @@ style:
           visible: false
         ticks:
           visible: false
-        label:
+        labels:
           padding: 6.0
 
     line:
       scale:
-        zero: auto
+        continuous:
+          zero: auto
       endpoint_labels:
         visible: false
         label_offset: 6.0
@@ -588,7 +584,8 @@ style:
       # Authors who want a stacked area chart opt in via ``chart.style.stack: "zero"``.
       stack: none
       scale:
-        zero: auto
+        continuous:
+          zero: auto
       endpoint_labels:
         visible: false
         label_offset: 6.0
@@ -739,7 +736,8 @@ style:
     # _ChartStyleBase, so mypy can't verify zero-arg construction. These stay required.
     scatter:
       scale:
-        zero: auto
+        continuous:
+          zero: auto
       # Scatter always breaks at missing buckets (honest dots). Pinned here so a
       # future change to style.charts.axis_x.fill does not connect gaps on point marks.
       # Bar is intentionally NOT pinned: an author who opts into fill: linear on a bar
@@ -811,6 +809,18 @@ style:
       axis_y:
         grid:
           visible: false
+      # Heatmap's color channel carries the whole measure — a reader can't
+      # decode dark-vs-light without a key. Keep this a family default so
+      # themes that globally suppress legends (editorial direct-labeling)
+      # still inherit an honest gradient legend here, just as scatter opts
+      # back in.
+      legend:
+        visible: true
+        # The click-to-mute toggle mutes every mark whose color differs from
+        # the clicked one; a heatmap's color is its measure, near-unique per
+        # cell, so one click drops the whole chart to muted opacity — and a
+        # gradient key has no symbols to click.
+        interactive_legend: false
 
     # Series-label primitive. Typography for Cartesian text marks that name a
     # data series — endpoint labels and direct stack labels. Placement is

dataface/core/defaults/themes/cream.yaml

@@ -62,15 +62,13 @@ style:
         font:
           color: dft-creams.heading
     axis:
-      domain:
+      line:
         color: dft-creams.grid
       grid:
         color: dft-creams.grid
-        zero:
-          color: dft-creams.subtitle
       ticks:
         color: dft-creams.grid
-      label:
+      labels:
         font:
           color: dft-creams.muted
       title:
@@ -82,6 +80,8 @@ style:
     axis_y:
       grid:
         color: dft-creams.grid-emphasis  # softer grid for the value axis (overrides default gray)
+        zero:
+          color: dft-creams.subtitle
       ticks:
         color: dft-creams.grid-emphasis
     axis_quantitative:

dataface/core/defaults/themes/diagnostics-title-baseline.yaml

@@ -4,7 +4,7 @@ extends: stark
 style:
   charts:
     axis:
-      label:
+      labels:
         font:
           color: dft-grays.muted
       title:

dataface/core/defaults/themes/diagnostics-title-color-extreme.yaml

@@ -4,7 +4,7 @@ extends: stark
 style:
   charts:
     axis:
-      label:
+      labels:
         font:
           color: dft-grays.muted
       title:

dataface/core/defaults/themes/diagnostics-title-font-extreme.yaml

@@ -4,7 +4,7 @@ extends: stark
 style:
   charts:
     axis:
-      label:
+      labels:
         font:
           color: dft-grays.muted
       title:

dataface/core/defaults/themes/diagnostics-title-size-extreme.yaml

@@ -4,7 +4,7 @@ extends: stark
 style:
   charts:
     axis:
-      label:
+      labels:
         font:
           color: dft-grays.muted
       title:

dataface/core/defaults/themes/diagnostics-title-weight-extreme.yaml

@@ -4,7 +4,7 @@ extends: stark
 style:
   charts:
     axis:
-      label:
+      labels:
         font:
           color: dft-grays.muted
       title:

dataface/core/defaults/themes/editorial.yaml

@@ -69,7 +69,7 @@ style:
         # dataface/src/dataface/core/defaults/palettes/categorical/editorial-10.yml.
         palette: editorial-10
     axis:
-      label:
+      labels:
         font:
           color: dft-grays.muted
       title:
@@ -80,15 +80,15 @@ style:
           color: dft-grays.subtitle
       grid:
         color: dft-grays.grid
-        zero:
-          color: dft-grays.subtitle
       ticks:
         color: dft-grays.grid
-      domain:
+      line:
         color: dft-grays.grid
     axis_y:
       grid:
         color: dft-grays.grid-emphasis
+        zero:
+          color: dft-grays.subtitle
       ticks:
         color: dft-grays.grid-emphasis
     axis_quantitative:
@@ -152,12 +152,12 @@ style:
       # left/right for a horizontal bar — vertical bars' bottom labels have
       # no edge to resolve against and stay untouched.
       axis_x:
-        label:
+        labels:
           align: inward
     heatmap:
       # Inward-align the row labels (heatmap's y is always the nominal row axis).
       axis_y:
-        label:
+        labels:
           align: inward
     line:
       endpoint_labels:

dataface/core/defaults/themes/neon.yaml

@@ -64,16 +64,14 @@ style:
       bar:
         background: *faint
     axis:
-      domain:
+      line:
         color: *faint
       grid:
         color: *faint
         width: 1
-        zero:
-          color: &value dft-grays.canvas  # baseline anchors at max contrast
       ticks:
         color: *faint
-      label:
+      labels:
         font:
           color: *mid
       title:
@@ -82,8 +80,12 @@ style:
     axis_x:
       grid:
         visible: false
+    axis_y:
+      grid:
+        zero:
+          color: &value dft-grays.canvas  # baseline anchors at max contrast
     axis_quantitative:
-      label:
+      labels:
         font:
           color: *value            # numeric readouts POP
       ticks:
@@ -104,9 +106,14 @@ style:
         visible: true
     bar:
       legend:
-        visible: true              # bars can't endpoint-label → keep legend
+        # A bar that direct-labels has this suppressed again by resolve. It is
+        # load-bearing for the bars that cannot — grouped, or stacked but
+        # disqualified by `multiples:`, a negative measure, or a series absent
+        # from the last column — which would otherwise carry no series key at
+        # all, since the theme hides legends globally.
+        visible: true
       axis_x:                      # inward-align horizontal-bar row labels (resolve scopes to left/right edge)
-        label:
+        labels:
           align: inward
     scatter:
       legend:
@@ -141,7 +148,7 @@ style:
         gradient:
           palette: viridis
       axis_y:                      # inward-align heatmap row labels (y is always nominal)
-        label:
+        labels:
           align: inward
     table:
       border:

dataface/core/defaults/themes/plain.yaml

@@ -35,20 +35,22 @@ style:
         single_series_palette: ['editorial-10.1']   # editorial denim single series
     # Generic BI chrome: medium-gray, visible — nothing recedes dramatically.
     axis:
-      domain:
+      line:
         color: dft-grays.grid-emphasis
       grid:
         color: dft-grays.grid-emphasis   # visible, medium (the BI-default look)
-        zero:
-          color: dft-grays.subtitle
       ticks:
         color: dft-grays.grid-emphasis
-      label:
+      labels:
         font:
           color: dft-grays.muted
       title:
         font:
           color: dft-grays.subtitle
+    axis_y:
+      grid:
+        zero:
+          color: dft-grays.subtitle
     # Soft light tooltip, mirroring editorial's look -- stark (the structural
     # root plain extends directly) now sets a sharp/thick/no-shadow/triangle
     # tooltip for its own utilitarian voice; plain wants the same soft BI-report

dataface/core/defaults/themes/stark.yaml

@@ -45,20 +45,22 @@ style:
         # inherit. dark/editorial/cream override.
         single_series_palette: [dft-grays.black]
     axis:
-      domain:
+      line:
         color: *color_ink
       ticks:
         color: *color_ink
       grid:
         color: *color_ink
-        zero:
-          color: *color_ink
-      label:
+      labels:
         font:
           color: *color_ink
       title:
         font:
           color: *color_ink
+    axis_y:
+      grid:
+        zero:
+          color: *color_ink
 
     legend:
       label:
@@ -155,12 +157,12 @@ style:
           color: *color_ink
 
     axis_quantitative:
-      label:
+      labels:
         font:
           family: '''DFT Sans Tabular'', Inter, system-ui, sans-serif'
 
-    # Direct-label multi-series lines/areas at their endpoints rather than
-    # leaning on a side legend. Set on the structural root so the plain
+    # Direct-label multi-series lines/areas/bars at their endpoints rather
+    # than leaning on a side legend. Set on the structural root so the plain
     # theme inherits it; the crafted themes (editorial/vivid/neon) already
     # set their own true.
     line:
@@ -169,6 +171,13 @@ style:
     area:
       endpoint_labels:
         visible: true
+    # A vertical bar's labels anchor to the last column's per-series stack
+    # midpoints; a horizontal bar's take the top-row rail instead. Resolve
+    # turns this back off wherever the rail cannot name every series — see
+    # _bar_endpoint_labels_for_stack.
+    bar:
+      endpoint_labels:
+        visible: true
 
     pie:
       total:

dataface/core/defaults/themes/vivid.yaml

@@ -35,16 +35,14 @@ style:
       categorical:
         single_series_palette: ['vivid-10.1']   # brand-blue single series
     axis:
-      domain:
+      line:
         color: *faint
       grid:
         color: *faint
         width: 1
-        zero:
-          color: &value dft-grays.ink  # baseline anchors at max contrast
       ticks:
         color: *faint
-      label:
+      labels:
         font:
           color: *mid              # category/time labels = MID
       title:
@@ -53,9 +51,13 @@ style:
     axis_x:
       grid:
         visible: false
+    axis_y:
+      grid:
+        zero:
+          color: &value dft-grays.ink  # baseline anchors at max contrast
     # Numeric axis readouts POP at the max VALUE tier (TradingView scale-text).
     axis_quantitative:
-      label:
+      labels:
         font:
           color: *value
       ticks:
@@ -76,13 +78,18 @@ style:
         visible: true
     bar:
       legend:
-        visible: true              # bars can't endpoint-label → keep legend
+        # A bar that direct-labels has this suppressed again by resolve. It is
+        # load-bearing for the bars that cannot — grouped, or stacked but
+        # disqualified by `multiples:`, a negative measure, or a series absent
+        # from the last column — which would otherwise carry no series key at
+        # all, since the theme hides legends globally.
+        visible: true
       axis_x:                      # inward-align horizontal-bar row labels (resolve scopes to left/right edge)
-        label:
+        labels:
           align: inward
     heatmap:                       # inward-align heatmap row labels (y is always nominal)
       axis_y:
-        label:
+        labels:
           align: inward
     scatter:
       legend:

dataface/core/diagnostics/__init__.py

@@ -20,7 +20,6 @@ from dataface.core.diagnostics.codes_compile import (
     ERR_EXTRA_FIELD,
     ERR_FILE_NOT_FOUND,
     ERR_JINJA_ERROR,
-    ERR_LABEL_VALUES_MEASURE_AXIS,
     ERR_LAYERS_AMBIGUOUS_Y_DOMAIN,
     ERR_LINE_Y_NOT_NUMERIC,
     ERR_LOG_SCALE_REQUIRES_POSITIVE_DATA,
@@ -114,6 +113,7 @@ from dataface.core.diagnostics.codes_unknown import ERR_INTERNAL
 from dataface.core.diagnostics.diagnostic import (
     ColumnSpan,
     Diagnostic,
+    RelatedLocation,
     SourceRange,
     build_diagnostic,
     display_message,
@@ -137,6 +137,7 @@ __all__ = [
     "Diagnostic",
     "SourceRange",
     "ColumnSpan",
+    "RelatedLocation",
     "build_diagnostic",
     "display_message",
     "build_doc_url",
@@ -166,7 +167,6 @@ __all__ = [
     "ERR_LOG_SCALE_REQUIRES_POSITIVE_DATA",
     "ERR_AREA_STACKED_LOG_SCALE_NOT_SUPPORTED",
     "ERR_FILE_NOT_FOUND",
-    "ERR_LABEL_VALUES_MEASURE_AXIS",
     "ERR_TICKS_INTERVAL_MEASURE_AXIS",
     # Compile warnings
     "WARN_UNREFERENCED_CHART",