dataface 0.1.2__py3-none-any.whl

dataface/core/render/fonts/_emoji_font_face.css

@@ -0,0 +1,43 @@
+@font-face {
+  font-family: 'Inter Variable';
+  src: url('/static/fonts/InterVariable.woff2') format('woff2-variations');
+  font-weight: 100 900;
+  font-style: normal;
+  font-display: swap;
+}
+@font-face {
+  font-family: 'DFT Sans Tabular';
+  src: url('/static/fonts/DFTSansTabular-Regular.woff2') format('woff2-variations');
+  font-weight: 100 900;
+  font-style: normal;
+  font-display: swap;
+}
+@font-face {
+  font-family: 'Source Serif 4';
+  src: url('/static/fonts/source-serif-4-variable-latin.woff2') format('woff2-variations');
+  font-weight: 200 900;
+  font-style: normal;
+  font-display: swap;
+}
+@font-face {
+  font-family: 'Noto Emoji';
+  src: url('/static/fonts/NotoEmoji-Regular.woff2') format('woff2');
+  font-display: swap;
+  unicode-range:
+    U+1F000-1F02F, U+1F0A0-1F0FF, U+1F100-1F1FF, U+1F200-1F2FF,
+    U+1F300-1F5FF, U+1F600-1F64F, U+1F650-1F67F, U+1F680-1F6FF,
+    U+1F700-1F77F, U+1F780-1F7FF, U+1F800-1F8FF, U+1F900-1F9FF,
+    U+1FA00-1FA6F, U+1FA70-1FAFF, U+2600-26FF, U+2700-27BF,
+    U+FE00-FE0F, U+1F1E6-1F1FF;
+}
+@font-face {
+  font-family: 'Noto Color Emoji';
+  src: url('/static/fonts/NotoColorEmoji-Regular.woff2') format('woff2');
+  font-display: swap;
+  unicode-range:
+    U+1F000-1F02F, U+1F0A0-1F0FF, U+1F100-1F1FF, U+1F200-1F2FF,
+    U+1F300-1F5FF, U+1F600-1F64F, U+1F650-1F67F, U+1F680-1F6FF,
+    U+1F700-1F77F, U+1F780-1F7FF, U+1F800-1F8FF, U+1F900-1F9FF,
+    U+1FA00-1FA6F, U+1FA70-1FAFF, U+2600-26FF, U+2700-27BF,
+    U+FE00-FE0F, U+1F1E6-1F1FF;
+}

dataface/core/render/format_utils.py

