from __future__ import annotations import math from math import pi from typing import Any from bokeh.layouts import row as bk_row from bokeh.models.css import InlineStyleSheet from bokeh.models.layouts import LayoutDOM from bokeh.models.ranges import Range1d from bokeh.models.sources import ColumnDataSource from bokeh.models.tools import HoverTool from bokeh.models.widgets.markups import Div from bokeh.plotting import figure as bk_figure from bokeh.transform import cumsum from ..helper.bokeh import render_template from ..schemes.scheme import Scheme HERO_LEGEND_MIN_WIDTH: int = 140 HERO_COLUMN_GAP: int = 12 VALUE_PRECISION: int = 8 VALUE_FORMAT: str = f".{VALUE_PRECISION}f" def hero_block_min_width(donut_width: int) -> int: """Minimum content width of donut + responsive legend block in `hero_donut_block`. Use to size the paired hero column so both columns match instead of relying on a hardcoded magic number. """ return donut_width + HERO_COLUMN_GAP + HERO_LEGEND_MIN_WIDTH def build_styled_tooltip_html(tooltips: list[tuple[str, str]], scheme: Scheme) -> str: """ Build styled tooltip HTML for Bokeh hover tools. """ tooltip_html = "" for t in tooltips: tooltip_html += "" tooltip_html += render_template( scheme, """ """, ) return tooltip_html def apply_styled_tooltip( figure: Any, renderer: Any, tooltips: list[tuple[str, str]], scheme: Scheme ) -> None: """ Apply styled tooltip to a figure, matching the style used in figure.py """ # Create HoverTool with initial tooltips (like in figure.py) hover_tool = HoverTool(tooltips=tooltips, renderers=[renderer]) figure.add_tools(hover_tool) # Then replace with styled version hover_tool.tooltips = build_styled_tooltip_html(tooltips, scheme) _MAX_INT: int = (1 << 63) - 1 def _strip_trailing_zeros(s: str) -> str: if "." not in s: return s suffix: str = "" body: str = s if s.endswith("%"): suffix = "%" body = s[:-1] head: str tail: str head, _, tail = body.rpartition(".") tail = tail.rstrip("0") body = f"{head}.{tail}".rstrip(".") if tail else head return f"{body}{suffix}" def format_value(value: Any, fmt: str = VALUE_FORMAT) -> str: if value is None: return "-" if isinstance(value, str): return value if isinstance(value, float) and (math.isnan(value) or math.isinf(value)): return "-" if isinstance(value, float): formatted: str = f"{value:{fmt}}" if "." in formatted: formatted = formatted.rstrip("0").rstrip(".") return formatted or "0" return str(value) def format_metric( value: Any, fmt: str = VALUE_FORMAT, *, pct: bool = False, sign: bool = False, pct_precision: int = 1, ) -> str: """Format metric/KPI value for display. Returns "-" for None, NaN/Inf, backtrader sentinel ints (±sys.maxsize), and zero (treated as missing/absent metric). Trailing zeros stripped. pct=True formats as f".{pct_precision}f%" (default 1 decimal). sign=True forces +/- and adds thousands separator using VALUE_FORMAT. """ if value is None: return "-" if isinstance(value, float) and (math.isnan(value) or not math.isfinite(value)): return "-" if value in (_MAX_INT, -_MAX_INT): return "-" if value == 0: return "-" if pct: return _strip_trailing_zeros(f"{float(value):.{pct_precision}f}%") if sign: return _strip_trailing_zeros(f"{float(value):+,{VALUE_FORMAT}}") return _strip_trailing_zeros(f"{value:{fmt}}") def apply_theme(p: Any, scheme: Scheme) -> None: p.background_fill_color = scheme.background_fill p.border_fill_color = scheme.border_fill p.outline_line_color = None p.xgrid.grid_line_color = scheme.grid_line_color p.ygrid.grid_line_color = scheme.grid_line_color p.xgrid.grid_line_alpha = 0.25 p.ygrid.grid_line_alpha = 0.25 p.axis.axis_line_color = scheme.axis_line_color p.axis.major_tick_line_color = scheme.tick_line_color p.axis.minor_tick_line_color = None p.axis.major_label_text_color = scheme.axis_label_text_color p.axis.axis_label_text_color = scheme.axis_label_text_color def style_legend(p: Any, scheme: Scheme) -> None: if not p.legend: return p.legend.visible = True p.legend.background_fill_alpha = scheme.legendtrans p.legend.click_policy = scheme.legend_click p.legend.location = scheme.legend_location p.legend.background_fill_color = scheme.legend_background_color p.legend.label_text_color = scheme.legend_text_color p.legend.orientation = scheme.legend_orientation p.legend.inactive_fill_color = scheme.legend_inactive_fill_color p.legend.inactive_fill_alpha = scheme.legend_inactive_fill_alpha p.legend.border_line_color = None def spacer() -> Div: return Div( width=10, height=10, sizing_mode="fixed", ) def divider() -> Div: return Div( height=20, sizing_mode="stretch_width", ) def section_title(title: str, stylesheet: InlineStyleSheet) -> Div: return Div( text=title, css_classes=["table-title"], sizing_mode="stretch_width", stylesheets=[stylesheet], ) def area_title(title: str, stylesheet: InlineStyleSheet) -> Div: return Div( text=title, css_classes=["tab-panel-title"], sizing_mode="stretch_width", stylesheets=[stylesheet], ) def subsection_title_div( title: str, hint: str, scheme: Scheme, stylesheet: InlineStyleSheet, ) -> Div: return Div( text=( f'

