dataface 0.1.2__py3-none-any.whl

dataface/core/render/chart/time_unit_detect.py

@@ -0,0 +1,809 @@
+"""Predicate-based time-unit detection and smart-default labelExpr for temporal axes.
+
+detect_time_unit: pure function; given distinct non-null x-field values,
+returns the VL timeUnit string or None (continuous/sub-daily).
+
+default_label_expr_for: returns a Vega expression for an
+encoding time unit + label time unit pair.
+
+Bucket string vocabulary (pattern → VL timeUnit):
+  YYYY-MM         → yearmonth   (2024-01)
+  Mon YYYY        → yearmonth   (Jan 2024)
+  MM/YYYY         → yearmonth   (01/2024, US-only)
+  YYYY-Qn         → yearquarter (2024-Q1, canonical ISO quarter)
+  Qn YYYY         → yearquarter (Q1 2024)
+  YYYYQn          → yearquarter (2024Q1)
+  FYnnnn          → year        (FY2024 → Jan 1)
+  MM/DD/YYYY      → yearmonthdate (01/15/2024, US-only)
+  Mon DD[,] YYYY  → yearmonthdate (Jan 15, 2024)
+  YYYY-Www        → yearweek    (2024-W01, canonical ISO week)
+  W[eek ]N YYYY   → yearweek    (W32 2024, Week 32 2024)
+  Half-year (H1 YYYY, YYYY-H1): not supported; treated as unparseable.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import itertools
+import re
+from typing import Any
+
+# ISO date: "2024-01-15"
+_ISO_DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+# ISO datetime with T separator ("2024-01-15T14:30:00") or space from DB driver str()
+_ISO_DATETIME_RE = re.compile(r"^\d{4}-\d{2}-\d{2}[T ]")
+# ISO week-year: "2024-W32" (weeks 01–53)
+_ISO_WEEK_RE = re.compile(r"^\d{4}-W(0[1-9]|[1-4]\d|5[0-3])$")
+# Calendar quarter: "2024-Q3"
+_ISO_QUARTER_RE = re.compile(r"^\d{4}-Q[1-4]$")
+
+# ── Bucket-string patterns ──────────────────────────────────────────────────
+# YYYY-MM: 2024-01 (valid month 01-12)
+_YEARMONTH_STR_RE = re.compile(r"^\d{4}-(0[1-9]|1[0-2])$")
+# Mon YYYY: Jan 2024
+_MON_YYYY_RE = re.compile(
+    r"^(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\s+(\d{4})$", re.IGNORECASE
+)
+# MM/YYYY: 01/2024 (US month/year)
+_MM_YYYY_RE = re.compile(r"^(0[1-9]|1[0-2])/(\d{4})$")
+# Qn YYYY: Q1 2024 (space optional)
+_Q_YYYY_RE = re.compile(r"^Q([1-4])\s*(\d{4})$", re.IGNORECASE)
+# YYYYQn: 2024Q1
+_YYYY_Q_RE = re.compile(r"^(\d{4})Q([1-4])$", re.IGNORECASE)
+# FYnnnn: FY2024
+_FY_RE = re.compile(r"^FY(\d{4})$", re.IGNORECASE)
+# MM/DD/YYYY: 01/15/2024 (US month/day/year)
+_MM_DD_YYYY_RE = re.compile(r"^(0[1-9]|1[0-2])/(0[1-9]|[12]\d|3[01])/(\d{4})$")
+# Mon DD[,] YYYY: Jan 15, 2024 or Jan 15 2024
+_MON_DD_YYYY_RE = re.compile(
+    r"^(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\s+(\d{1,2}),?\s+(\d{4})$",
+    re.IGNORECASE,
+)
+# W[eek ]N YYYY: W32 2024, Week 32 2024
+_WEEK_SPELLED_RE = re.compile(r"^W(?:eek\s*)?(\d{1,2})\s+(\d{4})$", re.IGNORECASE)
+
+_MONTH_ABBR: dict[str, int] = {
+    "jan": 1,
+    "feb": 2,
+    "mar": 3,
+    "apr": 4,
+    "may": 5,
+    "jun": 6,
+    "jul": 7,
+    "aug": 8,
+    "sep": 9,
+    "oct": 10,
+    "nov": 11,
+    "dec": 12,
+}
+_QUARTER_FIRST_MONTH_LOOKUP: dict[int, int] = {1: 1, 2: 4, 3: 7, 4: 10}
+
+# Ordered family list: (name, regex).  First match wins in _classify_bucket.
+_BUCKET_FAMILIES: list[tuple[str, re.Pattern[str]]] = [
+    ("iso_week", _ISO_WEEK_RE),
+    ("iso_quarter", _ISO_QUARTER_RE),
+    ("yearmonth_str", _YEARMONTH_STR_RE),
+    ("mon_yyyy", _MON_YYYY_RE),
+    ("mm_yyyy", _MM_YYYY_RE),
+    ("q_yyyy", _Q_YYYY_RE),
+    ("yyyy_q", _YYYY_Q_RE),
+    ("fy", _FY_RE),
+    ("mm_dd_yyyy", _MM_DD_YYYY_RE),
+    ("mon_dd_yyyy", _MON_DD_YYYY_RE),
+    ("week_spelled", _WEEK_SPELLED_RE),
+]
+
+
+def _classify_bucket(v: str) -> str | None:
+    """Return the format-family name for a bucket string, or None."""
+    for name, pattern in _BUCKET_FAMILIES:
+        if pattern.match(v):
+            return name
+    return None
+
+
+def _parse_bucket_string(value: str) -> dt.date | None:
+    """Return the anchor date (first instant of bucket) for a labeled format.
+
+    Returns None for unrecognized strings. Does NOT raise — invalid ISO weeks
+    that pass the regex (e.g. W53 in a 52-week year) return None here; the
+    error is raised only by the explicit ``_week_to_iso`` converter used in
+    ``normalize_labeled_temporal``.
+    """
+    if _YEARMONTH_STR_RE.match(value):
+        return dt.date(int(value[:4]), int(value[5:7]), 1)
+    m = _MON_YYYY_RE.match(value)
+    if m:
+        month = _MONTH_ABBR[m.group(1).lower()]
+        return dt.date(int(m.group(2)), month, 1)
+    m = _MM_YYYY_RE.match(value)
+    if m:
+        return dt.date(int(m.group(2)), int(m.group(1)), 1)
+    m = _Q_YYYY_RE.match(value)
+    if m:
+        return dt.date(int(m.group(2)), _QUARTER_FIRST_MONTH_LOOKUP[int(m.group(1))], 1)
+    m = _YYYY_Q_RE.match(value)
+    if m:
+        return dt.date(int(m.group(1)), _QUARTER_FIRST_MONTH_LOOKUP[int(m.group(2))], 1)
+    m = _FY_RE.match(value)
+    if m:
+        return dt.date(int(m.group(1)), 1, 1)
+    m = _MM_DD_YYYY_RE.match(value)
+    if m:
+        try:
+            return dt.date(int(m.group(3)), int(m.group(1)), int(m.group(2)))
+        except ValueError:
+            return None
+    m = _MON_DD_YYYY_RE.match(value)
+    if m:
+        month = _MONTH_ABBR[m.group(1).lower()]
+        try:
+            return dt.date(int(m.group(3)), month, int(m.group(2)))
+        except ValueError:
+            return None
+    m = _WEEK_SPELLED_RE.match(value)
+    if m:
+        week, year = int(m.group(1)), int(m.group(2))
+        try:
+            return dt.date.fromisocalendar(year, week, 1)
+        except ValueError:
+            return None
+    # ISO week/quarter: delegate to existing helpers (avoid duplication);
+    # return None on invalid week numbers (the convert path raises separately).
+    if _ISO_WEEK_RE.match(value):
+        year, week = int(value[:4]), int(value[6:])
+        try:
+            return dt.date.fromisocalendar(year, week, 1)
+        except ValueError:
+            return None
+    if _ISO_QUARTER_RE.match(value):
+        q = int(value[6])
+        return dt.date(int(value[:4]), _QUARTER_FIRST_MONTH_LOOKUP[q], 1)
+    return None
+
+
+_TIME_UNIT_TO_VL: dict[str, str] = {
+    "monthofyear": "month",
+    "dayofweek": "day",
+    "dayofmonth": "date",
+    "dayofyear": "dayofyear",
+    "hourofday": "hours",
+}
+
+# Calendar-bucketed units → default ordinal scale.
+# Distinct from time-part units (monthofyear etc.) which stay temporal.
+BUCKETED_CALENDAR_UNITS: frozenset[str] = frozenset(
+    {"year", "yearquarter", "yearmonth", "yearweek", "yearmonthdate"}
+)
+
+
+def _parse_date(value: Any) -> dt.date | dt.datetime | None:
+    """Parse value to date/datetime. Returns None if unparseable."""
+    if isinstance(value, dt.datetime):
+        return value
+    if isinstance(value, dt.date):
+        return value
+    if isinstance(value, str):
+        if _ISO_DATETIME_RE.match(value):
+            try:
+                # Python <3.11: fromisoformat doesn't accept the trailing 'Z' UTC suffix.
+                v = value[:-1] + "+00:00" if value.endswith("Z") else value
+                return dt.datetime.fromisoformat(v)
+            except ValueError:
+                return None
+        if _ISO_DATE_RE.match(value):
+            try:
+                return dt.date.fromisoformat(value)
+            except ValueError:
+                return None
+        return _parse_bucket_string(value)
+    return None
+
+
+def detect_time_unit(values: list[Any]) -> str | None:
+    """Detect VL timeUnit from distinct non-null x-field values.
+
+    Returns one of: "year", "yearquarter", "yearmonth", "yearweek",
+    "yearmonthdate", or None (sub-daily continuous or insufficient data).
+
+    Raises ValueError when ≥10% of distinct values are unparseable strings.
+    """
+    distinct = list({v for v in values if v is not None})
+    if len(distinct) < 2:
+        return None
+
+    parsed: list[dt.date | dt.datetime] = []
+    bad: list[Any] = []
+    for v in distinct:
+        p = _parse_date(v)
+        if p is None:
+            bad.append(v)
+        else:
+            parsed.append(p)
+
+    if bad and len(bad) / len(distinct) >= 0.1:
+        examples = bad[:5]
+        raise ValueError(
+            f"Couldn't auto-detect timeUnit: ≥10% unparseable date values: {examples}. "
+            "Set style.axis_x.time_unit explicitly or fix the query."
+        )
+
+    if not parsed or len(parsed) < 2:
+        return None
+
+    # Sub-daily fallthrough: any nonzero hms → continuous
+    for p in parsed:
+        if isinstance(p, dt.datetime) and (p.hour or p.minute or p.second):
+            return None
+
+    # Normalize to date for predicate checks
+    dates = [p.date() if isinstance(p, dt.datetime) else p for p in parsed]
+
+    # Predicate check: coarsest to finest
+    if all(d.month == 1 and d.day == 1 for d in dates):
+        return "year"
+    if all(d.day == 1 and d.month in (1, 4, 7, 10) for d in dates):
+        return "yearquarter"
+    if all(d.day == 1 for d in dates):
+        return "yearmonth"
+    # Weekly cadence: every distinct value falls on the same weekday. Pinning
+    # to Monday-only (ISO week-start) missed the common case of Sunday-
+    # aligned weekly data (and Sat / mid-week pay-period reports), all of
+    # which want yearmonth-style x-axis labels rather than per-day "7 Jan,
+    # 14 Jan, ..." chatter. Same-weekday already implies every pairwise gap
+    # is a multiple of 7 (calendar arithmetic), so no separate gap check.
+    if len({d.weekday() for d in dates}) == 1:
+        return "yearweek"
+    return "yearmonthdate"
+
+
+_MIXED_LABEL_MSG = (
+    "Couldn't auto-detect timeUnit: column contains mixed label and "
+    "non-label values. "
+    "Set style.axis_x.time_unit explicitly."
+)
+
+
+def _week_to_iso(v: str) -> str:
+    year, week = int(v[:4]), int(v[6:])
+    try:
+        return dt.date.fromisocalendar(year, week, 1).isoformat()
+    except ValueError as exc:
+        raise ValueError(
+            f"Couldn't auto-detect timeUnit: '{v}' is not a valid ISO week "
+            f"(week {week} does not exist in year {year}). "
+            "Set style.axis_x.time_unit explicitly or fix the query."
+        ) from exc
+
+
+def _quarter_to_iso(v: str) -> str:
+    return dt.date(int(v[:4]), _QUARTER_FIRST_MONTH_LOOKUP[int(v[6])], 1).isoformat()
+
+
+def _bucket_to_iso(v: str) -> str:
+    """Convert any recognized bucket string to an ISO date string."""
+    if _ISO_WEEK_RE.match(v):
+        return _week_to_iso(v)
+    if _ISO_QUARTER_RE.match(v):
+        return _quarter_to_iso(v)
+    anchor = _parse_bucket_string(v)
+    if anchor is None:
+        raise ValueError(
+            f"Couldn't auto-detect timeUnit: unrecognized bucket format '{v}'. "
+            "Set style.axis_x.time_unit explicitly or fix the query."
+        )
+    return anchor.isoformat()
+
+
+def normalize_labeled_temporal(
+    data: list[dict[str, Any]], field: str
+) -> list[dict[str, Any]]:
+    """Convert labeled bucket strings in *field* to ISO dates.
+
+    Supported formats: YYYY-Www, YYYY-Qn, Qn YYYY, YYYYQn, YYYY-MM,
+    Mon YYYY, MM/YYYY, FYnnnn, MM/DD/YYYY, Mon DD YYYY, W[eek ]N YYYY.
+
+    When all non-null values share the same format family, returns a copy
+    with values replaced by the ISO date for the first instant of each
+    bucket. Returns *data* unchanged when the field uses plain ISO dates
+    or date/datetime objects (no labeling needed).
+
+    Raises ValueError when:
+    - labeled values are mixed with ISO date strings (or other non-labeled)
+    - values span more than one format family (e.g. YYYY-Www with YYYY-Qn)
+    - an ISO week label encodes an invalid week number
+    """
+    values = [row[field] for row in data if field in row and row[field] is not None]
+    if not values:
+        return data
+
+    def _is_iso(v: Any) -> bool:
+        return isinstance(v, str) and bool(
+            _ISO_DATE_RE.match(v) or _ISO_DATETIME_RE.match(v)
+        )
+
+    def _is_labeled(v: Any) -> bool:
+        return isinstance(v, str) and not _is_iso(v) and _classify_bucket(v) is not None
+
+    labeled = [v for v in values if _is_labeled(v)]
+    if not labeled:
+        return data
+
+    # Any ISO dates mixed in → mixed label error
+    if any(_is_iso(v) for v in values):
+        raise ValueError(_MIXED_LABEL_MSG)
+
+    # Any unrecognized strings mixed in → mixed label error
+    if len(labeled) < len(values):
+        raise ValueError(_MIXED_LABEL_MSG)
+
+    # All are labeled — check they're all the same format family
+    families = {_classify_bucket(v) for v in labeled}
+    if len(families) > 1:
+        raise ValueError(_MIXED_LABEL_MSG)
+
+    return [
+        (
+            {**row, field: _bucket_to_iso(row[field])}
+            if field in row and row[field] is not None
+            else row
+        )
+        for row in data
+    ]
+
+
+def ordinal_axis_values(
+    data: list[dict[str, Any]],
+    field: str,
+    time_unit: str,
+    label_time_unit: str | None,
+) -> list[Any] | None:
+    """Return sorted distinct x-values filtered to the label cadence.
+
+    For ordinal bucketed-time axes, returns the sorted distinct values from
+    data. When label_time_unit is coarser than encoding time_unit, filters
+    to values that open a new label period (e.g., first week of each month
+    for yearweek encoding with yearmonth labels).
+
+    Returns None when the field has no non-null values.
+    """
+    values = sorted(
+        {row[field] for row in data if field in row and row[field] is not None}
+    )
+    if not values:
+        return None
+
+    # axis.values rides directly into the VL spec; stringify date/datetime so
+    # vl_convert always receives JSON-safe values regardless of whether the
+    # caller (e.g. the per-layer-datasets path) normalized rows beforehand.
+    values = [
+        v.isoformat() if isinstance(v, (dt.date, dt.datetime)) else v for v in values
+    ]
+
+    if not label_time_unit or label_time_unit in ("auto", "none"):
+        return values
+
+    # Filter to label-period openers only.
+    # Values at this point are ISO date strings (from normalize_data_types
+    # or normalize_labeled_temporal) so we parse them to dates.
+    filtered: list[Any] = []
+    for v in values:
+        d = _parse_date(v)
+        if d is None:
+            # Non-parseable string → include (conservative)
+            filtered.append(v)
+            continue
+        date = d.date() if isinstance(d, dt.datetime) else d
+        if _is_label_opener(date, time_unit, label_time_unit):
+            filtered.append(v)
+    return filtered if filtered else values
+
+
+def _next_bucket(date: dt.date, time_unit: str) -> dt.date:
+    """Return the first date of the next bucket at the given grain."""
+    if time_unit == "yearmonthdate":
+        return date + dt.timedelta(days=1)
+    if time_unit == "yearweek":
+        return date + dt.timedelta(weeks=1)
+    if time_unit == "yearmonth":
+        # Advance to first of the next month
+        if date.month == 12:
+            return dt.date(date.year + 1, 1, 1)
+        return dt.date(date.year, date.month + 1, 1)
+    if time_unit == "yearquarter":
+        # Advance by 3 months
+        new_month = date.month + 3
+        if new_month > 12:
+            return dt.date(date.year + 1, new_month - 12, 1)
+        return dt.date(date.year, new_month, 1)
+    if time_unit == "year":
+        return dt.date(date.year + 1, 1, 1)
+    raise ValueError(f"Unsupported time_unit for bucket stepping: {time_unit!r}")
+
+
+def _enumerate_buckets(
+    min_date: dt.date, max_date: dt.date, time_unit: str
+) -> list[dt.date]:
+    """Return every bucket date from min_date to max_date inclusive."""
+    buckets: list[dt.date] = []
+    current = min_date
+    while current <= max_date:
+        buckets.append(current)
+        current = _next_bucket(current, time_unit)
+    return buckets
+
+
+_GAP_FILL_HANDLINGS = frozenset(
+    {
+        "linear",
+        "step-after",
+        "step-before",
+        "step-center",
+        "curve",
+    }
+)
+
+
+def _smoothstep(t: float) -> float:
+    """Hermite ease: 0 at t=0, 1 at t=1, flat derivatives at endpoints."""
+    return t * t * (3.0 - 2.0 * t)
+
+
+def _apply_gap_fill_handling(
+    rows: list[dict[str, Any]],
+    x_field: str,
+    dim_fields: list[str],
+    dim_combos: list[tuple[Any, ...]],
+    measure_cols: list[str],
+    mode: str,
+) -> None:
+    """Fill null measures on synthetic buckets; mutates ``rows`` in place."""
+    key_to_row: dict[tuple[Any, ...], dict[str, Any]] = {}
+    bucket_order: dict[str, int] = {}
+    for row in rows:
+        bkt = row[x_field]
+        if bkt not in bucket_order:
+            bucket_order[bkt] = len(bucket_order)
+        combo = tuple(row.get(d) for d in dim_fields)
+        key_to_row[(bkt, *combo)] = row
+
+    all_buckets_sorted = sorted(bucket_order, key=lambda b: bucket_order[b])
+
+    for combo in dim_combos:
+        group_rows: list[dict[str, Any]] = []
+        for bkt in all_buckets_sorted:
+            key = (bkt, *combo)
+            if key in key_to_row:
+                group_rows.append(key_to_row[key])
+
+        for col in measure_cols:
+            n = len(group_rows)
+            # Only observed (query) rows are anchors — not values filled in this pass.
+            # Any non-null value is a valid anchor; arithmetic below raises loudly if
+            # the value is non-numeric (e.g. a string) rather than silently skipping it.
+            anchors = [idx for idx in range(n) if group_rows[idx][col] is not None]
+            for i, row in enumerate(group_rows):
+                if row[col] is not None:
+                    continue
+                left_anchors = [a for a in anchors if a < i]
+                right_anchors = [a for a in anchors if a > i]
+                left_idx = left_anchors[-1] if left_anchors else -1
+                right_idx = right_anchors[0] if right_anchors else -1
+
+                if mode == "step-after":
+                    if left_idx >= 0:
+                        row[col] = group_rows[left_idx][col]
+                    continue
+
+                if mode == "step-before":
+                    if right_idx >= 0:
+                        row[col] = group_rows[right_idx][col]
+                    continue
+
+                if left_idx < 0 or right_idx < 0:
+                    continue
+
+                left_val = group_rows[left_idx][col]
+                right_val = group_rows[right_idx][col]
+                gap_width = right_idx - left_idx
+                gap_pos = i - left_idx
+                t = gap_pos / gap_width
+
+                if mode == "linear":
+                    row[col] = left_val + (right_val - left_val) * t
+                elif mode == "step-center":
+                    mid = left_idx + gap_width / 2
+                    row[col] = left_val if i < mid else right_val
+                elif mode == "curve":
+                    row[col] = left_val + (right_val - left_val) * _smoothstep(t)
+
+
+def complete_ordinal_time_series(
+    data: list[dict[str, Any]],
+    x_field: str,
+    time_unit: str,
+    dim_fields: list[str],
+    fill: str,
+) -> list[dict[str, Any]]:
+    """Synthesize missing time-bucket rows so every bucket in [min, max] is present.
+
+    For ordinal bucketed-time charts the engine must supply every bucket
+    between the dataset's min and max so the ordinal x-axis has a slot for
+    each period. Without this, missing buckets simply disappear from the axis.
+
+    Args:
+        data: rows from the query (non-empty; caller must guard empty datasets).
+        x_field: the x-encoding column name (must be ISO date strings or
+            datetime.date objects after normalize_labeled_temporal runs).
+        time_unit: one of BUCKETED_CALENDAR_UNITS (year, yearquarter, yearmonth,
+            yearweek, yearmonthdate).
+        dim_fields: categorical dimension columns to cross-join over (e.g. the
+            color/series field). Engine only cross-joins over values actually
+            present in the data window.
+        fill: "null" fills missing measure columns with None;
+            "zero" fills with 0; interpolate-* modes fill interior synthetic
+            buckets (see ``_GAP_FILL_HANDLINGS``).
+
+    Returns:
+        A new list of dicts, sorted (bucket asc, dim_1 asc, …), with the
+        original rows merged in. When no buckets are missing, returns data
+        sorted by the same key. If data is empty, returns data unchanged.
+    """
+    if not data:
+        return data
+
+    # Collect all x values; parse to date for comparison
+    raw_x_values = [
+        row[x_field] for row in data if x_field in row and row[x_field] is not None
+    ]
+    if not raw_x_values:
+        return data
+
+    # Convert to ISO strings for uniform comparison (ordinal path uses strings)
+    def _to_iso(v: Any) -> str:
+        if isinstance(v, dt.datetime):
+            return v.date().isoformat()
+        if isinstance(v, dt.date):
+            return v.isoformat()
+        return str(v)
+
+    x_iso = [_to_iso(v) for v in raw_x_values]
+
+    # Parse to dates for arithmetic
+    parsed_dates: list[dt.date] = []
+    for iso in x_iso:
+        d = _parse_date(iso)
+        if d is not None:
+            parsed_dates.append(d.date() if isinstance(d, dt.datetime) else d)
+
+    if not parsed_dates:
+        return data
+
+    min_date = min(parsed_dates)
+    max_date = max(parsed_dates)
+    all_buckets = _enumerate_buckets(min_date, max_date, time_unit)
+
+    # Determine distinct dimension values from actual data
+    dim_values: list[list[Any]] = []
+    for dim in dim_fields:
+        seen: list[Any] = []
+        seen_set: set[Any] = set()
+        for row in data:
+            v = row.get(dim)
+            if v not in seen_set:
+                seen_set.add(v)
+                seen.append(v)
+        dim_values.append(sorted(seen, key=lambda x: (x is None, x)))
+
+    # Identify measure columns: all non-x, non-dim columns
+    sample_keys = list(data[0].keys())
+    dim_set = set(dim_fields) | {x_field}
+    measure_cols = [k for k in sample_keys if k not in dim_set]
+
+    # For fill modes other than "zero", synthesized rows start as None; the
+    # second pass (_apply_gap_fill_handling) overwrites them for interior gaps.
+    fill_value = 0 if fill == "zero" else None
+
+    # Build lookup from (bucket_str, *dim_vals) → row
+    def _row_key(row: dict[str, Any]) -> tuple[Any, ...]:
+        return (_to_iso(row.get(x_field)),) + tuple(row.get(d) for d in dim_fields)
+
+    existing: dict[tuple[Any, ...], dict[str, Any]] = {
+        _row_key(row): row for row in data
+    }
+
+    # Generate full scaffold via cross-product of buckets × dim combinations
+    if dim_fields:
+        dim_combos: list[tuple[Any, ...]] = list(itertools.product(*dim_values))
+    else:
+        dim_combos = [()]
+
+    result: list[dict[str, Any]] = []
+    for bucket in all_buckets:
+        bucket_str = bucket.isoformat()
+        for combo in dim_combos:
+            key = (bucket_str,) + combo
+            if key in existing:
+                result.append(existing[key])
+            else:
+                # Synthesize a row: bucket value + dim values + filled measures
+                synth: dict[str, Any] = {x_field: bucket_str}
+                for dim, val in zip(dim_fields, combo, strict=True):
+                    synth[dim] = val
+                for col in measure_cols:
+                    synth[col] = fill_value
+                result.append(synth)
+
+    if fill in _GAP_FILL_HANDLINGS:
+        _apply_gap_fill_handling(
+            result, x_field, dim_fields, dim_combos, measure_cols, fill
+        )
+
+    return result
+
+
+def _is_label_opener(date: dt.date, encoding_unit: str, label_unit: str) -> bool:
+    """Return True when *date* opens a new label period."""
+    if label_unit == "year":
+        if encoding_unit in {"yearweek", "yearmonthdate"}:
+            return date.month == 1 and date.day <= 7
+        return date.month == 1 and date.day == 1
+    if label_unit == "yearquarter":
+        if encoding_unit == "yearweek":
+            return date.month % 3 == 1 and date.day <= 7
+        if encoding_unit == "yearmonthdate":
+            return date.month % 3 == 1 and date.day == 1
+        return date.month % 3 == 1 and date.day == 1  # yearmonth
+    if label_unit == "yearmonth":
+        if encoding_unit == "yearweek":
+            return date.day <= 7
+        if encoding_unit == "yearmonthdate":
+            return date.day == 1
+    return True  # same cadence or unknown — include all
+
+
+def vl_time_unit(time_unit: str) -> str:
+    """Return the Vega-Lite timeUnit for a Dataface time_unit value.
+
+    Chronological grains return their UTC variant (utcyearmonth etc.) so VL
+    bucketing stays UTC-aligned regardless of the renderer's TZ.  Time-part
+    units (monthofyear, dayofweek, hourofday, …) are cyclic and have no utc*
+    sibling — they pass through via _TIME_UNIT_TO_VL.
+    """
+    if time_unit in BUCKETED_CALENDAR_UNITS:
+        return f"utc{time_unit}"
+    return _TIME_UNIT_TO_VL.get(time_unit, time_unit)
+
+
+def resolve_label_time_unit(
+    encoding_time_unit: str | None, authored_label_time_unit: str | None
+) -> str | None:
+    """Return the label cadence for a resolved encoding time_unit.
+
+    ``None``/``auto`` inherit from the encoding cadence, except weekly buckets
+    default to month labels so dense weekly axes read Jan/Feb/Mar instead of
+    W01/W02/W03. ``none`` disables Dataface's smart label expression.
+    """
+    if authored_label_time_unit == "none":
+        return None
+    if authored_label_time_unit not in (None, "auto"):
+        return authored_label_time_unit
+    if encoding_time_unit in {"yearweek", "yearmonthdate"}:
+        return "yearmonth"
+    return encoding_time_unit
+
+
+def _year_label(v: str, fmt: str, _month: str, _date: str) -> str:
+    return f"{fmt}({v}, '%Y')"
+
+
+def _month_label(v: str, fmt: str, month: str, _date: str) -> str:
+    return (
+        f"{month}({v}) === 0"
+        f" ? [{fmt}({v}, '%b'), {fmt}({v}, '%Y')]"
+        f" : {fmt}({v}, '%b')"
+    )
+
+
+def _quarter_label(v: str, fmt: str, month: str, _date: str) -> str:
+    return (
+        f"{month}({v}) === 0"
+        f" ? ['Q' + (floor({month}({v})/3) + 1), {fmt}({v}, '%Y')]"
+        f" : 'Q' + (floor({month}({v})/3) + 1)"
+    )
+
+
+def _week_label(v: str, fmt: str, month: str, date: str) -> str:
+    return (
+        f"{date}({v}) <= 7 && {month}({v}) === 0"
+        f" ? [{fmt}({v}, 'W%V'), {fmt}({v}, '%Y')]"
+        f" : {fmt}({v}, 'W%V')"
+    )
+
+
+def _day_label(v: str, fmt: str, month: str, date: str) -> str:
+    return (
+        f"{date}({v}) === 1 && {month}({v}) === 0"
+        f" ? [{fmt}({v}, '%-d %b'), {fmt}({v}, '%Y')]"
+        f" : {fmt}({v}, '%-d %b')"
+    )
+
+
+def opens_label_period(
+    encoding_time_unit: str,
+    label_time_unit: str,
+    v: str = "datum.value",
+    month: str = "month",
+    date: str = "date",
+) -> str | None:
+    if label_time_unit == "yearquarter" and encoding_time_unit in {
+        "yearmonth",
+        "yearweek",
+        "yearmonthdate",
+    }:
+        clauses = [f"{month}({v}) % 3 === 0"]
+        if encoding_time_unit == "yearweek":
+            clauses.append(f"{date}({v}) <= 7")
+        elif encoding_time_unit == "yearmonthdate":
+            clauses.append(f"{date}({v}) === 1")
+        return " && ".join(clauses)
+    if label_time_unit == "yearmonth" and encoding_time_unit in {
+        "yearweek",
+        "yearmonthdate",
+    }:
+        return (
+            f"{date}({v}) <= 7"
+            if encoding_time_unit == "yearweek"
+            else f"{date}({v}) === 1"
+        )
+    if label_time_unit == "year" and encoding_time_unit not in {"year"}:
+        clauses = [f"{month}({v}) === 0"]
+        if encoding_time_unit in {"yearweek", "yearmonthdate"}:
+            clauses.append(
+                f"{date}({v}) <= 7"
+                if encoding_time_unit == "yearweek"
+                else f"{date}({v}) === 1"
+            )
+        return " && ".join(clauses)
+    return None
+
+
+def default_label_expr_for(
+    encoding_time_unit: str | None,
+    label_time_unit: str | None,
+) -> str | None:
+    """Return a smart Vega labelExpr for an encoding/label cadence pair.
+
+    The gate (``opens_label_period``) filters to label-period openers because
+    VL's tick cadence is geometry-driven and may overshoot the label cadence —
+    producing duplicate Q-labels when monthly ticks land inside a quarter.
+
+    Always emits ``toDate(datum.value)`` + ``utcFormat`` / ``utcmonth`` /
+    ``utcdate``. Ordinal axes are string-domain (need ``toDate`` to parse);
+    temporal axes use ``scale.type: "utc"`` (so component extraction must
+    also be UTC, otherwise local-TZ ``month()`` shifts January UTC into
+    December local and the cadence gate stamps every tick blank). ``toDate``
+    is a no-op on Date values, so a single shape covers both paths without
+    local-TZ drift.
+    """
+    if not encoding_time_unit or not label_time_unit:
+        return None
+    if label_time_unit in {"auto", "none"}:
+        return None
+    label_exprs = {
+        "year": _year_label,
+        "yearquarter": _quarter_label,
+        "yearmonth": _month_label,
+        "yearweek": _week_label,
+        "yearmonthdate": _day_label,
+    }
+    label_fn = label_exprs.get(label_time_unit)
+    if label_fn is None:
+        return None
+    v = "toDate(datum.value)"
+    fmt = "utcFormat"
+    month = "utcmonth"
+    date = "utcdate"
+    expr = label_fn(v, fmt, month, date)
+    gate = opens_label_period(encoding_time_unit, label_time_unit, v, month, date)
+    return f"{gate} ? ({expr}) : ''" if gate else expr