"use client"

/**
 * KeyMetrics — WCAG 2.1 AA reusable KPI panel
 *
 * Variants:
 *   "card"    (default) — one Card wraps the whole KPI strip (hairline grid inside)
 *   "cards"             — each KPI in its own Card tile (responsive grid); preferred for hubs
 *   "compact"           — single Card, metrics only (no header)
 *   "flat"              — grouped KPI strip (hairline cells, one band); same MetricItem
 *                         features as cards (size, alert, chart on md/lg, click). Not for hubs —
 *                         hubs use `cards`. Use flat when KPIs must read as one grouped strip.
 *
 * Mini charts: `sm` places the plot on the **right** of the value; `md` / `lg`
 * stack a taller full-bleed chart under the value (no bottom card padding).
 *
 * 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 { HorizontalScrollRegion } from "./horizontal-scroll-region"
import { useKeyMetricsContext } from "./key-metrics-context"
import { useCompactMetricsStrip } from "../../hooks/use-compact-metrics-strip"

const MetricMiniChart = React.lazy(() =>
  import("./key-metrics-mini-chart").then(m => ({ default: m.MetricMiniChart })),
)

const KEY_METRICS_CARD_SURFACE_STYLE: React.CSSProperties = {
  backgroundColor: "var(--card)",
}

export type KeyMetricsSize = "sm" | "md" | "lg"

/** Padding / type scale for card tiles and strip cells. */
function keyMetricsSizeClasses(size: KeyMetricsSize, layout: "strip" | "cardTile"): {
  cardPadding?: string
  /** Top + horizontal padding when a full-bleed bottom chart is present (no bottom pad). */
  cardPaddingWithChart?: string
  /** Negative horizontal margin so the chart spans edge-to-edge under the padding. */
  chartBleed?: string
  stackGap?: string
  label: string
  value?: string
  valueRow?: string
  valueDefault?: string
  valueHero?: string
  labelMinH?: string
  stripPadding?: string
  trend: string
  description: string
  /** Pixel height for mini charts; `0` means charts are suppressed. */
  chartHeight?: number
} {
  if (layout === "cardTile") {
    switch (size) {
      case "sm":
        return {
          cardPadding: "p-3",
          cardPaddingWithChart: "p-3",
          stackGap: "gap-2",
          label: "text-xs line-clamp-2",
          value: "text-lg",
          valueRow: "min-h-7 items-center",
          trend: "text-xs",
          description: "text-xs line-clamp-2",
          chartHeight: 28,
        }
      case "lg":
        return {
          cardPadding: "p-5",
          cardPaddingWithChart: "px-5 pt-5 pb-0",
          chartBleed: "-mx-5",
          stackGap: "gap-3",
          label: "text-sm line-clamp-2",
          value: "text-4xl tracking-tight sm:text-5xl",
          valueRow: "min-h-12 items-baseline gap-2.5",
          trend: "text-sm sm:text-base",
          description: "text-sm line-clamp-2",
          chartHeight: 88,
        }
      case "md":
      default:
        return {
          cardPadding: "p-4",
          cardPaddingWithChart: "px-4 pt-4 pb-0",
          chartBleed: "-mx-4",
          stackGap: "gap-2.5",
          label: "text-sm line-clamp-2",
          value: "text-3xl tracking-tight sm:text-4xl",
          valueRow: "min-h-10 items-baseline gap-2",
          trend: "text-sm",
          description: "text-sm line-clamp-2",
          chartHeight: 72,
        }
    }
  }

  switch (size) {
    case "sm":
      return {
        stripPadding: "gap-1.5 p-2 sm:px-3 sm:py-2.5",
        stackGap: "gap-1.5",
        labelMinH: "min-h-[1.75rem] gap-y-0.5",
        label: "text-xs line-clamp-2",
        valueDefault: "text-base sm:text-lg",
        valueHero: "text-lg sm:text-xl",
        valueRow: "min-h-7 items-center",
        trend: "text-xs",
        description: "text-xs line-clamp-2",
        chartHeight: 28,
      }
    case "lg":
      return {
        stripPadding: "gap-2.5 p-3.5 sm:px-6 sm:py-5",
        stackGap: "gap-3",
        labelMinH: "min-h-[2.75rem] gap-y-0.5",
        label: "text-sm line-clamp-2",
        valueDefault: "text-2xl sm:text-3xl",
        valueHero: "text-3xl sm:text-4xl",
        valueRow: "min-h-10 items-center",
        trend: "text-sm",
        description: "text-sm line-clamp-2",
        chartHeight: 64,
      }
    case "md":
    default:
      return {
        stripPadding: "gap-2 p-3 sm:px-5 sm:py-4",
        stackGap: "gap-2.5",
        labelMinH: "min-h-[2.625rem] gap-y-0.5",
        label: "text-sm line-clamp-2",
        valueDefault: "text-xl sm:text-2xl",
        valueHero: "text-2xl sm:text-3xl",
        valueRow: "min-h-8 items-center",
        trend: "text-xs sm:text-sm",
        description: "text-sm line-clamp-2",
        chartHeight: 48,
      }
  }
}

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>
  )
}

