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

dataface/core/compile/models/style/theme/axis.py

@@ -14,6 +14,21 @@ from dataface.core.compile.models.markers import (
     Strategy,
 )
 
+_TIME_UNIT_LITERAL = Literal[
+    "auto",
+    "year",
+    "yearquarter",
+    "yearmonth",
+    "yearweek",
+    "yearmonthdate",
+    "monthofyear",
+    "dayofweek",
+    "dayofmonth",
+    "dayofyear",
+    "hourofday",
+    "none",
+]
+
 
 class AxisLabelOverlapConfig(BaseModel):
     """Two-bool overlap strategy enablement for x-axis labels.
@@ -59,7 +74,7 @@ from dataface.core.compile.models.style.theme.board import (
 class AxisGridZeroStyle(BaseModel):
     """Zero-baseline gridline color and width overrides.
 
-    Nested sub-object under AxisGridStyle.zero. Quantitative axes only —
+    Nested sub-object under BaseAxisGridStyle.zero. Quantitative axes only —
     band axes never tick at value=0.
     """
 
@@ -76,13 +91,18 @@ class AxisGridZeroStyle(BaseModel):
     )
 
 
-class AxisGridStyle(BaseModel):
+class BaseAxisGridStyle(BaseModel):
+    """Grid line style for all axis variants.
+
+    No zero field — that lives only on MeasureGridStyle (AxisYStyle.grid). A
+    zero-baseline gridline only makes sense on the measure (y) axis; putting it
+    on the shared base would allow authoring it on x-axes where it is silent.
+    """
+
     model_config = ConfigDict(extra="forbid", frozen=True)
 
-    # All fields are nullable in AxisGridStyle so the cascade can fill
-    # missing values from parent `axis` into `axis_x` / `axis_y` /
-    # `axis_quantitative`. The base `axis` slot must have all fields non-None;
-    # `_build_resolved_axis` validates this at resolve time.
+    # All fields are nullable so the cascade can fill missing values from parent
+    # `axis` into `axis_x` / `axis_y` / `axis_quantitative`.
     visible: bool | None = Field(
         default=None, description="Show grid lines; None inherits from parent axis."
     )
@@ -103,17 +123,32 @@ class AxisGridStyle(BaseModel):
         default=None,
         description="Dash pattern for grid lines; None renders a solid line.",
     )
-    # Zero-baseline sub-block. None on child axes means "no override at this level";
-    # the cascade fills individual zero.* fields from the parent axis.
-    # SkipInheritSlots(cascade=True): apply_inherit copies the entire zero object when
-    # the child axis has zero=None; apply_inherit copies the zero object from the parent axis slot (cascade=True).
+
+
+class MeasureGridStyle(BaseAxisGridStyle):
+    """BaseAxisGridStyle + zero-baseline override for the measure (y) axis.
+
+    Used only by AxisYStyle.grid. The zero sub-block is structurally absent on
+    all other axis variants so the model rejects it at validation time.
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    # Zero-baseline sub-block. None means "no override at this level"; the
+    # cascade fills individual zero.* fields from the parent axis.
+    # SkipInheritSlots(cascade=True): apply_inherit copies the entire zero object
+    # when the child axis has zero=None; fills individual None fields when partial.
     zero: Annotated[AxisGridZeroStyle | None, SkipInheritSlots(cascade=True)] = Field(
         default=None,
         description="Zero-baseline gridline style; None inherits from parent axis.",
     )
 
 
-class AxisDomainStyle(BaseModel):
+class AxisLineStyle(BaseModel):
+    """Axis domain/baseline line style. Renamed from ``AxisDomainStyle`` —
+    same 3 fields, no shape change; ``domain`` collided too easily with
+    scale-domain terminology."""
+
     model_config = ConfigDict(extra="forbid", frozen=True)
 
     # Nullable so the cascade can fill missing values from parent `axis`.
@@ -130,56 +165,11 @@ class AxisDomainStyle(BaseModel):
     )
 
 
-class AxisTicksCadenceValidationMixin(BaseModel):
-    """Authored-input validator for step-anchored tick cadence.
-
-    Applied only to ``AxisTicksStylePatch`` (the authored overlay), not the
-    compiled ``AxisTicksStyle`` — the compiled type is the cascade-merged
-    result across theme/chart-type/chart-local layers, and a legitimate
-    theme default (e.g. editorial's ``axis_quantitative.ticks.count: 6``)
-    can land in the same merged object as an unrelated authored ``interval``
-    on a different axis slot without either single authored layer actually
-    conflicting. Validating only the as-authored patch catches the real
-    mistake (both fields set together in the same authored block) without
-    that cross-layer false positive. ``build_patch_model_ext`` only carries
-    over validators that live on the patch model's base class (mirrors
-    ``ScaleDomainValidationMixin`` above).
-
-    Enforces: ``step`` requires ``interval`` (step alone doesn't name a
-    cadence unit), and ``interval``/``count`` are mutually exclusive (two
-    different ways to express tick cadence). Both fields absent, or
-    ``interval`` alone, are always valid.
-    """
-
-    model_config = ConfigDict(extra="forbid")
-
-    @model_validator(mode="before")
-    @classmethod
-    def _validate_cadence(cls, data: object) -> object:
-        if not isinstance(data, dict):
-            return data
-        step = data.get("step")
-        interval = data.get("interval")
-        count = data.get("count")
-        if step is not None and interval is None:
-            raise ValueError(
-                "ticks.step is set without ticks.interval — step alone "
-                "doesn't name a cadence unit (year/quarter/month). Author "
-                "both (e.g. interval: year, step: 5), or use ticks.count for "
-                "VL's advisory tick-count hint instead."
-            )
-        if interval is not None and count is not None:
-            raise ValueError(
-                "ticks.interval and ticks.count cannot both be set — they "
-                "are two different ways to express tick cadence. Use "
-                "ticks.interval/step for a step-anchored cadence (every N "
-                "years/quarters/months), or ticks.count for VL's advisory "
-                "tick-count hint, not both."
-            )
-        return data
-
-
 class AxisTicksStyle(BaseModel):