@@ -0,0 +1,329 @@
+"""D3 formatting utilities for value display.
+
+Stage: RENDER
+Purpose: Resolve format aliases from the theme cascade and format values
+         using D3-style format strings.
+
+The format alias vocabulary lives in theme YAML (style.formats). Callers
+pass compiled_style.formats to resolve_format(); unknown keys and raw d3
+specs pass through unchanged for d3 to parse.
+
+The d3-format spec parsing and number formatting is delegated to the
+``d3_format`` library (``libs/d3-format/``), which implements byte-for-byte
+parity with d3.js for the supported type subset.
+
+Dataface-specific extensions over d3-format:
+- ``analytic`` notation: SI ``k/M/G/T`` suffixes mapped to ``K/M/B/T`` with a
+  space separator (e.g. d3's ``"1.5G"`` becomes ``"1.5 B"``).
+- ``narrative`` notation: ``k/M/G/T`` mapped to ``k/mn/bn/tr`` (no space,
+  journalistic abbreviations — not part of the d3-format standard).
+- ``None`` value: rendered as ``"—"`` (em dash) regardless of spec.
+
+See also:
+    - https://d3js.org/d3-format
+    - vega_lite.py: Uses these utilities for KPI chart formatting
+"""
+
+from typing import Any
+
+from d3_format import format as _d3_format, parse as _d3_parse
+
+# Import FormatConfig from types to avoid duplication
+# Re-export for convenience
+from dataface.core.compile.models.primitives import FormatConfig
+
+# ============================================================================
+# NATIVE (NON-D3) FORMATTERS
+# ============================================================================
+# These handle format aliases that cannot be expressed as D3 format strings.
+# Keyed by the alias name (same string an author writes in YAML format: field).
+# Checked in format_value / format_kpi_parts before the D3 path.
+#
+# percent_number / percent_number_delta: the value IS the whole-number percent
+# (12.8 means 12.8%). D3's "%" type multiplies by 100, so it can't express this.
+
+_NATIVE_FORMATTERS: dict[str, Any] = {
+    "percent_number": lambda v: "—" if v is None else f"{float(v):.1f}%",
+    "percent_number_delta": lambda v: "—" if v is None else f"{float(v):+.1f}%",
+}
+
+# ============================================================================
+# FORMAT RESOLUTION
+# ============================================================================
+
+
+def resolve_format(
+    format_input: str | FormatConfig | dict[str, Any] | None,
+    formats: dict[str, str] | None = None,
+) -> str:
+    """Convert format input to D3 format string.
+
+    Resolution order:
+    1. formats[key] — theme/face-defined alias lookup (key-sensitive)
+    2. Raw d3 passthrough — author typed a literal d3 spec
+
+    If an alias key is not in formats and is not a valid d3 spec, d3 itself
+    will raise at render time. That is the intended contract.
+
+    Args:
+        format_input: Format specification (string, FormatConfig, dict, or None)
+        formats: The resolved format alias dict from the theme cascade
+                 (compiled_style.formats). None = no aliases defined.
+
+    Returns:
+        D3 format string, or "" for null/empty input.
+    """
+    if format_input is None:
+        return ""
+
+    # Extract spec from FormatConfig or dict
+    if isinstance(format_input, FormatConfig):
+        format_str = format_input.spec or ""
+    elif isinstance(format_input, dict):
+        format_str = format_input.get("spec", "")
+    else:
+        format_str = str(format_input)
+
+    if not format_str:
+        return ""
+
+    # Theme/face alias lookup (case-sensitive, key-exact)
+    if formats and format_str in formats:
+        return formats[format_str]
+
+    # Raw d3 passthrough — let d3 parse or raise
+    return format_str
+
+
+def get_format_prefix_suffix(
+    format_input: str | FormatConfig | dict[str, Any] | None,
+) -> tuple[str, str]:
+    """Extract prefix and suffix from format configuration.
+
+    Args:
+        format_input: Format specification
+
+    Returns:
+        Tuple of (prefix, suffix) strings
+    """
+    if format_input is None:
+        return "", ""
+
+    if isinstance(format_input, FormatConfig):
+        return format_input.prefix or "", format_input.suffix or ""
+    elif isinstance(format_input, dict):
+        return format_input.get("prefix", ""), format_input.get("suffix", "")
+
+    # String format has no prefix/suffix
+    return "", ""
+
+
+def _get_notation(
+    format_input: str | FormatConfig | dict[str, Any] | None,
+) -> str | None:
+    """Extract notation family from format configuration."""
+    if isinstance(format_input, FormatConfig):
+        return format_input.notation
+    elif isinstance(format_input, dict):
+        return format_input.get("notation")
+    return None
+
+
+# ============================================================================
+# D3 FORMATTING IMPLEMENTATION
+# ============================================================================
+
+
+def format_d3(
+    value: int | float | None,
+    format_spec: str,
+    prefix: str = "",
+    suffix: str = "",
+    notation: str | None = None,
+) -> str:
+    """Format a value using D3-style format specification.
+
+    Delegates to ``libs/d3-format/`` for spec parsing and formatting.
+    Applies Dataface-specific analytic/narrative notation post-processing for
+    SI (``s``-type) specs after the lib produces d3-standard output.
+
+    Args:
+        value: Numeric value to format
+        format_spec: D3 format string (e.g., "$,.2f", ".1~%", "~s")
+        prefix: Custom prefix to prepend
+        suffix: Custom suffix to append
+        notation: SI-prefix notation family ("analytic" or "narrative")
+
+    Returns:
+        Formatted string
+    """
+    if value is None:
+        return f"{prefix}—{suffix}"
+
+    if not format_spec:
+        return f"{prefix}{value}{suffix}"
+
+    formatted = _d3_format(format_spec)(float(value))
+
+    # Dataface-specific SI notation post-processing.
+    # d3 emits SI standard: k/M/G/T with no space. Dataface surfaces show
+    # K/M/B/T with a space (analytic) or k/mn/bn/tr (narrative).
+    if _is_si_spec(format_spec):
+        effective_notation = notation or "analytic"
+        if effective_notation == "analytic":
+            formatted = _apply_analytic_notation(formatted)
+        elif effective_notation == "narrative":
+            formatted = _apply_narrative_notation(formatted)
+        else:
+            raise ValueError(f"Unknown notation: {effective_notation!r}")
+
+    return f"{prefix}{formatted}{suffix}"
+
+
+def _is_si_spec(spec: str) -> bool:
+    """True when spec's type character is 's' (SI prefix)."""
+    return _d3_parse(spec).type == "s"
+
+
+# d3 SI prefix → Dataface analytic suffix mapping
+_D3_TO_ANALYTIC: dict[str, str] = {
+    "k": " K",
+    "M": " M",
+    "G": " B",
+    "T": " T",
+    "P": " P",
+    "E": " E",
+    "Z": " Z",
+    "Y": " Y",
+}
+
+# d3 SI prefix → Dataface narrative suffix mapping
+_D3_TO_NARRATIVE: dict[str, str] = {
+    "k": "k",
+    "M": "mn",
+    "G": "bn",
+    "T": "tr",
+}
+
+
+def _apply_analytic_notation(d3_str: str) -> str:
+    """Convert d3 SI string (e.g. '1.5M') to analytic notation (e.g. '1.5 M')."""
+    for d3_sfx, analytic_sfx in _D3_TO_ANALYTIC.items():
+        if d3_str.endswith(d3_sfx):
+            return d3_str[: -len(d3_sfx)] + analytic_sfx
+    return d3_str
+
+
+def _apply_narrative_notation(d3_str: str) -> str:
+    """Convert d3 SI string (e.g. '1.5G') to narrative notation (e.g. '1.5bn')."""
+    for d3_sfx, narrative_sfx in _D3_TO_NARRATIVE.items():
+        if d3_str.endswith(d3_sfx):
+            return d3_str[: -len(d3_sfx)] + narrative_sfx
+    return d3_str
+
+
+def format_value(
+    value: int | float | None,
+    format_input: str | FormatConfig | dict[str, Any] | None,
+    formats: dict[str, str] | None = None,
+) -> str:
+    """Format a value using the given format configuration.
+
+    Args:
+        value: Numeric value to format
+        format_input: Format specification (string, FormatConfig, dict, or None)
+        formats: Theme format alias dict from compiled_style.formats
+
+    Returns:
+        Formatted string
+    """
+    format_spec = resolve_format(format_input, formats)
+    if format_spec in _NATIVE_FORMATTERS:
+        return _NATIVE_FORMATTERS[format_spec](value)
+    prefix, suffix = get_format_prefix_suffix(format_input)
+    notation = _get_notation(format_input)
+
+    return format_d3(value, format_spec, prefix, suffix, notation=notation)
+
+
+def format_kpi_parts(
+    value: int | float | None,
+    format_input: str | FormatConfig | dict[str, Any] | None,
+    formats: dict[str, str] | None = None,
+) -> tuple[str, str, str]:
+    """Format a KPI value into (prefix, number, suffix) parts.
+
+    Separates prefix symbols ($), magnitude suffixes (M, K, bn), and unit
+    suffixes (%, USD) from the formatted number so they can be rendered or
+    positioned independently.
+
+    Args:
+        value: Numeric value to format
+        format_input: Format specification
+        formats: Theme format alias dict from compiled_style.formats
+    """
+    if value is None:
+        return "", "—", ""
+
+    explicit_prefix, explicit_suffix = get_format_prefix_suffix(format_input)
+    format_spec = resolve_format(format_input, formats)
+
+    # Native formatters bypass D3: split formatted string into number + % suffix.
+    if format_spec in _NATIVE_FORMATTERS:
+        formatted = _NATIVE_FORMATTERS[format_spec](value)
+        if formatted.endswith("%"):
+            return "", formatted[:-1], "%"
+        return "", formatted, ""
+
+    d3_prefix = ""
+    d3_suffix = ""
+    magnitude_suffix = ""
+
+    if format_spec:
+        # Pull $ out of the D3 spec so it renders as a separate element
+        if "$" in format_spec:
+            d3_prefix = "$"
+            format_spec_clean = format_spec.replace("$", "")
+        else:
+            format_spec_clean = format_spec
+
+        notation = _get_notation(format_input)
+
+        # SI/compact: split magnitude suffix into its own field
+        if _is_si_spec(format_spec_clean):
+            # Format via the lib (without notation post-process), then split suffix
+            raw = _d3_format(format_spec_clean)(float(value))
+            number_str = raw
+            effective_notation = notation or "analytic"
+            if effective_notation == "analytic":
+                for d3_sfx, analytic_sfx in _D3_TO_ANALYTIC.items():
+                    if raw.endswith(d3_sfx):
+                        number_str = raw[: -len(d3_sfx)]
+                        magnitude_suffix = analytic_sfx.strip()
+                        break
+            elif effective_notation == "narrative":
+                for d3_sfx, narrative_sfx in _D3_TO_NARRATIVE.items():
+                    if raw.endswith(d3_sfx):
+                        number_str = raw[: -len(d3_sfx)]
+                        magnitude_suffix = narrative_sfx
+                        break
+            else:
+                raise ValueError(f"Unknown notation: {effective_notation!r}")
+        else:
+            number_str = format_d3(value, format_spec_clean, notation=notation)
+
+        # Pull trailing % that format_d3 appended
+        if "%" in format_spec and number_str.endswith("%"):
+            d3_suffix = "%"
+            number_str = number_str[:-1]
+    else:
+        v = float(value)
+        if v == int(v) and abs(v) < 1e15:
+            number_str = f"{int(v):,}"
+        else:
+            number_str = f"{v:,.2f}"
+
+    prefix = ((explicit_prefix or "") + d3_prefix).strip()
+    suffix = (magnitude_suffix + d3_suffix + (explicit_suffix or "").strip()).strip()
+
+    return prefix, number_str.strip(), suffix