/** Insight card CTA — falls back to `KeyMetricsProvider.defaultInsightAction`. */
function InsightActionCta({
  insight,
  compact = false,
  className,
  wrapperClassName,
}: {
  insight: MetricInsight
  compact?: boolean
  className?: string
  wrapperClassName?: string
}) {
  const { defaultInsightAction, defaultActionLabel = "Ask Leo" } = useKeyMetricsContext()
  const onInsightAction = insight.onAction ?? defaultInsightAction
  if (!onInsightAction) return null

  const label = insight.actionLabel ?? defaultActionLabel
  const button = (
    <InsightDefaultTooltip actionLabel={insight.actionLabel}>
      <Button
        variant={compact ? "outline" : "ghost"}
        size="sm"
        className={className}
        onClick={onInsightAction}
        type="button"
        aria-label={label}
      >
        <i
          className={
            insight.actionIcon
              ? `fa-light ${insight.actionIcon} text-xs`
              : "fa-duotone fa-solid fa-star-christmas text-xs text-brand"
          }
          aria-hidden="true"
        />
        {label}
      </Button>
    </InsightDefaultTooltip>
  )

  if (!wrapperClassName) return button
  return <div className={wrapperClassName}>{button}</div>
}

/* ── 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"
  /**
   * Mini bar fill (`cards` / `flat`). When `progressMax` is set,
   * treated as a raw count against that max; otherwise 0–100 percent.
   * Ignored when `chart` is set at `md` / `lg` (one visual per tile).
   */
  progress?: number
  progressMax?: number
  /** Mini bar colour. Default `brand` for KPI cards (non-judgmental quota). */
  progressTone?: MetricProgressTone
  /**
   * Optional mini chart (`cards` or `flat`). `sm`: compact plot on the right of the value;
   * `md` / `lg`: taller plot below. Limited kinds: `sparkline` | `bars`.
   * Mutually exclusive with `progress` when shown.
   */
  chart?: MetricChart
  /**
   * Surfaces an attention state on the tile (something wrong / needs action).
   * Use with `trendPolarity: "lower_is_better"` when the count rising is bad.
   * `warning` = needs review; `danger` = blocking / critical.
   */
  alert?: MetricAlert
}

/** Attention tone for a KPI tile — not the same as trend arrow colour. */
export type MetricAlert = "warning" | "danger"

export type MetricProgressTone = "auto" | "success" | "warning" | "danger" | "info" | "brand"

/** One point in a KPI mini chart (`label` shown in the hover tooltip). */
export type MetricChartPoint = {
  value: number
  label?: string
}

/** Closed set of embeddable KPI graphs — full plots stay in ChartCard. */
export type MetricChartKind = "sparkline" | "bars"

export type MetricChart = {
  kind: MetricChartKind
  /** 4–12 points recommended. Numbers or `{ value, label }` for hover copy. */
  series: Array<number | MetricChartPoint>
  /** Stroke / fill tone. Default `brand`. */
  tone?: MetricProgressTone
}

export function normalizeMetricChartSeries(
  series: MetricChart["series"],
): MetricChartPoint[] {
  return series.map((point, index) => {
    if (typeof point === "number") {
      return { value: point, label: String(index + 1) }
    }
    return {
      value: point.value,
      label: point.label?.trim() || String(index + 1),
    }
  })
}

