dataface 0.1.2__py3-none-any.whl

dataface/core/render/terminal_layouts.py

@@ -0,0 +1,299 @@
+"""Terminal layout rendering functions.
+
+Stage: RENDER
+Purpose: Render different layout types (rows, cols, grid, tabs) to terminal output.
+
+This module provides functions to render layouts in terminal-friendly format:
+- Rows: Vertical stacking
+- Cols: Horizontal distribution (if terminal width allows)
+- Grid: Character-based grid layout
+- Tabs: Text-based tabs
+"""
+
+from dataface.core.compile.models.face.compiled import LayoutItem, VariableValues
+from dataface.core.execute.executor import Executor
+from dataface.core.render.terminal_text import (
+    pad_visible,
+    truncate_visible,
+    visible_len,
+)
+
+
+def _layout_item_is_table(item: LayoutItem) -> bool:
+    if item.type != "chart":
+        return False
+    assert item.chart is not None  # normalizer: chart layout items always carry chart
+    return item.chart.type == "table"
+
+
+def _cols_should_stack_vertically(items: list[LayoutItem], col_width: int) -> bool:
+    if col_width < 50:
+        return True
+    return any(_layout_item_is_table(item) for item in items)
+
+
+def render_rows_layout_terminal(
+    items: list[LayoutItem],
+    executor: Executor,
+    variables: VariableValues,
+    available_width: int,
+    available_height: int,
+    gap: int = 1,
+    background: str | None = None,
+) -> str:
+    """Render items in vertical stack for terminal.
+
+    Args:
+        items: Layout items to render
+        executor: Executor for query execution
+        variables: Variable values for queries
+        available_width: Available terminal width in characters
+        available_height: Available terminal height in characters
+        gap: Gap between items (in lines)
+        background: Optional background color (not used in terminal)
+
+    Returns:
+        Terminal-formatted string for rows layout
+    """
+    from dataface.core.render.terminal import render_layout_item_terminal
+
+    if not items:
+        return ""
+
+    rendered_items: list[str] = []
+    for item in items:
+        item_output = render_layout_item_terminal(
+            item, executor, variables, available_width, available_height
+        )
+        if item_output:
+            rendered_items.append(item_output)
+            # Add gap between items
+            if gap > 0:
+                rendered_items.append("")
+
+    return "\n".join(rendered_items)
+
+
+def render_cols_layout_terminal(
+    items: list[LayoutItem],
+    executor: Executor,
+    variables: VariableValues,
+    available_width: int,
+    available_height: int,
+    gap: int = 2,
+    background: str | None = None,
+) -> str:
+    """Render items side-by-side for terminal.
+
+    Note: Terminal columns are limited by width. If items don't fit,
+    we fall back to vertical stacking.
+
+    Args:
+        items: Layout items to render
+        executor: Executor for query execution
+        variables: Variable values for queries
+        available_width: Available terminal width in characters
+        available_height: Available terminal height in characters
+        gap: Gap between items (in characters)
+        background: Optional background color (not used in terminal)
+
+    Returns:
+        Terminal-formatted string for columns layout
+    """
+    from dataface.core.render.terminal import render_layout_item_terminal
+
+    if not items:
+        return ""
+
+    # Calculate column width
+    n = len(items)
+    total_gap = gap * (n - 1)
+    col_width = (available_width - total_gap) // n
+
+    if _cols_should_stack_vertically(items, col_width):
+        return render_rows_layout_terminal(
+            items,
+            executor,
+            variables,
+            available_width,
+            available_height,
+            gap,
+        )
+
+    # Render each item in its column
+    rendered_items: list[list[str]] = []
+    max_lines = 0
+
+    for item in items:
+        item_output = render_layout_item_terminal(
+            item, executor, variables, col_width, available_height
+        )
+        lines = item_output.split("\n")
+        rendered_items.append(lines)
+        max_lines = max(max_lines, len(lines))
+
+    # Combine columns horizontally
+    output_lines: list[str] = []
+    for line_idx in range(max_lines):
+        line_parts = []
+        for item_lines in rendered_items:
+            if line_idx < len(item_lines):
+                line = item_lines[line_idx]
+                if visible_len(line) > col_width:
+                    line = truncate_visible(line, col_width)
+                line_parts.append(pad_visible(line, col_width))
+            else:
+                line_parts.append(" " * col_width)
+
+        output_lines.append((" " * gap).join(line_parts))
+
+    return "\n".join(output_lines)
+
+
+def render_grid_layout_terminal(
+    items: list[LayoutItem],
+    executor: Executor,
+    variables: VariableValues,
+    available_width: int,
+    available_height: int,
+    columns: int = 2,
+    gap: int = 1,
+    background: str | None = None,
+) -> str:
+    """Render items in a grid layout for terminal.
+
+    Args:
+        items: Layout items to render
+        executor: Executor for query execution
+        variables: Variable values for queries
+        available_width: Available terminal width in characters
+        available_height: Available terminal height in characters
+        columns: Number of columns in grid
+        gap: Gap between items (in characters/lines)
+        background: Optional background color (not used in terminal)
+
+    Returns:
+        Terminal-formatted string for grid layout
+    """
+    from dataface.core.render.terminal import render_layout_item_terminal
+
+    if not items:
+        return ""
+
+    # Calculate cell dimensions
+    total_gap = gap * (columns - 1)
+    cell_width = (available_width - total_gap) // columns
+
+    # Group items into rows
+    rows: list[list[LayoutItem]] = []
+    current_row: list[LayoutItem] = []
+    for item in items:
+        current_row.append(item)
+        if len(current_row) >= columns:
+            rows.append(current_row)
+            current_row = []
+    if current_row:
+        rows.append(current_row)
+
+    # Render each row
+    rendered_rows: list[str] = []
+    for row_items in rows:
+        # Render items in this row
+        row_rendered: list[list[str]] = []
+        max_lines = 0
+
+        for item in row_items:
+            item_output = render_layout_item_terminal(
+                item, executor, variables, cell_width, available_height
+            )
+            lines = item_output.split("\n")
+            row_rendered.append(lines)
+            max_lines = max(max_lines, len(lines))
+
+        # Combine row items horizontally
+        row_lines: list[str] = []
+        for line_idx in range(max_lines):
+            line_parts = []
+            for item_lines in row_rendered:
+                if line_idx < len(item_lines):
+                    line = item_lines[line_idx]
+                    if visible_len(line) > cell_width:
+                        line = truncate_visible(line, cell_width)
+                    line_parts.append(pad_visible(line, cell_width))
+                else:
+                    line_parts.append(" " * cell_width)
+
+            row_lines.append((" " * gap).join(line_parts))
+
+        rendered_rows.append("\n".join(row_lines))
+        if gap > 0:
+            rendered_rows.append("")  # Gap between rows
+
+    return "\n".join(rendered_rows)
+
+
+def render_tabs_layout_terminal(
+    items: list[LayoutItem],
+    executor: Executor,
+    variables: VariableValues,
+    available_width: int,
+    available_height: int,
+    tab_titles: list[str] | None = None,
+    default_tab: int = 0,
+    tab_position: str = "top",
+    background: str | None = None,
+) -> str:
+    """Render tabs layout for terminal.
+
+    Note: For terminal, we render all tabs sequentially with headers,
+    since terminal doesn't support interactive tabs.
+
+    Args:
+        items: Layout items (one per tab)
+        executor: Executor for query execution
+        variables: Variable values for queries
+        available_width: Available terminal width in characters
+        available_height: Available terminal height in characters
+        tab_titles: Optional list of tab titles
+        default_tab: Default active tab (not used in terminal)
+        tab_position: Tab position ("top" or "bottom", not used in terminal)
+        background: Optional background color (not used in terminal)
+
+    Returns:
+        Terminal-formatted string for tabs layout
+    """
+    from dataface.core.render.terminal import render_layout_item_terminal
+
+    if not items:
+        return ""
+
+    output_lines: list[str] = []
+
+    for idx, item in enumerate(items):
+        # Add tab header
+        tab_title = (
+            tab_titles[idx]
+            if tab_titles and idx < len(tab_titles)
+            else f"Tab {idx + 1}"
+        )
+
+        # Create header line
+        header_line = f"┌─ {tab_title} {'─' * (available_width - len(tab_title) - 5)}┐"
+        output_lines.append(header_line)
+
+        # Render tab content
+        item_output = render_layout_item_terminal(
+            item, executor, variables, available_width - 4, available_height
+        )
+
+        # Indent content
+        content_lines = item_output.split("\n")
+        for line in content_lines:
+            output_lines.append(f"│ {line.ljust(available_width - 4)} │")
+
+        # Add footer
+        footer_line = f"└{'─' * (available_width - 2)}┘"
+        output_lines.append(footer_line)
+        output_lines.append("")  # Gap between tabs
+
+    return "\n".join(output_lines)