+    """Universal tick config. ``step``-anchored cadence needs a named time
+    unit to mean anything — that unit field lives on ``DimensionTicksStyle``
+    (axis_x only), not here; ``step`` alone on this base class is inert."""
+
     model_config = ConfigDict(extra="forbid", frozen=True)
 
     # Nullable so the cascade can fill `visible` from parent `axis`.
@@ -189,7 +179,7 @@ class AxisTicksStyle(BaseModel):
     color: str | None = Field(
         default=None, description="Tick color; None uses Vega-Lite's default."
     )
-    size: float | None = Field(
+    length: float | None = Field(
         default=None,
         description="Tick length in pixels; None uses Vega-Lite's default.",
     )
@@ -197,6 +187,10 @@ class AxisTicksStyle(BaseModel):
         default=None,
         description="Tick stroke width in pixels; None uses Vega-Lite's default.",
     )
+    offset: float | None = Field(
+        default=None,
+        description="Pixel offset of ticks from their default position; None means no offset.",
+    )
     # SkipInheritSlots: count is not inherited — axis family variants each set their own count.
     count: Annotated[int | None, SkipInheritSlots()] = Field(
         default=None,
@@ -208,31 +202,99 @@ class AxisTicksStyle(BaseModel):
             "which VL's time-scale tick logic honours as a target."
         ),
     )
-    # SkipInheritSlots: interval/step are not inherited — axis family variants each set their own.
-    interval: Annotated[
-        Literal["year", "quarter", "month"] | None, SkipInheritSlots()
-    ] = Field(
+    # SkipInheritSlots: step is not inherited — axis family variants each set their own.
+    step: Annotated[int | None, SkipInheritSlots()] = Field(
         default=None,
         description=(
-            "Step-anchored tick cadence unit — 'ticks every N <interval>, "
-            "anchored on multiples of N'. Mutually exclusive with count. "
-            "Meaningful on a continuous-temporal axis_x only — raises at "
-            "compile on axis_y, and at render if the x-axis resolves to a "
-            "non-temporal (ordinal) scale."
+            "Step multiple for a step-anchored tick cadence (e.g. on "
+            "DimensionTicksStyle: time_unit: year, step: 5 -> ticks every 5 "
+            "years). Inert on this base class alone — a channel that wants "
+            "step-anchored cadence adds the unit field (DimensionTicksStyle.time_unit)."
         ),
     )
-    step: Annotated[int | None, SkipInheritSlots()] = Field(
+
+
+class DimensionTicksStyle(AxisTicksStyle):
+    """axis_x-only: step-anchored tick cadence needs a named time unit.
+
+    Distinct from ``DimensionLabelStyle.time_unit`` (label-cadence override)
+    and ``AxisXStyle.time_unit`` (bucketing grain) — three different
+    time_unit fields, three different meanings.
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    time_unit: _TIME_UNIT_LITERAL | None = Field(
+        default=None,
+        description="Step-anchored tick cadence unit; None disables step-anchored ticks.",
+    )
+
+    @model_validator(mode="after")
+    def _validate_cadence(self) -> DimensionTicksStyle:
+        if self.step is not None and self.time_unit is None:
+            raise ValueError(
+                "ticks.step is set without ticks.time_unit — step alone "
+                "doesn't name a cadence unit (year/quarter/month/...). "
+                "Author both (e.g. time_unit: year, step: 5), or use "
+                "ticks.count for VL's advisory tick-count hint instead."
+            )
+        if self.time_unit is not None and self.count is not None:
+            raise ValueError(
+                "ticks.time_unit and ticks.count cannot both be set — they "
+                "are two different ways to express tick cadence. Use "
+                "ticks.time_unit/step for a step-anchored cadence (every N "
+                "years/quarters/months), or ticks.count for VL's advisory "
+                "tick-count hint, not both."
+            )
+        return self
+
+
+class AxisTitleStyle(BaseModel):
+    """Axis title typography — deliberately thin. A title is one short static
+    string, not a per-tick label stream, so it doesn't need the label-overlap
+    strategy machinery or VL passthrough knobs (bound/flush/offset/line_height)
+    that only make sense for a repeated per-tick label. padding is kept
+    (unlike those) since the theme authors a real, non-VL-default value."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    font: Annotated[FontStyle, InheritSlot(from_path="Style.charts.font")] = Field(
+        default_factory=FontStyle, description="Axis title font style overrides."
+    )
+    padding: float | None = Field(
+        default=None,
+        description="Padding between axis title and labels in pixels; None uses Vega-Lite's default.",
+    )
+    angle: float | None = Field(
+        default=None,
+        description="Title rotation angle in degrees; None uses Vega-Lite's default.",
+    )
+    # Same left/right/center/inward/outward vocabulary as AxisLabelStyle.align
+    # — resolved through the identical _resolve_own_side_align machinery.
+    align: Literal["left", "right", "center", "inward", "outward"] | None = Field(
         default=None,
         description=(
-            "Step multiple for the interval cadence (e.g. interval: year, "
-            "step: 5 -> ticks every 5 years). Requires interval to also be "
-            "set — step alone doesn't name a unit."
+            "Horizontal text alignment of the title. 'left'/'right'/'center' "
+            "are absolute. 'inward'/'outward' resolve against the axis's own "
+            "left/right edge, same as label.align; a no-op on an axis with no "
+            "left/right edge. None uses Vega-Lite's default."
         ),
     )
+    visible: bool | None = Field(
+        default=None,
+        description="Show the axis title; None uses Vega-Lite's default (title shown).",
+    )
 
 
-class AxisElementStyle(BaseModel):
-    """Axis label or title: font + padding + VL-passthrough."""
+class AxisLabelStyle(BaseModel):
+    """Axis label: font + padding + VL-passthrough.
+
+    This is the universal base — fields that are meaningful on both dimension
+    and measure axes. Dimension-only fields (tilt_increments, values,
+    time_unit) live on DimensionLabelStyle, which is used for AxisXStyle.labels.
+    expr stays here: it is universal and read by time_unit_detect.py on both
+    axes.
+    """
 
     model_config = ConfigDict(extra="forbid", frozen=True)
 
@@ -268,10 +330,6 @@ class AxisElementStyle(BaseModel):
             "default."
         ),
     )