/** Resolve 0–100 fill for card-tile mini bars. */
export function metricProgressPercent(
  progress: number | undefined,
  progressMax?: number,
): number | null {
  if (progress === undefined || Number.isNaN(progress)) return null
  if (progressMax != null && progressMax > 0) {
    return Math.max(0, Math.min(100, Math.round((progress / progressMax) * 100)))
  }
  return Math.max(0, Math.min(100, Math.round(progress)))
}

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"     — one Card wraps the whole strip (dashboard tile)
     * "cards"    — each KPI in its own Card (hubs / overview grids) — preferred for list hubs
     * "flat"     — grouped KPI strip (hairline cells); same features as cards, no per-tile Card
     * "compact"  — Card shell, metrics only
     */
    variant?: "card" | "cards" | "flat" | "compact"
  /**
   * Typography + padding scale. Hub strips: `sm`. Dashboard card tile: `md` (default).
   * Catalog / hero demos: `lg`.
   */
  size?: KeyMetricsSize
  /** 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
  /**
   * Force the horizontal scroll KPI strip on desktop (e.g. token index with many category
   * shortcuts). Default: scroll only on compact viewports / reflow zoom.
   */
  metricsStripScroll?: 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-e")
  }

  if (itemCount === 4) {
    const narrow2x2 = metricsHalfWidthLayout
      ? "@[max-width:23.99rem]"
      : "@[max-width:23.99rem]"
    return cn(
      "gap-0",
      childBorder,
      /* Wide strip (matches `@[24rem]:grid-cols-4`) — verticals between all tiles, no horizontal */
      "[&>*:not(:last-child)]:border-e",
      /* Narrow strip (`@[18rem]`–`@[24rem]` 2×2) */
      `${narrow2x2}:[&>*:not(:last-child)]:border-e-0`,
      `${narrow2x2}:[&>*:nth-child(odd)]:border-e`,
      `${narrow2x2}:[&>*:not(:nth-last-child(-n+2))]:border-b`,
    )
  }

  if (itemCount === 3) {
    return cn("gap-0", childBorder, "[&>*:not(:last-child)]:border-e")
  }

  if (itemCount === 5) {
    const narrow3x2 = metricsHalfWidthLayout
      ? "@[max-width:35.99rem]"
      : "@[max-width:39.99rem]"
    return cn(
      "gap-0",
      childBorder,
      "[&>*:not(:last-child)]:border-e",
      `${narrow3x2}:[&>*:nth-child(3)]:border-e-0`,
      `${narrow3x2}:[&>*:not(:nth-last-child(-n+2))]:border-b`,
    )
  }

  return cn("gap-0", childBorder, "[&>*:not(:last-child)]:border-e")
}

/**
 * Below `lg` the strip uses a horizontal scroll row (see `KeyMetricsInner`).
 * Desktop row column steps live in `metricsRowColumnsClass`.
 */
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.
      // 4-col from ~24rem so sidebar + secondary panel + moderate zoom still fit one row.
      return half
        ? "grid-cols-1 @[14rem]:grid-cols-2 @[24rem]:grid-cols-4"
        : "grid-cols-1 @[18rem]:grid-cols-2 @[24rem]:grid-cols-4"
    case 5:
      return half
        ? "grid-cols-1 @[14rem]:grid-cols-2 @[28rem]:grid-cols-3 @[38rem]:grid-cols-5"
        : "grid-cols-1 @[18rem]:grid-cols-2 @[32rem]:grid-cols-3 @[48rem]:grid-cols-5"
    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 ───────────────────────────────────────────────────────── */

function metricProgressToneClass(tone: MetricProgressTone = "brand"): string {
  switch (tone) {
    case "success":
      return "bg-chart-2"
    case "warning":
      return "bg-chart-4"
    case "danger":
      return "bg-destructive"
    case "info":
      return "bg-primary"
    case "auto": {
      return "bg-primary"
    }
    case "brand":
    default:
      return "bg-[color:var(--brand-color)]"
  }
}

/** Mini track under card-tile values — full width, 6px tall. */
function MetricMiniBar({
  percent,
  tone = "brand",
}: {
  percent: number
  tone?: MetricProgressTone
}) {
  const fillClass =
    tone === "auto"
      ? percent < 34
        ? "bg-destructive"
        : percent < 67
          ? "bg-chart-4"
          : "bg-chart-2"
      : metricProgressToneClass(tone)

  return (
    <div
      role="progressbar"
      aria-valuemin={0}
      aria-valuemax={100}
      aria-valuenow={percent}
      aria-label={`${percent}%`}
      className="h-1.5 w-full overflow-hidden rounded-full bg-muted"
    >
      <div
        className={cn("h-full rounded-full transition-[width]", fillClass)}
        style={{ width: `${percent}%` }}
      />
    </div>
  )
}

