sparkline

import type * as React from "react"
import { cn } from "@/lib/utils"

// A SERIES AS A LINE THE SIZE OF A WORD: the shape of a window at a glance, beside the
// number it explains (a stat's, a table cell's). No axes, no labels, no hover: what a
// reader needs from it is up, down, steady or spiking.
//
//   <Sparkline values={visits} label="visits, last 30 days" />
//   <Sparkline values={revenue} label="revenue" area className="h-10 w-32 text-tone-ok" />
//
// SIZED BY ITS CONTAINER, both ways: as wide as where it is put (`w-full`) and 32 px
// tall unless `className` says otherwise. Nothing is measured and no width is
// guessed: the line is drawn in a 1 by 1 box the browser stretches to the element's
// own size (`preserveAspectRatio="none"`), the stroke kept 1.5 px whatever the
// stretch (`vector-effect: non-scaling-stroke`), and the last value's dot is a round
// element placed at its point in percent, so it stays round. A sparkline is right at
// any width on the first paint, server-rendered, with nothing to hydrate.
//
// THE SCALE: from `min` to `max`, by default the values' own range widened to take in
// zero, so a count that went from 40 to 44 reads as the small change it is, not as a
// cliff. Pass `min` (and `max`) to look closely at a series far from zero (a latency
// around 200 ms); a value outside them screams. The area, when drawn, fills down to
// zero, or to the floor when zero is outside the scale.
//
// EMPTY AND ONE VALUE say only what is there: an empty series draws nothing, one value
// is its dot alone at the right end (the latest), never a line made up to join it to
// nothing. In the ink of where it stands (`currentColor`).
//
// A screen reader hears `label` and what the line shows: how many values, the first
// and the last, the lowest and the highest, each through `format`.
//
// No "use client": it renders in a server component as it is, `format` included.

const plain = new Intl.NumberFormat("en-US")

export type SparklineProps = Omit<React.ComponentProps<"div">, "children"> & {
  /** The series, oldest first. */
  values: readonly number[]
  /** What the series is, for a screen reader ("visits, last 30 days"). */
  label: string
  /** The area under the line, filled faintly. Default off. */
  area?: boolean
  /** The last value marked with a dot, so "now" reads without an axis. Default on. */
  dot?: boolean
  /** The scale's floor. Default the lowest value, or zero when lower. */
  min?: number
  /** The scale's top. Default the highest value, or zero when higher. */
  max?: number
  /** How a value is said to a screen reader. Default grouped digits ("48,210"). */
  format?: (value: number) => string
}

/** What the line shows, in words. */
function described(
  label: string,
  values: readonly number[],
  format: (value: number) => string,
): string {
  const first = values[0]
  const last = values.at(-1)
  if (first === undefined || last === undefined) return `${label}: no values`
  if (values.length === 1) return `${label}: one value, ${format(first)}`
  return `${label}: ${values.length} values, from ${format(first)} to ${format(last)}, lowest ${format(Math.min(...values))}, highest ${format(Math.max(...values))}`
}

export function Sparkline({
  values,
  label,
  area = false,
  dot = true,
  min,
  max,
  format = plain.format,
  className,
  ...props
}: SparklineProps) {
  for (const v of values)
    if (!Number.isFinite(v))
      throw new Error(`Sparkline "${label}": ${v} is no value`)
  const floor = min ?? Math.min(0, ...values)
  const top = max ?? Math.max(0, ...values)
  if (min !== undefined && max !== undefined && !(max > min))
    throw new Error(`Sparkline "${label}": max ${max} is not above min ${min}`)
  for (const v of values)
    if (v < floor || v > top)
      throw new Error(
        `Sparkline "${label}": ${v} is outside the scale ${floor} to ${top}`,
      )
  // Only an all-zero series has no range: its line lies on the floor.
  const range = top - floor || 1
  const n = values.length
  /** Where a value falls, 0 at the top and 1 at the floor. */
  const y = (v: number) => (top - v) / range
  /** Where the i-th value falls across; one value is the latest, at the right end. */
  const x = (i: number) => (n === 1 ? 1 : i / (n - 1))
  const points = values
    .map((v, i) => `${x(i).toFixed(4)},${y(v).toFixed(4)}`)
    .join(" ")
  const base = y(Math.min(Math.max(0, floor), top)).toFixed(4)
  const last = values.at(-1)

  return (
    <div
      role="img"
      aria-label={described(label, values, format)}
      data-slot="sparkline"
      className={cn("relative h-8 w-full", className)}
      {...props}
    >
      {n > 1 && (
        <svg
          aria-hidden
          viewBox="0 0 1 1"
          preserveAspectRatio="none"
          className="absolute inset-0 size-full overflow-visible"
        >
          {area && (
            <polygon
              data-slot="sparkline-area"
              points={`0,${base} ${points} 1,${base}`}
              className="fill-current/12"
            />
          )}
          <polyline
            data-slot="sparkline-line"
            points={points}
            fill="none"
            stroke="currentColor"
            strokeWidth={1.5}
            strokeLinejoin="round"
            strokeLinecap="round"
            vectorEffect="non-scaling-stroke"
          />
        </svg>
      )}
      {dot && last !== undefined && (
        <span
          aria-hidden
          data-slot="sparkline-dot"
          className="absolute top-(--ag-sparkline-y) left-(--ag-sparkline-x) size-1.5 -translate-1/2 rounded-full bg-current"
          style={
            {
              "--ag-sparkline-x": `${x(n - 1) * 100}%`,
              "--ag-sparkline-y": `${y(last) * 100}%`,
            } as React.CSSProperties
          }
        />
      )}
    </div>
  )
}