Metric Card

import * as React from "react"

import { cn } from "@/registry/lib/utils"
import {
  Card,
  CardContent,
  DashboardCardHeader,
  MetricCardValue,
} from "@/registry/ui/card"
import { Stack } from "@/registry/ui/stack"

type SparklineType = "bar" | "line" | "area"
type SparklineSize = "sm" | "default" | "lg"

const SIZE_CLASS: Record<SparklineSize, string> = {
  sm: "h-6",
  default: "h-10",
  lg: "h-16",
}

const SIZE_HEIGHT: Record<SparklineSize, number> = {
  sm: 24,
  default: 40,
  lg: 64,
}

// The bar takes 60% of its column and the gap takes the rest, at every width.
// The ratio is the constant here, not a pixel: the chart fills its container,
// so the bar grows and shrinks with the card and a wide card gets wider bars
// rather than the same thin ones adrift in their gutters.
//
// An earlier version capped the pitch and centered a narrower chart in a wide
// box, which is why that box used to render a short chart floating in the
// middle of it. The failure that cap was written for is a different one: it is
// capping the BAR while the gap keeps growing, which does read as a dotted
// line. Scaling both together has no such break, so nothing needs a ceiling.
const BAR_RATIO = 0.6

// The FEWEST columns a bar chart divides its width into. Below it, a short
// series keeps the bar width it would have at this count instead of spreading
// out, and the bars sit against the RIGHT edge, newest last, so the empty
// columns read as history that has not happened yet.
//
// Without it the ratio above has no floor: three points made three bars each
// a fifth of the card wide, and a bar wider than the chart is tall cannot
// round into a pill. Its ends take half the WIDTH as their radius, which the
// height then clamps, so each bar painted as an oval. This is not the cap the
// note above rejects: that one fixed the pitch at every count and centered the
// result. This one only acts on a short series, and the chart still ends on
// the card's edge. At 12 a default-height bar stays taller than it is wide up
// to an 800px card.
const MIN_BAR_COLUMNS = 12

// The shortest a bar can be, so a zero in the middle of a series is still a
// mark rather than a gap in the row.
const MIN_BAR_HEIGHT = 2

// Bars are DRAWN, not laid out, and that is the whole reason this is an SVG
// instead of the flex row it started as.
//
// A row of CSS boxes cannot be evenly spaced at an arbitrary width. Thirty
// columns in a 203px card is a 6.77px pitch, and a browser paints a box by
// snapping its edges to whole device pixels, so those columns land 13 and 14
// device pixels apart in whatever pattern the fraction falls in. The bars
// themselves come out pixel-identical, which is what makes it so hard to read:
// measured, every bar was exactly 10 device pixels, and the unevenness was
// entirely in the 3px-vs-4px GAPS between them. The eye reads that whitespace
// as part of the rhythm, so a bar with a tight gap on each side looks fatter
// than its neighbor and the row looks like it has the wrong bars in it.
//
// SVG geometry is not snapped, it is ANTIALIASED. A bar at a fractional
// position spreads its edge across two pixels instead of jumping to the next
// one, so every bar carries the same ink and every gap carries the same ink at
// any container width. The cost is that an edge is soft rather than crisp,
// which is the trade this makes on purpose.
//
// No viewBox, deliberately: user units are then CSS pixels, so a width is a
// real width and `rx` paints a true half-circle end. The line and area shapes
// below take the opposite deal (a 100-wide viewBox stretched with
// preserveAspectRatio="none") because a path has to be positioned in
// proportional units, and they pay for it with `vector-effect` on every stroke.