/** Single KPI cell inside the metrics grid */
const MetricCell = React.memo(function MetricCell({
  label,
  value,
  delta,
  trend,
  trendPolarity = "higher_is_better",
  description,
  progress,
  progressMax,
  progressTone = "brand",
  chart,
  alert,
  href,
  onClick,
  metricVariant = "default",
  dense = false,
  mobileStrip = false,
  edgeGutter = true,
  layout = "strip",
  size = "md",
  shellInteractive = false,
}: Omit<MetricItem, "id"> & {
  dense?: boolean
  mobileStrip?: boolean
  edgeGutter?: boolean
  /** `cardTile` — one KPI per Card (`variant="cards"`); tighter, aligned stack */
  layout?: "strip" | "cardTile"
  size?: KeyMetricsSize
  /**
   * When true, the parent Card / link owns the click target — render a non-interactive
   * inner stack (still shows the affordance arrow).
   */
  shellInteractive?: boolean
}) {
  const isUp       = trend === "up"
  const isDown     = trend === "down"
  const tone        = metricTrendTone(trend, trendPolarity)
  const isInteractive = shellInteractive || !!(href || onClick)
  const isHero     = metricVariant === "hero"
  const isCardTile = layout === "cardTile"
  const sizeCls = keyMetricsSizeClasses(size, isCardTile ? "cardTile" : "strip")
  const chartHeight = sizeCls.chartHeight ?? 0
  const showChart =
    chartHeight > 0 && chart != null && chart.series.length >= 2
  /** `sm`: chart sits to the right of the value so the tile stays short. */
  const chartInline = showChart && size === "sm"
  const barPercent =
    !showChart ? metricProgressPercent(progress, progressMax) : null
  const ariaAlert = metricAlertAria(alert)

  // 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 labelRow = (
      <div
        className={cn(
          "grid grid-cols-[minmax(0,1fr)_auto] items-start gap-x-2",
          isCardTile
            ? "min-h-0 gap-y-0"
            : mobileStrip
              ? "min-h-0 gap-y-0"
              : dense
                ? "min-h-[1.5rem] gap-y-0.5"
                : sizeCls.labelMinH,
        )}
      >
        <p
          className={cn(
            "min-w-0 text-muted-foreground leading-snug wrap-break-word",
            isCardTile
              ? sizeCls.label
              : mobileStrip
                ? "text-xs line-clamp-2"
                : dense
                  ? "text-xs line-clamp-1"
                  : cn(sizeCls.label, "wrap-break-word"),
            isHero && !mobileStrip && !isCardTile && "font-medium",
            alert === "danger" && "text-destructive-ink",
            alert === "warning" && "text-[color:var(--chart-4)]",
          )}
        >
          {alert ? (
            <span className="me-1.5 inline-flex align-middle" aria-hidden="true">
              <i
                className={cn(
                  "fa-light text-xs",
                  alert === "danger" ? "fa-circle-xmark text-destructive-ink" : "fa-circle-exclamation text-[color:var(--chart-4)]",
                )}
              />
            </span>
          ) : null}
          {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 group-hover/card:text-interactive-hover-foreground sm:group-hover/card:translate-x-0.5" />
          </span>
        ) : null}
      </div>
  )

  const valueRow = (
      <div
        className={cn(
          "flex flex-wrap gap-2",
          isCardTile || showChart || barPercent !== null
            ? sizeCls.valueRow
            : "items-baseline",
        )}
      >
        <span
          className={cn(
            "font-bold tabular-nums leading-none text-foreground",
            isCardTile
              ? sizeCls.value
              : mobileStrip
                ? isHero
                  ? "text-base"
                  : "text-sm"
                : dense
                  ? isHero
                    ? "text-sm sm:text-lg"
                    : "text-sm sm:text-base"
                  : isHero
                    ? sizeCls.valueHero
                    : sizeCls.valueDefault,
          )}
        >
          {value}
        </span>

        {showTrendChip && (
          <span
            className={cn(
              "inline-flex items-center gap-1 font-medium leading-none",
              dense ? "text-xs sm:text-xs" : sizeCls.trend,
              tone === "positive" && "text-chart-2",
              tone === "negative" && "text-destructive-ink",
              tone === "muted" && "text-muted-foreground",
            )}
          >
            <span className="sr-only">{metricTrendAriaQualifier(trend, trendPolarity)}</span>
            {isUp   && <i className="fa-light fa-arrow-trend-up text-xs"   aria-hidden="true" />}
            {isDown && <i className="fa-light fa-arrow-trend-down text-xs" aria-hidden="true" />}
            {!isUp && !isDown && deltaText.length > 0 && (
              <i className="fa-light fa-minus text-xs" aria-hidden="true" />
            )}
            {deltaText.length > 0 && <span>{deltaText}</span>}
          </span>
        )}
      </div>
  )

  const descriptionEl = description ? (
        <p
          className={cn(
            "min-w-0 text-muted-foreground leading-snug wrap-break-word",
            isCardTile
              ? sizeCls.description
              : "line-clamp-2",
            !isCardTile && mobileStrip && "text-xs line-clamp-1",
            !isCardTile && !mobileStrip && (dense ? "text-xs line-clamp-1" : sizeCls.description),
          )}
          title={description}
        >
          {description}
        </p>
  ) : null

  const chartEl = showChart ? (
    <React.Suspense fallback={null}>
      <MetricMiniChart
        chart={chart!}
        height={chartHeight}
        metricLabel={label}
        className={
          chartInline
            ? undefined
            : cn(
                "mt-auto",
                isCardTile && size !== "sm" && sizeCls.chartBleed,
              )
        }
      />
    </React.Suspense>
  ) : null

  const inner = (
    <>
      {labelRow}

      {chartInline ? (
        <div className="flex min-w-0 items-end gap-2.5">
          <div className={cn("flex min-w-0 flex-1 flex-col", sizeCls.stackGap ?? "gap-1.5")}>
            {valueRow}
            {descriptionEl}
          </div>
          <div
            className="w-[44%] max-w-[8rem] min-w-[4.5rem] shrink-0 self-center"
            style={{ height: chartHeight }}
          >
            {chartEl}
          </div>
        </div>
      ) : (
        <>
          {valueRow}
          {descriptionEl}
          {chartEl}
          {barPercent !== null ? (
            <div className="mt-auto w-full">
              <MetricMiniBar percent={barPercent} tone={progressTone} />
            </div>
          ) : null}
        </>
      )}
    </>
  )

  const sharedClass = cn(
    "group flex min-w-0 flex-col text-start outline-none",
    isCardTile
      ? cn("h-full flex-1", sizeCls.stackGap)
      : mobileStrip
        ? cn("gap-0.5 p-2.5", (showChart || barPercent !== null) && "h-full")
        : cn(
            dense ? "gap-1 p-1.5 sm:px-2.5 sm:py-2" : sizeCls.stripPadding,
            (showChart || barPercent !== null) && !chartInline && cn("h-full", sizeCls.stackGap),
            chartInline && sizeCls.stackGap,
          ),
    !isCardTile && edgeGutter && "first:ps-0 last:pe-0",
    !isCardTile && isHero && !mobileStrip && size !== "sm" && "gap-2.5",
    !isCardTile && metricAlertStripClass(alert),
    isInteractive && !shellInteractive && [
      "cursor-pointer transition-colors duration-150",
      "hover:bg-foreground/5",
      "focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring",
    ]
  )

  const cellAria = ariaAlert
    ? `${label}: ${value}. ${ariaAlert}`
    : `${label}: ${value}`

  if (!shellInteractive && href) {
    return (
      <a href={href} className={sharedClass} aria-label={cellAria}>
        {inner}
      </a>
    )
  }

  if (!shellInteractive && onClick) {
    return (
      <button type="button" onClick={onClick} className={sharedClass} aria-label={cellAria}>
        {inner}
      </button>
    )
  }

  return <div className={sharedClass}>{inner}</div>
})

