create-hedgeboard 1.0.7 → 1.0.8

package/hedgeboard/viz/components.py

@@ -1,391 +0,0 @@
-"""Dashboard components — reusable building blocks for financial dashboards.
-
-Provides KPI cards, callout boxes, scorecards, comparison tables, heatmaps,
-timelines, sparklines, section headers, source citations, and metric deltas.
-
-All components return HTML strings ready for render_dashboard().
-
-Usage:
-    from viz.components import kpi_row, callout, grid, scorecard
-"""
-
-from __future__ import annotations
-
-import html as _html
-from typing import Literal
-
-# ---------------------------------------------------------------------------
-# Chart color palette — 8 distinct colors for multi-series data
-# ---------------------------------------------------------------------------
-
-COLORS = [
-    "#EAEAEA",   # primary (white-ish)
-    "#4ADE80",   # green
-    "#60A5FA",   # blue
-    "#FBBF24",   # amber
-    "#F87171",   # red
-    "#A78BFA",   # purple
-    "#34D399",   # teal
-    "#FB923C",   # orange
-]
-
-COLORS_DIM = [
-    "rgba(234,234,234,0.15)",
-    "rgba(74,222,128,0.15)",
-    "rgba(96,165,250,0.15)",
-    "rgba(251,191,36,0.15)",
-    "rgba(248,113,113,0.15)",
-    "rgba(167,139,250,0.15)",
-    "rgba(52,211,153,0.15)",
-    "rgba(251,146,60,0.15)",
-]
-
-
-def _esc(text: str) -> str:
-    return _html.escape(str(text))
-
-
-# ---------------------------------------------------------------------------
-# Grid layout — put charts/components side by side
-# ---------------------------------------------------------------------------
-
-def grid(items: list[str], columns: int = 2) -> str:
-    """Place items side-by-side in a responsive grid.
-
-    Args:
-        items: List of HTML strings (charts, tables, etc.).
-        columns: Number of columns (2 or 3).
-    """
-    cells = "".join(f'<div class="hb-grid-cell">{item}</div>' for item in items)
-    return f'<div class="hb-grid hb-grid-{columns}">{cells}</div>'
-
-
-# ---------------------------------------------------------------------------
-# KPI Row — top-level metrics with deltas
-# ---------------------------------------------------------------------------
-
-def kpi_row(metrics: list[dict]) -> str:
-    """Render a row of KPI metric cards.
-
-    Args:
-        metrics: List of dicts with keys:
-            - label: str (e.g. "Revenue")
-            - value: str (e.g. "$901M")
-            - delta: str, optional (e.g. "+15.5%")
-            - trend: str, optional ("up", "down", "flat")
-            - sparkline: list[float], optional (mini trend data)
-    """
-    cards = []
-    for m in metrics:
-        delta_html = ""
-        if m.get("delta"):
-            trend = m.get("trend", "")
-            if not trend:
-                d = m["delta"]
-                trend = "up" if (d.startswith("+") or d.startswith("▲")) else "down" if (d.startswith("-") or d.startswith("▼")) else "flat"
-            cls = "hb-delta-up" if trend == "up" else "hb-delta-down" if trend == "down" else "hb-delta-flat"
-            arrow = "▲" if trend == "up" else "▼" if trend == "down" else "—"
-            delta_html = f'<span class="hb-kpi-delta {cls}">{arrow} {_esc(m["delta"])}</span>'
-
-        spark_html = ""
-        if m.get("sparkline"):
-            spark_html = sparkline(m["sparkline"])
-
-        cards.append(f'''<div class="hb-kpi">
-            <span class="hb-kpi-label">{_esc(m["label"])}</span>
-            <span class="hb-kpi-value">{_esc(m["value"])}</span>
-            {delta_html}
-            {spark_html}
-        </div>''')
-
-    return f'<div class="hb-kpi-row">{" ".join(cards)}</div>'
-
-
-# ---------------------------------------------------------------------------
-# Callout / Alert boxes
-# ---------------------------------------------------------------------------
-
-def callout(
-    text: str,
-    type: Literal["info", "success", "warning", "danger"] = "info",
-    title: str | None = None,
-) -> str:
-    """Render a callout box for key insights.
-
-    Args:
-        text: The callout message.
-        type: "info", "success", "warning", or "danger".
-        title: Optional bold title line.
-    """
-    icons = {"info": "ℹ", "success": "✓", "warning": "⚠", "danger": "✕"}
-    icon = icons.get(type, "ℹ")
-    title_html = f'<strong>{_esc(title)}</strong> ' if title else ""
-    return f'''<div class="hb-callout hb-callout-{type}">
-        <span class="hb-callout-icon">{icon}</span>
-        <div>{title_html}{_esc(text)}</div>
-    </div>'''
-
-
-# ---------------------------------------------------------------------------
-# Scorecard — bull/bear/neutral verdict
-# ---------------------------------------------------------------------------
-
-def scorecard(
-    verdict: Literal["bullish", "neutral", "bearish"],
-    reasoning: str,
-    title: str = "Outlook",
-) -> str:
-    """Render a scorecard with a bullish/neutral/bearish verdict.
-
-    Args:
-        verdict: "bullish", "neutral", or "bearish".
-        reasoning: Brief explanation.
-        title: Card title.
-    """
-    colors = {"bullish": "#4ADE80", "neutral": "#FBBF24", "bearish": "#F87171"}
-    labels = {"bullish": "▲ Bullish", "neutral": "— Neutral", "bearish": "▼ Bearish"}
-    return f'''<div class="hb-scorecard">
-        <span class="hb-section-lbl">{_esc(title)}</span>
-        <div class="hb-scorecard-verdict" style="color:{colors[verdict]}">
-            {labels[verdict]}
-        </div>
-        <p class="hb-scorecard-reason">{_esc(reasoning)}</p>
-    </div>'''
-
-
-# ---------------------------------------------------------------------------
-# Comparison table — multi-company side-by-side with color coding
-# ---------------------------------------------------------------------------
-
-def comparison_table(
-    headers: list[str],
-    rows: list[list],
-    title: str = "",
-    highlight_best: bool = True,
-) -> str:
-    """Render a comparison table with color-coded best/worst values.
-
-    Args:
-        headers: Column headers (first is typically "Metric").
-        rows: Each row is [metric_name, val1, val2, ...].
-              Numeric values get color-coded.
-        title: Optional table title.
-        highlight_best: If True, highest numeric value gets green, lowest gets red.
-    """
-    title_html = f'<div class="hb-table-title">{_esc(title)}</div>' if title else ""
-
-    # Header
-    ths = "".join(f'<th>{_esc(h)}</th>' for h in headers)
-    thead = f"<thead><tr>{ths}</tr></thead>"
-
-    # Body with highlighting
-    tbody_rows = []
-    for row in rows:
-        tds = []
-        # Find numeric values for highlighting
-        nums = []
-        for i, val in enumerate(row):
-            if i > 0:
-                try:
-                    clean = str(val).replace("$", "").replace(",", "").replace("%", "").replace("B", "e9").replace("M", "e6").replace("K", "e3")
-                    nums.append((i, float(clean)))
-                except (ValueError, TypeError):
-                    nums.append((i, None))
-
-        best_idx = None
-        worst_idx = None
-        if highlight_best and len(nums) > 1:
-            valid = [(i, n) for i, n in nums if n is not None]
-            if valid:
-                best_idx = max(valid, key=lambda x: x[1])[0]
-                worst_idx = min(valid, key=lambda x: x[1])[0]
-                if best_idx == worst_idx:
-                    best_idx = worst_idx = None
-
-        for i, val in enumerate(row):
-            cls = ""
-            if i == best_idx:
-                cls = ' class="hb-cell-best"'
-            elif i == worst_idx:
-                cls = ' class="hb-cell-worst"'
-            elif i == 0:
-                cls = ' class="hb-cell-label"'
-            tds.append(f"<td{cls}>{_esc(val)}</td>")
-
-        tbody_rows.append(f"<tr>{''.join(tds)}</tr>")
-
-    return f'''{title_html}
-    <div class="hb-table-wrap">
-        <table class="hb-comp-table">
-            {thead}
-            <tbody>{''.join(tbody_rows)}</tbody>
-        </table>
-    </div>'''
-
-
-# ---------------------------------------------------------------------------
-# Heatmap table — cell intensity based on value
-# ---------------------------------------------------------------------------
-
-def heatmap_table(
-    headers: list[str],
-    rows: list[list],
-    title: str = "",
-) -> str:
-    """Render a table where numeric cells have background intensity based on value.
-
-    Args:
-        headers: Column headers.
-        rows: Each row is [label, val1, val2, ...].
-    """
-    title_html = f'<div class="hb-table-title">{_esc(title)}</div>' if title else ""
-    ths = "".join(f'<th>{_esc(h)}</th>' for h in headers)
-
-    # Collect all numeric values for normalization
-    all_nums = []
-    for row in rows:
-        for val in row[1:]:
-            try:
-                all_nums.append(float(str(val).replace("$", "").replace(",", "").replace("%", "")))
-            except (ValueError, TypeError):
-                pass
-
-    min_val = min(all_nums) if all_nums else 0
-    max_val = max(all_nums) if all_nums else 1
-    val_range = max_val - min_val or 1
-
-    tbody_rows = []
-    for row in rows:
-        tds = [f'<td class="hb-cell-label">{_esc(row[0])}</td>']
-        for val in row[1:]:
-            try:
-                num = float(str(val).replace("$", "").replace(",", "").replace("%", ""))
-                intensity = (num - min_val) / val_range
-                color = f"rgba(234,234,234,{intensity * 0.2 + 0.02})"
-                tds.append(f'<td style="background:{color}">{_esc(val)}</td>')
-            except (ValueError, TypeError):
-                tds.append(f"<td>{_esc(val)}</td>")
-        tbody_rows.append(f"<tr>{''.join(tds)}</tr>")
-
-    return f'''{title_html}
-    <div class="hb-table-wrap">
-        <table class="hb-comp-table">
-            <thead><tr>{ths}</tr></thead>
-            <tbody>{''.join(tbody_rows)}</tbody>
-        </table>
-    </div>'''
-
-
-# ---------------------------------------------------------------------------
-# Sparklines — tiny inline SVG charts
-# ---------------------------------------------------------------------------
-
-def sparkline(data: list[float], width: int = 80, height: int = 24) -> str:
-    """Render a tiny SVG sparkline chart.
-
-    Args:
-        data: List of numeric values.
-        width: SVG width.
-        height: SVG height.
-    """
-    if not data or len(data) < 2:
-        return ""
-
-    min_v = min(data)
-    max_v = max(data)
-    v_range = max_v - min_v or 1
-    pad = 2
-
-    points = []
-    for i, v in enumerate(data):
-        x = pad + (i / (len(data) - 1)) * (width - 2 * pad)
-        y = pad + (1 - (v - min_v) / v_range) * (height - 2 * pad)
-        points.append(f"{x:.1f},{y:.1f}")
-
-    trend_color = "#4ADE80" if data[-1] >= data[0] else "#F87171"
-
-    return f'''<svg class="hb-sparkline" width="{width}" height="{height}" viewBox="0 0 {width} {height}">
-        <polyline points="{' '.join(points)}" fill="none"
-            stroke="{trend_color}" stroke-width="1.5" stroke-linecap="round"/>
-    </svg>'''
-
-
-# ---------------------------------------------------------------------------
-# Metric delta badge
-# ---------------------------------------------------------------------------
-
-def delta_badge(value: str, trend: Literal["up", "down", "flat"] | None = None) -> str:
-    """Render an inline delta badge (▲ +15.5% in green, etc.).
-
-    Args:
-        value: The delta text (e.g. "+15.5%", "-3.2%").
-        trend: "up", "down", or "flat". Auto-detected from value if not given.
-    """
-    if not trend:
-        trend = "up" if value.startswith("+") else "down" if value.startswith("-") else "flat"
-    arrow = "▲" if trend == "up" else "▼" if trend == "down" else "—"
-    cls = f"hb-delta-{trend}"
-    return f'<span class="hb-delta-badge {cls}">{arrow} {_esc(value)}</span>'
-
-
-# ---------------------------------------------------------------------------
-# Section header
-# ---------------------------------------------------------------------------
-
-def section_header(label: str, title: str = "", description: str = "") -> str:
-    """Render a clean section divider with label and optional title.
-
-    Args:
-        label: Uppercase label (e.g. "REVENUE ANALYSIS").
-        title: Optional larger title.
-        description: Optional description text.
-    """
-    parts = [f'<span class="hb-section-lbl">{_esc(label)}</span>']
-    if title:
-        parts.append(f'<h2 class="hb-section-title">{_esc(title)}</h2>')
-    if description:
-        parts.append(f'<p class="hb-section-desc">{_esc(description)}</p>')
-    return f'<div class="hb-section-header">{"".join(parts)}</div>'
-
-
-# ---------------------------------------------------------------------------
-# Source citation panel
-# ---------------------------------------------------------------------------
-
-def source_panel(sources: list[str]) -> str:
-    """Render a collapsible source citation panel.
-
-    Args:
-        sources: List of source strings (e.g. "SEC 10-K, filed 2025-10-31").
-    """
-    items = "".join(f"<li>{_esc(s)}</li>" for s in sources)
-    return f'''<details class="hb-sources">
-        <summary class="hb-sources-toggle">Sources & Data ({len(sources)})</summary>
-        <ul class="hb-sources-list">{items}</ul>
-    </details>'''
-
-
-# ---------------------------------------------------------------------------
-# Timeline — horizontal milestones
-# ---------------------------------------------------------------------------
-
-def timeline(events: list[dict]) -> str:
-    """Render a horizontal timeline of events.
-
-    Args:
-        events: List of dicts with keys:
-            - date: str (e.g. "2025-10-31")
-            - label: str (e.g. "10-K Filed")
-            - detail: str, optional
-    """
-    items = []
-    for ev in events:
-        detail = f'<span class="hb-timeline-detail">{_esc(ev.get("detail", ""))}</span>' if ev.get("detail") else ""
-        items.append(f'''<div class="hb-timeline-item">
-            <span class="hb-timeline-date">{_esc(ev["date"])}</span>
-            <span class="hb-timeline-dot"></span>
-            <span class="hb-timeline-label">{_esc(ev["label"])}</span>
-            {detail}
-        </div>''')
-
-    return f'<div class="hb-timeline">{"".join(items)}</div>'