dataface/core/render/terminal_text.py

@@ -0,0 +1,31 @@
+"""ANSI-aware string width helpers for terminal layout joining."""
+
+from __future__ import annotations
+
+import re
+
+_ANSI_ESCAPE_RE = re.compile(r"\x1b\[[0-9;]*m")
+
+
+def strip_ansi(text: str) -> str:
+    return _ANSI_ESCAPE_RE.sub("", text)
+
+
+def visible_len(text: str) -> int:
+    return len(strip_ansi(text))
+
+
+def pad_visible(text: str, width: int) -> str:
+    padding = width - visible_len(text)
+    if padding <= 0:
+        return text
+    return text + (" " * padding)
+
+
+def truncate_visible(text: str, max_width: int) -> str:
+    if visible_len(text) <= max_width:
+        return text
+    plain = strip_ansi(text)
+    if max_width <= 3:
+        return plain[:max_width]
+    return plain[: max_width - 3] + "..."

dataface/core/render/text/__init__.py

@@ -0,0 +1 @@
+"""Text transform utilities for DFT render layer."""

dataface/core/render/text/case.py

@@ -0,0 +1,113 @@
+"""Letter-case transform dispatcher for DFT typography.
+
+Applies at render time — after Jinja resolution but before the string reaches
+an SVG <text> node or a Vega-Lite spec string field.
+
+Supported values (matching FontStyle.case):
+  none       — no-op; string emitted as authored / as normalized by slug_to_text.
+  upper      — str.upper() (Unicode-aware).
+  lower      — str.lower() (Unicode-aware).
+  sentence   — first character uppercased, remainder unchanged.
+               Preserves acronyms and proper nouns that the author
+               already capitalized.  Does NOT lowercase the rest of the
+               string — that would corrupt ARR, iOS, etc.
+  title      — Chicago/Gruber algorithm via the `titlecase` library.
+               Lowercases stopwords (a, an, and, as, at, but, by, en,
+               for, if, in, of, on, or, the, to, v[.], vs[.], via).
+               Always capitalizes first and last words.
+               Preserves any token with internal capitals (ARR, iPhone,
+               MRR, SQL) — the key differentiator from naive
+               "capitalize every word" algorithms.
+  slug       — Machine identifier form: spaces/hyphens → underscore, lower.
+               "Order Status" → "order_status".
+  camel      — camelCase: first word lower, subsequent words capitalized.
+               "order status" → "orderStatus".
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+from titlecase import titlecase as _titlecase
+
+from dataface.core.utils import slug_to_text
+
+if TYPE_CHECKING:
+    from dataface.core.compile.models.primitives import MergedFontStyle
+
+CaseValue = Literal["none", "sentence", "title", "upper", "lower", "slug", "camel"]
+
+
+def apply_case(text: str, case: CaseValue) -> str:
+    """Apply a letter-case transform to *text* and return the result.
+
+    Args:
+        text: The string to transform.  May be empty.
+        case: One of 'none', 'upper', 'lower', 'sentence', 'title', 'slug', 'camel'.
+
+    Returns:
+        The transformed string.
+
+    Raises:
+        ValueError: If *case* is not a recognised value.
+    """
+    if case == "none":
+        return text
+    if case == "upper":
+        return text.upper()
+    if case == "lower":
+        return text.lower()
+    if case == "sentence":
+        # Cautious sentence case: uppercase only the first character, leave
+        # the rest unchanged.  Preserves acronyms/proper nouns.
+        return text[:1].upper() + text[1:] if text else text
+    if case == "title":
+        return _titlecase(text)
+    if case == "slug":
+        # Machine form: spaces/hyphens → underscore, all lowercase.
+        return text.replace(" ", "_").replace("-", "_").lower()
+    if case == "camel":
+        # camelCase: lower the first word, capitalize subsequent words.
+        words = text.replace("-", " ").replace("_", " ").split()
+        if not words:
+            return text
+        return words[0].lower() + "".join(w.capitalize() for w in words[1:])
+    raise ValueError(
+        f"Unknown case: {case!r}. Expected one of 'none', 'upper', "
+        "'lower', 'sentence', 'title', 'slug', 'camel'."
+    )
+
+
+def apply_font_case(text: str, font: MergedFontStyle) -> str:
+    """Apply the letter-case transform specified by font.case.
+
+    Args:
+        text: The string to transform.
+        font: A fully-resolved font; font.case drives the transform.
+
+    Returns:
+        The transformed string.
+    """
+    return apply_case(text, font.case)
+
+
+def format_display_text(
+    text: str,
+    *,
+    from_slug: bool,
+    font: MergedFontStyle,
+) -> str:
+    """Two-step render pipeline: optional slug tokenization then font case.
+
+    Args:
+        text: The raw input string — either an authored string or a slug.
+        from_slug: True when *text* is a field slug / identifier that needs
+            ``slug_to_text`` tokenization first (underscore→space, unit/abbreviation
+            expansion).  False when *text* is already human-readable authored text.
+        font: The resolved font for this slot; font.case drives the case transform.
+
+    Returns:
+        The display-ready string.
+    """
+    normalized = slug_to_text(text) if from_slug else text
+    return apply_font_case(normalized, font)

dataface/core/render/text_format.py

@@ -0,0 +1,129 @@
+"""Text render output format for AI agents.
+
+Walks the layout tree via face_to_dict (shared with JSON format),
+then templates into compact markdown text.
+"""
+
+from typing import Any
+
+from dataface.core.compile.models.face.compiled import Face, VariableValues
+from dataface.core.errors import StructuredError
+from dataface.core.execute.executor import Executor
+from dataface.core.render.json_format import face_to_dict
+
+
+def render_face_text(
+    face: Face,
+    executor: Executor,
+    variables: VariableValues,
+    error_collector: list[StructuredError] | None = None,
+) -> str:
+    """Render a compiled face to compact markdown text for AI agents."""
+    d = face_to_dict(face, executor, variables, error_collector)
+    lines: list[str] = []
+    _render_face(d, lines, depth=1)
+    return "\n".join(lines)
+
+
+def _render_face(face: dict[str, Any], lines: list[str], depth: int) -> None:
+    """Render a face dict to markdown lines at the given heading depth."""
+    title = face.get("title") or face.get("id", "Untitled")
+    lines.append(f"{'#' * depth} {title}")
+    for item in face.get("items", []):
+        if item["type"] == "chart":
+            _render_chart(item, lines, depth + 1)
+        elif item["type"] == "face":
+            lines.append("")
+            _render_face(item["face"], lines, depth + 1)
+
+
+def _render_chart(item: dict[str, Any], lines: list[str], depth: int) -> None:
+    """Render a chart item to markdown lines."""
+    # Chart error: emit a compact error line instead of data
+    if "_error" in item:
+        err = item["_error"]
+        code = err.get("code", "")
+        msg = err.get("message", "error")
+        chart_id = err.get("fields", {}).get("chart_id", "unknown")
+        lines.append(f"\n[chart error: {code} {msg} (chart: {chart_id})]")
+        return
+
+    chart = item["chart"]
+    data = item.get("data", [])
+
+    chart_type = chart.get("chart_type", "unknown")
+    title = chart.get("title") or chart.get("id", "chart")
+    lines.append("")
+    lines.append(f"{'#' * depth} {title} ({chart_type})")
+
+    # KPI: show value, optionally resolved against the bound row when the
+    # authored value is a column reference.
+    if chart_type == "kpi":
+        raw = chart.get("value")
+        cell = (
+            data[0].get(raw)
+            if isinstance(raw, str) and data and raw in data[0]
+            else raw
+        )
+        if isinstance(cell, (int, float)):
+            display = f"{cell:,}" if cell == int(cell) else f"{cell:,.2f}"
+        elif cell is not None:
+            display = str(cell)
+        else:
+            display = ""
+        if display:
+            lines.append(f"- value: {display}")
+        return
+
+    # Field mappings
+    fields = _field_mappings(chart)
+    if fields:
+        lines.append(f"- {', '.join(fields)}")
+
+    # Data summary
+    if data:
+        summary = _data_summary(chart, data)
+        if summary:
+            lines.append(f"- {summary}")
+
+
+def _field_mappings(chart: dict[str, Any]) -> list[str]:
+    """Extract field mapping strings like 'x: month, y: revenue'."""
+    mappings = []
+    for key in ("x", "y", "color", "size", "theta", "value"):
+        val = chart.get(key)
+        if val:
+            mappings.append(f"{key}: {val}")
+    return mappings
+
+
+def _data_summary(chart: dict[str, Any], data: list[dict]) -> str:
+    """Build a compact data summary string."""
+    parts = [f"{len(data)} rows"]
+
+    # Collect chart field names by role
+    field_roles: dict[str, str] = {}
+    for key in ("x", "y", "color", "size", "theta"):
+        val = chart.get(key)
+        if val:
+            field_roles[val] = key
+
+    for col, role in field_roles.items():
+        values: list[Any] = [row[col] for row in data if row.get(col) is not None]
+        if not values:
+            continue
+        if all(isinstance(v, (int, float)) for v in values) and role in (
+            "y",
+            "size",
+            "theta",
+        ):
+            lo, hi = min(values), max(values)
+            parts.append(f"{col}: {lo}–{hi}")
+        elif all(isinstance(v, str) for v in values) and role in ("x", "color"):
+            distinct = sorted(set(values))
+            if len(distinct) <= 5:
+                parts.append(f"{col}: {', '.join(distinct)}")
+            else:
+                parts.append(f"{col}: {len(distinct)} distinct")
+
+    return " | ".join(parts)

dataface/core/render/utils.py

@@ -0,0 +1,106 @@
+"""Shared utility functions for the render module.
+
+This module contains common utilities used across multiple render modules
+to avoid code duplication.
+"""
+
+from __future__ import annotations
+
+import re
+from decimal import Decimal
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from dataface.core.compile.models.chart.compiled import (
+        Chart,
+    )
+
+SQL_IDENTIFIER_PATTERN = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_]*$")
+
+
+def is_valid_sql_identifier(identifier: str) -> bool:
+    """Validate that a string is a safe SQL identifier.
+
+    Prevents SQL injection by ensuring identifiers only contain
+    alphanumeric characters and underscores, starting with a letter
+    or underscore.
+    """
+    if not identifier:
+        return False
+    return SQL_IDENTIFIER_PATTERN.match(identifier) is not None
+
+
+from dataface.core.utils import slug_to_text  # noqa: F401 — re-exported
+
+
+def resolve_field_names(
+    chart: Chart,
+    data: list[dict[str, Any]],
+) -> Chart:
+    """Resolve chart field references against actual data column names.
+
+    Handles case mismatches (e.g. chart says ``x: stage`` but data has
+    ``Stage``) by remapping the chart's field attributes to match the
+    real column keys.  Returns a copy of the chart with updated fields
+    if any mismatches are found; returns the original chart unchanged
+    when all fields already match.
+    """
+    if not data:
+        return chart
+
+    actual_cols = set(data[0].keys())
+    lower_to_actual: dict[str, str] = {k.lower(): k for k in actual_cols}
+
+    field_attrs = [
+        "x",
+        "y",
+        "color",
+        "size",
+        "shape",
+        "theta",
+        "lookup",
+        "value",  # always a column reference; case-insensitive remapping applies
+    ]
+    updates: dict[str, Any] = {}
+
+    for attr in field_attrs:
+        val = getattr(chart, attr, None)
+        if val is None:
+            continue
+        if isinstance(val, list):
+            resolved_fields = [
+                lower_to_actual.get(f.lower(), f) if isinstance(f, str) else f
+                for f in val
+            ]
+            if resolved_fields != val:
+                updates[attr] = resolved_fields
+        elif isinstance(val, str) and val not in actual_cols:
+            resolved_field = lower_to_actual.get(val.lower())
+            if resolved_field:
+                updates[attr] = resolved_field
+
+    if updates:
+        return chart.model_copy(update=updates)
+    return chart
+
+
+def normalize_data_types(data: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Normalize data types for JSON serialization and rendering.
+
+    Converts Decimal to float, preserves lists/tuples, and stringifies
+    other non-JSON-serializable types.
+    """
+    normalized: list[dict[str, Any]] = []
+    for row in data:
+        normalized_row: dict[str, Any] = {}
+        for key, value in row.items():
+            if isinstance(value, Decimal):
+                normalized_row[key] = float(value)
+            elif isinstance(value, (int, float, str, bool, type(None))):
+                normalized_row[key] = value
+            elif isinstance(value, (list, tuple)):
+                normalized_row[key] = list(value)
+            else:
+                normalized_row[key] = str(value)
+        normalized.append(normalized_row)
+    return normalized