// The SVG viewBox is 100 wide and stretches to the container (preserveAspectRatio
// "none"), so horizontal units are percentages and vertical units are real pixels.
// Every stroke carries vector-effect="non-scaling-stroke", which is what keeps the
// line 2.5px and the end dot round no matter how wide the card gets.
const VIEW_WIDTH = 100
// 2.5px, not a hairline. The line sits beside 14px text and is the subject of
// the row it is in; at 1.5 it was the lightest thing in that row, and 3 was
// heavy. It is set in SCREEN pixels, not user units, because of the
// non-scaling-stroke above, so this number is literally what renders at any
// card width - and it is CSS pixels, so a screenshot off a 2x display measures
// double. Half a pixel is fine: a curve is antialiased anyway, so there is no
// hairline to snap and no text to blur.
const STROKE_WIDTH = 2.5
// Twice the stroke. Tie the two together: a dot much past 2x reads as a blob
// stuck on the end rather than the last reading, and much under it disappears
// into the line.
const DOT_SIZE = STROKE_WIDTH * 2
// Vertical inset so a peak's stroke and the end dot are not sheared off by the
// top and bottom edges. Horizontal bleed is handled by letting the SVG overflow.
const INSET = DOT_SIZE / 2

function formatValue(value: number) {
  return Number.isInteger(value) ? String(value) : value.toFixed(1)
}

function describe(data: number[]) {
  const first = data[0]
  const last = data[data.length - 1]
  const direction = last > first ? "trending up" : last < first ? "trending down" : "flat"
  return `${data.length} points, ${formatValue(first)} to ${formatValue(last)}, ${direction}`
}

