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

dataface/core/render/chart/type_inference.py

@@ -9,7 +9,7 @@ from typing import TYPE_CHECKING, Any, TypeAlias
 
 from dataface.core.compile.config import get_chart_rendering
 from dataface.core.render.chart.artifacts import ChartRenderData
-from dataface.core.render.chart.vl_field_maps import SCALE_FIELD_MAP, map_fields
+from dataface.core.render.chart.vl_field_maps import emit_resolved_scale_vl
 from dataface.core.text.format_d3 import is_time_format
 
 if TYPE_CHECKING:
@@ -17,7 +17,7 @@ if TYPE_CHECKING:
 
 # Date-only ISO forms (YYYY-MM, YYYY-MM-DD) — the only string shapes JS
 # Date.parse treats as UTC midnight, making them safe domain values for the
-# label.values epoch-ms membership filter on ordinal axes. Datetime strings
+# labels.values epoch-ms membership filter on ordinal axes. Datetime strings
 # without an offset parse as LOCAL time in JS and are deliberately excluded.
 _ISO_UTC_SAFE_RE = re.compile(r"^\d{4}-(0[1-9]|1[0-2])(-(0[1-9]|[12]\d|3[01]))?$")
 
@@ -126,7 +126,10 @@ def resolve_authored_x_type(axis: ResolvedAxisStyle) -> str | None:
     """
     authored_type = axis.type
     if authored_type in (None, "auto") and axis.scale is not None:
-        if axis.scale.type == "temporal":
+        _ax_scale_type = (
+            axis.scale.continuous.type if axis.scale.continuous is not None else None
+        )
+        if _ax_scale_type == "temporal":
             authored_type = "temporal"
     return authored_type
 
@@ -196,7 +199,7 @@ def resolve_cartesian_x_type(
 
 def temporal_edge_labels_flushed(vl_type: str, axis: ResolvedAxisStyle) -> bool:
     """Whether Vega flushes this temporal axis's outer labels into the plot."""