/** Responsive column steps for `variant="cards"` — container width, not viewport. */
function metricCardsGridClass(itemCount: number): string {
  switch (Math.min(itemCount, 4)) {
    case 1:
      return "grid-cols-1"
    case 2:
      return "grid-cols-1 @[18rem]:grid-cols-2"
    case 3:
      return "grid-cols-1 @[18rem]:grid-cols-2 @[36rem]:grid-cols-3"
    case 4:
    default:
      /* 4-up only when the strip itself is wide enough (~12rem per tile). */
      return "grid-cols-1 @[20rem]:grid-cols-2 @[48rem]:grid-cols-4"
  }
}

function metricAlertCardClass(alert: MetricAlert | undefined): string | undefined {
  if (alert === "danger") {
    return "bg-destructive/4 ring-destructive/35 hover:ring-destructive/50 dark:bg-destructive/10"
  }
  if (alert === "warning") {
    return "bg-[color-mix(in_oklch,var(--chart-4)_8%,var(--card))] ring-[color-mix(in_oklch,var(--chart-4)_45%,transparent)] hover:ring-[color-mix(in_oklch,var(--chart-4)_60%,transparent)]"
  }
  return undefined
}

function metricAlertStripClass(alert: MetricAlert | undefined): string | undefined {
  if (alert === "danger") {
    return "bg-destructive/5 ring-1 ring-inset ring-destructive/25"
  }
  if (alert === "warning") {
    return "bg-[color-mix(in_oklch,var(--chart-4)_8%,transparent)] ring-1 ring-inset ring-[color-mix(in_oklch,var(--chart-4)_35%,transparent)]"
  }
  return undefined
}

function metricAlertAria(alert: MetricAlert | undefined): string {
  if (alert === "danger") return "Critical alert"
  if (alert === "warning") return "Needs attention"
  return ""
}