function Sparkline({
  data,
  type = "bar",
  size = "default",
  label,
  columns: minColumns = MIN_BAR_COLUMNS,
  className,
  ...props
}: Omit<React.ComponentProps<"div">, "children"> & {
  /** The series, oldest first. */
  data: number[]
  /** `bar` for a count per period, `line` for a trend, `area` for volume under a trend. */
  type?: SparklineType
  /** 24px / 40px / 64px tall. */
  size?: SparklineSize
  /** Accessible name. Generated from the data when omitted. */
  label?: string
  /**
   * Bar charts only: the fewest columns the width is divided into. Defaults
   * to 12. Raise it on a WIDE card whose series is short, so its bars keep
   * the weight of the narrower cards beside it instead of spreading out: a
   * bar is 60% of its column, so the same points in twice the width paint
   * bars twice as fat. Set it to the number of periods the chart is meant to
   * hold (60 for "the last 60 days") and the row fills in from the right as
   * history arrives. Never below 12, which is the floor that keeps a bar
   * taller than it is wide.
   */
  columns?: number
}) {
  const height = SIZE_HEIGHT[size]

  // No data still renders the full height, so a card does not jump when the
  // series arrives. A hairline on the baseline reads as "nothing yet".
  if (data.length === 0) {
    return (
      <div
        data-slot="sparkline"
        data-empty=""
        className={cn("flex w-full items-end", SIZE_CLASS[size], className)}
        role="img"
        aria-label={label ?? "No data"}
        {...props}
      >
        {/* 2px against the line's 2.5, on purpose, and NOT tied to STROKE_WIDTH.
            Matching the numbers does not match the weight: this bar is dead
            straight, so every pixel of it is full opacity, while a curve of the
            same width spreads across partially transparent edge pixels. At an
            equal 2.5 the baseline read visibly heavier than the line it stands
            in for. Optical, so it is corrected by eye, not by arithmetic. */}
        <div className="bg-border h-0.5 w-full rounded-full" />
      </div>
    )
  }

  const min = Math.min(...data)
  const max = Math.max(...data)

  const root = (children: React.ReactNode) => (
    <div
      data-slot="sparkline"
      data-type={type}
      className={cn("text-accent w-full", SIZE_CLASS[size], className)}
      role="img"
      aria-label={label ?? describe(data)}
      {...props}
    >
      {children}
    </div>
  )

  if (type === "bar") {
    // A bar's LENGTH is the value, so bars measure from zero, never from the
    // series low: a band-scaled bar chart says a 98 is a fraction of a 100.
    // Values below zero clamp to the baseline; a series that crosses zero
    // wants `type="line"`, whose band scale is the honest one for it.
    const span = max > 0 ? max : 1

    // One column per point (at least MIN_BAR_COLUMNS), and the bar sits centered in it: 60% wide, so 20%
    // of the pitch is left over on each side. Both are percentages of the SAME
    // rendered width, which is what keeps every bar and every gap equal however
    // wide the card is.
    const columns = Math.max(data.length, MIN_BAR_COLUMNS, minColumns)
    const pitch = 100 / columns
    // Empty columns go on the left, so the newest bar always ends the row.
    const offset = columns - data.length
    const bar = (value: number, i: number) => {
      const length = Math.max(
        MIN_BAR_HEIGHT,
        (Math.max(0, Math.min(value, max)) / span) * height
      )
      return (
        // A NESTED VIEWPORT PER BAR, which is the only way to round one whose
        // width is a percentage.
        //
        // CSS and SVG disagree about an oversized radius. `rounded-full` scales
        // both radii by ONE factor until they fit, so the ends stay circular. An
        // SVG rect clamps rx to half its width and ry to half its height
        // SEPARATELY, so the same trick paints a 2.5 x 20 ellipse and a row of
        // them reads as a line of eyes. Naming a real radius instead is no help:
        // the bar's width is a percentage of the card, and nothing knows what
        // that is in pixels at render time.
        //
        // Inside its own <svg>, 50% means half the BAR. rx resolves to half the
        // width, ry follows rx, and each lands under its own clamp, so the ends
        // are circular at any card width and a near-zero value still flattens
        // to the same lozenge the CSS box drew.
        <svg
          key={i}
          aria-hidden="true"
          focusable="false"
          x={`${(offset + i + (1 - BAR_RATIO) / 2) * pitch}%`}
          y={height - length}
          width={`${BAR_RATIO * pitch}%`}
          height={length}
        >
          <rect width="100%" height="100%" rx="50%" fill="currentColor" />
        </svg>
      )
    }

    return root(
      <svg className="block h-full w-full" aria-hidden="true" focusable="false">
        {/* The most recent bar is the one the eye should land on, so the rest
            step back. Opacity, not a lighter token, so both strengths stay the
            same color as a consumer's own `--accent`.

            It is set on the GROUP rather than on each bar, so the muted bars
            composite once. Per-bar opacity blends twice anywhere two of them
            touch, which paints a seam down a dense row. */}
        <g opacity={0.6}>{data.slice(0, -1).map((value, i) => bar(value, i))}</g>
        {bar(data[data.length - 1], data.length - 1)}
      </svg>
    )
  }

  // Line and area read the min-to-max BAND, not zero: a trend is about the
  // shape of the change, and a zero-based line flattens every real series
  // whose values sit far from zero.
  const span = max - min || 1
  const usable = height - INSET * 2
  const x = (i: number) => (data.length === 1 ? VIEW_WIDTH / 2 : (i / (data.length - 1)) * VIEW_WIDTH)
  const y = (value: number) => INSET + (1 - (value - min) / span) * usable

  const points = data.map((value, i) => `${x(i)},${y(value)}`).join(" ")
  const lastX = x(data.length - 1)
  const lastY = y(data[data.length - 1])

  return root(
    <svg
      className="h-full w-full overflow-visible"
      viewBox={`0 0 ${VIEW_WIDTH} ${height}`}
      preserveAspectRatio="none"
      aria-hidden="true"
      focusable="false"
    >
      {type === "area" && (
        // A flat fill rather than a gradient: a gradient needs an id, ids must
        // be unique per instance, and useId is not available to a component
        // that renders on the server.
        <polygon
          points={`0,${height} ${points} ${VIEW_WIDTH},${height}`}
          fill="currentColor"
          fillOpacity={0.15}
        />
      )}
      <polyline
        points={points}
        fill="none"
        stroke="currentColor"
        strokeWidth={STROKE_WIDTH}
        strokeLinecap="round"
        strokeLinejoin="round"
        vectorEffect="non-scaling-stroke"
      />
      {/* A zero-length round-capped stroke paints a true circle. A <circle>
          cannot: the viewBox scales horizontally only, so an r would render
          as an ellipse that stretches with the card. */}
      <line
        x1={lastX}
        y1={lastY}
        x2={lastX}
        y2={lastY}
        stroke="currentColor"
        strokeWidth={DOT_SIZE}
        strokeLinecap="round"
        vectorEffect="non-scaling-stroke"
      />
    </svg>
  )
}