-    baseline: str | None = Field(
-        default=None,
-        description="Vertical text baseline of labels; None uses Vega-Lite's default.",
-    )
     # Two-bool struct enabling/disabling each overlap strategy.
     # None = not authored — inherit the parent axis's setting from the cascade.
     # SkipInheritSlots(cascade=True): if overlap is None on the child axis,
@@ -290,38 +348,18 @@ class AxisElementStyle(BaseModel):
             "to a coarser calendar period without changing the axis or label time unit."
         ),
     )
-    separation: float | None = Field(
+    min_gap: float | None = Field(
         default=None,
-        description="Minimum pixel separation between labels; None uses Vega-Lite's default (0px).",
+        description="Minimum pixel gap between labels; None uses Vega-Lite's default (0px).",
     )
     visible: bool | None = Field(
         default=None,
         description="Show axis labels; None uses Vega-Lite's default (labels shown).",
     )
-    # Optional label cadence for temporal axes. None inherits from the parent
-    # axis time_unit; render-time layout may promote sub-month auto labels.
-    time_unit: (
-        Literal[
-            "auto",
-            "year",
-            "yearquarter",
-            "yearmonth",
-            "yearweek",
-            "yearmonthdate",
-            "monthofyear",
-            "dayofweek",
-            "dayofmonth",
-            "dayofyear",
-            "hourofday",
-            "none",
-        ]
-        | None
-    ) = Field(
-        default=None,
-        description="Label cadence for temporal axes; None inherits from the parent axis time_unit.",
-    )
     # When None and the parent axis has a temporal time_unit, the render layer
     # fills in a smart conditional labelExpr — see render/chart/time_unit_detect.py.
+    # Kept on the base (not just DimensionLabelStyle) — both axes may use custom
+    # label expressions, e.g. for axis_y mirror overrides via AxisMirrorStyle.expr.
     expr: str | None = Field(
         default=None,
         description="Custom Vega expression for label text; None uses smart temporal defaults when applicable.",
@@ -339,11 +377,27 @@ class AxisElementStyle(BaseModel):
         default=None,
         description="Pixel offset of the label from its tick anchor; None uses Vega-Lite's default.",
     )
-    line_height: float | None = Field(
+    format: str | None = Field(
+        default=None, description="Tick value format string; None uses auto-format."
+    )
+
+
+class DimensionLabelStyle(AxisLabelStyle):
+    """AxisLabelStyle + dimension-axis-only label fields.
+
+    Used only by AxisXStyle.labels. Fields here are structurally absent on
+    AxisYStyle.labels so the model rejects them at validation time rather than
+    requiring a scattered runtime check.
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    # Optional label cadence for temporal axes. None inherits from the parent
+    # axis time_unit, except yearweek defaults to month labels.
+    time_unit: _TIME_UNIT_LITERAL | None = Field(
         default=None,
-        description="Line height for multi-line labels in pixels; None uses Vega-Lite's default.",
+        description="Label cadence for temporal axes; None inherits from the parent axis time_unit.",
     )
-    anchor: Literal["start", "middle", "end"] | None = Field(default=None, description="Label anchor position; None uses Vega-Lite's default.")  # fmt: skip
     # Descending tilt ladder consulted by the "tilt" strategy on discrete x-axes.
     # The picker walks this list and returns the first angle whose label widths
     # fit at the chart's drawable width; fall-through uses the last entry (steepest).
@@ -356,15 +410,17 @@ class AxisElementStyle(BaseModel):
     # Decouples LABEL density from tick/grid density on temporal x-axes. This
     # is a filter, not a tick list: it does not add or remove ticks. Ticks and
     # gridlines are produced exactly as they would be without this field —
-    # from ``AxisStyle.values`` if authored, else the auto-fill default. Each
-    # of those ticks then gets its label text kept only if its date appears
-    # in this list; every other tick keeps its position/gridline but its
-    # label is blanked. A date here that doesn't match any actual tick is a
-    # silent no-op (nothing exists to unblank). To change tick/grid density
-    # itself, author ``axis_x.values``. None labels every tick per the
+    # from ``axis_x.scale.values`` if authored, else the auto-fill default.
+    # Each of those ticks then gets its label text kept only if its date
+    # appears in this list; every other tick keeps its position/gridline but
+    # its label is blanked. A date here that doesn't match any actual tick is
+    # a silent no-op (nothing exists to unblank). To change tick/grid density
+    # itself, author ``axis_x.scale.values``. None labels every tick per the
     # existing smart cadence/format. Temporal x-axes only — the render layer
-    # raises when authored on a non-temporal axis or on axis_y (the measure
-    # axis is never temporal in Dataface's model).
+    # raises when authored on a non-temporal axis, on axis_y (the measure
+    # axis is never temporal in Dataface's model), or on a bar chart whose
+    # categorical axis renders horizontal (that axis is always nominal,
+    # regardless of orientation being forced or auto-inferred).
     values: Annotated[list[Any] | None, Merge(Strategy.OVERRIDE)] = Field(
         default=None,
         min_length=1,
@@ -375,7 +431,8 @@ class AxisElementStyle(BaseModel):
             "add or remove ticks. Every tick not in this list keeps its "
             "position and gridline but has its label blanked. Set "
             "axis_x.values separately to change tick/grid density itself. "
-            "Temporal x-axes only; None labels every tick as usual."
+            "Temporal x-axes only; not supported on a horizontal bar's "
+            "categorical axis. None labels every tick as usual."
         ),
     )
 
@@ -407,7 +464,7 @@ def _is_iso_date_string(value: str) -> bool:
 class ScaleDomainValidationMixin(BaseModel):
     """Shared authored-input validator for scale domain shape/consistency.
 
-    Inherited by both ``ScaleStyle`` and ``ScaleStylePatch`` so chart-local
+    Inherited by both ``BaseScaleStyle`` and ``BaseScaleStylePatch`` so chart-local
     authored patches enforce the same domain rules as theme-stage input —
     ``build_patch_model_ext`` only carries over validators that live on the
     patch model's base class (mirrors ``_FaceDesugarMixin``).
@@ -447,86 +504,63 @@ class ScaleDomainValidationMixin(BaseModel):
         return data
 
 
-class ScaleBandStyle(BaseModel):
-    """Band mark size constraints (min/max pixel width for band-scale marks)."""
+class ScaleLogStyle(BaseModel):
+    """Log-scale-only param."""
 
     model_config = ConfigDict(extra="forbid", frozen=True)
 
-    min_size: float | None = Field(  # None = no min constraint; authored overlay
-        default=None,
-        description="Minimum band mark width in pixels; None uses Vega-Lite's default.",
-    )
-    max_size: float | None = Field(  # None = no max constraint; authored overlay
+    base: float | None = Field(
         default=None,
-        description="Maximum band mark width in pixels; None uses Vega-Lite's default.",
+        description="Log base; only meaningful with type: log. None lets Vega-Lite apply its own default (10).",
     )
 
 
-class ScaleStyle(ScaleDomainValidationMixin):
-    """Scale configuration primitive.
-
-    Used both at chart-level (``style.scale`` — applies to both x and y) and
-    per-axis (``style.axis_x.scale``, ``style.axis_y.scale`` — overrides on
-    that channel only). Per-axis values win on conflict.
-    """
+class ScalePowStyle(BaseModel):
+    """Power-scale-only param."""
 
     model_config = ConfigDict(extra="forbid", frozen=True)
 
-    band_padding_inner: float | None = Field(
-        default=None,
-        description="Inner padding fraction for band scales; None uses Vega-Lite's default.",
-    )
-    band_padding_outer: float | None = Field(
-        default=None,
-        description="Outer padding fraction for band scales; None uses Vega-Lite's default.",
-    )
-    point_padding: float | None = Field(
-        default=None,
-        description="Padding fraction for point scales; None uses Vega-Lite's default.",
-    )
-    rect_band_padding_inner: float | None = Field(
+    exponent: float | None = Field(
         default=None,
-        description="Inner padding fraction for rect band scales; None uses Vega-Lite's default.",
+        description="Power exponent; only meaningful with type: pow. None uses Vega-Lite's default.",
     )
-    round: bool | None = Field(
+
+
+class ScaleSymlogStyle(BaseModel):
+    """Symlog-scale-only param."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    constant: float | None = Field(
         default=None,
-        description="Round scale outputs to nearest integer; None uses Vega-Lite's default (no rounding).",
+        description="Symlog constant; only meaningful with type: symlog. None uses Vega-Lite's default.",
     )
-    zero: bool | Literal["auto"] | None = Field(  # None = VL passthrough
+
+
+class ScaleContinuousStyle(ScaleDomainValidationMixin):
+    """Continuous-scale-only config: type, domain, zero-baseline, log/pow/symlog params.
+
+    Carries two validators moved from the old flat ``BaseScaleStyle``:
+    - ScaleDomainValidationMixin: the domain-shape check (applies to both this
+      class and its generated Patch via build_patch_model_ext).
+    - _validate_log_pow_symlog_params: defined DIRECTLY here, NOT on a mixin —
+      this validator fires on the fully-merged result; it must NOT carry into
+      the generated Patch since a theme layer may set type: log and a
+      chart-local patch layer may set only base. The cross-field check fires
+      once, on the merged result.
+
+    All fields optional — see test_scale_groups_have_no_required_fields.
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    zero: bool | Literal["auto"] | None = Field(
         default=None,
         description=(
             'Force scale zero-baseline: True/False pins it; "auto" runs the '
             "Dataface smart-zero heuristic; None passes through to Vega-Lite."
         ),
     )
-    clamp: bool | None = Field(
-        default=None,
-        description="Clamp values to scale domain; None uses Vega-Lite's default (no clamping).",
-    )
-    continuous_padding: float | None = Field(
-        default=None,
-        description="Padding in pixels for continuous scales; None uses Vega-Lite's default.",
-    )
-    band: ScaleBandStyle | None = Field(  # None = no band size constraint authored
-        default=None,
-        description="Band mark size constraints; None uses Vega-Lite's defaults.",
-    )
-    quantile_count: int | None = Field(
-        default=None,
-        description="Number of quantile buckets; None uses Vega-Lite's default.",
-    )
-    quantize_count: int | None = Field(
-        default=None,
-        description="Number of quantize buckets; None uses Vega-Lite's default.",
-    )
-    use_unaggregated_domain: bool | None = Field(
-        default=None,
-        description="Use unaggregated domain for scale extent; None uses Vega-Lite's default.",
-    )
-    x_reverse: bool | None = Field(
-        default=None,
-        description="Reverse the x-axis scale direction; None means no reversal.",
-    )
     type: Literal["linear", "log", "pow", "sqrt", "symlog", "temporal"] | None = Field(
         default=None,
         description=(
@@ -551,21 +585,6 @@ class ScaleStyle(ScaleDomainValidationMixin):
             "date/datetime strings."
         ),
     )
-    base: float | None = Field(
-        default=None,
-        description=(
-            "Log base; only meaningful with type: log. None lets Vega-Lite "
-            "apply its own default (10)."
-        ),
-    )
-    exponent: float | None = Field(
-        default=None,
-        description="Power exponent; only meaningful with type: pow. None uses Vega-Lite's default.",
-    )
-    constant: float | None = Field(
-        default=None,
-        description="Symlog constant; only meaningful with type: symlog. None uses Vega-Lite's default.",
-    )
     domain_strategy: Literal["stable", "auto"] | None = Field(
         default=None,
         description=(
@@ -574,10 +593,82 @@ class ScaleStyle(ScaleDomainValidationMixin):
             "the domain to the chart query's full unfiltered extent — the same "
             "value lands at the same pixel across variable changes. 'auto' "
             "rescales the domain to the current filtered subset on every variable "
-            "change. An explicit `domain` always wins over "
-            "either strategy."
+            "change. An explicit `domain` always wins over either strategy."
         ),
     )
+    log: ScaleLogStyle | None = Field(
+        default=None,
+        description="Log-scale param (base); only meaningful with type: log.",
+    )
+    pow: ScalePowStyle | None = Field(
+        default=None,
+        description="Power-scale param (exponent); only meaningful with type: pow.",
+    )
+    symlog: ScaleSymlogStyle | None = Field(
+        default=None,
+        description="Symlog-scale param (constant); only meaningful with type: symlog.",
+    )
+
+    # NOT on ScaleDomainValidationMixin: unlike domain shape, this pairing can
+    # legitimately span two cascade layers (a theme sets type: log, a chart
+    # overlay sets only log.base) — merge_onto_base re-validates the fully-merged
+    # ScaleContinuousStyle via model_validate, so this fires on the merged
+    # result, not on an isolated authored patch fragment (the generated Patch
+    # does not inherit it — it is defined directly here, not on a mixin).
+    @model_validator(mode="after")
+    def _validate_log_pow_symlog_params(self) -> ScaleContinuousStyle:
+        if self.log is not None and self.log.base is not None and self.type != "log":
+            raise ValueError(
+                "scale.continuous.log.base is only meaningful with type: log — "
+                "set axis_y.scale.continuous.type: log, or remove log.base."
+            )
+        if (
+            self.pow is not None
+            and self.pow.exponent is not None
+            and self.type != "pow"
+        ):
+            raise ValueError(
+                "scale.continuous.pow.exponent is only meaningful with type: pow "
+                "— set axis_y.scale.continuous.type: pow, or remove pow.exponent."
+            )
+        if (
+            self.symlog is not None
+            and self.symlog.constant is not None
+            and self.type != "symlog"
+        ):
+            raise ValueError(
+                "scale.continuous.symlog.constant is only meaningful with type: "
+                "symlog — set axis_y.scale.continuous.type: symlog, or remove "
+                "symlog.constant."
+            )
+        if self.type == "log" and self.zero is True:
+            raise ValueError(
+                "scale.continuous.type: log is incompatible with zero: true — a log "
+                "domain cannot include 0. Remove zero or drop the log scale."
+            )
+        return self
+
+
+class BaseScaleStyle(BaseModel):
+    """Universal + continuous-only scale config.
+
+    Channel-agnostic — used at chart-level ``scale:`` (applies to both x and y)
+    and at ``axis_y.scale``. band/point/quantize/mark_size scale config was
+    deleted (2026-08 trim): no chart currently needs it, and it more than
+    doubled the authoring surface for zero real use. Rely on Vega-Lite's own
+    defaults until a real need for those knobs shows up.
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    round: bool | None = Field(
+        default=None,
+        description="Round scale outputs to nearest integer; None uses Vega-Lite's default (no rounding).",
+    )
+    clamp: bool | None = Field(
+        default=None,
+        description="Clamp values to scale domain; None uses Vega-Lite's default (no clamping).",
+    )
     nice: bool | None = Field(
         default=None,
         description="Round scale domain to nice values; None uses Vega-Lite's default.",
@@ -604,36 +695,34 @@ class ScaleStyle(ScaleDomainValidationMixin):
             "Ignored with an explicit `domain` or `stack: normalize`."
         ),
     )
+    # Explicit tick values for the scale (not to be confused with
+    # labels.values, which is a dimension-only label density filter on
+    # DimensionLabelStyle). Moved in from the old BaseAxisStyle.values.
+    values: Annotated[list[Any] | None, Merge(Strategy.OVERRIDE)] = Field(
+        default=None,
+        description="Explicit tick values; None uses Vega-Lite's auto tick values.",
+    )
+    continuous: ScaleContinuousStyle | None = Field(
+        default=None,
+        description="Continuous-scale overrides (type, domain, zero, log/pow/symlog params); None means no override.",
+    )
 
-    # NOT on ScaleDomainValidationMixin: unlike domain shape, this pairing can
-    # legitimately span two cascade layers (a theme sets type: log, a chart
-    # overlay sets only base) — merge_onto_base re-validates the fully-merged
-    # ScaleStyle via model_validate, so this fires on the merged result, not
-    # on an isolated authored patch fragment (ScaleStylePatch deliberately
-    # does not inherit it).
-    @model_validator(mode="after")
-    def _validate_log_pow_symlog_params(self) -> ScaleStyle:
-        if self.base is not None and self.type != "log":
-            raise ValueError(
-                "scale.base is only meaningful with type: log — set "
-                "axis_y.scale.type: log, or remove base."
-            )
-        if self.exponent is not None and self.type != "pow":
-            raise ValueError(
-                "scale.exponent is only meaningful with type: pow — set "
-                "axis_y.scale.type: pow, or remove exponent."
-            )
-        if self.constant is not None and self.type != "symlog":
-            raise ValueError(
-                "scale.constant is only meaningful with type: symlog — set "
-                "axis_y.scale.type: symlog, or remove constant."
-            )
-        if self.type == "log" and self.zero is True:
-            raise ValueError(
-                "scale.type: log is incompatible with zero: true — a log "
-                "domain cannot include 0. Remove zero or drop the log scale."
-            )
-        return self
+
+class XScaleStyle(BaseScaleStyle):
+    """Scale config for axis_x.scale only.
+
+    x_reverse is structurally absent from BaseScaleStyle so the model rejects
+    it on axis_y.scale and chart-level scale: at validation time, closing the
+    silent-leak bug where x_reverse on a chart-level scale reached VL's y-scale
+    via the old flat SCALE_FIELD_MAP.
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    x_reverse: bool | None = Field(
+        default=None,
+        description="Reverse the x-axis scale direction; None means no reversal.",
+    )
 
 
 class TooltipSlotStyle(BaseModel):
@@ -784,107 +873,77 @@ class AxisMirrorStyle(BaseModel):
         return self
 
 
-class AxisStyle(BaseModel):
+class BaseAxisStyle(BaseModel):
+    """Universal axis surface — grid/line/ticks/labels/title/scale.
+
+    Channel-agnostic: used for the theme's ``axis:`` slot (applies to all axes)
+    and for AxisXStyle/AxisYStyle/QuantitativeAxisStyle/BandAxisStyle subclasses.
+    Dimension-only and measure-only fields live on the appropriate subclass so
+    the model rejects them at validation time rather than requiring scattered
+    runtime checks. No ``position`` here — AxisXStyle/AxisYStyle each declare
+    their own narrowed literal; axis_quantitative/axis_band have no position
+    concept of their own.
+    """
+
     model_config = ConfigDict(extra="forbid", frozen=True)
 
-    grid: AxisGridStyle = Field(
-        default_factory=AxisGridStyle, description="Grid line style for this axis."
+    grid: BaseAxisGridStyle = Field(
+        default_factory=BaseAxisGridStyle,
+        description="Grid line style for this axis.",
     )
-    domain: AxisDomainStyle = Field(
-        default_factory=AxisDomainStyle, description="Domain line style for this axis."
+    line: AxisLineStyle = Field(
+        default_factory=AxisLineStyle, description="Domain line style for this axis."
     )
     ticks: AxisTicksStyle = Field(
         default_factory=AxisTicksStyle, description="Tick mark style for this axis."
     )
-    label: AxisElementStyle = Field(
-        default_factory=AxisElementStyle, description="Axis label style."
+    labels: AxisLabelStyle = Field(
+        default_factory=AxisLabelStyle, description="Axis label style."
     )
-    title: AxisElementStyle = Field(
-        default_factory=AxisElementStyle, description="Axis title style."
+    title: AxisTitleStyle = Field(
+        default_factory=AxisTitleStyle, description="Axis title style."
     )
-    # ── Fields excluded from slot expansion (not inherited across axis variants) ───────
-    # These fields are per-axis-variant values; child axes do not inherit them
-    # from the canonical axis.  SkipInheritSlots prevents InheritSlot expansion
-    # via the axis_x/y/quantitative slot from adding incorrect graph entries.
-
-    # "auto" → "right" by default; flips to "left" when chart has right-edge
-    # series labels (e.g. line endpoint labels). VL passthrough for explicit values.
-    position: Annotated[
-        Literal["left", "right", "top", "bottom", "auto"] | None, SkipInheritSlots()
-    ] = Field(
-        default=None,
-        description="Axis position; auto flips y-axis when endpoint labels are present.",
-    )
-    # Only populated on axis_y in theme YAML; None on shared/x/quantitative/band
-    # axes means "skip this VL property" matching the VL config emit layer.
-    categorical_orient: Annotated[str | None, SkipInheritSlots()] = Field(
-        default=None,
-        description="Orientation for categorical y-axis (e.g. 'left'); None skips this VL property.",
+    # SkipInheritSlots: scale is not inherited — axis family variants each own their scale config.
+    scale: Annotated[BaseScaleStyle | None, SkipInheritSlots()] = Field(
+        default=None, description="Per-axis scale overrides; None means no override."
     )
-    # Only meaningful on the y (measure) axis; the renderer consumes it only for
-    # axis_y (mirroring x doesn't make sense). None/False = single edge. An
-    # AxisMirrorStyle object still turns mirroring on (truthy) and additionally
-    # relabels the mirrored edge; see AxisMirrorStyle.
-    mirror: Annotated[bool | AxisMirrorStyle | None, SkipInheritSlots()] = Field(
-        default=None,
-        description="Draw the y-scale on both left and right edges (wide charts). "
-        "true mirrors the primary axis's label verbatim; an object (format/expr) "
-        "relabels only the mirrored edge — e.g. a percent-of-total right axis "
-        "next to an absolute-value left axis — while ticks stay aligned to the "
-        "single shared scale. Only meaningful on axis_y.",
+
+
+class AxisXStyle(BaseAxisStyle):
+    """Dimension/category-time axis style. Theme slot: axis_x.
+
+    Adds dimension-only fields: fill (required — theme supplies via axis_x.fill),
+    time_unit (bucketing), type (ordinal/temporal discriminant), and overrides
+    ticks/labels with DimensionTicksStyle/DimensionLabelStyle.
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    # Override base's ticks type to add step-anchored cadence's unit field.
+    ticks: DimensionTicksStyle = Field(
+        default_factory=DimensionTicksStyle, description="Dimension axis tick style."
     )
-    band_position: Annotated[float | None, SkipInheritSlots()] = Field(
-        default=None,
-        description="Band position within the step (0–1); None uses Vega-Lite's default.",
+    # Override base's labels type to add dimension-only label fields.
+    labels: DimensionLabelStyle = Field(
+        default_factory=DimensionLabelStyle, description="Dimension axis label style."
     )
-    offset: Annotated[float | None, SkipInheritSlots()] = Field(
+    position: Annotated[Literal["top", "bottom"] | None, SkipInheritSlots()] = Field(
         default=None,
-        description="Pixel offset of the axis from its default position; None means no offset.",
-    )
-    # Encoding-level passthrough: applied to encoding.y.axis, not config.axis
-    format: Annotated[str | None, SkipInheritSlots()] = Field(
-        default=None, description="Tick value format string; None uses auto-format."
+        description="X-axis position; None uses Vega-Lite's default (bottom).",
     )
-    values: Annotated[
-        list[Any] | None, SkipInheritSlots(), Merge(Strategy.OVERRIDE)
-    ] = Field(
+    # Override base's scale type to XScaleStyle so x_reverse can be authored here.
+    scale: Annotated[XScaleStyle | None, SkipInheritSlots()] = Field(
         default=None,
-        description="Explicit tick values; None uses Vega-Lite's auto tick values.",
+        description="X-axis scale overrides including x_reverse; None means no override.",
     )
     # Time-unit bucketing for temporal x axes (auto-detected when None or "auto").
     # "none" disables bucketing (continuous temporal). VL timeUnit values otherwise.
-    time_unit: Annotated[
-        Literal[
-            "auto",
-            "year",
-            "yearquarter",
-            "yearmonth",
-            "yearweek",
-            "yearmonthdate",
-            "monthofyear",
-            "dayofweek",
-            "dayofmonth",
-            "dayofyear",
-            "hourofday",
-            "none",
-        ]
-        | None,
-        SkipInheritSlots(),
-    ] = Field(
+    time_unit: Annotated[_TIME_UNIT_LITERAL | None, SkipInheritSlots()] = Field(
         default=None,
         description="Time-unit bucketing for temporal x-axes; None or 'auto' auto-detects from data.",
     )
-    # Per-axis scale overrides — applied to encoding.{x,y}.scale, win over
-    # the chart-level ``style.scale`` when both are set.
-    # SkipInheritSlots: scale is not inherited — axis family variants each own their scale config.
-    scale: Annotated[ScaleStyle | None, SkipInheritSlots()] = Field(
-        default=None, description="Per-axis scale overrides; None means no override."
-    )
-
-    # Authored opt-in scale type for bucketed-time x-axes (axis_x only).
-    # None/"auto" = ordinal when time_unit resolves to a bucketed-calendar
-    # grain, temporal for continuous date. "temporal" forces the temporal
-    # escape-hatch path. "ordinal" forces ordinal. Author always wins.
+    # Authored opt-in scale type for bucketed-time x-axes.
+    # None/"auto" = ordinal when time_unit resolves to a bucketed-calendar grain.
     type: Annotated[
         Literal["auto", "ordinal", "temporal"] | None, SkipInheritSlots()
     ] = Field(
@@ -892,11 +951,8 @@ class AxisStyle(BaseModel):
         description="Scale type for bucketed-time x-axes; None/'auto' infers from time_unit grain.",
     )
     # Fill mode for missing time buckets on ordinal bucketed-time x-axes.
-    # "null" → synthesized rows carry null measures; line/area breaks at gap.
-    # "zero" → synthesized rows carry 0 measures; event-count charts opt in.
-    # linear / step-* / curve → fill interior synthetic buckets (Looker-aligned names).
     # Required; theme YAML supplies the default ("null") via axis_x.fill.
-    # SkipInheritSlots: fill is per-axis-variant; always non-None (validator converts None→"null").
+    # SkipInheritSlots: fill is x-axis-only; always non-None (validator converts None→"null").
     fill: Annotated[
         Literal[
             "null",
@@ -919,11 +975,11 @@ class AxisStyle(BaseModel):
     # 1 (January) is the calendar-quarter convention; any other value shifts
     # both the bucket boundaries (_enumerate_buckets) and the Q1..Q4 numbering
     # / year-boundary detection (is_label_opener, opens_label_period,
-    # _quarter_label) by the same offset. Required (like fill) since the model
-    # enforces it on every axis variant; semantically only active on axis_x
-    # for the year/yearquarter grains — yearmonth/yearweek/yearmonthdate
-    # bucket boundaries are fixed regardless of this value.
-    # SkipInheritSlots: per-axis-variant, matches fill/time_unit/type.
+    # _quarter_label) by the same offset. Required (like fill) — theme YAML
+    # supplies the default (1) via axis_x.fiscal_year_start_month. Only
+    # meaningful for the year/yearquarter grains — yearmonth/yearweek/
+    # yearmonthdate bucket boundaries are fixed regardless of this value.
+    # SkipInheritSlots: matches fill/time_unit/type (x-axis-only fields).
     fiscal_year_start_month: Annotated[int, SkipInheritSlots()] = Field(
         description=(
             "Calendar month (1=Jan..12=Dec) that opens a fiscal year/quarter "
@@ -952,3 +1008,67 @@ class AxisStyle(BaseModel):
         if value is None:
             return "null"
         return value
+
+
+class AxisYStyle(BaseAxisStyle):
+    """Measure axis style. Theme slot: axis_y.
+
+    Adds measure-only fields: mirror; overrides grid with MeasureGridStyle
+    (adds grid.zero). x-axis-only fields (fill, time_unit, type,
+    tilt_increments, labels.values) are structurally absent so the model
+    rejects them at validation time.
+
+    No ``categorical_orient`` (deleted 2026-08 trim) — ``position`` (below)
+    now serves the "which side does this axis's orient read as" role for
+    every consumer, dimension-swap-into-VL-y included.
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    # Override base's grid type to add grid.zero (measure axis only).
+    grid: MeasureGridStyle = Field(
+        default_factory=MeasureGridStyle,
+        description="Measure axis grid style (includes zero-baseline override).",
+    )
+    position: Annotated[Literal["left", "right", "auto"] | None, SkipInheritSlots()] = (
+        Field(
+            default=None,
+            description="Y-axis position; auto flips when endpoint labels are on the right.",
+        )
+    )
+    # y-axis only: draw the y-scale on both edges.
+    mirror: Annotated[bool | AxisMirrorStyle | None, SkipInheritSlots()] = Field(
+        default=None,
+        description=(
+            "Draw the y-scale on both left and right edges (wide charts). "
+            "true mirrors the primary axis's label verbatim; an object (format/expr) "
+            "relabels only the mirrored edge — e.g. a percent-of-total right axis "
+            "next to an absolute-value left axis — while ticks stay aligned to the "
+            "single shared scale. Only meaningful on axis_y."
+        ),
+    )
+
+
+class QuantitativeAxisStyle(BaseAxisStyle):
+    """Scale-type overlay for quantitative axes. Theme slot: axis_quantitative.
+
+    Thin today (no extra fields beyond BaseAxisStyle). Subclassed to give
+    quantitative-axis patches a distinct type so AxisOverrides can be precisely
+    typed per slot.
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+
+class BandAxisStyle(BaseAxisStyle):
+    """Scale-type overlay for band (categorical) axes. Theme slot: axis_band.
+
+    Adds band_position — structurally absent from all other variants.
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    band_position: Annotated[float | None, SkipInheritSlots()] = Field(
+        default=None,
+        description="Band position within the step (0–1); None uses Vega-Lite's default.",
+    )