dataface 0.4.1.dev32__py3-none-any.whl → 0.4.1.dev53__py3-none-any.whl

dataface/agent_api/diagnostics.py

@@ -36,9 +36,10 @@ __all__ = [
     "DiagnosticCodeDetail",
     "DiagnosticCodesListResult",
     "DiagnosticCodeDetailResult",
+    "DiagnosticDisplay",
     "list_diagnostic_codes",
     "get_diagnostic_code",
-    "doc_url_map",
+    "display_map",
 ]
 
 # ----- Args types ------------------------------------------------------------
@@ -77,6 +78,20 @@ class DiagnosticCodeSummary(BaseModel):
     model_config = ConfigDict(extra="forbid", frozen=True)
 
 
+class DiagnosticDisplay(BaseModel):
+    """Registry-derived presentation data for one code, shipped per page.
+
+    Both fields are derived DiagnosticCode properties rather than serialized
+    Diagnostic fields, so a display surface resolves them from the code it
+    already has instead of receiving them on every payload.
+    """
+
+    title: str
+    doc_url: str
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+
 class DiagnosticCodeDetail(BaseModel):
     """Full details for a single diagnostic code."""
 
@@ -207,11 +222,14 @@ def get_diagnostic_code(code: str) -> DiagnosticCodeDetailResult:
     )
 
 
-def doc_url_map() -> dict[str, str]:
-    """The registry's code -> doc_url map, built once for embedding alongside a page.
+def display_map() -> dict[str, DiagnosticDisplay]:
+    """The registry's code -> display map, built once for embedding alongside a page.
 
-    doc_url is a derived DiagnosticCode property, never an authored/serialized
-    field — Cloud and Playground each ship this map once rather than
-    re-deriving or hand-formatting a URL per diagnostic.
+    `title` and `doc_url` are derived DiagnosticCode properties, never
+    authored/serialized Diagnostic fields — Cloud and Playground each ship this
+    map once rather than re-deriving a URL or restating a title per diagnostic.
     """
-    return {dc.code: dc.doc_url for dc in REGISTRY.all()}
+    return {
+        dc.code: DiagnosticDisplay(title=dc.title, doc_url=dc.doc_url)
+        for dc in REGISTRY.all()
+    }

dataface/agent_api/docs/yaml-reference.md

@@ -1894,14 +1894,14 @@ Authored overlay for BlockMarginStyle. Top and bottom margin for a prose block r
 
 <a id="textcolumnstyle"></a>
 ## TextColumnStyle
-Authored overlay for TextColumnStyle. Multi-column layout for face body text (CSS column-count/gap/rule/max_chars).
+Authored overlay for TextColumnStyle. Author overrides for the column layout of face body text.
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
-| `number` | int | ✓ | Fixed column count. None = single column. |
-| `gap` | float | ✓ | Gap between columns in pixels. None = use layout gap token. |
+| `number` | int | ✓ | Ceiling on the column count. The renderer may choose fewer when there is not enough text to fill them. None = no ceiling. |
+| `gap` | float | ✓ | Gap between columns in pixels. None = 1.5 line boxes, so the gutter scales with the type it separates. |
 | `rule` | str | ✓ | CSS column-rule shorthand, e.g. '1px solid #e5e7eb'. None = no rule. |
-| `max_chars` | int | ✓ | Target column width as a character count. The pixel width is derived at render time via fonttools OS/2.xAvgCharWidth × max_chars; column count auto-derives as ceil(available / col_width_px). |
+| `max_chars` | int | ✓ | Column width as a character count, overriding the shipped measure. The width is used exactly and the column count follows from it. |
 
 <a id="textcodestyle"></a>
 ## TextCodeStyle
@@ -2335,7 +2335,6 @@ Authored overlay for ScaleContinuousStyle. Continuous-scale-only config: type, d
 | `zero` | bool \| enum: "auto" | ✓ | Force scale zero-baseline: True/False pins it; "auto" runs the Dataface smart-zero heuristic; None passes through to Vega-Lite. |
 | `type` | enum: "linear", "log", "pow", "sqrt", "symlog", "temporal" | ✓ | Scale type override. 'linear'/'log'/'pow'/'sqrt'/'symlog' pass straight through to Vega-Lite's quantitative scale.type. 'temporal' is a Dataface escape hatch for a cartesian x-axis: it forces a continuous temporal scale instead of the auto-inferred ordinal/nominal bucketed type, which is required before an authored ``domain`` of ISO dates can extend the visible range past the data extent. None lets Dataface/Vega-Lite infer from the field type. |
 | `domain` | list[Any] | ✓ | Explicit [low, high] scale domain; None lets Vega-Lite auto-determine from data. Must have exactly 2 elements — Dataface only wires a continuous range override through to Vega-Lite, not an explicit category enumeration. When ``type: temporal`` is set, both elements must be ISO-8601 date/datetime strings. |
-| `domain_strategy` | enum: "stable", "auto" | ✓ | How the numeric domain responds to filter-variable changes when no explicit `domain` is authored. 'stable' (the default when None) pins 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. |
 | `log` | [ScaleLogStyle](#scalelogstyle) | ✓ | Log-scale param (base); only meaningful with type: log. |
 | `pow` | [ScalePowStyle](#scalepowstyle) | ✓ | Power-scale param (exponent); only meaningful with type: pow. |
 | `symlog` | [ScaleSymlogStyle](#scalesymlogstyle) | ✓ | Symlog-scale param (constant); only meaningful with type: symlog. |

dataface/core/compile/chart_update.py

@@ -36,13 +36,10 @@ Usage:
     )
 """
 