/** Single KPI inside its own Card — whole card is the click target when `href` / `onClick` is set. */
const MetricCardTile = React.memo(function MetricCardTile({
  metric,
  size = "md",
}: {
  metric: MetricItem
  size?: KeyMetricsSize
}) {
  const sizeCls = keyMetricsSizeClasses(size, "cardTile")
  const interactive = !!(metric.href || metric.onClick)
  const cardSize = size === "sm" ? "sm" : "default"
  const alertClass = metricAlertCardClass(metric.alert)
  const ariaAlert = metricAlertAria(metric.alert)
  const ariaLabel = ariaAlert
    ? `${metric.label}: ${metric.value}. ${ariaAlert}`
    : `${metric.label}: ${metric.value}`
  const hasBleedChart =
    size !== "sm" &&
    metric.chart != null &&
    normalizeMetricChartSeries(metric.chart.series).length >= 2

  const card = (
    <Card
      size={cardSize}
      interactive={interactive}
      data-alert={metric.alert || undefined}
      className={cn(
        /* overflow-visible so chart tooltips can escape the card edge;
           hover:z elevates above sibling KPI cards while the tip is open. */
        "h-full gap-0 overflow-visible! bg-card py-0 shadow-xs ring-1 ring-foreground/8",
        "relative z-0 hover:z-30 focus-within:z-30",
        interactive && "transition-[box-shadow,background-color] hover:bg-muted/25 hover:ring-foreground/12",
        alertClass,
      )}
    >
      <CardContent
        className={cn(
          "flex h-full flex-col overflow-visible",
          hasBleedChart ? sizeCls.cardPaddingWithChart : sizeCls.cardPadding,
        )}
      >
        <MetricCell
          {...metric}
          layout="cardTile"
          edgeGutter={false}
          size={size}
          shellInteractive={interactive}
        />
      </CardContent>
    </Card>
  )

  if (metric.href) {
    return (
      <a
        href={metric.href}
        className="block h-full rounded-xl outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background"
        aria-label={ariaLabel}
      >
        {card}
      </a>
    )
  }

  if (metric.onClick) {
    return (
      <button
        type="button"
        onClick={metric.onClick}
        className="block h-full w-full rounded-xl text-start outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background"
        aria-label={ariaLabel}
      >
        {card}
      </button>
    )
  }

  return card
})
/** 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 p-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 line-clamp-2 text-sm leading-snug text-muted-foreground"
                title={body}
              >
                {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>

        <InsightActionCta
          insight={insight}
          compact={compact}
          wrapperClassName="mt-auto flex shrink-0 justify-end pt-3"
          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"
          )}
        />
      </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-ink" },
  }[severity]

  return (
    <span
      className={cn(
        "inline-flex shrink-0 items-center justify-center rounded-full",
        size === "sm" ? "size-6 text-xs" : "size-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
  /** Tighter KPI cells + 2-col mobile grid (half-width dashboard card). */
  metricsHalfWidthLayout?: boolean
  /** Force horizontal scroll strip on desktop (many category shortcuts). */
  metricsStripScroll?: 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"
  /** Typography + padding scale for strip cells. */
  size?: KeyMetricsSize
}