' f'{title}' f"
" f'{hint}' f"

" ), sizing_mode="stretch_width", stylesheets=[stylesheet], ) def text_div( text: str, scheme: Scheme, stylesheet: InlineStyleSheet, ) -> Div: return Div( text=( f'

{text}

' ), sizing_mode="stretch_width", stylesheets=[stylesheet], ) def stats_div( items: list[tuple[str, str, str | None] | None], scheme: Scheme, stylesheet: InlineStyleSheet, ) -> Div: """Compact tearsheet-style key-value table. None item inserts a separator.""" rows: str = "" for item in items: if item is None: rows += ( f'' f'

' ) else: label, value, color = item c: str = color or scheme.axis_label_text_color rows += ( f"" f'{label}' f'{value}' f"" ) return Div( text=f'{rows}

', sizing_mode="stretch_width", stylesheets=[stylesheet], ) def hero_stats_div( value: str, color: str, subtitle: str, subtitle_color: str, *, min_width: int | None = None, ) -> Div: """Large prominent primary-metric display for tearsheet hero KPI.""" host_css: str = ( ":host { display: flex; flex-direction: column; " "justify-content: center; align-items: center; text-align: center;" "padding: 6px 12px 6px 0; box-sizing: border-box; }" ) div = Div( text=( f'

{value}

' f'

' f"{subtitle}