-import logging
 from typing import Any
 
 import yaml
 
-logger = logging.getLogger(__name__)
-
 
 def update_chart_in_yaml(
     yaml_content: str,
@@ -147,6 +144,25 @@ def update_chart_in_yaml(
         if field in edits and edits[field]:
             chart_def[field] = edits[field]
 
+    # Validate rewritability before any mutation.
+    # A rows/cols source_path must be exactly two segments (layout_key.N) where N
+    # is a digit — that is the only shape _update_layout_reference can rewrite.
+    # Deeper paths (rows.0.cols.1) name a chart inside a nested face; the nested
+    # face's own file must name the chart instead.
+    if source_path and source_path.split(".")[0] in ("rows", "cols"):
+        _segs = source_path.split(".")
+        if len(_segs) != 2:
+            raise ValueError(
+                f"Cannot promote inline chart at '{source_path}': only top-level "
+                "layout positions (rows.N / cols.N) are supported; name the chart "
+                "in the nested face's own file instead"
+            )
+        if not _segs[1].isdigit():
+            raise ValueError(
+                f"Cannot promote inline chart at '{source_path}': "
+                f"'{_segs[1]}' is not a valid integer index"
+            )
+
     # Update the charts section
     # If chart already exists, merge with existing values
     if chart_id in data["charts"]:
@@ -171,31 +187,19 @@ def update_chart_in_yaml(
 def _update_layout_reference(
     data: dict[str, Any], source_path: str, chart_id: str
 ) -> None:
-    """Update a layout position to reference a named chart instead of inline.
+    """Replace an inline chart at a top-level layout position with a named reference.
 
     Args:
         data: Parsed YAML data (modified in place)
-        source_path: Path like "rows.0" or "rows.0.cols.1"
+        source_path: Validated path of the form "rows.N" or "cols.N".
+            Caller guarantees exactly two segments and a digit index.
         chart_id: ID of the chart to reference
     """
-    # Only a top-level position is rewritable here: this replaces an entry in
-    # `data[layout_key]`, and a deeper path (`rows.0.cols.1`) names an entry in a
-    # nested face's own list, which this function never walks into.
-    segments = source_path.split(".")
-    if len(segments) != 2 or segments[0] not in ("rows", "cols"):
-        logger.debug(f"Unrecognized source_path format: {source_path}")
-        return
-    layout_key, raw_index = segments
-    if not raw_index.isdigit():
-        logger.warning(f"Failed to parse index from source_path: {source_path}")
-        return
+    layout_key, raw_index = source_path.split(".")
     index = int(raw_index)
-
-    # Update the layout
     if (
         layout_key in data
         and isinstance(data[layout_key], list)
         and 0 <= index < len(data[layout_key])
     ):
-        # Replace inline chart with named reference
         data[layout_key][index] = chart_id

dataface/core/compile/migrations/versions/v0_4_0.py

@@ -8,10 +8,11 @@ leaf move creates its destination container on demand, and the later
 container move must find that destination still empty (or absent) to avoid
 a spurious MigrationConflictError against an unrelated field that also sets
 the old container. See dataface/AGENTS.md's "Two validation boundaries" —
-these are structural moves; categorical_orient (deleted), ticks.interval
-(reinterpreted vocabulary, not renamed), and the band/point/quantize scale
-groups (deleted) are semantic changes with no lossless move and are left to
-raise UnsupportedSchemaError for manual migration.
+these are structural moves; categorical_orient (deleted), the stable-axis
+domain-strategy key (deleted), ticks.interval (reinterpreted vocabulary, not
+renamed), and the band/point/quantize scale groups (deleted) are semantic
+changes with no lossless move and are left to raise UnsupportedSchemaError for
+manual migration.
 """
 
 from __future__ import annotations
@@ -29,7 +30,6 @@ RENAMES: tuple[tuple[YamlKeyPath, YamlKeyPath], ...] = (
     (("scale", "continuous", "domain"), ("scale", "domain")),
     (("scale", "continuous", "zero"), ("scale", "zero")),
     (("scale", "continuous", "type"), ("scale", "type")),
-    (("scale", "continuous", "domain_strategy"), ("scale", "domain_strategy")),
     (("scale", "continuous", "log", "base"), ("scale", "base")),
     (("scale", "continuous", "pow", "exponent"), ("scale", "exponent")),
     (("scale", "continuous", "symlog", "constant"), ("scale", "constant")),

dataface/core/compile/models/config.py

@@ -162,6 +162,22 @@ class ChartRenderingConfig(ConfigNode):
         footer_rule_gap_px: int
         footer_timestamp_gap_px: int
 
+    class ProseConfig(ConfigNode):
+        target_chars: int
+        single_column_chars: int
+        min_chars: int
+        max_chars: int
+        min_lines_per_column: int
+        max_columns: int
+        gutter_line_boxes: float
+        orphan_penalty: float
+        widow_penalty: float
+        interior_break_penalty: float
+        block_break_penalty: float
+        balance_weight: float
+        balance_scale: float
+        balance_undershoot: float
+
     class DataTableConfig(ConfigNode):
         divider_gap: float
         chart_data_table_max_x_ticks: int
@@ -174,6 +190,7 @@ class ChartRenderingConfig(ConfigNode):
     bar: BarConfig
     type_inference: TypeInferenceConfig
     board: BoardConfig
+    prose: ProseConfig
     data_table: DataTableConfig
     stroke: StrokeConfig
     axis: AxisConfig

dataface/core/compile/models/style/resolved/_base.py

@@ -201,7 +201,6 @@ class ResolvedScaleContinuousStyle(BaseModel):
     zero: bool | Literal["auto"] | None = None
     type: Literal["linear", "log", "pow", "sqrt", "symlog", "temporal"] | None = None
     domain: list[Any] | None = None
-    domain_strategy: Literal["stable", "auto"] | None = None
     log: ResolvedScaleLogStyle | None = None
     pow: ResolvedScalePowStyle | None = None
     symlog: ResolvedScaleSymlogStyle | None = None

dataface/core/compile/models/style/resolved/_cascade.py

@@ -572,7 +572,6 @@ def build_resolved_scale(
                 zero=scale.continuous.zero,
                 type=scale.continuous.type,
                 domain=scale.continuous.domain,
-                domain_strategy=scale.continuous.domain_strategy,
                 log=(
                     ResolvedScaleLogStyle(base=scale.continuous.log.base)
                     if scale.continuous.log is not None

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

@@ -104,7 +104,6 @@ from dataface.core.compile.models.style.theme.board import (
     TitleWidthOffsetsStyle,
     _normalize_overflow_value,
     coerce_gap,
-    compute_text_column_count,
     font_weight_as_css,
 )
 from dataface.core.compile.models.style.theme.callout import (
@@ -414,6 +413,5 @@ __all__ = [
     "_RadialChartStyle",
     "_normalize_overflow_value",
     "coerce_gap",
-    "compute_text_column_count",
     "font_weight_as_css",
 ]

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

@@ -585,17 +585,6 @@ class ScaleContinuousStyle(ScaleDomainValidationMixin):
             "date/datetime strings."
         ),
     )
-    domain_strategy: Literal["stable", "auto"] | None = Field(
-        default=None,
-        description=(
-            "How the numeric domain responds to filter-variable changes when no "
-            "explicit `domain` is authored. 'stable' (the default when None) pins "
-            "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."
-        ),
-    )
     log: ScaleLogStyle | None = Field(
         default=None,
         description="Log-scale param (base); only meaningful with type: log.",

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

@@ -68,26 +68,35 @@ _COLUMN_RULE_HEX_RE = re.compile(
 
 
 class TextColumnStyle(BaseModel):
-    """Multi-column layout for face body text (CSS column-count/gap/rule/max_chars).
+    """Author overrides for the column layout of face body text.
 
-    Two orthogonal controls:
-    - ``number``: fixed column count. None = not set.
-    - ``max_chars``: target column width as a character count. When set, the
-      pixel width is derived at render time via fonttools OS/2.xAvgCharWidth,
-      and column count auto-derives as ``ceil(available / col_width_px)``.
+    Body text is measured and flowed whether or not any of these are set: the
+    renderer picks a column count whose measure reads well, and how much text
+    there is decides how many of those columns are worth using. These narrow
+    that choice rather than switching it on.
 
-    When both are set, ``number`` acts as a ceiling on the auto-derived count.
-    When neither is set, text renders as a single column.
+    - ``number``: ceiling on the count. The renderer may still choose fewer,
+      when the text is too short to fill them.
+    - ``max_chars``: the measure itself, overriding the shipped default. The
+      width is used exactly and the count follows from it.
     """
 
     model_config = ConfigDict(extra="forbid", frozen=True)
 
     number: int | None = Field(
-        default=None, ge=1, description="Fixed column count. None = single column."
+        default=None,
+        ge=1,
+        description=(
+            "Ceiling on the column count. The renderer may choose fewer when there "
+            "is not enough text to fill them. None = no ceiling."
+        ),
     )
     gap: float | None = Field(
         default=None,
-        description="Gap between columns in pixels. None = use layout gap token.",
+        description=(
+            "Gap between columns in pixels. None = 1.5 line boxes, so the gutter "
+            "scales with the type it separates."
+        ),
     )
     rule: str | None = Field(
         default=None,
@@ -97,9 +106,8 @@ class TextColumnStyle(BaseModel):
         default=None,
         gt=0,
         description=(
-            "Target column width as a character count. The pixel width is derived at "
-            "render time via fonttools OS/2.xAvgCharWidth × max_chars; column count "
-            "auto-derives as ceil(available / col_width_px)."
+            "Column width as a character count, overriding the shipped measure. "
+            "The width is used exactly and the column count follows from it."
         ),
     )
 
@@ -134,60 +142,6 @@ class TextColumnStyle(BaseModel):
             )
         return v
 
-    @model_validator(mode="after")
-    def _validate_column_settings(self) -> TextColumnStyle:
-        multi = (
-            self.number is not None and self.number > 1
-        ) or self.max_chars is not None
-        if self.gap is not None and not multi:
-            raise ValueError(
-                "column.gap requires column.number > 1 or column.max_chars"
-            )
-        if self.rule is not None and not multi:
-            raise ValueError(
-                "column.rule requires column.number > 1 or column.max_chars"
-            )
-        return self
-
-    @property
-    def has_overrides(self) -> bool:
-        """True when multi-column layout is configured."""
-        return (
-            self.number is not None and self.number > 1
-        ) or self.max_chars is not None
-
-
-def compute_text_column_count(
-    col: TextColumnStyle,
-    available_width: float,
-    col_width_px: float | None = None,
-) -> int:
-    """Auto-derive column count, with number as ceiling.
-
-    When ``col_width_px`` is provided (derived from max_chars × avg_char_width):
-      count = max(1, ceil(available / col_width_px)).
-    When only number is set: count = number.
-    When both are set: count = min(number, auto-derived).
-    When neither is set: single column.
-
-    ``col_width_px`` must be provided when col.max_chars is set; it is derived by
-    the caller via fonttools OS/2.xAvgCharWidth × max_chars × (font_size / upm).
-    """
-    import math
-
-    if col.max_chars is not None and col_width_px is None:
-        raise ValueError(
-            "col_width_px must be provided when col.max_chars is set — the "
-            "caller must derive it from max_chars before calling "
-            "compute_text_column_count."
-        )
-    if col_width_px is not None:
-        auto = max(1, math.ceil(available_width / col_width_px))
-        return min(col.number, auto) if col.number is not None else auto
-    if col.number is not None:
-        return col.number
-    return 1
-
 
 def coerce_gap(v: Any) -> float | None:
     """Coerce gap value from int, float, or CSS px string."""

dataface/core/compile/resolve/__init__.py

@@ -25,8 +25,8 @@ one-way: shared modules never import a family module, and no family module impor
 another family module — only `_dispatch` imports family modules.
 """
 
-from ._dispatch import needs_stable_y_domain, resolve
-from ._domain import StableYDomain, resolve_y_zero
+from ._dispatch import resolve
+from ._domain import resolve_y_zero
 from ._kwargs import (
     AutomaticLinkCandidate,
     default_chart_width,
@@ -42,11 +42,9 @@ from ._table import infer_pivot_measure_names
 
 __all__ = [
     "AutomaticLinkCandidate",
-    "StableYDomain",
     "auto_link_excludes_x",
     "default_chart_width",
     "infer_pivot_measure_names",
-    "needs_stable_y_domain",
     "preferred_chart_width",
     "resolve",
     "resolve_chart_display_title",

dataface/core/compile/resolve/_dispatch.py

@@ -5,13 +5,7 @@ from __future__ import annotations
 from collections.abc import Mapping, Sequence
 from types import EllipsisType
 
-from dataface.core.compile.models.chart.normalized import (
-    AreaChart,
-    BarChart,
-    Chart,
-    LineChart,
-    ScatterChart,
-)
+from dataface.core.compile.models.chart.normalized import Chart
 from dataface.core.compile.models.chart.resolved import (
     ResolvedChart,
 )
@@ -19,35 +13,21 @@ from dataface.core.compile.models.primitives import ResolvedFontStyle
 from dataface.core.compile.models.style.resolved import (
     ResolvedStyle,
 )
-from dataface.core.compile.resolve._axes import (
-    _bake_cartesian_axes,
-    _extract_axis_overrides,
-)
-from dataface.core.compile.resolve._channels import _classify_to_channel_type
 from dataface.core.compile.resolve._chart_rows import (
     ChartRows,
     LayerDatasets,
 )
-from dataface.core.compile.resolve._domain import (
-    StableYDomain,
-    _first_non_numeric_y,
-    _stable_domain_enabled,
-)
 from dataface.core.compile.resolve._kwargs import (
     _EMPTY_CHART_TEXT_VARIABLES,
     AutomaticLinkCandidate,
     ChartTextVariables,
     preferred_chart_width,
 )
-from dataface.core.compile.resolve._palette import _with_color_tokens
 from dataface.core.compile.resolve._table import (
     _EMPTY_TABLE_COLUMN_LINKS,
     _resolve_table,
 )
-from dataface.core.compile.resolve.area import (
-    _resolve_area,
-    _validate_area_encoding,
-)
+from dataface.core.compile.resolve.area import _resolve_area
 from dataface.core.compile.resolve.bar import (
     _resolve_bar,
     _resolve_histogram,
@@ -65,85 +45,18 @@ from dataface.core.compile.resolve.simple import (
     _resolve_kpi,
     _resolve_spark_bar,
 )
-from dataface.core.compile.style_cascade import (
-    build_resolved_style,
-)
 
 __all__ = [
-    "needs_stable_y_domain",
     "resolve",
 ]
 
 
-def needs_stable_y_domain(
-    normalized: Chart,
-    data: ChartRows,
-    board_style: ResolvedStyle,
-) -> bool:
-    """Whether runtime orchestration should gather a stable y extent.
-
-    This is a compile-owned pre-resolution decision: render may execute the
-    requested sibling queries, but it does not inspect style cascade results.
-    """
-    if not isinstance(normalized, (BarChart, LineChart, AreaChart, ScatterChart)):
-        return False
-    if normalized.type == "histogram" or not isinstance(normalized.y, str):
-        return False
-
-    board_rcs = board_style.charts
-    primary = _with_color_tokens(normalized.style, board_style)
-    charts_style = (
-        build_resolved_style(board_style, normalized)
-        if isinstance(normalized, (BarChart, LineChart, AreaChart))
-        else board_rcs
-    )
-    x_channel_type = _classify_to_channel_type(normalized.x, data, is_dimension=True)
-    if isinstance(normalized, ScatterChart):
-        y_channel_type = _classify_to_channel_type(
-            normalized.y, data, is_dimension=False
-        )
-        if y_channel_type != "quantitative":
-            return False
-    elif isinstance(normalized, AreaChart):
-        resolved_stack = (
-            normalized.stack
-            if normalized.stack is not None
-            else charts_style.area.stack
-        )
-        _validate_area_encoding(normalized, data, x_channel_type, resolved_stack)
-        y_channel_type = "quantitative"
-    else:
-        if _first_non_numeric_y(normalized.y, data) is not None:
-            return False
-        y_channel_type = "quantitative"
-    _, ay, _, _ = _bake_cartesian_axes(
-        charts_style,
-        normalized,
-        normalized.type,
-        x_channel_type,
-        y_channel_type,
-        _extract_axis_overrides(primary, normalized.x_label, normalized.y_label),
-        multiples=normalized.multiples,
-        y=normalized.y,
-    )
-    if not _stable_domain_enabled(ay):
-        return False
-    if isinstance(normalized, BarChart):
-        stack = (
-            normalized.stack if normalized.stack is not None else charts_style.bar.stack
-        )
-        if stack == "normalize":
-            return False
-    return True
-
-
 def resolve(
     normalized: Chart,
     data: ChartRows,
     board_style: ResolvedStyle,
     width: float | None = None,
     datasets: LayerDatasets = ...,
-    stable_y_domain: StableYDomain | EllipsisType = ...,
     automatic_link_candidate: AutomaticLinkCandidate = None,
     table_column_links: Mapping[str, str] = _EMPTY_TABLE_COLUMN_LINKS,
     table_column_rows: Sequence[Mapping[str, str]] = (),
@@ -164,8 +77,6 @@ def resolve(
             needs a concrete width; other families retain the board-level default.
         datasets: Query-name keyed rows for own-query overlay layers. Callers without
             an executor may omit it; same-query layers still resolve from ``data``.
-        stable_y_domain: Query-derived extent gathered by runtime
-            orchestration after ``needs_stable_y_domain()`` requests it.
         automatic_link_candidate: Executor-derived root-link candidate. Authored
             links retain precedence during construction.
         table_column_links: Executor-derived FK-link candidates by column name.
@@ -198,7 +109,6 @@ def resolve(
                 board_style,
                 effective_width,
                 datasets,
-                stable_y_domain,
                 automatic_link_candidate,
                 variables,
             )
@@ -218,7 +128,6 @@ def resolve(
                 board_style,
                 effective_width,
                 datasets,
-                stable_y_domain,
                 automatic_link_candidate,
                 variables,
             )
@@ -229,7 +138,6 @@ def resolve(
                 board_style,
                 effective_width,
                 datasets,
-                stable_y_domain,
                 automatic_link_candidate,
                 variables,
             )
@@ -240,7 +148,6 @@ def resolve(
                 board_style,
                 effective_width,
                 datasets,
-                stable_y_domain,
                 automatic_link_candidate,
                 variables,
             )