dataface/core/render/geo_defaults.yml

@@ -0,0 +1,28 @@
+geo_sources:
+  us-states:
+    url: "https://vega.github.io/vega-datasets/data/us-10m.json"
+    format: topojson
+    feature: states
+    projection: albersUsa
+    key: id
+
+  us-counties:
+    url: "https://vega.github.io/vega-datasets/data/us-10m.json"
+    format: topojson
+    feature: counties
+    projection: albersUsa
+    key: id
+
+  world-countries:
+    url: "https://vega.github.io/vega-datasets/data/world-110m.json"
+    format: topojson
+    feature: countries
+    projection: equalEarth
+    key: id
+
+  world-50m:
+    url: "https://vega.github.io/vega-datasets/data/world-50m.json"
+    format: topojson
+    feature: countries
+    projection: equalEarth
+    key: id

dataface/core/render/json_format.py

@@ -0,0 +1,146 @@
+"""JSON render output format.
+
+Walks the layout tree, executes queries, resolves charts, and returns
+the resolved objects plus executed data as a JSON string.
+"""
+
+import dataclasses
+import json
+from collections.abc import Mapping
+from datetime import date, datetime
+from decimal import Decimal
+from typing import Any
+
+from pydantic import BaseModel
+
+from dataface.core.compile.errors import DatafaceError
+from dataface.core.compile.models.face.compiled import Face, VariableValues
+from dataface.core.errors import DF_RENDER_INTERNAL, StructuredError
+from dataface.core.execute.executor import Executor
+from dataface.core.render.chart.pipeline import resolve_chart
+from dataface.core.render.utils import resolve_field_names
+
+
+def _json_default(obj: Any) -> Any:
+    """Handle non-serializable types."""
+    if isinstance(obj, BaseModel):
+        return obj.model_dump(exclude_none=True)
+    if isinstance(obj, Mapping):
+        return dict(obj)
+    if isinstance(obj, set):
+        return sorted(obj)
+    if isinstance(obj, Decimal):
+        return str(obj)
+    if isinstance(obj, (date, datetime)):
+        return obj.isoformat()
+    raise TypeError(f"Object of type {type(obj).__name__} is not JSON serializable")
+
+
+def _resolved_chart_to_dict(resolved: Any) -> dict[str, Any]:
+    """Convert a ResolvedChart dataclass to a dict, skipping source_chart."""
+    d = dataclasses.asdict(resolved)
+    d.pop("source_chart", None)
+    return d
+
+
+def _render_chart_item(
+    chart: Any,
+    executor: Executor,
+    variables: VariableValues,
+    error_collector: list[StructuredError] | None = None,
+) -> dict[str, Any]:
+    """Execute, resolve, and serialize a single chart item."""
+    from dataface.core.execute.errors import ExecutionError
+    from dataface.core.render.errors import RenderError
+
+    try:
+        data = executor.execute_chart(chart, variables)
+        resolved_chart = resolve_field_names(chart, data)
+        col_descs = (
+            executor.get_column_descriptions(chart.query_name)
+            if chart.query_name
+            else None
+        )
+        presentation = resolve_chart(resolved_chart, data, col_descs)
+        return {
+            "type": "chart",
+            "chart": _resolved_chart_to_dict(presentation),
+            "data": data,
+        }
+    except (RenderError, ExecutionError, DatafaceError) as e:
+        e.fields["chart_id"] = chart.id
+        structured = e.to_structured()
+        if error_collector is not None:
+            error_collector.append(structured)
+        return {"type": "chart", "_error": structured.model_dump(exclude_none=True)}
+    except Exception as e:  # noqa: BLE001
+        wrapped = RenderError.from_code(DF_RENDER_INTERNAL, inner_message=str(e))
+        wrapped.fields["chart_id"] = chart.id
+        structured = wrapped.to_structured()
+        if error_collector is not None:
+            error_collector.append(structured)
+        return {"type": "chart", "_error": structured.model_dump(exclude_none=True)}
+
+
+def _render_face_items(
+    face: Face,
+    executor: Executor,
+    variables: VariableValues,
+    error_collector: list[StructuredError] | None = None,
+) -> list[dict[str, Any]]:
+    """Walk layout items and serialize each."""
+    results: list[dict[str, Any]] = []
+    for item in face.layout.items:
+        if item.type == "chart" and item.chart:
+            results.append(
+                _render_chart_item(item.chart, executor, variables, error_collector)
+            )
+        elif item.type == "face" and item.face:
+            results.append(
+                {
+                    "type": "face",
+                    "face": face_to_dict(
+                        item.face, executor, variables, error_collector
+                    ),
+                }
+            )
+    return results
+
+
+def face_to_dict(
+    face: Face,
+    executor: Executor,
+    variables: VariableValues,
+    error_collector: list[StructuredError] | None = None,
+) -> dict[str, Any]:
+    """Convert a face to a JSON-serializable dict."""
+    result: dict[str, Any] = {
+        "id": face.id,
+        "title": face.title,
+        "items": _render_face_items(face, executor, variables, error_collector),
+    }
+    if face.variables:
+        result["variables"] = {
+            name: var.model_dump(exclude_none=True)
+            for name, var in face.variables.items()
+        }
+    return result
+
+
+def render_face_json(
+    face: Face,
+    executor: Executor,
+    variables: VariableValues,
+    error_collector: list[StructuredError] | None = None,
+) -> str:
+    """Render a compiled face to JSON.
+
+    Walks the layout tree, executes queries, resolves charts
+    (auto type, auto fields), and returns a JSON string with
+    the resolved chart semantics and executed data.
+    """
+    return json.dumps(
+        face_to_dict(face, executor, variables, error_collector),
+        default=_json_default,
+        indent=2,
+    )