// @use-when a dashboard figure: one number with its label, and optionally a
// delta and a sparkline. `layout="tile"` for a row of KPIs (often four across)
// that are each one number, a status pill and one line under it; the default
// layout for a metric with a chart or more than one line under the value.
function MetricCard({
  layout = "default",
  title,
  value,
  goal,
  delta,
  unit,
  badge,
  action,
  link,
  trend,
  children,
  className,
  ...props
}: Omit<React.ComponentProps<typeof Card>, "title"> & {
  /**
   * `default` puts the label in its own header band above the value. `tile`
   * drops the band: one open card with the label on top, the status pill in
   * the top-right corner, then the value and one line. Use `tile` for a row of
   * KPIs that are each one number plus a status; keep `default` for a metric
   * with a chart or several lines under it.
   */
  layout?: "default" | "tile"
  /** Card header label. In `tile`, the small label above the value. */
  title: string
  /** The headline number. */
  value: React.ReactNode
  /** The line under the value, e.g. "Goal: 262" or "vs. last month". */
  goal?: React.ReactNode
  /** Distance left to the goal. Renders "Goal reached!" once it hits zero. */
  delta?: { value: number; label?: string }
  /** Appended to `goal`, e.g. "lb". */
  unit?: string
  /** Sits inline beside the value. Pass an element: `badge={<Badge>+12%</Badge>}`.
   *  In `tile`, it moves to the top-right corner, beside the label. */
  badge?: React.ReactNode
  /** Header right slot, for a Kebab or an icon Button. In `tile`, pass the
   *  `icon-sm` size: the slot sits on the label row and a taller control
   *  would reach toward the value under it. */
  action?: React.ReactNode
  /** Header right slot as a text link. Ignored when `action` is set. */
  link?: { label: string; onClick: () => void }
  /** Recent history, drawn under the value. */
  trend?: {
    data: number[]
    type?: React.ComponentProps<typeof Sparkline>["type"]
    size?: React.ComponentProps<typeof Sparkline>["size"]
    label?: string
    /** Bar charts only: the fewest columns. See `Sparkline`'s `columns`. */
    columns?: number
  }
  /** Extra content in the value block, e.g. a Progress bar. */
  children?: React.ReactNode
}) {
  const chart = trend && (
    <Sparkline
      className="mt-auto"
      data={trend.data}
      type={trend.type}
      size={trend.size}
      columns={trend.columns}
      label={trend.label ?? `${title} over the last ${trend.data.length} periods`}
    />
  )

  if (layout === "tile") {
    const corner = action ?? (link ? (
      <button
        onClick={link.onClick}
        className="rounded-sm text-xs text-muted-foreground hover:text-foreground transition-colors duration-small ease-small cursor-pointer outline-none focus-visible:ring-[3px] focus-visible:ring-ring-focus pointer-coarse:py-2"
      >
        {link.label}
      </button>
    ) : null)

    return (
      <Card className={cn(className)} {...props}>
        {/* Same CardContent, so the same 16px side inset as the default
            layout's header and body: a tile and a default card in one grid
            share a left edge. The floor-pinned chart works exactly as below. */}
        <CardContent className="flex flex-1 flex-col">
          <Stack gap="cluster" className="flex-1">
            {/* `lines` (12px), the rung MetricCardValue already uses between
                the value and its goal line. The label names the value and the
                line under it, so label, value and goal are three short
                cap-trimmed lines reading as one unit, which is exactly what
                `lines` is for. One rung top to bottom keeps the three evenly
                spaced instead of the label floating off on its own. */}
            <Stack gap="lines">
              {/* THE LABEL ROW IS AS TALL AS THE LABEL'S CAPS, whatever sits
                  at its end. The label is cap-trimmed so the 12px rung below
                  it paints as 12px. The corner (badge, action, link) sits in a
                  zero-height wrapper, the same trick MetricCardValue uses for
                  its badge: it is centred on the label and overflows the row
                  rather than growing it, so a tile with a badge and one
                  without put their values at the same height. The overflow
                  lands in CardContent's 20px top padding and the 12px gap,
                  which is why the action slot asks for `icon-sm`.

                  The label is a LABEL, not a heading: text-sm (14px), the
                  same size as the default layout's header label, so the two
                  layouts name a metric at one size. Muted, because in a tile
                  the number is the thing read first and the label explains
                  it, which is the muted job in the rules' three text colours.
                  The sideways cut is overflow-x-clip, never truncate, for the
                  reason given on MetricCardValue's goal line: a trimmed box
                  ends at the baseline and truncate would shear descenders. */}
              <div className="flex items-center justify-between gap-2">
                <span className="cap-trim min-w-0 overflow-x-clip text-ellipsis whitespace-nowrap text-sm font-medium text-muted-foreground">
                  {title}
                </span>
                {(badge || corner) && (
                  <span className="flex h-0 shrink-0 items-center gap-2 self-center">
                    {badge}
                    {corner}
                  </span>
                )}
              </div>
              <Stack gap="bind">
                <MetricCardValue value={value} goal={goal} delta={delta} unit={unit} />
                {children}
              </Stack>
            </Stack>
            {chart}
          </Stack>
        </CardContent>
      </Card>
    )
  }

  return (
    <Card className={cn(className)} {...props}>
      <DashboardCardHeader title={title} action={action} link={link} />
      {/* THE CHART SITS ON THE CARD'S FLOOR, not wherever the text above it
          happens to end. Metric cards live in a grid, a grid row stretches
          every card to the tallest, and the text block is the part that varies:
          a card with a `delta` line is one line taller than one without. Packed
          from the top, that difference falls as dead space UNDER the chart, so
          three cards in a row show three charts at three different heights and
          the shortest text gets the biggest hole beneath it. Pinning the chart
          down instead puts the slack above it, where it reads as breathing room,
          and gives the row a common baseline to scan across.

          `mt-auto` is a flex push absorbing free space, not a child setting a
          gap to a sibling: the rung above still supplies the 16px minimum, and
          on a card that is NOT stretched there is no free space, so this is
          inert and the card keeps its natural height. */}
      <CardContent className="flex flex-1 flex-col">
        {/* Two rungs, not one. The goal line and anything passed as children
            explain the value, so they bind to it at 8. The trend chart is a
            peer artifact about the same metric, sitting under that whole
            block at 16. One flat stack would put the chart at the same
            distance as the goal line and read as a fourth line of text. */}
        <Stack gap="cluster" className="flex-1">
          <Stack gap="bind">
            <MetricCardValue value={value} goal={goal} delta={delta} unit={unit}>
              {badge}
            </MetricCardValue>
            {children}
          </Stack>
          {trend && (
            <Sparkline
              className="mt-auto"
              data={trend.data}
              type={trend.type}
              size={trend.size}
              columns={trend.columns}
              label={trend.label ?? `${title} over the last ${trend.data.length} periods`}
            />
          )}
        </Stack>
      </CardContent>
    </Card>
  )
}

// Two exports, one file, on purpose. `MetricCard` is the pattern; `Sparkline`
// is the chart it draws, still reachable on its own for a table row or a list
// item, where a card would be the wrong box entirely.
//
// The card is a COMPOSITION, not a new surface: `Card`, `DashboardCardHeader`,
// `MetricCardValue`, and `Stack` all ship separately, and what this adds is the
// rhythm, which is the part that was being retyped and quietly getting
// different at every call site. Reach past it to those parts whenever the
// layout differs; that is not a fork, it is what the parts are for.
//
// The chart paints with `currentColor` off a `text-accent` root, so one class
// on the element retargets every mark. Deliberately static: no enter
// animation, no hover. A metric card is read dozens of times a day, and a
// chart that replays its fill on every visit is noise, not delight.
export { MetricCard, Sparkline }