dataface 0.1.2__py3-none-any.whl

dataface/core/compile/chart_update.py

@@ -0,0 +1,261 @@
+"""Chart update utilities for edit-back support.
+
+This module provides functions to update chart definitions in dashboard YAML,
+preserving the original formatting as much as possible.
+
+When a user edits a chart in the chart editor:
+1. The edit produces new values (SQL, type, x, y, title, etc.)
+2. This module updates the original YAML with those changes
+3. Inline charts/queries are promoted to named entries for clarity
+
+Example:
+    >>> yaml_content = '''
+    ... title: Dashboard
+    ... rows:
+    ...   - title: Revenue
+    ...     query: {sql: SELECT * FROM sales}
+    ...     type: bar
+    ... '''
+    >>> edits = {"sql": "SELECT * FROM orders", "type": "line"}
+    >>> updated = update_chart_in_yaml(yaml_content, "revenue", edits)
+    >>> # Chart is now promoted to named, query to named
+
+Usage:
+    from dataface.core.compile.chart_update import update_chart_in_yaml
+
+    updated_yaml = update_chart_in_yaml(
+        yaml_content=original_yaml,
+        chart_id="revenue",
+        edits={
+            "sql": "SELECT * FROM new_query",
+            "type": "bar",
+            "x": "date",
+            "y": "amount",
+            "title": "New Title",
+        }
+    )
+"""
+
+import logging
+from typing import Any
+
+import yaml
+
+logger = logging.getLogger(__name__)
+
+
+def update_chart_in_yaml(
+    yaml_content: str,
+    chart_id: str,
+    edits: dict[str, Any],
+    source_path: str | None = None,
+    query_is_inline: bool = False,
+) -> str:
+    """Update a chart definition in dashboard YAML.
+
+    This function:
+    1. Parses the YAML
+    2. Finds the chart by ID
+    3. Updates the chart with new values
+    4. Promotes inline charts/queries to named entries
+    5. Returns the updated YAML
+
+    Args:
+        yaml_content: Original dashboard YAML content
+        chart_id: ID of the chart to update
+        edits: Dict of fields to update (sql, type, x, y, title, etc.)
+        source_path: Original source path (e.g., "charts.revenue", "rows[0]")
+        query_is_inline: Whether the chart had an inline query
+
+    Returns:
+        Updated YAML content as string
+
+    Example:
+        >>> edits = {"sql": "SELECT * FROM orders", "type": "line", "x": "date"}
+        >>> updated = update_chart_in_yaml(yaml, "revenue", edits)
+
+    Raises:
+        ValueError: If YAML content is invalid or SQL is provided but empty/whitespace.
+    """
+    # Parse the YAML with error handling
+    try:
+        data = yaml.safe_load(yaml_content) or {}
+    except yaml.YAMLError as e:
+        raise ValueError(f"Invalid YAML content: {e}") from e
+
+    # Initialize sections if needed
+    if "charts" not in data:
+        data["charts"] = {}
+    if "queries" not in data:
+        data["queries"] = {}
+
+    # Get the SQL if provided (validate it's a non-empty string)
+    new_sql = edits.get("sql")
+    if new_sql is not None:
+        if not isinstance(new_sql, str):
+            raise ValueError("SQL must be a string")
+        if not new_sql.strip():
+            raise ValueError("SQL cannot be empty or whitespace only")
+    new_source = edits.get("source")
+
+    # Try to find the existing source from the original chart's query
+    if not new_source:
+        existing_chart = data.get("charts", {}).get(chart_id)
+        if existing_chart and isinstance(existing_chart, dict):
+            existing_query_ref = existing_chart.get("query")
+            if existing_query_ref:
+                # It might be a string reference to a named query
+                if isinstance(existing_query_ref, str):
+                    existing_query = data.get("queries", {}).get(existing_query_ref)
+                    if existing_query and isinstance(existing_query, dict):
+                        new_source = existing_query.get("source")
+                # Or it might be an inline query dict
+                elif isinstance(existing_query_ref, dict):
+                    new_source = existing_query_ref.get("source")
+
+        # Also check face-level source as fallback
+        if not new_source and "source" in data:
+            new_source = data["source"]
+
+    # If SQL is being edited, create/update a named query
+    query_name = f"{chart_id}_query"
+    if new_sql:
+        query_def: dict[str, Any] = {"sql": new_sql}
+        if new_source:
+            query_def["source"] = new_source
+        data["queries"][query_name] = query_def
+
+    # Build the chart definition
+    chart_def: dict[str, Any] = {}
+
+    # Title
+    if "title" in edits and edits["title"]:
+        chart_def["title"] = edits["title"]
+
+    # Query reference (always use named query if SQL was edited)
+    if new_sql:
+        chart_def["query"] = query_name
+    elif "query" in edits:
+        chart_def["query"] = edits["query"]
+
+    # Chart type
+    if "type" in edits and edits["type"]:
+        chart_def["type"] = edits["type"]
+
+    # Data mappings
+    for field in ["x", "y", "color", "size", "value"]:
+        if field in edits and edits[field]:
+            chart_def[field] = edits[field]
+
+    # Update the charts section
+    # If chart already exists, merge with existing values
+    if chart_id in data["charts"]:
+        existing = data["charts"][chart_id]
+        if isinstance(existing, dict):
+            # Preserve existing fields not being edited
+            for key, value in existing.items():
+                if key not in chart_def and key not in ["query"]:
+                    chart_def[key] = value
+    data["charts"][chart_id] = chart_def
+
+    # If chart was inline, we need to update the layout reference
+    if source_path and (
+        source_path.startswith("rows[") or source_path.startswith("cols[")
+    ):
+        _update_layout_reference(data, source_path, chart_id)
+
+    # Serialize back to YAML
+    return yaml.dump(
+        data, default_flow_style=False, sort_keys=False, allow_unicode=True
+    )
+
+
+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.
+
+    Args:
+        data: Parsed YAML data (modified in place)
+        source_path: Path like "rows[0]" or "cols[1]"
+        chart_id: ID of the chart to reference
+    """
+    # Parse the source path to get the layout type and index
+    if source_path.startswith("rows["):
+        layout_key = "rows"
+        try:
+            index = int(source_path.split("[")[1].rstrip("]"))
+        except (ValueError, IndexError):
+            logger.warning(f"Failed to parse row index from source_path: {source_path}")
+            return
+    elif source_path.startswith("cols["):
+        layout_key = "cols"
+        try:
+            index = int(source_path.split("[")[1].rstrip("]"))
+        except (ValueError, IndexError):
+            logger.warning(
+                f"Failed to parse column index from source_path: {source_path}"
+            )
+            return
+    else:
+        logger.debug(f"Unrecognized source_path format: {source_path}")
+        return
+
+    # 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
+
+
+def get_chart_edits_from_form(
+    sql: str | None = None,
+    source: str | None = None,
+    chart_type: str | None = None,
+    x: str | None = None,
+    y: str | None = None,
+    color: str | None = None,
+    title: str | None = None,
+    value: str | None = None,
+) -> dict[str, Any]:
+    """Build an edits dict from form parameters.
+
+    Convenience function for building the edits dict from
+    individual form fields.
+
+    Args:
+        sql: Query SQL
+        source: Query source name
+        chart_type: Chart type (bar, line, etc.)
+        x: X-axis field
+        y: Y-axis field
+        color: Color field
+        title: Chart title
+        value: Value field (for KPI charts: column reference — string column name)
+
+    Returns:
+        Dict of non-None edits
+    """
+    edits: dict[str, Any] = {}
+
+    if sql is not None:
+        edits["sql"] = sql
+    if source is not None:
+        edits["source"] = source
+    if chart_type is not None:
+        edits["type"] = chart_type
+    if x is not None:
+        edits["x"] = x
+    if y is not None:
+        edits["y"] = y
+    if color is not None:
+        edits["color"] = color
+    if title is not None:
+        edits["title"] = title
+    if value is not None:
+        edits["value"] = value
+
+    return edits

dataface/core/compile/colors.py

@@ -0,0 +1,64 @@
+"""Color utility functions for Dataface renderers.
+
+Provides is_dark_color and sanitize_color for use across compile and render layers.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import overload
+
+_CSS_HEX_COLOR_PATTERN = re.compile(r"^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$")
+
+
+def is_dark_color(color: str) -> bool:
+    """Check if a color is dark based on luminance.
+
+    Uses the relative luminance formula to determine if a color is
+    dark (luminance < 0.5) or light (luminance >= 0.5).
+    """
+    if not color or not color.startswith("#"):
+        return False
+
+    hex_color = color.lstrip("#")
+    if len(hex_color) == 3:
+        hex_color = "".join(c * 2 for c in hex_color)
+
+    if len(hex_color) != 6:
+        return False
+
+    try:
+        r = int(hex_color[0:2], 16) / 255.0
+        g = int(hex_color[2:4], 16) / 255.0
+        b = int(hex_color[4:6], 16) / 255.0
+    except ValueError:
+        return False
+
+    luminance = 0.299 * r + 0.587 * g + 0.114 * b
+    return luminance < 0.5
+
+
+@overload
+def sanitize_color(color: str | None, fallback: str) -> str: ...
+
+
+@overload
+def sanitize_color(color: str | None, fallback: None) -> str | None: ...
+
+
+def sanitize_color(color: str | None, fallback: str | None = "#000000") -> str | None:
+    """Validate and sanitize a color value for safe use in SVG/HTML.
+
+    Accepts hex colors (``#fff``, ``#FFFFFF``) and the CSS keywords
+    ``transparent`` and ``none``.  Presets use ``transparent`` to
+    explicitly clear an inherited theme color (YAML ``null`` means
+    "no override" in the merge system, so it doesn't disable an
+    inherited fill).
+    """
+    if not color or not isinstance(color, str):
+        return fallback
+    if _CSS_HEX_COLOR_PATTERN.match(color):
+        return color
+    if color.lower() in {"transparent", "none"}:
+        return "transparent"
+    return fallback