function KeyMetricsInner({
  title,
  description,
  period,
  periods,
  metrics,
  rows,
  insight,
  onPeriodChange,
  innerPadding = "",
  showHeader = true,
  insightCompact = false,
  insightFullWidth = false,
  metricsHalfWidthLayout = false,
  metricsStripScroll = false,
  metricsCellSurfaceClassName = "bg-background",
  surfaceVariant = "default",
  size = "md",
}: InnerProps) {
  const compactStrip = useCompactMetricsStrip()
  const scrollStrip = metricsStripScroll || compactStrip
  const isFlatBand = surfaceVariant === "flat"
  const metricsGridClassName = isFlatBand
    ? flatMetricsHairlineClass(metrics.length, metricsHalfWidthLayout)
    : "gap-px bg-border"
  /** Side-by-side KPI + insight rail (md+). Disabled when the scroll strip is active — controls + tiles need full width at reflow zoom. */
  const insightSideBySide =
    insight && !insightFullWidth && !metricsHalfWidthLayout && metrics.length >= 2 && !scrollStrip
  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",
          insightSideBySide && insightKpiGridClass(metrics.length),
          innerPadding
        )}
      >

        {/* Metrics section — stretch to match insight height on lg+ */}
        <div
          className={cn(
            "min-w-0 lg:flex lg:min-h-0 lg:flex-col",
            !insightSideBySide && "w-full",
            insightSideBySide && "lg:self-stretch lg:justify-center"
          )}
        >
          {/*
            Compact / mobile / high-zoom: horizontal scroll strip — ~2 tiles visible.
          */}
          <HorizontalScrollRegion
            ariaLabel="Key metrics"
            controlsLayout="group-end"
            fit="content"
            scrollClassName="items-stretch"
            className={cn(!scrollStrip && "hidden")}
          >
            <div
              role="group"
              aria-label="Key metrics"
              className="flex w-max min-w-0 gap-0"
            >
              {metrics.map((m, index) => (
                <div
                  key={m.id}
                  className={cn(
                    "w-[8.5rem] shrink-0 sm:w-[9rem]",
                    index > 0 &&
                      (isFlatBand
                        ? "border-s border-[color:var(--key-metrics-flat-divider)]"
                        : "border-s border-border"),
                    metricsCellSurfaceClassName,
                    "py-0.5",
                  )}
                >
                  <MetricCell {...m} mobileStrip edgeGutter={false} size={size} />
                </div>
              ))}
            </div>
          </HorizontalScrollRegion>

          {/*
            Wide desktop: row-by-row container-queried grid.
          */}
          <div className={cn("@container/metrics-strip", scrollStrip && "hidden")}>
            {rows.map((row, rowIdx) => (
              <React.Fragment key={rowIdx}>
                {rowIdx > 0 && isFlatBand && (
                  <div
                    aria-hidden="true"
                    className="h-px w-full shrink-0 bg-[color:var(--key-metrics-flat-divider)]"
                  />
                )}
                {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} size={size} />
                    </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-2 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 || !insightSideBySide}
                />
              ) : (
                <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="line-clamp-2 text-sm leading-relaxed text-muted-foreground"
                            title={insight.description}
                          >
                            {insight.description}
                          </p>
                        ) : null}
                      </div>
                      <InsightActionCta
                        insight={insight}
                        wrapperClassName="flex w-full shrink-0 md:w-auto"
                        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]"
                      />
                    </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="line-clamp-2 text-sm leading-relaxed text-muted-foreground"
                            title={insight.description}
                          >
                            {insight.description}
                          </p>
                        ) : null}
                      </div>
                      <InsightActionCta
                        insight={insight}
                        wrapperClassName="flex w-full shrink-0 md:w-auto"
                        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]"
                      />
                    </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
}

/** Split metrics into grid rows — prefer one row for ≤5 tiles so insight rail pairs cleanly. */
function resolveMetricRows(
  metrics: MetricItem[],
  metricsSingleRow: boolean,
  metricsHalfWidthLayout: boolean,
): MetricItem[][] {
  if (metrics.length === 0) return []
  if (metricsSingleRow) {
    return metricsHalfWidthLayout ? chunkMetricPairs(metrics) : [metrics]
  }
  if (metrics.length <= 5) return [metrics]
  const out: MetricItem[][] = []
  for (let i = 0; i < metrics.length; i += 3) {
    out.push(metrics.slice(i, i + 3))
  }
  return out
}

/** KPI + insight side-by-side column ratio scales with tile count. */
function insightKpiGridClass(metricCount: number): string {
  if (metricCount <= 2) {
    return "lg:grid lg:grid-cols-[minmax(0,1fr)_minmax(14rem,1fr)] lg:items-stretch lg:gap-x-6 lg:gap-y-0"
  }
  if (metricCount === 3) {
    return "lg:grid lg:grid-cols-[minmax(0,5fr)_minmax(14rem,4fr)] lg:items-stretch lg:gap-x-6 lg:gap-y-0"
  }
  return "lg:grid lg:grid-cols-[minmax(0,3fr)_minmax(13rem,2fr)] lg:items-stretch lg:gap-x-6 lg:gap-y-0"
}

/**
 * Same as `insightKpiGridClass` but keyed to the KeyMetrics `@container`
 * (catalog / hub panes can be narrow while the viewport is `lg`).
 */
function insightCardsRailClass(metricCount: number): string {
  if (metricCount <= 2) {
    return "@[40rem]:grid-cols-[minmax(0,1fr)_minmax(14rem,1fr)] @[40rem]:gap-x-6 @[40rem]:gap-y-0"
  }
  if (metricCount === 3) {
    return "@[44rem]:grid-cols-[minmax(0,5fr)_minmax(14rem,4fr)] @[44rem]:gap-x-6 @[44rem]:gap-y-0"
  }
  return "@[48rem]:grid-cols-[minmax(0,3fr)_minmax(13rem,2fr)] @[48rem]:gap-x-6 @[48rem]:gap-y-0"
}

/* ── Main component ───────────────────────────────────────────────────────── */

const EMPTY_METRICS: MetricItem[] = []