" ), align="center", stylesheets=[InlineStyleSheet(css=host_css)], ) if min_width is not None: div.min_width = min_width return div def donut_chart_plot( categories: list[str], values: list[float], colors: list[str], scheme: Scheme, *, height: int = 220, width: int | None = None, ) -> Any: """Donut chart. Returns raw Bokeh figure; caller adds title/layout. When all values sum to zero, returns an outline-only placeholder (two unfilled concentric circles) so layout stays consistent with populated donuts. """ total: float = sum(v for v in values if v > 0) p = bk_figure( height=height, width=width, tools="", toolbar_location=None, output_backend=scheme.output_backend, sizing_mode="fixed" if width is not None else "stretch_width", x_range=Range1d(start=-0.55, end=0.55), y_range=Range1d(start=-0.55, end=0.55), match_aspect=True, ) apply_theme(p, scheme) p.axis.visible = False p.xgrid.visible = False p.ygrid.visible = False p.outline_line_color = None p.min_border = 0 if total == 0: outline_color: str = scheme.axis_line_color for diameter in (0.96, 0.50): p.ellipse( x=[0], y=[0], width=[diameter], height=[diameter], fill_alpha=0, line_color=outline_color, line_width=1, ) return p angles: list[float] = [v / total * 2 * pi for v in values] source: ColumnDataSource = ColumnDataSource( { "label": categories, "value": values, "color": colors, "angle": angles, } ) wedge_renderer = p.annular_wedge( x=0, y=0, inner_radius=0.25, outer_radius=0.48, start_angle=cumsum("angle", include_zero=True), end_angle=cumsum("angle"), color="color", source=source, line_color=scheme.background_fill, line_width=2, legend_field="label", ) # Apply styled tooltip matching figure.py style apply_styled_tooltip(p, wedge_renderer, [("", "@label"), ("Count", "@value{0}")], scheme) if p.legend: p.legend.visible = False return p def _responsive_legend_div( categories: list[str], colors: list[str], scheme: Scheme, *, list_breakpoint_px: int = 295, container_name: str = "txblock", ) -> Div: """HTML legend that uses container queries on a parent named container. - Default (parent narrow / legend wrapped below): horizontal centered row. - Parent ≥ ``list_breakpoint_px``: vertical list, left-aligned. """ items_html: str = "" for label, color in zip(categories, colors, strict=True): items_html += ( '' f'' f"{label}" ) style_html: str = ( "" ) legend_host_css: str = ( f":host {{ flex: 1 1 auto; min-width: {HERO_LEGEND_MIN_WIDTH}px; " "display: flex; justify-content: center; align-items: center; }" ) return Div( text=f'{style_html}

{items_html}

', height=60, min_width=HERO_LEGEND_MIN_WIDTH, stylesheets=[InlineStyleSheet(css=legend_host_css)], ) def hero_donut_block( hero_div: LayoutDOM, donut: Any | None, categories: list[str], colors: list[str], scheme: Scheme, ) -> LayoutDOM: """Compose hero KPI + (donut, responsive legend) into a flex-wrap row. Layout behavior: - Inner block holds donut and legend; legend wraps below donut on narrow widths. - Outer row holds hero and inner block; inner block wraps below hero only at very narrow widths. - Legend orientation toggles via container query: list when beside donut, centered row when wrapped below. """ if donut is None: return hero_div container_name: str = "txblock" donut_height: int | None = getattr(donut, "height", None) if donut_height is not None and isinstance(hero_div, Div): hero_div.height = donut_height legend_div: Div = _responsive_legend_div( categories=categories, colors=colors, scheme=scheme, container_name=container_name, ) outer_flex_css: str = ( ":host { display: flex; flex-wrap: wrap; " f"column-gap: {HERO_COLUMN_GAP}px; row-gap: 4px; " "align-items: center; justify-content: center; }" ) inner_flex_css: str = ( ":host { display: flex; flex-wrap: wrap; " f"column-gap: {HERO_COLUMN_GAP}px; row-gap: 4px; align-items: center; " "justify-content: center; " f"container-type: inline-size; container-name: {container_name}; }}" ) inner_block: LayoutDOM = bk_row( children=[donut, legend_div], sizing_mode="stretch_width", stylesheets=[InlineStyleSheet(css=inner_flex_css)], ) return bk_row( children=[hero_div, inner_block], sizing_mode="stretch_width", stylesheets=[InlineStyleSheet(css=outer_flex_css)], ) def zone_scale_plot( zones: list[tuple[float, float, str, str]], scheme: Scheme, *, x_lo: float | None = None, x_hi: float | None = None, marker: float | None = None, marker_label: str = "", secondary_marker: float | None = None, secondary_label: str = "", height: int = 130, ) -> Any: """Horizontal color-band zone bar. zones = [(lo, hi, color, label), ...]. Primary marker = solid white line. Secondary = dashed line.""" _x_lo: float = x_lo if x_lo is not None else zones[0][0] _x_hi: float = x_hi if x_hi is not None else zones[-1][1] span: float = _x_hi - _x_lo p = bk_figure( height=height, x_range=Range1d(_x_lo, _x_hi), y_range=Range1d(-1.5, 2.0), tools="", toolbar_location=None, output_backend=scheme.output_backend, sizing_mode="stretch_width", ) apply_theme(p, scheme) p.axis.visible = False p.xgrid.visible = False p.ygrid.visible = False p.outline_line_color = None for lo, hi, color, label in zones: a_lo: float = max(lo, _x_lo) a_hi: float = min(hi, _x_hi) if a_lo >= _x_hi or a_hi <= _x_lo: continue p.hbar( y=0.0, left=a_lo, right=a_hi, height=0.9, fill_color=color, fill_alpha=0.75, line_color=None, ) mid: float = (a_lo + a_hi) / 2.0 p.text( x=[mid], y=[0.0], text=[label], text_color="white", text_font_size="11px", text_align="center", text_baseline="middle", ) for _, hi, _, _ in zones[:-1]: if _x_lo < hi < _x_hi: p.segment( x0=[hi], y0=[-0.45], x1=[hi], y1=[0.45], line_color=scheme.background_fill, line_width=1, ) if marker is not None: mx: float = max(_x_lo, min(_x_hi, marker)) p.segment(x0=[mx], y0=[-0.65], x1=[mx], y1=[0.65], line_color="white", line_width=2) if marker_label: p.text( x=[mx], y=[0.9], text=[marker_label], text_color=scheme.axis_label_text_color, text_font_size="10px", text_align="center", text_baseline="bottom", ) if secondary_marker is not None and ( marker is None or abs(secondary_marker - marker) > span * 0.02 ): sx: float = max(_x_lo, min(_x_hi, secondary_marker)) p.segment( x0=[sx], y0=[-0.65], x1=[sx], y1=[0.65], line_color=scheme.axis_label_text_color, line_width=1, line_dash="dashed", ) if secondary_label: p.text( x=[sx], y=[-0.9], text=[secondary_label], text_color=scheme.axis_label_text_color, text_font_size="10px", text_align="center", text_baseline="top", ) return p def range_bar_plot( *, worst: float, avg: float, stddev: float, best: float, scheme: Scheme, unit_suffix: str = "", value_fmt: str = VALUE_FORMAT, worst_label: str = "Worst", best_label: str = "Best", avg_label: str = "Avg", height: int = 130, ) -> Any: """Horizontal range bar — worst→best segment, avg marker, ± stddev band. Uses red/green half-plane shading split at 0 when range crosses zero. Pass NaN for `stddev` to omit the dispersion band. Returns None if worst/best are not finite. """ valid_worst: bool = math.isfinite(worst) valid_best: bool = math.isfinite(best) valid_avg: bool = math.isfinite(avg) valid_std: bool = math.isfinite(stddev) and stddev > 0.0 if not (valid_worst and valid_best): return None span: float = max(best - worst, 1e-6) pad: float = max(span * 0.15, 0.5) x_lo: float = min(worst, 0.0) - pad x_hi: float = max(best, 0.0) + pad p = bk_figure( height=height, x_range=Range1d(start=x_lo, end=x_hi), y_range=Range1d(start=-1.6, end=2.0), tools="", toolbar_location=None, output_backend=scheme.output_backend, sizing_mode="stretch_width", ) apply_theme(p, scheme) p.ygrid.visible = False p.yaxis.visible = False p.outline_line_color = None if x_lo < 0.0 < x_hi: p.hbar( y=0.0, left=x_lo, right=0.0, height=0.30, fill_color=scheme.color_red, fill_alpha=0.18, line_color=None, ) p.hbar( y=0.0, left=0.0, right=x_hi, height=0.30, fill_color=scheme.color_green, fill_alpha=0.18, line_color=None, ) p.segment( x0=[0.0], y0=[-0.25], x1=[0.0], y1=[0.25], line_color=scheme.grid_line_color, line_width=1, ) else: bg: str = scheme.color_red if x_hi <= 0.0 else scheme.color_green p.hbar( y=0.0, left=x_lo, right=x_hi, height=0.30, fill_color=bg, fill_alpha=0.18, line_color=None, ) p.segment( x0=[worst], y0=[0.0], x1=[best], y1=[0.0], line_color=scheme.axis_label_text_color, line_width=2, ) if valid_avg and valid_std: band_lo: float = max(x_lo, avg - stddev) band_hi: float = min(x_hi, avg + stddev) p.hbar( y=0.0, left=band_lo, right=band_hi, height=0.65, fill_color=scheme.axis_label_text_color, fill_alpha=0.20, line_color=None, ) p.scatter( x=[worst], y=[0.0], size=10, color=scheme.color_red, line_color="white", line_width=1, ) p.scatter( x=[best], y=[0.0], size=10, color=scheme.color_green, line_color="white", line_width=1, ) p.text( x=[worst], y=[-0.6], text=[f"{worst_label} {worst:{value_fmt}}{unit_suffix}"], text_color=scheme.color_red, text_font_size="10px", text_align="center", text_baseline="top", ) p.text( x=[best], y=[-0.6], text=[f"{best_label} {best:{value_fmt}}{unit_suffix}"], text_color=scheme.color_green, text_font_size="10px", text_align="center", text_baseline="top", ) if valid_avg: p.segment( x0=[avg], y0=[-0.55], x1=[avg], y1=[0.55], line_color="white", line_width=2, ) avg_text: str = f"{avg_label} {avg:{value_fmt}}{unit_suffix}" if valid_std: avg_text += f" ± {stddev:{value_fmt}}{unit_suffix}" p.text( x=[avg], y=[0.75], text=[avg_text], text_color=scheme.axis_label_text_color, text_font_size="10px", text_align="center", text_baseline="bottom", ) return p def risk_zone_plot( max_dd: float, current_dd: float, scheme: Scheme, stylesheet: InlineStyleSheet, *, height: int = 130, ) -> Any: """Drawdown severity zone bar — wrapper around zone_scale_plot.""" x_end: float = max(40.0, (max_dd if math.isfinite(max_dd) else 0.0) * 1.4 + 6.0) zones: list[tuple[float, float, str, str]] = [ (0.0, 10.0, scheme.color_green, "Mild"), (10.0, 20.0, scheme.color_amber, "Moderate"), (20.0, 30.0, scheme.color_orange, "Significant"), (30.0, x_end, scheme.color_red, "Severe"), ] show_secondary: bool = ( math.isfinite(current_dd) and current_dd > 0.05 and (not math.isfinite(max_dd) or abs(current_dd - max_dd) > 0.5) ) p: Any = zone_scale_plot( zones=zones, scheme=scheme, x_lo=0.0, x_hi=x_end, marker=max_dd if math.isfinite(max_dd) else None, marker_label=f"Max {max_dd:.1f}%" if math.isfinite(max_dd) else "", secondary_marker=current_dd if show_secondary else None, secondary_label=f"Now {current_dd:.1f}%" if show_secondary else "", height=height, ) p.stylesheets = [*p.stylesheets, stylesheet] return p