@exxatdesignux/ui 0.2.19 → 0.3.0

package/template/components/key-metrics.tsx

@@ -1,1063 +1 @@
-"use client"
-
-/**
- * KeyMetrics — WCAG 2.1 AA reusable KPI panel
- *
- * Variants:
- *   "card"  (default) — shadcn Card wrapper with brand gradient fill
- *   "flat"            — full-width soft tint band (brand-tint → background) + bottom glow, no card chrome
- *
- * AA checklist:
- *  ✓ Trend text never relies on colour alone — icon + label (WCAG 1.4.1)
- *  ✓ `trend` matches signed change; `trendPolarity` flips sentiment when “up” is bad (see `docs/kpi-trend-pattern.md`)
- *  ✓ Trend icons have aria-hidden; chip `aria-label` uses `metricTrendAriaQualifier` (1.1.1)
- *  ✓ Select has accessible label via aria-label (4.1.2)
- *  ✓ Insight action button has descriptive text (4.1.2)
- *  ✓ Decorative dividers are aria-hidden (1.1.1)
- *  ✓ Contrast: value text foreground ≥ 17:1, trend colours ≥ 4.5:1 (1.4.3)
- */
-
-import * as React from "react"
-import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card"
-import {
-  Select,
-  SelectContent,
-  SelectItem,
-  SelectTrigger,
-  SelectValue,
-} from "@/components/ui/select"
-import { Separator } from "@/components/ui/separator"
-import { AskLeoShortcutKbds, useAskLeo } from "@/components/ask-leo-sidebar"
-import { Button } from "@/components/ui/button"
-import {
-  Tooltip,
-  TooltipContent,
-  TooltipTrigger,
-} from "@/components/ui/tooltip"
-import { cn } from "@/lib/utils"
-
-/** Tooltip + optional ⌘⌥K when the insight CTA is the default Ask Leo action. */
-function InsightAskLeoTooltip({
-  actionLabel,
-  children,
-}: {
-  actionLabel?: string
-  children: React.ReactNode
-}) {
-  const label = actionLabel ?? "Ask Leo"
-  const showShortcut = !actionLabel || actionLabel === "Ask Leo"
-  if (!showShortcut) {
-    return (
-      <Tooltip>
-        <TooltipTrigger asChild>{children}</TooltipTrigger>
-        <TooltipContent side="top">{label}</TooltipContent>
-      </Tooltip>
-    )
-  }
-  return (
-    <Tooltip>
-      <TooltipTrigger asChild>{children}</TooltipTrigger>
-      <TooltipContent side="top" className="flex flex-wrap items-center gap-1.5">
-        <span>{label}</span>
-        <AskLeoShortcutKbds />
-      </TooltipContent>
-    </Tooltip>
-  )
-}
-
-/* ── Types ────────────────────────────────────────────────────────────────── */
-
-/**
- * Whether an **up** arrow should read as “good news” for tinting and assistive text.
- * - **`higher_is_better`** (default) — revenue, pass rate, approved count: up = favorable.
- * - **`lower_is_better`** — defects, overdue, **low PBI / quality flags**: more flags + up arrow = unfavorable.
- * - **`informational`** — volume or mix only; keep arrows **muted** (direction without value judgment).
- */
-export type MetricTrendPolarity = "higher_is_better" | "lower_is_better" | "informational"
-
-export type MetricTrendTone = "positive" | "negative" | "muted"
-
-/** Maps `trend` + polarity to semantic tone for colours (arrow direction still follows `trend`). */
-export function metricTrendTone(
-  trend: "up" | "down" | "neutral",
-  polarity: MetricTrendPolarity = "higher_is_better",
-): MetricTrendTone {
-  if (trend === "neutral") return "muted"
-  if (polarity === "informational") return "muted"
-  if (polarity === "higher_is_better") {
-    return trend === "up" ? "positive" : "negative"
-  }
-  return trend === "up" ? "negative" : "positive"
-}
-
-/** Short clause for `aria-label` on the trend chip (paired with the delta string). */
-export function metricTrendAriaQualifier(
-  trend: "up" | "down" | "neutral",
-  polarity: MetricTrendPolarity = "higher_is_better",
-): string {
-  if (trend === "neutral") return "no net change"
-  if (polarity === "informational") {
-    return trend === "up" ? "increased" : "decreased"
-  }
-  if (polarity === "higher_is_better") {
-    return trend === "up" ? "increased, favorable" : "decreased, unfavorable"
-  }
-  return trend === "up" ? "increased, unfavorable" : "decreased, favorable"
-}
-
-export interface MetricItem {
-  /** Unique identifier for React keying */
-  id: string
-  /** Short label shown above the value */
-  label: string
-  /** Displayed value — e.g. "23", "98%", "1,250" */
-  value: string | number
-  /** Change delta — e.g. "+5", "-3", "+12" */
-  delta: string | number
-  /** Visual trend direction (arrow follows the signed change in the underlying metric). */
-  trend: "up" | "down" | "neutral"
-  /**
-   * How to **tint** the trend chip. Omit = **`higher_is_better`** (legacy behaviour).
-   * Arrows always match `trend`; sentiment colours flip for **`lower_is_better`**.
-   */
-  trendPolarity?: MetricTrendPolarity
-  /** Makes the cell a link */
-  href?: string
-  /** Makes the cell a button */
-  onClick?: () => void
-  /**
-   * "hero" — primary KPI (e.g. total count): larger value, same structure as siblings.
-   * "default" — standard KPI strip cell.
-   */
-  metricVariant?: "default" | "hero"
-}
-
-export interface MetricInsight {
-  /** Optional single line for custom copy; rail prefers `title` + `description` when both are set */
-  statement?: string
-  /** Card headline */
-  title: string
-  /** Supporting body copy */
-  description?: string
-  /** Optional deep-link for the ↗ button */
-  href?: string
-  /** CTA label — defaults to "Ask Leo" */
-  actionLabel?: string
-  /** Font Awesome class for the CTA icon — defaults to fa-wand-magic-sparkles */
-  actionIcon?: string
-  /** Callback for the CTA button */
-  onAction?: () => void
-  /** Severity determines the badge colour (default: warning) */
-  severity?: "warning" | "info" | "error"
-}
-
-export interface PeriodOption {
-  value: string
-  label: string
-}
-
-export interface KeyMetricsProps {
-  /**
-   * "card"  — shadcn Card with brand gradient (default)
-   * "flat"  — full-width gradient band, no card chrome
-   */
-  variant?: "card" | "flat" | "compact"
-  /** Panel title */
-  title?: string
-  /** Subtitle / description below title */
-  description?: string
-  /** Array of KPI items — by default split into rows of 3 */
-  metrics: MetricItem[]
-  /** When true, all metrics share one horizontal row (md+ and compact mobile grid) */
-  metricsSingleRow?: boolean
-  /**
-   * When true with `metricsSingleRow`, use a 2-column KPI grid so half-width dashboard cards
-   * fit 1–4 KPIs without horizontal overflow (pair rows on md+; 2-col grid on small screens).
-   * The insight rail (if any) stacks below the KPI grid instead of sitting beside it on md+.
-   */
-  metricsHalfWidthLayout?: boolean
-  /** Optional insight card — see `insightFullWidth` */
-  insight?: MetricInsight
-  /**
-   * When true, the insight sits on its own full-width row under the metrics (not a narrow side rail).
-   */
-  insightFullWidth?: boolean
-  /** Comparison-period options for the Select */
-  periods?: PeriodOption[]
-  /** Initially-selected period value */
-  defaultPeriod?: string
-  /** Called with the new period value when the Select changes */
-  onPeriodChange?: (period: string) => void
-  /** When false, hides the title/description/period-selector header row (default: true) */
-  showHeader?: boolean
-  /**
-   * Tighter insight card: one short title + line of body, no vertical filler;
-   * aligns visually with a single-row KPI band.
-   */
-  insightCompact?: boolean
-  className?: string
-}
-
-/**
- * KPI grid column step patterns — Tailwind v4 container-query classes.
- *
- * We deliberately AVOID `repeat(auto-fit, minmax(...))` here because it
- * produces awkward "N + leftover" layouts at intermediate widths (e.g. 3
- * tiles in row 1 + 1 lonely tile in row 2 for a 4-KPI strip). Instead we
- * step the column count through values that evenly divide the row size:
- * 1 → 2 → 4 for a 4-KPI strip (3 is skipped on purpose).
- *
- * The breakpoints are container-query based (`@[Xrem]:…`) so they react to
- * the metrics strip's OWN width, not the viewport — that's what makes the
- * 2×2 fallback kick in when the primary sidebar + secondary panel are
- * both open and the strip column is ~360 px wide, even on a 1280 px display.
- *
- * `metricsHalfWidthLayout` = strip shares its row with the insight rail
- * (3fr / 2fr split). Tighter breakpoints because available width is ~60%
- * of the section.
- */
-/**
- * Flat KPI hairlines — cell borders only (no grid gap fill / no surface).
- * Four tiles: default 4-across verticals; 2×2 hairlines only when @container is narrow.
- */
-function flatMetricsHairlineClass(
-  itemCount: number,
-  metricsHalfWidthLayout: boolean,
-): string {
-  if (itemCount <= 1) return "gap-0"
-
-  const childBorder = "[&>*]:border-[color:var(--key-metrics-flat-divider)]"
-
-  if (itemCount === 2) {
-    return cn("gap-0", childBorder, "[&>*:first-child]:border-r")
-  }
-
-  if (itemCount === 4) {
-    const narrow2x2 = metricsHalfWidthLayout
-      ? "@[max-width:25.99rem]"
-      : "@[max-width:29.99rem]"
-    return cn(
-      "gap-0",
-      childBorder,
-      /* Wide strip (matches `@[30rem]:grid-cols-4`) — verticals between all tiles, no horizontal */
-      "[&>*:not(:last-child)]:border-r",
-      /* Narrow strip (`@[18rem]`–`@[30rem]` 2×2) */
-      `${narrow2x2}:[&>*:not(:last-child)]:border-r-0`,
-      `${narrow2x2}:[&>*:nth-child(odd)]:border-r`,
-      `${narrow2x2}:[&>*:not(:nth-last-child(-n+2))]:border-b`,
-    )
-  }
-
-  return cn("gap-0", childBorder, "[&>*:not(:last-child)]:border-r")
-}
-
-function metricsRowColumnsClass(rowLength: number, metricsHalfWidthLayout: boolean): string {
-  const half = metricsHalfWidthLayout
-  switch (rowLength) {
-    case 1:
-      return "grid-cols-1"
-    case 2:
-      return half
-        ? "grid-cols-1 @[14rem]:grid-cols-2"
-        : "grid-cols-1 @[18rem]:grid-cols-2"
-    case 3:
-      // 3 tiles divide evenly already — step 1 → 3.
-      return half
-        ? "grid-cols-1 @[18rem]:grid-cols-3"
-        : "grid-cols-1 @[24rem]:grid-cols-3"
-    case 4:
-      // Step 1 → 2 (2×2 grid) → 4. Skip 3 — that's the awkward 3+1 layout.
-      // Aggressive 4-col thresholds so the strip fits all four tiles even
-      // when the primary sidebar + secondary panel + insight rail are all
-      // expanded (typical question-bank layout puts the KPI grid at ~27rem).
-      return half
-        ? "grid-cols-1 @[14rem]:grid-cols-2 @[26rem]:grid-cols-4"
-        : "grid-cols-1 @[18rem]:grid-cols-2 @[30rem]:grid-cols-4"
-    default:
-      // 5+ KPIs (`exxat-kpi-max-four` caps the strip at 4, but key-metrics
-      // is a generic primitive — fall back to a sensible step). 1 → 2 → 3 → 6.
-      return half
-        ? "grid-cols-1 @[14rem]:grid-cols-2 @[26rem]:grid-cols-3 @[40rem]:grid-cols-6"
-        : "grid-cols-1 @[18rem]:grid-cols-2 @[30rem]:grid-cols-3 @[56rem]:grid-cols-6"
-  }
-}
-
-/* ── Default data ─────────────────────────────────────────────────────────── */
-
-const DEFAULT_PERIODS: PeriodOption[] = [
-  { value: "week",    label: "vs last week"    },
-  { value: "month",   label: "vs last month"   },
-  { value: "quarter", label: "vs last quarter" },
-  { value: "year",    label: "vs last year"    },
-]
-
-/* ── Sub-components ───────────────────────────────────────────────────────── */
-
-/** Single KPI cell inside the metrics grid */
-const MetricCell = React.memo(function MetricCell({
-  label,
-  value,
-  delta,
-  trend,
-  trendPolarity = "higher_is_better",
-  href,
-  onClick,
-  metricVariant = "default",
-  dense = false,
-  edgeGutter = true,
-}: Omit<MetricItem, "id"> & { dense?: boolean; edgeGutter?: boolean }) {
-  const isUp       = trend === "up"
-  const isDown     = trend === "down"
-  const tone        = metricTrendTone(trend, trendPolarity)
-  const isInteractive = !!(href || onClick)
-  const isHero     = metricVariant === "hero"
-
-  const inner = (
-    <>
-      {/* Label row — min-height = 2 lines so values align when some titles wrap */}
-      <div
-        className={cn(
-          "grid grid-cols-[minmax(0,1fr)_auto] items-start gap-x-2 gap-y-0.5",
-          dense ? "min-h-[2.125rem]" : "min-h-[2.625rem]",
-        )}
-      >
-        <p
-          className={cn(
-            "min-w-0 text-muted-foreground leading-snug wrap-break-word",
-            dense ? "text-xs" : "text-sm",
-            isHero && "font-medium",
-          )}
-        >
-          {label}
-        </p>
-        {isInteractive ? (
-          <span className="mt-0.5 inline-flex shrink-0" aria-hidden="true">
-            <i className="fa-light fa-arrow-right text-xs text-foreground/70 transition-colors duration-150 group-hover:text-interactive-hover-foreground sm:group-hover:translate-x-0.5" />
-          </span>
-        ) : null}
-      </div>
-
-      {/* Value + trend badge */}
-      <div className="flex items-baseline gap-2 flex-wrap">
-        <span
-          className={cn(
-            "font-bold tabular-nums leading-none text-foreground",
-            dense
-              ? isHero
-                ? "text-lg sm:text-xl"
-                : "text-base sm:text-lg"
-              : isHero
-                ? "text-2xl sm:text-[1.625rem]"
-                : "text-xl sm:text-2xl",
-          )}
-        >
-          {value}
-        </span>
-
-        {/* Trend chip — icon + text, never colour-only (WCAG 1.4.1) */}
-        <span
-          className={cn(
-            "inline-flex items-center gap-1 font-medium leading-none",
-            dense ? "text-xs sm:text-xs" : "text-xs sm:text-sm",
-            tone === "positive" && "text-chart-2",
-            tone === "negative" && "text-destructive",
-            tone === "muted" && "text-muted-foreground",
-          )}
-          aria-label={`${metricTrendAriaQualifier(trend, trendPolarity)} ${delta}`}
-        >
-          {isUp   && <i className="fa-light fa-arrow-trend-up text-[0.8rem]"   aria-hidden="true" />}
-          {isDown && <i className="fa-light fa-arrow-trend-down text-[0.8rem]" aria-hidden="true" />}
-          {!isUp && !isDown && <i className="fa-light fa-minus text-[0.8rem]"  aria-hidden="true" />}
-          <span>{delta}</span>
-        </span>
-      </div>
-    </>
-  )
-
-  const sharedClass = cn(
-    "group flex min-w-0 flex-col gap-2 text-left outline-none",
-    edgeGutter && "first:pl-0 last:pr-0",
-    dense ? "gap-1.5 px-2 py-2 sm:px-3 sm:py-3" : "gap-2 px-3 py-3 sm:px-5 sm:py-4",
-    isHero && "gap-2.5",
-    isInteractive && [
-      "cursor-pointer transition-colors duration-150",
-      "hover:bg-foreground/5",
-      "focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring",
-    ]
-  )
-
-  if (href) {
-    return (
-      <a href={href} className={sharedClass} aria-label={`${label}: ${value}`}>
-        {inner}
-      </a>
-    )
-  }
-
-  if (onClick) {
-    return (
-      <button type="button" onClick={onClick} className={sharedClass} aria-label={`${label}: ${value}`}>
-        {inner}
-      </button>
-    )
-  }
-
-  return <div className={sharedClass}>{inner}</div>
-})
-
-/** Body line for rail: `description`, else optional `statement` */
-function insightRailBody(insight: MetricInsight): string {
-  const d = insight.description?.trim()
-  if (d) return d
-  return insight.statement?.trim() ?? ""
-}
-
-/**
- * Rail insight: severity badge + title + description + optional ↗, Ask Leo (no rule between copy and action).
- */
-function InsightRailStatementAction({
-  insight,
-  compact,
-}: {
-  insight: MetricInsight
-  compact: boolean
-}) {
-  const badgeSize = compact ? "sm" : "default"
-  const surface = compact
-    ? "border border-border/50 bg-gradient-to-b from-muted/35 to-card"
-    : "bg-card"
-  const body = insightRailBody(insight)
-
-  return (
-    <Card
-      role="region"
-      aria-label="Insight"
-      className={cn(
-        "flex h-full min-h-0 flex-col overflow-hidden rounded-lg border-0 p-0 shadow-none ring-1 ring-foreground/8",
-        surface
-      )}
-    >
-      {/* flex-1 + mt-auto on the CTA: copy stays top-aligned when the rail stretches to KPI height */}
-      <div className="flex min-h-0 flex-1 flex-col px-3 py-3 sm:px-4 sm:py-4">
-        <div className="flex items-start gap-2.5">
-          <InsightBadge severity={insight.severity} size={badgeSize} />
-          <div className="min-w-0 flex-1">
-            <p className="text-sm font-semibold leading-snug text-foreground">{insight.title}</p>
-            {body ? (
-              <p className="mt-1 text-sm leading-snug text-muted-foreground">{body}</p>
-            ) : null}
-          </div>
-          {insight.href && (
-            <a
-              href={insight.href}
-              className="mt-0.5 shrink-0 text-muted-foreground transition-colors hover:text-interactive-hover-foreground focus-visible:rounded-sm focus-visible:outline-2 focus-visible:outline-ring"
-              aria-label={`Open ${insight.title} — details`}
-            >
-              <i className="fa-light fa-arrow-up-right text-xs" aria-hidden="true" />
-            </a>
-          )}
-        </div>
-
-        <div className="mt-auto flex shrink-0 justify-end pt-3">
-          <InsightAskLeoTooltip actionLabel={insight.actionLabel}>
-            <Button
-              variant={compact ? "outline" : "ghost"}
-              size="sm"
-              className={cn(
-                "h-8 w-full gap-1.5 text-xs sm:w-auto",
-                compact
-                  ? "border-border/60 bg-background px-3 text-foreground hover:bg-background"
-                  : "px-3 text-muted-foreground hover:text-interactive-hover-foreground"
-              )}
-              onClick={insight.onAction}
-              aria-label={insight.actionLabel ?? "Ask Leo"}
-            >
-              <i
-                className={
-                  insight.actionIcon
-                    ? `fa-light ${insight.actionIcon} text-xs`
-                    : "fa-duotone fa-solid fa-star-christmas text-xs text-brand"
-                }
-                aria-hidden="true"
-              />
-              {insight.actionLabel ?? "Ask Leo"}
-            </Button>
-          </InsightAskLeoTooltip>
-        </div>
-      </div>
-    </Card>
-  )
-}
-
-/** Severity icon badge for the insight card */
-
-function InsightBadge({
-  severity = "warning",
-  size = "default",
-}: {
-  severity?: MetricInsight["severity"]
-  size?: "default" | "sm"
-}) {
-  const styles = {
-    warning: {
-      bg: "bg-[var(--insight-severity-warning-bg)]",
-      icon: "fa-circle-exclamation",
-      color: "text-[var(--insight-severity-warning-fg)]",
-    },
-    info: {
-      bg: "bg-[var(--insight-severity-info-bg)]",
-      icon: "fa-circle-info",
-      color: "text-[var(--insight-severity-info-fg)]",
-    },
-    error: { bg: "bg-destructive/15", icon: "fa-circle-xmark", color: "text-destructive" },
-  }[severity]
-
-  return (
-    <span
-      className={cn(
-        "inline-flex shrink-0 items-center justify-center rounded-full",
-        size === "sm" ? "h-6 w-6 text-xs" : "h-7 w-7 text-sm",
-        styles.bg,
-        styles.color
-      )}
-      aria-hidden="true"
-    >
-      <i className={`fa-light ${styles.icon}`} />
-    </span>
-  )
-}
-
-/* ── Shared inner content ─────────────────────────────────────────────────── */
-
-interface InnerProps {
-  title: string
-  description: string
-  period: string
-  periods: PeriodOption[]
-  metrics: MetricItem[]
-  rows: MetricItem[][]
-  insight?: MetricInsight
-  onPeriodChange: (v: string) => void
-  /** Extra padding class injected by flat variant */
-  innerPadding?: string
-  /** When false, the header (title/description/period select) is hidden */
-  showHeader?: boolean
-  insightCompact?: boolean
-  insightFullWidth?: boolean
-  metricsSingleRow?: boolean
-  /** Tighter KPI cells + 2-col mobile grid (half-width dashboard card). */
-  metricsHalfWidthLayout?: boolean
-  /** Opaque fill behind each KPI cell when using hairline grid gaps (below `lg`). */
-  metricsCellSurfaceClassName?: string
-  /** Flat list-page band: softer dividers + tinted cells on a lavender-tinted surface */
-  surfaceVariant?: "default" | "flat"
-}
-
-function KeyMetricsInner({
-  title,
-  description,
-  period,
-  periods,
-  metrics,
-  rows,
-  insight,
-  onPeriodChange,
-  innerPadding = "",
-  showHeader = true,
-  insightCompact = false,
-  insightFullWidth = false,
-  metricsSingleRow = false,
-  metricsHalfWidthLayout = false,
-  metricsCellSurfaceClassName = "bg-background",
-  surfaceVariant = "default",
-}: InnerProps) {
-  const isFlatBand = surfaceVariant === "flat"
-  const metricsGridClassName = isFlatBand
-    ? flatMetricsHairlineClass(metrics.length, metricsHalfWidthLayout)
-    : "gap-px bg-border"
-  /** Side-by-side KPI + insight rail (md+). Disabled for half-width dashboard cards — insight stacks below. */
-  const insightSideBySide = insight && !insightFullWidth && !metricsHalfWidthLayout
-  const stackedRailInsight = insight && !insightFullWidth && metricsHalfWidthLayout
-
-  return (
-    <div data-slot="key-metrics" className="contents">
-      {/* ── Header ──────────────────────────────────────────────────── */}
-      {showHeader && (
-        <div className={cn(
-          "flex flex-col gap-2 pb-3",
-          "sm:flex-row sm:items-center sm:justify-between sm:gap-4",
-          innerPadding
-        )}>
-          <div>
-            <p className="text-base font-semibold text-foreground leading-tight">{title}</p>
-            <p className="mt-0.5 text-sm text-muted-foreground">{description}</p>
-          </div>
-
-          {/* Period selector — align="end" keeps dropdown flush-right */}
-          <Select value={period} onValueChange={onPeriodChange}>
-            <SelectTrigger
-              className="h-8 w-full sm:w-auto sm:min-w-[9rem] shrink-0 text-sm"
-              aria-label="Select comparison period"
-            >
-              <SelectValue />
-            </SelectTrigger>
-            <SelectContent align="end" sideOffset={4}>
-              {periods.map((p) => (
-                <SelectItem key={p.value} value={p.value}>
-                  {p.label}
-                </SelectItem>
-              ))}
-            </SelectContent>
-          </Select>
-        </div>
-      )}
-
-      {/* ── Body: metrics grid + optional insight ───────────────────── */}
-      <div
-        className={cn(
-          "flex flex-col gap-0",
-          /* 60% KPIs / 40% insight (3fr:2fr); lg+ only so phones/tablets stack KPIs + insight */
-          insightSideBySide &&
-            "lg:grid lg:grid-cols-[minmax(0,3fr)_minmax(13rem,2fr)] lg:items-stretch lg:gap-x-6 lg:gap-y-0",
-          innerPadding
-        )}
-      >
-
-        {/* Metrics section — self-start so KPI cells don’t stretch when the insight column is taller */}
-        <div
-          className={cn(
-            "min-w-0 lg:flex lg:min-h-0 lg:flex-col",
-            !insightSideBySide && "w-full",
-            insightSideBySide && "lg:self-start"
-          )}
-        >
-          {/*
-            Phone (<md): one column. Tablet (md–lg): 2-column grid (e.g. 2×2 for four KPIs).
-            Hairline separators use gap-px + opaque cell surfaces (divide-* breaks for 2-col order).
-            Half-width dashboard cards keep divide-x + optional template columns.
-          */}
-          {metricsHalfWidthLayout ? (
-            <div
-              className={cn(
-                "@container/metrics-strip grid lg:hidden",
-                metricsSingleRow
-                  ? metricsRowColumnsClass(metrics.length, /* half */ true)
-                  : "grid-cols-2",
-                metricsGridClassName,
-              )}
-            >
-              {metrics.map((m) => (
-                <div key={m.id} className={cn("min-w-0", metricsCellSurfaceClassName)}>
-                  <MetricCell {...m} dense edgeGutter={false} />
-                </div>
-              ))}
-            </div>
-          ) : (
-            <div
-              className={cn(
-                "@container/metrics-strip grid lg:hidden",
-                metricsRowColumnsClass(metrics.length, /* half */ false),
-                metricsGridClassName,
-              )}
-            >
-              {metrics.map((m) => (
-                <div key={m.id} className={cn("min-w-0", metricsCellSurfaceClassName)}>
-                  <MetricCell {...m} dense={false} edgeGutter={false} />
-                </div>
-              ))}
-            </div>
-          )}
-
-          {/*
-            lg+: row-by-row container-queried grid. Uses a `gap-px + bg` hairline
-            instead of `divide-x` so dividers render correctly when the row wraps
-            from 4-across to a 2×2 grid (the awkward 3+1 layout is skipped — see
-            `metricsRowColumnsClass`).
-          */}
-          <div className="@container/metrics-strip hidden lg:block">
-            {rows.map((row, rowIdx) => (
-              <React.Fragment key={rowIdx}>
-                {rowIdx > 0 && !isFlatBand && (
-                  <Separator aria-hidden="true" className="my-1" />
-                )}
-                <div
-                  className={cn(
-                    "grid",
-                    metricsRowColumnsClass(row.length, metricsHalfWidthLayout),
-                    isFlatBand
-                      ? flatMetricsHairlineClass(row.length, metricsHalfWidthLayout)
-                      : metricsGridClassName,
-                  )}
-                >
-                  {row.map((m) => (
-                    <div key={m.id} className={cn("min-w-0", metricsCellSurfaceClassName)}>
-                      <MetricCell {...m} dense={metricsHalfWidthLayout} edgeGutter={false} />
-                    </div>
-                  ))}
-                </div>
-              </React.Fragment>
-            ))}
-          </div>
-        </div>
-
-        {/* Insight card — only rendered when data provided */}
-        {insight && (
-          <>
-            {insightFullWidth ? (
-              <Separator
-                aria-hidden="true"
-                className={cn("my-4 w-full", isFlatBand && "bg-foreground/[0.06]")}
-              />
-            ) : stackedRailInsight ? (
-              <Separator
-                aria-hidden="true"
-                className={cn("my-4 w-full", isFlatBand && "bg-foreground/[0.06]")}
-              />
-            ) : (
-              <Separator
-                aria-hidden="true"
-                className={cn("my-3 lg:hidden", isFlatBand && "bg-foreground/[0.055]")}
-              />
-            )}
-
-            <div
-              className={cn(
-                "flex min-h-0 min-w-0 w-full flex-col",
-                /* Divider + padding replace vertical Separator so grid stays 2 columns */
-                insightSideBySide &&
-                  !insightFullWidth &&
-                  cn(
-                    "lg:h-full lg:pl-6",
-                    /* Flat band: insight card ring is the divider — skip `border-l` (double line). */
-                    !isFlatBand && "lg:border-l lg:border-border",
-                  )
-              )}
-            >
-              {insight && !insightFullWidth ? (
-                <InsightRailStatementAction insight={insight} compact={insightCompact} />
-              ) : (
-                <Card
-                  role="region"
-                  aria-label="Insight"
-                  className={cn(
-                    "overflow-hidden rounded-lg p-0 ring-1 ring-foreground/8 shadow-none",
-                    "flex min-h-0 flex-col bg-muted/25"
-                  )}
-                >
-                  {insightCompact ? (
-                    <div className="flex min-h-0 flex-1 flex-col gap-4 p-4 md:flex-row md:items-center md:justify-between md:gap-8 md:p-5">
-                      <div className="flex min-w-0 flex-1 flex-col gap-2">
-                        <div className="flex items-start gap-2.5">
-                          <InsightBadge severity={insight.severity} size="sm" />
-                          <div className="flex min-w-0 flex-1 items-start justify-between gap-2">
-                            <p className="text-base font-semibold leading-tight text-foreground">
-                              {insight.title}
-                            </p>
-                            {insight.href && (
-                              <a
-                                href={insight.href}
-                                className="shrink-0 text-muted-foreground transition-colors hover:text-interactive-hover-foreground focus-visible:rounded-sm focus-visible:outline-2 focus-visible:outline-ring"
-                                aria-label={`Open ${insight.title} — details`}
-                              >
-                                <i className="fa-light fa-arrow-up-right text-xs" aria-hidden="true" />
-                              </a>
-                            )}
-                          </div>
-                        </div>
-                        {insight.description ? (
-                          <p className="text-sm leading-relaxed text-muted-foreground">
-                            {insight.description}
-                          </p>
-                        ) : null}
-                      </div>
-                      <div className="flex w-full shrink-0 md:w-auto">
-                        <InsightAskLeoTooltip actionLabel={insight.actionLabel}>
-                          <Button
-                            variant="ghost"
-                            size="sm"
-                            className="h-9 w-full gap-1.5 px-4 text-xs text-muted-foreground hover:text-interactive-hover-foreground md:min-w-[8.5rem]"
-                            onClick={insight.onAction}
-                            aria-label={insight.actionLabel ?? "Ask Leo"}
-                          >
-                            <i
-                              className={insight.actionIcon ? `fa-light ${insight.actionIcon} text-xs` : "fa-duotone fa-solid fa-star-christmas text-xs text-brand"}
-                              aria-hidden="true"
-                            />
-                            {insight.actionLabel ?? "Ask Leo"}
-                          </Button>
-                        </InsightAskLeoTooltip>
-                      </div>
-                    </div>
-                  ) : (
-                    <div className="flex min-h-0 flex-1 flex-col gap-4 p-4 md:flex-row md:items-center md:justify-between md:gap-8 md:p-5">
-                      <div className="flex min-w-0 flex-1 flex-col gap-3">
-                        <div className="flex items-start gap-3">
-                          <InsightBadge severity={insight.severity} />
-                          <div className="flex min-w-0 flex-1 items-start justify-between gap-2">
-                            <p className="text-base font-semibold leading-snug text-foreground">
-                              {insight.title}
-                            </p>
-                            {insight.href && (
-                              <a
-                                href={insight.href}
-                                className="shrink-0 text-muted-foreground transition-colors hover:text-interactive-hover-foreground focus-visible:rounded-sm focus-visible:outline-2 focus-visible:outline-ring"
-                                aria-label={`Open ${insight.title} — details`}
-                              >
-                                <i className="fa-light fa-arrow-up-right text-xs" aria-hidden="true" />
-                              </a>
-                            )}
-                          </div>
-                        </div>
-                        {insight.description ? (
-                          <p className="text-sm leading-relaxed text-muted-foreground">
-                            {insight.description}
-                          </p>
-                        ) : null}
-                      </div>
-                      <div className="flex w-full shrink-0 md:w-auto">
-                        <InsightAskLeoTooltip actionLabel={insight.actionLabel}>
-                          <Button
-                            variant="ghost"
-                            size="sm"
-                            className="h-9 w-full gap-1.5 px-4 text-xs text-muted-foreground hover:text-interactive-hover-foreground md:min-w-[8.5rem]"
-                            onClick={insight.onAction}
-                            aria-label={insight.actionLabel ?? "Ask Leo"}
-                          >
-                            <i
-                              className={insight.actionIcon ? `fa-light ${insight.actionIcon} text-xs` : "fa-duotone fa-solid fa-star-christmas text-xs text-brand"}
-                              aria-hidden="true"
-                            />
-                            {insight.actionLabel ?? "Ask Leo"}
-                          </Button>
-                        </InsightAskLeoTooltip>
-                      </div>
-                    </div>
-                  )}
-                </Card>
-              )}
-            </div>
-          </>
-        )}
-      </div>
-    </div>
-  )
-}
-
-function chunkMetricPairs(metrics: MetricItem[]): MetricItem[][] {
-  const out: MetricItem[][] = []
-  for (let i = 0; i < metrics.length; i += 2) out.push(metrics.slice(i, i + 2))
-  return out
-}
-
-/* ── Main component ───────────────────────────────────────────────────────── */
-
-export function KeyMetrics({
-  variant       = "card",
-  title         = "Key Metrics",
-  description   = "Overview of performance indicators",
-  metrics       = [],
-  insight,
-  periods       = DEFAULT_PERIODS,
-  defaultPeriod = "week",
-  onPeriodChange,
-  showHeader    = true,
-  insightCompact = false,
-  insightFullWidth = false,
-  metricsSingleRow = false,
-  metricsHalfWidthLayout = false,
-  className,
-}: KeyMetricsProps) {
-  const [period, setPeriod] = React.useState(defaultPeriod)
-  const { toggle: toggleAskLeo } = useAskLeo()
-
-  function handlePeriodChange(v: string) {
-    setPeriod(v)
-    onPeriodChange?.(v)
-  }
-
-  /* Split metrics into rows of 3, or paired rows when half-width + single row, else one row */
-  const rows: MetricItem[][] = metricsSingleRow
-    ? metrics.length
-      ? metricsHalfWidthLayout
-        ? chunkMetricPairs(metrics)
-        : [metrics]
-      : []
-    : (() => {
-        const out: MetricItem[][] = []
-        for (let i = 0; i < metrics.length; i += 3) {
-          out.push(metrics.slice(i, i + 3))
-        }
-        return out
-      })()
-
-  const metricsCellSurfaceClassName =
-    variant === "flat"
-      ? "bg-transparent"
-      : "bg-card dark:bg-transparent"
-
-  const innerProps: InnerProps = {
-    title,
-    description,
-    period,
-    periods,
-    metrics,
-    rows,
-    insight,
-    onPeriodChange: handlePeriodChange,
-    insightCompact,
-    insightFullWidth,
-    metricsSingleRow,
-    metricsHalfWidthLayout,
-    metricsCellSurfaceClassName,
-    surfaceVariant: variant === "flat" ? "flat" : "default",
-  }
-
-  /*
-   * ── GLOW GUIDELINE ────────────────────────────────────────────────────────
-   * The bottom-glow treatment is a deliberate design signal. Use it only for:
-   *
-   *   1. AI / intelligence surfaces  — e.g. AI Insights, Ask Leo responses,
-   *      any card that surfaces machine-generated content.
-   *      Opacity: 0.12–0.16  (subtle; the glow should not dominate)
-   *
-   *   2. Designer-designated hero sections — e.g. Key Metrics (the primary
-   *      KPI band), onboarding completion, or any section the product team
-   *      explicitly wants to "elevate" visually.
-   *      Opacity: 0.18–0.24  (more pronounced; intentional focal point)
-   *
-   * Do NOT add glow to:
-   *   • Standard data/content cards  (Tasks, Activity, Learn, Charts…)
-   *   • Navigation or shell elements
-   *   • Cards that already use a coloured border or badge for status
-   *
-   * Implementation:
-   *   style={{ background: "radial-gradient(ellipse 110% 90% at 50% 100%,
-   *     oklch(from var(--brand-color) l c h / <opacity>) 0%, transparent 68%)" }}
-   *   + className="overflow-hidden"  ← required to clip the gradient
-   * ─────────────────────────────────────────────────────────────────────────
-   */
-  const glowStyle: React.CSSProperties = {
-    background: "var(--key-metrics-card-glow-radial)",
-  }
-
-  /** List-page KPI band — transparent; only `--key-metrics-flat-band-radial` glow. */
-  const flatBandStyle: React.CSSProperties = {
-    background: "var(--key-metrics-flat-band-radial)",
-    boxShadow: "var(--key-metrics-flat-band-shadow)",
-  }
-
-  /* ── Card variant — ChartCard-style chrome ───────────────────────────── */
-  if (variant === "card") {
-    return (
-      <Card className={cn("shadow-xs overflow-hidden flex flex-col", className)} style={glowStyle}>
-        <CardHeader className={cn("shrink-0 pb-2", metricsHalfWidthLayout && "space-y-2")}>
-          <div
-            className={cn(
-              "flex gap-2",
-              metricsHalfWidthLayout
-                ? "flex-col min-[400px]:flex-row min-[400px]:items-start min-[400px]:justify-between"
-                : "items-start",
-            )}
-          >
-            <div className="flex-1 min-w-0">
-              <CardTitle className="text-sm font-semibold leading-tight">{title}</CardTitle>
-              <CardDescription className="text-xs mt-0.5">{description}</CardDescription>
-            </div>
-            <div className="flex flex-wrap items-center gap-1.5 shrink-0">
-              <InsightAskLeoTooltip actionLabel="Ask Leo">
-                <Button
-                  size="sm"
-                  variant="outline"
-                  className="h-7 shrink-0 text-xs gap-1.5 px-2"
-                  aria-label="Ask Leo about these metrics"
-                  onClick={toggleAskLeo}
-                  type="button"
-                >
-                  <i className="fa-duotone fa-solid fa-star-christmas text-xs text-brand" aria-hidden="true" />
-                  <span>Ask Leo</span>
-                </Button>
-              </InsightAskLeoTooltip>
-              <Select value={period} onValueChange={handlePeriodChange}>
-                <SelectTrigger
-                  size="sm"
-                  className="w-auto min-w-[9rem] shrink-0 text-sm"
-                  aria-label="Select comparison period"
-                >
-                  <SelectValue />
-                </SelectTrigger>
-                <SelectContent align="end" sideOffset={4}>
-                  {periods.map((p) => (
-                    <SelectItem key={p.value} value={p.value}>
-                      {p.label}
-                    </SelectItem>
-                  ))}
-                </SelectContent>
-              </Select>
-            </div>
-          </div>
-        </CardHeader>
-        <CardContent className="flex-1 pb-4">
-          <KeyMetricsInner {...innerProps} showHeader={false} />
-        </CardContent>
-      </Card>
-    )
-  }
-
-  /* ── Compact variant — card chrome, no header, metrics only ──────────── */
-  if (variant === "compact") {
-    return (
-      <Card className={cn("shadow-xs overflow-hidden", className)} style={glowStyle}>
-        <CardContent className="py-3 px-4">
-          <KeyMetricsInner {...innerProps} showHeader={false} />
-        </CardContent>
-      </Card>
-    )
-  }
-
-  /* ── Flat variant — no surface; bottom brand glow only ── */
-  return (
-    <section
-      aria-label={title}
-      className={cn("relative w-full overflow-hidden pt-5 pb-8", className)}
-      style={flatBandStyle}
-    >
-      <KeyMetricsInner
-        {...innerProps}
-        innerPadding="px-4 lg:px-6"
-        showHeader={showHeader}
-      />
-    </section>
-  )
-}
-
-/**
- * KeyMetricsContent — renders just the metrics grid + optional insight panel.
- * No card wrapper, no header, no period selector.
- * Designed for embedding inside a ChartCard with tabOptions period tabs.
- */
-export function KeyMetricsContent({
-  metrics = [],
-  insight,
-  insightCompact = false,
-  insightFullWidth = false,
-}: Pick<KeyMetricsProps, "metrics" | "insight" | "insightCompact" | "insightFullWidth">) {
-  const rows: MetricItem[][] = []
-  for (let i = 0; i < metrics.length; i += 3) rows.push(metrics.slice(i, i + 3))
-
-  return (
-    <KeyMetricsInner
-      title=""
-      description=""
-      period=""
-      periods={[]}
-      metrics={metrics}
-      rows={rows}
-      insight={insight}
-      onPeriodChange={() => {}}
-      showHeader={false}
-      insightCompact={insightCompact}
-      insightFullWidth={insightFullWidth}
-      metricsCellSurfaceClassName="bg-card dark:bg-transparent"
-    />
-  )
-}
+export * from "@exxatdesignux/ui/components/key-metrics"