export function KeyMetrics(props: KeyMetricsProps) {
  const {
    variant       = "card",
    size          = "md",
    title         = "Key Metrics",
    description   = "Overview of performance indicators",
    metrics       = EMPTY_METRICS,
    insight,
    periods       = DEFAULT_PERIODS,
    defaultPeriod = "week",
    onPeriodChange,
    showHeader    = true,
    insightCompact = false,
    insightFullWidth = false,
    metricsSingleRow = false,
    metricsHalfWidthLayout = false,
    metricsStripScroll = false,
    className,
  } = props
  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)
  }

  const rows = resolveMetricRows(metrics, metricsSingleRow, metricsHalfWidthLayout)

  const metricsCellSurfaceClassName =
    variant === "flat" || variant === "card" || variant === "compact"
      ? "bg-transparent"
      : "bg-card dark:bg-transparent"

  const innerProps: InnerProps = {
    title,
    description,
    period,
    periods,
    metrics,
    rows,
    insight,
    onPeriodChange: handlePeriodChange,
    insightCompact,
    insightFullWidth,
    metricsHalfWidthLayout,
    metricsStripScroll,
    metricsCellSurfaceClassName,
    surfaceVariant:
      variant === "flat" || variant === "card" || variant === "compact" ? "flat" : "default",
    size,
  }

  /*
   * ── GLOW GUIDELINE ────────────────────────────────────────────────────────
   * KeyMetrics does **not** use brand radial glow. Prefer `variant="cards"` +
   * `size` for hub strips. Reserve Ask Leo utility-bar glow
   * (`--ask-leo-utility-glow-shadow`) for AI chrome only — not KPI tiles.
   * ─────────────────────────────────────────────────────────────────────────
   */

  /* ── Card variant — ChartCard-style chrome ───────────────────────────── */
  if (variant === "card") {
    return (
      <Card className={cn("shadow-xs overflow-hidden flex flex-col", className)} style={KEY_METRICS_CARD_SURFACE_STYLE}>
        <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="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>
    )
  }

  /* ── Cards variant — one Card per KPI tile ───────────────────────────── */
  if (variant === "cards") {
    const cardsGap = size === "sm" ? "gap-2.5" : size === "lg" ? "gap-4" : "gap-3"
    const insightSideBySide =
      !!insight && !insightFullWidth && !metricsHalfWidthLayout && metrics.length >= 2
    return (
      <section
        aria-label={title}
        className={cn(
          "@container flex flex-col px-4 lg:px-6",
          size === "sm" ? "gap-3 py-2 sm:py-3" : size === "lg" ? "gap-5 py-3 sm:py-4" : "gap-4 py-2.5 sm:py-3",
          className,
        )}
      >
        {showHeader ? (
          <div className="flex flex-col gap-2 sm:flex-row sm:items-center sm:justify-between sm:gap-4">
            <div className="min-w-0">
              <p className="text-base font-semibold leading-tight text-foreground">{title}</p>
              <p className="mt-0.5 text-sm text-muted-foreground">{description}</p>
            </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 gap-1.5 px-2 text-xs"
                    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
                  className="h-8 w-full min-w-[9rem] shrink-0 text-sm sm:w-auto"
                  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>
        ) : null}

        <div
          className={cn(
            "grid items-stretch",
            cardsGap,
            insightSideBySide && insightCardsRailClass(metrics.length),
            insightFullWidth && "grid-cols-1",
          )}
        >
          <div
            role="group"
            aria-label="Key metrics"
            className={cn(
              "@container grid min-w-0 items-stretch",
              cardsGap,
              metricCardsGridClass(metrics.length),
            )}
          >
            {metrics.map((metric) => (
              <MetricCardTile key={metric.id} metric={metric} size={size} />
            ))}
          </div>

          {insight ? (
            <div
              className={cn(
                "min-w-0",
                insightFullWidth && "col-span-full",
                insightSideBySide && "flex flex-col",
              )}
            >
              <InsightRailStatementAction
                insight={insight}
                compact={insightCompact || size === "sm"}
              />
            </div>
          ) : null}
        </div>
      </section>
    )
  }

  /* ── Compact variant — card chrome, no header, metrics only ──────────── */
  if (variant === "compact") {
    return (
      <Card className={cn("shadow-xs overflow-hidden", className)} style={KEY_METRICS_CARD_SURFACE_STYLE}>
        <CardContent className="py-3 px-4">
          <KeyMetricsInner {...innerProps} showHeader={false} />
        </CardContent>
      </Card>
    )
  }

  /* ── Flat variant — no card chrome, no glow (page canvas) ── */
  return (
    <section
      aria-label={title}
      className={cn(
        "relative w-full overflow-hidden",
        size === "sm" ? "pt-2 pb-2 sm:pt-2.5 sm:pb-3" : "pt-2 pb-3 sm:pt-3 sm:pb-4 lg:pt-5 lg:pb-8",
        className,
      )}
    >
      <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 = EMPTY_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"
    />
  )
}