-    return vl_type == "temporal" and axis.label.flush is not False
+    return vl_type == "temporal" and axis.labels.flush is not False
 
 
 def build_cartesian_x_encoding(
@@ -250,7 +253,7 @@ def build_cartesian_x_encoding(
     )
     from dataface.core.render.chart.vl_field_maps import _n
 
-    label_values: list[Any] | None = _n(axis, "label", "values")
+    label_values: list[Any] | None = _n(axis, "labels", "values")
 
     # label_tu is the resolved label cadence for a bucketed grain — computed once
     # so both the density gate below and the axis-values/labelExpr enrichment
@@ -258,7 +261,7 @@ def build_cartesian_x_encoding(
     label_tu: str | None = None
     authored_label_tu: str | None = None
     if time_unit and time_unit in BUCKETED_CALENDAR_UNITS:
-        authored_label_tu = getattr(getattr(axis, "label", None), "time_unit", None)
+        authored_label_tu = getattr(getattr(axis, "labels", None), "time_unit", None)
         label_tu = (
             format_time_unit
             if format_time_unit
@@ -289,7 +292,7 @@ def build_cartesian_x_encoding(
         label_tu in BUCKETED_CALENDAR_UNITS
         and label_tu != time_unit
         and axis.ticks.count is None
-        and axis.ticks.interval is None
+        and axis.ticks.time_unit is None
         and "values" not in ax_vl
     )
     label_tick_values: list[Any] = []
@@ -322,7 +325,7 @@ def build_cartesian_x_encoding(
             )
             temporal_anchor_value = str((anchor_openers or anchor_values[:1])[0])
 
-    # label.values needs the epoch-ms membership filter to match every
+    # labels.values needs the epoch-ms membership filter to match every
     # listed date exactly. On a continuous temporal scale datum.value is
     # already epoch ms — always exact. On any other emit path datum.value is
     # the raw domain value, which Vega parses with JS Date semantics: only
@@ -350,7 +353,11 @@ def build_cartesian_x_encoding(
                 raise ChartDataError.from_code(
                     ERR_LABEL_VALUES_NOT_TEMPORAL,
                     field=x_field,
-                    example=row[x_field],
+                    cause=f"it contains {row[x_field]!r}, which isn't a UTC-safe ISO date",
+                    remedy=(
+                        "Use date-only ISO dates (YYYY-MM-DD or YYYY-MM) or date "
+                        "objects in the query, or remove labels.values."
+                    ),
                 )
 
     result = dict(ax_vl)
@@ -430,15 +437,15 @@ def build_cartesian_x_encoding(
             )
             if smart_expr_t is not None:
                 result["labelExpr"] = smart_expr_t
-    # Step-anchored cadence (axis.ticks.interval/step) requires a genuinely
+    # Step-anchored cadence (axis.ticks.time_unit/step) requires a genuinely
     # continuous temporal x-axis — compile-time gates (_bake_cartesian_axes)
-    # already reject it on axis_y and reject step-without-interval, but
+    # already reject it on axis_y and reject step-without-time_unit, but
     # whether THIS axis resolves to temporal vs ordinal is a data-dependent
     # decision only known here. Unlike count (which silently no-ops on
-    # ordinal — see the density-gate test suite), interval/step raise: the
+    # ordinal — see the density-gate test suite), time_unit/step raise: the
     # whole point of the surface is an explicit cadence, so a silent no-op
     # would hide a misconfiguration rather than surface it.
-    if axis.ticks.interval is not None and vl_type != "temporal":
+    if axis.ticks.time_unit is not None and vl_type != "temporal":
         from dataface.core.diagnostics.chart_data import ChartDataError
         from dataface.core.diagnostics.codes_render import (
             ERR_TICKS_INTERVAL_NOT_TEMPORAL,
@@ -448,17 +455,29 @@ def build_cartesian_x_encoding(
             ERR_TICKS_INTERVAL_NOT_TEMPORAL, field=x_field, vl_type=vl_type
         )
 
-    # Authored ticks.count/interval on a temporal scale maps straight to VL's
+    # Authored ticks.count/time_unit on a temporal scale maps straight to VL's
     # axis.tickCount (a plain number, or {interval, step} for step-anchored
-    # cadence — see _resolve_cartesian_ticks for the quantitative-axis
+    # cadence — VL's own wire format uses "interval" regardless of Dataface's
+    # field name — see _resolve_cartesian_ticks for the quantitative-axis
     # explicit-values path, which is unrelated). Ordinal axes are out of
     # scope: tickCount has no meaning against a discrete-domain ordinal
     # scale, so this never fires for vl_type == "ordinal". axis.ticks is a
     # required ResolvedAxisStyle field — read it directly and crash loudly on
     # a malformed axis object rather than silently skipping.
     if vl_type == "temporal" and "tickCount" not in result and "values" not in result:
-        if axis.ticks.interval is not None:
-            tick_count: dict[str, Any] = {"interval": axis.ticks.interval}
+        _ticks_time_unit = axis.ticks.time_unit
+        if _ticks_time_unit is not None:
+            if _ticks_time_unit not in _TEMPORAL_TICK_INTERVAL:
+                from dataface.core.diagnostics.chart_data import ChartDataError
+
+                raise ChartDataError(
+                    f"ticks.time_unit: {_ticks_time_unit!r} has no step-anchored "
+                    "cadence — only a calendar-bucketing grain "
+                    f"({', '.join(_TEMPORAL_TICK_INTERVAL)}) names a VL tick "
+                    "interval."
+                )
+            interval, _ = _TEMPORAL_TICK_INTERVAL[_ticks_time_unit]
+            tick_count: dict[str, Any] = {"interval": interval}
             if axis.ticks.step is not None:
                 tick_count["step"] = axis.ticks.step
             result["tickCount"] = tick_count
@@ -478,7 +497,7 @@ def build_cartesian_x_encoding(
     )
 
     result = inject_axis_label_case(result, axis)
-    # label.values filter runs last of all — it wins over any smart-cadence
+    # labels.values filter runs last of all — it wins over any smart-cadence
     # or case-transformed text already resolved above.
     result = inject_axis_label_values_filter(result, axis)
     return vl_type, result, time_unit
@@ -490,21 +509,22 @@ def y_zero_scale(
 ) -> dict[str, Any]:
     """Build a VL y-scale dict from the resolved y-axis style.
 
-    Merges every ``SCALE_FIELD_MAP`` field (``type``, ``base``, ``exponent``,
-    etc.) the same way scatter's ``_build_axis_scale`` does — one canonical
-    mapper, so a measure-axis ``scale.type: log`` (previously honored only on
-    scatter) reaches line/area/bar too. ``zero`` is excluded from that merge
-    and computed separately:
+    Merges every scale field (``type``, ``base``, ``exponent``, etc.) via
+    ``emit_resolved_scale_vl`` — one canonical emitter, so a measure-axis
+    ``scale.type: log`` (previously honored only on scatter) reaches
+    line/area/bar too. ``zero`` is excluded from that merge and computed
+    separately:
 
     axis.scale.zero is True  → {"domainMin": tick_values[0] or 0.0, "zero": True}
     anything else            → {"zero": False}
     """
     scale = getattr(axis, "scale", None) if axis is not None else None
-    zero = getattr(scale, "zero", None) if scale is not None else None
+    _sc_cont = scale.continuous if scale is not None else None
+    zero = _sc_cont.zero if _sc_cont is not None else None
 
     out: dict[str, Any] = {}
     if scale is not None:
-        out.update(map_fields(scale, SCALE_FIELD_MAP))
+        out.update(emit_resolved_scale_vl(scale))
         out.pop("zero", None)  # zero is computed below, not passed through raw
 
     if zero is True:

dataface/core/render/chart/validation.py

@@ -6,6 +6,7 @@ Keeps data-shape policy separate from mechanical spec assembly.
 from __future__ import annotations
 
 from collections import Counter
+from decimal import Decimal
 from typing import Any
 
 from dataface.core.compile.models.chart.resolved import (
@@ -18,9 +19,15 @@ from dataface.core.diagnostics.chart_data import ChartDataError
 from dataface.core.diagnostics.codes_render import (
     ERR_BAR_DUPLICATE_ROWS,
     ERR_COLOR_NULL_SERIES,
+    ERR_HISTOGRAM_PREAGGREGATED,
 )
 from dataface.core.render.chart.type_inference import infer_vega_type_from_data
 
+# A run this short forming a gapless integer sequence by chance is not
+# meaningfully unusual for genuine raw data; below this length the "dense
+# integer run" signal in _forms_gapless_integer_run is too weak to act on.
+_MIN_RUN_FOR_GROUP_BY_SHAPE = 5
+
 
 def validate_color_series(
     chart: ResolvedBarChart | ResolvedLineChart | ResolvedAreaChart,
@@ -172,3 +179,87 @@ def validate_preaggregated_data(
         field_list=field_list,
         duplicate_preview=duplicate_preview,
     )
+
+
+def _forms_gapless_integer_run(values: list[Any]) -> bool:
+    """True when every value is integer-valued, none repeats, and together
+    they cover every integer between the min and max with no gaps.
+
+    This is exactly the shape ``GROUP BY <integer column>`` produces: one row
+    per distinct observed value. It is deliberately *not* "zero duplicate
+    values" alone — a continuous measure (the primary histogram use case,
+    e.g. price, latency) is essentially always duplicate-free too, so that
+    signal can't tell raw from aggregated. A dense, gapless run of whole
+    numbers is different: real raw samples have gaps and skew; hitting every
+    integer in a range exactly once is the kind of thing an integer bucket
+    key produces by construction; a continuous measure practically never
+    produces by chance.
+    """
+    if len(values) < _MIN_RUN_FOR_GROUP_BY_SHAPE:
+        return False
+
+    whole_numbers: set[int] = set()
+    for value in values:
+        if isinstance(value, bool):
+            return False
+        if isinstance(value, int):
+            whole = value
+        elif (isinstance(value, float) and value.is_integer()) or (
+            isinstance(value, Decimal) and value == value.to_integral_value()
+        ):
+            whole = int(value)
+        else:
+            return False
+        if whole in whole_numbers:
+            return False
+        whole_numbers.add(whole)
+
+    return max(whole_numbers) - min(whole_numbers) + 1 == len(whole_numbers)
+
+
+def validate_raw_rows_for_histogram(
+    chart: ResolvedBarChart,
+    data: list[dict[str, Any]],
+) -> None:
+    """Reject pre-aggregated data on a histogram — the mirror image of
+    ``validate_preaggregated_data``.
+
+    Histograms hand Vega-Lite raw, ungrouped rows and let VL do its own
+    binning + counting; a histogram's ``y`` is always ``aggregate: count``,
+    never a data column. A pre-aggregated table — the output of
+    ``SELECT x, count(*) FROM t GROUP BY x`` — carries that count (and
+    possibly other aggregates) in leftover numeric columns the emitter never
+    reads, and ``x`` forms a gapless run of whole numbers (what ``GROUP BY``
+    over an integer bucket produces — see ``_forms_gapless_integer_run``).
+    Both conditions together are the tell; either alone is common in genuine
+    raw data (a raw fact table often carries a spare numeric column — an id,
+    a second measure — and a continuous measure is duplicate-free as a
+    matter of course). Feeding pre-aggregated data to VL would bin and
+    recount the already-counted rows, silently discarding the real count.
+    """
+    if not data or chart.x is None:
+        return
+    x_field = chart.x
+
+    color_field = effective_color_field(chart)
+    extra_columns = [
+        column for column in data[0] if column not in {x_field, color_field}
+    ]
+    numeric_extra_columns = [
+        column
+        for column in extra_columns
+        if infer_vega_type_from_data(data, column) == "quantitative"
+    ]
+    if not numeric_extra_columns:
+        return
+
+    x_values = [row.get(x_field) for row in data]
+    if not _forms_gapless_integer_run(x_values):
+        return
+
+    raise ChartDataError.from_code(
+        ERR_HISTOGRAM_PREAGGREGATED,
+        chart_id=chart.id or "unknown",
+        field=x_field,
+        count_fields=", ".join(repr(column) for column in numeric_extra_columns),
+    )

dataface/core/render/chart/vega_lite.py

@@ -40,6 +40,7 @@ def _trace_vl_spec(chart_id: str, renderer: str, spec: dict[str, Any]) -> None:
 from dataface.core.compile.models.chart.resolved import ResolvedChart
 from dataface.core.compile.models.chart.resolved._base import (
     _CartesianResolvedChartFields,
+    _SharedResolvedChartFields,
 )
 from dataface.core.compile.models.chart.resolved.bar import ResolvedBarChart
 from dataface.core.compile.models.chart.resolved.pie import ResolvedPieChart
@@ -98,6 +99,10 @@ def _render_vl_artifact(
     )
     if svg is not None:
         return RenderArtifact(kind="svg", payload=svg)
+    # render_svg_family only returns None for the VL families, all of which
+    # are _SharedResolvedChartFields subclasses (KPI/callout/table/spark_bar
+    # return svg above) — title_style is guaranteed present below.
+    assert isinstance(resolved, _SharedResolvedChartFields)
 
     effective_height = height
     if (
@@ -144,13 +149,24 @@ def _render_vl_artifact(
         if padding is not None:
             vl["padding"] = padding
         _apply_facet_layout(vl, render_data, width, effective_height)
-        apply_title_overflow_to_spec(vl, resolved_style.charts.title)
+        apply_title_overflow_to_spec(vl, resolved.title_style)
         _trace_vl_spec(resolved.id, "v2", vl)
         return RenderArtifact(kind="vega_spec", payload=vl)
     if "hconcat" in vl:
         size_target = vl["hconcat"][0]
         if "title" in vl:
             size_target["title"] = vl.pop("title")
+        # hconcat's title wrap is deferred to render_vega_spec (see the
+        # comment below) — stamp the chart's own title_style so the deferred
+        # wrap reads the same chart-local source as the non-hconcat path
+        # above, instead of re-deriving it from the board-level style bag.
+        # A plain dict, not the live TitleStyle object: this sentinel can
+        # leak into a raw spec dict handed directly to vl-convert (e.g.
+        # generate_vega_lite_spec()'s return value, or a RenderArtifact
+        # payload used outside render_chart_artifact) — an unrecognized
+        # dict-valued key is harmless there, but a Pydantic object is not
+        # JSON-serializable.
+        vl["$df_title_style"] = resolved.title_style.model_dump()
     else:
         size_target = vl
     if padding is not None:
@@ -179,7 +195,7 @@ def _render_vl_artifact(
         # still the full column width — wrapping against it now overstates
         # the room the title actually has. render_vega_spec wraps it after
         # _correct_concat_overshoot shrinks pane[0] to its real width.
-        apply_title_overflow_to_spec(size_target, resolved_style.charts.title)
+        apply_title_overflow_to_spec(size_target, resolved.title_style)
     _trace_vl_spec(resolved.id, "v2", vl)
     return RenderArtifact(kind="vega_spec", payload=vl)
 
@@ -424,12 +440,9 @@ def generate_vega_lite_spec(
     SVG-family charts (kpi, table, spark_bar, callout) have no Vega-Lite
     spec; callers that ask for one get ERR_VEGA_LITE_UNSUPPORTED_TYPE.
     """
-    import dataclasses
-
     from dataface.core.compile.config import get_theme_style
     from dataface.core.compile.models.style.resolved import resolve_style
     from dataface.core.compile.resolve import preferred_chart_width, resolve
-    from dataface.core.compile.style_cascade import build_resolved_style
 
     style = board_style if board_style is not None else resolve_style(get_theme_style())
     # resolve() dispatches on chart.type first and raises for unsupported/synthetic
@@ -442,14 +455,13 @@ def generate_vega_lite_spec(
         if isinstance(resolved, ResolvedPieChart)
         else width if width is not None else preferred_chart_width(chart, style)
     )
-    # Merge chart-local style (e.g. bar.title.font.size) into board_style.charts so
-    # finalize_vl picks up authored title overrides when computing the VL spec config.
-    chart_charts_style = build_resolved_style(style, chart)
-    render_style = dataclasses.replace(style, charts=chart_charts_style)
+    # The resolved chart already carries its final chart-local presentation
+    # values (background, title_style) baked in at resolve() — no second
+    # style decision here. style is the unchanged face-level style.
     artifact = _render_vl_artifact(
         resolved,
         data,
-        render_style,
+        style,
         width=resolved_width,
         height=height,
         is_placeholder=False,
@@ -462,7 +474,14 @@ def generate_vega_lite_spec(
         )
     assert isinstance(artifact.payload, dict)
     vl = _apply_data_table_strip(artifact.payload, resolved, style.charts, data)
-    return vl if vl is not None else artifact.payload
+    result = vl if vl is not None else artifact.payload
+    # $df_title_style is an internal hand-off to render_vega_spec's deferred
+    # hconcat title wrap (converters/chart.py) — this entry point returns the
+    # spec directly without going through that conversion, and the sentinel
+    # holds a non-JSON-serializable TitleStyle object, so it must not leak
+    # into the public return value.
+    result.pop("$df_title_style", None)
+    return result
 
 
 def render_chart(