Hero Metric

Instructions

Implementation Reference

• src/charts/hero.ts:575-603 (handler)

  Main handler function for the render_hero_metric tool. Renders a hero metric card with theme support and delegates to renderHeroWidget for variant-specific content (big_number, progress_ring, status, comparison, rank, countdown, threshold, breakdown, nps, orb, gem). Also adds HTML export and refresh buttons.

  export function renderHeroMetric(container: HTMLElement, payload: HeroPayload): void {
    const theme = resolveTheme(payload.theme, {
      palette: payload.palette,
      typography: payload.typography,
      effects: payload.effects,
    });
    if (theme) applyTheme(container, theme);
  
    container.className = "chart-view";
    container.innerHTML = `
      <div class="card chart-card hero-metric">
        <div class="chart-card__header">
          <div>
            <div class="chart-card__title${theme?.effects.shimmerTitle ? " shimmer-text" : ""}">${escapeHtml(payload.title || "Metric")}</div>
          </div>
        </div>
        <div class="hero-metric__body"></div>
      </div>
    `;
  
    const body = container.querySelector<HTMLElement>(".hero-metric__body")!;
    renderHeroWidget(body, payload);
  
    const card = container.querySelector<HTMLElement>(".chart-card")!;
    addHtmlExportButton(card, payload.title || "hero-metric");
    addRefreshButton(card, () => {
      (window as any).__mcpRefresh?.();
    });
  }

• src/charts/hero.ts:8-69 (schema)

  HeroPayload interface defining the full input schema for render_hero_metric. Supports multiple variants: big_number, progress_ring, status, comparison, rank, countdown, threshold, breakdown, nps, orb, gem.

  interface HeroPayload {
    type: "hero_metric";
    variant?: HeroVariant;
    title?: string;
    theme?: string;
    palette?: string;
    typography?: string;
    effects?: string;
  
    // big_number
    value?: string | number;
    unit?: string;
    label?: string;
    change?: number;
    changePeriod?: string;
    sparkline?: number[];
  
    // progress_ring (absorbed speedometer)
    progress?: number;
    color?: string;
    size?: "sm" | "md" | "lg" | "xl";
    style?: "ring" | "gauge";
  
    // status (absorbed live_counter)
    statusLevel?: "good" | "warn" | "bad";
    subsystems?: Array<{ name: string; status: "good" | "warn" | "bad" }>;
    count?: number;
    peak?: number;
  
    // comparison
    before?: number | string;
    after?: number | string;
    improvement?: number | string;
    beforeLabel?: string;
    afterLabel?: string;
  
    // rank
    rank?: number;
    total?: number;
    percentile?: number;
    rankChange?: number;
  
    // countdown
    segments?: Array<{ value: number; label: string }>;
    deadline?: string;
  
    // threshold
    max?: number;
    threshold?: number;
    zones?: Array<{ label: string; from: number; to: number; color: string }>;
  
    // breakdown
    items?: Array<{ label: string; value: number; color?: string }>;
  
    // nps
    rating?: "good" | "neutral" | "bad";
  
    // orb (uses value, label, color)
  
    // events (for ticker - not used, kept for future)
    events?: Array<{ text: string; time?: string; type?: string }>;
  }

• src/charts/shared.ts:188-193 (registration)

  registerChart function that registers chart types with their tool names and render functions into a central registry.

  export function registerChart(
    type: string,
    toolName: string,
    render: (root: HTMLElement, data: any) => void,
  ): void {
    CHART_REGISTRY[type] = { toolName, render };

• src/charts/hero.ts:605-605 (registration)

  Registration call linking the chart type 'hero_metric' to the tool name 'render_hero_metric' and the renderHeroMetric handler function.

  registerChart("hero_metric", "render_hero_metric", renderHeroMetric);

• src/charts/hero.ts:524-571 (helper)

  renderHeroWidget helper function that routes to the correct variant renderer based on the payload variant field (big_number, progress_ring, status, comparison, rank, countdown, threshold, breakdown, nps, orb, gem).

  export function renderHeroWidget(body: HTMLElement, p: any): void {
    const variant = p.variant || "big_number";
    switch (variant) {
      case "big_number":
        renderBigNumber(body, p);
        break;
      case "progress_ring":
        renderHeroRing(body, {
          value: p.value ?? "",
          unit: p.unit,
          label: p.label,
          progress: p.progress,
          color: p.color,
          size: p.size,
          style: p.style,
        });
        break;
      case "status":
        renderStatus(body, p);
        break;
      case "comparison":
        renderComparison(body, p);
        break;
      case "rank":
        renderRank(body, p);
        break;
      case "countdown":
        renderCountdown(body, p);
        break;
      case "threshold":
        renderThreshold(body, p);
        break;
      case "breakdown":
        renderBreakdown(body, p);
        break;
      case "nps":
        renderNps(body, p);
        break;
      case "orb":
        renderOrb(body, p);
        break;
      case "gem":
        renderGem(body, p);
        break;
      default:
        renderBigNumber(body, p);
    }
  }