dataface 0.1.2__py3-none-any.whl

dataface/core/compile/typography.py

@@ -0,0 +1,299 @@
+"""DFT typographic system: title level, width offsets, sizes, weights, and family.
+
+A title's rendered size is determined by two orthogonal axes:
+
+  1. **Heading level** (``face.level``): the H-tag the title corresponds to.
+     Root face = 1 (H1), nested face = 2 (H2), chart title = parent face level + 1.
+
+  2. **Width offset**: an additive shift on the heading level based on card pixel
+     width.  Narrow cards "demote" a title one step down the size ramp; tiny cards
+     demote it further.  Offsets live in theme YAML under
+     ``style.title.width_offsets.*``.  Width breakpoints are engine constants here.
+
+Together they compute:
+    effective_level = clamp(level + width_offset(width), 1, len(sizes))
+    font_size = sizes[effective_level - 1]
+
+Width tiers and their default offsets:
+
+  tiny    (< 360px):                offset +3  / weight 600 (legibility floor)
+  narrow  (3–11 cols, 360–559px):   offset +1  / weight from config
+  medium  (12–23 cols, 560–1099px): offset  0  / weight from config
+  wide    (24 cols,    ≥ 1100px):   offset  0  / weight from config
+
+Font family rules (theme-driven; values below are per-theme):
+- Tiny + narrow chart titles always resolve to ``style.font.family`` (the body
+  family). On every shipped theme that's a sans family.
+- Medium + wide chart titles resolve to ``style.title.font.family`` (the
+  title-slot family). On ``stark`` this is also sans, so titles are sans at
+  every width. On the shipped ``default`` (and ``cream``) the title-slot
+  family is serif (Source Serif 4), so medium/wide chart titles render serif
+  while smaller cards stay sans for legibility.
+- Prose content and their titles: serif at any width, regardless of theme.
+  Prose is detected via ``is_prose(text)`` — true when word count ≥ 100.
+
+Page and section titles (face/board headers) always resolve to
+``style.font.family`` (sans on every shipped theme) at every width unless the
+face contains prose content.  Face titles clamp the width used for offset
+computation to the narrow boundary (≥ 360px) — a face header should never
+shrink below the narrow tier even on a narrow nested container.
+
+Chart labels (axis, legend, tick) are separately themed — not controlled here.
+
+Usage::
+
+    from dataface.core.compile.typography import chart_title_spec, face_title_spec
+
+    font_size, weight, family = chart_title_spec(
+        width, level=face_level + 1, resolved_chart_style=resolved_style.charts
+    )
+    font_size, weight, family = face_title_spec(width, level=face_level)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from dataface.core.compile.models.style.merged import MergedChartsStyle
+
+# ---------------------------------------------------------------------------
+# Pixel-width thresholds that separate the four width tiers.
+#
+# narrow/medium/wide approximate 11-col and 23-col boundaries for the default
+# 24-column, 1152px-content board (1200px total − 2 × 24px padding).
+# tiny catches sub-narrow charts (small-multiples, 5+ columns) where the flat
+# narrow size feels too large relative to chart width.
+# They are intentionally constant — column-grid geometry, not user preference.
+# Level offsets for each tier live in theme YAML under style.title.width_offsets.*.
+# ---------------------------------------------------------------------------
+
+_TINY_MAX: float = 360.0  # < 360px  → tiny
+_NARROW_MAX: float = 560.0  # 360–559px → narrow  (3–11 cols)
+_WIDE_MIN: float = 1100.0  # ≥ 1100px → wide    (24 cols)
+# 560–1099px             → medium  (12–23 cols)
+
+
+def width_tier(width: float) -> str:
+    """Return the tier name for a card's pixel width.
+
+    Single source of truth for the tier breakpoints — render-side
+    callers (e.g. donut-attached-table trigger) call this rather than
+    importing the module-private ``_TINY_MAX`` / ``_NARROW_MAX`` /
+    ``_WIDE_MIN`` constants.
+    """
+    if width < _TINY_MAX:
+        return "tiny"
+    if width < _NARROW_MAX:
+        return "narrow"
+    if width < _WIDE_MIN:
+        return "medium"
+    return "wide"
+
+
+# Tiny-tier weight floor. At small widths the theme's default weight (500)
+# reads as anemic; 600 is the legibility floor. Other tiers use
+# theme-configured weight.
+_TINY_WEIGHT: int = 600
+
+_PROSE_WORD_THRESHOLD = 100
+
+
+def _coerce_weight(raw: str | float | int) -> int | str:
+    """Return a CSS-valid font-weight value from FontStyle.weight.
+
+    FontStyle.weight is ``str | float | None``.  SVG and CSS both accept
+    numeric weights (int) and keyword weights (``"bold"``, ``"normal"``).
+    Cast numeric values to int so SVG emits ``font-weight="500"`` not
+    ``font-weight="500.0"``; leave string keywords unchanged.
+    """
+    if isinstance(raw, str):
+        return raw
+    return int(raw)
+
+
+def _width_offset(width: float, resolved_chart_style: MergedChartsStyle) -> int:
+    """Return the additive level offset for a card at the given pixel width.
+
+    Reads ``title.width_offsets`` from the active resolved style so face-local
+    theme overrides flow through. Width breakpoints are engine constants
+    (``_TINY_MAX``, ``_NARROW_MAX``, ``_WIDE_MIN``).
+
+    Args:
+        width: Pixel width of the card/chart.
+        resolved_chart_style: Active ``MergedChartsStyle`` for the face.
+
+    Returns:
+        Integer offset to add to the base heading level before indexing ``sizes``.
+    """
+    wo = resolved_chart_style.title.width_offsets
+    if width >= _WIDE_MIN:
+        return wo.wide
+    if width >= _NARROW_MAX:
+        return wo.medium
+    if width >= _TINY_MAX:
+        return wo.narrow
+    return wo.tiny
+
+
+def is_prose(text: str) -> bool:
+    """Return True if *text* qualifies as prose.
+
+    Prose is defined as body text with at least ``_PROSE_WORD_THRESHOLD`` words.
+    Prose content and its surrounding title render in serif at any card width.
+
+    Args:
+        text: Raw text content (Markdown or plain).
+
+    Returns:
+        ``True`` when the word count is ≥ 100.
+    """
+    return len(text.split()) >= _PROSE_WORD_THRESHOLD
+
+
+def chart_title_spec(
+    width: float,
+    *,
+    level: int,
+    resolved_chart_style: MergedChartsStyle,
+    use_title_family: bool | None = None,
+) -> tuple[int, int | str, str]:
+    """Return ``(font_size, font_weight, font_family)`` for a chart title.
+
+    Computes ``effective_level = clamp(level + width_offset(width), 1, len(sizes))``
+    then returns ``sizes[effective_level - 1]``.
+
+    Reads from the *active* resolved style passed in — not from
+    ``get_config()`` (the global default). That distinction is the whole point:
+    pre-fix the function was theme-blind and always returned the default
+    theme's families regardless of which theme the face actually used.
+
+    The resolved style has emoji families already baked into every
+    ``FontStyle.family`` by ``resolve_style``'s ``_append_emoji_family`` pass,
+    so no further emoji handling is needed here.
+
+    Level offsets per tier come from
+    ``resolved_chart_style.title.width_offsets.{tiny|narrow|medium|wide}``.
+    Font sizes come from ``resolved_chart_style.title.sizes`` (the H1–H6 ramp).
+
+    Family resolution by width tier:
+    - tiny + narrow → ``resolved_chart_style.font_family`` (body family — sans on
+      every shipped theme)
+    - medium + wide → ``resolved_chart_style.title.font.family`` (title-slot
+      family — sans on ``stark``, serif on the shipped ``default``/``cream``),
+      falling back to the body family when the title slot is unset.
+
+    Font weight comes from ``resolved_chart_style.title.font.weight`` for all
+    widths except tiny, which floors at 600 for legibility at small sizes.
+
+    Args:
+        width:  Pixel width of the chart card.
+        level:  Base heading level for this title (typically ``face.level + 1``
+                for chart titles).
+        resolved_chart_style:  Active ``MergedChartsStyle`` for the face. Produced
+                upstream by ``resolve_style(face_style).charts`` or
+                ``build_resolved_style(...).charts`` so face-local and
+                chart-local style patches are already merged in.
+        use_title_family:  ``True`` forces the title-slot family even on
+                narrow/tiny cards (so prose-tagged titles use serif at every
+                width on themes that define a serif title slot). ``False``
+                forces the body family at every width. ``None`` uses the
+                width default (title-slot family at medium/wide, body family
+                at narrow/tiny).
+
+    Returns:
+        ``(font_size_px, css_font_weight, css_font_family_string)``
+    """
+    sizes = resolved_chart_style.title.sizes
+    offset = _width_offset(width, resolved_chart_style)
+    effective_level = max(1, min(level + offset, len(sizes)))
+    font_size = int(sizes[effective_level - 1])
+
+    weight: int | str = (
+        _TINY_WEIGHT
+        if width < _TINY_MAX
+        else _coerce_weight(resolved_chart_style.title.font.weight or 500)
+    )
+
+    pick_title = (
+        (width >= _NARROW_MAX) if use_title_family is None else use_title_family
+    )
+    body = resolved_chart_style.font_family
+    assert body is not None, "resolved_chart_style.font_family must be populated"
+    title_family = resolved_chart_style.title.font.family
+    family = (title_family or body) if pick_title else body
+    return font_size, weight, family
+
+
+def face_title_spec(
+    width: float,
+    *,
+    level: int,
+) -> tuple[int, int | str, str]:
+    """Return ``(font_size, font_weight, font_family)`` for a face/page title.
+
+    Same logic as ``chart_title_spec`` but:
+    - The width used for offset computation is clamped to ``_TINY_MAX`` — a page
+      header should not shrink below the narrow tier even on a narrow container.
+    - Always returns sans (Inter) regardless of width.
+
+    Note: callers that render prose faces override the returned family to serif
+    by passing ``font_family=config.style.title.font.family`` to
+    ``get_compact_style``. The function itself is family-agnostic; the prose
+    exception lives in the render layer (see ``render_title`` in
+    ``render/svg_utils.py``).
+
+    Args:
+        width: Pixel width of the face/board.
+        level: Heading level for this face title (``face.level``).
+
+    Returns:
+        ``(font_size_px, css_font_weight, css_font_family_string)``
+    """
+    from dataface.core.compile.config import get_config
+    from dataface.core.compile.models.style.merged import apply_emoji_to_family
+
+    cfg = get_config()
+    sizes = cfg.style.title.sizes
+    wo = cfg.style.title.width_offsets
+    # Clamp tiny → narrow: face headers don't shrink below the narrow tier.
+    effective_width = max(width, _TINY_MAX)
+    if effective_width >= _WIDE_MIN:
+        offset = wo.wide
+    elif effective_width >= _NARROW_MAX:
+        offset = wo.medium
+    else:
+        offset = wo.narrow
+    effective_level = max(1, min(level + offset, len(sizes)))
+    font_size = int(sizes[effective_level - 1])
+
+    weight = _coerce_weight(cfg.style.title.font.weight or 500)
+    _root = cfg.style.font.family
+    assert _root is not None, "style.font.family must be configured"
+    _family = apply_emoji_to_family(_root, cfg.style.font.emoji)
+    return font_size, weight, _family
+
+
+def face_title_markdown(
+    title: str, width: float, *, level: int = 1
+) -> tuple[str, float, int | str]:
+    """Return ``(markdown, h1_size, font_weight)`` for a face title.
+
+    Formats the title as an h1 heading (``# title``). Callers pass ``h1_size``
+    to ``get_compact_style(h1_size=…)`` so the h1 renders at the exact pixel
+    size, and ``font_weight`` to ``heading_font_weight`` so the DFT weight tier
+    is applied. The pixel size comes from ``style.title.sizes`` indexed by the
+    effective level.
+
+    Args:
+        title: Title text (Jinja already resolved by the caller).
+        width: Pixel width of the face/board (drives width-offset selection).
+        level: Heading level for this face's title (``face.level``; default 1
+               for root faces).
+
+    Returns:
+        ``(markdown_string, h1_size, font_weight)`` — pass to
+        ``get_compact_style(h1_size=…, heading_font_weight=…)``.
+    """
+    font_size, weight, _family = face_title_spec(width, level=level)
+    return f"# {title}", float(font_size), weight

dataface/core/compile/validator.py

@@ -0,0 +1,301 @@
+"""Schema validation module.
+
+Stage: COMPILE (Step 2 of 4)
+Purpose: Validate AuthoredFace structure and cross-references.
+
+Entry Points:
+    - validate_face(face: AuthoredFace) -> List[ValidationError]
+
+Inputs:
+    - AuthoredFace (from parser)
+
+Outputs:
+    - List[ValidationError] (empty if valid)
+
+This validator focuses on semantic validation that Pydantic cannot handle:
+- Cross-reference validation (chart → query)
+- Layout item references (layout → chart)
+- Consistency checks between related fields
+
+Pydantic already handles:
+- Type validation
+- Required fields
+- Field constraints
+- Nested validation
+
+Dependencies:
+    - .types (AuthoredFace, Chart)
+    - .errors (ValidationError)
+
+See also:
+    - compile/parser.py: Previous step
+    - compile/normalizer.py: Next step
+"""
+
+from collections.abc import Mapping
+from typing import Any
+
+from dataface.core.compile.errors import ValidationError
+from dataface.core.compile.models.chart.authored import (
+    CalloutChart,
+    _SharedChartFields,
+)
+from dataface.core.compile.models.face.authored import AuthoredFace
+from dataface.core.compile.models.refs import ChartRef
+from dataface.core.compile.parser import looks_like_sql
+from dataface.core.errors.codes_compile import DF_COMPILE_UNKNOWN_QUERY
+
+
+def validate_face(face: AuthoredFace) -> list[ValidationError]:
+    """Validate a AuthoredFace structure and cross-references.
+
+    Stage: COMPILE (Step 2 of 4: Validation)
+
+    Performs semantic validation beyond what Pydantic provides:
+    - Chart → Query references exist
+    - Layout items reference existing charts
+
+    Note: Pydantic already validates types, required fields, and nested
+    structures during parsing. This function adds cross-reference validation.
+
+    Args:
+        face: Parsed AuthoredFace to validate
+
+    Returns:
+        List of ValidationError objects (empty if valid)
+
+    Example:
+        >>> face = parse_yaml(yaml_content)
+        >>> errors = validate_face(face)
+        >>> if errors:
+        ...     for e in errors:
+        ...         print(f"Error: {e}")
+    """
+    errors: list[ValidationError] = []
+
+    # Collect available names
+    query_names = set((face.queries or {}).keys())
+    chart_names = set((face.charts or {}).keys())
+
+    # Validate chart → query references
+    errors.extend(_validate_chart_query_references(face.charts or {}, query_names))
+
+    # Validate layout → chart references
+    errors.extend(_validate_layout_references(face, chart_names, query_names))
+
+    return errors
+
+
+def _validate_chart_query_references(
+    charts: Mapping[str, _SharedChartFields | CalloutChart | ChartRef],
+    query_names: set[str],
+) -> list[ValidationError]:
+    """Validate that charts reference existing queries.
+
+    Args:
+        charts: Chart definitions (chart patch instance or ChartRef cross-file references)
+        query_names: Available query names
+
+    Returns:
+        List of validation errors
+    """
+    errors: list[ValidationError] = []
+
+    for chart_name, chart in charts.items():
+        # Skip cross-file chart references — resolved during normalization
+        if isinstance(chart, ChartRef):
+            continue
+
+        # CalloutChart is minimal — no query field by design.
+        if isinstance(chart, CalloutChart):
+            continue
+
+        query_ref = chart.query
+
+        # Skip validation for blank charts (no query)
+        if query_ref is None:
+            continue
+
+        # Skip validation for inline query definitions (dicts)
+        # These are handled during normalization
+        if isinstance(query_ref, dict):
+            continue
+
+        # Strip "queries." prefix if present
+        if query_ref.startswith("queries."):
+            query_ref = query_ref[8:]
+
+        # Cross-file references (e.g., "other_file.queries.name") are resolved later
+        if "." in query_ref:
+            continue
+
+        if query_ref not in query_names:
+            if looks_like_sql(query_ref):
+                # Bare SQL string — normalizer will promote it to an inline query; skip here.
+                continue
+
+            errors.append(
+                ValidationError.from_code(
+                    DF_COMPILE_UNKNOWN_QUERY,
+                    chart_name=chart_name,
+                    query_name=query_ref,
+                )
+            )
+
+    return errors
+
+
+def _validate_layout_references(
+    face: AuthoredFace,
+    chart_names: set[str],
+    query_names: set[str],
+) -> list[ValidationError]:
+    """Validate that layout items reference existing charts.
+
+    Args:
+        face: AuthoredFace to validate
+        chart_names: Available chart names
+        query_names: Available query names
+
+    Returns:
+        List of validation errors
+    """
+    errors: list[ValidationError] = []
+
+    # Collect all layout items
+    layout_items = _get_layout_items(face)
+
+    for location, item in layout_items:
+        if isinstance(item, str):
+            # String reference - must be a chart name (or special reference)
+            if _is_special_reference(item):
+                continue
+
+            if item not in chart_names:
+                errors.append(
+                    ValidationError(
+                        f"Layout references unknown chart '{item}'", location=location
+                    )
+                )
+
+        elif isinstance(item, (dict, _SharedChartFields)):
+            # Inline chart - validate its query reference
+            query_ref = item.get("query") if isinstance(item, dict) else item.query
+
+            # Skip validation for blank charts (no query)
+            if query_ref is None:
+                continue
+
+            # Skip validation for inline query definitions (dicts)
+            # These are handled during normalization
+            if isinstance(query_ref, dict):
+                continue
+
+            if query_ref.startswith("queries."):
+                query_ref = query_ref[8:]
+
+            # Skip cross-file references
+            if "." not in query_ref and query_ref not in query_names:
+                if looks_like_sql(query_ref):
+                    continue
+                errors.append(
+                    ValidationError.from_code(
+                        DF_COMPILE_UNKNOWN_QUERY,
+                        chart_name=location,
+                        query_name=query_ref,
+                    )
+                )
+
+    return errors
+
+
+def _get_layout_items(face: AuthoredFace) -> list[tuple[str, Any]]:
+    """Extract all layout items with their locations.
+
+    Args:
+        face: AuthoredFace to extract items from
+
+    Returns:
+        List of (location, item) tuples
+    """
+    items: list[tuple[str, Any]] = []
+
+    if face.rows:
+        for idx, item in enumerate(face.rows):
+            items.append((f"rows[{idx}]", item))
+            items.extend(_get_nested_items(item, f"rows[{idx}]"))
+
+    if face.cols:
+        for idx, item in enumerate(face.cols):
+            items.append((f"cols[{idx}]", item))
+            items.extend(_get_nested_items(item, f"cols[{idx}]"))
+
+    if face.grid:
+        for idx, grid_item in enumerate(face.grid.items):
+            items.append((f"grid.items[{idx}]", grid_item.item))
+
+    if face.tabs:
+        for idx, tab_item in enumerate(face.tabs.items):
+            if tab_item.rows:
+                for i, item in enumerate(tab_item.rows):
+                    items.append((f"tabs.items[{idx}].rows[{i}]", item))
+            if tab_item.cols:
+                for i, item in enumerate(tab_item.cols):
+                    items.append((f"tabs.items[{idx}].cols[{i}]", item))
+
+    return items
+
+
+def _get_nested_items(item: Any, parent_location: str) -> list[tuple[str, Any]]:
+    """Extract items from nested face structures.
+
+    Args:
+        item: Item that might be a nested face
+        parent_location: Parent location string
+
+    Returns:
+        List of (location, item) tuples from nested structures
+    """
+    items: list[tuple[str, Any]] = []
+
+    if isinstance(item, dict):
+        # If nested face has its own charts, skip validation here -
+        # the nested face's layout items will reference its own charts,
+        # which will be validated during normalization
+        if "charts" in item:
+            return items
+
+        # Nested face without its own charts - extract its layout items
+        if "rows" in item:
+            for idx, nested in enumerate(item["rows"]):
+                items.append((f"{parent_location}.rows[{idx}]", nested))
+                items.extend(
+                    _get_nested_items(nested, f"{parent_location}.rows[{idx}]")
+                )
+        if "cols" in item:
+            for idx, nested in enumerate(item["cols"]):
+                items.append((f"{parent_location}.cols[{idx}]", nested))
+                items.extend(
+                    _get_nested_items(nested, f"{parent_location}.cols[{idx}]")
+                )
+
+    return items
+
+
+def _is_special_reference(ref: str) -> bool:
+    """Check if a reference is a special type (partial, remote, etc.).
+
+    Special references are validated during normalization, not here.
+
+    Args:
+        ref: Reference string to check
+
+    Returns:
+        True if this is a special reference type
+    """
+    # Partial references start with underscore
+    if ref.startswith("_"):
+        return True
+
+    # Cross-file references contain dots or slashes
+    return bool("." in ref or "/" in ref)

dataface/core/compile/variables.py

@@ -0,0 +1,53 @@
+"""Variable utilities for Dataface.
+
+Stage: COMPILE (utilities used by both execute and render)
+Purpose: Shared variable processing functions.
+
+This module provides utilities for working with variables that are needed
+by both the execute and render stages.
+"""
+
+import json
+from typing import Any
+
+from dataface.core.compile.models.face.compiled import VariableValues
+
+
+def parse_variable_json_strings(variables: VariableValues) -> VariableValues:
+    """Parse JSON strings in variables (e.g., from URL parameters).
+
+    When variables come from URL query parameters, complex values like
+    date ranges are often serialized as JSON strings. This function
+    parses them back to their native Python types.
+
+    This function is idempotent - calling it on already-parsed values
+    returns them unchanged.
+
+    Args:
+        variables: Variable values that may contain JSON strings
+
+    Returns:
+        Variables with JSON strings parsed to their actual types
+
+    Example:
+        >>> parse_variable_json_strings({"date_range": '["2024-01-01", "2024-01-31"]'})
+        {"date_range": ["2024-01-01", "2024-01-31"]}
+    """
+    parsed: dict[str, Any] = {}
+    for key, value in variables.items():
+        if isinstance(value, str):
+            # Try to parse as JSON (for date ranges, arrays, objects)
+            if value.startswith("[") or value.startswith("{"):
+                try:
+                    parsed[key] = json.loads(value)
+                except (json.JSONDecodeError, ValueError):
+                    # Not valid JSON, keep as string
+                    parsed[key] = value
+            else:
+                parsed[key] = value
+        else:
+            parsed[key] = value
+    return parsed
+
+
+__all__ = ["parse_variable_json_strings"]