@exxatdesignux/ui 0.2.19 → 0.4.0

package/src/components/ui/key-metrics.tsx

@@ -0,0 +1,1133 @@
+"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 "./card"
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "./select"
+import { Separator } from "./separator"
+import { Button } from "./button"
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from "./tooltip"
+import { cn } from "../../lib/utils"
+import { useKeyMetricsContext } from "./key-metrics-context"
+
+export {
+  KeyMetricsProvider,
+  useKeyMetricsContext,
+  type KeyMetricsContextValue,
+} from "./key-metrics-context"
+
+/**
+ * Tooltip around the default insight CTA. Renders the shortcut hint
+ * injected by `KeyMetricsProvider` (typically `⌘⌥K` for Ask Leo) when
+ * the CTA still uses the default action label — i.e. the consumer did
+ * NOT override `actionLabel` on the individual `MetricInsight`. Any
+ * custom `actionLabel` ("Open ticket", "Acknowledge", …) suppresses
+ * the shortcut hint since it no longer maps to the default chord.
+ */
+function InsightDefaultTooltip({
+  actionLabel,
+  children,
+}: {
+  actionLabel?: string
+  children: React.ReactNode
+}) {
+  const { shortcutHint, defaultActionLabel = "Ask Leo" } = useKeyMetricsContext()
+  const label = actionLabel ?? defaultActionLabel
+  const showShortcut =
+    !!shortcutHint && (!actionLabel || actionLabel === defaultActionLabel)
+  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>
+        {shortcutHint}
+      </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 **count** for the trend chip — e.g. `"+5"`, `"-3"`, `"+12%"`.
+   *
+   * Pass an **empty string** (or `0`) when there is no comparison delta to show.
+   * In that case the **trend chip is hidden entirely** (the previous `—` placeholder
+   * is dropped) — see `MetricCell`. Put contextual prose like
+   * `"left + right"` / `"vs last week"` in `description`, **never** here.
+   */
+  delta: string | number
+  /**
+   * Visual trend direction (arrow follows the signed change in the underlying metric).
+   * `"neutral"` paired with an empty `delta` suppresses the chip — use `description`
+   * for any caption you want to show below the value instead.
+   */
+  trend: "up" | "down" | "neutral"
+  /**
+   * Optional short caption rendered **below** the value + trend row (muted, small).
+   * Use for **what** the number means or **how** it breaks down
+   * (e.g. `"left + right"`, `"vs last week"`, `"across 4 sites"`) — NOT for delta counts.
+   */
+  description?: string
+  /**
+   * 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-e-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 library 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",
+  description,
+  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"
+
+  // Hide the trend chip entirely when there's no direction *and* no count to
+  // surface. This avoids the noisy `—` placeholder for purely informational
+  // metrics — see `docs/kpi-trend-pattern.md`.
+  const deltaText = typeof delta === "number"
+    ? (delta === 0 ? "" : String(delta))
+    : String(delta ?? "").trim()
+  const showTrendChip = isUp || isDown || deltaText.length > 0
+
+  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 + count, never colour-only (WCAG 1.4.1).
+            Suppressed when both `trend === "neutral"` and `delta` is empty
+            (see `showTrendChip` above) so informational KPIs render cleanly. */}
+        {showTrendChip && (
+          <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)} ${deltaText}`.trim()}
+          >
+            {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 && deltaText.length > 0 && (
+              <i className="fa-light fa-minus text-[0.8rem]" aria-hidden="true" />
+            )}
+            {deltaText.length > 0 && <span>{deltaText}</span>}
+          </span>
+        )}
+      </div>
+
+      {/* Caption — below the value row. Use for what the number means or how
+          it breaks down (e.g. "left + right", "vs last week"). Never the delta. */}
+      {description ? (
+        <p
+          className={cn(
+            "min-w-0 text-muted-foreground leading-snug wrap-break-word",
+            dense ? "text-[11px]" : "text-xs",
+          )}
+        >
+          {description}
+        </p>
+      ) : null}
+    </>
+  )
+
+  const sharedClass = cn(
+    "group flex min-w-0 flex-col gap-2 text-start outline-none",
+    edgeGutter && "first:ps-0 last:pe-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">
+          <InsightDefaultTooltip 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>
+          </InsightDefaultTooltip>
+        </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:ps-6",
+                    /* Flat band: insight card ring is the divider — skip `border-l` (double line). */
+                    !isFlatBand && "lg:border-s 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">
+                        <InsightDefaultTooltip 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>
+                        </InsightDefaultTooltip>
+                      </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">
+                        <InsightDefaultTooltip 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>
+                        </InsightDefaultTooltip>
+                      </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)
+  // Pull the host app's "default insight action" (e.g. toggle Ask Leo
+  // sidebar) and label out of `KeyMetricsProvider` instead of
+  // hardcoding `useAskLeo()`. When no provider is mounted, the default
+  // action button hides entirely so the strip stays useful in apps
+  // without an AI assistant.
+  const {
+    defaultInsightAction,
+    defaultActionLabel = "Ask Leo",
+  } = useKeyMetricsContext()
+
+  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">
+              {defaultInsightAction ? (
+                <InsightDefaultTooltip actionLabel={defaultActionLabel}>
+                  <Button
+                    size="sm"
+                    variant="outline"
+                    className="h-7 shrink-0 text-xs gap-1.5 px-2"
+                    aria-label={`${defaultActionLabel} about these metrics`}
+                    onClick={defaultInsightAction}
+                    type="button"
+                  >
+                    <i className="fa-duotone fa-solid fa-star-christmas text-xs text-brand" aria-hidden="true" />
+                    <span>{defaultActionLabel}</span>
+                  </Button>
+                </InsightDefaultTooltip>
+              ) : null}
+              <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"
+    />
+  )
+}